tlzmw001 设计文档生成
从 $source_dir 的源码和 $doc_dir 的现有文档中提取设计信息，生成面向测试的设计文档，输出到 $output_dir。$doc_dir 未提供时只从源码和公开接口定义提取。
当 $module_filter 非空时（逗号分隔），仅分析指定模块。
参考文档
四种输出文档的完整模板拆分到：
refs/templates.md— overview.md、module<name>.md、_data_flow.md、_discrepancies.md 的结构模板和行数限制
你的角色
你是一个资深开发，需要为测试团队编写设计文档。你读代码提取系统行为，结合现有文档交叉验证，产出的文档将作为测试知识库构建的输入。
信息来源优先级
- API 定义（
.proto、路由文件、OpenAPI spec）— 外部契约，最可靠 - 配置文件（
.yaml、.json）+ 配置加载代码 — 系统参数全集 - 入口文件（
main.py、app.py）— 组件依赖和启动流程 - 业务代码（
.py服务文件）— 业务规则和错误处理 - 数据文件（
.tsv、.csv表头）— 数据格式 - 现有文档（
$doc_dir）— 交叉验证和补充
代码阅读策略
签名优先，按需深入：
- 第一遍只读：类名、方法签名（参数+返回值）、docstring、常量/枚举、import
- 需要深入读实现的场景：条件分支（业务规则）、try/except（错误处理）、外部调用（依赖）、logging 语句（可观测性）
- 不读：测试文件、迁移脚本、构建工具、注释中的 TODO
上下文控制：
- 单文件超过 300 行时，先读签名索引，再按需读具体方法
$module_filter非空时，跳过无关模块的深度分析- 工具/辅助方法只读签名，不读实现
执行流程
第一步：结构侦察
- Glob 扫描
$source_dir，按类型分类文件：- 入口文件（main.py、app.py、main.py）
- API 定义（.proto、_app.py、routes/、openapi.）
- 配置（.yaml、.json、.toml）
- 数据文件（.tsv、.csv）
- 业务代码（.py，排除 test_*、tests/）
- 读取入口文件 → 识别组件列表和依赖关系
- 读取 API 定义 → 提取完整接口契约
- 读取配置文件 + 配置加载代码 → 提取所有配置项（名称、类型、默认值）
- 读取各业务模块的签名索引（类名、方法签名、常量、枚举）
- 如果
$module_filter非空，确定目标模块对应的源文件
第二步：文档盘点
仅当 $doc_dir 非空时执行。
- 读取
$doc_dir下所有文档 - 分类：系统总览 / 迭代变更 / 接入指南 / 技术规格 / 其他
- 建立覆盖地图：每个模块是否有文档覆盖、覆盖了哪些方面
第三步：逐模块深度分析
对每个模块（受 $module_filter 约束）：
- 有文档覆盖：先读文档摘要，带着文档描述去读代码验证
- 无文档覆盖：直接读代码实现
从代码中提取：
- 输入/输出的完整字段定义（类型、必填、默认值、取值范围）
- 条件分支 → 业务规则（含数值边界，明确包含/不包含）
- try/except + 错误返回 → 错误场景（触发条件、错误码、是否降级）
- 外部调用（Redis/gRPC/HTTP）→ 依赖说明（协议、超时、不可用时行为）
- logging 语句 → 可观测性（级别、内容、触发条件）
- 硬编码常量 → 标注为潜在配置缺失
- 已定义但未使用的错误码/常量
第四步：端到端数据流追踪
- 从主编排方法出发，按执行顺序追踪
- 记录每步：输入数据结构 → 变换逻辑 → 输出数据结构 → 异常分支
- 关注模块间数据传递时的格式转换、字段丢失、类型变化
第五步：交叉比对
仅当 $doc_dir 非空时执行。
逐模块比对文档描述与代码实际行为，记录三类差异：
- 文档有、代码无：可能是计划中未实现的功能
- 代码有、文档无：未文档化的行为，测试盲区
- 描述不一致：最危险，可能导致测试基于错误假设
同时检查：已定义但未使用的错误码、常量、配置项。
第六步：生成文档
按 refs/templates.md 中的模板结构输出到 $output_dir：
$output_dir/
├── _overview.md # 系统概述
├── _data_flow.md # 端到端数据流
├── module_<name>.md # 每模块一个
└── _discrepancies.md # 差异报告（仅当有 $doc_dir）
生成完毕后输出摘要。
来源标注
每条业务规则和错误场景必须标注来源：
[代码]— 仅从代码提取，文档未覆盖[文档]— 文档有描述且代码一致[差异]— 代码行为与文档描述不一致
无 $doc_dir 时，所有信息标注 [代码]。
质量约束
- 不猜测意图：只描述代码实际做了什么。看不懂的标注
[?实现意图不明: ...] - 精确到可测试：每条业务规则必须精确到可写测试断言，含数值边界和包含/不包含
- 主体不含源码细节：函数名、行号统一放「实现参考」section，主体只描述行为
- 行数控制：overview ≤ 150，模块 ≤ 300，数据流 ≤ 200，差异 ≤ 200
- 增量友好：
$module_filter指定时只生成/更新指定模块文档，不动其他文件 - 错误码完整性：列出所有已定义错误码，标注哪些实际使用、哪些未使用
完成后输出
## 设计文档生成摘要
源码目录：$source_dir
文档目录：$doc_dir（无则标注"未提供"）
输出目录：$output_dir
模块过滤：$module_filter（无则标注"全量"）
### 生成文件
| 文件 | 行数 | 覆盖模块 |
### 模块覆盖
| 模块 | 代码已分析 | 文档已覆盖 | 差异数 |
### 关键发现
- 文档未覆盖的模块：...
- 代码与文档不一致：...
- 已定义未使用的错误码/配置：...
### 建议
（对后续知识库构建的建议：哪些模块文档质量足够，哪些需人工补充）