ai-project-manage-cli 2.0.9 → 2.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/api/cli.d.ts +50 -0
  2. package/dist/api/cli.d.ts.map +1 -1
  3. package/dist/api/client.d.ts +4 -0
  4. package/dist/api/client.d.ts.map +1 -1
  5. package/dist/api/index.d.ts +1 -1
  6. package/dist/api/index.d.ts.map +1 -1
  7. package/dist/api/request-config.d.ts +5 -1
  8. package/dist/api/request-config.d.ts.map +1 -1
  9. package/dist/api/request-config.js +16 -0
  10. package/dist/api/request-config.js.map +1 -1
  11. package/dist/cli/commands/get.d.ts.map +1 -1
  12. package/dist/cli/commands/get.js +59 -0
  13. package/dist/cli/commands/get.js.map +1 -1
  14. package/dist/cli/commands/set.d.ts.map +1 -1
  15. package/dist/cli/commands/set.js +51 -0
  16. package/dist/cli/commands/set.js.map +1 -1
  17. package/dist/core/cursor-cmd.d.ts.map +1 -1
  18. package/dist/core/cursor-cmd.js +3 -2
  19. package/dist/core/cursor-cmd.js.map +1 -1
  20. package/dist/core/parse-testcase-md.d.ts +17 -0
  21. package/dist/core/parse-testcase-md.d.ts.map +1 -0
  22. package/dist/core/parse-testcase-md.js +79 -0
  23. package/dist/core/parse-testcase-md.js.map +1 -0
  24. package/package.json +2 -1
  25. package/templates/skills/apm-apply-change/SKILL.md +191 -0
  26. package/templates/skills/apm-auto-dev/SKILL.md +63 -116
  27. package/templates/skills/{bug-fix → apm-fixbug}/SKILL.md +2 -2
  28. package/templates/skills/apm-propose/SKILL.md +123 -0
  29. package/templates/skills/apm-propose/design-instruction.md +94 -0
  30. package/templates/skills/apm-propose/propose-instruction.md +81 -0
  31. package/templates/skills/apm-propose/specs-instruction.md +114 -0
  32. package/templates/skills/apm-propose/tasks-instruction.md +90 -0
  33. package/templates/skills/code-change-summary/SKILL.md +84 -0
  34. package/templates/skills/code-change-summary/summary-template.md +55 -0
  35. package/templates/skills/code-deploy/SKILL.md +39 -0
  36. package/templates/skills/prd-testcase/SKILL.md +82 -0
  37. package/templates/skills/case-creator/SKILL.md +0 -130
  38. package/templates/skills/mr-review-brief/SKILL.md +0 -79
  39. package/templates/skills/mr-review-brief/mr-review-template.md +0 -47
  40. package/templates/skills/openspec-apply-change/SKILL.md +0 -167
  41. package/templates/skills/openspec-propose/SKILL.md +0 -127
  42. package/templates/skills/test-env-release/SKILL.md +0 -31
  43. /package/templates/skills/{case-creator → prd-testcase}/reference.md +0 -0
@@ -1,130 +0,0 @@
1
- ---
2
- name: case-creator
3
- description: 基于用户指定的本地 Markdown 需求文档生成手工测试用例(test_case.md)。Use when 用户提到“手工测试case/测试用例/test_case.md”,并希望以需求为唯一真理产出可执行测试点。
4
- ---
5
-
6
- # 从需求文档生成手工测试用例
7
-
8
- ## 触发条件
9
-
10
- - 用户希望生成手工测试 case,且**指定本地 Markdown 需求文档路径**(项目内相对路径或绝对路径)。
11
- - 本技能仅负责产出 `test_case.md`。
12
-
13
- ## 输入
14
-
15
- - **需求内容**:需求文档的 Markdown 文件路径或者文档内容
16
- - **requirementId**:需求 ID(number),用于将测试用例导入系统
17
-
18
- ## 输出
19
-
20
- 1. 手工测试用例文档:`.apm/workitems/<name>/test_case.md`
21
-
22
- ---
23
-
24
- ## 执行流程
25
-
26
- ### 1. 确定需求来源并读取内容
27
-
28
- - 直接读取用户指定的本地 Markdown 文件内容。
29
- - 计算输出目录名 `<name>`:默认使用需求文档文件名(去掉扩展名)作为 `<name>`。
30
- - 输出文件固定写入 `.apm/workitems/<name>/test_case.md`。
31
-
32
- ### 2. 提取需求清单
33
-
34
- - 若该文档中含有「## 需求清单」章节,则只取该章节正文作为需求清单;否则将**整份文档**视为需求清单
35
- - 需求清单是唯一真理:所有测试点、口径、阈值、边界与禁止项必须从需求清单提炼。
36
- - 将需求拆分为可追踪条目并编号:`REQ-001`、`REQ-002`、`REQ-003`...
37
-
38
- ### 3. 先做覆盖设计(严格模式)
39
-
40
- - **需求正向覆盖(强制)**:每个 `REQ` 至少映射 1 条测试用例(`REQ -> TC`)。
41
- - **用例逆向追踪(强制)**:每条 `TC` 必须回指至少 1 个 `REQ`(`TC -> REQ`)。
42
- - **场景维度覆盖(强制)**:每个 `REQ` 至少覆盖以下三类场景:
43
- - 正向场景(主流程成功)
44
- - 边界场景(阈值/长度/上下限/临界值)
45
- - 异常场景(非法输入/失败分支/缺失前置条件)
46
- - 按上述规则先形成覆盖矩阵,再进入写作:
47
- - 需求覆盖矩阵:`REQ -> TC[]`
48
- - 用例追踪矩阵:`TC -> REQ[]`
49
-
50
- ### 4. 生成手工测试用例(正文平铺)
51
-
52
- - 依据需求清单归纳可测场景,生成 `test_case.md`。
53
- - **靶心优先级(强制,避免“先射箭再画靶”)**:
54
- - **最高优先级:需求清单(requirements/PRD)**。用例的“口径/阈值/不得改变的规则/显示范围/不做什么”等验收结论,必须优先从需求清单可读出的表述提炼。
55
- - **第二优先级:产品能力清单 CAP**。用例的“目标入口/目标组件区域”必须以 CAP 的 `入口锚点(强制)` 与 `UI 识别锚点(强制)` 为准;若用例目标落在其它相似页面/表格组件上,应视为冲突,必须改写用例以落到 CAP 指定区域。
56
- - **入口锚点补全(强制,引用产品能力清单)**:
57
- - 若仓库存在 `.apm/product-capability-inventory/`,则对每条用例的“目标 UI 区域”执行 CAP 对齐:
58
- 1. 从 `.apm/product-capability-inventory/<系统名>/index.md` 的「能力条目目录表」中,基于需求点标题/关键术语选择最匹配的 `CAP-xxx`(仅选一个最匹配的)。
59
- 2. 打开对应 `.apm/product-capability-inventory/<系统名>/CAP-xxx.md`,读取字段 `入口锚点(强制)` 与 `UI 识别锚点(强制)`。
60
- 3. 将 `入口锚点(强制)` 作为“导航来源”,把它转译为用例中的 **操作步骤**(至少覆盖:菜单/抽屉标题/Tab/子页签/目标区域的进入)。
61
- 4. 将 `UI 识别锚点(强制)` 作为“断言来源”,在 **预期结果**中至少包含 1 条与 `UI 识别锚点(强制)` 对应的可断言检查(例如:表头列名/关键按钮文案/区域标题等),并确保步骤中确实进入了该区域。
62
- - 若找不到合适 CAP 或 CAP 缺失上述必填字段,则回退到“保守定位”:
63
- - 用例操作步骤必须显式包含:菜单路径/页面标题 或 抽屉标题 或 Tab 文案 + 目标区域至少两列表头/关键按钮文案(从需求清单提炼),并用预期结果体现可断言点。
64
- - **test_case.md 格式与结构(强制)**:正文平铺用例、`case_id` 以及缩进/编号规则等全部约束,严格遵循同目录 [`reference.md`](./reference.md)。
65
- - 将整份 Markdown 写入固定路径:`.apm/workitems/<name>/test_case.md`
66
- - 在文末追加覆盖校验小节(强制):
67
- - `## 覆盖校验`
68
- - `### 需求覆盖矩阵(REQ -> TC)`
69
- - `### 用例追踪矩阵(TC -> REQ)`
70
- - `### 场景维度检查`(逐条 REQ 标记正向/边界/异常是否覆盖)
71
-
72
- ### 5. 导入测试用例到系统(强制)
73
-
74
- - **使用本仓库 CLI 导入**(内部调用 `POST /requirements/test-cases/create-batch`),**不要**手写 `curl` 调 HTTP。
75
- - **前置**:已在 `packages/cli` 下配置好 `apm` 的 base-url,且已 `apm login`(与 CLI 其它需求接口一致)。
76
- - **命令**(在仓库根目录执行):
77
-
78
- ```bash
79
- apm requirement test-case import --requirement-id <requirementId> --file <jsonPath>
80
- ```
81
-
82
- - **导入文件 `--file`**:UTF-8 的 **JSON 数组**(至少 1 条),元素字段与批量创建接口一致(CLI 会为每条补上 `requirementId`,取自 `--requirement-id`):
83
- - `title`:string(用例标题,**不含** `(TC-xxx)`)
84
- - `steps`:string(操作步骤,建议保留 `test_case.md` 中的编号列表,行与行之间用 `\n` 拼接)
85
- - `expectedResult`:string(可选;预期结果,编号列表同样建议用 `\n` 拼接)
86
- - `status`:string(可选;枚举:`DRAFT` | `READY` | `PASSED` | `FAILED` | `BLOCKED`)
87
-
88
- **JSON 示例**(写入任意临时 JSON 文件后导入即可):
89
-
90
- ```json
91
- [
92
- {
93
- "title": "列表顶部展示新增入口",
94
- "steps": "1. 使用具备权限账号登录\n2. 进入目标页面",
95
- "expectedResult": "1. 页面顶部展示新增按钮"
96
- }
97
- ]
98
- ```
99
-
100
- - **字段映射约定(从 `test_case.md` 到 JSON,再交给 CLI)**:
101
- - `### Pn: 标题(TC-xxx)` -> `title`(去掉 `(TC-xxx)`;`Pn` 仅作优先级提示,可写入标题前缀如 `[P0]` 或省略,以团队习惯为准)
102
- - `- 操作步骤:` 下编号列表 -> `steps`
103
- - `- 预期结果:` 下编号列表 -> `expectedResult`
104
- - `- 数据依赖:...`:若需落库为说明,可并入 `steps` 首行或单独一行(当前接口无独立 `dataDependency` 字段)
105
- - **导入前校验**:
106
- - JSON 数组非空
107
- - 每条元素的 `title`、`steps` 非空;`expectedResult` 建议非空(与用例文档一致)
108
- - **失败处理**:若 CLI 报错,保留 `.apm/workitems/<name>/test_case.md` 与已生成的 JSON **不回滚**,根据终端/API 错误修正映射或数据后重试。
109
- - **清理约定**:CLI 导入成功后,删除本次导入使用的临时 JSON 文件。
110
-
111
- ---
112
-
113
- ## 依赖与约定
114
-
115
- - **本地文档**:需求清单取该文件中的「## 需求清单」章节(有则只取该节),无则该文件全文视为需求清单
116
- - **输出结构**:仅遵循 `reference.md` 的用例文档格式规范
117
-
118
- - **完整示例**:见 [reference.md](reference.md)
119
-
120
- ---
121
-
122
- ## 成功标准
123
-
124
- - 手工测试用例文档已生成到约定路径(`.apm/<name>/test_case.md`)
125
- - 文档格式与结构完全符合同目录 `reference.md`(正文平铺用例、`case_id` 与缩进/编号规则)。
126
- - 每条用例均为 **操作步骤 + 预期结果** 的精简形态,便于生成 **前端 E2E** 用例脚本
127
- - 需求覆盖率为 100%(无未覆盖 REQ)
128
- - 无孤儿用例(每条 TC 均可追溯到至少 1 条 REQ)
129
- - 每条 REQ 至少覆盖正向、边界、异常三类场景
130
- - `apm requirement test-case import` 执行成功,且返回条数与 JSON 数组条数一致
@@ -1,79 +0,0 @@
1
- ---
2
- name: mr-review-brief
3
- description: 在功能分支上相对 main/master 生成 MR 评审说明:功能变更、复杂项实现思路、对照仓库约定的规范符合性、建议验证步骤。供人类审核 AI 或大批量 diff,避免看不懂直接打回。用户主动触发;提及 MR 评审说明、评审摘要、变更说明、代码评审说明、release-checklist(历史名称)时使用。
4
- ---
5
-
6
- # MR 评审说明(供人类审核)
7
-
8
- **目的**:把相对基准分支的改动整理成评审者可读的说明,**不是**上线清单。重点三件事:
9
-
10
- 1. **功能面**:改了什么、用户侧前后差异、该验什么。
11
- 2. **实现思路(复杂项)**:AI/作者为何这样拆问题、数据流或调用链、与现有模块如何衔接,避免评审者对着大段 diff 无从读起。
12
- 3. **规范符合性**:对照本仓库已有约定(`AGENTS.md`、`.cursor/rules` 等)做**诚实对照**,便于确认 AI 是否按项目规矩办事。
13
-
14
- ## 触发前提
15
-
16
- - **仅在新分支执行**:当前分支必须不是 `main` 或 `master`
17
- - **用户主动触发**:如「生成 MR 评审说明」「评审摘要」「给 MR 写说明」等
18
-
19
- 若当前在 main/master,提示:请先切换到功能分支再生成。
20
-
21
- ## 核心原则
22
-
23
- - **按功能写正文**,不把「文件 M/A/D 列表」当正文主体;需要指到代码时,用少量**关键路径**(文件或模块名)辅助复杂项说明即可。
24
- - **实现思路**用自然语言与少量结构化小标题,**禁止**大段粘贴源码。
25
- - **规范符合性**:只能写**有据可查**的结论;不确定一律标为 **待评审核对** 并写明要查什么,**禁止**无依据写「已全部遵守规范」。
26
- - 功能描述要**具体**:「之前 → 现在」,禁止空泛「调整了 XX 模块」。
27
-
28
- ## 执行流程
29
-
30
- 1. **获取变更**(只读 git):
31
-
32
- ```bash
33
- git branch --show-current
34
- git log main..HEAD --oneline # 或 master..HEAD
35
- git diff main..HEAD --name-status
36
- git diff main..HEAD # 必要时查看具体 diff
37
- ```
38
-
39
- 2. **按功能归纳**:业务功能维度、影响页面/流程;识别**复杂项**(填法见模板文件末尾注释中的 `{RATIONALE_COMPLEX}`)。
40
-
41
- 3. **规范对照**(按变更范围选读,不必全文背诵):
42
-
43
- - 仓库根:`AGENTS.md`(Rush、子项目命令、Prisma 等)
44
- - 若涉及前端:`apps/fe/AGENTS.md`
45
- - 若涉及后端:`servers/be/AGENTS.md`
46
- - 与改动相关的 `.cursor/rules`(如 Rush 命令规范)
47
-
48
- 将**与本次 diff 可能相关的条目**逐条对照,写入 `{CONVENTION_COMPLIANCE}`。
49
-
50
- 4. **填充模板**:`mr-review-template.md`,替换全部占位符。
51
-
52
- 5. **交付**:
53
-
54
- - **必须在对话中输出完整 Markdown**,便于粘贴到 MR 描述或首条评论;**勿包含**模板末尾的 `<!-- 填法... -->` 注释块。
55
- - **落盘**(可选):仅当用户明确要求且提供保存位置时写入,默认**不落盘**。
56
-
57
- ## 模板占位符
58
-
59
- 模板路径:`mr-review-template.md`。
60
-
61
- | 占位符 | 含义 |
62
- |--------|------|
63
- | `{BRANCH_NAME}` | 当前分支名 |
64
- | `{DATE}` | 生成日期 |
65
- | `{BASE_BRANCH}` | main 或 master |
66
- | `{SCOPE}` | 前端 / 后端 / 全栈 / 公共 等 |
67
- | `{FUNCTION_CHANGES}` | 功能变更正文 |
68
- | `{RATIONALE_COMPLEX}` | 复杂项实现思路 |
69
- | `{CONVENTION_COMPLIANCE}` | 规范符合性 |
70
- | `{VERIFY_SUGGESTIONS}` | 建议验证步骤 |
71
-
72
- **各占位符的正文结构、字段与示例**:见模板**文件末尾** `<!-- ... -->` 填法注释。生成粘贴到 MR 的 Markdown 时**不要输出该 HTML 注释块**。
73
-
74
- **仅在 SKILL 强调(注释里不重复展开)**:规范结论须与「核心原则」一致——有据才写「已遵守」,否则标「待评审核对」并写清查什么。
75
-
76
- ## 实现注意
77
-
78
- - 只读命令:`git branch`、`git diff`、`git log`、`git show-ref`
79
- - 基准分支:优先 `main`,否则 `master`
@@ -1,47 +0,0 @@
1
- # MR 评审说明 - {BRANCH_NAME}
2
-
3
- **生成时间**:{DATE}
4
- **对比基准**:{BASE_BRANCH}
5
- **变更范围**:{SCOPE}
6
-
7
- ---
8
-
9
- ## 功能变更
10
-
11
- {FUNCTION_CHANGES}
12
-
13
- ---
14
-
15
- ## 实现思路(复杂项)
16
-
17
- {RATIONALE_COMPLEX}
18
-
19
- ---
20
-
21
- ## 项目规范符合性
22
-
23
- {CONVENTION_COMPLIANCE}
24
-
25
- ---
26
-
27
- ## 建议验证
28
-
29
- {VERIFY_SUGGESTIONS}
30
-
31
- <!--
32
- 填法(勿粘贴到 MR 正文):输出时去掉本注释块。
33
-
34
- {FUNCTION_CHANGES} — 每个功能一段:
35
- ### N. {功能/页面名称}
36
- - 之前:{行为}
37
- - 现在:{行为}
38
- - 影响范围:{入口、流程、页面(产品语言)}
39
-
40
- {RATIONALE_COMPLEX} — 仅复杂项展开(多文件联动、新抽象、非直观重构、关键算法或状态机);简单增删改写「本次以局部增删为主,无单独展开的实现思路。」
41
- 每复杂项可用二级标题,含:要解决的问题(1~2 句);实现要点(拆分、数据流/调用链、与现有代码接点);若有明显取舍可一句说明。
42
-
43
- {CONVENTION_COMPLIANCE} — 列表或表格,每条:规范来源;状态:已遵守 | 不适用 | 待评审核对;说明一句。
44
- 已遵守须能指向本次改动中的体现;待评审核对须写清评审要查什么;未触及的规范勿强行已遵守。
45
-
46
- {VERIFY_SUGGESTIONS} — 与功能对应或可合并为场景流;步骤可执行,写清预期结果。
47
- -->
@@ -1,167 +0,0 @@
1
- ---
2
- name: openspec-apply-change
3
- description: 根据 OpenSpec 变更实施任务。在用户希望开始实现、继续实现或逐项完成任务时使用。
4
- license: MIT
5
- compatibility: 需要 openspec CLI。
6
- metadata:
7
- author: openspec
8
- version: "1.0"
9
- generatedBy: "1.2.0"
10
- ---
11
-
12
- 根据 OpenSpec 变更实施任务。
13
-
14
- **输入**:可选指定变更名称。若未指定,先尝试从对话上下文推断;若仍无法唯一确定,按步骤 1 的固定规则选定变更。**不要**向用户发起反问式确认或交互式选题。
15
-
16
- **步骤**
17
-
18
- 1. **选择变更**
19
-
20
- 若已提供名称则直接使用。否则:
21
- - 若用户在对话中提到了变更,从上下文推断
22
- - 若仅存在一个活跃变更,自动选中
23
- - 若仍有歧义:运行 `openspec list --json`,**按 CLI 返回列表中的第一个候选**作为本次变更(若你的环境有更稳定的排序字段,以「列表顺序优先」为准);在回复中列出当时可见的候选名,并声明「使用变更:<name>」以及如何覆盖(例如 `/opsx:apply <其他>`)。**不要**调用 AskUserQuestion,**不要**停下来让用户当场选择。
24
-
25
- 始终声明:「使用变更:<name>」以及如何覆盖(例如 `/opsx:apply <其他>`)。
26
-
27
- 2. **查看状态以理解 schema**
28
- ```bash
29
- openspec status --change "<name>" --json
30
- ```
31
- 解析 JSON 以了解:
32
- - `schemaName`:当前工作流(例如 `"spec-driven"`)
33
- - 任务清单在哪个工件中(spec-driven 通常为 `tasks`,其他 schema 以 status 为准)
34
-
35
- 3. **获取 apply 说明**
36
-
37
- ```bash
38
- openspec instructions apply --change "<name>" --json
39
- ```
40
-
41
- 返回内容包括:
42
- - 上下文文件路径(因 schema 而异,可能是 proposal/specs/design/tasks 或 spec/tests/implementation/docs)
43
- - 进度(总数、已完成、剩余)
44
- - 带状态的任务列表
45
- - 基于当前状态的动态说明
46
-
47
- **处理状态:**
48
- - 若 `state: "blocked"`(缺少工件):展示提示,建议使用 openspec-continue-change
49
- - 若 `state: "all_done"`:祝贺完成,建议归档
50
- - 其他情况:进入实现
51
-
52
- 4. **阅读上下文文件**
53
-
54
- 阅读 apply 说明输出中 `contextFiles` 列出的文件。
55
- 文件取决于所用 schema:
56
- - **spec-driven**:proposal、specs、design、tasks
57
- - 其他 schema:以 CLI 输出的 contextFiles 为准
58
-
59
- 5. **展示当前进度**
60
-
61
- 展示:
62
- - 所用 schema
63
- - 进度:「N/M 个任务已完成」
64
- - 剩余任务概览
65
- - CLI 返回的动态说明
66
-
67
- 6. **实现任务(循环直至完成或阻塞)**
68
-
69
- 对每个待办任务:
70
- - 说明正在处理哪一项
71
- - 完成所需代码改动
72
- - 保持改动最小、聚焦
73
- - 在标记完成前收集依据:
74
- - `Requirement IDs`:本实现满足哪些需求
75
- - `Planned Files` 与实际改动文件:若有合理偏差需注明
76
- - `Validation Case IDs`:为验证行为执行了哪些用例
77
- - `Validation Result`:通过/失败及简要断言摘要
78
- - 仅在依据已记录且验证通过后,在任务文件中将 `- [ ]` 改为 `- [x]`
79
- - **Git**:本待办对应的实现与任务勾选等改动,**单独提交一个 commit**(一项待办 = 一个 commit;不要把多项待办混在同一 commit)。提交信息建议包含变更名与任务标识或简述。
80
- - 继续下一项
81
-
82
- **暂停条件:**
83
- - 任务不清晰 → 依据上下文与已有工件做合理推断并继续;必要时在说明中写明假设,**不反问用户**
84
- - 实现暴露设计问题 → 建议更新工件(陈述式说明,不提问)
85
- - 遇到错误或阻塞 → 报告原因与可选后续,**不反问用户**
86
- - 用户中断
87
-
88
- 7. **完成或暂停时展示状态**
89
-
90
- 展示:
91
- - 本会话完成的任务
92
- - 总体进度:「N/M 个任务已完成」
93
- - 若全部完成:建议归档
94
- - 若暂停:说明原因并列出可选后续(陈述式,**不反问用户**)
95
-
96
- **实现过程中的输出**
97
-
98
- ```
99
- ## 正在实施:<change-name>(schema: <schema-name>)
100
-
101
- 处理任务 3/7:<task description>
102
- [...实现过程...]
103
- ✓ 任务完成 · commit <short-sha> <subject>
104
-
105
- 处理任务 4/7:<task description>
106
- [...实现过程...]
107
- ✓ 任务完成 · commit <short-sha> <subject>
108
- ```
109
-
110
- **完成时的输出**
111
-
112
- ```
113
- ## 实现完成
114
-
115
- **变更:** <change-name>
116
- **Schema:** <schema-name>
117
- **进度:** 7/7 个任务已完成 ✓
118
-
119
- ### 本会话已完成
120
- - [x] Task 1
121
- - [x] Task 2
122
- ...
123
-
124
- (每项待办均已对应独立 commit。)
125
-
126
- 全部任务完成!可以归档此变更。
127
- ```
128
-
129
- **暂停时的输出(遇到问题)**
130
-
131
- ```
132
- ## 实现已暂停
133
-
134
- **变更:** <change-name>
135
- **Schema:** <schema-name>
136
- **进度:** 4/7 个任务已完成
137
-
138
- ### 遇到的问题
139
- <问题描述>
140
-
141
- **可选后续:**
142
- 1. <选项 1>
143
- 2. <选项 2>
144
- 3. <选项 3>
145
-
146
- (陈述即可;不要求用户当场作答。)
147
- ```
148
-
149
- **约束**
150
- - 持续执行任务直至完成或阻塞
151
- - 开始前务必阅读上下文文件(来自 apply 说明输出)
152
- - 若任务有歧义,先依据上下文与 spec 做合理推断并实现;**不**为澄清而反问用户
153
- - 若实现暴露问题,暂停并建议更新工件
154
- - 代码改动保持最小、与每项任务范围一致
155
- - 未完成需求映射与验证依据前,**不要**将任务勾为完成
156
- - 若验证失败或缺少依据,保持任务未勾选并明确报告缺口
157
- - 若任务元数据缺失(Requirement IDs / Planned Files / Validation Case IDs / Done Criteria),在可能的情况下于实现前补全
158
- - 每完成一项任务并记录依据后,立即更新对应勾选框,并**随即**为该待办单独 `git commit`(一项待办一个 commit)
159
- - 遇错误或硬阻塞时暂停并说明原因;需求不清时在任务说明中记录假设与风险,**不反问用户**
160
- - 使用 CLI 输出的 contextFiles,不要假定具体文件名
161
-
162
- **与流动工作流的衔接**
163
-
164
- 本技能支持「对变更执行操作」模型:
165
-
166
- - **可随时调用**:不必等所有工件就绪(若已有任务)、可在部分实现之后、可与其他操作穿插
167
- - **允许更新工件**:若实现暴露设计问题,建议更新工件——不锁阶段,可灵活推进
@@ -1,127 +0,0 @@
1
- ---
2
- name: openspec-propose
3
- description: 以明确的需求文档为输入,一步生成 OpenSpec 变更工件(proposal/design/tasks/specs)。在用户只需要规格与实现规划、不需要手工测试用例时使用。
4
- license: MIT
5
- compatibility: 需要 openspec CLI。
6
- metadata:
7
- author: openspec
8
- version: "1.1"
9
- generatedBy: "1.2.0"
10
- ---
11
-
12
- 提出新变更——在**需求文档**基础上创建变更并生成 OpenSpec 工件。
13
-
14
- 范围边界:
15
- - 本技能仅用于规格/规划类工件(`proposal.md`、`design.md`、`tasks.md`、specs)。
16
-
17
- 将创建包含以下内容的变更:
18
- - proposal.md(做什么、为什么)
19
- - design.md(怎么做)
20
- - tasks.md(实现步骤)
21
-
22
- ---
23
-
24
- **输入(必须满足)**
25
-
26
- 1. **明确的需求文档**——二选一或同时提供:
27
- - 文档**正文**(粘贴到对话中),或
28
- - 仓库内**文件路径**(由你读取该文件)。
29
- 2. **变更名**(kebab-case)——可选;若未给出,由你从需求文档中归纳 kebab-case 名称,**不要**为命名向用户追问。
30
-
31
- **不满足时不继续**:仅有模糊想法、没有可引用的需求正文/文件时,说明本技能需要「可对照的需求文档」,请用户先整理需求或指明文档路径后再触发。
32
-
33
- ---
34
-
35
- **执行流程**
36
-
37
- ### 1. 锚定需求与变更名
38
-
39
- - 若给的是路径:用 Read 读取全文,确认可读、无截断。
40
- - 通读需求文档,标记:目标用户/场景、功能范围、非目标、约束、验收口径。文档未写明的部分:**不要**向用户追问;在 `proposal.md` / `design.md` 中写明合理**假设**,或列为**已知缺口/风险/待后续补充**,并在任务中体现需实现侧拍板的内容。
41
- - 确定或推导变更目录名 `<name>`(kebab-case)。若与已有 `openspec/changes/<name>/` 冲突:在 `proposal.md` 中说明与既有变更的关系;若需新建目录则自动采用不冲突名称(例如在原名后加 `-2`、`-extend` 等),**不要**为此反问用户。
42
-
43
- ### 2. 创建变更脚手架
44
-
45
- ```bash
46
- openspec new change "<name>"
47
- ```
48
-
49
- 会在 `openspec/changes/<name>/` 下生成带 `.openspec.yaml` 的变更脚手架。
50
-
51
- ### 3. 获取工件构建顺序
52
-
53
- ```bash
54
- openspec status --change "<name>" --json
55
- ```
56
-
57
- 解析 JSON:
58
-
59
- - `applyRequires`:实现前需完成的工件 ID 列表(例如 `["tasks"]`)
60
- - `artifacts`:所有工件及其状态与依赖
61
-
62
- ### 4. 按依赖顺序生成工件(需求文档为唯一事实来源)
63
-
64
- 使用 **TodoWrite** 跟踪各工件进度。按依赖顺序遍历(先处理无待处理依赖的工件)。
65
-
66
- 对每一个依赖已满足的 `ready` 工件:
67
-
68
- a. 获取该工件的生成说明:
69
-
70
- ```bash
71
- openspec instructions <artifact-id> --change "<name>" --json
72
- ```
73
-
74
- 说明 JSON 含:`context`、`rules`、`template`、`instruction`、`outputPath`、`dependencies`(**不要**把 `context`/`rules` 写入输出文件)。
75
-
76
- b. 读取已完成的依赖文件;**撰写正文时严格以需求文档为准**,将需求中的条目映射到 `template` 各节,避免臆造未在需求中出现的范围。
77
-
78
- c. 按 `template` 结构写入 `outputPath`。创建 `tasks` 时,每项任务须含可追溯元数据:
79
-
80
- - `Requirement IDs`:对应规格中的需求 ID
81
- - `Planned Files`:预期改动的文件路径
82
- - `Validation Case IDs`:验证用例 ID(若有)
83
- - `Done Criteria`:可观察的完成标准
84
-
85
- d. 简短提示:「已创建 <artifact-id>」
86
-
87
- e. 每完成一个工件后重新执行:
88
-
89
- ```bash
90
- openspec status --change "<name>" --json
91
- ```
92
-
93
- 直到 `applyRequires` 中所有工件在 `artifacts` 里均为 `status: "done"`。
94
-
95
- ### 5. 展示最终状态
96
-
97
- ```bash
98
- openspec status --change "<name>"
99
- ```
100
-
101
- ---
102
-
103
- **输出**
104
-
105
- 完成所有工件后汇总:
106
-
107
- - 变更名称与路径
108
- - 已创建工件列表及简要说明
109
- - 说明需求文档如何反映在各工件中(一两句即可)
110
- - 就绪说明:「所有工件已创建!可以开始实现。」
111
- - 提示:「执行 `/opsx:apply` 或让我来实现,即可开始处理任务。」
112
-
113
- ---
114
-
115
- **工件编写指引**
116
-
117
- - 各工件类型遵循 `openspec instructions` 返回的 `instruction` 与 `template`。
118
- - **需求文档**是范围与验收的权威来源;`context`/`rules` 是给你的约束,**不得**写入输出文件。
119
- - 创建新工件前先读依赖工件,保持与已写规格一致。
120
- - 实现细节优先落在 `tasks.md`:spec 写行为与需求,task 写可追溯的实现与验证映射。
121
-
122
- **护栏**
123
-
124
- - 按模式中 `apply.requires` 创建**全部**必需工件。
125
- - 每写入一个工件后确认文件存在,再进入下一个。
126
- - 对任务项保留 Requirement IDs、Planned Files、Validation Case IDs、Done Criteria,便于后续审计。
127
- - 需求与现有变更冲突或同名目录已存在时:按上文规则在文档中说明关系或自动换名,**不要**反问用户。
@@ -1,31 +0,0 @@
1
- ---
2
- name: test-env-release
3
- description: 部署测试环境。必须先阅读项目根目录下的 `.apm/deploy/README.md` 并按文档执行(文档不存在则终止,不猜测命令)。Use when 用户提到「部署测试环境」「测试环境部署」「发布测试环境」等与测试环境部署相关诉求。
4
- ---
5
-
6
- # 部署测试环境
7
-
8
- ## 目标
9
-
10
- 在目标项目根目录完成一次**可复现**的测试环境部署。所有具体命令、前置条件、校验方式**以项目内文档为准**,本技能不替代该文档。
11
-
12
- ## 唯一权威:`.apm/deploy/README.md`
13
-
14
- 1. **执行任何部署命令之前**,必须先使用 Read 工具阅读**项目根目录**下的:
15
-
16
- `.apm/deploy/README.md`
17
-
18
- 2. **若该文件不存在或无法读取**:立即终止,明确告知用户需在项目根目录补充 `.apm/deploy/README.md` 部署说明;**不要**用 README、package.json 或其它文件猜测部署方式。
19
-
20
- 3. **严格按文档步骤执行**:文档中写明的命令、目录、环境变量、顺序即为执行依据;文档未提及的操作不要自行发明。
21
-
22
- 4. 若文档要求先构建再发布/上传等:仅在文档允许的前提下,再参考文档中指向的其它路径(例如某子目录 README);仍**不得**绕过 `.apm/deploy/README.md` 中已写明的流程。
23
-
24
- ## 失败处理
25
-
26
- - 文档缺失或步骤无法执行:终止并说明缺少什么或哪一步失败。
27
- - 某一步命令非 0 退出:按文档是否有「失败时」说明处理;若无,则终止并输出错误信息,不静默重试无关命令。
28
-
29
- ## 成功判定
30
-
31
- 以 `.apm/deploy/README.md` 中定义的「完成」或「验证」为准(例如健康检查、访问地址、接口返回等)。文档未写成功条件时,以文档列出的最后一步无错误执行完毕为准。