母工作流执行架构与阶段二次开发¶

本篇用于指导开发者修改当前 Workflow Builder 母工作流的阶段结构和端到端调用链。Workflow Builder 使用“需求提取、中心设计、分组件生成、集成验收”的结构生成业务工作流；中心设计位于 wfgen/，最终公开产物位于 workflow/。理解这些运行结果是为了安全调整母配置、阶段 Checker 和生成调用顺序，不是让读者手工执行某个子阶段。

二次开发目标¶

典型任务包括增加或合并母阶段、调整阶段输入输出、改变中心 workflow spec、接入新生成器、改变评估阻塞策略、优化上下文读取或修复增量终止条件。每项修改都要从母配置进入，沿 UCTool 到 core，再到生成文件和 Checker，形成闭合影响分析。

母工作流修改入口¶

• 主构建阶段：根 config.yaml 与 Guide_Doc/stages/。
• 增量阶段：根 inc.yaml、增量 GuideDoc 和 tools/workflow_evaluation_control/。
• 评估阶段：eval_tools.yaml、eval_checkers.yaml、eval_flow.yaml、eval_env.yaml、eval_run.yaml。
• 构建执行：tools/workflow_builder/core.py 及其 uc_tools.py 包装。
• 启动编排：根 Makefile。

修改阶段时先画出旧阶段的 reference、output、工具和 Checker，再设计新结构。直接在 YAML 中插入一个 stage 而不更新计划标记、GuideDoc、变量、Checker和回归，会让流程形式存在但无法稳定执行。

构建数据流¶

1
2
3
4
5
6
7

input/guide.md + input/test_input/
  -> requirements_manifest.yaml
  -> workflow_implementation_plan.md
  -> input_example_manifest.yaml
  -> workflow_build.yaml
  -> workflow/ 工具、Checker、GuideDoc、配置、文档和环境设施
  -> make check / make check_example

requirements_manifest.yaml 是规范化需求清单；workflow_build.yaml 是中心构建设计，必须提前声明阶段、文件、工具、Checker、GuideDoc 和运行契约；实现计划承担跨阶段沟通，后续阶段只能在自己的标记区追加问题与处理，不能覆盖先前决策。

阶段执行¶

根 config.yaml 定义母工作流阶段。每个阶段包含任务描述、参考文件、输出文件、工具和 Checker。Agent 先通过 RoleInfo 获取当前任务，再读取本阶段必要参考，调用工具生成或更新产物，最后由 Checker 验证。Checker 失败会令同一阶段重试，因此任务描述必须给出准确修复方向，避免 Agent 反复猜格式。

一个阶段的 reference 不能指向未来阶段才生成的文件。目录也不能作为 reference 或 output 的替代，因为 UCAgent 的引用追踪、权限和存在性判断以具体文件为单位。

评估数据流¶

静态评估分为 tools、checkers、flow、env 四个责任域。每个评估 Agent 读取紧凑执行指南、当前报告索引、用户资源和目标源码，然后通过结构化存储追加 checks/findings。聚合器不重新判断源码，只汇总各分项报告和审批状态。

eval_run 是可选的昂贵运行评估，与静态评估分开。静态审查不得偷偷启动完整子工作流，运行评估也不应一次同时跑 default 和 inc 两种模式。

增量数据流¶

1
2
3
4
5
6
7
8
9

approvals + user suggestions
  -> start-inc-run 分配 run id
  -> 读取目标摘要和相关源码
  -> tmp/inc_runs/<id>/ 候选
  -> 确定性检查
  -> 保存旧版本并原子部署
  -> make check / 相关测试
  -> incremental_report + applied_changes
  -> 重新评估

增量流程必须维护“批准条目到修改文件、检查证据”的映射。部署后不能停在 pending approval 状态；正式文件已改变时，必须继续修复回归或明确失败。版本管理解决的是可恢复性，不是再次审批已经部署的文件。

控制台¶

控制台由 tools/workflow_evaluation_control/review_server.py 提供本地 HTTP 服务。页面读取结构化 JSON、构建设计 YAML/Markdown、工作流文件树和 UCAgent 状态。写入操作必须经过服务端校验，浏览器不能直接写原始文件。

扩展原则¶

增加阶段前先判断是否能并入现有核心阶段。过多 spec、清单和认知核验会消耗上下文但不增加业务质量。优先保证工具、Checker、GuideDoc、config 和用户文档正确；只有新的结构能消除真实歧义或支持确定性验证时才引入。

构建设计加载与基础校验¶

源码位置：tools/workflow_builder/core.py，符号 load_yaml_config()、get_nested() 和 validate_build_config()。

1
2
3
4
5
6
7
8

def validate_build_config(data: dict[str, Any]) -> None:
    for key, expected_type in REQUIRED_FIELDS.items():
        value = get_nested(data, key)
        if not isinstance(value, expected_type):
            raise WorkflowBuildError("BUILD-CFG-003", ...)
    if "tmp" not in data["directories"]["public"]:
        raise WorkflowBuildError("BUILD-CFG-007", ...)
    validate_workflow_spec_contract(data)

加载函数只接受 YAML mapping，避免后续代码在 list 或标量上产生难懂的属性错误。get_nested() 使用点路径读取必需字段，使错误能直接指出 workflow.name 或 runtime_contract。validate_build_config() 先验证外层形状，再检查语义约束，最后进入中心 workflow spec 验证。开发者新增字段时，应判断它是 Builder 运行不可缺少的必需字段，还是可选业务扩展；把所有字段都塞进 REQUIRED_FIELDS 会破坏旧设计兼容。

根级 tmp 约束体现了临时文件治理：所有组件共享一个受控临时根，禁止重新引入 .workflow/temp。这类跨组件不变量必须在最早的中心校验中阻断，而不是依赖后期文档提醒。

中心 workflow spec 校验¶

validate_workflow_spec_contract() 要求 Checker 和阶段在构建前完整规划。它先收集 shape errors 并一次报告多个结构缺项，再检查名称、源码入口、fixture、测试和阶段引用。这种“一次报告全部同类结构问题”的策略减少 Agent 每次只修一个字段造成的重试。

核心逻辑可以概括为：建立 Checker 名称、文件、类和 fixture 的唯一集合；验证每个 stage 引用的 Checker 都能在中心定义中找到；验证 reference/output 是具体文件且不存在未来引用；验证阶段注册参数与定义可追踪。若要增加 Checker 字段，不仅要在这里验证，还要同步 checker generator、schema、最小示例和控制台结构视图。

这一阶段不能验证所有业务语义。例如“章节一致性 Checker 是否真的覆盖用户需求”需要 fixture 和评估流程判断。中心校验负责证明设计闭合和可物化，不应膨胀为运行整个业务。

物化主调用链代码分析¶

源码位置：tools/workflow_builder/core.py，符号 build_workflow()。

1
2
3
4
5
6
7
8
9

data = load_yaml_config(config_path)
validate_build_config(data)
root = check_path_safety(data, base_dir)
create_directories(root, data, report)
for group_name in ("public", "internal"):
    for item in data["files"][group_name]:
        content = render_file_by_template(...)
        write_file(root, rel_path, content, overwrite, report)
generate_planned_business_checkers(root, data, overwrite, report)

顺序很重要。路径安全检查发生在任何写入之前，避免部分产物已经创建后才发现 root 越界。目录先于文件创建；公开与内部文件都通过同一模板分派和 write_file()，因此 overwrite、报告记录和路径边界一致。业务 Checker 在基础骨架和 config 存在后生成，因为 checker generator 需要写源码、fixture，并可能读取注册结构。

模板分派函数 render_file_by_template() 是固定交付物的集中入口。新增模板时要明确未知模板的行为。目前未知模板会生成空文件并追加 warning；对于强制业务产物，仅靠 warning 通常不够，后续 acceptance 必须阻止空壳通过。不要在多个分支用同一路径生成不同语义内容，否则路径规则会掩盖 template 错误。

配置生成与阶段注入¶

源码位置：tools/workflow_config_generator/core.py，符号 validate_config_spec()、_inject_planned_stage_contracts() 和 generate_config()。

配置生成器先验证 placeholder、作用域泄漏、父工作流路径泄漏、正文详细度以及 reference/output 文件契约。_planned_stages() 把中心 workflow spec 转为按阶段名索引，_inject_planned_stage_contracts() 再把 Checker、参考和输出约束注入 config spec。这样 config 不应成为第二套人工维护的阶段事实来源。

生成后 _validate_generated_config() 再审查最终 YAML，而不是假设 spec 正确就等于渲染结果正确。开发者修改模板覆盖或 placeholder 语法时，必须同时考虑生成前静态分析和生成后结果验证。常见错误包括未定义变量、双花括号残留、循环替换、父工作区绝对路径、目录被写入 file list，以及 reference 在当前阶段尚不存在。

评估状态机代码分析¶

源码位置：tools/workflow_evaluation_control/core.py，符号 evaluation_stage_decision()。

1
2
3
4
5
6
7
8

if is_report:
    decision = "run"
elif stage_name in state.get("skipped_stages", []):
    decision = "skip"
elif state.get("status") in {"blocked", "terminated", "completed"}:
    decision = "skip"
else:
    decision = "run"

报告阶段始终运行，是为了即使前面阻塞，也能把失败原因和建议持久化，而不是无报告退出。显式 skipped stage 优先于普通 running；blocked 和 terminated 阻止昂贵后续动作；completed 防止重复执行。evaluation_control_action() 每次状态变化追加 event，使“为什么跳过”可审计。

修改状态机时必须防止两个极端：阻塞后仍运行所有昂贵阶段，以及失败后连报告阶段也跳过。评估状态机与增量部署状态机不是一套状态；不能把评估的 pending/blocked 语义直接套到已经替换正式文件的增量流程。

增量部署调用链¶

源码位置：tools/workflow_evaluation_control/incremental.py，符号 deploy_incremental_changes()。

部署器依次验证工作流根、change id、当前 run/batch/attempt、审批新鲜度、映射字段、候选路径、目标路径和审批覆盖。随后进行 projected semantic audit，保存每个目标旧版本，使用同目录临时文件原子替换，并写 applied_changes.json。中途失败时按逆序 rollback。

1
2
3
4

backup = _archive_target(workspace, history_root, target_root, target)
_atomic_copy(source, target)
...
_rollback_targets(workspace, target_root, archived)

_atomic_copy() 使用 os.replace()，因此不要求旧文件本身具有普通写权限，只要求目标目录允许创建和替换。这正是只读 config/Makefile 仍能受控部署的原因。备份记录包括原文件是否存在、路径、哈希和时间，既支持恢复已有文件，也支持回滚本轮新建文件。

文件生产者与消费者矩阵¶

这个矩阵用于判断“应该改哪个文件”。例如工具源码和 workflow build spec 不一致时，不能只编辑注册后的 config；应先决定中心设计是否改变，再重新物化或以增量报告完整记录偏差。

扩展阶段的决策方法¶

新增阶段需要满足至少一个条件：它产生独立、可验证、被后续消费的产物；它拥有不同写入权限；或它隔离了高成本/高风险动作。单纯因为任务描述很长，不足以拆阶段。拆分后还要计算新增 reference、Checker、GuideDoc 和上下文读取成本。

反过来，工具生成和工具测试可以在同一责任阶段批量完成：先独立生成多个工具，再一次更新注册和运行综合检查。把每个工具拆成“生成、读回、检查、再读回”四个阶段会放大模型往返，却没有增加确定性证据。

失败路径与部分写入分析¶

构建主链的异常可能发生在中心配置加载、路径检查、目录创建、模板渲染、文件写入、Checker物化或示例复制。开发者应确认每一层错误是否带责任域错误码，以及失败时 report 是否准确反映已经发生的写入。Builder 当前不是一个跨全部文件的数据库事务，因此中途失败可能保留已创建文件；重试依赖 overwrite 和各生成器幂等性恢复。

这意味着新增生成步骤不能假设工作流根总为空。它应验证已有目标、采用安全覆盖策略，并在失败前不要破坏用户漂移文件。对于必须整体一致的共享文件，例如 config 注册，应先在内存生成和校验完整候选，再原子写入，而不是循环追加后在最后一项失败。

UCTool 包装层应捕获已知 WorkflowBuildError 并返回 code/message/report；未知异常保留 traceback 给开发日志，同时向 Agent返回不含敏感内容的失败摘要。不要捕获所有异常后返回 ok=True 加 warning，这会让阶段 Checker面对半成品并产生误导重试。

运行契约与示例目标¶

runtime_contract 连接构建设计和最终 Makefile。它定义 input root、output root、example target 和 required input。Builder据此复制 test_input 到业务工作流示例、生成 input/output 文档，并让 make check_example 检查同一契约。若某个生成器自行假设 data/ 或固定目标名，就会与 config 和文档分叉。

新增输入类型时，应先更新 runtime contract 和 input example manifest，再让 Builder复制实际样例，最后由 Makefile和 Checker读取同一列表。示例目标必须代表真实最小业务，不能只放空 JSON 为结构检查提供假通过。

可观察性与阶段耗时¶

流程层应把关键产物写入 report 或计划，而不是只在 TUI打印。长阶段排障需要知道当前处理的 spec、最近写入、检查返回码和剩余队列。批量生成时先记录队列总数和已完成 id；上下文压缩后从结构化进度继续，不重新全文认识整个工作流。

性能优化不能删除最终综合检查。正确方式是减少重复全量检查、限制无关读取和并行无共享写入的任务。任何优化都用不同业务对比阶段失败次数、工具调用数、上下文压缩和最终质量。

主工作流 24 个阶段逐步说明¶

下面的阶段顺序来自根 config.yaml，是当前母工作流的公开执行架构。WorkflowPlanAppender 几乎贯穿所有阶段，用于只追加当前阶段的设计记录；表中只额外列出本阶段具有代表性的工具。二次开发者修改阶段时必须同时核对 config、对应 Guide_Doc/stages/、实现计划 block、reference/output 和 Checker 参数。

第一组：需求与中心设计¶

阶段 00 的核心不是“写三份文件”，而是建立后续阶段不再随意重设计的事实来源。若需要增加知识库、许可证或新配置类型，先在这里定义交付契约。阶段 01 则把需求转换成生成器能消费的字段；新增顶层字段前应先判断现有 workflow_spec、runtime_contract 或 acceptance 是否可以表达，避免 spec 膨胀。

第二组：初始骨架与 Tool 冒烟闭环¶

这一组采用“先验证生成器，再生成一个业务 Tool，再从真实边界调用”的递进设计。二次开发时不要把 03、05、08 合并成一个无法定位失败的大阶段；也不要为每个 Tool复制整套 smoke 阶段。全量工具在后面的批量阶段处理。

第三组：完整配置与全部业务 Tool¶

10–11 把“设计配置”和“生成并自审配置”分开，是为了在任何正式 YAML 写入前发现中心设计矛盾。12–14 同理先完成 Tool spec 队列，再批量物化和综合测试。若新业务只有一个 Tool，这些阶段仍应保留语义，但任务可以快速确认没有额外项，而不是生成空壳文件凑数量。

第四组：文档、依赖和可复用模板¶

第五组：发布完整性与最终需求覆盖¶

第六组：清理、迁移与外部验证¶

如何二次开发一个阶段¶

1. 在根 config.yaml 中确认阶段唯一职责、位置和 alias。
2. 修改或新增对应 Guide_Doc/stages/<index>_<name>.md，给出工具、Checker和最小格式。
3. 若阶段产生新的中心文件，更新 wfgen schema、设计编辑器和实现计划标记。
4. 在 reference_files 中只列阶段开始前存在的文件，在 output_files 中只列本阶段实际写入文件。
5. 注册适合的 Checker；新 Checker走 03 文档描述的生成和回归路径。
6. 更新 living plan 规则，保证本阶段只追加自己的 block。
7. 增加配置/GuideDoc/阶段回归，并在一个全新业务工作区验证。

新增阶段后不要只观察它能否通过，还要比较前后阶段上下文是否重复、是否引入新的全量文档读取、是否可以合并到已有责任域。阶段删除则必须清理 Checker alias、GuideDoc、计划标记、reference 和所有恢复历史中的旧阶段假设。

继续阅读¶

阶段通过 UCTool 执行确定性操作，请继续阅读 Tool 简介，查看母工作流完整工具清单、注册上下文和修改联动。