ai-project-manage-cli 2.0.9 → 2.0.11

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}
+- **仅当**存在非显而易见的控制流、状态机、并发、算法、跨层协议时再写；简单字段增删、重命名、配置替换可写「本次无复杂逻辑需单独说明。」或等价一句。
+- 内容侧重：**为何这样拆分**、数据流/调用链、关键取舍；禁止大段粘贴源码。
+-->

package/templates/skills/code-deploy/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: code-deploy
+description: 按项目内 `.apm/deploy/README.md` 执行部署；仅在用户主动提及该技能或明确要求按部署文档操作时触发。
+---
+
+# 按文档部署
+
+## 工作流程（必须按顺序）
+
+1. **读取部署文档**  
+   在**目标项目根目录**下，用 Read 工具阅读：
+
+   `.apm/deploy/README.md`
+
+2. **文档不存在则结束**  
+   若该路径不存在、无法读取或内容为空且无可用步骤：**立即终止**，简要说明缺少 `.apm/deploy/README.md`；**不要**用其它文件（如根 README、package.json、CI 配置）推断部署方式。
+
+3. **文档存在则部署到目标环境**  
+   - **确定目标环境**（可与文档、用户描述对照，作合理推断；与下文「步骤失败」的禁止猜测不是同一回事）：  
+     - 用户若明确说了环境（如预发、生产），以用户为准。  
+     - **若未说明，默认部署到测试环境。**  
+     - 若文档**只提供一种部署方式**、未区分多环境，**按该文档直接执行即可**。  
+     - 若文档区分多环境而用户未点名，**结合文档章节/标题与用户描述**推断；仍无法确定时，**采用默认测试环境**。  
+   - **只执行与本次目标环境相关的部分**（以文档中的章节、命令、变量为准）。  
+   - **严格按文档给出的命令、顺序、目录与环境变量执行**；文档未写明的操作一律不做。  
+   - **若任一步报错**（非 0 退出、明确失败输出、或文档步骤无法继续）：**立即结束**，如实汇报错误与失败步骤；**不要**猜测原因、不要擅自换命令、不要静默重试或「尝试修复」——除非文档本身写了失败时的处理分支。
+
+## 结果汇报与成败判定
+
+`.apm/deploy/README.md` **通常不会**提供「如何确认部署已成功」的校验方式；**不要**自行做健康检查、访问地址验证等以证明服务真实可用。**如实汇报**按文档执行的步骤、命令与终端输出即可，**不宣称**已验证目标环境一定部署成功。
+
+- **失败**：部署过程中出现**明显报错**（例如命令非 0 退出、明确的错误输出、无法按文档继续执行），与上文第 3 步「任一步报错」一致，立即结束并说明失败点。  
+- **非失败**：未出现上述明显报错时，按流程执行完毕后**如实汇总结果**即可，**不**额外判定「是否真的部署成功」。
+
+## 禁止事项
+
+- 绕过或未读 `.apm/deploy/README.md` 就执行部署。  
+- 文档缺失时从别处「推断」部署流程。  
+- 步骤失败后用通用经验替代文档或继续试错。

package/templates/skills/prd-testcase/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: prd-testcase
+description: 基于需求文档为其生成测试用例，当用户在明确要求调用本技能时使用，输入参数是 requirementId。
+---
+
+# 从需求文档生成手工测试用例
+
+## 触发条件
+
+用户在对话中明确要求使用本技能。
+
+## 输入
+
+- **requirementId**：需求 ID
+
+## 输出
+
+1. 手工测试用例文档：`.apm/workitems/<requirementId>/testcase.md`
+
+---
+
+## 执行流程
+
+1. **拉取需求与评论（使用 CLI）**：执行 `apm get requirement <requirementId>`，获取需求文档。
+
+### 2. 提取需求点
+- 需求点是唯一真理：所有测试点、口径、阈值、边界与禁止项必须从需求清单提炼。
+- 将需求拆分为可追踪条目并编号：`REQ-001`、`REQ-002`、`REQ-003`...
+
+### 3. 先做覆盖设计（严格模式）
+
+- **需求正向覆盖（强制）**：每个 `REQ` 至少映射 1 条测试用例（`REQ -> TC`）。
+- **用例逆向追踪（强制）**：每条 `TC` 必须回指至少 1 个 `REQ`（`TC -> REQ`）。
+- **场景维度覆盖（强制）**：每个 `REQ` 至少覆盖以下三类场景：
+  - 正向场景（主流程成功）
+  - 边界场景（阈值/长度/上下限/临界值）
+  - 异常场景（非法输入/失败分支/缺失前置条件）
+- 按上述规则先形成覆盖矩阵，再进入写作：
+  - 需求覆盖矩阵：`REQ -> TC[]`
+  - 用例追踪矩阵：`TC -> REQ[]`
+
+### 4. 生成手工测试用例（正文平铺）
+
+- 依据需求清单归纳可测场景，生成 `test_case.md`。
+- **靶心优先级（强制，避免“先射箭再画靶”）**：
+  - **最高优先级：需求清单（requirements/PRD）**。用例的“口径/阈值/不得改变的规则/显示范围/不做什么”等验收结论，必须优先从需求清单可读出的表述提炼。
+  - **第二优先级：产品能力清单 CAP**。用例的“目标入口/目标组件区域”必须以 CAP 的 `入口锚点（强制）` 与 `UI 识别锚点（强制）` 为准；若用例目标落在其它相似页面/表格组件上，应视为冲突，必须改写用例以落到 CAP 指定区域。
+- **入口锚点补全（强制，引用产品能力清单）**：
+  - 若仓库存在 `.apm/product-capability-inventory/`，则对每条用例的“目标 UI 区域”执行 CAP 对齐：
+    1. 从 `.apm/product-capability-inventory/<系统名>/index.md` 的「能力条目目录表」中，基于需求点标题/关键术语选择最匹配的 `CAP-xxx`（仅选一个最匹配的）。
+    2. 打开对应 `.apm/product-capability-inventory/<系统名>/CAP-xxx.md`，读取字段 `入口锚点（强制）` 与 `UI 识别锚点（强制）`。
+    3. 将 `入口锚点（强制）` 作为“导航来源”，把它转译为用例中的 **操作步骤**（至少覆盖：菜单/抽屉标题/Tab/子页签/目标区域的进入）。
+    4. 将 `UI 识别锚点（强制）` 作为“断言来源”，在 **预期结果**中至少包含 1 条与 `UI 识别锚点（强制）` 对应的可断言检查（例如：表头列名/关键按钮文案/区域标题等），并确保步骤中确实进入了该区域。
+  - 若找不到合适 CAP 或 CAP 缺失上述必填字段，则回退到“保守定位”：
+    - 用例操作步骤必须显式包含：菜单路径/页面标题 或 抽屉标题 或 Tab 文案 + 目标区域至少两列表头/关键按钮文案（从需求清单提炼），并用预期结果体现可断言点。
+- **testcase.md 格式与结构（强制）**：正文平铺用例、`case_id` 以及缩进/编号规则等全部约束，严格遵循同目录 [`reference.md`](./reference.md)。
+- 将整份 Markdown 写入固定路径：`.apm/workitems/<requirementId>/testcase.md`
+- 在文末追加覆盖校验小节（强制）：
+  - `## 覆盖校验`
+  - `### 需求覆盖矩阵（REQ -> TC）`
+  - `### 用例追踪矩阵（TC -> REQ）`
+  - `### 场景维度检查`（逐条 REQ 标记正向/边界/异常是否覆盖）
+
+### 5. 导入测试用例到系统
+
+- **命令**（在仓库根目录执行）：`apm set testcase <requirementId>`
+---
+
+## 依赖与约定
+
+- **输出结构**：仅遵循 `reference.md` 的用例文档格式规范
+- **完整示例**：见 [reference.md](reference.md)
+---
+
+## 成功标准
+
+- 手工测试用例文档已生成到约定路径（`.apm/workitems/<requirementId>/testcase.md`）
+- 文档格式与结构完全符合同目录 `reference.md`（正文平铺用例、`case_id` 与缩进/编号规则）。
+- 每条用例均为 **操作步骤 + 预期结果** 的精简形态，便于生成 **前端 E2E** 用例脚本
+- 需求覆盖率为 100%（无未覆盖 REQ）
+- 无孤儿用例（每条 TC 均可追溯到至少 1 条 REQ）
+- 每条 REQ 至少覆盖正向、边界、异常三类场景