ai-project-manage-cli 2.0.11 → 2.0.13

package/templates/skills/apm-fixbug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apm-fixbug
-description: 基于分支名和缺陷描述执行标准化的缺陷修复流程：先做工作区检查点提交，再切换分支、完成修复、生成发布检查清单、落盘 bugfix 留痕，并提交推送分支；当用户明确声明使用该技能是触发。
+description: 基于 requirementId 与 `.apm/workitems/<id>/bugs/` 下的 status.yaml、缺陷 Markdown 执行标准化缺陷修复：开发前准备 → 按「待处理」循环修复并落盘复盘 → 推送 → 调用 code-deploy 部署测试环境；当用户明确声明使用该技能时触发。
 ---
 
 # 缺陷修复流程
@@ -8,152 +8,90 @@ description: 基于分支名和缺陷描述执行标准化的缺陷修复流程
 ## 目的
 
 使用本技能可基于以下输入执行一致的端到端缺陷修复流程：
-- `branchName`：目标分支名
-- `bugDescription`：清晰的缺陷描述与期望行为
-- `defectId`：缺陷 ID（可选；用于调用 CLI 更新缺陷状态）
+- `requirementId`：需求 id（与 `.apm/workitems/<requirementId>/` 目录一致）
+- 缺陷清单以 `apm get defect <requirementId>` 同步后的本地文件为准（见步骤 1）
 
-**主 Agent 收尾（必选）**：在协调子 Agent 完成步骤 1～8 后，**必须在面向用户的最终回复中附上一张 Markdown 表格**，逐行对应每个步骤，汇总**执行状态**（如：已完成 / 已跳过 / 失败）与**简要说明**（关键结果、commit、失败原因等），便于审阅者核对流程是否闭环。
+**主 Agent 收尾（必选）**：在协调子 Agent 完成各步骤后，**必须在面向用户的最终回复中附上一张 Markdown 表格**，逐行对应每个步骤，汇总**执行状态**（如：已完成 / 已跳过 / 失败）与**简要说明**（关键结果、commit、失败原因等），便于审阅者核对流程是否闭环。
 
 ## 输入
 
-收集并确认：
-- `branchName`
-- `bugDescription`
-- `defectId`（可选）
+**输入（必填）** `requirementId`：需求 id
 
-若 `branchName` 或 `bugDescription` 缺失，需先向用户补充确认后再继续。
+## 本地缺陷文件约定（必读）
 
-## 执行步骤
-
-严格按以下顺序执行，且每一步都必须由子 Agent 独立执行并回传结果。
-
-### 步骤 1 — 子 Agent：分支切换与未提交处理
-
-1. 执行 `git fetch origin`，确保可获取最新远程分支信息。
-2. 记录 `TARGET=<branchName>` 与当前分支 `CURRENT`，并检查工作区是否有未提交变更（staged/unstaged/untracked）。
-3. 若 `CURRENT != TARGET` 且工作区有变更：先执行 `git stash push -u` 保存现场，再切换到 `TARGET`。
-4. 若 `CURRENT == TARGET` 且工作区有变更：不要 stash，直接将当前改动作为“修复前检查点”提交，提交文案需明确说明这是 bugfix 前的检查点（例如：`chore: checkpoint before bugfix on <branchName>`）。
-5. 切换到 `TARGET`：本地分支不存在时，从远程跟踪分支创建并切换。
-6. 若在第 3 步执行过 stash，切换成功后不要自动 `stash pop`，避免与后续修复流程冲突。
-7. 最终必须确认当前分支与 `branchName` 完全一致。
-
-**完成判定**：当前分支等于 `branchName`，且步骤 3/4 的语义已正确执行（按分支状态选择了 stash 或 checkpoint commit）。
-
-### 步骤 2 — 子 Agent：按缺陷描述修改代码
-
-1. 基于 `bugDescription` 复现并分析缺陷。
-2. 实施最小化、针对性的修复。
-3. 运行相关验证（tests/lint/build 或最接近的校验命令）。
-4. 若验证失败，持续迭代直至通过；如遇阻塞，输出具体报错信息并说明阻塞点。
-
-**完成判定**：修复代码已落地，且验证通过；或明确输出可复现的阻塞错误与原因。
-
-### 步骤 3 — 子 Agent：更新分支对应的变更说明文件
-
-代码改动稳定后，必须调用技能 `mr-review-brief` 生成评审说明内容；随后定位当前分支产出的 workitem 名称 `<name>`，并处理 `.apm/workitems/<name>/change.md`：
-- 若文件不存在：创建该文件并写入本次变更说明。
-- 若文件已存在：在原文件上更新内容，反映本次最新变更。
-
-变更说明应包含：
-- 功能变更摘要
-- 自检项
-- 发布备注/注意事项
+同步命令 `apm get defect <requirementId>` 会在如下路径落盘（**不要**臆造路径）：
 
-注意：`<name>` 必须取当前分支对应且由本分支产出的 workitem，禁止误用其他分支的 `<name>`。
+- 状态汇总：`.apm/workitems/<requirementId>/bugs/status.yaml`  
+  - 结构示例：根键 `defects`，下挂 `"<缺陷数字 id>"`，每项含 `status`，取值为中文：**已创建**、**待处理**、**处理中**、**待验证**、**已解决**、**重新打开**（与 CLI 生成一致）。
+- 缺陷正文：`.apm/workitems/<requirementId>/bugs/<id>.md`（`<id>` 与 `status.yaml` 中键一致）
 
-**完成判定**：`.apm/workitems/<name>/change.md` 已创建或更新，且内容包含功能变更摘要、自检项、发布备注/注意事项。
+本流程**仅将「待处理」视为待修复队列**；循环直至不存在状态为「待处理」的缺陷后，进入部署步骤。
 
-### 步骤 4 — 子 Agent：提交修复改动（不推送）
-
-1. 先执行 `git status`；若存在未跟踪或已修改文件，执行 `git add -A`。
-2. 若存在暂存变更，则执行 `git commit`；commit 文案必须明确描述“本次改了什么”，必要时补充变更原因。
-3. 记录本次 bugfix 提交的 `commit id`（例如 `git rev-parse --short HEAD`），供下一步留痕文件使用。
-
-**完成判定**：本次 bugfix commit 已创建成功，且已拿到对应 `commit id`。
-
-### 步骤 5 — 子 Agent：落盘 bugfix 留痕文档
-
-在完成步骤 4 后，定位当前分支产出的 workitem 名称 `<name>`，在 `.apm/workitems/<name>/` 下写入本次留痕文档：
-
-1. 文件名规则：`bugfixN.md`，其中 `N` 为递增序号（`1/2/3/...`）。
-   - 若目录中无 `bugfix*.md`，创建 `bugfix1.md`。
-   - 若已有 `bugfix1.md`、`bugfix2.md`...，本次创建下一个序号文件（如 `bugfix3.md`）。
-2. 文档内容必须包含以下结构（按顺序）：
-   - 一级标题：`# <commit id>`（标题直接使用步骤 4 产出的 commit id）
-   - `## Bug 描述`：写入 `bugDescription` 的关键信息
-   - `## 解决方案`：说明本次修复的实现方案
-   - `## 原因复盘`：说明问题根因、为何发生、后续如何避免
-3. 该文件用于沉淀每次 bug 修复记录，禁止覆盖历史 `bugfixN.md`。
-4. 写入内容时使用以下固定模板（将占位符替换为实际内容）：
-
-```markdown
-# <commit id>
-
-## Bug 描述
-<一句话描述现象 + 影响范围>
-
-## 解决方案
-- <改动点 1>
-- <改动点 2>
-
-## 原因复盘
-- 根因：<根因说明>
-- 触发条件：<在什么条件下触发>
-- 防再发措施：<测试/校验/流程上的防护>
-```
+## 执行步骤
 
-注意：`<name>` 必须取当前分支对应且由本分支产出的 workitem，禁止误用其他分支的 `<name>`。
+严格按以下顺序执行，且每一步都必须由子 Agent 独立执行并回传结果。
 
-**完成判定**：`.apm/workitems/<name>/bugfixN.md` 创建成功，且内容包含 commit id、Bug 描述、解决方案、原因复盘四部分。
+### 步骤 1 — 子 Agent：开发前的准备
 
-### 步骤 6 — 子 Agent：推送分支提交
+1. 执行 `apm get branchName <requirementId>` 获取目标开发分支名 `branchName`。
+2. 开发工作区准备
+   1. 执行 `git fetch origin`，确保可获取最新远程分支信息。
+   2. 记录 `TARGET=<branchName>` 与当前分支 `CURRENT`，并检查工作区是否有未提交变更（staged/unstaged/untracked）。
+   3. 若 `CURRENT != TARGET` 且工作区有变更：先执行 `git stash push -u` 保存现场，再切换到 `TARGET`。
+   4. 若 `CURRENT == TARGET` 且工作区有变更：不要 stash，直接将当前改动作为「修复前检查点」提交，提交文案需明确说明这是 bugfix 前的检查点（例如：`chore: checkpoint before bugfix on <branchName>`）。
+   5. 切换到 `TARGET`：本地分支不存在时，从远程跟踪分支创建并切换。
+   6. 若在第 3 步执行过 stash，切换成功后不要自动 `stash pop`，避免与后续修复流程冲突。
+   7. 最终必须确认当前分支与 `branchName` 完全一致。
+3. 执行 `apm get defect <requirementId>` 同步 BUG 状态与内容到 `.apm/workitems/<requirementId>/bugs/`（含 `status.yaml` 与各 `<id>.md`）。
 
-1. 必须将 `branchName` 推送到远程：优先使用 `git push -u origin "<branchName>"`；若当前分支已配置 upstream，可直接 `git push`。
-2. 若推送失败，输出失败原因并将流程标记为失败，不得宣称完成。
+**完成判定**：已在目标分支上，且本地 bugs 目录已与远端缺陷列表同步。
 
-最低完成标准：
-- 推送成功
-- 工作区干净（或仅保留需用户自行处理的 stash 提示）
+### 步骤 2 — 子 Agent：按 bugs 清单循环修复
 
-**完成判定**：推送成功，且满足最低完成标准。
+#### 2.1 每轮开始：确定队列并登记 Todo
 
-### 步骤 7 — 子 Agent：可选调用 CLI 更新缺陷状态为已解决
+1. 使用 **Read** 读取 `.apm/workitems/<requirementId>/bugs/status.yaml`，解析 `defects` 下各缺陷的 `status`，**仅**将状态为 **「待处理」** 的缺陷 id 列入本轮待办。
+2. 调用 **TodoWrite**，为当前所有仍处于「待处理」的缺陷各建一条 todo（标题或内容中写明缺陷 id），用于跟踪处理进度；后续每完成一个缺陷的闭环（至「待验证」并已推送）后，须将该缺陷对应 todo 标为已完成，并在下一轮开始时可按最新 `status.yaml` 刷新待办列表。
 
-1. 仅当输入包含 `defectId` 时才执行本步骤；若未提供 `defectId`，则跳过并继续完成流程。
-2. 在仓库根目录调用 CLI，将当前缺陷状态更新为 `RESOLVED`：
+若**没有任何**「待处理」缺陷：跳过 2.2，直接进入**步骤 3**。
 
-```bash
-apm requirement defect set-status --defect-id <defectId> --status RESOLVED
-```
+#### 2.2 单个缺陷处理（对其中一个「待处理」缺陷执行；完成后回到 2.1）
 
-3. 若命令执行失败，输出 stderr 并将流程标记为失败。
+1. **读取缺陷文档**：根据 `status.yaml` 中的缺陷 id，用 Read 读取同目录下的 `<id>.md`（例如 `123.md`）。
+2. **标为处理中**：将该缺陷在 `status.yaml` 中的 `status` 改为 **「处理中」**；并在同一 `<id>.md` 中同步该状态（例如在文首增加一行 `**状态**：处理中`，或新增 `## 状态` 小节——全仓库保持一致即可），保证 YAML 与 Markdown 一致。**随后**执行 `apm status defect <id>`（`<id>` 与 `status.yaml` 键、文件名一致），由服务端按当前状态自动流转（此处应为「待处理」→「处理中」）；若命令失败，不得进入本缺陷的代码修复，须先排查登录/权限或与服务端状态是否一致。
+3. **修复代码**：依据 `<id>.md` 中的缺陷描述复现、定位并实施**最小化**修复；运行相关验证（tests / lint / build 或项目最接近的校验命令），失败则迭代直至通过或明确输出阻塞信息。
+4. **复盘落盘**：在**同一** `<id>.md` 中**新增**二级标题 `## 复盘`，将根因分析、结论与必要说明写在**该标题下**（勿覆盖「缺陷内容」等与同步相关的固定段落）。
+5. **标为待验证**：将该缺陷在 `status.yaml` 中的 `status` 改为 **「待验证」**；并同步更新 `<id>.md` 中的状态展示，与 YAML 一致。**随后**执行 `apm status defect <id>`，由服务端按当前状态自动流转（此处应为「处理中」→「待验证」）；若命令失败，不得进入提交推送步骤，须先修复阻塞（含服务端状态与本流程不一致的情况）。
+6. **提交并推送**：执行 `git add -A`（或按项目规范纳入本次改动），`git commit`，提交说明须能识别对应缺陷（含 id 或标题关键词）；将当前分支推送到远程（`git push` 或 `git push -u origin "<branchName>"`）。推送失败则本流程标记失败并停止，不得宣称该缺陷已闭环。
+7. **循环**：回到 **2.1**（重新 Read `status.yaml`、更新 TodoWrite），继续处理剩余的「待处理」缺陷，直至不存在「待处理」。
 
-**完成判定**：未提供 `defectId` 时本步骤被正确跳过；提供 `defectId` 时 CLI 返回成功且缺陷状态为 `RESOLVED`。
+**完成判定**：`status.yaml` 中已无非预期的「待处理」项（全部已按流程进入「待验证」或同步结果本身无待处理项）；且每次提交均已推送成功。
 
-### 步骤 8 — 子 Agent：调用 `test-env-release` 部署测试环境
+### 步骤 3 — 子 Agent：部署测试环境
 
-1. 本步骤必须在“全部代码提交完成”后执行（至少已完成步骤 4；若有推送要求则需先完成步骤 6）。
-2. 调用技能 `test-env-release`，按项目根目录 `.apm/deploy/README.md` 部署测试环境。
-3. 若部署失败，输出失败原因并将流程标记为失败，不得宣称 bug-fix 全流程完成。
+1. 本步骤须在**步骤 2 的循环结束后**执行（所有待处理缺陷已处理完毕，或同步后本就没有待处理项）。
+2. 调用技能 **`code-deploy`**，按目标项目根目录 `.apm/deploy/README.md` 执行部署；**未说明目标环境时，以 `code-deploy` 技能为准，默认部署到测试环境**。
+3. 若部署失败，输出失败原因并将流程标记为失败，不得宣称全流程完成。
 
-**完成判定**：`test-env-release` 执行成功，测试环境部署完成。
+**完成判定**：`code-deploy` 按该技能约定执行完毕且未判定为失败。
 
 ### 汇总表格式（主 Agent 最终输出）
 
-主 Agent 在流程结束时的表格应至少包含以下列，行数覆盖步骤 1～8（步骤 7 未提供 `defectId` 时可为「已跳过」）：
+主 Agent 在流程结束时的表格应至少包含以下列，行数覆盖**步骤 1～3**：
 
 | 步骤 | 内容概要 | 状态 | 说明 |
 |------|----------|------|------|
-| 1 | 分支切换与未提交处理 | 已完成 | 例：当前分支 `feat/xxx`，已 checkpoint / stash |
-| 2 | 按缺陷描述修改代码 | 已完成 | 例：验证通过（lint/test） |
-| … | … | … | … |
+| 1 | 分支与工作区准备、同步 defect | 已完成 | 例：已在 `feat/xxx`，已 `apm get defect` |
+| 2 | 读取 status.yaml、TodoWrite、循环修复与推送 | 已完成 | 例：3 个缺陷已待验证，commit `abc123`，已 push |
+| 3 | code-deploy 测试环境 | 已完成 | 例：已按 `.apm/deploy/README.md` 执行 |
 
 状态列建议统一用语：`已完成`、`已跳过`（并写明跳过原因）、`失败`（并附报错或阻塞点）。
 
 ## 约束
 
 - 主 Agent 交付本流程结果时，应以「步骤汇总表」为主、文字为辅；禁止仅用零散叙述代替逐步状态说明。
-- 存在未提交变更时，禁止跳过步骤 1。
-- 当前分支错误时，禁止继续后续步骤。
-- 步骤 8 完成前，不得宣称完成。
-- 修复必须保持最小改动，并与 `bugDescription` 保持一致。
+- 存在未提交变更时，禁止跳过步骤 1 中的工作区与分支整理（除非该步已明确处理）。
+- 当前分支与 `branchName` 不一致时，禁止进入步骤 2 的修复循环。
+- **仅**根据 `status.yaml` 中 **「待处理」** 驱动修复队列，不要跳过 Read / TodoWrite 的登记与更新。
+- 修复须保持最小改动，并与 `<id>.md` 中的缺陷描述一致。
+- 步骤 3 完成前，不得宣称「缺陷修复与部署全流程」已完成。

package/templates/skills/apm-release/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: apm-release
+description: 需求上线：取分支 → 切分支并拉最新 → code-deploy 正式环境 → apm release 同步状态。用户 @ 本技能时使用。
+---
+
+# 需求上线（apm-release）
+
+## 输入
+
+- **`requirementId`（必须）**：需求主键 ID。
+- **`-f` / `--force`（可选，默认不加）**：仅当用户在对话中**明确表态**「不用走代码审核 / 不审代码直接上线 / 合并 PR 即可」等同类含义时，第 4 步的 `apm release` 才增加 **`-f`**（与 CLI 一致：创建 PR 后对其实施 squash 合并）。**用户未明确说时一律不带 `-f`**，不得自行替用户决定。
+
+## 执行顺序（严格 1 → 2 → 3 → 4）
+
+### 第 1 步 — 获取分支名
+
+执行：
+
+```bash
+apm get branchName <requirementId>
+```
+
+从标准输出读取**一行分支名**，记为 `BRANCH`。若命令失败，**不要继续第 2、3 步**，直接进入第 4 步（见下：若拿不到 `BRANCH`，`-b` 无法填写时须在对话中说明，并按失败场景处理）。
+
+**对话输出**：本步结束后，在回复中写明**执行状态**（成功/失败）与**结果**（分支名或报错摘要）。
+
+### 第 2 步 — 切分支并拉取最新
+
+1. 若工作区有未提交变更（含未跟踪文件按项目习惯）：先 `git stash`（或等价方式）保存，再切分支。
+2. `git checkout <BRANCH>`（已在该分支可跳过 checkout）。
+3. `git pull`（或 `git fetch` + 与项目一致的合并方式），确保当前分支与远程一致、代码最新。
+4. **合并冲突时**（pull/merge 产生冲突）：
+   - 可先**自行解决**，但**只处理**与本次需求意图**明显无冲突**的情形（例如无关文件、能明确判定为可安全合并的变更）。
+   - 一旦出现**无法分辨**的冲突（说不清是否影响本需求、怀疑与需求意图相悖、或不能确信合并结果正确）：**立即判定本步骤失败**，**不要**猜测性选边或强行合并；进入第 4 步，`-r` 用简短说明（如 `pull 冲突无法安全解决`）。
+
+任一步失败则**停止第 3 步**，进入第 4 步。
+
+**对话输出**：本步结束后，在回复中写明**执行状态**与**结果**（当前分支、pull 是否成功、stash 是否使用、若有冲突则是否已解决或已判失败等）。
+
+### 第 3 步 — 部署正式环境
+
+调用 **`code-deploy` 技能**：按项目 `.apm/deploy/README.md`（或技能约定）部署**线上/正式环境**。
+
+失败则**停止**，进入第 4 步。
+
+**对话输出**：本步结束后，在回复中写明**执行状态**与**结果**（部署是否完成、关键输出摘要）。
+
+### 第 4 步 — 同步状态（`apm release`）
+
+**始终在本流程末尾执行本步**（前面任一步失败也要执行，用于同步服务端状态）。
+
+```bash
+apm release <requirementId> -b <BRANCH>
+# 用户已明确「不审代码直接上线」时（见上文「输入」）：
+apm release <requirementId> -b <BRANCH> -f
+```
+
+- **第 1～3 步全部成功**：带 `-b`；**仅**在用户已明确要求时再加 `-f`。不带 `-r`。
+- **任一步失败**：带 `-b` 与 **`-r`**，`reason` 为**简短**失败说明（十来字～一两行），不要把整段日志塞进 `-r`。**失败路径不要加 `-f`**（`-f` 只用于成功同步且用户明确要跳审合并的场景）。
+
+示例：
+
+```bash
+apm release <requirementId> -b <BRANCH> -r "获取分支失败"
+apm release <requirementId> -b <BRANCH> -r "git pull 冲突"
+apm release <requirementId> -b <BRANCH> -r "code-deploy 失败"
+```
+
+若第 1 步未得到 `BRANCH`，无法在命令行合法填写 `-b` 时：在对话中说明阻塞原因；若能从用户或环境确认分支名再补 `-b`，否则不要编造分支名。
+
+## 对话输出（必选）
+
+**第 1～3 步**在面向用户的回复中用下面表格呈现（每步一行；未执行的步骤填「未执行」及原因）：
+
+| 步骤 | 状态 | 结果/说明 |
+|------|------|-----------|
+| 1 获取分支名 | 成功 / 失败 / 未执行 | 分支名或报错摘要 |
+| 2 切分支并拉取 | 成功 / 失败 / 未执行 | 当前分支、pull/stash/冲突处理摘要 |
+| 3 code-deploy | 成功 / 失败 / 未执行 | 部署是否完成、关键输出摘要 |
+
+**第 4 步**：在表格后另起一段说明是否执行 `apm release`、是否带 **`-r`**、是否因用户明确要求而带 **`-f`**、命令是否成功。
+
+## 约束
+
+- `-r` 仅用于概括失败类型，详细日志放在对话说明里。
+- **`-f`**：仅在用户**明确口头表达**「不审代码直接上线」等含义时使用；不得因图省事或默认假设而加 `-f`。
+- 不要为「碰运气」重复执行同一意图的 `apm release`；成功路径 `-b`（无 `-r`）与失败路径 `-b -r` 各以一次为常例。