ai-project-manage-cli 3.0.3 → 3.0.5

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

@@ -0,0 +1,94 @@
+# design 工件：写作说明
+
+生成 **`design.md`** 时说明 **如何实现**（HOW）：架构与决策为主，不写逐行代码。动机与范围以 **`proposal.md`** 为准，需求细节以 **`prd.md`** 与后续 **`specs/`** 为准。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/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/template/skills/apm-propose/propose-instruction.md

@@ -0,0 +1,81 @@
+# proposal 工件：写作说明
+
+生成 **`proposal.md`** 时须建立 **「为何要做」**，并与后续 **`specs/`** 对齐：**Capabilities** 段落是 proposal 与 specs 之间的契约。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/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/template/skills/apm-propose/specs-instruction.md

@@ -0,0 +1,114 @@
+# specs 工件：写作说明（供 apm-propose 读取）
+
+在工作项目录下生成 **`specs/`** 内的规格文件，定义系统 **应做什么**，与 **`design.md`**（如何实现）区分。内容须可验证：**每条「需求」下须有至少一个「场景」**。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/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/template/skills/apm-propose/tasks-instruction.md

@@ -0,0 +1,90 @@
+# tasks 工件：写作说明（供 apm-propose 读取）
+
+生成 **`tasks.md`**：把实现工作拆成**可勾选、可追踪**的条款。后续 **apm-apply-change** 依赖 **`- [ ]` / `- [x]`** 勾选推进，格式须严格遵守。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/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/template/skills/apm-refine/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: apm-refine
+description: 根据需求 ID 读取工作项 prd.md 与 reviews.xml，按「修订稿」标准结构（修订说明、背景与目标、范围、需求点、非功能、待确认/问题与局限等）润色并回写，再执行 apm refine 同步平台；当用户在对话中 @ 本技能或提出需求润色时使用。
+---
+
+# APM 需求润色（PRD 标准化）
+
+用户仅提供 **需求 ID**（workitem id）。**缺 ID 时索要，不猜测。**
+
+## 强制执行顺序（四步）
+
+### 步骤 1：读取 `prd.md` 与 `reviews.xml`
+
+1. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/prd.md`**。
+2. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/reviews.xml`**。
+
+**失败与缺省：**
+
+- 若 **`prd.md` 无法读取**（不存在、无权限等）：**终止**后续步骤，在最终对用户的说明中记录失败原因。
+- 若 **`reviews.xml` 无法读取**（不存在等）：**不终止**；视为**无评审意见**，仅基于当前 `prd.md` 做标准化与润色，不杜撰评审内容。
+
+### 步骤 2：润色为「标准需求文档」
+
+在**不向用户追问补充信息**的前提下完成（**禁止**为润色向用户发起对话式提问；材料中已写的 `reply` 与评审意见视为**补充信息**可吸收。有歧义、缺信息、与 reviews 冲突等，**对材料未载明之事项**一律记入 **「问题与局限」** 或按条件写入 **「待确认」**，见 **[apm-refine-template.md](./apm-refine-template.md)** 与小节 3）。
+
+1. **综合 `reviews.xml`（若可读）**  
+   解析其中各条 `review` 的 `content`（对 prd 的改进点/问题）与 `reply`（已给出的处理意见）。将**可落实的**回复与结论吸收进正文；**未覆盖或仍模糊**的，写入 **「问题与局限」**；若原文或 `reply` 中**已标明**未决、「待定」等，则同时或单独写入 **「待确认」**。**不**停步询问用户。
+
+2. **落盘结构：标准「修订稿」模板（写入 `prd.md` 须遵循）**  
+   使用 **Read** 读取与 `SKILL.md` 同目录的 **[apm-refine-template.md](./apm-refine-template.md)**，按其中**修订稿骨架**与章节说明组织正文（默认全文润色形态）。执行本技能时**须**读取该文件，不以记忆代替。
+
+   **改动与边界（仍须满足）**  
+   - **修订说明**中的「本次合并的要点」须**分点**写清本次相对原文的变更与**范围边界**（影响面、不做的事）。若改动项多于 3 条，可在「修订说明」后续追加小节 **「相对原文的变更」** 继续分点罗列。  
+   - 全文润色时**不要机械留空标题**：无内容的章节可删除（如无非功能则不写该章），但**背景与目标 / 范围 / 需求说明**一般应完整可读。
+
+   **局部替换（不必强行铺满模板）**  
+   若本轮实质上只需替换若干段落：可在 `prd.md` 中保留未改章节，仅重写涉及段落为**修改后的完整段落**，并在 **修订说明**（或 **相对原文的变更摘要**）中用简短 bullet 说明相对原文改了什么。**对用户对话仍以步骤 5 表格为唯一输出**，不把局部稿粘贴到对话里。
+
+3. **「问题与局限」与「待确认」**  
+   触发条件见 **[apm-refine-template.md](./apm-refine-template.md)** 文末两节；凡触发「问题与局限」的情形须按该节撰写，**禁止**因上述情况向用户发起追问。
+
+### 步骤 3：回写 `prd.md`
+
+使用 **Write** 将**完整**润色后的正文写回 **第一步同一路径**：**`.apm/workitems/<需求ID>/prd.md`**（覆盖原文件）。
+
+### 步骤 4：执行 `apm refine <需求ID>`
+
+在**仓库/工作区根目录**执行：
+
+```bash
+apm refine <需求ID>
+```
+
+命令结束后将本步执行结果记入「步骤 5」表格对应行的**状态**（见下）。
+
+### 步骤 5：回复用户
+
+对用户可见回复 **仅限一张 Markdown 表格**，**仅填写步骤 1～4 每步的执行状态**。**不得**在表格外输出任何其他内容（不粘贴 prd 正文、不另写摘要或提示）。
+
+建议表头（每行「状态」仅填 **成功** / **失败** / **跳过**；失败时可加简短原因，如 `失败：文件不存在`）：
+
+| 步骤 | 状态 |
+|------|------|
+| 1. 读取 `prd.md` 与 `reviews.xml` |  |
+| 2. 润色为「标准需求文档」 |  |
+| 3. 回写 `prd.md` |  |
+| 4. 执行 `apm refine <需求ID>` |  |
+
+---
+
+## 内部编排要点
+
+**通读 prd → Read [apm-refine-template.md](./apm-refine-template.md) →（若有）解析 reviews 与 reply → 按修订稿骨架写入 → 写回 `prd.md` → `apm refine`。**
+
+唯 **对用户可见** 的回复遵守上文「步骤 5」的表格约束。

package/template/skills/apm-refine/apm-refine-template.md

@@ -0,0 +1,47 @@
+# APM 需求「修订稿」落盘模板
+
+由 **`apm-refine`** 技能引用：润色并写回 `.apm/workitems/<需求ID>/prd.md` 时，按下列骨架组织正文。
+
+文中 **「补充信息」** 指 **`reviews.xml`** 中的评审意见与 `reply`（及评审记录中已写明的事实），不单指对话里的用户发言。
+
+---
+
+# [需求标题]（修订稿）
+
+**修订说明**（可选，但在依据评审合并或全文润色时**建议必备**）
+
+- 基于评审日期 / 评审记录：简要一句（若有可溯源的 review id、模型名可写）
+- 本次合并的要点：1～3 条 bullet（写清相对原文合并了什么、边界在哪）
+
+---
+
+## 背景与目标
+
+（合并原文与补充信息中明确补充/修正的表述）
+
+## 范围
+
+- **包含**：
+- **不包含**：（若补充信息或原文中明确收窄/排除）
+
+## 需求说明
+
+### 需求点 1：[名称]
+
+（将原文与补充信息合并后的**可执行描述**写清：角色、场景、规则、口径、边界）
+
+### 需求点 2：…
+
+## 非功能与约束（若有）
+
+（性能、权限、兼容、埋点等——仅当原文或补充信息涉及）
+
+## 待确认（可选；整节省略）
+
+仅当**原文、`reviews` 的 reply 或评审记录中**明确留下未拍板事项、或写明「待定」「再议」等时列出：
+
+- [ ] （未决口径摘要）— 用户原话或简要归纳
+
+## 问题与局限（按条件出现；与「待确认」区分）
+
+**待确认**承载「材料里用户/评审已标明的未决项」。本节承载润色过程中发现的：**评审缺失或 XML 不可解析、reviews 与 prd 冲突、关键口径无法从现有材料唯一确定**等；**禁止**为此向用户追问，仅列事实与风险。