doc-genlisted

# 设计文档生成 从 `$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. **无文档覆盖**：直接读代码实现 从代码中提取： - 输入/输出的完整字段定义（类型、必填、默