ai-project-manage-cli 2.0.10 → 2.0.12

package/templates/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**：按「单会话读取策略」读取 **`.cursor/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**：**`.cursor/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**：**`.cursor/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**：**`.cursor/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` 为唯一锚点。
+- **不向用户追问**需求细节以推进度；歧义写入假设或「待确认」。

package/templates/skills/apm-propose/design-instruction.md

@@ -0,0 +1,94 @@
+# design 工件：写作说明
+
+生成 **`design.md`** 时说明 **如何实现**（HOW）：架构与决策为主，不写逐行代码。动机与范围以 **`proposal.md`** 为准，需求细节以 **`prd.md`** 与后续 **`specs/`** 为准。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| `.apm/workitems/<requirementId>/prd.md` | 约束、验收、业务事实 |
+| `.apm/workitems/<requirementId>/proposal.md` | Why / What / Capabilities / Impact |
+
+若 **`proposal.md` 不存在**，**不得**单独写 `design.md`（与 DAG 一致）。
+
+---
+
+## 输出路径
+
+- **`.apm/workitems/<requirementId>/design.md`**
+
+---
+
+## 何时需要写满设计文档
+
+若以下任一条成立，应写完整 **`design.md`**；若均不成立且变更极小，可写精简版，但仍建议保留 **Context** 与 **Decisions** 要点。
+
+- 跨模块/多服务，或引入新的架构模式  
+- 新外部依赖，或数据模型/API 有显著变更  
+- 安全、性能、迁移复杂度值得关注  
+- 需要先拍板技术方案再编码的模糊点  
+
+---
+
+## Instruction
+
+撰写技术设计：**偏架构与取舍**，不要替代 **`tasks.md`** 里的实现步骤枚举。
+
+**须覆盖的小节**：
+
+- **Context**：背景、当前状态、约束、干系人（可简写）
+- **Goals / Non-Goals**：本设计要达到什么、**明确不做什么**
+- **Decisions**：关键技术与选型，**每项**说明取舍与备选方案（为何 X 而非 Y）
+- **Risks / Trade-offs**：风险与妥协，格式建议：`[风险] → 缓解措施`
+- **Migration Plan**：上线/灰度/回滚步骤（不适用则写「无」或「不适用」）
+- **Open Questions**：尚未决定或待验证项
+
+写作时：**引用 proposal 的动机**；规格层行为以 **prd / specs** 为准，不在 design 里重复抄 specs 全文。重点是决策的 **why**。
+
+---
+
+## Template（产出 `design.md` 时按此结构填空）
+
+小节标题可使用英文如下，或改为中文等价（如 **Context** → **上下文**，**Decisions** → **技术决策** 等）。
+
+```markdown
+## Context
+
+<!-- 背景、现状、约束、干系人 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+
+<!-- 本设计要达成什么 -->
+
+**Non-Goals:**
+
+<!-- 明确不做的范围 -->
+
+## Decisions
+
+<!-- 关键选型：备选方案 + 取舍理由 -->
+
+## Risks / Trade-offs
+
+<!-- [风险] → 缓解 -->
+
+## Migration Plan
+
+<!-- 部署/迁移/回滚；无则说明 -->
+
+## Open Questions
+
+<!-- 待决问题；无则写 无 -->
+```
+
+---
+
+## Unlocks
+
+完成并落盘 **`design.md`** 后，与已完成的 **`specs/`** 一起解锁 **`tasks.md`**（`tasks` 须同时依赖二者）。

package/templates/skills/apm-propose/propose-instruction.md

@@ -0,0 +1,81 @@
+# proposal 工件：写作说明
+
+生成 **`proposal.md`** 时须建立 **「为何要做」**，并与后续 **`specs/`** 对齐：**Capabilities** 段落是 proposal 与 specs 之间的契约。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 输出路径
+
+- 工作项目录：`.apm/workitems/<requirementId>/`
+- 写入：**`.apm/workitems/<requirementId>/proposal.md`**
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | **唯一权威需求来源**；须全文阅读后再写 `proposal.md`。 |
+
+若工作项下尚无 **`prd.md`**：先在仓库根目录执行 **`apm get requirement <requirementId>`**，再 **Read**；仍缺失则**不得**生成 proposal（以 apm-propose **SKILL** 为准）。
+
+---
+
+## Instruction
+
+以 **`prd.md`** 为事实来源撰写变更提案（**Why**，不写实现细节；实现放在 `design.md`）。
+
+**篇幅**：精短，约 1～2 页等效内容均可。
+
+### 必含小节
+
+- **Why**：1～2 句话说明问题或机会——解决什么、为何是现在。
+- **What Changes**：要点列表，写清新增/修改/删除的能力；**破坏性变更**标注 **BREAKING**。
+- **Capabilities**：标明后续 **`specs/`** 要如何落文件——这是 proposal 与 specs 阶段的**契约**，填写前可检索仓库内既有能力文档（如 `.apm/product-capability-inventory/`）或相关 PRD/CAP 引用，避免与已有命名脱节。
+  - **New Capabilities**：新增能力，每一条对应本工作项下后续将新增的 **`specs/<kebab-name>.md`** 文件（例如 `user-auth`、`api-rate-limit`）。用 kebab-case 作文件名主干。
+  - **Modified Capabilities**：已有「规格层行为」将变更的能力（不仅是实现细节）。每条对应后续 **delta 规格**写法（可与 New 一样落在 `specs/<name>.md`，在文中标明相对既有行为的增量变更）。若无行为规格变化则留空或写「无」。
+- **Impact**：受影响的代码区域、API、依赖、系统或运维面。
+
+**注意**：Capabilities 里列出的每一项，都应在后续 **`specs/`** 中有可追溯对应（可一文件多条能力，但须在 specs 中写清）。
+
+---
+
+## Template（产出 `proposal.md` 时按此结构填空）
+
+小节标题可使用英文如下，或改为中文等价（如 **Why** → **背景与动机**，**What Changes** → **变更内容**，**Capabilities** → **能力范围**，**Impact** → **影响面**）。
+
+```markdown
+## Why
+
+<!-- 动机：解决什么问题？为何是现在？ -->
+
+## What Changes
+
+<!-- 具体变更要点；BREAKING 标注破坏性变更 -->
+
+## Capabilities
+
+### New Capabilities
+
+<!-- 每条对应后续 `specs/<kebab-name>.md` -->
+
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+<!-- 既有能力在规格层的行为变化；无则写 无 -->
+
+- `<existing-name>`: <what requirement behavior changes>
+
+## Impact
+
+<!-- 受影响代码、API、依赖、系统 -->
+```
+
+---
+
+## Unlocks
+
+完成并落盘 **`proposal.md`** 后，方可编写 **`design.md`** 与 **`specs/`**（二者仅依赖 proposal，可并行）。

package/templates/skills/apm-propose/specs-instruction.md

@@ -0,0 +1,114 @@
+# specs 工件：写作说明（供 apm-propose 读取）
+
+在工作项目录下生成 **`specs/`** 内的规格文件，定义系统 **应做什么**，与 **`design.md`**（如何实现）区分。内容须可验证：**每条「需求」下须有至少一个「场景」**。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须全文阅读）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | 业务事实、约束、验收；**唯一权威需求来源**。 |
+| **`.apm/workitems/<requirementId>/proposal.md`** | **能力范围**（新增能力 / 变更能力）；每项能力须在 `specs/` 中有对应文档；文件名用**短横线小写**（如 `user-auth`、`data-export`）。 |
+
+若无 **`proposal.md`**，不得编写 specs。若无 **`prd.md`**，按 apm-propose **SKILL** 先执行 **`apm get requirement <requirementId>`** 再读。
+
+**不依赖** **`design.md`**：specs 可与设计文档并行撰写，但须与 **proposal 中的能力约定**、**prd** 一致。
+
+---
+
+## 输出位置
+
+- 根目录：**`.apm/workitems/<requirementId>/specs/`**
+- 文件组织（须与 **`propose-instruction.md`** 及 proposal 中的能力列表一致）：
+  - **常用**：一能力一文件 **`specs/<短横线名称>.md`**
+  - **也可**：**`specs/<短横线名称>/规格.md`**（同一工作项内择一风格，勿混用）
+
+---
+
+## 写作说明
+
+### 与 proposal 对齐
+
+按 **`proposal.md`「能力范围」**逐条落地：
+
+- **新增能力**：每个名称对应一个上述路径下的文件，以 **「新增需求」** 类内容为主。
+- **变更能力**：在对应文件中用 **变更需求 / 移除需求 / 重命名需求** 等章节描述相对旧行为的变化。若仓库有既有能力说明，可先阅读 **`.apm/product-capability-inventory/`** 或相关能力文档以核对名称，**不得**虚构 prd、proposal 未出现的能力。
+
+### 变更分块（均使用二级标题 `##`）
+
+可按需组合多个分块：
+
+| 二级标题 | 用途 |
+| --- | --- |
+| **新增需求** | 全新能力或新需求条款。 |
+| **变更需求** | 行为有变：须写入**修改后的完整段落**（从「### 需求：」到其下全部场景），禁止只贴片段，以免后续对账丢失上下文。 |
+| **移除需求** | 下线或废弃：每条须写 **原因**、必要时写 **迁移说明**。 |
+| **重命名需求** | 仅名称变化：写清 **原名称**、**新名称**。 |
+
+若整份文件均为新能力，可只保留 **新增需求** 分块。纯新增内容放在 **新增需求**，不要用 **变更需求** 代替。
+
+### 单条需求结构
+
+- 需求标题：`**### 需求：<名称>**`，其下为正文。
+- **措辞**：对行为约束用 **须、必须** 等明确用语，避免「尽量、可以」之类除非 prd 明确要求弱化。
+- 场景标题：`**#### 场景：<名称>**`（场景标题固定用 **四个井号**，勿用三个，以免与需求层级混淆）。
+- 场景正文建议采用：
+  - `- **当** …`
+  - `- **则** …`
+- **每条需求至少包含一个场景。**
+
+### 变更类特别注意
+
+若产品清单或仓库中已有该能力的旧规格，应先找到旧全文，再整体放入 **变更需求** 下改写，**保持标题与结构便于对照**。
+
+若只是补充新条款、不改变已有行为，在 **新增需求** 中增加条目，勿用 **变更需求**。
+
+### 可验证性
+
+每个 **场景** 都能对应测试或验收步骤；后续 **`tasks.md`** 中的 **需求编号** 可与 **需求 / 场景** 标题互相对照。
+
+---
+
+## 单文件模板示例
+
+```markdown
+## 新增需求
+
+### 需求：<需求名称>
+系统须 <规范性行为，一条或多句表述清楚>。
+
+#### 场景：<场景名称>
+- **当** <前置或触发条件>
+- **则** <预期结果>
+
+## 变更需求
+
+### 需求：<与既有需求同一标题>
+<!-- 此处放完整替换后的需求正文及全部场景 -->
+
+#### 场景：<场景名称>
+- **当** …
+- **则** …
+
+## 移除需求
+
+### 需求：<需求名称>
+**原因**：……  
+**迁移说明**：……
+
+## 重命名需求
+
+- **原名称：** …
+- **新名称：** …
+```
+
+按实际只保留需要的 `##` 分块；不需要的整块省略。
+
+---
+
+## 与后续工件的关系
+
+本目录与 **`design.md`** 均完成后，方可编写 **`.apm/workitems/<requirementId>/tasks.md`**。

package/templates/skills/apm-propose/tasks-instruction.md

@@ -0,0 +1,90 @@
+# tasks 工件：写作说明（供 apm-propose 读取）
+
+生成 **`tasks.md`**：把实现工作拆成**可勾选、可追踪**的条款。后续 **apm-apply-change** 依赖 **`- [ ]` / `- [x]`** 勾选推进，格式须严格遵守。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | 范围与验收 |
+| **`.apm/workitems/<requirementId>/proposal.md`** | 动机与能力边界 |
+| **`.apm/workitems/<requirementId>/design.md`** | 如何做、模块与路径 |
+| **`.apm/workitems/<requirementId>/specs/`** | 须做什么、需求与场景 |
+
+若 **`design.md` 或 `specs/`**（至少一个规格文件）尚未就绪，**不得**编写 **tasks.md**。
+
+---
+
+## 输出路径
+
+**`.apm/workitems/<requirementId>/tasks.md`**
+
+---
+
+## 写作说明
+
+### 格式（须严格遵守）
+
+- **每一条待办必须是复选框**：行首 **`- [ ]`**（半角方括号、半角空格）。**不用** `- [ ]` 的行在实现阶段**无法被可靠追踪**。
+- **按主题分组**：使用带序号的二级标题，例如 **`## 1. 环境准备`**、**`## 2. 核心实现`**。
+- **任务编号**：组内序号 **`组号.序号`**，与描述同一行，例如 **`- [ ] 1.1 初始化数据模型`**、**`- [ ] 2.1 实现导出接口`**。
+- **粒度**：每项宜在一次会话内能做完；过粗则拆，过细可按模块合并。
+- **顺序**：按**技术依赖**排列（例如契约/数据先于接口/UI）。
+
+### 每条任务须带的元数据（缩进子列表）
+
+紧接在 **`- [ ]` 行下方**，用无序列表写出（便于人工与 Agent 对照）：
+
+| 字段 | 说明 |
+| --- | --- |
+| **需求编号** | 对应 **specs** 中 **### 需求：** 或 **#### 场景：** 的可识别标题/编号 |
+| **预期改动路径** | 计划修改或新增的文件/目录（可多条） |
+| **验证用例编号** | 可选；与测试或验收条目对应 |
+| **完成标准** | 可观察的完成判据（与 specs 场景可对照） |
+
+示例：
+
+```markdown
+## 1. 数据层
+
+- [ ] 1.1 新增合同状态字段
+  - **需求编号**：需求：合同状态同步（见 specs/contract.md）
+  - **预期改动路径**：`servers/be/prisma/schema.prisma` …
+  - **完成标准**：迁移可执行；已有合同默认状态正确
+```
+
+### 内容来源
+
+- **做什么、验收什么**：以 **specs** 为主，**prd** 补业务约束。
+- **改哪里、怎么迁**：以 **design** 为主，**预期改动路径**须与 design 中的模块划分**一致**；必要时 **SemanticSearch** 仓库以填路径。
+
+### 可验证性
+
+每条任务应有明确「做完」的样子；**完成标准** 应能让评审者或自己判断无需再猜。
+
+---
+
+## 模板示例
+
+```markdown
+## 1. <!-- 分组名称，如：准备 -->
+
+- [ ] 1.1 <!-- 简短任务说明 -->
+  - **需求编号**：…
+  - **预期改动路径**：…
+  - **验证用例编号**：（可选）…
+  - **完成标准**：…
+
+## 2. <!-- 分组名称，如：核心实现 -->
+
+- [ ] 2.1 …
+  - **需求编号**：…
+  - **预期改动路径**：…
+  - **完成标准**：…
+```
+
+---

package/templates/skills/code-change-summary/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: code-change-summary
+description: 在功能分支上相对基线分支（可指定，未指定则用 main/master）生成代码变更摘要；须提供需求 id，结果落盘至 `.apm/workitems/<需求id>/change.md`；对话中只汇报步骤结果、不输出文件正文。用户主动触发，例如在对话中提及本技能时调用。
+---
+
+# 代码变更摘要
+
+**目的**：把相对基准分支的改动整理成可读的摘要，便于评审或交接。输出**只包含**下列四类（与 `summary-template.md` 四节一一对应；顺序可调整；无内容按模板留空或写「无」）：
+
+1. **修改原因**：需求/问题背景（仅来自已提供的需求、Issue、说明；**无则留空或「无」，禁止猜测**）。
+2. **改了什么**：涉及哪些路径、整体做了什么（归纳为主，可附文件列表）。
+3. **为什么这么改**：按文件或文件组，说明技术层面的修改动机；**可用 Markdown 表格**（例如列为「路径/文件（组）」「修改原因」）呈现，便于扫读。
+4. **复杂逻辑与编写思路**：有复杂处再展开；否则一句话带过。
+
+## 输入
+
+- **需求 id**（**必填**）：工作项 / 需求唯一标识；用于落盘路径与正文元数据。对话中未给出时，**须先向用户索要**，不得用占位符或猜测值继续生成。
+- **基线分支**（对比起点）：用户可在对话中**明确指定**（例如「相对 `develop` 的变更」）。**未指定**时，在仓库中选用 **`main` 或 `master`**：优先使用存在的 `refs/heads/main`，否则使用 `refs/heads/master`（可用 `git show-ref`、`git rev-parse --verify` 等只读命令确认）。
+- 后续所有 `git log` / `git diff` 均相对该基线分支与当前 `HEAD` 进行比较。
+
+## 触发前提
+
+- **仅在新分支执行**：当前分支必须不是 `main` 或 `master`
+- **用户主动触发**：当用于在对话中提及本技能时触发
+- **已提供需求 id**：无则仅提示补充，不生成、不落盘
+
+## 核心原则
+
+- **依据**：第 1 点只能写「有据可查」的背景；第 2、3 点须与 `git diff`（及对话中用户补充的事实）对齐，不臆测改动意图。
+- **写法**：以归纳与说明为主，**禁止**大段粘贴源码；复杂逻辑用自然语言 / 小标题写清思路即可。
+
+## 执行流程
+
+1. **确定基线并获取变更**（只读 git）：先按上文「输入」解析出 `{BASE_BRANCH}`，记为 `BASE`（用户指定名，或 `main` / `master` 中实际存在的那一个）。
+
+```bash
+git branch --show-current
+git log BASE..HEAD --oneline
+git diff BASE..HEAD --name-status
+git diff BASE..HEAD            # 必要时查看具体 diff
+```
+
+2. **整理「改了什么」**：从 `--name-status` 与 diff 归纳模块、变更类型（新增/修改/删除）与一句话范围。
+
+3. **整理「为什么这么改」**：按文件或文件组，对照 diff 说明动机（修 bug、接新需求、重构、命名约定等）；**推荐用表格**输出，见模板中 `{WHY_PER_FILE}` 填法。
+
+4. **判断是否需要「复杂逻辑与编写思路」**：多文件联动、新抽象、状态机、非直观算法等则展开；否则第四节用一句话带过。
+
+5. **修改原因**：若用户本次对话或链接中**没有**需求描述，该节为空或「无」；若用户粘贴了需求，再提炼为简短背景。
+
+6. **填充模板**：`summary-template.md`，替换全部占位符（含 `{WORKITEM_ID}`）。
+
+7. **交付（落盘）**：
+
+   - **路径**（相对仓库根）：`.apm/workitems/<需求id>/change.md`（`<需求id>` 为输入中的需求 id，与目录名一致）。
+   - **内容**：填充后的完整 Markdown；**勿包含**模板末尾的 `<!-- 填法... -->` 注释块。
+   - **目录**：若 `.apm/workitems/<需求id>/` 不存在则创建后再写入。
+
+## 对话中的汇报
+
+- **只汇报各步骤的执行结果**（例如：基线已解析为 `main`、已读取 diff、已填充模板、已写入某路径）。**不要**在对话中输出、复述或摘要 **`change.md` 的文件内容**（全文与片段均不要），除非用户**另行明确要求**查看。
+
+## 模板占位符
+
+模板路径：`summary-template.md`。
+
+| 占位符 | 含义 |
+|--------|------|
+| `{WORKITEM_ID}` | 需求 id（与输入一致，写入正文元数据） |
+| `{BRANCH_NAME}` | 当前分支名 |
+| `{DATE}` | 生成日期 |
+| `{BASE_BRANCH}` | 本次对比使用的基线分支名（用户指定，或未指定时解析得到的 `main` 或 `master`） |
+| `{CHANGE_REASON}` | 修改原因（无则空或「无」） |
+| `{WHAT_CHANGED}` | 改了什么（文件与归纳） |
+| `{WHY_PER_FILE}` | 为什么这么改（按文件/文件组；**可用表格**，见模板填法） |
+| `{COMPLEX_LOGIC_RATIONALE}` | 复杂逻辑与编写思路（无则简短声明） |
+
+**各占位符的正文结构与填法**：见模板**文件末尾** `<!-- ... -->` 注释。生成最终 Markdown 时**不要输出该 HTML 注释块**。
+
+## 实现注意
+
+- 只读命令：`git branch`、`git diff`、`git log`、`git show-ref`、`git rev-parse`
+- 未指定基线时：优先选用本地存在的 `main`，否则 `master`；若用户指定了其他分支名，则必须以该分支为 `BASE`（需存在且可解析）
+- 落盘：写入 `.apm/workitems/<需求id>/change.md`；`<需求id>` 中含路径不安全字符时，按操作系统与团队约定处理（一般需求 id 为字母数字与 `-`/`_`）

package/templates/skills/code-change-summary/summary-template.md

@@ -0,0 +1,55 @@
+# 代码变更摘要 - {BRANCH_NAME}
+
+**需求 ID**：{WORKITEM_ID}  
+**生成时间**：{DATE}  
+**对比基准**：{BASE_BRANCH}
+
+---
+
+## 修改原因
+
+{CHANGE_REASON}
+
+---
+
+## 改了什么
+
+{WHAT_CHANGED}
+
+---
+
+## 为什么这么改
+
+{WHY_PER_FILE}
+
+---
+
+## 复杂逻辑与编写思路
+
+{COMPLEX_LOGIC_RATIONALE}
+
+<!--
+填法（勿粘贴到最终输出）：输出时去掉本注释块。
+
+{WORKITEM_ID}
+- 与技能输入中的**需求 id**一致；同时用于落盘路径 `.apm/workitems/<需求id>/change.md`。
+
+{CHANGE_REASON}
+- 从用户给出的需求、Issue、PR 描述、产品说明等**已提供信息**中提炼背景与动机；若对话或仓库中**没有**可依据的叙述，本小节只保留标题下空行或写「无」（**禁止臆测、补全故事**）。
+
+{WHAT_CHANGED}
+- 基于相对**基线分支**（`{BASE_BRANCH}`）的 `git diff BASE..HEAD` / `--name-status` 归纳：涉及哪些路径、增删改概况；可按「模块 / 职责」分组一句话概括，避免把 diff 全文当正文。
+
+{WHY_PER_FILE}
+- **按文件**（或关系密切的一组文件合并成一条）说明本次修改的直接原因：解决什么问题、与相邻改动的关系；与「改了什么」对应，避免重复贴代码。
+- **呈现**：优先使用 Markdown **表格**，列建议包含「路径 / 文件（组）」与「修改原因」；文件很多时可按目录或模块合并行。示例：
+
+| 路径 / 文件（组） | 修改原因 |
+| --- | --- |
+| `path/to/a.ts` | … |
+| `path/to/`（多文件） | … |
+
+{COMPLEX_LOGIC_RATIONALE}
+- **仅当**存在非显而易见的控制流、状态机、并发、算法、跨层协议时再写；简单字段增删、重命名、配置替换可写「本次无复杂逻辑需单独说明。」或等价一句。
+- 内容侧重：**为何这样拆分**、数据流/调用链、关键取舍；禁止大段粘贴源码。
+-->