Write Design Doc

详细设计编写 Skill

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

模板文件

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

数据来源（输入）

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

仓库级输入

工程级输入

代码输入

输出位置

命名规范说明

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

枚举取值约束

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

置信度判定规则

低置信度项标注要求

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

性能指标三元组

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

接口运行语义

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

证据来源要求

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

分析设计原则

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

1. 证据优先原则

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

2. 可证伪原则

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

3. 不确定性显式化原则

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

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

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

5. 影响面前置原则

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

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

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

7. 可回滚优先原则

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

8. 性能守恒原则

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

9. 变更边界原则

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

10. 可追踪闭环原则

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

CRUD 分类规则

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

优先级

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

自动识别规则

自动识别过滤规则

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

多操作混合

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

置信度标注：

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

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

对生成的指导

识别出的 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> 标黄以突出显示。

示例：

**本轮变更说明**：

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

Mermaid 图变更标记

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

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

删除元素的处理

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

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

**本轮变更说明**：

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

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

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

本轮变更说明：

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

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

本轮变更说明：

清理步骤

写操作前执行：

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

Mermaid 图按需加载策略

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

加载映射

加载规则

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

代码探查规则

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

输出注意事项

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. 表格完整性：每个表格至少包含表头和一行示例数据，空表格标注为"暂无"