深度长文：一款强大的国产AI Coding工作流CodeFlow，如何解决让 AI 进入有边界、有规范、有门禁、有沉淀的交付流程！

图注：工作流是流程骨架，角色、技能、工具、知识库是支撑骨架的零件。

一句话认识工作流：CodeFlow 工作流把"谁做什么、用什么做、参考什么、谁把关、失败了怎么退"变成一张可执行的流程图，让 AI 按节点协作，让交付可验证、可沉淀。

很多人第一次接触 CodeFlow 时，会直接打开画布拖节点。但拖出来的流程常常跑不稳：节点输出忽长忽短、下游读不到字段、评审不过就全流程重跑。

问题不在画布操作，而在于工作流的"零件"没先想清楚。

本指南面向第一次接触 CodeFlow 的使用者，按"先理解机制、再维护零件、最后搭建流程"的顺序，讲透三件事：工作流如何运行、角色/技能/工具/知识库如何定义、节点如何流转与把关。

快速路径：如果团队已有可复用的角色、技能、知识库，直接读第 2、7、8 章即可上手搭建；从零开始的新团队请按全文顺序——第 4-6 章定义的零件是第 7 章搭建的前提，跳过的后果是节点绑定时没有可用的角色。

一、工作流是什么

工作流是"流程驱动 + 多智能体协作"的执行载体，它把真实业务流程变成 AI 可以按步骤执行的编排图。

CodeFlow 工作流的核心价值，不是让 AI 在对话框里回答得更聪明，而是让 AI 进入有边界、有规范、有门禁、有沉淀的交付流程：

• 流程驱动：谁做什么、输入是什么、输出是什么、谁把关、失败了怎么退，全部显式化。
• 多智能体协作：每个节点由一个 AI 角色执行，关键节点由人工确认。
• 规格控制：角色按定义好的规则、知识、技能产出，输出稳定可预期。
• 经验沉淀：经审核确认后的知识和交付物可持续沉淀，供后续流程复用。

一个关键认知：工作流只是"流程骨架"，它决定节点怎么走；但每个节点执行得好不好，取决于绑定的角色定义得好不好，以及角色绑定的技能、工具、知识库是否适配。

• 角色定义差 → 节点输出质量差，再好的流程也跑不出好结果。
• 技能工具不适配 → 角色有"手"但使不上劲，执行反复失败。
• 知识库缺失 → 角色不了解项目上下文，产出脱离实际。

所以本指南先讲机制，再重点讲零件，最后讲搭建。

图注：工作流运行时，节点按编排顺序依次执行，每个节点由绑定的角色完成，产物向下游传递。

1.1 CodeFlow 自研核心工作流：把研发方法固化为可执行骨架

CodeFlow 将工作流定义、运行时推进、Agent 协作、产物契约、质量门禁、受控返工和运行证据整合为一套自研编排内核。模型负责完成节点任务，CodeFlow 负责定义任务如何推进、何时暂停、如何交接、如何验证以及失败后回到哪里。

当前默认资产中，已经提供了面向不同研发节奏的核心工作流：

这几条工作流共享同一套编排能力，但解决的问题不同：研发工作流负责把需求推进到可验收交付，知识库工作流负责让企业上下文持续可用。两者结合后，交付产物、验证结论和稳定经验可以进入后续流程的知识与资产范围，形成“执行—验证—沉淀—复用”的持续改进路径。

自研编排内核的四个关键能力：

• 流程状态推进：用节点、连线、条件分支、并行分叉与汇合管理任务状态；当前条件出口由人工选择，关键决策保持在可解释的控制点内。
• 多 Agent 协作：每个节点绑定明确角色，角色拥有自己的输入、输出、知识库、技能和工具；上游通过 Artifact、文件路径和结构化字段向下游交接。
• 质量门禁与精确返工：节点可以自动流转或等待人工确认；审核不通过时按返工白名单回到责任节点，避免小问题触发全流程重跑。
• 运行证据与版本边界：记录节点状态、审核动作、交付物和执行事件，并以运行时使用的工作流版本解释历史实例，便于复盘和持续优化。

本文后面搭建的“需求变更处理”流程，是把这套核心能力拆成一个适合学习的自定义示例：先用最小流程跑通节点、产物、分支和人工门禁，再根据团队实际方法扩展为完整研发流程。

二、工作流的运行机制

2.1 核心元素

节点（Node）——流程的最小执行单元：

• start / end：流程起止标记。
• role（角色节点）：绑定一个角色执行，是流程的"工作单元"。
• condition（条件节点）：分支决策，当前仅支持人工选择出口；运行态暂不支持按条件表达式自动判断。
• parallel-fork / parallel-join（分叉/汇合）：并行执行与汇合。

边（Edge）——节点之间的连线，定义执行顺序以及分支、并行关系。

节点配置——每个节点除了绑定角色，还有几类关键配置：

• approvalMode（审核方式）：manual（人工确认后流转）/ auto（自动流转）。
• reworkPolicy（返工白名单）：本节点被驳回时可回退到的上游节点，取值为上游节点列表（如"仅技术设计"）。
• failPolicy（失败策略）：节点执行失败后流程如何处理。常见取值：wait-feedback（失败后等待人工反馈，人工可修正输入后重试）、stop（失败即中止流程，用于失败不可继续的强一致链路）。

配置选取的直觉：approvalMode 与 failPolicy 是两个独立维度，分别判断——manual 用于需要人工把关的环节（是否确认后流转），failPolicy 按失败成本选（失败可修正用 wait-feedback，失败不可继续用 stop）。

图注：画布左侧是节点面板（❶），提供角色、条件、分叉、汇合、Start、End 六种节点；画布上的角色节点（❷）是流程的工作单元，条件节点（❸）负责分叉，分叉节点（❹）展开并行。

2.2 节点之间如何流转和传递信息

一个角色节点执行完成后，它的产物会成为下游节点的输入。 下游获取的信息取决于上游交付方式，但两种方式都会同时携带结构化字段：

术语：resultKey 是角色输出契约里给产物起的稳定标识名（如 analysis-report），流程靠它引用节点产物；approval 这类输出字段的值也有约定格式（如 pass / fail），下游按字段名 + 约定格式消费。

为什么强调"结构化字段"？ 如果下游需要从上游文档里"自己找"关键值，格式一变就容易出错。上游按输出契约给出稳定结构，下游按契约消费，流程才稳定。

图注：上游"写文件"时下游拿到文件路径，"直接输出"时下游拿到文本内容；两种方式都会同时携带结构化字段。

2.3 条件分支

条件节点用于流程分叉，当前只支持人工选择出口。 节点执行后由人工根据上下文选择下一步走向；运行态暂不支持按条件表达式自动判断，也不要把它理解为 AI 自主决策。

2.4 驳回与审核

质量门禁节点（manual）的产出，必须经人工确认才流转。 人工可以"通过"，也可以"驳回"：

• 审核：人工查看 AI 产出，点击"通过"或"驳回"。
• 驳回与返工：节点被驳回后，按返工白名单（reworkPolicy）回退到指定上游重做，而不是全链路重跑。

返工白名单只放真正导致问题的那一层：

• 变更评审不通过 → 退回"技术设计"或"实现"。
• 只有分析阶段的问题 → 才退回"分析"。

为什么白名单要收敛？ 一次小问题触发全流程重跑，失败成本成倍放大。返工范围最小化，失败成本才可控。

三、搭建工作流之前：先维护好四个"零件"

工作流节点绑定角色，角色依赖技能、工具和知识库。 搭建工作流之前，先把四个零件维护好，否则节点绑定时无角色可选、角色执行时没有知识和能力。

图注：角色、技能、工具、知识库四个零件各自回答一个问题，共同支撑工作流节点的执行。

依赖关系：

工作流（Workflow）
└── 节点（Node）──绑定──> 角色（Agent）
    ├── 绑定 ──> 技能（Skill）
    ├── 绑定 ──> 工具（Tool）
    └── 绑定 ──> 知识库（KB）

资产库按资产类型分为五个标签页：WF（工作流）、Agent（角色）、Skill（技能）、KB（知识库）、Tool（工具）。

图注：资产库按类型分五个标签页（❶）：WF、Agent、Skill、KB、Tool；❷ 是新建流程的入口。

本章之后：第 4-6 章分别详讲四个零件的定义方法，第 7 章再回到工作流搭建。

四、角色（Agent）：工作流的质量核心

4.1 角色是什么

角色定义"这个节点由谁执行、怎么执行"，定义质量直接决定节点输出质量。

同一个工作流，绑定一个定义良好的角色和一个敷衍的角色，输出质量天差地别。角色是工作流中最值得投入的部分。

图注：角色定义决定节点"由谁执行、怎么执行"，是节点输出质量的直接来源。

4.2 创建角色

在资产库 Agent 标签页，点击 "新建 Agent"，打开角色创建表单。表单有 8 个标签页：基本、输入、输出、门禁、知识库、Skills、工具、配置。

图注：在 Agent 标签页（❶）可以看到已创建的角色列表，点击任一角色（❷）进入编辑；"新建 Agent"按钮在左上角。

图注：进入角色编辑后，顶部是八个配置标签页（❶）；本节先看"基本"标签页里的职责边界（❷）和系统提示词（❸）。

4.3 "基本"标签页：定义角色身份

四个核心字段：角色名称、描述、职责边界、系统提示词。

系统提示词是核心，建议至少写清三件事：

• 角色身份：我是谁，在什么流程里承担什么职责。
• 执行顺序：先确认输入 → 再读取知识库/代码/文件 → 最后输出交付物。
• 硬约束：只基于实际读取到的资料下结论；缺少关键输入时必须失败或询问，不得伪造成功；不做职责外的工作。

重要原则：不要把具体任务事实（某个需求编号、某次验收细节、临时路径）写进角色定义。这些来自节点运行时输入。角色定义是"怎么交付"的稳定契约，不是"这一次做什么"的任务书。

4.4 "输入"标签页：定义角色需要什么

输入契约只设真正阻断执行的必填字段。 每个输入字段包含：名称、类型、描述、是否必填、默认值。

常见错误：把"有帮助但非必需"的字段设为必填，导致发起运行时总被要求补不必要的信息。

图注："输入"标签页（❶）先写整体输入说明（❷），再逐条维护字段列表（❸）；点开单个字段可配 key、类型和是否必需（❹）。

4.5 "输出"标签页：定义角色交付什么

输出契约是流程稳定运行的基石——下游节点按"结果名称"和"输出字段"消费上游产物。输出契约一旦被下游引用，应保持兼容；修改结果名称或字段时，应同步调整引用节点。

交付方式的取舍：

图注："输出"标签页（❶）决定交付方式（❷）；结果名称（❸）供下游节点引用，结构化输出字段（❹）是下游消费产物的契约。

4.6 "门禁"标签页：程序化质量校验

门禁定义节点通过的前置条件，与人工审核形成"机器先校验、人工再拍板"的双层把关。当前运行态只支持 regex 和 json-schema 两类门禁。

• regex：把节点最终文本产物交给 JavaScript 正则表达式匹配（多行模式）；匹配成功通过，表达式无效或不匹配则失败。
• json-schema：先要求产物是有效 JSON，再按当前实现检查顶层 type（object 或 array）和 required 必填字段。properties、字段类型、格式、additionalProperties 等完整 JSON Schema 规则当前不会校验。

例如，regex 可填写 ^## 结论，要求产物包含以“## 结论”开头的行；json-schema 可填写 {"type":"object","required":["approval"]}，要求产物是 JSON 对象且包含 approval 字段。配置内容本身无效时，门禁校验失败。

门禁配置为阻断时，校验失败会阻止节点继续流转；不要配置依赖 AI 自动评估的门禁，运行态尚未接入 AI 评估器。

图注：门禁标签页（❶）当前支持两类校验——regex 匹配文本产物（❷），json-schema 校验顶层 type 与 required 字段（❸）；右侧开关控制校验失败是否阻断流转。

4.7 "知识库 / Skills / 工具"标签页：角色的能力与知识

这三个标签页决定角色"参考什么、用什么做"，见第 5、6 章。

图注："知识库"标签页（❶）选的是角色默认知识库（❷），运行时与流程级、节点级知识库合并；本例只勾选了执行必需的一个（❸）。

图注："Skills"标签页（❶）绑定角色默认技能；绑定的 Skill 必须匹配当前执行引擎（❷），本例勾选了"变更影响分析"（❸）。

图注："工具"标签页（❶）按需勾选外部 MCP 工具集（❷）；builtin 平台工具（❸）自动注入，无需绑定即可用。

4.8 "配置"标签页：执行引擎与运行参数

配置标签页决定角色用什么引擎、什么模型执行，以及权限和上下文边界。

最容易踩的坑：角色的执行引擎与技能声明的适用引擎不一致，导致技能静默不生效。定义角色和技能时优先确认引擎对齐。

五、技能（Skill）与工具（Tool）：角色的能力

5.1 技能是什么

技能是跨角色复用的稳定能力——一组执行方法、指令或脚本，多个角色都能调用。例如"Git 分支操作""代码调用链检索""需求知识库检索"。

什么情况下需要创建技能——判断标准：

• ✅ 多个角色稳定复用该能力（如 Git 操作在开发、评审、交付多个节点都要用）。
• ✅ 需要独立文件/脚本/触发口径（如一个可执行脚本、一套固定检索规则）。
• ❌ 只被一个角色使用的能力 → 直接写进该角色的系统提示词，不用抽成技能。
• ❌ 能力不稳定、一次性的任务 → 不抽技能。

反模式：为了"看起来专业"把所有能力都抽成技能，导致角色定义被掏空、技能列表冗余。技能抽取得越克制，维护成本越低。

5.2 创建技能

在资产库 Skill 标签页，点击 "新建 Skill"：

图注：Skill 标签页（❶）的技能列表（❷）；每个技能要分别配"适用引擎"（❸，能在哪跑）和"安装目标"（❹，装到哪）。

图注：新建 Skill 表单——名称（❶）、标签（❷）、适用引擎（❸，必须与角色执行引擎一致）、执行指令（❹，写稳定步骤与失败口径）。

5.3 工具是什么

工具分两类，别混淆：

与技能的区别：

注意：普通读文件、跑命令、Git 检查不需要伪装成工具。运行时平台工具（runtime.*）自动注入，无需也不应自行创建。

图注：Tool 标签页只维护外部平台/MCP 工具集；普通读文件、跑命令不需要在这里创建。

用三个问题判断"该建技能还是工具"：

1. 这个能力需要外部平台 API 或 MCP 服务吗？ 是 → 工具（Tool）。
2. 多个角色都会稳定复用吗？ 是 → 技能（Skill）。如 Git 操作、代码检索、知识检索。
3. 只被一个角色使用吗？ 是 → 都不建，直接写进该角色的系统提示词。

简化记忆：外部 API → 工具；多角色复用 → 技能；单角色专用 → 写进角色。（runtime.* 平台工具自动注入，不用管）

5.4 技能与角色的绑定关系

角色的能力 = 系统提示词里的执行纪律 + 绑定的技能 + 绑定的工具。

角色通过 Skills 标签页绑定技能。绑定后，技能以稳定规则的形式注入角色的执行提示词。

定义顺序建议：先定义角色（职责、输入输出），再为角色补齐它需要的技能和工具——技能从"多个角色都需要的共性能力"中提炼。

六、知识库（KB）：角色的知识来源

6.1 知识库是什么

知识库是角色执行时参考的信息来源：可以是直接附带的正文，也可以是执行时读取的文件/目录范围（如源码目录、规范文档目录）。

6.2 创建知识库

在资产库 KB 标签页，点击 "新建知识库"：

图注：KB 标签页展示已创建的知识库，每条显示资产范围与来源条数。

图注：知识库名称（❶）是集合名，资产范围（❷）决定可见范围；来源可选五类（❸），逐条维护在来源清单里（❹）。

注意区分两个概念：资产范围（全局/共享/私有）是知识库自身的可见范围，在创建时定义一次；绑定层级（角色级/流程级/节点级）是"这个知识库挂到流程的哪一层"，在角色、流程、节点的配置里分别选择。两者是不同维度，不要混为一谈。

6.3 三层绑定与维护原则

知识库按三层绑定，只挂执行必需的上下文：

• 角色级（角色的"知识库"标签页）：该角色执行必需的稳定上下文。
• 流程级（流程设置里的"默认知识库"）：整个流程稳定需要的上下文。
• 节点级（节点绑定里的"额外知识库"）：单个节点的例外上下文。

怎么判断该放哪一层——按"需求范围"决策：

• 只要这个角色在执行，无论哪个流程都需要 → 角色级（如"需求分析员"总需要历史需求库）。
• 整个流程的所有节点都需要 → 流程级（如"需求变更处理"流程全流程都需要规范文档）。
• 只有某个节点的例外场景需要 → 节点级（如只有"设计评审"节点需要架构文档）。

反模式：把整个知识库挂到所有角色上。上下文膨胀会让模型注意力分散、检索噪音多、执行质量下降。能不放就不放，先跑通再加上下文。

6.4 知识库的持续维护

知识库不是建一次就完了，需要持续维护：

• 初始化：首次搭建时，把外部文档、历史资料、源码基线同步进来。
• 持续更新：每次流程交付后，把新的结论、组件、规范增量回写；定期清理过时内容。
• 质量底线：知识沉淀采用"候选 + 审核"模式——AI 生成候选知识，人工审核后写回，避免 AI 直接写库污染知识来源。

图注：技能提供能力、工具提供外部接口、知识库提供上下文，三者职责不重叠。

图注：一个最小可运行工作流的骨架：起止、角色节点、条件分支与人工门禁。

七、搭建一个完整的工作流

以"需求变更处理"为例，完整走一遍搭建过程。

图注：本章要搭出的完整流程——START（❶）→ 需求接收（❷）→ 条件判断（❸）→ 前端/后端并行实现（❹❺）→ 汇合（❻）→ 变更评审（❼）→ END（❽）。

7.1 新建工作流

在资产库 WF 标签页，点击 "新建流程"：

图注：在 WF 标签页（❶）点击新建按钮（❷）创建流程。

填写流程模板名称（如"需求变更处理"）和描述（说明适用场景）：

图注：画布顶部依次是流程模板名称（❶）、描述（❷）和"流程设置"入口（❸）。

进入画布编辑界面，画布默认有 START 和 END 节点。

7.2 配置流程级默认知识库

当前“流程设置”维护流程家族与流程级默认知识库，不提供流程发起输入字段。 发起时的需求标题、背景和验收等运行上下文在“需求编排”中创建；角色节点所需的稳定字段则在 Agent 的“输入”标签页定义。

图注：流程设置弹窗里维护流程家族（❶）与流程级默认知识库（❷），勾选的知识库对全流程节点生效。

7.3 添加节点与连线

画布左侧是节点面板，提供六种节点：角色、条件、分叉、汇合、Start、End。

本案例搭一个最小闭环（可直接照抄）：

START → 需求接收 → 条件（是否进入实现？）
                         │              │
                      需要实现        暂不处理
                         │              │
                       分叉            END（流程终止）
           │     │
        前端实现  后端实现
           │     │
            汇合
              │
          变更评审 → END

1. 点击 "角色" 添加 4 个角色节点：需求接收、前端实现、后端实现、变更评审。
2. 点击 "条件" 添加分支节点（"是否进入实现？"），点击 "分叉" 和 "汇合" 实现并行。
3. 用连线连接节点，并把条件节点的出口连到两条路径：需要实现 → 分叉；暂不处理 → 结束。

图注：从节点面板（❶）拖出节点后，角色节点（❷）、条件节点（❸）和分叉节点（❹）在画布上各司其职。

图注：连线完成后，用"自动布局"（❶）一键理顺节点位置；选中节点后点"编辑绑定"（❷）进入配置。

7.4 配置角色节点

选中一个角色节点，点击"编辑绑定"，打开节点绑定配置窗口：

图注：节点绑定窗口的前半部分——绑定角色（❶）、失败策略（❷）、节点审核方式（❸）。

选择角色：点击"绑定角色"下拉，从角色列表中选择（内置角色或自定义 Agent）。

图注：同一窗口向下滚动的后半部分——节点启动方式（❶）、工作项模式（❷）、返工白名单（❸）。

关键配置的决策思路（以本案例为例）：

• 审核方式：判断标准是"错误后果是否不可逆"。本案例中"变更评审"是质量门禁，选人工；"需求接收""前端实现""后端实现"选自动——自动审核表示节点完成后无需人工确认即可继续流转，是否抽查由流程管理决定。
• 失败策略：本案例选择 wait-feedback，含义见 2.1 节。
• 返工白名单：只选"前端实现/后端实现"而不选"可行性分析"，因为评审不通过，问题大概率出在实现环节。白名单只放真正导致问题的那一层，避免小问题触发全流程重跑。

7.5 配置条件节点

选中条件节点打开"编辑绑定"，当前只需确认人工选择出口：

图注：条件节点编辑窗口中，类型保持为 condition（❶），条件说明当前仅支持启发式（❷）；界面已写明"运行态不支持通用条件表达式"（❸），因此"分支决策方式"设为"人工选择"（❹），运行时由人工决定走"需要实现"或"暂不处理"出口。

• 人工选择：节点执行后由人工选择下一步走向。

7.6 保存流程

配置完成后点击 "保存"，流程保存为可用状态。

图注：画布右上角的"保存"按钮（❶），点击后流程存为可用状态。

八、运行、验证与持续优化

8.1 运行工作流

在"需求编排"中发起运行，填写输入参数，流程开始执行。 节点按配置的顺序、分支或并行关系执行，manual 节点等待人工确认。

图注：顶部条显示当前待办节点摘要（❶）；已完成节点标绿（❷），"变更评审（人工确认）"停在待审核（❸），END 尚未执行（❹）。画布采用与工作流定义一致的自动水平布局。

8.2 人工确认与驳回

节点执行完成后，manual 节点需要人工查看产出并点击"通过"或"驳回"。 驳回后按返工白名单回到指定上游重做。

图注：人工确认界面左侧是交付物（❶）与结构化输出字段（❷），右下角可选择"驳回"（❸）按返工白名单回退，或"通过并继续"（❹）。

8.3 持续优化

工作流上线后用运行数据持续优化，观察节点耗时、重试率、返工率、人工反馈。问题归因时先看该节点的执行快照——模型实际看到什么，比"我以为它看到什么"更重要。

排查顺序建议（从最可能到最不可能）：

1. 任务输入问题——先确认本次运行时输入字段是否齐全（目标、编号、范围），输入缺失时下游无法正常执行。
2. 产物契约问题——再看上游产物是否按约定产出（文件路径、结构化字段），下游拿不到字段通常是这里断的。
3. 角色定义问题——再看角色本身（职责模糊、提示词没写清执行纪律、输出契约错误）。
4. 知识上下文问题——接着看角色是否拿到应有的知识库（缺失或过宽）。
5. 技能绑定问题 / 工具问题——最后看能力层：技能引擎不匹配、工具绑定异常。
6. 流程编排问题 / 启动配置问题 / 执行质量问题——以上都排除了，再看流程层。

问题归因按九类分类，不同根因改不同地方：

• 角色定义问题：职责模糊、执行步骤缺失、输出契约错误、必填输入错误。
• 技能绑定问题：缺失技能、目标引擎不支持。
• 流程编排问题：顺序错误、缺少节点、并行依赖不满足、审批点错误、返工目标错误。
• 启动配置问题：发起运行时跳过了必要节点，导致下游缺少上游产物。
• 执行质量问题：节点耗时、重试率、失败率异常。
• 知识上下文问题：知识库缺失或过宽、路径不可读。
• 产物契约问题：resultKey 错、文件路径错、字段未结构化输出。
• 运行工具问题：工具绑定异常、工具调用失败。
• 任务输入问题：目标、验收、编号、范围或关键约束缺失。

复盘还要注意版本边界：正式变更走版本管理，旧实例的复盘用当时的实例快照，不要用最新定义解释历史执行——定义变了，历史行为就无法用当前版本解释了。

图注：上线后用运行数据反哺角色、技能和知识库，形成持续优化闭环。

结语

先跑通一个能用的流程，再回头打磨角色、技能和知识库——每次打磨都能在节点输出上看到回报。

更多产品与实践信息可访问 CodeFlow 官网 codeflow.hanshangai.com。