# Req Doc

> > 用于生成、撰写、创建、细化、审查或反向同步 SRS 需求规格说明书的技能。 触发场景：(1) "生成需求说明书" "写需求说明书" "创建需求文档" "需求文档" "SRS" "SRS需求" "需求规格说明书", (2) "细化需求" "补充需求" "完善需求说明书" "完善SRS", (3) "导出需求说明书" "需求说明书导出Word" "需求文档转Word" "SRS导出", (4) "根据代码更新需求" "反向更新需求说明书" "同步需求文档" "代码和需求对齐", (5) "审查需求说明书" "检查需求文档" "需求文档审查" "需求说明书有没有问题" "审查SRS", (6) "从Word生成模板" "导入需求模板" "提炼模板" "生成新模板" 或用户提供.docx路径并提到"模板", (7) 用户提供需求概述，需要输出详细规格说明时， (8) 用户需要细化现有需求说明书的特定章节时， (9) 用户需要将现有前端代码/页面同步回需求文档时， (10) "PRD转SRS" "PRD 转 SRS" "进开发" "转写需求" "按 PRD 写 SRS" "PRD 转需求说明书" 或仅有 PRD 却要 page-generator / 交付计划 / 概要设计时。 支持完整生成、局部完善、审查修复、从代码反向同步、从 Word 生成模板、**PRD→SRS 转写（Step F）**。

- Skill: `idwong/req-doc` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add idwong/req-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/idwong/req-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: iDWong (https://skillmd.com/u/idwong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/idwong/req-doc

---


> **⚠️ `.agents/` 是外部资源包路径，本机已不存在**（`Documents/Claude/Product/.agents/` 已删除）。
> 下文凡引用 `.agents/knowledge/`、`.agents/agents/`、`.agents/agent-memory/` 的地方**读不到文件**，
> 按以下降级处理，**不要因此中止**：
> - `.agents/knowledge/**`（内容规范、质量清单）→ 用本技能 `references/` 下的模板与检查表；两者都缺时按通用工程规范执行并在产出里标注「无内容规范可依」
> - `.agents/agents/*.md`（子 Agent 派发）→ 不派发，由当前会话直接执行该角色的工作
> - `.agents/agent-memory/**`（跨会话记忆）→ 跳过读写，改为在产出里写清本次的决定
> - `.agents/rules/prd-to-srs-gate.md` → **已迁到 `../common/prd-to-srs-gate.md`**（库内权威副本）

# SRS需求规格说明书生成器

## Agent 协作架构

```
req-doc skill（主流程：调度 + 文件写入）
  ├── req-analyzer agent（分析师）
  │     职责：读取设计文档/代码/已有需求，输出结构化功能摘要
  │     输出：字段表、业务规则、枚举值、依赖关系
  │
  ├── req-writer agent（撰写者）
  │     职责：摘要 + 规范 → 符合 PRD 语言的 Markdown 章节
  │     约束：只写"做什么"，不写技术实现，不写 UI 布局
  │
  ├── req-reviewer agent（审查者）
  │     职责：四维度独立审查（语言规范/章节结构/三要素/提示文案）
  │     时机：**按 AGENTS.md「交付模式」** — 标准模式下 A6 **抽检**（非全量）；严格模式全量审查
  │     → 汇总审查结果 → **P0 自动修复**；P1/P2 按模式决定是否询问用户
  │
  └── template-analyzer agent（模板提炼器）
        职责：分析已有需求说明书，提炼可复用模板
        输入：docling 转换后的 Markdown 全文
        输出：分析摘要 + 完整模板文件内容
        仅由 Step E（模板生成模式）调用
```

**审查策略（见 `AGENTS.md`「交付模式」；**本技能未声明时默认「标准」**）：

| 模式 | A6 / B6 / C / D 审查 | 修复 |
| --- | --- | --- |
| **标准**（默认） | 结构性章节主流程对照模板；3.5.x **抽检** req-reviewer（见 A6） | **P0 自动修**；P1/P2 汇总后 **问一次**「是否一并修复 P1？」 |
| **严格** | 全部 3.5.x 并行 req-reviewer | P0/P1/P2 均展示报告后等用户确认再修 |
| **快速** | 仅结构性检查 + 禁用词 grep（不调用 req-reviewer） | P0 自动修；P1/P2 仅列表，不主动修 |

**生成模式写入阶段（A5）仍不穿插 reviewer**；审查集中在 A6 一次完成。

**分组并行策略**：若需要生成多个功能模块，按以下规则分组执行：

1. **analyzer 阶段**：将所有功能模块按 2-3 个一组，同组内并行调用 `req-analyzer`，组间串行
2. **writer 阶段**：每组 analyzer 完成后，同组内并行调用 `req-writer`（**writer 后不跑 reviewer**）
3. **文件写入阶段**：同组写入完成后，按章节编号顺序串行追加到文档

**分组示例（6个模块）：**
- 第1组：模块A、模块B、模块C → 并行 analyzer → 并行 writer → 各自串行 reviewer → 串行写入
- 第2组：模块D、模块E、模块F → 同上
- 两组之间串行，不跨组并行

---

## 工作模式

| 模式 | 触发场景 | 入口 |
| --- | --- | --- |
| **生成模式** | 从零生成SRS需求规格说明书 | → Step A |
| **反向同步模式** | 根据已有前端代码更新SRS需求规格说明书 | → Step B |
| **局部完善模式** | 补充或修改某个章节 | → Step C |
| **审查修复模式** | 审查已有SRS需求规格说明书，找出问题并修复 | → Step D |
| **模板生成模式** | 从已有Word需求说明书提炼新模板 | → Step E |
| **PRD 转 SRS 模式** | 已有 PRD，进研发前转写为 SRS 真源 | → Step F |

> **门禁**：研发类技能（`page-generator` 等）无 SRS 时须先 Step F。规则见 `../common/prd-to-srs-gate.md`。

---

## Step A: 生成模式

### A1: 扫描项目上下文

先主动扫描项目，找到已有文档再开始工作：

| 优先级 | 文件类型 | 查找方式 |
| --- | --- | --- |
| 最高 | SRS需求规格说明书 | `Glob("**/*需求*说明书*.md")` |
| 高 | 设计方案 | `Glob("**/*设计*方案*.md")` |
| 低 | 路由/代码 | `src/router/`, `src/views/`, `src/api/` |

### A2: 读取模板

读取 `references/templates/requirements-spec.md`，严格按照模板中每个章节的内容要求生成文档。

### A3: 收集信息

**必须收集：** 项目名称、项目背景和目标、核心功能模块列表、目标用户群体

**按需询问：** 系统类型（Web/移动端/多端）、特殊业务规则

**术语表冷启动检查：**

检查 `.agents/agent-memory/req-writer/` 目录是否存在项目术语表文件：
- 若存在 → 读取并在 A4 任务清单中注明"已有术语表，analyzer 将复用"
- 若不存在 → 在任务清单第一个 [Agent] 任务备注"首次运行，analyzer 将初始化术语表"，并在第一组 analyzer 全部完成后，主流程汇总各 analyzer 输出的术语，写入 `.agents/agent-memory/req-writer/project-{项目名}-terminology.md`，后续各组 analyzer 直接读取复用

### A4: 生成任务清单

**必须先展示任务清单，再逐个生成，禁止一次性写入整个文档。**

任务拆分原则：**每个功能模块（3.5.x）是一个独立任务，非详细设计章节（文档信息、项目概述、功能清单等）也各自独立。**

**[Agent] 任务分组规则：每 2-3 个功能模块为一组，同组并行 analyzer → 同组并行 writer → 串行写入。**

任务清单示例：
```
| 序号 | 任务名称 | 类型 | 分组 | 状态 |
|------|---------|------|------|------|
| 1  | 文档信息 + 项目概述 | [文档] | - | [ ] 等待中 |
| 2  | 生成业务流程图 | [图表] | - | [ ] 等待中 |
| 3  | 3.1 总体功能架构 | [文档] | - | [ ] 等待中 |
| 4  | 生成系统架构图 | [图表] | - | [ ] 等待中 |
| 5  | 3.2 需求功能清单 | [文档] | - | [ ] 等待中 |
| 6  | 3.3 页面功能清单 | [文档] | - | [ ] 等待中 |
| 7  | 3.4 页面访问权限 | [文档] | - | [ ] 等待中 |
| 8  | 生成首页+数据看板+基础档案 操作流程图+时序图 | [图表] | 第1组 | [ ] 等待中 |
| 9  | 3.5.1 首页 | [Agent] | 第1组 | [ ] 等待中 |
| 10 | 3.5.2 数据看板 | [Agent] | 第1组 | [ ] 等待中 |
| 11 | 3.5.3.1 基础档案 | [Agent] | 第1组 | [ ] 等待中 |
| 12 | 生成供应商管理+用户管理+任务计划 操作流程图+时序图 | [图表] | 第2组 | [ ] 等待中 |
| 13 | 3.5.3.2 供应商管理 | [Agent] | 第2组 | [ ] 等待中 |
| 14 | 3.5.4 用户管理 | [Agent] | 第2组 | [ ] 等待中 |
| 15 | 3.5.5 任务计划 | [Agent] | 第2组 | [ ] 等待中 |
...
```

**关键规则：**
- 每个 [Agent] 任务之前必须有对应的 [图表] 任务，同组的图表任务合并为一个批次
- [图表] 任务完成后将图片路径记录在备注列，[Agent] 任务执行时从备注列读取路径传给 req-writer
- 同组 [Agent] 任务的 analyzer 阶段并行，writer 阶段并行，文件写入按编号顺序串行

状态标识：[ ] 等待中 → [进行中] → [完成]

**类型说明：**
- [文档]：主流程直接写（文档信息、概述、功能清单等结构性章节）
- [图表]：调用 `diagram-generator` 技能生成
- [Agent]：调用 analyzer → writer → reviewer 流程生成（所有 3.5.x 功能详细设计）

### A5: 执行任务

**执行规则：**
1. [文档] 和 [图表] 类任务：每次只执行一个，执行前更新为 [进行中]，完成后更新为 [完成]
2. [Agent] 类任务：按分组执行，同组内并行 analyzer → 并行 writer → 串行写入
3. 第一个任务用 Write 创建文件，后续用 Edit 追加
4. 每次写入不超过 150 行

**[文档] 类任务执行方式（主流程直接写）：**

直接按模板写入，无需调用 agent。

**[图表] 类任务执行方式：**

同组的图表任务合并为一个批次调用 `diagram-generator` 技能，获取所有图片路径后记录在任务清单备注中，供后续 [Agent] 任务使用。

**[Agent] 类任务执行方式（分组并行）：**

每组功能模块按以下流程执行：

```
Phase 1 — 并行 analyzer（同组所有模块同时启动）
  对组内每个模块，并行调用 req-analyzer：
    subagent_type: "req-analyzer"
    传入：
      PROJECT_PATH: {项目根目录}
      FEATURE_NAME: {功能名称}
      MODE: from_design 或 from_code
      SOURCE_PATH: {设计文档路径 或 src/ 目录}
  等待组内所有 analyzer 完成后进入 Phase 2

Phase 2 — 并行 writer（同组所有模块同时启动）
  对组内每个模块，并行调用 req-writer：
    subagent_type: "req-writer"
    传入：
      PROJECT_PATH: {项目根目录}
      FEATURE_NAME: {功能名称}
      SECTION_NUMBER: {章节编号}
      功能摘要: {对应模块的 req-analyzer 输出}
      DIAGRAM_PATHS: {对应 [图表] 任务已生成的图片路径}
  等待组内所有 writer 完成后进入 Phase 3

Phase 3 — 串行写入（按章节编号顺序）
  对组内每个模块，按编号顺序用 Edit 工具追加到文档
  每次写入后验证：grep 章节标题确认写入正确
```

**注意：** writer 阶段不运行 reviewer。同组全部写入完成后，在 **A6** 统一审查（按交付模式）。

**注意：** diagram-generator 是技能（Skill），不是 agent，无法在 agent 协作流程中间调用。流程图必须作为独立的 [图表] 类任务，在对应 [Agent] 任务之前完成，再将图片路径传给 req-writer。

### A6: 审查与修复（精简）

所有任务写入完成后，**一次**进入审查。读取 `AGENTS.md`「交付模式」；**本技能未声明时默认「标准」**。

#### 第一步：结构性检查（所有模式必做）

主流程对照 `requirements-spec.md` 检查：

- 文档信息、概述、3.1–3.4 结构完整
- 3.2 功能清单 ↔ 3.3 页面清单 ↔ 3.5.x 章节 **数量与命名一致**
- 权限矩阵覆盖 3.3 页面

#### 第二步：3.5.x 深度审查（按模式）

| 模式 | 动作 |
| --- | --- |
| **快速** | 跳过 req-reviewer；对本次新增/变更段落做 **禁用词 grep**（见 `req-doc-workflow.md`） |
| **标准** | 对 3.5.x **抽检**：`max(2, ceil(模块数 × 20%))` 个模块并行 req-reviewer；优先抽 **首个、中间、末尾** 模块 |
| **严格** | **全部** 3.5.x 按 2–3 个一组并行 req-reviewer |

```
subagent_type: "req-reviewer"
传入：
  PROJECT_PATH: {项目根目录}
  FEATURE_NAME: {功能名称}
  章节内容: {从文档中读取的对应章节内容}
  REVIEW_MODE: standard | strict   # 传入当前模式，reviewer 只输出 P0/P1/P2 列表
```

#### 第三步：汇总报告

```
## 审查报告

### P0（已自动修复 / 待自动修复）
- [章节] 问题 → 处理状态

### P1（可选修复）
- [章节] 问题 → 修复方案

### P2（建议优化）
- [章节] 问题 → 修复方案

---
共 N 项（P0: x，P1: y，P2: z）
```

无问题 → 「✅ 审查通过」，更新版本号（若需要）后结束。

#### 第四步：修复（减少确认轮次）

| 优先级 | 标准模式 | 严格模式 | 快速模式 |
| --- | --- | --- | --- |
| **P0** | **自动修复**，修完简报 | 展示后等用户确认再修 | 自动修复 |
| **P1** | 报告末尾 **问一次**：「是否一并修复 P1（共 y 项）？」默认 **否** | 与 P0 一起等用户确认 | 仅列表，不主动修 |
| **P2** | 仅列表，不主动修 | 仅列表，用户点名再修 | 仅列表 |

**禁止**：P0 存在时仍等待用户说「可以修复」；**禁止** P1 每一项单独问一次。

修复方式（同原规则）：

- [Agent 重写]：问题数 ≥ 2，或涉及结构/三要素 → analyzer(from_existing) → req-writer → **最多 1 次** req-reviewer 复审
- [主流程修正]：单点文案/格式 → 直接 Edit

全部 P0（及用户确认的 P1）修完后，更新版本号（+0.1）、重命名文件（日期+版本），输出修复汇总。

---

## Step B: 反向同步模式

**触发场景：** 前端功能已实现，需要将实际功能同步回SRS需求规格说明书。

**核心原则：全文档对齐，不是只更新功能详细设计。** 需求说明书中任何引用了功能模块的地方（功能清单、页面清单、权限矩阵、架构描述、流程图、项目范围……）都必须与代码现状保持一致。

### B1: 双向全面分析

同时分析两个信息源，建立完整的对照关系：

**第一步：分析代码现状（提取"代码中实际有什么"）**

**判定规则 — 路由注册表是唯一真相源：**

```
功能是否存在的判定标准：路由是否注册（router/modules/index.ts 或对应入口文件中是否 import 并导出）

- 路由已注册 → 功能存在，纳入需求说明书
- 路由未注册（即使 view 文件、mock 文件、api 文件仍残留在目录中）→ 功能不存在，需求说明书中必须删除

常见残留情况（均视为"功能已删除"）：
- src/views/Xxx/ 目录存在，但 router/modules/ 中无对应路由文件
- router/modules/xxx.ts 文件存在，但未在 index.ts 中注册（未 import/未导出）
- src/api/xxx.ts、src/mock/xxx.ts 存在，但对应路由已删除

不要被残留文件误导。只看路由注册表。
```

扫描项目代码，提取以下信息：

```
1. 路由注册表：读取 router/modules/index.ts（或等效入口），确认哪些路由模块被实际注册
   → 只有被注册的路由才算"功能存在"
   → 输出：实际存在的页面列表（路径、名称、所属模块）

2. 对照 src/views/ 目录：识别哪些 view 目录有对应路由（活跃），哪些没有（残留/死代码）
   → 残留目录不计入功能列表

3. API 接口：扫描 src/api/ 目录，交叉验证是否被活跃页面引用
   → 输出：实际在用的接口模块列表

4. 若有多端（admin + mobile），每端独立扫描，各自以自己的路由注册表为准
```

**第二步：分析现有需求说明书（提取"文档中写了什么"）**

逐章读取 SRS 全文，提取以下信息：

```
1. 2.3 项目范围 → 文档中声称的功能范围
2. 3.1 总体功能架构 → 文档中描述的模块结构
3. 3.2 需求功能清单 → 文档中列出的所有功能编号和名称
3. 3.3 页面功能清单 → 文档中列出的所有页面路径和名称
4. 3.4 页面访问权限 → 文档中列出的权限矩阵
5. 3.5.x 功能详细设计 → 文档中有哪些功能模块的详细设计章节
6. 流程图/时序图 → 文档中引用的图表及其描述的流程节点
```

### B2: 生成全文差异清单

将 B1 两步的结果交叉对比，**逐章节**生成差异：

```
## 全文差异清单

### 一、模块级差异（影响多个章节）

| 差异 | 模块名 | 影响章节 |
|------|-------|---------|
| 代码已删除，文档仍存在 | 报表统计 | 3.2、3.3、3.4、3.5.x、流程图 |
| 代码已删除，文档仍存在 | 消息通知 | 3.2、3.3、3.4、3.5.x |
| 代码新增，文档中缺失 | 移动端首页 | 3.2、3.3、3.5.x |

### 二、逐章节差异明细

#### 3.2 需求功能清单
- [ ] 删除：「报表统计」相关行（第xx行）
- [ ] 删除：「消息通知」相关行（第xx行）
- [ ] 新增：「移动端首页」功能行

#### 3.3 页面功能清单
- [ ] 删除：/report/* 相关行
- [ ] 新增：/mobile/home 页面行

#### 3.4 页面访问权限
- [ ] 删除：报表统计相关权限行

#### 3.1 总体功能架构
- [ ] 更新架构描述，移除已删除模块，补充新增模块

#### 2.3 项目范围
- [ ] 更新功能范围描述

#### 3.5.x 功能详细设计
- [ ] 删除：3.5.x 报表统计 整章
- [ ] 更新：3.5.x 订单管理（字段变更）
- [ ] 新增：3.5.x 移动端首页

#### 流程图/架构图
- [ ] 重新生成：主业务流程图（包含已删除节点）
- [ ] 重新生成：系统架构图（模块结构变更）
```

### B3: 功能模块深度分析

对 B2 中标记为"需要更新"或"需要新增"的 3.5.x 功能模块，按 2-3 个一组并行调用 `req-analyzer`：

```
subagent_type: "req-analyzer"
传入：
  PROJECT_PATH: {项目根目录}
  FEATURE_NAME: {功能名称}
  MODE: from_code
  SOURCE_PATH: {对应子项目的 src/ 目录，如 admin/src/ 或 mobile/src/}
```

**关键：analyzer 会自动从路由文件出发，逐层定位并完整读取所有相关文件（view → components → api → mock），不需要主流程预先列出文件清单。但主流程必须确保 SOURCE_PATH 指向正确的子项目目录。**

**主流程在调用前的准备工作：**
1. 确认该功能模块对应的路由文件路径（从 B1 的路由扫描结果中获取）
2. 在 prompt 中补充提示：`该功能对应路由文件为 {路由文件路径}，请从此文件开始逐层分析`

**代码质量评估：** analyzer 完成后，检查摘要中的自检结果。若某模块摘要中：
- 筛选字段数 + 列表列数 + 表单字段数 合计 < 5 → 标记为"代码信息不足"
- 自检结果中有"✗"标记 → 要求 analyzer 重新读取对应文件补充

对"代码信息不足"的模块，在差异清单中标注 ⚠️，提示用户该模块需要人工补充，不自动写入 SRS。

### B4: 展示差异清单，用户确认

将 B2 的全文差异清单展示给用户，等待确认后再执行更新。用户可以：
- 确认全部更新
- 排除某些项（如"这个模块先不删，后面还要加回来"）
- 调整优先级

### B5: 执行更新

用户确认后，按以下顺序执行（先结构后内容，先删后增）：

```
Phase 1 — 删除已移除内容（主流程直接 Edit）
  1. 3.5.x 中已删除模块的整章删除
  2. 3.2 需求功能清单中删除对应行
  3. 3.3 页面功能清单中删除对应行
  4. 3.4 页面访问权限中删除对应行
  5. 3.1 总体功能架构中移除已删除模块描述
  6. 2.3 项目范围中更新描述

Phase 2 — 更新/新增结构性章节（主流程直接 Edit）
  1. 3.2 补充新增功能行
  2. 3.3 补充新增页面行
  3. 3.4 补充新增权限行
  4. 3.1 更新架构描述

Phase 3 — 更新/新增 3.5.x 功能详细设计（调用 req-writer）
  对每个需要更新或新增的模块，调用 req-writer 生成内容并写入

Phase 4 — 重新生成图表（调用 diagram-generator）
  对标记需要重新生成的流程图/架构图，调用 diagram-generator
```

### B6: 审查

所有更新完成后，**按 A6 相同策略**（交付模式 + 抽检 + P0 自动修）执行审查与修复；变更模块纳入抽检样本。修复完成后更新历史版本表格，重命名文件。

---

## Step C: 局部完善模式

1. 读取现有SRS需求规格说明书对应章节
2. 调用 `req-analyzer`（MODE: from_existing）分析现有内容，识别缺失和问题
3. 调用 `req-writer` 补充/改写，生成新章节内容
4. 用 Edit 工具将新内容写入文件
5. **按 A6 策略**审查变更范围（标准模式：变更章节 + 关联结构性交叉检查；快速模式：grep 即可）
6. P0 自动修复；P1 **问一次**是否一并修复
7. 修复完成后更新文档版本号

---

## Step D: 审查修复模式

### D1: 扫描文档

找到SRS需求规格说明书：`Glob("**/*需求*说明书*.md")`

### D2: 生成审查任务清单

**先展示审查任务清单，再逐章审查，禁止一次性完成所有审查。**

审查任务清单示例：
```
| 序号 | 审查项 | 类型 | 状态 |
|------|-------|------|------|
| 1  | 一、文档信息 | [主流程] | [ ] 等待中 |
| 2  | 二、项目概述（2.1-2.5） | [主流程] | [ ] 等待中 |
| 3  | 三、3.1-3.4 结构性章节 | [主流程] | [ ] 等待中 |
| 4  | 三、3.5.1 首页 | [Agent] | [ ] 等待中 |
| 5  | 三、3.5.2 数据看板 | [Agent] | [ ] 等待中 |
| 6  | 三、3.5.3.1 基础档案 | [Agent] | [ ] 等待中 |
...
```

### D3: 逐章审查

- **结构性章节**：主流程对照模板检查
- **3.5.x**：按交付模式 — **严格** 全量 req-reviewer；**标准** 仅审查 D2 清单中标记 `[Agent]` 的章节（用户点名审查时可全量）；**快速** 跳过 reviewer，grep 禁用词

### D4: 汇总报告与修复

汇总 P0/P1/P2 报告。**P0 自动修复**（标准/快速/严格均适用）。

- **标准**：P1 问一次「是否一并修复？」；用户说「只审查不修复」则停
- **严格**：P0 修完后，P1/P2 展示报告并等用户确认再修
- **快速**：只输出列表

修复流程同 A6 第四步。D3 的问题清单保留至 D6，修复时传给 req-writer，**每章最多 1 次** reviewer 复审。

### D5: 生成修复任务清单并执行

**用户确认修复后**，将所有 ❌ 问题按章节归组，生成修复任务清单并展示，然后逐项执行：

```
| 序号 | 修复项 | 问题数 | 修复方式 | 状态 |
|------|-------|-------|---------|------|
| 1  | 3.5.3.1 基础档案 | 3个问题 | [Agent 重写] | [ ] 等待中 |
| 2  | 3.5.3.3 供应商管理 | 5个问题 | [Agent 重写] | [ ] 等待中 |
| 3  | 3.3 页面功能清单 | 1个问题 | [主流程修正] | [ ] 等待中 |
```

**修复方式判断：**
- [Agent 重写]：问题数 >= 2，或涉及语言规范/章节结构/三要素缺失 → 整章重写
- [主流程修正]：问题数 = 1，且是局部文案/格式问题 → 直接 Edit 修改

**关键：D3 审查时每章的问题清单必须保留在上下文中，D6 修复时直接传给 req-writer 和 req-reviewer，不需要重新审查。**

### D6: 逐项执行修复

每次只修复一个任务，执行前更新为 [进行中]，完成后更新为 [完成]，立即开始下一个。

**[Agent 重写] 流程（整章重写）：**

```
Step 1: 调用 req-analyzer（MODE: from_existing）
  传入：
    PROJECT_PATH: {项目根目录}
    FEATURE_NAME: {功能名称}
    MODE: from_existing
    SOURCE_PATH: {SRS需求规格说明书路径}
  作用：提取现有章节中可复用的内容，同时标注哪些需要改写

Step 2: 调用 req-writer
  传入：
    PROJECT_PATH: {项目根目录}
    FEATURE_NAME: {功能名称}
    SECTION_NUMBER: {章节编号}
    功能摘要: {req-analyzer 的输出}
    审查报告: {D3 中该章节的问题清单，原文传入，不要省略}
    DIAGRAM_PATHS: {已有流程图路径，无需重新生成}

Step 3: 调用 req-reviewer 复审
  传入：
    PROJECT_PATH: {项目根目录}
    FEATURE_NAME: {功能名称}
    章节内容: {req-writer 的输出}
    原始问题清单: {D3 中该章节的 ❌ 问题列表，原文传入}

Step 4: 处理复审结果
  - 全部通过 → 进入 Step 5
  - 仍有 ❌ → 再次调用 req-writer 修正（最多重试1次）
    仍未通过 → 写入文件并在文档末尾附注"待人工复查：[问题描述]"

Step 5: 替换文档中的对应章节
  用 Bash grep 定位该章节的起止行号
  按 AGENTS.md 编码底线与 `.agents/rules/` 中的写入规范执行分块替换（占位符接力法）
  替换后验证：grep 章节标题确认新结构正确
```

**[主流程修正] 流程（局部修改）：**

```
直接用 Edit 工具修改对应行（仅适用于 ≤ 20 行的局部修改）
修改后 Read 验证内容正确
```

### D7: 修复完成后更新文档版本

所有修复任务完成后：
1. 更新文档历史版本表格（版本号 +0.1，说明"审查修复：修正 N 处规范问题"）
2. **重命名文件**：将文件名中的日期和版本号同步更新，使用 Bash `mv` 命令：
```bash
mv "旧文件路径" "{新日期YYYYMMDD}-{客户名称}{项目名称}-SRS需求规格说明书-V{新版本号}.md"
```
例如：`mv .../20260518-...-V1.0.md .../20260519-...-V1.1.md`
- 日期取当天日期（`date +%Y%m%d`）
  - 版本号 +0.1
1. 汇总输出修复结果：

```
## 修复完成

共修复 N 个章节，M 个问题：
✅ 3.5.3.1 基础档案 — 修复3个问题（语言规范2个、提示文案1个）
✅ 3.5.3.3 供应商管理 — 修复5个问题（章节结构缺失3个、三要素2个）
✅ 3.3 页面功能清单 — 修复1个问题（格式）

文档版本已更新至 V{x.x}
```

---

## Step E: 模板生成模式

**触发场景：** 用户提供一个已有需求说明书的 Word 文件，希望从中提炼出新的可复用模板。

**触发词：** "从Word生成模板"、"导入需求模板"、"提炼模板"、"生成新模板"、用户消息中包含 `.docx` 路径且提到"模板"

### E1: 收集信息

询问用户：
1. `.docx` 文件的完整路径
2. 新模板的名称（如"政府项目模板"、"SaaS产品模板"）
3. 简短描述这份 Word 文档的项目类型（可选，帮助提高分析精度）

### E2: 转换 Word 文档

检测 docling 是否可用：

```bash
# 检测 docling
docling --version 2>/dev/null && echo "docling可用" || echo "docling不可用"
```

**若 docling 可用：**
```bash
docling {docx路径} --to md --output /tmp/req-template-source.md
```

**若 docling 不可用，降级到 pandoc：**
```bash
pandoc {docx路径} -o /tmp/req-template-source.md --wrap=none 2>/dev/null && echo "pandoc成功" || echo "pandoc不可用"
```

**若两者都不可用，降级到解压 XML：**
```bash
unzip -p {docx路径} word/document.xml > /tmp/req-doc-raw.xml
# 提示用户安装 docling 以获得更好的转换质量
```

转换完成后，读取 `/tmp/req-template-source.md` 的内容。

### E3: 调用 template-analyzer

```
subagent_type: "template-analyzer"
传入：
  CONVERTED_CONTENT: {E2 转换后的完整 Markdown 内容}
  TEMPLATE_NAME: {用户提供的模板名称}
  PROJECT_PATH: {项目根目录}
```

### E4: 写入模板文件

将 template-analyzer 的输出直接写入：

```
{PROJECT_PATH}/../req-doc/references/templates/{模板文件名}.md
```

**模板文件命名规则：**
- 去掉"模板"二字，转为小写英文 + 连字符
- 示例：
  - "政府项目模板" → `requirements-spec-gov.md`
  - "SaaS产品模板" → `requirements-spec-saas.md`
  - "移动端模板" → `requirements-spec-mobile.md`

写入后验证：读取文件前 10 行，确认标题和"写作前必读"章节存在。

### E5: 更新模板选择逻辑

检查 `references/templates/` 下是否有多个模板文件：
```bash
ls {PROJECT_PATH}/../req-doc/references/templates/*.md
```

若有多个模板，在 A3 收集信息时列出所有可用模板，让用户选择：

```
当前可用模板：
1. requirements-spec.md — 默认模板（通用）
2. requirements-spec-gov.md — 政府项目模板
3. requirements-spec-saas.md — SaaS产品模板

请选择本次使用的模板（默认：1）：
```

用户选择后，A2 读取对应模板文件，后续 req-writer 按所选模板的规范生成内容。

### E6: 完成提示

```
✅ 模板生成完成

模板名称：{TEMPLATE_NAME}
文件路径：references/templates/{文件名}.md

下次生成需求说明书时，在 A3 步骤选择此模板即可。
```

---

## Step F: PRD → SRS 转写模式

**触发**（任一命中）：

- 用户说「PRD 转 SRS」「进开发」「转写需求」「按 PRD 写 SRS」
- 下游技能门禁阻断（见 `../common/prd-to-srs-gate.md` §3）
- `pm-master` 阶段 **7C**（见 `pm-master/references/stages/s7-spec.md`）
- `prd-writer` / `prototype-to-prd` 交付后用户要开发

**禁止**：未 Read PRD 全文就写 3.5；把 PRD 的 UI/API 术语原样抄进 SRS。

### F0: 门禁与输入确认

1. Read `../common/prd-to-srs-gate.md` 与 `references/prd-to-srs-handoff.md`
2. 扫描 PRD **落地版**：`Glob("prd/PRD/*-产品需求文档-V*.md")`；未命中再 `Glob("prd/PRD/*-PRD.md")`、`Glob("docs/**/*-PRD.md")`（兼容旧命名与旧路径）；登记 `PRD_SOURCE`。
   **概念版／评审／原型盘点不能当转写源**——它们只在下一条作补充材料；只找到这三类时按「无落地版 PRD」中止并说明
3. 可选补充：`Glob("prd/PRD/*-概念版-V*.md")`、`Glob("prd/PRD/*-原型盘点-V*.md")`（旧命名 `prd/PRD/*-概念版.md` / `prd/PRD/*-原型盘点.md`，旧路径 `docs/*-概念版.md` / `docs/*-原型盘点.md`）
4. 执行 `references/prd-to-srs-handoff.md` **转写前检查**；不通过则中止并说明
5. 扫描是否已有 SRS：若已有且用户未要求覆盖 → 转 **Step C** 增量同步，或询问覆盖/新建版本

### F1: 转写范围确认

确定本期转写范围——**先判上游结构**（见 `references/prd-to-srs-handoff.md`「两种上游 PRD」）：

- `prd-writer` / `prototype-to-prd` 结构 → 从 PRD **§4** 提取 🔴 / MVP / V1.0 模块列表
- `pm-prd-spec` 结构（功能域/页面，**通常没有 🔴**）→ 依次取：页面清单表的优先级列 →
  `prd/planning/roadmap-*.md` 的 V1.0 范围 → **都没有就列出全部功能域与页面问用户一次**。
  **不要因为找不到 §4 或 🔴 就中止**，那只是结构不同，不是 PRD 不合格。

输出：

```text
PRD → SRS 转写计划
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
来源 PRD：{路径}
本期转写模块（{N} 个）：[模块1, 模块2, ...]
暂不展开：[...]（`prd-writer` 结构写 🟡⚪；`pm-prd-spec` 结构写「本期范围外」）
输出路径：dev/SRS/{日期}-{项目}-SRS需求规格说明书-V1.0.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**标准/快速**：默认继续，不等待确认。**严格**：等用户确认模块列表后再写。

### F2: 执行转写（复用 Step A 流水线）

与 Step A 相同任务清单结构，差异如下：

| 步骤 | 说明 |
| --- | --- |
| A1 上下文 | 以 `PRD_SOURCE` 为最高优先级输入 |
| A2 模板 | 同 Step A |
| A3 信息 | 从 PRD §1–§2 提取，缺的再问 |
| A4 任务清单 | 每个 🔴 模块一个 3.5.x [Agent] 任务 |
| A5 执行 | analyzer 传 `MODE: from_prd`、`SOURCE_PATH: {PRD}` |
| 文首 | 按 `prd-to-srs-handoff.md` 写来源 PRD 元数据 |

**3.1 / 3.2 / 3.3 / 6.1**：主流程按对照表从 PRD §4 / §5 展开，不得留空。

### F3: 审查与出口（A6 同等）

按当前 `DELIVERY_MODE` 执行 Step A6 审查策略；转写完成后对照 `../common/prd-to-srs-gate.md` **§5 七项出口检查**。

### F4: 登记与交接

```text
✅ PRD → SRS 转写完成

来源 PRD：{PRD_SOURCE}
SRS 真源：{SRS路径}
SPEC_SOURCE 已更新

下一步：/task-breakdown 拆任务（三源缺口 + 任务包 + 看板），或 /page-generator 实现{首个模块}
```

会话登记：**`SPEC_SOURCE={SRS路径}`**（覆盖 PRD 登记）。

**要设计稿（可点 HTML，不是工程页面）时**：**转 `pm-master` 的阶段 8**——设计稿只在产品链产出，
研发链不出稿（`dev-master` 阶段 6 只接手已有的稿）。那一阶段调 `ui-ux-pro-max`
（设计侧只此一个技能，材质与层级已并入），细则以它的交付契约为准：
读 PRD+SRS 全文（**设计稿内容以 PRD 为主真源**，
SRS 只补 PRD 未写明的规格细节；研发交付真源仍是 SRS）、落 `design-system/`、
**共三张 iframe 预览墙**（移动墙：APP / H5 / 小程序 共用一张 393×852，卡片按形态分组；官网墙 1280×900；后台墙 1440×900）、
点预览卡即进全屏、墙内不注入工具条、全屏页右下角需求标注开关与「重置演示进度」；**不做出稿帧**，交付的是完整流程的动态交互设计稿（所有状态与分支靠真实操作走到）+ `FLOWS.md` 流程清单 + `HANDOFF.md` 工程师对接清单。

---

### Word 导出

**默认不导，也不要主动问（用户明确开口才导）**

**SRS 的默认交付物只有 md，不生成 docx。** SRS 落盘（Step A / C / F 任一出口）后直接进交付说明，
**不要停下来问**"要不要导 Word"——交付说明里一句话带过就够：

```
SRS 已落盘：dev/SRS/20260411-PM能源科技智慧厂区巡检平台-SRS需求规格说明书-V1.0.md
（本次交付为 md；需要 Word 评审稿说一声，随时可补导。）
```

**唯一开导情形**：用户在对话里**原话开口**要 Word / 要 docx / 要评审稿文件，
或直接以「导出需求说明书」「需求说明书导出Word」「SRS导出」这类说法触发本技能——这本身就是明确要求，直接导。
除此之外一律不导——"看起来要评审""顺手导一份更稳妥"这类自行判断**不算**用户要求。

**禁止**：把导出当默认收尾动作；用"顺手导了一份"代替用户的明确要求；
反过来追着问"要不要导 Word"。

**与 PRD 口径一致**：由 `pm-prd-spec` 出 PRD 后再走 Step F 转 SRS 时，两边都默认只交 md、都不问——
`pm-prd-spec` 的「Word 导出」小节已同步改成同一条规则。

导出能力本身保留，**用户明确要求后**才执行：

**Windows（PowerShell，需 Python 3）：**

```powershell
../common/export-word.ps1 <markdown文件路径> req-doc
```

**Git Bash / Linux / macOS / Python：**

```bash
python ../common/export-word.py <markdown文件路径> req-doc
# 或
bash ../common/export-word.sh <markdown文件路径> req-doc
```

> 更多模板见 `../common/README.md`。

**导出后必须验证图片真的嵌进去了**——导出接口对非 ASCII 图片文件名会**静默丢图**（照样打印 `Found N local image(s)` 和 `Export succeeded`，但 docx 里只有空图框）：

```bash
unzip -l "<导出的.docx>" | grep -c "word/media/"
```

数字必须等于文档里的图片张数（流程图/时序图/ER 图等）。为 0 就是丢了。

**丢图的原因不止文件名**——2026-09-10 实测：只有 `images/<纯ASCII名>.png`（**与文档同级的 `images/` 子目录**）
能嵌入；`img/`、`images/sub/`、`assets/img/`、`../images/`、与文档同目录、中文文件名**全部丢图**。
图片在别处就**先拷进「与本文档同级的 `images/`」**再引用——SRS 落在 `dev/SRS/`，所以是 `dev/SRS/images/`，
**不是某个集中的 `images/`**——图片必须与文档同级。调 `diagram-generator` 渲图时直接指定 `dev/SRS/images/`。
完整实测边界表见 `../common/README.md`。

## 文档命名规范

`dev/SRS/{日期}-{客户名称}{项目名称}-SRS需求规格说明书-V{版本号}.md`

**SRS 一律落 `dev/SRS/`**（目录不存在先 `mkdir -p dev/SRS`）；PRD 落 `prd/PRD/`，两者分目录归档，不要混放。

示例：`dev/SRS/20260411-PM能源科技智慧厂区巡检平台-SRS需求规格说明书-V1.0.md`

**修订：就地改也要改文件名。** **不论体量大小一律就地 `Edit` 改**（大文档尤其别整份重写，小文档也不要另存新文件）——**目录里永远只留最高版本那一份**；改完必须三样一起动——文首「文档版本」、版本记录表、**`mv` 把文件名的版本号也改掉**（局部修订 `+0.1`，结构性重写进大版本；日期取改动当天）。**绝不允许内容已是 V1.1、文件名还写 V1.0。**改名后 `grep` 一遍旧名，把 README 清单、下游「来源」行、`tools/` 脚本里的引用一并改掉。完整规则见 `../common/README.md`。

### 交付包 README：`dev/README-SRS.md`，不准用裸 `README.md`，也不要落项目根

一份交付包里 PRD 与 SRS 两条链路各写一份 README，必须带**文档类型后缀**区分，否则后写的会覆盖先写的：

| 谁写 | 文件名 | 内容 |
| --- | --- | --- |
| 本技能（SRS 链路） | `dev/README-SRS.md` | SRS 清单（文档名 / 覆盖模块 / 版本）、章节与规格真源说明、图表来源（`diagram-generator` 产物与 draw.io 源）、与 PRD 的对应关系、Word 导出状态（默认「未导出」） |
| `pm-prd-spec`（PRD 链路） | `prd/README-PRD.md` | PRD 清单、原型图与脚本位置、下游路由 |

**两份 README 各跟自己那条链路的目录走，项目根不再放它们**：PRD 在 `prd/PRD/`，它的 README 就在 `prd/`；
SRS 在 `dev/SRS/`，它的 README 就在 `dev/`。这样 `prd/` 与 `dev/` 各自是一个能整包搬走的交付物，
项目根只留项目自己的东西（`design-system/`、`tools/` 与两条链路的目录）。
**老项目里那两份还躺在项目根的**，下次改动时 `mv` 到新位置并 `grep` 改掉指向它的行，别两处各留一份。


多份 SRS **合写一份 `dev/README-SRS.md`**，用表格分行；已存在时**增量更新**对应行，不要整篇覆盖。

## 参考资源

| 资源 | 路径 | 用途 |
| --- | --- | --- |
| SRS需求规格说明书模板（默认） | `references/templates/requirements-spec.md` | 通用模板，文档结构和章节规范 |
| 其他模板（用户生成） | `references/templates/requirements-spec-*.md` | 从Word提炼的项目类型专属模板 |
| PRD 语言规范 | Read(".agents/knowledge/phase1-requirements/prd-language.md") | 禁止词汇、替换表 |
| 章节格式规范 | Read(".agents/knowledge/phase1-requirements/section-format.md") | 详细设计章节结构 |
| 质量审查清单 | Read(".agents/knowledge/phase1-requirements/srs-quality-checklist.md") | SRS四维度审查标准 |
| 模块依赖规范 | Read(".agents/knowledge/phase1-requirements/module-dependency.md") | 依赖关系描述方式 |
| PRD→SRS 转写对照 | `references/prd-to-srs-handoff.md` | Step F 章节映射与展开规则 |
| PRD→SRS 门禁 | Read("../common/prd-to-srs-gate.md") | 下游阻断与 SPEC_SOURCE |
| 图表生成 | 调用 `diagram-generator` 技能 | 流程图、时序图 |
| 模板提炼 Agent | `.agents/agents/template-analyzer.md` | 从Word文档提炼新模板 |

## 外部依赖与降级：Word/xlsx 导出

导出链走**技能库根的 `config.json`** 里的 `apiBaseUrl`（**端点不随仓库分发**，取值见该文件）。

**默认流程走不到这一节**——只有用户明确要求导 Word 时才需要这条链。

| 情况 | 表现 | 怎么办 |
|---|---|---|
| 没配 `config.json` | 脚本报「无法从 config.json 读取 apiBaseUrl」 | 从同级 `config.example.json` 复制后填地址 |
| 服务没起 | `curl` 连不上 / 超时 | 先自检（在技能自己的目录下跑）：`curl -s -o /dev/null -w '%{http_code}' "$(python3 -c 'import json;print(json.load(open("../config.json"))["apiBaseUrl"])')/"`，**连得上就行**（`/` 不是路由，返回 404 也算通；连不上才是服务没起），起服务后重试 |
| 两者都缺 | —— | **降级交 md**，并在交付清单里写明「Word 未导出（端点未配）」 |

**三条不许**（仅在用户明确要求导出时适用）：不许把「导出失败」写成完成；不许拿「默认不导」当借口跳过用户已经明确要求的导出；
不许在导出后不验图——`unzip -l x.docx | grep -c 'word/media/'` 要等于文档里的图片张数（文件名含中文会静默丢图）。