Workflow Builder 母工作流二次开发总述¶

本组文档面向准备对当前 examples/workflow_builder/ 母工作流进行二次开发的用户。目标是帮助开发者修改母流程阶段、生成器、评估控制、增量部署、控制台和交付契约，而不是指导某次子工作流 Agent怎样完成业务任务。文中出现的生成工作流、业务 Tool、业务 Checker 和 GuideDoc 都是母工作流代码的输出对象，用于解释一次母代码修改会影响什么。

二次开发目标¶

开发者阅读本组文档后，应能从一个需求或缺陷定位到母工作流中的真实修改入口，理解模块接口和调用关系，设计向后兼容的数据结构，补充确定性回归，并用独立业务验证生成效果。一次业务生成失败可能来自需求、母阶段描述、GuideDoc、生成器、Checker、UCAgent 运行时或外部服务；只有确认责任域后才修改母代码，不能用修改 UCAgent 核心或手工补子产物掩盖问题。

这里不重复 Usage 中的日常启动步骤，也不把阶段提示词当作开发者教程。开发者关心的是：阶段由哪个 YAML 定义、工具由哪个 UCTool 暴露、核心函数如何写文件、哪些 schema 和回归必须同步，以及如何让下一次任意业务都获得修复。

阅读顺序¶

1. 工作流程简介：理解构建、评估、增量和控制台的数据流。
2. Tool 简介：理解工具注册、调用、返回结构和写入边界。
3. Checker 简介：理解阶段验收、参数注入和证据语义。
4. 指导文档简介：理解 GuideDoc 模板、阶段 FAQ 和最小示例。
5. 评估与增量控制：理解审批、候选、部署和版本历史。
6. 测试与回归：确定修改后必须运行哪些确定性检查。
7. 工作流产物二次开发指南：理解生成子工作流的组件、所有权、扩展顺序与回流母生成器的判断标准。

母工作流修改入口¶

二次开发通常从四类入口开始。流程行为修改 config.yaml、inc.yaml、eval_*.yaml 及其 Guide_Doc/；产物生成能力修改 tools/workflow_builder/ 和四个 generator；评估、审批、部署或 UI 修改 tools/workflow_evaluation_control/；运行和环境入口修改根 Makefile 与 setup。确定入口后再阅读对应源码分析，不要先编辑某个历史 workspace_x/workflow/。

主要源码区域¶

开发边界¶

• 优先修改 examples/workflow_builder/ 内的母工作流，不修改 UCAgent 核心来掩盖生成器问题。
• 业务特定文件名不能写入通用 GuideDoc，除非它只是明确标注的示例。
• 新增工具或 Checker 必须同步更新 spec、注册、测试、配置和生成文档。
• reference_files 与 output_files 只能列文件，不能列目录；引用文件必须在该阶段执行前确实存在。
• 所有临时文件进入工作区 tmp/；评估报告进入 eval/；用户专业知识进入 res/。
• 长文档要使用索引和按需读取策略，不能为了“建立认识”要求 Agent 每轮全文读取全部资料。

修改前的问题陈述¶

建议先写清可观察症状、最小复现命令、失败阶段、Checker 消息、相关产物和预期行为。对于性能问题，还要记录阶段开始时间、实际工具调用、产物时间戳是否变化以及是否发生上下文压缩。这样才能区分真实计算、模型等待和无状态空转。

完成定义¶

开发修改只有同时满足以下条件才算完成：代码实现与文档一致；目标回归通过；未破坏其他生成器；新字段具有兼容策略；生成产物可以由 make check 验收；真实工作区验证时没有由母 Agent 代替子工作流手写产物。

从命令到源码的入口地图¶

开发者首先要明确自己运行的是哪一层入口。根 Makefile 的 run、run_eval_* 和 run_inc 都在业务构建工作区中启动 UCAgent，但加载的配置分别来自 Workflow Builder 根目录的 config.yaml、评估配置和 inc.yaml。Makefile 负责准备工作区、复制公共输入、选择输出根、设置 PYTHONPATH、启动权限守护以及传递 TUI/loop 参数。UCAgent 随后按照配置中的阶段调用本目录注册的 UCTool；这些工具再进入各生成器或评估控制模块。

关键入口可以按下表定位：

如果问题发生在生成产物中，仍要沿这张表向上追溯：产物文件是哪个模板或 spec 生成的，spec 又由哪个母阶段写出，哪个 Checker 本应更早拦截。只在最后生成文件中修一行虽然可能让当前工作区通过，却不能改善下一个业务。

核心数据对象代码分析¶

源码位置：tools/workflow_builder/core.py，符号 WorkflowBuildError 与 BuildReport。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

class WorkflowBuildError(RuntimeError):
    def __init__(self, code: str, message: str):
        super().__init__(f"{code}: {message}")
        self.code = code
        self.message = message

@dataclass
class BuildReport:
    workflow_name: str = ""
    created_dirs: list[str] = field(default_factory=list)
    created_files: list[str] = field(default_factory=list)
    skipped_files: list[str] = field(default_factory=list)
    warnings: list[str] = field(default_factory=list)
    errors: list[str] = field(default_factory=list)

这两个类型体现了生成器的错误和结果边界。WorkflowBuildError 使用稳定错误码把“配置无法解析”“路径越界”“Checker 生成失败”等问题与普通 Python 堆栈区分开。调用者可以把 code 写入 UCTool 的结构化错误，让阶段任务获得可行动原因，而不必解析自然语言。新增验证规则时应选择与责任域一致的错误码前缀，并保持一个错误码只代表一类修复动作。

BuildReport 不是最终业务报告，而是一次物化操作的变更清单。created_files 与 skipped_files 支持判断 overwrite 策略是否生效，warnings 用于记录不阻断但需要开发者处理的问题。新增生成步骤时必须把实际写入追加到 report，否则 UCTool 虽然返回成功，Agent 和回归却无法确认产生了什么。反过来，也不能在文件写入失败前预先登记成功。

环境配置调用分析¶

Workflow Builder 根目录的 setup.py 只生成 .workflow_builder/local.mk。Makefile 在默认变量定义前可选加载它，因此保存值可以成为本机默认值，而命令行 make WS=... 仍具有更高优先级。该配置面向“如何启动母工作流”，包含 UCAgent 源码、虚拟环境、默认工作区、MCP/控制台端口和可选代理。

生成业务工作流中的 workflow/setup.py 来自 tools/workflow_builder/core.py 的 WORKFLOW_ENVIRONMENT_SETUP 模板。它读取业务工作流自己的 config/environment.schema.yaml，保存 .workflow/local/environment.yaml，并更新生成产物 Makefile 与 ucagent_setup.sh 的受控区块。两者名称相同但状态目录、schema 和修改对象完全不同。开发文档、测试和报错必须使用“Workflow Builder 根 setup”或“生成工作流 setup”这样的限定词。

环境配置的修改风险集中在三个方面：第一，Make 的变量优先级是否改变；第二，敏感值是否被写入可提交文件；第三，配置失败时是否留下半个受控区块。任何修改都应测试首次写入、重复执行、dry-run、非法输入、命令行覆盖和原子替换。

源码位置：根 Makefile，本地配置加载入口。

1
2
3
4
5
6

WORKFLOW_BUILDER_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
LOCAL_CONFIG ?= $(WORKFLOW_BUILDER_DIR)/.workflow_builder/local.mk
-include $(LOCAL_CONFIG)

UCAGENT_HOME ?= $(HOME)/FDocB/UCAgent
WS ?= $(WORKFLOW_BUILDER_HOME)/workspace

先计算 Makefile 自身目录，而不是依赖调用者 cwd，因此从业务工作区用 make -f ... 启动仍能找到本地配置。-include 允许首次使用时文件不存在；配置中的普通赋值会覆盖后面的 ?= 默认值，而命令行变量仍由 GNU Make保持最高优先级。修改这段顺序会直接影响跨工作区启动，必须通过无配置、有配置和命令行覆盖三种 dry-run 验证。

数据所有权与写入边界¶

input/ 是用户需求来源，母 Agent只能复制和读取；wfgen/ 是中心设计，构建阶段按职责追加；workflow/ 是公开业务工作流；eval/ 只能通过结构化存储更新；res/ 是用户专业知识；tmp/ 保存临时案例、增量候选和历史版本。写入边界不是文档建议，而是防止评估 Agent修改被评估对象、增量 Agent越过审批范围以及临时文件污染正式交付的安全契约。

开发新工具时，应先确定它属于哪一种所有者。普通评估命令执行器不能写 workflow/；候选 stager 可以从正式文件复制到当前 run 目录，但不能反向部署；只有 deployer 在验证批准来源和候选映射后才能替换正式文件。将这些动作合并为一个“万能文件工具”会使审批、审计和回滚失去意义。

一次缺陷的完整定位示例¶

假设生成的 config.yaml 在第一阶段引用不存在的 {INPUT}。不要只把它改成某个绝对路径。首先在生成工作区读取 wfgen/workflow_build.yaml，确认变量是否在 runtime contract 或模板覆盖中声明；然后检查 workflow_config_generator.core._find_unknown_runtime_placeholders() 和 _inject_planned_stage_contracts() 是否应拦截；再检查母阶段 GuideDoc 是否要求生成后自审；最后为 config generator 增加一个包含未定义占位符的负向 fixture。

正确修复应让未来所有未知占位符在生成阶段失败，并给出字段位置。当前工作区可以通过重新运行相应阶段或增量流程获得新配置。验收不仅是 YAML 可解析，还包括 config generator 回归、delivery contract、实际 make check 和新业务构建。这个过程说明：开发者修复的是产生错误的机制和缺失的防线，而不是历史文件中的一个字符串。

兼容性和变更评审¶

修改公开 spec 字段时，要回答旧工作区能否继续读取。可选新字段应有明确默认值；必选字段应在 schema、最小示例和迁移说明中同时出现。重命名字段必须提供兼容读取或明确的版本门，不能只更新生成器而让控制台、Checker 和回归读取旧名字。

评审时至少检查：输入 schema、生成文件、配置注册、用户文档、开发文档、错误码、回归 fixture 和增量兼容。代码行数很少并不代表影响范围小，例如改变 reference_files 的路径规则会同时影响 config 生成、UCAgent 引用追踪、评估和控制台解析。

扩展点汇总¶

本系统优先通过中心 schema、模板 renderer、UCTool 包装、结构化存储 API 和控制台 editor schema 扩展。新增能力应选择最窄的正确扩展点：业务渲染进入对应生成器，跨组件不变量进入中心校验，人工审批进入评估控制，不能把所有逻辑堆入 tools/workflow_builder/core.py 或任意 shell。