zdoc-write

name: zdoc-write description: "标准文档撰写引擎。根据用户输入撰写 16 种 SSOT 文档（PRD/Arch/API/UX/Tech/Test/Data/DDD/Skill/Adapter/Job/Business/Strategy/Review/Testset/UX-Prototype），自动填充必输章节、补充缺失内容、识别核心决策点和分歧点供用户确认，严格遵循 DOC-WRITING-GUIDE 和 ITERATION-DOCUMENT-CHECKLIST 完整性要求。" argument-hint: " [--input PATH] [--module ID] [--output-dir DIR] [--project PATH]" allowed-tools: - Read - Write - Edit - Bash - Grep - Glob - AskUserQuestion

zdoc-write

标准文档撰写引擎 — 根据输入撰写符合 SSOT 规范的文档，自动补充缺失内容，识别核心决策点和分歧点供用户确认。

Primary Abstraction

Skill (governed capability template)

Secondary Abstraction

Pipeline — LLM 4-phase: analyze → generate → summarize → finalize

Authority

Canonical bundle: zdoc-write/

Canonical Authority

• DOC-WRITING-GUIDE v1.0 (docs/mvp-lite/DOC-WRITING-GUIDE.md)
• ITERATION-DOCUMENT-CHECKLIST v2.1 (docs/ITERATION-DOCUMENT-CHECKLIST.md)

关联文档

1. 目标与非目标

1.1 目标

• 根据用户输入撰写 16 种 SSOT 文档（PRD/Arch/API/UX/Tech/Test/Data/DDD/Skill/Adapter/Job/Business/Strategy/Review/Testset/UX-Prototype）。
• 自动识别文档类型、填充必输章节、补充缺失内容。
• 标记 AI 补充内容（[需确认]），识别核心决策点与分歧点供用户确认。
• 输出符合 DOC-WRITING-GUIDE 和 ITERATION-DOCUMENT-CHECKLIST 规范的文档。
• 撰写涉及用户交互的 PRD 时，必须生成用户旅程（主路径、分支路径、异常路径），作为验收前置条件。

1.2 非目标

• 不修改已有文档：除非用户明确请求更新，否则只从零撰写新文档。
• 不做文档质量校验：写完后应调用 zdoc-design-check 做质量检查。
• 不拆分实施任务：任务分解由 zdoc-i2i 负责。
• 不做多轮评审收敛：质量循环由 zdoc-quality-loop 负责。

2. 输入/输出

2.1 输入

2.2 输出

3. 执行步骤

1. 输入分析与类型识别：解析参数，读取输入，识别或推断文档类型，加载对应必输章节规范，分析已有内容 vs 缺失内容。
2. 旧接口/功能变更检测（Phase 1.5）：搜索同模块旧文档，提取旧定义并与新输入做差异对比；API 类型强制执行，其他类型检测到变更关键词时执行。
3. 涉及用户交互的 PRD 用户旅程检查（Phase 1.6）：当文档类型为 PRD 且内容包含用户动作、页面流程、表单、通知、权限、支付、审批、配置等交互时，必须抽取或补全用户旅程（主路径、分支路径、异常路径）。
4. 文档生成（Phase 2）：生成 YAML frontmatter，按类型模板生成章节结构，填充用户内容，注入变更标注，补充缺失章节并标记 [需确认]，建立交叉引用。
5. 核心决策点与分歧点摘要（Phase 3）：识别影响全局的设计选择、存在多种合理方案的分歧点、以及开放问题，输出结构化摘要供用户确认。
6. 最终化（Phase 4）：根据用户确认更新文档，执行完整性自检，输出最终文档与决策摘要。

支持的文档类型

架构

┌──────────────────────────────────────────────────────────────────┐
│              zdoc-write — 标准文档撰写引擎                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: 输入分析与类型识别                                      │
│  ──────────────────────────────                                  │
│  1. 解析用户输入（文本/文件/混合）                                │
│  2. 识别或推断文档类型                                            │
│  3. 加载对应类型的必输章节规范                                     │
│  4. 分析已有内容 vs 缺失内容                                      │
│  5. 确定模块编号和命名                                            │
│                                                                  │
│  Phase 1.5: 旧接口/功能变更检测                                   │
│  ──────────────────────────────                                  │
│  1. 搜索同模块/同功能的现有文档                                    │
│  2. 提取旧接口定义（端点、Schema、字段）                           │
│  3. 与新输入做差异对比                                            │
│  4. 生成变更清单（新增/修改/删除）                                │
│  5. API 类型：强制执行；其他类型：检测到变更时执行                  │
│                                                                  │
│  Phase 1.6: 涉及用户交互的 PRD 用户旅程检查                       │
│  ──────────────────────────────                                  │
│  1. 判断 PRD 是否涉及用户动作、页面流程、表单、通知等交互           │
│  2. 抽取或补全用户角色、触发入口、目标、主路径、分支路径、异常路径   │
│  3. 无法从输入确定的旅程节点必须标记 [需确认]                      │
│                                                                  │
│  Phase 2: 文档生成                                               │
│  ──────────────────────────────                                  │
│  1. 生成 YAML frontmatter                                        │
│  2. 按类型模板生成完整章节结构                                     │
│  3. 填充用户提供内容                                              │
│  4. 注入变更标注（来自 Phase 1.5）                                │
│  5. 补充缺失章节（标记 [需确认]）                                 │
│  6. 建立交叉引用                                                  │
│                                                                  │
│  Phase 3: 核心决策点与分歧点摘要                                  │
│  ──────────────────────────────                                  │
│  1. 识别文档中的核心决策（影响全局的设计选择）                      │
│  2. 识别分歧点（存在多种合理方案的章节）                           │
│  3. 识别开放问题和假设                                            │
│  4. 输出结构化摘要供用户确认                                      │
│                                                                  │
│  Phase 4: 最终化                                                 │
│  ──────────────────────────────                                  │
│  1. 根据用户确认更新文档                                          │
│  2. 执行完整性自检                                                │
│  3. 输出最终文档                                                  │
│                                                                  │
│  输入: 用户描述 + 可选的现有文档/上下文                            │
│  输出: 完整的标准文档 + 变更标注 + 决策摘要                       │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Phase 1: 输入分析与类型识别

执行步骤：

1. 解析 {{args}}，确定输入模式
2. 读取输入内容
3. 识别或推断文档类型
4. 加载对应类型的结构规范
5. 分析已有内容 vs 缺失内容
6. 检测变更关键词（"修改""变更""升级""迁移""替换"等），标记是否需要旧文档对比

1.1 输入模式

1.2 文档类型识别规则

当用户未明确指定类型时，按以下规则推断：

1.3 必输章节加载

根据识别的文档类型，加载对应的必输章节规范。详见 references/doc-type-requirements.md，其中按类型列出了：

• 必须包含的章节（来自 DOC-WRITING-GUIDE）
• 可选包含的章节
• 不包含的边界（防止越界）
• ITERATION-DOCUMENT-CHECKLIST 中对应的完整性要求

1.4 内容差距分析

对比用户提供内容与必输章节要求：

## 内容差距分析

| 章节 | 状态 | 说明 |
|------|------|------|
| 文档定位 | ✅ 已有 | {用户提供} |
| 用户故事 | ⚠️ 部分 | 有 3 条，缺少 AC |
| 业务规则 | ❌ 缺失 | 需要补充 |
| 验收标准 | ⚠️ 部分 | 有 AC 但缺少 Given-When-Then 格式 |

Phase 1.5: 旧接口/功能变更检测

目的：当撰写涉及旧功能变更的文档时，自动搜索同模块/同功能的现有文档，提取旧定义并与新输入做差异对比，生成变更标注。

强制级别：API 文档为 强制执行（写 API 文档时必须运行此阶段）；其他类型文档为 检测到变更时执行（用户描述中提及"修改""变更""升级""迁移"等关键词时触发）。

1.5.1 搜索策略

根据当前文档类型和模块编号，搜索现有文档：

搜索工具：使用 Glob 扫描文件，使用 Grep 提取关键定义（端点、Schema、字段名等）。

1.5.2 变更检测维度

API 文档（强制）

对找到的每个旧 API 文档，提取并对比以下维度：

其他文档类型（检测到变更时）

1.5.3 变更分类

对检测到的差异进行分类：

1.5.4 API 变更报告格式

API 文档检测到变更时，必须生成变更报告：

## API 变更检测报告

### 旧文档来源
- **文件**: [{旧文档文件名}]({相对路径})
- **最后更新**: {日期}
- **模块**: {module_id}

### 变更清单

| # | 变更类型 | 端点/字段 | 旧定义 | 新定义 | 影响 |
|---|---------|----------|--------|--------|------|
| 1 | `~MOD` | `POST /api/v1/users` | 响应含 `user_id: string` | 响应含 `user_id: int64` | 客户端需适配类型变更 |
| 2 | `+ADD` | `GET /api/v1/users/:id/profile` | — | 新增端点 | 向后兼容 |
| 3 | `-DEL` | `DELETE /api/v1/users/:id` | 存在 | 移除 | 破坏性变更，需确认 |
| 4 | `~REN` | `POST /api/v1/plans` 字段 `plan_name` | `plan_name` | `title` | 需要迁移 |

### 破坏性变更确认

以下变更可能影响现有客户端，需要用户确认：

1. **{变更描述}** — {影响范围} — 请确认是否执行此变更
2. ...

### 迁移注意事项

- {迁移步骤 1}
- {迁移步骤 2}

### 旧文档中存在但新文档未提及的端点

| 端点 | 旧文档章节 | 状态 |
|------|-----------|------|
| `GET /api/v1/old-endpoint` | §3.2 | 未在新文档中提及，可能被遗漏 |

1.5.5 非 API 文档变更标注格式

其他文档类型检测到变更时，在文档对应章节内嵌入变更标注：

### 字段变更

| 字段 | 旧定义 | 新定义 | 变更类型 |
|------|--------|--------|---------|
| `risk_level` | enum: low/medium/high | enum: low/medium/high/critical | `~MOD` — 新增 critical 值 |

<!-- [变更标注] 本字段在 TECH-M12 v1.0 中定义为 3 级枚举，本次变更为 4 级。
     旧文档: TECH-M12-Onboarding-Identity.md §3.2
     影响: 所有读取 risk_level 的下游服务需要适配新枚举值 -->

1.5.6 未找到旧文档的处理

1.5.7 输出物

Phase 1.5 的产出：

1. change-report.json：结构化变更检测结果（供后续阶段消费）
2. 变更标注：注入到 Phase 2 生成的文档中

{
  "doc_type": "api",
  "module_id": "M12",
  "old_doc_ref": {
    "path": "docs/mvp-lite/api/API-M12-Onboarding-Identity.md",
    "last_updated": "2026-05-20",
    "status": "frozen"
  },
  "changes_detected": true,
  "total_changes": 4,
  "breaking_changes": 1,
  "change_list": [
    {
      "id": "CHG-001",
      "type": "MOD",
      "target": "POST /api/v1/users",
      "dimension": "response_schema",
      "old_value": "user_id: string",
      "new_value": "user_id: int64",
      "breaking": true,
      "old_doc_ref": "API-M12-Onboarding-Identity.md §3.1"
    }
  ],
  "unmentioned_endpoints": [
    {
      "endpoint": "GET /api/v1/old-endpoint",
      "old_doc_section": "§3.2",
      "status": "potentially_missed"
    }
  ]
}

Phase 1.6: 涉及用户交互的 PRD 用户旅程检查

目的：PRD 只要涉及用户交互，就必须描述用户如何完成目标，避免只有功能清单、没有真实流程。

强制级别：文档类型为 prd 且触发交互判定时 强制执行。未提供用户旅程时必须补全并标记 [需确认]；不能以“待 UX 文档补充”为理由跳过。

1.6.1 触发条件

当 PRD 内容出现以下任一交互信号时，判定为“涉及用户交互”：

1.6.2 必须生成的用户旅程内容

涉及用户交互的 PRD 必须包含 “用户旅程” 章节，至少覆盖：

1.6.3 用户旅程格式

## 用户旅程

### 角色与目标

- **主要角色**: {用户角色}
- **用户目标**: {用户希望完成什么}
- **触发条件**: {何时/为何开始该旅程}

### 主路径

| 步骤 | 用户动作 | 系统响应 | 状态/结果 | 对应 FR/AC |
|------|----------|----------|-----------|------------|
| 1 | {动作} | {响应} | {状态} | FR-1 / AC-1 |
| 2 | {动作} | {响应} | {状态} | FR-2 / AC-2 |

### 分支路径

| 分支 | 触发条件 | 用户动作 | 系统响应 | 回到主路径/结束状态 |
|------|----------|----------|----------|---------------------|
| B1 | {条件} | {动作} | {响应} | {状态} |

### 异常路径

| 异常 | 类型 | 触发条件 | 系统提示/处理 | 用户恢复方式 | 最终状态 |
|------|------|----------|----------------|--------------|----------|
| E1 | 业务异常 | {条件} | {提示} | {操作} | {状态} |
| E2 | 系统异常 | {条件} | {提示} | {操作} | {状态} |

1.6.4 缺失处理

Phase 2: 文档生成

执行步骤：

1. 生成 YAML frontmatter
2. 按类型模板生成章节结构
3. 填充用户已有内容
4. 注入变更标注（来自 Phase 1.5 的 change-report.json）
5. 补充缺失内容（标记 [需确认]）
6. 建立与其他文档的交叉引用

2.1 Frontmatter 规范

所有文档必须包含 YAML frontmatter：

---
title: "{中文标题}"
status: draft
created: "{YYYY-MM-DD}"
updated: "{YYYY-MM-DD}"
module_id: ""        # 模块级文档必须填写
layer: ""            # L0-L3 层级
priority: ""         # P0/P1/P2
related_docs: []
relationships:
  depends_on: []
  implements: []
  constrains: []
  references: []
  supersedes: []
  superseded_by: []
---

2.2 章节生成规则

按类型模板生成，每个文档类型遵循 DOC-WRITING-GUIDE 中定义的必输章节：

通用必填章节（所有类型）：

• 文档定位：一句话说明本文负责回答什么问题
• 关联文档：列出上下游文档
• 范围边界：In Scope / Out of Scope
• 验收或检查点：判断本文描述成立的条件

类型特定章节：参见 references/doc-type-requirements.md

req 类型章节生成规则：

req 文档按以下结构生成章节：

testset 类型章节生成规则：

testset 文档必须按以下 9 节标准结构生成章节（对齐 TD-8）：

2.3 内容填充策略

2.4 补充标记规范

AI 补充的内容使用以下标记，确保用户知道哪些是 AI 生成的：

<!-- [需确认] AI 根据上下文补充，可能不准确 -->
{补充内容}

<!-- [AI 建议] 基于文档类型规范自动生成 -->
{建议内容}

2.5 交叉引用

使用 Markdown 相对路径建立文档间引用：

[PRD-M12-Onboarding-Identity](../prds/PRD-M12-Onboarding-Identity.md)

frontmatter 中的 related_docs 使用纯文件名。

2.6 命名规则

遵循 DOC-WRITING-GUIDE §0.6：

• 文件名：英文 kebab-case，含类型前缀和模块编号
• frontmatter title：中文
• 章节标题：中文为主，技术术语保留英文
• 序号：三位补零格式（001、002）

2.7 变更标注注入

当 Phase 1.5 检测到旧文档变更时，按以下规则注入变更标注：

API 文档

在文档中新增 "变更说明" 章节（位于"文档定位"之后、具体端点定义之前）：

## 变更说明

> 本文档基于 [{旧文档文件名}]({相对路径}) 进行变更，以下为变更清单。

### 变更概要

| 变更类型 | 数量 |
|---------|------|
| 新增端点 | {N} |
| 修改端点 | {N} |
| 删除端点 | {N} |
| 字段变更 | {N} |

### 破坏性变更

> ⚠️ 以下变更可能影响现有客户端，需确认迁移方案。

1. **{端点} {变更描述}** — {影响}
2. ...

### 详细变更清单

| # | 类型 | 端点/字段 | 旧定义 | 新定义 |
|---|------|----------|--------|--------|
| 1 | `~MOD` | {target} | {old} | {new} |
| 2 | `+ADD` | {target} | — | {new} |

### 旧文档中未提及的端点

| 端点 | 来源 | 处理建议 |
|------|------|---------|
| {endpoint} | {old_doc} §{section} | {保留/移除/迁移} |

在 frontmatter 中关联旧文档：

related_docs:
  - "{旧文档文件名}"
relationships:
  supersedes:
    - "{旧文档文件名}"

其他文档类型

在变更涉及的章节内，紧跟变更内容后插入标注块：

<!-- [变更标注] 相对于 {旧文档文件名} §{section} 的变更
     变更类型: {~MOD/+ADD/-DEL}
     旧定义: {旧内容摘要}
     影响: {影响范围}
-->

Phase 3: 核心决策点与分歧点摘要

目的：在生成文档后，识别需要用户确认的关键点，避免 AI 自行决策导致语义漂移。

核心原则（来自 ITERATION-DOCUMENT-CHECKLIST）：凡是需要人类反复讨论、拍板、确认的内容，都必须明确标记，让用户决策。

3.1 识别维度

核心决策点

影响全局的设计选择，一旦确定难以修改：

分歧点

存在多种合理方案的章节：

开放问题

文档中无法确定、需要后续决策的内容。

3.2 摘要输出格式

## 文档摘要 — {文档标题}

### 文档概况
- **类型**: {doc_type}
- **模块**: {module_id}
- **章节完整性**: {已填充}/{总计} 个必填章节
- **补充内容**: {N} 处 [需确认]

### 核心决策点（需要您确认）

#### 1. {决策标题}
- **位置**: §{章节号}
- **当前方案**: {AI 生成的默认方案}
- **备选方案**: {其他合理方案}
- **影响范围**: {哪些章节/模块受影响}
- **建议**: {AI 的推荐及理由}
- **请确认**: {具体问题}

#### 2. ...

### 分歧点（可能需要讨论）

#### 1. {分歧标题}
- **位置**: §{章节号}
- **方案 A**: {描述}
- **方案 B**: {描述}
- **权衡**: {各方案的 trade-off}
- **请确认**: 选择哪个方案？

### 开放问题
1. {问题 1} — 建议 {处理方式}
2. {问题 2} — 建议 {处理方式}

### 下一步
请确认上述决策点和分歧点后，我将更新文档并生成最终版本。

Phase 4: 最终化

执行步骤：

1. 根据用户确认更新文档
2. 执行完整性自检
3. 输出最终文档

4.1 用户确认处理

• 用户确认的决策：更新文档，移除 [需确认] 标记
• 用户修改的方案：按用户选择更新
• 用户跳过的点：保留 [需确认] 标记，在 Open Questions 中记录

4.2 完整性自检

输出文档前执行以下检查：

4.3 输出

最终输出两个文件：

1. 文档本体：{output_dir}/{type_prefix}-{module_id}-{slug}.md
2. 决策摘要：{output_dir}/.zdoc-write/{doc_id}-decisions.md

Workflow Boundary

• Input: 用户描述 + 可选的现有文档/上下文
• Output: 完整的标准文档（符合 DOC-WRITING-GUIDE 规范）+ 决策摘要
• Out of scope:
  • 不修改已有文档（除非用户明确要求更新）
  • 不校验文档质量（用 zdoc-design-check）
  • 不拆分实施任务（用 zdoc-i2i）
  • 不做多轮评审（用 zdoc-quality-loop）

Non-Negotiable Rules

1. 必填章节不跳过：DOC-WRITING-GUIDE 定义的必填章节必须全部生成
2. 补充内容必须标记：AI 补充的内容必须标记 [需确认]，不得冒充用户输入
3. 核心决策必须确认：影响全局的设计选择不得自行决策，必须通过 Phase 3 摘要让用户确认
4. Out of Scope 必须具体：至少列出 3 项具体的排除内容，不能写"无"或"暂无"
5. 不越界：不同类型文档的内容不混写（如 PRD 不写 API 端点细节）
6. 命名规范：严格遵循 DOC-WRITING-GUIDE §0.6 命名规则
7. 中英文规则：文件名英文 kebab-case，title 中文，章节标题中文为主
8. 状态初始为 draft：新文档 status 初始为 draft，不擅自设为 approved/frozen
9. 可追溯：补充内容应标注来源或推理依据
10. API 变更检测强制：撰写 API 文档时，必须执行 Phase 1.5 搜索同模块旧 API 文档并生成变更标注。未搜索到旧文档时标注"首次撰写"，搜索到旧文档时必须生成完整变更清单和破坏性变更确认
11. 其他类型变更检测：撰写非 API 文档时，如果用户描述中包含变更/修改/升级/迁移等关键词，必须执行 Phase 1.5 搜索相关旧文档。未触发变更关键词时可跳过
12. 涉及用户交互的 PRD 必须有用户旅程：PRD 只要包含用户动作、页面流程、表单、通知、权限、支付、审批、配置等交互信号，就必须包含“用户旅程”章节，覆盖主路径、分支路径、异常路径，并映射到 FR/AC；缺失部分必须标记 [需确认]

Pitfalls / 常见坑与规避

Usage

# 指定类型撰写
zdoc-write prd --module M12 --output-dir docs/mvp-lite/prds/

预期输出（用户确认后落盘）:

docs/mvp-lite/prds/
├── PRD-M12-Onboarding-Identity.md
└── .zdoc-write/
    └── PRD-M12-Onboarding-Identity-decisions.md

# 从内容推断类型
zdoc-write "我需要写一个用户注册模块的架构文档，用 React + Go + PostgreSQL"

预期输出（用户确认后落盘）:

{output-dir}/
├── ARCH-M12-User-Registration.md          # 推断类型为 arch，模块编号需用户确认或后续指定
└── .zdoc-write/
    └── ARCH-M12-User-Registration-decisions.md

注：未指定 --module 和 --output-dir 时，文档摘要中会提示用户补全，确认后按用户指定路径落盘。

# 从现有文件补充
zdoc-write prd --input docs/drafts/prd-notes.md --output-dir docs/mvp-lite/prds/

预期输出（用户确认后落盘）:

docs/mvp-lite/prds/
├── PRD-M12-Onboarding-Identity.md         # 从 prd-notes.md 提取内容，自动填充缺失章节
└── .zdoc-write/
    └── PRD-M12-Onboarding-Identity-decisions.md

决策摘要示例内容：

• 核心决策点：模块编号 M12 是否准确、Out of Scope 的 3 项排除内容
• 分歧点：用户故事采用 Given-When-Then 还是 Bullet AC 格式
• 开放问题：未提供业务规则，已标记 [需确认]

# 指定项目路径（用于交叉引用）
zdoc-write tech --module M12 --project . --output-dir docs/mvp-lite/tech/

预期输出（用户确认后落盘）:

docs/mvp-lite/tech/
├── TECH-M12-Onboarding-Identity.md
└── .zdoc-write/
    └── TECH-M12-Onboarding-Identity-decisions.md

注：指定 --project . 后，Phase 1 会扫描项目内已有文档（如 ../prds/PRD-M12-*.md、../arch/ARCH-M12-*.md），自动建立交叉引用并在决策摘要中列出关联文档清单。

# 完整参数
zdoc-write api --module M12 --output-dir docs/mvp-lite/api/ --project .

预期输出（用户确认后落盘）:

docs/mvp-lite/api/
├── API-M12-Onboarding-Identity.md
└── .zdoc-write/
    ├── API-M12-Onboarding-Identity-decisions.md
    └── API-M12-Onboarding-Identity-change-report.json   # API 类型强制生成变更检测报告

注：API 类型强制触发 Phase 1.5 旧接口变更检测。若搜索到同模块旧 API 文档，决策摘要中会包含破坏性变更确认项；若未搜索到，文档中标注"首次撰写，无历史版本"。

执行流程说明：上述命令不会立即落盘最终文档。执行后，zdoc-write 会先输出 ## 文档摘要 供用户确认核心决策点；用户确认后进入 Phase 4 最终化，生成文档本体与决策摘要。

Compatibility Note

本技能遵循 DOC-WRITING-GUIDE v1.0 和 ITERATION-DOCUMENT-CHECKLIST v2.1 的全部规范。输出文档可直接被 zdoc-design-check 校验、被 zdoc-i2i 转化为实施任务。文档类型覆盖 docs/mvp-lite/ 下全部 17 个子目录。