ai-project-manage-cli 4.0.21 → 4.0.23

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 (8) hide show
  1. package/dist/index.js +446 -177
  2. package/package.json +1 -1
  3. package/template/theater-skills/README.md +13 -0
  4. package/template/theater-skills/apm-theater-backend/SKILL.md +115 -0
  5. package/template/theater-skills/apm-theater-backend/apm-theater-api-template.md +146 -0
  6. package/template/theater-skills/apm-theater-backend/apm-theater-backend-template.md +132 -0
  7. package/template/theater-skills/apm-theater-dev/SKILL.md +149 -0
  8. package/template/theater-skills/apm-theater-prd/SKILL.md +98 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-project-manage-cli",
3
- "version": "4.0.21",
3
+ "version": "4.0.23",
4
4
  "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
5
5
  "type": "module",
6
6
  "private": false,
package/template/theater-skills/README.md ADDED
@@ -0,0 +1,13 @@
1
+ ## 剧场技能
2
+
3
+ 供剧场（Theater）会话中各角色 Agent 使用的技能，由 `apm init` 复制到 `.apm/theater-skills/`，可用 `apm update-theater-skills` 从 CLI 内置模板重置。
4
+
5
+ `THEATER_JOB` 开始时会自动 `pull-session`，将平台会话文档下载到 `.apm/theater-sessions/<sessionId>/docs/`。`docs/` 下文档变更后通过 `apm sync-session-document` 同步到平台；**Agent 对话日志不上传**。
6
+
7
+ ## 目录
8
+
9
+ | 技能 | 说明 |
10
+ | ---------------------- | -------------------------------------------------------------------------------------------------------- |
11
+ | `apm-theater-prd/` | 产品经理：维护会话 PRD（`.apm/theater-sessions/<sessionId>/docs/prd.md`）并同步到平台 |
12
+ | `apm-theater-backend/` | 后端：`docs/backend.md`（技术评审实现思路）、`docs/api.md`（前端联调接口说明）；增删改查与同步规则同 PRD |
13
+ | `apm-theater-dev/` | 开发：按 `sessionId` 全自动编码（切分支、Quick/Spec、提交推送、同步 `docs/` 文档） |
package/template/theater-skills/apm-theater-backend/SKILL.md ADDED
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: apm-theater-backend
3
+ description: 剧场会话后端文档：在 .apm/theater-sessions/<sessionId>/docs/ 维护 backend.md（技术评审用实现思路）与 api.md（前端联调用接口说明），落盘后同步到平台会话文档。仅当用户 @ 本技能时使用。
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # 剧场会话后端文档
8
+
9
+ 在剧场会话上下文中维护后端交付文档：
10
+
11
+ | 文件 | 用途 |
12
+ | --------------------- | ------------------------------------------------------------ |
13
+ | **`docs/backend.md`** | **后端技术文档**：如何实现该需求，实现思路写清，供技术评审 |
14
+ | **`docs/api.md`** | **接口联调文档**：涉及接口与参数，给前端；多接口协作须写清楚 |
15
+
16
+ 本地路径均在 **`.apm/theater-sessions/<sessionId>/docs/`**；落盘后须通过 CLI 同步到平台「会话文档」。
17
+
18
+ `THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；仅 `docs/` 下业务文档在变更后同步。
19
+
20
+ ---
21
+
22
+ ## 输入
23
+
24
+ | 字段 | 规则 |
25
+ | --------------- | -------------------------------------------------------------------------------------- |
26
+ | **`sessionId`** | **必填**。剧场会话 ID，与 `.apm/theater-sessions/<sessionId>/` 目录名一致。 |
27
+ | **目标文档** | 按用户意图选择 `backend.md` 或 `api.md`；未指明时结合上下文判断，仍不明则询问。 |
28
+ | **会话上下文** | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
29
+
30
+ ---
31
+
32
+ ## 文件路径
33
+
34
+ 以下规则对 **`backend.md`**、**`api.md`** 均适用（将 `<文件名>` 替换为对应文件）：
35
+
36
+ | 操作 | 路径 / 方式 |
37
+ | -------- | ------------------------------------------------------------------------------------- |
38
+ | **新增** | 创建 `.apm/theater-sessions/<sessionId>/docs/<文件名>`（`docs` 目录不存在时一并创建） |
39
+ | **编辑** | 更新上述文件（Write / StrReplace） |
40
+ | **查阅** | 使用 **Read** 工具阅读上述文件 |
41
+ | **删除** | **不支持**。不要删除该文件，也不要尝试从平台删除对应文档。 |
42
+
43
+ ---
44
+
45
+ ## 同步到平台（新增 / 编辑后必做）
46
+
47
+ 本地文档 **新增或内容变更后**执行：
48
+
49
+ ```bash
50
+ apm sync-session-document <sessionId> --file docs/backend.md
51
+ apm sync-session-document <sessionId> --file docs/api.md
52
+ ```
53
+
54
+ - 命令会调用平台接口 **新增或更新** 该会话的产物文档（按 `fileName` 幂等）。
55
+ - **查阅**（Read）**不需要**执行同步。
56
+ - **不要**同步 Agent 对话日志（`sessions/` 等）；仅同步 `docs/` 业务文档。
57
+ - 同步失败时：在回复中说明错误，**不要**声称已写入平台。
58
+
59
+ ---
60
+
61
+ ## 撰写要求
62
+
63
+ 撰写前建议 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（若存在），与需求范围对齐。
64
+
65
+ ### `backend.md`（技术评审）
66
+
67
+ 须 **Read** [apm-theater-backend-template.md](./apm-theater-backend-template.md)，按模板**章节粒度**组织正文（需求摘要 → 方案总览 → 库表 → 分层 → 核心流程 → 实现状态 → 待办 → 风险）。核心是 **实现思路写清楚**；接口参数明细放 `api.md`。
68
+
69
+ ### `api.md`（前端联调）
70
+
71
+ 须 **Read** [apm-theater-api-template.md](./apm-theater-api-template.md)，按模板**章节粒度**组织正文（基础约定 → 数据模型 → 接口清单 → 接口明细 → 页面配合 → 错误场景 → 联调清单）。写清每个功能的**方法、路径、参数、响应**；多接口协作须写**步骤、顺序、副作用与前端展示规则**。
72
+
73
+ ---
74
+
75
+ ## 流程
76
+
77
+ ### 1. 锚定会话与文档
78
+
79
+ 确认 **`sessionId`** 与目标文件（`backend.md` / `api.md`）。
80
+
81
+ ### 2. 查阅（只读）
82
+
83
+ **Read** `.apm/theater-sessions/<sessionId>/docs/<文件名>`。
84
+
85
+ - 文件不存在：说明尚未创建，询问是否新建；**不要**编造正文。
86
+
87
+ ### 3. 新增 `backend.md`
88
+
89
+ 1. **Read** `prd.md`（若存在）与 [apm-theater-backend-template.md](./apm-theater-backend-template.md)。
90
+ 2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/backend.md`。
91
+ 3. **`apm sync-session-document <sessionId> --file docs/backend.md`**。
92
+
93
+ ### 4. 新增 `api.md`
94
+
95
+ 1. **Read** `prd.md`、必要时 `backend.md`，以及 [apm-theater-api-template.md](./apm-theater-api-template.md)。
96
+ 2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/api.md`。
97
+ 3. **`apm sync-session-document <sessionId> --file docs/api.md`**。
98
+
99
+ ### 5. 编辑
100
+
101
+ 1. **Read** 现有文件与对应模板（若本会话尚未读过）。
102
+ 2. **Write** 或 **StrReplace** 落盘。
103
+ 3. **`apm sync-session-document <sessionId> --file docs/<文件名>`**。
104
+ 4. 简要说明变更要点。
105
+
106
+ ---
107
+
108
+ ## Guardrails
109
+
110
+ - **不要删除** `backend.md`、`api.md`，也不要删除平台会话文档。
111
+ - **不要**在无 `sessionId` 时写入任意目录。
112
+ - **新增或编辑后必须同步** `docs/` 文档；仅 Read 时不同步。
113
+ - **不要**上传或同步 Agent 对话日志。
114
+ - 同步失败时如实报告，不假装成功。
115
+ - `backend.md` 与 `api.md` 分工明确：方案在 backend，接口契约在 api；待确认项写入文档，避免阻塞主文。
package/template/theater-skills/apm-theater-backend/apm-theater-api-template.md ADDED
@@ -0,0 +1,146 @@
1
+ # 接口联调文档模板
2
+
3
+ **定位**：给**前端**联调用的接口说明——写清涉及到的接口、参数、响应与页面配合方式；若某功能需**多个接口配合**（如先上传再绑定），须写清**步骤、顺序与副作用**。
4
+
5
+ 撰写前建议 **Read** `prd.md`、必要时 **Read** `backend.md`，与需求及后端方案对齐。
6
+
7
+ ---
8
+
9
+ ## 正文骨架
10
+
11
+ 按下列章节组织（编号可依项目调整，但**顺序与粒度**保持一致）：
12
+
13
+ ```markdown
14
+ # [需求标题] — 接口联调文档
15
+
16
+ > 后端模块：`XxxController`（`/模块前缀`）
17
+
18
+ ## 1. 基础约定
19
+
20
+ ### 1.1 Base URL
21
+
22
+ （开发/测试示例地址；是否带 context-path）
23
+
24
+ ### 1.2 鉴权
25
+
26
+ （Header / Token 名称；本期是否有额外权限参数）
27
+
28
+ ### 1.3 统一响应体
29
+
30
+ （字段表 + 成功/失败 JSON 示例；写明业务数据在哪个字段，如 `result` / `data`）
31
+
32
+ ### 1.4 特殊接口说明（若有）
33
+
34
+ （如：文件流下载无 JSON 包装、预览返回路径给现网组件等）
35
+
36
+ ---
37
+
38
+ ## 2. 数据模型 `[实体名]`
39
+
40
+ 列表、详情、编辑共用的核心字段表（字段 | 类型 | 说明）；**前端展示规则**写进说明列（如某字段为 `null` 时列表留空）。
41
+
42
+ ---
43
+
44
+ ## 3. 接口清单
45
+
46
+ | 方法 | 路径 | 说明 |
47
+ | ---- | ---- | ---- |
48
+ | … | … | … |
49
+
50
+ 未落地接口在说明列标 **待后端实现/提供**。
51
+
52
+ ---
53
+
54
+ ## 4. 接口明细
55
+
56
+ ### 4.1 [接口名称]
57
+
58
+ **[METHOD]** `完整路径`
59
+
60
+ **Query / Body 参数表**（参数 | 必填 | 默认 | 说明）
61
+
62
+ **响应**（`result` / `data` 结构；复杂时给 JSON 示例）
63
+
64
+ **前端展示/交互要点**（与本接口直接相关的 UI 规则）
65
+
66
+ **说明**（业务副作用、与 PRD 的对应关系）
67
+
68
+ ### 4.2 …
69
+
70
+ #### 多步骤协作（如「行内上传 + 绑定」）
71
+
72
+ 分步骤写清，每步单独小节：
73
+
74
+ 1. **步骤 1**：上传接口 — 入参、成功时哪个字段是后续要用的路径
75
+ 2. **步骤 2**：编辑/保存接口 — Body 示例（首次 / 更换两种）、副作用（如是否更新 `submitDate`）、成功后是否刷新列表
76
+
77
+ **注意**：只读页面不调写接口等 PRD 约束写在本节。
78
+
79
+ ### 4.x 易混淆接口对比（若存在）
80
+
81
+ 用表格对比「入口 | 接口 | 内容」，避免前端联调混用。
82
+
83
+ ---
84
+
85
+ ## 5. 前端页面与接口配合
86
+
87
+ 按页面用缩进树或列表写调用链，例如：
88
+
89
+ ### 5.1 列表页
90
+
91
+ 加载列表 → GET /list
92
+ ├─ 新增 → …
93
+ ├─ 删除 → …
94
+ └─ 某列操作 → 多步 upload → edit
95
+
96
+ ### 5.2 新增页 / 详情页
97
+
98
+ …
99
+
100
+ ---
101
+
102
+ ## 6. 错误场景
103
+
104
+ | 场景 | 表现 |
105
+ | ---- | --------------------------------------- |
106
+ | … | `success=false` 的 message 或 HTTP 状态 |
107
+
108
+ ---
109
+
110
+ ## 7. 联调检查清单
111
+
112
+ - [ ] …
113
+ - [ ] …
114
+ ```
115
+
116
+ ---
117
+
118
+ ## 写法要点
119
+
120
+ | 类型 | 写法要点 |
121
+ | ---------- | --------------------------------------------------------------------------- |
122
+ | 接口清单 | 先总表后明细；路径、方法、一句话说明齐全 |
123
+ | 单接口 | 参数表 + 响应结构 + **前端展示要点**；复杂 Body 给完整 JSON 示例 |
124
+ | 多接口协作 | 分步骤编号；每步写清入参、成功判据、传给下一步的字段；写副作用与是否刷新 |
125
+ | 数据模型 | 共用实体一次定义；`null` / 空值的 UI 处理写在字段说明或列表要点里 |
126
+ | 页面配合 | 按列表/新增/详情分节；用树状流程串起接口，不只堆接口表 |
127
+ | 易混淆能力 | 同类下载/预览等多入口时，用对比表说明差异 |
128
+ | 待实现 | 明确标 **待后端实现**；错误场景与检查清单可预留项 |
129
+ | 项目约定 | 遵循目标项目既有风格（如 Jeecg `Result`、APM `{ data }`）；不擅自改路径规范 |
130
+
131
+ ---
132
+
133
+ ## 落盘前自检
134
+
135
+ - [ ] 含 **基础约定、数据模型、接口清单、接口明细、页面配合、错误场景、联调清单**
136
+ - [ ] 每个 PRD 功能点在「页面配合」或明细中能找到对应接口
137
+ - [ ] 多步骤流程（上传+保存等）顺序与字段传递写清
138
+ - [ ] 列表/详情/空值展示规则前端可直接照做
139
+ - [ ] 与 `backend.md` 不矛盾；未实现接口已标注
140
+ - [ ] 检查清单覆盖 PRD 关键验收点
141
+
142
+ ---
143
+
144
+ ## 局部替换
145
+
146
+ 只改部分接口或页面时：同步更新 **§3 清单**、**§4 明细**、**§5 页面配合** 与 **§7 检查清单** 中相关条目。
package/template/theater-skills/apm-theater-backend/apm-theater-backend-template.md ADDED
@@ -0,0 +1,132 @@
1
+ # 后端技术文档模板
2
+
3
+ **定位**：说明后端**准备如何实现该需求**，实现思路写清楚，供**技术评审**。接口参数与前端联调细节放在 `api.md`，本文聚焦方案、数据、流程与实现状态。
4
+
5
+ 撰写前须 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（若存在）。
6
+
7
+ ---
8
+
9
+ ## 正文骨架
10
+
11
+ ```markdown
12
+ # [需求标题] — 后端技术方案
13
+
14
+ > 关联 PRD：[prd.md](./prd.md)
15
+
16
+ ## 1. 需求摘要
17
+
18
+ （一段话概括本期做什么；**本期不做**单独列出）
19
+
20
+ ---
21
+
22
+ ## 2. 方案总览
23
+
24
+ | 项 | 说明 |
25
+ | -------- | ----------------- |
26
+ | 模块 | … |
27
+ | 数据表 | … |
28
+ | 接口前缀 | … |
29
+ | 实现风格 | … |
30
+ | 代码现状 | 已落地 / 待完善项 |
31
+
32
+ （与同类既有模块的差异、核心设计决策 1 ～ 3 句）
33
+
34
+ ---
35
+
36
+ ## 3. 数据库设计
37
+
38
+ （迁移脚本路径若有则写）
39
+
40
+ | 字段 | 类型 | 说明 |
41
+ | ---- | ---- | ---- |
42
+ | … | … | … |
43
+
44
+ **索引**、**约束**、注释与命名注意点。
45
+
46
+ ---
47
+
48
+ ## 4. 后端分层结构
49
+
50
+ （目录树或包结构：entity / mapper / service / controller）
51
+
52
+ ---
53
+
54
+ ## 5. 核心业务流程
55
+
56
+ 按 PRD 场景分小节（如 5.1 新增、5.2 行内上传…），每节写清：
57
+
58
+ 1. 步骤顺序
59
+ 2. 校验规则与 **不做什么**
60
+ 3. 副作用（写库、写文件、更新时间等）
61
+ 4. **待实现** 项单独标出
62
+
63
+ 多接口协作写清与通用能力（如上传）的组合方式；易混淆能力用表格对比。
64
+
65
+ ---
66
+
67
+ ## 6. 接口能力对照（实现状态）
68
+
69
+ | 能力 | 状态 | 备注 |
70
+ | ---- | ------------ | ---- |
71
+ | … | ✅ / ⚠️ / ❌ | … |
72
+
73
+ （评审用速览表；细节不在此重复，见 `api.md`）
74
+
75
+ ---
76
+
77
+ ## 7. 菜单与权限（若涉及）
78
+
79
+ ---
80
+
81
+ ## 8. 配置与部署
82
+
83
+ | 配置 | 说明 |
84
+ | ---- | ---- |
85
+ | … | … |
86
+
87
+ ---
88
+
89
+ ## 9. 待办清单（开发任务）
90
+
91
+ 1. …
92
+ 2. …
93
+
94
+ ---
95
+
96
+ ## 10. 风险与注意点
97
+
98
+ - …
99
+ ```
100
+
101
+ 按需删减章节（如无独立菜单配置可省略 §7）；**核心业务流程**与 **待办清单** 不可省。
102
+
103
+ ---
104
+
105
+ ## 写法要点
106
+
107
+ | 类型 | 写法要点 |
108
+ | ---------- | ----------------------------------------------------------------------- |
109
+ | 需求摘要 | 与 PRD 一一对应；**本期不做** 写清，避免评审范围漂移 |
110
+ | 方案总览 | 模块、表、接口前缀、与存量模块关系；**代码现状** 如实（已做/待补） |
111
+ | 数据库 | 字段业务含义、NULL 语义、何时写入；索引与 PRD 约束（如不做唯一性）对齐 |
112
+ | 核心流程 | 分场景编号；写清两步/多步协作、副作用、与 PRD 差异；**待实现** 醒目标注 |
113
+ | 实现状态表 | 能力粒度与 PRD 验收点对齐；用 ✅ ⚠️ ❌ 或文字状态 |
114
+ | 待办清单 | 可执行任务，与 §6 中未完成项对应 |
115
+ | 风险 | 安全、磁盘、与相似模块混淆等；不写接口 JSON |
116
+
117
+ ---
118
+
119
+ ## 落盘前自检
120
+
121
+ - [ ] 评审人不读代码也能理解**怎么做、差什么**
122
+ - [ ] 与 `prd.md` 范围一致，「本期不做」无遗漏
123
+ - [ ] 核心流程覆盖 PRD 各场景，含多步协作与副作用
124
+ - [ ] §6 实现状态与 §9 待办一致
125
+ - [ ] 接口契约细节在 `api.md`，本文不重复参数表
126
+ - [ ] 未臆造已完成功能；待做项已列出
127
+
128
+ ---
129
+
130
+ ## 局部替换
131
+
132
+ 只改部分能力时：同步更新 **§5 流程**、**§6 状态表**、**§9 待办** 与 **§10 风险** 中相关条目。
package/template/theater-skills/apm-theater-dev/SKILL.md ADDED
@@ -0,0 +1,149 @@
1
+ ---
2
+ name: apm-theater-dev
3
+ description: 按剧场会话 ID 全自动编码：按需读会话 PRD（及 backend/api 文档）、按改动规模选择 Quick 或 Spec、推送代码；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及剧场全自动开发或「apm-theater-dev」时使用。
4
+ ---
5
+
6
+ # 剧场全自动开发（按会话 ID）
7
+
8
+ 用户给出 **剧场会话 ID**（`sessionId`，与 `.apm/theater-sessions/<sessionId>/` 目录名一致）。**缺 ID 时索要，不猜测。**
9
+
10
+ 由 **`THEATER_JOB` / `apm connect`** 自动完成（**无需在本技能中切分支**）：
11
+
12
+ - 检出或创建 **`feat/req-<sessionId>`** 并拉取最新
13
+ - **pull** 平台会话文档到 `.apm/theater-sessions/<sessionId>/docs/`
14
+ - Agent 结束后若有未提交变更，CLI 自动 **`git add` & `commit`**
15
+
16
+ Agent **对话日志不上传**。**不要**执行 `apm sync-session-document`（会话文档由网页或其他角色维护）。
17
+
18
+ ---
19
+
20
+ ## 输入
21
+
22
+ | 字段 | 规则 |
23
+ | --------------- | -------------------------------------------------------------------------------------- |
24
+ | **`sessionId`** | **必填**。与 `.apm/theater-sessions/<sessionId>/` 目录名一致。 |
25
+ | **会话上下文** | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
26
+
27
+ **会话根目录**：`.apm/theater-sessions/<sessionId>/`
28
+ **PRD（按需）**：`docs/prd.md`
29
+ **可选参考（按需）**：`docs/backend.md`、`docs/api.md`
30
+
31
+ ---
32
+
33
+ ## 技能文件定位（apm-propose / apm-apply-change）
34
+
35
+ Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。进入 Spec 子流程前父 Agent **须 Read**：
36
+
37
+ | 技能 | 路径 |
38
+ | -------------------- | --------------------------------------- |
39
+ | **apm-propose** | `.apm/skills/apm-propose/SKILL.md` |
40
+ | **apm-apply-change** | `.apm/skills/apm-apply-change/SKILL.md` |
41
+
42
+ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-instruction.md`）。若上述 `SKILL.md` **不存在或不可读**：**不得**进入 Spec 子流程；在表格中标记失败原因（例如需先 `apm init` 或 `apm update-skills`），并停止步骤 3。
43
+
44
+ 委派子 Agent 时须说明：本轮为**剧场会话**，**`sessionId`** 替代需求 ID；PRD 在 **`docs/prd.md`**（按需阅读）；Spec 工件落在 **`.apm/theater-sessions/<sessionId>/`**（非 `workitems`）。
45
+
46
+ ---
47
+
48
+ ## 流程总览
49
+
50
+ | 序号 | 步骤 | 说明 |
51
+ | ---- | ------------------------- | ----------------------------------------------------------------------------------------- |
52
+ | 1 | **按需读文档 + 成本评估** | 按本轮任务**按需 Read** `docs/prd.md` 及需要的 `backend.md` / `api.md`，判定 Quick / Spec |
53
+ | 2 | **Quick 开发** | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码 |
54
+ | 3 | **Spec 开发** | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**（子 Agent） |
55
+ | 4 | **推送** | `git push`；确认工作区干净（提交通常已由 CLI 在 Agent 结束时完成） |
56
+
57
+ 流程**仅以上 4 步**，**无**同步会话文档环节（不执行 `apm sync-session-document`）。
58
+
59
+ ---
60
+
61
+ ## 步骤 1：按需读文档并评估改动成本
62
+
63
+ 1. **不要**无差别全文 Read `prd.md`；根据主持委派任务、已有对话与实现范围，**按需**阅读：
64
+ - 需要理解需求范围或验收时 → **Read** `docs/prd.md`（全文或相关章节）
65
+ - 涉及后端实现思路 → **Read** `docs/backend.md`
66
+ - 涉及接口联调 → **Read** `docs/api.md`
67
+ 2. 若任务明确只需改代码、且上下文已足够，可**跳过**读 PRD，但在表格中注明依据（例如「主持任务已说明改 X 文件」）。
68
+ 3. 若判定需要 PRD/backend/api 但文件不存在或读失败，**停止后续实现**，仅在表格中标记失败原因。
69
+ 4. **不**为评估向用户发起追问；信息不足时倾向 **Spec**（保守）。
70
+
71
+ ### Quick（较小）与 Spec（较大）判定参考
72
+
73
+ **倾向 Quick**（满足越多越适用）：
74
+
75
+ - 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
76
+ - 无新表结构/大规模迁移/权限模型变更。
77
+ - 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
78
+ - 不需要跨多服务的架构裁定即可开工。
79
+
80
+ **倾向 Spec**（命中任一条即可）：
81
+
82
+ - 前后端联动、多包改造或新公共抽象。
83
+ - 新数据模型、迁移、或安全/审计/权限相关。
84
+ - 范围大、条款多，或存在明显「待确认/多方案」需先规划。
85
+ - 评估认为不先产出 **proposal / design / specs / tasks** 则难以保证实现与验收对齐。
86
+
87
+ 在表格「步骤 1」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）；若读了哪些文档也一并注明。
88
+
89
+ ---
90
+
91
+ ## 步骤 2：Quick 开发模式（子 Agent）
92
+
93
+ **条件**：步骤 1 判定为 **Quick**。
94
+
95
+ 1. 父 Agent 已按需掌握必要文档；委派时在提示中写明 **`sessionId`**、会话根路径、以及「实现须对照已读文档与主持任务，改动范围最小化」。
96
+ 2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
97
+ - **按需 Read** `docs/prd.md` 及需要的 `backend.md` / `api.md`。
98
+ - 按任务与文档直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
99
+ - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若跑了 `rushx build` / 测试等则写明结果）。
100
+ 3. 父 Agent 根据子 Agent 返回在表格中填写步骤 2 **状态**；本模式下步骤 3 填 **跳过**。
101
+
102
+ ---
103
+
104
+ ## 步骤 3：Spec 开发模式（子 Agent）
105
+
106
+ **条件**：步骤 1 判定为 **Spec**。
107
+
108
+ 1. 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
109
+ 2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并遵循，但将工件目录改为 **`.apm/theater-sessions/<sessionId>/`**，PRD 来源为 **`docs/prd.md`**（按需阅读），上下文使用 **`sessionId`** 而非 `requirementId`；生成 **proposal、design、specs、tasks** 等（顺序以 SKILL 为准）。
110
+ 3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并遵循：按 **`.apm/theater-sessions/<sessionId>/tasks.md`** 驱动实现与勾选。
111
+ 4. 若未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
112
+ 5. 表格中步骤 2 填 **跳过**；步骤 3 分两行或合并一行写清 propose / apply 状态。
113
+
114
+ ---
115
+
116
+ ## 步骤 4：推送
117
+
118
+ 在仓库根目录执行：
119
+
120
+ 1. `git status`：确认变更范围；若仍有未提交变更（例如子 Agent 在 CLI 自动 commit 之后又改了文件），执行 `git add -A` 与 `git commit -m "feat(req-<sessionId>): <简短说明>"`。
121
+ 2. `git push`：推送到当前分支 **`feat/req-<sessionId>`**（首次必要时 `-u origin feat/req-<sessionId>`）。
122
+ 3. 再次 `git status`：**须为干净工作区**。
123
+
124
+ 将命令结果、当前分支名、是否已 push、工作区是否干净写入表格（见下节「回复格式」）。
125
+
126
+ ---
127
+
128
+ ## 回复格式
129
+
130
+ 完成步骤 4 后，对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1 ～ 4**：
131
+
132
+ | 步骤 | 内容 | 结果 |
133
+ | ---- | ------------------------------------------------ | ------------------------------ |
134
+ | 1 | 按需读文档 + 成本评估 | Quick 或 Spec；读了哪些 / 失败 |
135
+ | 2 | Quick 开发（子 Agent） | 成功 / 失败 / **跳过** |
136
+ | 3 | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过** |
137
+ | 4 | push；工作区干净 | 成功 / 失败（原因） |
138
+
139
+ **可选**：表格外增加**简短**摘要（当前分支、阻塞点）。
140
+
141
+ ---
142
+
143
+ ## Guardrails
144
+
145
+ - **失败即终止**：在用户提供的 **`sessionId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络等做**多次**重试。
146
+ - **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**。
147
+ - **不要**在无依据的情况下编造需求实现；需要 PRD 时须先 Read，读不到则停止。
148
+ - **不要**上传或同步 Agent 对话日志。
149
+ - **子 Agent** 提示中须带 **`sessionId`** 与会话根路径，避免改错工作树。
package/template/theater-skills/apm-theater-prd/SKILL.md ADDED
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: apm-theater-prd
3
+ description: 剧场会话 PRD 文档：在 .apm/theater-sessions/<sessionId>/docs/prd.md 新增、编辑、查阅需求正文，落盘后同步到平台会话文档。仅当用户 @ 本技能时使用。
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # 剧场会话 PRD
8
+
9
+ 在剧场会话上下文中维护 **产品需求文档（PRD）**。本地权威路径为 **`.apm/theater-sessions/<sessionId>/docs/prd.md`**；落盘后须通过 CLI 同步到平台「会话文档」。
10
+
11
+ `THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；仅 `docs/` 下业务文档在变更后同步。
12
+
13
+ ---
14
+
15
+ ## 输入
16
+
17
+ | 字段 | 规则 |
18
+ | --------------- | -------------------------------------------------------------------------------------- |
19
+ | **`sessionId`** | **必填**。剧场会话 ID，与 `.apm/theater-sessions/<sessionId>/` 目录名一致。 |
20
+ | **会话上下文** | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
21
+
22
+ ---
23
+
24
+ ## 文件路径
25
+
26
+ | 操作 | 路径 / 方式 |
27
+ | -------- | ----------------------------------------------------------------------------------- |
28
+ | **新增** | 创建 `.apm/theater-sessions/<sessionId>/docs/prd.md`（`docs` 目录不存在时一并创建） |
29
+ | **编辑** | 更新上述文件（Write / StrReplace） |
30
+ | **查阅** | 使用 **Read** 工具阅读上述文件 |
31
+ | **删除** | **不支持**。不要删除该文件，也不要尝试从平台删除对应文档。 |
32
+
33
+ ---
34
+
35
+ ## 同步到平台（新增 / 编辑后必做）
36
+
37
+ 本地 `prd.md` **新增或内容变更后**执行：
38
+
39
+ ```bash
40
+ apm sync-session-document <sessionId>
41
+ ```
42
+
43
+ - 默认同步 `docs/prd.md`；若同步其他相对路径，加 `--file <相对路径>`（相对于 `.apm/theater-sessions/<sessionId>/`）。
44
+ - 命令会调用平台接口 **新增或更新** 该会话的产物文档（按 `fileName` 幂等）。
45
+ - **查阅**（Read）**不需要**执行同步。
46
+ - **不要**同步 Agent 对话日志（`sessions/` 等）；仅同步 `docs/` 业务文档。
47
+ - 同步失败时：在回复中说明错误，**不要**声称已写入平台。
48
+
49
+ ---
50
+
51
+ ## 撰写要求（PRD 正文）
52
+
53
+ 撰写或修订 `prd.md` 前，须 **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)，按其中正文骨架、需求点写法、示例与落盘自检组织正文。
54
+
55
+ 在此基础上补充：
56
+
57
+ - **可验收**：产品、测试、开发不读代码也能写用例。
58
+ - **业务化**：写界面、流程、规则与系统表现；避免堆砌实现细节。
59
+ - **术语统一**：同一概念全文同一叫法。
60
+
61
+ ---
62
+
63
+ ## 流程
64
+
65
+ ### 1. 锚定会话
66
+
67
+ 确认 **`sessionId`**。根目录：`.apm/theater-sessions/<sessionId>/docs/`。
68
+
69
+ ### 2. 查阅（只读）
70
+
71
+ **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`。
72
+
73
+ - 文件不存在：说明尚未创建，询问是否新建；**不要**编造正文。
74
+
75
+ ### 3. 新增
76
+
77
+ 1. **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)，按模板撰写完整 PRD 正文。
78
+ 2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/prd.md`。
79
+ 3. 执行 **`apm sync-session-document <sessionId>`**。
80
+ 4. 简要确认：本地路径、已同步到会话文档。
81
+
82
+ ### 4. 编辑
83
+
84
+ 1. **Read** 现有 `prd.md`（若本会话尚未读过）。
85
+ 2. 按需 **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)；按用户或场景要求修订；**Write** 或 **StrReplace** 落盘。
86
+ 3. 执行 **`apm sync-session-document <sessionId>`**。
87
+ 4. 简要说明变更要点。
88
+
89
+ ---
90
+
91
+ ## Guardrails
92
+
93
+ - **不要删除** `prd.md`，也不要删除平台会话文档。
94
+ - **不要**在无 `sessionId` 时写入任意目录。
95
+ - **新增或编辑后必须同步** `docs/` 文档；仅 Read 时不同步。
96
+ - **不要**上传或同步 Agent 对话日志。
97
+ - 同步失败时如实报告，不假装成功。
98
+ - 向用户澄清范围时，歧义写入 PRD 的「待确认」或「假设」，避免阻塞整篇文档。