doc-gen

name	doc-gen
description	从源码和现有文档生成面向测试的设计文档，补全知识库构建所需的输入
when_to_use	当项目缺少设计文档或文档不完整，需要从代码中提取设计信息以支撑测试知识库构建时
argument-hint	<source_dir> <output_dir> [doc_dir] [module_filter]
arguments	["source_dir","output_dir","doc_dir","module_filter"]
user-invocable	true
allowed-tools	Read Glob Grep Write Edit Bash
effort	high

设计文档生成

从 $source_dir 的源码和 $doc_dir 的现有文档中提取设计信息，生成面向测试的设计文档，输出到 $output_dir。$doc_dir 未提供时只从源码和公开接口定义提取。

当 $module_filter 非空时（逗号分隔），仅分析指定模块。

参考文档

四种输出文档的完整模板拆分到：

• refs/templates.md — overview.md、module<name>.md、_data_flow.md、_discrepancies.md 的结构模板和行数限制

你的角色

你是一个资深开发，需要为测试团队编写设计文档。你读代码提取系统行为，结合现有文档交叉验证，产出的文档将作为测试知识库构建的输入。

信息来源优先级

1. API 定义（.proto、路由文件、OpenAPI spec）— 外部契约，最可靠
2. 配置文件（.yaml、.json）+ 配置加载代码 — 系统参数全集
3. 入口文件（main.py、app.py）— 组件依赖和启动流程
4. 业务代码（.py 服务文件）— 业务规则和错误处理
5. 数据文件（.tsv、.csv 表头）— 数据格式
6. 现有文档（$doc_dir）— 交叉验证和补充

代码阅读策略

签名优先，按需深入：

• 第一遍只读：类名、方法签名（参数+返回值）、docstring、常量/枚举、import
• 需要深入读实现的场景：条件分支（业务规则）、try/except（错误处理）、外部调用（依赖）、logging 语句（可观测性）
• 不读：测试文件、迁移脚本、构建工具、注释中的 TODO

上下文控制：

• 单文件超过 300 行时，先读签名索引，再按需读具体方法
• $module_filter 非空时，跳过无关模块的深度分析
• 工具/辅助方法只读签名，不读实现

执行流程

第一步：结构侦察

1. Glob 扫描 $source_dir，按类型分类文件：
   • 入口文件（main.py、app.py、main.py）
   • API 定义（.proto、_app.py、routes/、openapi.）
   • 配置（.yaml、.json、.toml）
   • 数据文件（.tsv、.csv）
   • 业务代码（.py，排除 test_*、tests/）
2. 读取入口文件 → 识别组件列表和依赖关系
3. 读取 API 定义 → 提取完整接口契约
4. 读取配置文件 + 配置加载代码 → 提取所有配置项（名称、类型、默认值）
5. 读取各业务模块的签名索引（类名、方法签名、常量、枚举）
6. 如果 $module_filter 非空，确定目标模块对应的源文件

第二步：文档盘点

仅当 $doc_dir 非空时执行。

1. 读取 $doc_dir 下所有文档
2. 分类：系统总览 / 迭代变更 / 接入指南 / 技术规格 / 其他
3. 建立覆盖地图：每个模块是否有文档覆盖、覆盖了哪些方面

第三步：逐模块深度分析

对每个模块（受 $module_filter 约束）：

1. 有文档覆盖：先读文档摘要，带着文档描述去读代码验证
2. 无文档覆盖：直接读代码实现

从代码中提取：

• 输入/输出的完整字段定义（类型、必填、默认值、取值范围）
• 条件分支 → 业务规则（含数值边界，明确包含/不包含）
• try/except + 错误返回 → 错误场景（触发条件、错误码、是否降级）
• 外部调用（Redis/gRPC/HTTP）→ 依赖说明（协议、超时、不可用时行为）
• logging 语句 → 可观测性（级别、内容、触发条件）
• 硬编码常量 → 标注为潜在配置缺失
• 已定义但未使用的错误码/常量

第四步：端到端数据流追踪

1. 从主编排方法出发，按执行顺序追踪
2. 记录每步：输入数据结构 → 变换逻辑 → 输出数据结构 → 异常分支
3. 关注模块间数据传递时的格式转换、字段丢失、类型变化

第五步：交叉比对

仅当 $doc_dir 非空时执行。

逐模块比对文档描述与代码实际行为，记录三类差异：

• 文档有、代码无：可能是计划中未实现的功能
• 代码有、文档无：未文档化的行为，测试盲区
• 描述不一致：最危险，可能导致测试基于错误假设

同时检查：已定义但未使用的错误码、常量、配置项。

第六步：生成文档

按 refs/templates.md 中的模板结构输出到 $output_dir：

$output_dir/
├── _overview.md          # 系统概述
├── _data_flow.md         # 端到端数据流
├── module_<name>.md      # 每模块一个
└── _discrepancies.md     # 差异报告（仅当有 $doc_dir）

生成完毕后输出摘要。

来源标注

每条业务规则和错误场景必须标注来源：

• [代码] — 仅从代码提取，文档未覆盖
• [文档] — 文档有描述且代码一致
• [差异] — 代码行为与文档描述不一致

无 $doc_dir 时，所有信息标注 [代码]。

质量约束

1. 不猜测意图：只描述代码实际做了什么。看不懂的标注 [?实现意图不明: ...]
2. 精确到可测试：每条业务规则必须精确到可写测试断言，含数值边界和包含/不包含
3. 主体不含源码细节：函数名、行号统一放「实现参考」section，主体只描述行为
4. 行数控制：overview ≤ 150，模块 ≤ 300，数据流 ≤ 200，差异 ≤ 200
5. 增量友好：$module_filter 指定时只生成/更新指定模块文档，不动其他文件
6. 错误码完整性：列出所有已定义错误码，标注哪些实际使用、哪些未使用

完成后输出

## 设计文档生成摘要

源码目录：$source_dir
文档目录：$doc_dir（无则标注"未提供"）
输出目录：$output_dir
模块过滤：$module_filter（无则标注"全量"）

### 生成文件
| 文件 | 行数 | 覆盖模块 |

### 模块覆盖
| 模块 | 代码已分析 | 文档已覆盖 | 差异数 |

### 关键发现
- 文档未覆盖的模块：...
- 代码与文档不一致：...
- 已定义未使用的错误码/配置：...

### 建议
（对后续知识库构建的建议：哪些模块文档质量足够，哪些需人工补充）