# Write Design Doc

> 编写 C++ 项目的详细设计文档和设计变更影响面分析。当用户说要写详细设计、生成设计文档、做影响面分析、描述功能需求要写设计、或者说"把这个需求的设计写出来"时触发。也用于增量更新已有设计文档、以及清除迭代标记输出最终版。

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

---


# 详细设计编写 Skill

从需求规格、概要设计、项目代码等输入，生成符合模板规范的详细设计文档和设计变更影响面分析。

---

## 模板文件

模板和规范文件优先从工程级路径读取，若工程级路径不存在，则回退到 `references/` 目录。**当使用 `references/` 下的引用文件时，必须告知用户**。

| 文件 | 用途 | 优先读取路径 | 回退路径 | 何时加载 |
|------|------|-------------|----------|---------|
| 应用设计说明书模板 | 详细设计文档模板，含每章的 AI 注释指令 | `projects/{工程名}/docs/04-设计/应用设计说明书_模板.md` | `references/应用设计说明书_模板.md` | 仅在初次新建时加载。增量更新直接修改已有文档，不重新加载模板 |
| 设计变更影响面分析模板 | 影响面分析模板，相对独立 | `projects/{工程名}/docs/04-设计/设计变更影响面分析_模板.md` | `references/设计变更影响面分析_模板.md` | 仅在生成或更新影响面分析时加载 |
| mermaid 画图规范 | Mermaid 图表绘制规范，约 1000 行 | `projects/{工程名}/docs/04-设计/画图规范.md` | `references/画图规范.md` | 按需按章节加载 |

---

## 数据来源（输入）

下表列出生成详细设计文档时需要的输入数据。根据当前设计范围，只加载相关的输入。

### 仓库级输入

| 类别 | 说明 | 推荐路径 |
|------|------|---------|
| 需求规格说明书 | 版本目标、功能需求 | `Program/software/docs/02-需求/需求规格说明书.md` |
| 需求影响分析矩阵 | 影响范围 | `Program/software/docs/02-需求/需求影响分析矩阵.md` |
| 系统架构总览 | 分层架构、通信拓扑、设计约束 | `Program/software/docs/01-总览/系统架构总览.md` |
| 客户端概要设计 | 客户端概设 | `Program/software/docs/03-概设/客户端概要设计.md` |
| 服务端概要设计 | 服务端概设 | `Program/software/docs/03-概设/服务端概要设计.md` |
| 通信协议 | 跨工程通信方式、消息格式 | `Program/software/docs/04-协议/通信协议.md` |
| 全局错误码 | 错误码分段、通用错误码 | `Program/software/docs/04-协议/全局错误码.md` |
| 服务端工程说明 | 核心流程、状态机、异常模式 | `Program/software/docs/07-工程说明/server.md` |

### 工程级输入

| 类别 | 说明 | 推荐路径 |
|------|------|---------|
| 架构总览 | 本工程分层架构 | `projects/{工程名}/docs/01-总览/架构总览.md` |
| 目录结构 | 本工程目录约定 | `projects/{工程名}/docs/01-总览/目录结构.md` |
| 模块索引 | 模块依赖关系、影响面速查 | `projects/{工程名}/docs/03-模块依赖/模块索引.md` |
| 模块 README | 类图、接口签名、文件路径 | `projects/{工程名}/docs/03-模块依赖/{模块名}/README.md` |
| 编码规范 | 本工程编码约束 | `projects/{工程名}/docs/02-规范/编码规范.md` |

### 代码输入

| 类别 | 路径模式 | 提取内容 |
|------|---------|---------|
| 公共接口 | `components/include/` 下对应 `.h` | 类声明、继承关系、public 方法签名 |
| 业务实现 | `components/business/` 下对应 `.cpp` | 函数调用链、线程创建、缓存操作、SQL 语句、异常处理 |

---

## 输出位置

| 产出物 | 路径 | 文件名命名规范 |
|--------|------|---------------|
| 详细设计文档 | `projects/{工程名}/docs/04-设计/` | `{项目或迭代版本}_服务端/客户端_应用设计说明书.md` |
| 影响面分析 | `projects/{工程名}/docs/04-设计/` | `{项目或迭代版本}_服务端/客户端_影响面分析.md` |

### 命名规范说明

1. **基本格式**：`{项目或迭代版本}_{端}_应用设计说明书.md`
   - 示例：`V2.3_机器人引导_服务端_应用设计说明书.md`
   - 示例：`迭代三_视觉检测_客户端_应用设计说明书.md`
2. **`{项目或迭代版本}`**：取需求规格或版本计划中的版本号、迭代号或项目简称
3. **`{端}`**：根据设计范围选择 `服务端` 或 `客户端`；同时涉及两端时，分别输出两份文档
4. **影响面分析**：与对应详设文档同名，将 `应用设计说明书` 替换为 `影响面分析`

---

## 四种工作模式

### 模式一：新建详细设计

用户描述一个新需求，从零生成设计文档和影响面分析。

**步骤**：

1. **收集意图**：与用户确认设计范围——涉及哪些模块、新增还是修改、有无参考的已有设计

2. **探查输入**：
   - 按模板文件加载策略读取 应用设计说明书_模板.md（优先工程级路径，回退 `references/`，全文，仅初次新建时加载）
   - 搜索并读取需求相关文档（从数据来源表中按需选择）
   - 搜索受影响模块的 README

3. **探查代码**（每个受影响的模块）：
   - `.h` 文件：提取类声明、继承关系、public 方法签名
   - `.cpp` 文件：搜索线程创建 (`std::thread` / `pthread_create`)、缓存结构 (`DataCache` / `m_cache`)、异常处理 (`LOG_ERROR` / `try`-`catch`)、SQL 语句 (`CREATE TABLE`)
   - 仅搜索与本次设计相关的文件

4. **按章生成**：
   - 按模板骨架逐章生成。每章先读注释理解要求，再结合输入内容生成
   - 需要 mermaid 图时，按模板文件加载策略读取 画图规范.md 的对应章节（见下方"Mermaid 图按需加载策略"）
   - 生成顺序：第 1 章 → 第 2 章 → 第 3 章（全局设计 → 各模块）→ 第 4 章 → 第 5 章 → 第 6 章 → 第 7 章 → 第 8 章
   - 第 3 章生成时，按模块顺序（被依赖的先写）

5. **生成影响面分析**：
   - 按模板文件加载策略读取 设计变更影响面分析_模板.md
   - 根据设计文档中的变更内容，填充客户端变更（第 2 章）和服务端变更（第 3 章）

6. **输出**：保存两个文件到输出位置

---

### 模式二：增量更新

在已有设计文档基础上增量修改。

**步骤**：

1. **读取已有文档**：读取当前版本的设计文档

2. **确认上一轮已完成评审（强提示 + 默认继续）**：
   - 检查文档中是否仍残留 `<mark>` 标签、mermaid 黄色高亮块或"本轮变更说明"表
   - 若存在，提示用户："检测到上一轮迭代标记未清理，建议先完成评审。如无需处理，将在 5 秒后自动清理并继续。"
   - **用户不回应或确认继续时，默认清理旧标记并继续**；用户明确拒绝时停止

3. **清除上一轮标记**：清除上一轮遗留的所有标记（见"迭代标记与清理规范"）

4. **探查变更影响**：
   - 根据变更描述，确定受影响的章节
   - 读取相关代码文件的最新版本
   - 仅在受影响的章节范围内工作

5. **增量修改**：
   - 只重写受影响的章节，未变更的章节保持原样
   - 新增/修改的内容用 `<mark>...</mark>` 包裹
   - 删除的内容：直接从正文和 mermaid 图中移除，**不在文档中保留被删除的原文或旧图元素**
   - 在章节末尾或 mermaid 图下方的"本轮变更说明"表中，用文字列出删除项（删除项描述可标黄），说明删除原因

6. **更新影响面分析**：
   - 对比新旧设计文档的差异
   - 更新影响面分析中对应的客户端（第 2 章）/服务端（第 3 章）变更章节
   - 新的影响项用 `<mark>` 包裹

7. **输出**：覆盖原文件

---

### 模式三：单独生成影响面分析

**步骤**：
1. 按模板文件加载策略读取 设计变更影响面分析_模板.md
2. 对比两个版本设计文档的差异（或 git diff）
3. 提取变更的文件、接口、数据库、配置维度
4. 填充客户端（第 2 章）和服务端（第 3 章）变更列表
5. 标注 AI 推断项（"影响的关联产品"置信度低，标记需人工确认）

---

### 模式四：发布定稿

清除所有迭代标记，输出可提交评审的最终版本。**必须由用户显式触发**，禁止在增量更新中自动执行。

**步骤**：
1. 清除全文档所有 `<mark>` 和 `</mark>` 标签（保留内容文本）
2. 清除 mermaid 图中所有变更标记：
   - 移除 `fill:#FFD700` 黄色高亮样式，恢复节点原色
   - 移除 `stroke:#FFD700` 黄色描边/加粗样式
3. 移除所有 mermaid 图下方的"本轮变更说明"表
4. 将 TLDR 和正文中的 `{占位符}` 替换为实际内容
5. 更新修订记录表中的版本号和日期
6. 输出

---

## AI 生成约束

所有由本 Skill 生成的文档（含 AI-native 版详设文档和影响面分析）必须遵守以下约束。这些规则不写入模板正文，而是作为 Skill 生成指令的一部分执行。

### 统一标识规则

生成文档时，为下列对象分配唯一 ID，并确保跨章节引用一致：

| 对象类型 | ID 前缀 | 示例 | 使用位置 |
|----------|---------|------|----------|
| 需求 | REQ- | REQ-001 | 需求追踪、功能说明、实现任务 |
| 接口 | IF- | IF-001 | 接口契约、接口变更、实现任务 |
| 数据表 | TBL- | TBL-001 | 表汇总、数据库变更、实现任务 |
| 风险 | RISK- | RISK-001 | 风险与注意事项、实现任务 |
| 实现任务 | TASK- | TASK-001 | 实现任务清单 |

规则：
- ID 按文档内首次出现顺序递增编号。
- 同一对象在不同章节中引用时必须使用相同 ID。
- 实现任务清单中的 `关联接口/表/风险` 列必须填写对应 ID。

### 枚举取值约束

以下字段只能使用指定枚举值，禁止自由文本：

| 字段 | 允许取值 |
|------|----------|
| 操作类型 | 增 / 删 / 改 / 查 |
| 影响评估 | 无影响 / 增加 / 减少 / 待评估 |
| 兼容策略 | 兼容 / 不兼容 / 自动迁移 / 手动配置 / 需迁移脚本 |
| 严重程度 | 高 / 中 / 低 |
| 线程安全 | 是 / 否 / 部分 |
| 置信度 | 高 / 中 / 低 |

### 置信度判定规则

| 置信度 | 判定规则 |
|--------|----------|
| 高 | 可直接从代码或需求原文验证，无跨模块推理 |
| 中 | 需要跨文件或跨模块推理，存在一定合理假设 |
| 低 | 需要跨工程/跨产品推断，或信息不足，必须人工确认 |

### 低置信度项标注要求

- 影响面分析中置信度为“低”的推断项，必须在表格中用 `<mark>` 或加粗方式突出显示。
- 不在表格中预填写确认人、确认结论、确认日期。
- 增量更新或发布定稿前，需检查所有低置信度项是否已被人工处理（直接修改或删除 `<mark>`）。

### 性能指标三元组

所有性能相关表格必须包含：

| 字段 | 说明 |
|------|------|
| 基线值 | 变更前的测量值；无法确定时填“需人工填写” |
| 目标值 | 变更后期望达到的测量值；无法确定时填“需人工填写” |
| 测量方法 | 如何测量，如单请求压测、并发压测、内存监控等 |

### 接口运行语义

接口契约表必须包含以下字段：

| 字段 | 说明 |
|------|------|
| 超时 | 接口调用超时时间；不适用时填 N/A |
| 重试 | 失败重试次数；不适用时填 N/A |

### 证据来源要求

影响面分析中的 AI 推断项必须填写证据来源：

| 推断类型 | 证据来源示例 |
|----------|-------------|
| 影响的模块 | 代码分析：`include/Xxx.h`、`调用链搜索结果` |
| 影响的关联产品 | 跨工程关联推断；置信度为低时必须标注 |
| 性能影响 | 代码变更范围、调用链分析 |
| 回退策略 | 变更内容、配置文件变更 |

---

## 分析设计原则

本 Skill 在需求分析、方案设计和影响面评估阶段必须遵循以下原则。这些原则约束 AI 的推理过程，而非文档格式。

### 1. 证据优先原则

所有分析结论必须绑定可验证证据来源（需求条目、接口契约、数据模型、调用链、历史缺陷等）。无证据来源的推断必须标注为低置信度。

### 2. 可证伪原则

每个结论必须给出反证路径和验证方式，确保结论可被推翻或验证，而不是只可证明、不可推翻。

### 3. 不确定性显式化原则

对推断项必须标注置信度（高/中/低）。低置信度项必须进入人工确认清单，并在表格中用 `<mark>` 或加粗方式突出显示。

### 4. 冲突即停止原则（分析阶段）

发现需求与约束、接口与数据模型、设计与实现现实冲突时，停止继续细化设计，先输出冲突清单并等待解决。

### 5. 影响面前置原则

在设计阶段就完整列出文件、接口、数据库、配置、性能影响，不把影响面留到开发阶段补全。

### 6. 契约优先与版本化原则

先定义接口契约，再设计流程；涉及变更时，先定义版本策略与兼容边界。

### 7. 可回滚优先原则

方案设计时同步给出回退路径、数据可逆性判断、升级失败触发条件。

### 8. 性能守恒原则

无基线和目标时，不允许写“无影响”；必须说明测量口径和阈值。

### 9. 变更边界原则

明确包含与不包含范围，超范围项必须单列并重新评估。

### 10. 可追踪闭环原则

确保需求-设计决策-验证项可一一映射，为开发阶段提供可执行输入。

---

## CRUD 分类规则

在进入具体模块设计前，先识别本需求/模块涉及的操作类型（增 Create、删 Delete、改 Update、查 Read/Query），作为后续差异化生成的依据。

### 优先级

1. **用户显式说明为第一优先级**：如果用户在触发 skill 时明确指定了操作类型（例如"这是一个新增需求"、"只做查询和导出"、"涉及增删改"），直接按用户说明分类，不再自动推断。
2. **自动识别为第二优先级**：用户未显式说明时，根据需求规格说明书中的功能需求描述自动识别。

### 自动识别规则

| 操作类型 | 典型关键词/语义特征 |
|----------|---------------------|
| **增（Create）** | 新增、创建、添加、插入、导入、注册、生成、初始化、上传 |
| **删（Delete）** | 删除、移除、卸载、注销、清空、回收、废弃、下架 |
| **改（Update）** | 修改、更新、编辑、变更、调整、配置、设置、启用/禁用、重置、状态变更 |
| **查（Query）** | 查询、查看、搜索、筛选、列表、详情、统计、导出、报表、历史记录 |

### 自动识别过滤规则

关键词匹配容易产生误判，需结合上下文过滤：

| 过滤场景 | 示例 | 处理 |
|----------|------|------|
| **否定词** | "不支持删除"、"无法修改"、"禁止查询" | 该关键词不计入对应操作类型 |
| **非操作对象** | "删除键"（键盘按键）、"查询语言"、"配置文件更新" | 判断动作是否有明确的业务数据对象，无对象则过滤 |
| **日志/记录类描述** | "更新日志"、"删除记录查看"、"历史修改记录" | 若关键词用于描述记录本身而非业务操作，过滤或降级为"查" |
| **将来/计划态** | "计划新增"、"未来可能删除" | 未在本次版本落地的操作，不计入 |
| **单一出现且无宾语** | 文本中只出现"删除"二字，未说明删除什么 | 置信度标为低，提示用户确认 |

### 多操作混合

一个需求可能同时包含多种操作。识别结果用逗号分隔列出，例如：`增、改、查` 或 `增、删、改、查`。

**置信度标注**：
- **高**：关键词明确 + 有明确操作对象 + 无否定词
- **中**：关键词明确但对象模糊，或存在需过滤的上下文
- **低**：仅出现单一关键词且无宾语，或用户描述与自动识别结果冲突

对于中/低置信度的识别结果，在生成时标注 `<!-- 待确认 -->`，并提示用户核对。

### 对生成的指导

识别出的 CRUD 类型用于指导后续章节生成：

- **3.x.1 功能说明**：明确写出"本模块提供 XX 的[增/删/改/查]能力"
- **3.x.2 模块结构及依赖**：配置界面类模块可划分子模块时，优先按 CRUD 拆分（如 `XxxAddPage`、`XxxEditPage`、`XxxQueryPage`）
- **3.x.3 类关系图 / 3.x.4 核心类描述**：按 CRUD 组织接口或类，接口命名倾向 `addXxx` / `removeXxx` / `updateXxx` / `queryXxx`
- **3.x.5 核心流程说明**：每个主要操作类型一个 H5 子章节，分别画时序图
- **3.x.9 数据缓存说明**：查操作关注缓存命中与失效策略；改操作关注缓存更新与一致性
- **3.x.10 测试要点**：按 CRUD 生成覆盖黄金路径、异常路径、边界条件的测试场景
- **6.3 物理设计**：查操作关注索引设计；改操作关注事务与并发控制；删操作关注级联与外键约束
- **影响面分析**：服务端接口变更和数据库变更按 CRUD 分组列出

---

## 迭代标记与清理规范

多轮迭代时，让评审者一眼看出本轮改了什么。

### 新增/修改标记

- 本轮新增或修改的**文本、表格行、列表项**用 `<mark>...</mark>` 包裹
- 未修改的旧内容不包裹
- `<mark>` 标签在大多数 Markdown 渲染器中显示黄色高亮背景

**写之前必须先确认并清理**：
1. 确认上一轮标记**已完成评审**（模式二步骤 2，强提示 + 默认继续）
2. 清除上一轮遗留的所有 `<mark>` 和 `</mark>` 标签
3. 清除 mermaid 图中上一轮遗留的黄色高亮块和"本轮变更说明"表

### 删除标记

删除的内容直接从正文和 mermaid 图中移除，**不在文档内保留被删除的原文或旧图元素**。

若需让 reviewer 了解删除情况，在章节末尾或 mermaid 图下方的"本轮变更说明"表中列出删除项，**删除项描述可用 `<mark>...</mark>` 标黄**以突出显示。

**示例**：

```markdown
**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新接口 | 新增 | 新增替代接口 |
| <mark>旧接口</mark> | <mark>删除</mark> | <mark>已废弃，由新接口替代</mark> |
```

### Mermaid 图变更标记

mermaid 代码块内无法使用 `<mark>` HTML 标签，统一使用 **黄色高亮块（`#FFD700`）** 表示新增/修改。**删除的元素/消息直接从图中移除**，不在图中保留灰色、注释或任何标记。

#### 按图表类型的标记方式（优先使用稳定语法）

| 图表类型 | 新增/修改 | 删除 | 说明 |
|----------|-----------|------|------|
| **flowchart / classDiagram** | 节点：`style Node fill:#FFD700,color:#000`<br/>连线：`linkStyle N stroke:#FFD700,stroke-width:4px` | 直接移除节点/连线 | `style` 和 `linkStyle` 在 flowchart/classDiagram 中稳定支持 |
| **erDiagram** | 实体：`style Entity fill:#FFD700,color:#000` | 直接移除实体/关系 | ER 图变更较少，优先通过文字说明 |
| **sequenceDiagram** | 参与者：`box rgb(255, 215, 0) ... end` 包裹新增/修改的参与者<br/>消息块：`rect rgb(255, 215, 0) ... end` 包裹新增/修改的消息 | 直接移除该消息行 | 避免使用 `style`/`classDef` 修饰参与者，不同 Mermaid 版本兼容性差 |

#### 删除元素的处理

1. 直接从 mermaid 图中移除被删除的节点、连线或消息
2. 在图下方"本轮变更说明"表中用文字记录删除项，删除项描述可标黄
3. 定稿阶段由用户触发，确认后无额外清理工作

**每个 mermaid 图下方必须补充"本轮变更说明"表**：

```markdown
**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新节点 | 新增 | 新增 XXX 处理节点 |
| <mark>旧连线</mark> | <mark>删除</mark> | <mark>原确认逻辑移入 C</mark> |
```

**示例 1：flowchart（新增节点、修改连线）**

```mermaid
flowchart LR
    A["服务A"]
    B["服务B"]
    C["服务C"]

    A --> B
    B --> C

    style C fill:#FFD700,color:#000
    linkStyle 1 stroke:#FFD700,stroke-width:4px
```

**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| C | 新增 | 新增服务C |
| B->C | 修改 | 原为 B->D，D 已删除 |
| <mark>B->D</mark> | <mark>删除</mark> | <mark>D 不再使用</mark> |

**示例 2：sequenceDiagram（新增参与者、修改消息）**

```mermaid
sequenceDiagram
    participant A as 服务A
    participant B as 服务B

    box rgb(255, 215, 0) 新增服务C
        participant C as 服务C
    end

    A->>B: 查询数据

    rect rgb(255, 215, 0)
        B-->>A: 返回结果
    end
```

**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| C | 新增 | 新增服务C作为后续确认处理方 |
| B-->>A: 返回结果 | 修改 | 原为"返回数据" |
| <mark>B->>A: 旧的确认消息</mark> | <mark>删除</mark> | <mark>确认逻辑移入C</mark> |

### 清理步骤

写操作前执行：
1. 移除全文档所有 `<mark>` `</mark>` 标签（保留内容）
2. 移除 mermaid 图中上一轮遗留的黄色高亮样式：
   - 所有 `fill:#FFD700` 恢复为原色
   - 所有 `stroke:#FFD700` 恢复为默认
3. 移除所有 mermaid 图下方的"本轮变更说明"表
4. 上一轮已删除的节点/连线/消息已在当时移除，无需额外清理

---

## Mermaid 图按需加载策略

`画图规范.md` 约 1000 行，按需读取，不全文加载。按模板文件加载策略优先从工程级路径读取。

### 加载映射

| 模板章节 | 需要的图 | 读取规范的章节 |
|---------|---------|-------------|
| 2.2 系统结构 | 系统上下文图 / 软硬件拓扑图 | `## 四、系统上下文图` 或 `## 十四、软硬件拓扑图` |
| 2.2 系统结构 | 子系统上下文图 | `## 五、子系统上下文图` |
| 3.1.2 全局类关系图 | 类图 | `## 十三、类图`（连接线类型 + C++ 映射 + 示例） |
| 3.x.2 模块结构及依赖 | 模块结构及依赖图 | `## 六` / `## 七` / `## 八` |
| 3.x.3 类关系图 | 类图 | `## 十三、类图`（连接线类型 + C++ 映射 + 测量框架类图） |
| 3.x.5 核心流程说明 | 流程时序图（类） | `## 十二、流程时序图(类)` |
| 3.x.6 核心线程说明 | 线程图（模块内） | `## 十五、线程图`（模块内示例） |
| 4.1 跨模块线程说明 | 线程图（模块间） | `## 十五、线程图`（模块间示例） |
| 5. 接口设计 | 系统接口图 | `## 四、系统上下文图`（系统接口图变体） |
| 6.2 逻辑设计 | E-R 图 | `## 十七、E-R 图` |
| 7. 软件目录结构 | — | 不需要 mermaid |

### 加载规则

- 每章绘制前，搜索 `mermaid画图规范.md` 中对应的 `## 标题`，只读那一节到下一个 `##` 为止
- 通用规范（`## 一、通用规范`）在每个设计任务开始时读一次
- 不需要的图类型不加载

---

## 代码探查规则

1. **确定范围**：先和用户确认本次设计涉及哪些模块
2. **定位代码**：根据工程级模块索引找到每个模块的源码路径
3. **按需提取**：

| 目的 | 方法 |
|------|------|
| 接口描述 | 读 `.h` 的 public 方法签名 |
| 类关系 | 读 `.h` 的继承声明、成员指针、智能指针 |
| 核心流程 | 读 `.cpp` 关键函数的调用链 |
| 线程 | `grep` 搜索 `std::thread`、`pthread_create`、`std::async` |
| 缓存 | `grep` 搜索 `DataCache`、`m_cache`、`m_map` |
| 数据库 | `grep` 搜索 `CREATE TABLE`、`INSERT INTO`、`sqlite3` |
| 异常 | `grep` 搜索 `LOG_ERROR`、`try`、`catch` |

---

## 输出注意事项

1. **章节边界**：每输出一个 H2 或 H3 章节后，暂停，确认内容后再继续
2. **Mermaid 语法**：确保无语法错误——类名不含 `{`，箭头语法正确。正常生成的 sequenceDiagram 尽量不用 `box`/`rect` 着色；用于增量标记时，可用 `box rgb(255, 215, 0)` 高亮参与者、用 `rect rgb(255, 215, 0)` 包裹变更消息块
3. **交叉引用**：文内引用的章节编号必须与实际一致（如 `参见 3.1.1 命名规范`）
4. **TLDR**：全文档完成后，最后写 TLDR 一行概括
5. **占位符**：模板中 `{内容}`、`{类名}` 等占位符，生成时替换为实际内容；无法确定的内容保留占位符并标注 `<!-- 待确认 -->`
6. **表格完整性**：每个表格至少包含表头和一行示例数据，空表格标注为"暂无"