graph-doc-writer

name	graph-doc-writer
description	基于 Graph 当前代码实现生成或重写说明文档。用户要求“给某个 Graph 写/重写 README、按既有风格成文、强调工作流与实现细节”时触发。

Graph Doc Writer（图文档生成器）

用于把某个 Graph 的实现（graph.py / state.py / nodes.py）整理成结构化中文 Markdown 说明文档，且文风对齐项目现有 Graph 文档（如 ConversationGraph、FRBuildingGraph）。

触发时机

• 用户要求“给 Graph 写说明文档 / 重写 README / 补文档”。
• 用户强调“按现有风格写”“参考已有 Graph 文档结构”。
• 用户要求文档必须“严格基于当前代码实现”，不能写成方案草稿。

输入

• 目标 Graph 路径（通常在 src/agents/graphs/<GraphName>/）。
• 参考风格文档（通常是同目录 README.md，或其他 Graph 的 README）。
• 用户给出的结构要求（例如必须包含“工作流设计”“短期记忆策略”等）。
• 文档落盘位置（src/.../README.md 或 docs/...）。

强制事实来源优先级

1. 目标 Graph 当前源码（graph.py、state.py、nodes.py）。
2. 目标 Graph 的现有 README（若存在）。
3. 其他 Graph README（仅用于风格与组织方式参考）。
4. 用户补充说明。

若 README 与源码冲突，必须以源码为准，并在文档中按“当前实现”表述，禁止把未落地方案写成已实现事实。

执行步骤

1. 先读实现，再读文档。

   • 必读 graph.py：节点、边、并行关系、编译与实例化方式。
   • 必读 state.py：输入输出结构、关键 state 字段、合并语义（尤其 Annotated / MessagesState）。
   • 必读 nodes.py：每个节点真实输入/输出、外部依赖、错误路径、日志、关键参数。
   • 再读目标 README 与风格参考 README。

2. 抽取“可落文档事实清单”。

   • 图入口与出口。
   • 节点职责与执行顺序。
   • 并行分支、汇合点与依赖关系。
   • 状态更新机制（整表覆盖 vs patch 更新）。
   • 关键策略（trim / recall / conflict / report 等）。
   • 环境变量与默认值。
   • 异常处理与降级路径。

3. 生成文档骨架（默认两层）。

   • # <GraphName>
   • 一段“用途定义”。
   • ## 工作流设计：使用编号步骤（1,2,3...）描述端到端链路。
   • ## 关键实现策略：按模块拆分（如短期记忆、召回、落库、输出构建）。
   • ## 参数与边界（有必要时）。
   • ## 当前取舍（优点 / 成本，均需可追溯到代码）。

4. 工作流段落写作规范（强约束）。

   • 按真实执行顺序写，不能按理想流程重排。
   • 节点名使用代码真实命名（如 nodeBuildAndTrimMessage）。
   • 并行关系必须明确标注“并行”与“汇合到哪个节点”。
   • 每个步骤至少包含“输入来源 + 动作 + 输出写回 state”。

5. 实现策略段落写作规范（强约束）。

   • 必须写“触发条件”“处理逻辑”“返回结构”“对下游影响”。
   • 若有阈值参数，必须列出变量名和默认值。
   • 若有降级或兜底路径，必须明确条件和结果。
   • 禁止泛泛而谈“做了优化”，必须可映射到函数级实现。

6. 风格对齐（贴近现有 Graph README）。

   • 句式偏工程实操，不写空泛术语。
   • 优先使用“这个 graph 用于...”“步骤 N ...”。
   • 保留“【过程中实时记录日志】”这类项目内固定表达（若该图确实有日志链路）。

7. 输出与回检。

   • 落盘到用户指定路径。
   • 自检：节点名、字段名、环境变量名、默认值是否与代码一致。
   • 若做了覆盖式重写，确保原有关键结论未丢失（除非与源码冲突）。

质量门槛

• 真实性：每条关键描述都能在当前代码中定位依据。
• 完整性：至少覆盖“输入 -> 图流转 -> 输出”的完整闭环。
• 可执行性：读者可据文档快速定位每个节点的职责与改动点。
• 风格一致性：与 FRBuildingGraph / ConversationGraph README 读感一致。
• 无幻觉：不新增代码里不存在的节点、字段、策略、参数。

禁止事项

• 禁止只参考旧 README，不读当前源码。
• 禁止把注释里的 TODO/设想写成“当前已实现”。
• 禁止改写节点命名导致文档与代码检索不一致。
• 禁止忽略并行分支与 state 合并语义。
• 禁止省略错误路径与降级逻辑（若代码中存在）。