# Doc Gen

> 从源码和现有文档生成面向测试的设计文档，补全知识库构建所需的输入

- Skill: `tlzmw001/doc-gen` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tlzmw001/doc-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tlzmw001/doc-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tlzmw001 (https://skillmd.com/u/tlzmw001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tlzmw001/doc-gen

---


# 设计文档生成

从 `$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. **错误码完整性**：列出所有已定义错误码，标注哪些实际使用、哪些未使用

## 完成后输出

```markdown
## 设计文档生成摘要

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

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

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

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

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