/pdlc-deploy

name: pdlc-deploy
description: 按已评审的功能或发布版本写部署手册（docs/05_deployment/guides/），不执行真实部署；要发布版本先用 /pdlc-ship
argument-hint: "<v<版本> | 功能ID | 服务名 | 应用名>"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: deploy
produces:
  - docs/05_deployment/**
requires: []
next_step: null
terminal_state: deploy_done

创建部署文档

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ **IRON LAW · 不可违反的硬门禁**

以下规则为**不可协商**的执行约束：

1. **文件必须落盘**：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。 2. **阶段必须落章**：每个阶段完成后必须在状态机 `docs/.pdlc-state/<feature-id>.json` 追加 history，不可跳过。 3. **测试必须存在**：进入 `/pdlc-implement` 前，对应测试必须存在且处于红灯状态。违反则中止。 4. **自检必须执行**：段二自检为强制步骤，不得以"已经很好了"为由跳过。 5. **防循环**：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。 6. **状态必推进**：成功执行某 phase 后 `current_stage` 必须变更。收尾时若发现 `current_stage` 未推进，视为失败并报错，**不得静默返回**（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，`current_stage` 保持不变但必须写 `last_phase_result.ok=false` + `blocked_reason`。

**违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。** <!-- @include-end templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（`--autonomous`）

若本命令的参数含 `--autonomous`，本命令进入**无人值守**模式，按以下规则处理原本需要人应答的交互点。**参数是唯一真源**：不带 `--autonomous` 即为交互模式，一切照旧正常询问用户；绝不回读状态机 `run_mode` 兜底（「掉出 autonomous」是安全的失败方向）。

1. **流程性确认**（如「测试已绿是否继续」「是否覆盖已有文件」）→ **不询问**，按预设默认前进，并把决策追加到状态机 `history[].auto_decisions[]` （写状态机的命令：推进时给状态推进脚本传 `--decision "<确认点描述>=<所选默认>"`，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

2. **真需人判断**（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、**测试与设计 / PRD 矛盾**等无法安全默认的点）→ **不猜**。 改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 `--decision`：

• `current_stage` 保持不变（不推进）
• 写 `last_phase_result.ok = false` 且 `blocked_reason = "<原因>"`（写状态机的命令：给状态推进脚本传 `--blocked "<原因>"`）
• 末行输出哨兵：`<<<PDLC blocked reason="<原因>">>>`
• 立即结束命令，交还人类
• **守卫拦截也走这一条**：前置守卫（缺设计文档、缺测试、测试没红等）在 `--autonomous` 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 `ok=false` + `blocked_reason`（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 `ok=true`，循环驱动只看到 `current_stage` 没动，会把「被拦」误报成「卡住」，真实原因丢失。 3. **破坏性操作**（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ `--autonomous` **无效**，仍必须人工显式确认。 4. **顺手的 sidecar 产物**（如缺失时创建 `CHANGELOG.md`、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，**直接做并记入 `auto_decisions[]`**；这类改动不新增外部副作用，不属破坏性操作。

> 进入 autonomous 模式时，在状态机顶层写 `run_mode: "autonomous"` 仅供留痕（复盘区分人工 vs 循环产出）。 <!-- @include-end templates/prompts/noninteractive.md -->

> ⛔ **部署面向生产、不可逆·外发**：真实执行部署属破坏性范畴。**`--autonomous` 对涉及真实部署动作的环节无效**——仍必须人工显式确认。本命令默认只产出部署**文档**，不代表授权自动上线。

为一次发布、指定服务或应用创建部署手册。

PDLC 前置检查（必须执行，不可跳过）

先按输入形态确定本次部署涉及的功能：

• **版本号**（`v1.2.0` / `1.2.0`，`/pdlc-ship` 交接时给的就是它）→ **发布级部署**：读 `CHANGELOG.md` 里 `## [<版本>]` 段，

收集其中的功能 / 缺陷 ID（`F…` / `B…`）；这些就是本次部署涉及的功能。 段落不存在 → 停止并提示先跑 `/pdlc-ship`。段落里一个 ID 都没有（如只发了文档 / 依赖升级）→ 照常出发布级文档，跳过下面的评审记录查找

• **功能ID**（`F…` / `B…`）→ 单个功能
• **服务名 / 应用名 / 关键词** → 按下面第 2 步搜评审记录

对上面确定的每个功能（或关键词）做评审记录检查：

<!-- @include templates/prompts/artifact-lookup.md（已内联于下方，无需另读） -->

定位上游产物：先查状态机，再按关键词搜

守卫要找的上游文档（PRD、设计文档、评审记录等），按下面的顺序定位，**命中即停**：

1. **输入是功能ID / 缺陷ID**（`F…` / `B…`）且 `docs/.pdlc-state/<ID>.json` 存在 → 读它 `history[].produced` 里记下的路径，取所需类型的文档。这是上游阶段亲手记的，最可靠 2. **没有状态机、或 `produced` 里没有所需文档** → 在对应目录下搜：文件名含该 ID 或功能名关键词，或文件顶部 PDLC 追溯头的 `功能ID` 等于该 ID 3. **命中多份** → 不要随手挑一份：交互模式下列出来请人选；`--autonomous` 下优先取文件名含该 ID 的，仍不止一份则按「真需人判断」阻塞（写 `blocked_reason`，列出候选）

找到后从文件名或追溯头取功能ID，后续产出一律沿用它，**不另分配新 ID**。 <!-- @include-end templates/prompts/artifact-lookup.md -->

1. 从用户输入中提取服务/功能名称关键词（输入已是版本号或功能ID时，用上面确定的功能ID） 2. 按下面「定位上游产物」的顺序找 `docs/07_reviews/code/` 下的评审记录（有功能ID时先看状态机里 `review` 阶段记下的 `produced`） 3. **未找到评审记录** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的评审记录。
   部署文档必须基于已完成评审的代码。请先运行：
   👉 /pdlc-review <评审目标>

4. **找到** → 提取功能ID（如 `F20260326-090000`），读取评审记录内容，继续执行。 发布级部署时逐个功能检查，缺评审记录的功能列在停止信息里一并指出

工作流程

1. 阅读目标服务/应用的 README.md 和技术栈信息 2. 阅读 `docs/02_design/architecture/` 下的架构设计文档（如有） 3. 阅读评审记录，确认功能状态 4. **【必须创建文件】** 在 `docs/05_deployment/guides/` 下创建部署手册

• **使用模板**: 本 skill 目录下的 `assets/deploy-doc-template.md`（结构完整、章节齐全）
• **文件名格式**：
• 发布级部署：`v<版本>-deploy.md`（如 `v1.2.0-deploy.md`）——一份文档覆盖本次发布的全部功能，

各功能涉及的配置 / 迁移 / 回滚要点在文档里分节写明

• 单个功能：`<功能ID>-<功能名>-deploy.md`（如 `F20260326-090000-user-auth-deploy.md`）
• 若无功能ID，则使用旧格式 `YYYYMMDD-<服务名>-deploy.md`
• **文档顶部必须包含 PDLC 追溯头**（发布级部署的 `功能ID` 与 `前置文档` 列出全部，逗号分隔，并加一行 `版本`）：

     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-090000 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 部署 -->
     <!-- 前置文档: docs/07_reviews/code/F20260326-090000-user-auth-review.md -->

发布级示例：`<!-- 功能ID: F20260326-090000, B20260328-140000 -->`、`<!-- 版本: v1.2.0 -->`

文档内容

• 前置条件（环境要求、依赖服务）
• 环境配置（环境变量、配置文件）
• 构建步骤
• 部署步骤
• 健康检查验证
• 回滚方案
• 常见问题排查

部署文档自审与自动修复（创建后立即执行，不可跳过）

重新阅读刚创建的部署文档，逐项检查以下质量门禁：

关键章节检查

• [ ] 前置条件：是否列出了所有运行时依赖（数据库版本、中间件版本、系统配置）
• [ ] 环境变量：是否列出了每个环境变量的名称、用途、示例值、是否必填
• [ ] 构建步骤：是否可直接复制执行，无需额外推断
• [ ] 部署步骤：是否区分了首次部署与升级部署
• [ ] 健康检查：是否定义了健康检查 URL、预期响应、超时时间
• [ ] 回滚方案：是否有明确的回滚步骤（不是简单写「回滚到上一版本」）
• [ ] 数据库迁移：如涉及 DB 变更，是否有迁移执行和回滚步骤
• [ ] 常见问题排查：是否有至少 3 个常见错误场景及解决方案

可执行性检查

• [ ] 所有命令是否完整可复制（无省略号 `...`、无占位符未说明）
• [ ] 端口号、域名、路径是否使用了变量或占位符并在前置条件中说明
• [ ] 步骤顺序是否合理（不会因顺序错误导致部署失败）

自动修复

• 缺失的健康检查：根据服务类型（HTTP/gRPC）自动补充标准健康检查配置
• 缺失的回滚方案：自动补充基于版本的回滚步骤模板
• 缺失的环境变量说明：从代码中扫描 `process.env`/`os.Getenv`/`System.getenv` 等，自动补充
• 模糊的操作步骤：改写为具体命令
• 缺失的常见问题：自动补充 3 个通用排查项（端口占用、权限不足、依赖不可达）
• 修复后在文档末尾追加审查记录：

  ## 自审记录
  - 审查时间：<ISO 8601>
  - 发现问题：X 项
  - 自动修复：X 项
  - 修复明细：
    - [已修复] <问题描述>

要求

<!-- @include templates/prompts/output-language.md（已内联于下方，无需另读） --> 🌐 **Output language for generated artifacts**

All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:

1. **Default — match the conversation language exactly**:

• 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
• User talks to Claude in English → pr