母工作流 GuideDoc 与文档生成二次开发¶

本篇面向维护母工作流 Guide_Doc/ 和 tools/workflow_guidedoc_generator/ 的开发者，说明如何修改阶段指导契约、公共 FAQ、用户文档生成和注册逻辑。GuideDoc 的实际读者是执行阶段的 Agent，但本篇的目的不是教 Agent做任务，而是教开发者如何设计和实现这套指导系统。

二次开发目标¶

典型任务包括新增母阶段 GuideDoc、调整语义章节契约、增加用户文档类型、修复详细度算法、控制参考文档读取量、更新通用 FAQ 或改变 guide_docs 注册。修改后需要证明母 Agent读取到正确指导，同时生成工作流的用户文档没有被错误注入每个阶段。

母工作流修改入口¶

• 根 Guide_Doc/：母流程实际加载的公共和阶段指导。
• 根 config.yaml、评估/增量 YAML：GuideDoc 注册和阶段引用。
• tools/workflow_guidedoc_generator/contract.py：稳定章节语义与兼容标题。
• tools/workflow_guidedoc_generator/core.py：spec 校验、渲染、写入和注册。
• tools/workflow_builder/core.py：固定用户文档模板。
• regression/：GuideDoc、交付文档和详细度回归。

目录和生成方式¶

母工作流公共指导位于根 Guide_Doc/。分阶段文档通常位于 Guide_Doc/stages/，常见问题位于同一公共目录并由各阶段引用。生成业务 GuideDoc 的实现位于 tools/workflow_guidedoc_generator/，注册信息进入业务配置。

一个阶段文档应包含什么¶

• 阶段目标和不在本阶段处理的内容。
• 必须读取的具体参考文件及读取顺序。
• 工具名称、参数来源、输出和失败处理。
• 需要生成或更新的具体文件。
• Checker 名称、参数和每项检查的含义。
• 最小可通过版本，使用稳定占位符而非某次业务文件名。
• 一个贴近实际的常见示例。
• 常见失败、确认方法和修复顺序。
• 实现计划中本阶段追加记录的格式。

最小示例的作用是消除 YAML、JSON、Markdown 标记或注册格式的歧义，不代表鼓励 Agent 只生成最小内容。存在正文长度要求时，应在示例后明确“该片段只展示结构，正式内容必须满足详细度要求”。

FAQ 的定位¶

阶段 FAQ 是前人运行后总结出的稳定经验，随 Workflow Builder 一起放在公共 Guide_Doc/，不是每次业务运行都自动改写。只有确认问题具有通用性、原因和修复方法都得到验证后，才更新 FAQ。

FAQ 条目建议包含症状、真正原因、错误做法、正确处理和适用阶段。业务专有文件名只能放在“示例”字段，不能变成通用强制产物。例如不能因为某次业务生成了 diag_checker.py，就在通用规则里要求所有工作流创建它。

读取成本控制¶

阶段任务应直接引用本阶段短文档，不要把数百行公共契约全文塞入每个 config 阶段。Agent 先读目录、摘要和最小示例，遇到具体问题再定向读 FAQ 或开发文档。评估和增量认知阶段同样采用预算化读取，建立初步认识不等于全文扫描所有 docs。

修改方法¶

1. 先确认问题来自指导缺失，而不是 Checker 实现错误。
2. 更新公共源文档和相应阶段引用。
3. 如格式契约变化，同步更新最小示例、schema 和 Checker。
4. 检查文字不含业务耦合、未来文件引用和矛盾步骤。
5. 运行 GuideDoc 生成回归及配置引用检查。

文档质量检查¶

详细不等于反复说“必须详细”。高质量指导会给出字段、数据流、工具参数、判定条件和失败恢复。阶段描述至少应让没有参与过本次对话的 Agent 能够执行，不需要猜测文件名、模板名或输出位置。

GuideDoc spec 与文档类型¶

GuideDoc generator 同时处理阶段操作指导和最终用户文档，但两类文档使用不同契约。阶段 GuideDoc 强调 purpose、inputs、outputs、usage、execution、checks 和 failure recovery；用户文档强调有效正文长度、命令、输入输出和开发维护信息。开发者新增文档类型时，应先判断它由 Agent执行还是由人阅读，不能用同一组标题机械校验所有文档。

spec 应明确目标路径、文档类型、章节 id、heading、content 和注册阶段。id 是稳定语义，heading 可以中文化或调整措辞。只依靠标题文本会让“输入”“Inputs”“输入输出”被错误视为不同契约，因此当前实现保留兼容映射。

语义章节契约代码分析¶

源码位置：tools/workflow_guidedoc_generator/contract.py，符号 REQUIRED_SECTION_IDS、LEGACY_HEADING_IDS 和 section_id()。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

REQUIRED_SECTION_IDS = (
    "purpose", "inputs", "outputs", "usage",
    "execution", "checks", "failure_recovery",
)

def section_id(section):
    value = section.get("id")
    if isinstance(value, str) and value.strip():
        return value.strip()
    return LEGACY_HEADING_IDS.get(section.get("heading"), "")

显式 id 优先，使中文标题变更不影响验证。旧 spec 没有 id 时才按 heading 映射，提供向后兼容。新增必需章节会影响所有既有 GuideDoc，因此需要 schema 版本、默认迁移或充分回归；不能直接向 tuple 添加一个值并期望旧工作区自动通过。

REQUIRED_OPERATION_MARKERS 进一步检查关键章节是否真正说明 input/<TARGET>/、output/、make check_example 和 make run。它解决“标题齐全但正文空泛”的问题。不过 marker 只是最低证据，不应演变成所有业务文档都粘贴同一段命令。

spec 验证代码分析¶

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

验证器先通过 _safe() 限制 spec 和输出路径，再加载 YAML mapping，区分 user document 与 GuideDoc。对操作指导，它建立 section id 集合、检查缺失或重复、内容类型和 marker；对用户文档，调用 _effective_prose_length() 排除代码围栏、标题和格式噪声后计算正文。

这种顺序很重要：路径不安全应在读取或写入前失败；结构不合法时不要继续拼 Markdown；长度检查应基于实际说明而不是 YAML 序列化长度。若新增“源码分析”文档要求，应检查真实源码路径、代码围栏和分析章节，而不是把代码字符计入正文凑长度。

验证函数返回规范化 spec 列表供生成阶段使用。开发者不应在验证后再次从原始 YAML 读取一套未经规范化的字段，否则验证和生成会出现差异。

文档生成与注册代码分析¶

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

1
2
3
4
5
6

specs = validate_guidedoc_specs(workflow_root, spec_paths)
for spec in specs:
    target = _safe(root, spec["path"])
    content = render_sections(spec["sections"])
    _write_text(root, target, content)
    ... update config guide_docs registration ...

生成器应使用原子写入，避免长文档写到一半时被 UCAgent 读取。注册只适用于 Agent需要加载的 GuideDoc；普通用户文档不应全部塞入 guide_docs，否则每个阶段上下文都会无意义增大。注册记录必须使用 workflow-relative 文件路径，并与阶段引用一致。

当多个 GuideDoc 批量生成时，最好先全部验证，再开始写入。这样第七份 spec 格式错误不会留下前六份新文件和旧 config 的混合状态。若当前实现不能事务化，report 至少要准确列出已写文件，供失败恢复清理。

阶段指导的最小可通过结构¶

以下结构只展示语义，不代表正式内容可以如此简略：

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

path: Guide_Doc/stages/prepare.md
document_type: guidedoc
sections:
  - id: purpose
    heading: 目的
    content: 说明本阶段完成的唯一责任和明确不处理的内容。
  - id: inputs
    heading: 输入
    content: 列出执行前存在的具体文件、字段及来源阶段。
  - id: execution
    heading: 执行步骤
    content: 按顺序说明工具、参数、输出和计划追加位置。

正式 spec 还要包含 outputs、usage、checks、failure_recovery，并给每个工具和 Checker 足够细节。最小示例应紧邻“正文必须满足详细度”的提醒，防止 Agent把示例原样复制为最终文档。

FAQ 的维护链路¶

阶段失败得到证据后，先在实现计划本阶段“问题与处理”记录业务现场。流程完成后再分类：如果是某业务专有约束，保留在业务计划或业务 GuideDoc；如果是生成器缺陷，修改代码和回归；如果是跨业务稳定误区，才写入公共 FAQ。

FAQ 条目要提供症状、影响、确认步骤、根因、正确修复和错误做法。比如“Checker 报未读取 .//workflow/x”的通用根因是路径未规范化，不应把 .// 作为未来 Agent必须模仿的正确格式。FAQ 更新后应检查哪些阶段需要引用，不要让所有阶段默认读取所有 FAQ。

阅读预算与上下文设计¶

GuideDoc 的目标是减少 Agent决策成本，不是增加阅读仪式。一个阶段应直接引用短而完整的本阶段文档；共享长契约通过索引和规则 id 按需查阅。评估和增量流程应先读目录、manifest 摘要和目标对象索引，再按 finding 读取源码。

任务描述中“完整了解整个流程”容易导致全文扫描 tools、checkers、docs 和报告，压缩后又重复读取。更可靠的指令是规定第一轮最多读取哪些索引、要输出什么认知摘要，以及在处理某个对象时允许追加哪些直接依赖。

二次开发案例：为母工作流增加阶段指导¶

假设新增“素材许可证审查”阶段。开发者先在中心 workflow spec 声明输入为具体素材清单文件、输出为许可证报告、Tool 为许可证元数据解析器、Checker 为许可状态检查。阶段 GuideDoc 解释来源白名单、未知许可证行为、网络失败恢复和报告证据。

如果只增加 GuideDoc 而没有中心阶段和 Checker，文档不会被执行；如果只增加 config 阶段没有 GuideDoc，Agent会猜测工具参数；如果注册整个 docs/ 目录，阶段上下文会爆炸。正确修改同时覆盖 spec、工具、Checker、GuideDoc 注册、最小 fixture 和回归。

扩展点与测试¶

新增章节语义时测试显式 id、旧 heading 映射、缺失章节、重复章节和未知 id。修改长度算法时测试代码块、表格、链接、中文和英文正文。修改注册时测试用户文档不被注入 Agent、GuideDoc 可读取、路径不逃逸以及重复生成幂等。

真实业务验收还要阅读生成后的文档，而不仅看 checker return code。结构正确但步骤与工具实际签名不一致，仍然是严重文档缺陷。

横切 GuideDoc 完整索引¶

下表中的文件都位于母工作流 Guide_Doc/。它们是母 Agent 的执行契约，不是本开发者文档的内容。修改前要先在 YAML 中查询引用阶段，避免一份长文被无意注入所有阶段上下文。

24 份阶段 GuideDoc 完整索引¶

Guide_Doc/stages/README.md 是阶段文档目录与共享结构说明。下列文件与主 config.yaml 的 24 个 stage 一一对应，文件名中的序号和 stage name 都应保持同步。

新增或修改 GuideDoc 的标准流程¶

1. 定位这是横切契约、评估/增量契约还是一个主阶段的操作指导，并查询当前 YAML 引用范围。
2. 用具体文件、字段、Tool 参数、Checker 判定和失败证据写步骤，表述性内容使用中文，类名/字段/命令保留原文。
3. 附最小可通过结构和一个常见完整示例，紧邻提醒“最小示例不满足正文详细度/字数”，防止 Agent 照抄简略示例。
4. 将稳定通用故障写入对应 FAQ，只保留症状、根因、确认、正确修复和错误做法；不在每次业务运行中自动改母 FAQ。
5. 同步 stage task、guide_docs 注册、对应 Checker、生成文档规则和文档回归，再用一个新业务观察 Agent 是否可独立执行。

继续阅读¶

评估和增量 GuideDoc 背后还有 JSON 状态、审批新鲜度、候选部署与回滚契约。请继续阅读评估与增量控制，不要只改自然语言指导而留下不一致状态机。