ai-project-manage-cli 3.0.4 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,
@@ -26,7 +26,8 @@
     "typescript": "~5.6.0",
     "@types/ws": "~8.18.1",
     "esbuild": "~0.28.0",
-    "vitest": "~4.1.5"
+    "vitest": "~4.1.5",
+    "@types/dockerode": "~4.0.1"
   },
   "engines": {
     "node": ">=18"
@@ -35,6 +36,8 @@
     "ws": "~8.20.0",
     "listpage-http": "~0.0.318",
     "commander": "~14.0.3",
-    "yaml": "~2.8.4"
+    "yaml": "~2.8.4",
+    "minio": "~8.0.7",
+    "dockerode": "~5.0.0"
   }
 }

package/template/apm.config.json

@@ -1,5 +1,27 @@
 {
-    "name": "project-name",
-    "frontendDeploy": {},
-    "backendDeploy": {}
-}
+  "name": "project-name",
+  "frontendDeploy": {
+    "endpoint": "",
+    "port": 9000,
+    "useSsl": false,
+    "accessKey": "",
+    "secretKey": "",
+    "bucket": ""
+  },
+  "backendDeploy": {
+    "name": "",
+    "registryHost": "",
+    "registryNamespace": "",
+    "registryUser": "",
+    "registryPassword": "",
+    "remoteHost": "",
+    "remotePort": 2376,
+    "remoteProtocol": "https",
+    "caPath": "",
+    "certPath": "",
+    "keyPath": "",
+    "envFilePath": "",
+    "containerPortsMappings": ["3000:3000"],
+    "dockerNetwork": ""
+  }
+}

package/template/skills/apm-apply-change/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: apm-apply-change
+description: 在 .apm/workitems/<requirementId>/ 按 tasks.md 逐项实现、勾选；一项任务一个 commit。遇事实性阻塞（如规划与代码严重不符）须停止执行，仅陈述事实与需用户提供的材料，不替用户决策或列方案。/opsx:apply 同此技能。
+---
+
+# APM 工作项：按任务实现
+
+根据工作项目录下的 **`tasks.md`** 驱动实现：**读规划 → 做代码 → 对账元数据 → 勾选 → 单独 commit**，直至全部完成或遇硬阻塞；上下文以 **`.apm/workitems/<requirementId>/`** 内文件为准。
+
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **推荐显式提供**（与 `.apm/workitems/<requirementId>/` 目录名一致）。 |
+
+若本轮未提供 `requirementId`：
+
+1. 若对话中已能**唯一**确定工作项目录名，则用之。
+2. 否则查看 **`.apm/workitems/`** 下子目录：若**仅有一个**，自动采用；若**多个**，**按目录名字典序取第一个**作为本次工作项，并在回复中列出当时可见的候选名，声明 **使用工作项：`<requirementId>`** 及如何覆盖（例如下次显式给出 id）。**不要**调用 AskUserQuestion，**不要**停下来让用户当场选择。
+
+**不要**为澄清需求而反问用户。若执行中发现**无法在无决策前提下继续**的事实性问题（见上文 **「停止执行」**），**不要**用推断顶过去。
+
+---
+
+## 停止执行（优先于继续推进）
+
+若在实施过程中**发现**任一情况，**立即停止**本技能所驱动的后续实现与勾选（不再继续下一项任务），仅在会话中输出：
+
+1. **客观事实**：已读到的文件/路径、与代码或任务条目的**具体矛盾点**（可摘引，避免主观评价）。
+2. **当前进度**：处理到 `tasks.md` 的哪一条、仓库是否已有未提交改动（若有，说明范围）。
+3. **需要用户提供什么**：为继续推进所**缺的信息或决策**（例如：以何者为准、是否接受某类改动、需确认的业务口径）。用**清单**列出，**一句一项**。
+
+**禁止**：给出「建议你先改 A / 再改 B」「可选方案 1/2/3」「宜采用…」等**替用户决策**或**行动建议**；不指导用户如何改文档、不预设优先级。
+
+**允许**：描述「若不补充某信息则无法继续」的**逻辑关系**（仍不展开成方案）。
+
+---
+
+## 工作项路径与必备文件
+
+- **根路径**：**`.apm/workitems/<requirementId>/`**
+- **必备**：**`tasks.md`**（含 `- [ ]` / `- [x]` 待办）。若不存在或无可执行条目：**阻塞**，说明须先完成 **apm-propose**（或手工补齐 `tasks.md`）。
+- **强烈建议读**：**`prd.md`**（范围与验收）；实现时按需 **Read** **`proposal.md`**、**`design.md`**、**`specs/`**（与 **`tasks-instruction.md`** 中每条任务的元数据一致）。
+- **进度**：仅由 **`tasks.md`** 中复选框统计「已完成 / 总数」。
+
+### 单会话读取（可选减负）
+
+同一轮连续执行多项任务时：**`prd.md` / `design.md` / 各 spec** 若已在会话内读过且无疑虑，不必每个任务重复全文 Read；以**当前任务行**及元数据指向的 spec/设计段落为准，必要时对文件 **Read（偏移）** 或再读全文。
+
+---
+
+## Steps
+
+### 1. 锚定工作项
+
+确定 **`requirementId`** 与工作项根路径；声明 **使用工作项：`<requirementId>`**（若依上节规则自动选定，须说明如何覆盖）。
+
+### 2. 读取 `tasks.md` 并判断状态
+
+- **Read** **`.apm/workitems/<requirementId>/tasks.md`**。
+- 若文件缺失、为空、或无任何 `- [ ]`：**停止**，提示先具备可执行 `tasks`（规划阶段）。
+- 若全部已为 `- [x]`：**可**直接汇报「已全部完成」（仅作事实陈述，不建议是否提交或发 MR）。
+
+### 3. 读取实现上下文（按任务需要）
+
+开始**第一个**未勾选任务前，至少 **Read**：
+
+- **`prd.md`**（若存在；与验收相关条款）
+- 与任务相关的 **`design.md`** 片段、**`specs/`** 下对应文件（见任务条目的 **需求编号** / 描述）
+
+不要求每次任务都重读全部规划文件；以 **`tasks.md` 当前项** + **缺口再 Read** 为准。
+
+### 4. 展示当前进度
+
+在对话中简要展示：
+
+- **工作项**：`requirementId`
+- **进度**：「N/M 个任务已完成」（由 `tasks.md` 勾选统计）
+- **当前将处理**：下一条 `- [ ]` 的摘要（含组号/编号如 `2.1`）
+
+### 5. 实现任务（循环直至完成或阻塞）
+
+对每一条 **未勾选** 任务（建议按 `tasks.md` 自上而下顺序）：
+
+1. **说明**正在处理哪一项（编号 + 简述）。
+2. **实现**所需代码/配置/迁移等；改动保持**最小**、与该项描述一致。
+3. **标记完成前**在回复或备注中收集依据（与 **`tasks-instruction.md`** 子列表字段对齐即可）：
+   - **需求编号**：本实现对应 specs / tasks 中的哪条需求或场景。
+   - **预期改动路径** 与 **实际改动文件**：若有合理偏差，简要说明原因。
+   - **验证用例编号**（若任务中有）。
+   - **验证结果** / **完成标准**：如何确认本项已达成（可简短）。
+4. 仅在依据已齐、且自洽通过后，将 **`tasks.md`** 中对应行 **`- [ ]` 改为 `- [x]`**。
+5. **Git**：本待办对应的**实现 + 勾选**等改动，**单独 `git commit` 一次**（**一项待办 = 一个 commit**；勿把多项待办混在同一 commit）。提交信息建议包含 `requirementId` 与任务编号或简述。
+
+**何时停止（不继续下一项）**——与上文 **「停止执行」** 一致：
+
+- **`design` / `specs` / `tasks` 与当前代码或彼此严重不一致**，以致无法按任务字面含义在**不臆造**的前提下完成 → **按「停止执行」输出**（事实 + 需用户提供的材料），**不**建议先改哪份文档、不改哪些。
+- 命令失败、环境错误、权限等**硬阻塞** → 说明原因、失败点、已执行步骤；**不**给排障步骤或替代命令建议（除非任务本身要求执行某命令且该命令已写在任务/文档中）。
+- 用户中断。
+
+**何时仍可继续**（仅当满足）：任务表述略含糊，但可在 **prd / design / specs / tasks** 已有文字内**自洽**完成；若有**假设**，在回复中写清**假设**（仍不反问）。一旦假设会触及「以谁为准」的**产品/架构决策**，转 **「停止执行」**。
+
+### 6. 完成或暂停时展示状态
+
+- **本会话**完成了哪些任务（可列勾选项摘要）。
+- **总体进度**：「N/M 个任务已完成」。
+- 若**全部完成**：仅陈述事实（进度与勾选状态），**不**建议后续流程（MR/发布/归档等）。
+- 若**暂停**：按 **「停止执行」** 或硬阻塞格式输出，**无**「可选后续」或方案建议。
+
+---
+
+## 实现过程中的输出（示例）
+
+```
+## 正在实施：<requirementId>
+
+处理任务 3/7：2.1 实现导出接口
+[...实现过程...]
+✓ 任务完成 · commit <short-sha> <subject>
+
+处理任务 4/7：2.2 …
+```
+
+---
+
+## 全部完成时的输出（示例）
+
+```
+## 实现完成
+
+**工作项：** <requirementId>
+**进度：** 7/7 个任务已完成 ✓
+
+### 本会话已完成
+- [x] …
+- [x] …
+
+（每项待办均已对应独立 commit。）
+```
+
+---
+
+## 暂停时的输出（示例）
+
+```
+## 实现已暂停
+
+**工作项：** <requirementId>
+**进度：** 4/7 个任务已完成
+
+### 事实与原因
+<客观描述：文件/行/与任务或代码的矛盾点>
+
+### 需要用户提供（或决策）
+- …
+- …
+```
+
+（无方案列表、无「建议」；用户补充信息后可再次运行本技能。）
+
+---
+
+## 约束
+
+- 持续执行待办直至完成、**停止执行**或硬阻塞。
+- 开始前须已能对照 **`tasks.md`** 与 **`prd.md`**（及任务所需的 design/spec）；**不要**在未读清当前任务依赖时盲改。
+- 任务表述有歧义时，仅在**无需用户决策**的前提下依据 **specs / design / prd** 推断；一旦涉及**以谁为准**或**严重不一致**，**停止执行**（见上文）。
+- **不**因「发现规划与代码不符」而**主动建议**修改 `design.md` / `specs/` / `tasks.md`；**停止**并说明事实与需用户提供的材料即可。
+- 代码改动保持最小、与**当前任务**范围一致。
+- 未完成需求/验证对账前，**不要**将任务勾为完成。
+- 验证失败或依据不足时，保持 **`- [ ]`**，并明确写出缺口。
+- 若任务元数据缺失（需求编号、预期改动路径、完成标准等），在可能范围内于实现前**补全或按 tasks 模板推断**，并在说明中注明。
+- 每完成一项任务并记录依据后，**立即**更新勾选并**随即**单独 `git commit`。
+- 遇硬阻塞时暂停并说明原因（**不**给出替代命令或排查建议，除非任务/文档已写明）；
+- 需求不清且无法自洽推断时，**停止执行**并列出需用户提供的材料；**不反问用户**。
+
+---
+
+## 与规划流程的衔接
+
+- **`tasks.md`** 须由 **apm-propose**（或等价流程）生成并符合 **`tasks-instruction.md`** 格式（`- [ ]`、元数据子列表等），否则本技能无法可靠追踪。
+- 若执行中发现 **`design` / `specs` 与代码严重不一致**：**停止执行**，按上文输出事实与**需用户提供**的决策/信息；**不**建议先改哪类工件、不代用户排优先级。
+
+---
+
+## 流动工作流
+
+- **可分段调用**：可在部分任务完成后结束会话，下次同一工作项继续。
+- **规划修订**：由用户在**流程外**修订 `design.md` / `specs/` / `tasks.md` 后，再触发本技能；本技能执行中**不因发现不符**而主动改规划文件或提出修改方案。

package/template/skills/apm-dev/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: apm-dev
+description: 按需求 ID 全自动开发：切分支、读 PRD、按改动规模选择 Quick 或 Spec 路径实现代码、提交并推送；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及全自动开发或「apm-dev」时使用。
+---
+
+# APM 全自动开发（按需求 ID）
+
+用户给出 **需求 ID**（`requirementId`，与工作项目录名一致）。**缺 ID 时索要，不猜测。**
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **必填**。与 `.apm/workitems/<requirementId>/` 目录名一致。 |
+
+---
+
+## 技能文件定位（apm-propose / apm-apply-change）
+
+Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。执行前父 Agent **须 Read**：
+
+| 技能 | 路径 |
+| --- | --- |
+| **apm-propose** | `.apm/skills/apm-propose/SKILL.md` |
+| **apm-apply-change** | `.apm/skills/apm-apply-change/SKILL.md` |
+
+instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-instruction.md`）。若上述 `SKILL.md` **不存在或不可读**：**不得**进入 Spec 子流程；在表格中标记失败原因（例如需先 `apm init` 或同步 `.apm/skills`），并停止步骤 4。
+
+---
+
+## 流程总览
+
+| 序号 | 步骤 | 说明 |
+| --- | --- | --- |
+| 1 | **切分支** | 在仓库根目录执行 `apm branch <requirementId>` |
+| 2 | **读 PRD + 成本评估** | **Read** `.apm/workitems/<requirementId>/prd.md`，判定 Quick / Spec |
+| 3 | **Quick 开发** | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码 |
+| 4 | **Spec 开发** | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**，均由 **子 Agent** 按对应技能执行 |
+| 5 | **提交与推送** | `git` 提交并 `push`，工作区干净 |
+| 6 | **对用户回复** | **一张 Markdown 表格**汇总各步执行结果（见文末模板） |
+
+---
+
+## 步骤 1：`apm branch`
+
+1. 在**仓库/工作区根目录**执行：
+
+   ```bash
+   apm branch <requirementId>
+   ```
+
+2. 记录：命令是否成功、简要输出或错误信息（写入最终表格）。**失败则按「Guardrails → 失败即终止」处理**，不为此命令做多轮重试（除非属 Agent 用错目录等可纠正失误）。
+
+---
+
+## 步骤 2：读取 PRD 并评估改动成本
+
+1. **Read** 全文：`.apm/workitems/<requirementId>/prd.md`。
+2. 若无法读取：在仓库根目录执行 **`apm pull <requirementId>`**（同步工作项），再 **Read** 一次；仍失败则**停止后续实现**，仅在表格中标记失败原因。
+3. **不**为评估向用户发起追问；信息不足时倾向 **Spec**（保守）。
+
+### Quick（较小）与 Spec（较大）判定参考
+
+**倾向 Quick**（满足越多越适用）：
+
+- 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
+- 无新表结构/大规模迁移/权限模型变更。
+- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 不需要跨多服务的架构裁定即可开工。
+
+**倾向 Spec**（命中任一条即可）：
+
+- 前后端联动、多包改造或新公共抽象。
+- 新数据模型、迁移、或安全/审计/权限相关。
+- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 评估认为不先产出 **proposal / design / specs / tasks** 则难以保证实现与验收对齐。
+
+在表格「步骤 2」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）。
+
+---
+
+## 步骤 3：Quick 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **Quick**。
+
+1. 父 Agent 已通过 **Read** 掌握 `prd.md`；若启动新子 Agent，在委派提示中写明 **`requirementId`**、工作项路径、以及「实现须严格对照 PRD，改动范围最小化」。
+2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
+   - 自行 **Read** `.apm/workitems/<requirementId>/prd.md`（若会话未带全文）。
+   - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+   - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `rushx build` / 测试等则写明结果）。
+3. 父 Agent 根据子 Agent 返回在表格中填写步骤 3 **状态**；本模式下步骤 4 填 **跳过**。
+
+---
+
+## 步骤 4：Spec 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **Spec**。
+
+1. 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
+2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `.apm/workitems/<requirementId>/` 生成 **proposal、design、specs、tasks** 等工件（顺序与依赖以 SKILL 为准）。
+3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
+4. 若 **apm-propose** 未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
+5. 表格中步骤 3 填 **跳过**；步骤 4 分两行或合并一行写清 propose / apply 状态（见表格模板）。
+
+---
+
+## 步骤 5：提交并推送
+
+在仓库根目录执行（可用一条复合命令或分步；以实际仓库远程为准）：
+
+1. `git status`：确认变更范围。
+2. 若有未提交变更：`git add -A`，然后 `git commit -m "feat(req-<requirementId>): <简短说明>"`（说明应概括本轮需求实现；若子 Agent 已按任务多次 commit，则可能无需新 commit，以 `status` 为准）。
+3. `git push`：推送到当前分支对应远程（首次必要时 `-u origin <branch>`）。
+4. 再次 `git status`：**须为干净工作区**（无未提交、未跟踪的重要残留；若有应记录为失败或说明例外）。
+
+将命令结果、最终分支名、是否已 push、工作区是否干净写入表格。
+
+---
+
+## 步骤 6：对用户回复（表格）
+
+对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1～5**（步骤 6 为呈现表格本身，可不单独成行）。表头建议：
+
+| 步骤 | 内容 | 结果 |
+| --- | --- | --- |
+| 1 | `apm branch <requirementId>` | 成功 / 失败（原因） |
+| 2 | 读 PRD + 成本评估 | Quick 或 Spec；一行理由 |
+| 3 | Quick 开发（子 Agent） | 成功 / 失败 / **跳过** |
+| 4 | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**；可注明子步骤 |
+| 5 | commit & push；工作区干净 | 成功 / 失败（原因） |
+
+**可选**：在表格外增加**简短**一句话摘要（例如当前分支名、阻塞点）；若用户此前约定「仅表格」，则可仅输出表格。
+
+---
+
+## Guardrails
+
+- **失败即终止**：在用户提供的 **`requirementId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含 `apm branch`、`apm pull`、读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络、命令结果等做**多次**或「轮番」重试。
+- **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正 `cwd` 或路径后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**，不再扩展尝试。
+- **不要**在无 `prd.md`（且 `apm pull` 后仍无）的情况下编造需求实现。
+- **子 Agent** 提示中须带 **`requirementId`** 与仓库根路径意识，避免改错工作树。

package/template/skills/apm-dev copy/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: apm-dev
+description: 按需求 ID 全自动开发：切分支、读 PRD、按改动规模选择 Quick 或 Spec 路径实现代码、提交并推送；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及全自动开发或「apm-dev」时使用。
+---
+
+# APM 全自动开发（按需求 ID）
+
+用户给出 **需求 ID**（`requirementId`，与工作项目录名一致）。**缺 ID 时索要，不猜测。**
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **必填**。与 `.apm/workitems/<requirementId>/` 目录名一致。 |
+
+---
+
+## 技能文件定位（apm-propose / apm-apply-change）
+
+Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。执行前父 Agent **须 Read**：
+
+| 技能 | 路径 |
+| --- | --- |
+| **apm-propose** | `.apm/skills/apm-propose/SKILL.md` |
+| **apm-apply-change** | `.apm/skills/apm-apply-change/SKILL.md` |
+
+instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-instruction.md`）。若上述 `SKILL.md` **不存在或不可读**：**不得**进入 Spec 子流程；在表格中标记失败原因（例如需先 `apm init` 或同步 `.apm/skills`），并停止步骤 4。
+
+---
+
+## 流程总览
+
+| 序号 | 步骤 | 说明 |
+| --- | --- | --- |
+| 1 | **切分支** | 在仓库根目录执行 `apm branch <requirementId>` |
+| 2 | **读 PRD + 成本评估** | **Read** `.apm/workitems/<requirementId>/prd.md`，判定 Quick / Spec |
+| 3 | **Quick 开发** | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码 |
+| 4 | **Spec 开发** | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**，均由 **子 Agent** 按对应技能执行 |
+| 5 | **提交与推送** | `git` 提交并 `push`，工作区干净 |
+| 6 | **对用户回复** | **一张 Markdown 表格**汇总各步执行结果（见文末模板） |
+
+---
+
+## 步骤 1：`apm branch`
+
+1. 在**仓库/工作区根目录**执行：
+
+   ```bash
+   apm branch <requirementId>
+   ```
+
+2. 记录：命令是否成功、简要输出或错误信息（写入最终表格）。**失败则按「Guardrails → 失败即终止」处理**，不为此命令做多轮重试（除非属 Agent 用错目录等可纠正失误）。
+
+---
+
+## 步骤 2：读取 PRD 并评估改动成本
+
+1. **Read** 全文：`.apm/workitems/<requirementId>/prd.md`。
+2. 若无法读取：在仓库根目录执行 **`apm pull <requirementId>`**（同步工作项），再 **Read** 一次；仍失败则**停止后续实现**，仅在表格中标记失败原因。
+3. **不**为评估向用户发起追问；信息不足时倾向 **Spec**（保守）。
+
+### Quick（较小）与 Spec（较大）判定参考
+
+**倾向 Quick**（满足越多越适用）：
+
+- 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
+- 无新表结构/大规模迁移/权限模型变更。
+- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 不需要跨多服务的架构裁定即可开工。
+
+**倾向 Spec**（命中任一条即可）：
+
+- 前后端联动、多包改造或新公共抽象。
+- 新数据模型、迁移、或安全/审计/权限相关。
+- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 评估认为不先产出 **proposal / design / specs / tasks** 则难以保证实现与验收对齐。
+
+在表格「步骤 2」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）。
+
+---
+
+## 步骤 3：Quick 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **Quick**。
+
+1. 父 Agent 已通过 **Read** 掌握 `prd.md`；若启动新子 Agent，在委派提示中写明 **`requirementId`**、工作项路径、以及「实现须严格对照 PRD，改动范围最小化」。
+2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
+   - 自行 **Read** `.apm/workitems/<requirementId>/prd.md`（若会话未带全文）。
+   - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+   - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `rushx build` / 测试等则写明结果）。
+3. 父 Agent 根据子 Agent 返回在表格中填写步骤 3 **状态**；本模式下步骤 4 填 **跳过**。
+
+---
+
+## 步骤 4：Spec 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **Spec**。
+
+1. 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
+2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `.apm/workitems/<requirementId>/` 生成 **proposal、design、specs、tasks** 等工件（顺序与依赖以 SKILL 为准）。
+3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
+4. 若 **apm-propose** 未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
+5. 表格中步骤 3 填 **跳过**；步骤 4 分两行或合并一行写清 propose / apply 状态（见表格模板）。
+
+---
+
+## 步骤 5：提交并推送
+
+在仓库根目录执行（可用一条复合命令或分步；以实际仓库远程为准）：
+
+1. `git status`：确认变更范围。
+2. 若有未提交变更：`git add -A`，然后 `git commit -m "feat(req-<requirementId>): <简短说明>"`（说明应概括本轮需求实现；若子 Agent 已按任务多次 commit，则可能无需新 commit，以 `status` 为准）。
+3. `git push`：推送到当前分支对应远程（首次必要时 `-u origin <branch>`）。
+4. 再次 `git status`：**须为干净工作区**（无未提交、未跟踪的重要残留；若有应记录为失败或说明例外）。
+
+将命令结果、最终分支名、是否已 push、工作区是否干净写入表格。
+
+---
+
+## 步骤 6：对用户回复（表格）
+
+对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1～5**（步骤 6 为呈现表格本身，可不单独成行）。表头建议：
+
+| 步骤 | 内容 | 结果 |
+| --- | --- | --- |
+| 1 | `apm branch <requirementId>` | 成功 / 失败（原因） |
+| 2 | 读 PRD + 成本评估 | Quick 或 Spec；一行理由 |
+| 3 | Quick 开发（子 Agent） | 成功 / 失败 / **跳过** |
+| 4 | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**；可注明子步骤 |
+| 5 | commit & push；工作区干净 | 成功 / 失败（原因） |
+
+**可选**：在表格外增加**简短**一句话摘要（例如当前分支名、阻塞点）；若用户此前约定「仅表格」，则可仅输出表格。
+
+---
+
+## Guardrails
+
+- **失败即终止**：在用户提供的 **`requirementId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含 `apm branch`、`apm pull`、读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络、命令结果等做**多次**或「轮番」重试。
+- **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正 `cwd` 或路径后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**，不再扩展尝试。
+- **不要**在无 `prd.md`（且 `apm pull` 后仍无）的情况下编造需求实现。
+- **子 Agent** 提示中须带 **`requirementId`** 与仓库根路径意识，避免改错工作树。

package/template/skills/apm-propose/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: apm-propose
+description: 由 PRD 在 .apm/workitems/<requirementId>/ 按依赖顺序生成 proposal、design、specs、tasks，当用于主动声明使用该技能时触发。
+---
+
+# APM 工作项：规划工件
+
+在 **`.apm/workitems/<requirementId>/prd.md`** 上生成实现前规划工件。每个文件**生成前须读哪些依赖、与谁对齐**，以对应 **`propose-instruction.md` / `design-instruction.md` / `specs-instruction.md` / `tasks-instruction.md`** 里的 **「依赖」** 小节为**唯一清单**（本 SKILL 不重复展开）。本 SKILL 只约定**撰写顺序**与 **「单会话读取策略」**；落笔前须已掌握该工件 instruction 所列依赖（是否重复全文 Read 见策略）。
+
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **必填**。与 `.apm/workitems/<requirementId>/` 目录名一致。 |
+| **需求正文** | **唯一权威**：`.apm/workitems/<requirementId>/prd.md`。进入流程时须至少 **Read** 一次全文（是否在同一会话中重复读见「单会话读取策略」）。 |
+
+若 `prd.md` 不存在或不可读：先在仓库根目录执行 **`apm get requirement <requirementId>`**，该命令会下载最新的需求文档，再 **`Read`** 一次；仍不存在则**停止**并说明。**不要**用开放式提问代替 PRD；**不要**在缺 PRD 时继续生成工件。
+
+用户在本轮对话中的补充：仅在与 PRD 兼容时写入；若写入，在相关段落标注 **「会话补充（PRD 未载明）」**。
+
+---
+
+## Steps
+
+### 1. 锚定工作项与 PRD
+
+- 根路径：`.apm/workitems/<requirementId>/`。
+- 若尚无 `prd.md`：在仓库根目录执行 **`apm get requirement <requirementId>`**，再 **`Read` `prd.md` 全文**。若仍缺失则停止。
+- 已有则直接 `Read`：`prd.md` 全文。提取：目标用户/场景、范围、非目标、约束、验收口径。
+- PRD 未写明的：**不反问用户**；在后续工件的「假设 / 风险 / 待确认」中写明。
+- 必要时 **SemanticSearch** / **Read** 仓库代码，便于 `tasks.md` 中 **预期改动路径** 可落地；**不要**臆造 PRD 未给出的业务范围。
+
+### 2. 编排顺序与依赖出处
+
+- **依赖明细**（每个产出写入前须掌握哪些文件、不读哪些）：**只以**各 **`*-instruction.md`** 的 **「依赖」** 为准；不要在未读 instruction 的情况下凭记忆补依赖。
+- **撰写顺序（编排）**：
+  1. 先 **`proposal`**；再 **`design`** 与 **`specs`**（二者均只在 **`proposal` 落盘之后**撰写，**无**先后顺序要求，**互不**等待；**`specs` 是否读 `design`** 以 **`specs-instruction.md`** 为准）。
+  2. 最后 **`tasks`**：解锁条件以 **`tasks-instruction.md`**「依赖」为准（通常为 **`design` 与 `specs` 均已就绪**）。
+- **何时调用 Read**、如何避免重复读：下节 **「单会话读取策略」**。
+
+### 单会话读取策略（推荐）
+
+同一 Agent **连续一次跑完** proposal → design/specs → tasks 时，在**不违背各 instruction「依赖」、不少引用**的前提下减少重复 Read：
+
+| 类型 | 建议 |
+| --- | --- |
+| **`prd.md`** | 进入流程时 **Read 至少一次全文**。若本会话内已完整读过且无疑虑，写后续工件时**不必**为仪式感再次全文 Read；若 PRD **很长**、会话已很长、或需核对某条款，可对相关段落 **Read（偏移）** 或再读全文。 |
+| **`proposal.md`** | 落盘后，后续步骤以**磁盘文件**为准；若会话内已含刚写入的 proposal 全文，写 **design / specs** 时**可不重复 Read**，除非发现与磁盘不一致或需对账 Capabilities。 |
+| **`design.md` / `specs/`** | 写完并落盘后，写 **tasks** 时若会话内已无可靠记忆，应对 **`design.md`** 与 **`specs/` 下有关文件**执行 **Read**（至少覆盖 tasks 要引用的需求编号与路径）；若会话内仍完整持有二者内容，可直接撰写 tasks，**以落盘文件为最终依据**。 |
+| **`*-instruction.md`** | 每类工件在**首次**进入该工件撰写前 **Read** 对应 instruction **全文**一次即可；**不要**在同一轮流程里重复 Read 同一 instruction 文件，除非文件曾被改动或你从其他会话恢复。 |
+| **新会话 / 断点续写** | **不以**上表省略 Read：按各 **`*-instruction.md`「依赖」** 对**缺失或未确认的**文件重新 **Read**（通常以磁盘为准）。 |
+
+**不变原则**：**省略的是重复 Read**，不是省略各 instruction 写明的依赖关系；若本 SKILL 的编排顺序与某 **`*-instruction.md`「依赖」**冲突，**以该 instruction 为准**。
+
+使用 **TodoWrite** 跟踪四工件状态（`ready` / `blocked` / `done`）；**每完成一工件即落盘并标 `done`**，再解锁下一可写工件。**tasks** 条目中如何对照 specs、对齐 design 路径，以 **`tasks-instruction.md`** 为准。
+
+### 3. 生成各工件（按依赖解锁顺序）
+
+对当前工件：
+
+a. **掌握依赖内容**（见当前工件对应的 **`*-instruction.md`「依赖」** 与「单会话读取策略」）：按需 **Read**；**不要**把内部思考用标签（如 `<context>`）写进产出文件。
+
+b. **按各类工件的说明与模板**组织正文，内容严格以 **PRD** 为范围；说明文字**不**复制进产出文件。
+
+#### `proposal` → `proposal.md`
+
+- **Instruction**：按「单会话读取策略」读取 **`.apm/skills/apm-propose/propose-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/proposal.md`，严格遵循其中的 **Instruction** 与 **Template**（Why / What Changes / Capabilities / Impact）。
+- **Capabilities** 与后续 **`specs/*.md`** 一一可追溯；填写前可 **Read** `.apm/product-capability-inventory/` 等本仓库能力文档，避免与既有 CAP/命名冲突（路径以仓库实际为准）。
+- PRD 中有但 instruction 未列出的要点：在 **What Changes** 或 **Impact** 中体现；缺口/假设写在 **Why** 或 **Capabilities** 注释性短句中，**不反问用户**。
+
+#### `design` → `design.md`
+
+- **Instruction**：**`.apm/skills/apm-propose/design-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/design.md`，严格遵循其中的 **Instruction** 与 **Template**（Context、Goals/Non-Goals、Decisions、Risks/Trade-offs、Migration Plan、Open Questions）。
+- 说明「何时写满 / 可写精简版」的条件以 **design-instruction** 为准；与本仓库 **`tasks.md`** 的分工是：design 定方案与取舍，tasks 拆可执行步与 **预期改动路径**。
+
+#### `specs` → `specs/*.md`
+
+- **Instruction**：**`.apm/skills/apm-propose/specs-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/specs/` 下文件，严格遵循 **specs-instruction** 中的写作说明与模板（新增/变更/移除/重命名分块、`### 需求` / `#### 场景`、须/必须、**当**/**则** 等）。
+- **与 proposal 对齐**：**proposal** 能力列表中每一项须在 `specs/` 有对应；命名与 **`propose-instruction.md`** 短横线文件名约定一致；细则以 **specs-instruction** 为准。
+
+#### `tasks` → `tasks.md`
+
+- **Instruction**：**`.apm/skills/apm-propose/tasks-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准；写 **tasks** 时对**需求编号、路径、spec 条目**须有可靠依据，若会话内记忆不足则按「单会话读取策略」对相关落盘文件 **Read**。
+- **再写**：`.apm/workitems/<requirementId>/tasks.md`，严格遵循 **tasks-instruction**（**`- [ ]`**、分组 **`## 1.`**、编号 **1.1 / 2.1**、四条元数据子列表等）。
+- **口径**：做什么以 **specs** 为准，落在哪里以 **design** 为准；**预期改动路径** 与 design 一致。
+
+c. 每完成一个工件并落盘后，简短提示，如：`已创建 proposal` / `design` / `specs` / `tasks`。
+
+d. **不要**在依赖未满足时写下一工件（例如：`tasks` 不能在 `design` 或 `specs` 任一缺失时开写）。
+
+### 4. 全部就绪
+
+当 TodoWrite 中四个工件均为完成态，且无缺文件：
+
+- 汇总：工作项路径、已创建文件、PRD 与各工件的对应关系（一两句）。
+---
+
+## Output（对话中）
+
+完成全部工件后，回复须包含：
+- **工件列表**及各自一句话用途
+- **PRD 如何**映射到 proposal / design / specs / tasks
+
+---
+
+## Guardrails（对应原 Guardrails）
+
+- **跨工件一致**：后写须与 **PRD** 及已落盘的前序规划文件一致；各文件写什么、依赖谁、如何对齐 **proposal/specs/design**，**只以**各 **`*-instruction.md`** 为准（与 §3 相同来源，此处不重复展开）。
+- **产出纯净**：工作项下的 Markdown **不**夹带本 SKILL/对话中的内部推理、标签式草稿（参见 §3 步骤 a）。
+- **四个工件缺一不可**（specs 至少一个 `.md`）；遗漏则补全后再宣布完成。
+- **每写一个文件**：确认路径存在、内容非空后再进入下一工件。
+- **默认不覆盖**已存在的规划文件；若用户明确要求「整目录覆盖重生成」，可重写并声明覆盖范围。
+- **同名工作项目录**：以 `requirementId` 为唯一锚点。
+- **不向用户追问**需求细节以推进度；歧义写入假设或「待确认」。