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「交付模式」；本技能未声明时默认「标准」）：

生成模式写入阶段（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 → 同上
• 两组之间串行，不跨组并行

工作模式

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

Step A: 生成模式

A1: 扫描项目上下文

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

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 深度审查（按模式）

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 每一项单独问一次。

修复方式（同原规则）：

• [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 命令：

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 是否可用：

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

若 docling 可用：

docling {docx路径} --to md --output /tmp/req-template-source.md

若 docling 不可用，降级到 pandoc：

pandoc {docx路径} -o /tmp/req-template-source.md --wrap=none 2>/dev/null && echo "pandoc成功" || echo "pandoc不可用"

若两者都不可用，降级到解压 XML：

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/ 下是否有多个模板文件：

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 不合格。

输出：

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

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

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

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

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: 登记与交接

✅ 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）：

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

Git Bash / Linux / macOS / Python：

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 里只有空图框）：

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，必须带文档类型后缀区分，否则后写的会覆盖先写的：

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

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

参考资源

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

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

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

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