ai-project-manage-cli 6.0.52 → 6.0.53
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.
package/package.json
CHANGED
|
@@ -16,6 +16,13 @@
|
|
|
16
16
|
保存位置: .apm/sessions/<会话 ID>/docs/<文件名>
|
|
17
17
|
文档内容格式: 根据你的主题来，不限制，禁止记流水账。
|
|
18
18
|
|
|
19
|
+
## SQL 变更文档（仅后端）
|
|
20
|
+
|
|
21
|
+
固定文件名: `SQL.md`
|
|
22
|
+
保存位置: `.apm/sessions/<会话 ID>/docs/SQL.md`
|
|
23
|
+
适用场景: 后端开发涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等）时必须产出或追加更新，详见 `.apm/skills/apm-dev/SKILL.md` 中「后端 SQL 变更文档」章节。
|
|
24
|
+
格式要求: 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出。
|
|
25
|
+
|
|
19
26
|
## 文档同步
|
|
20
27
|
|
|
21
28
|
保存到 `docs/` 后，`apm connect` 会在每轮 Agent 结束时自动推送到平台，无需额外操作。
|
|
@@ -24,5 +31,5 @@
|
|
|
24
31
|
|
|
25
32
|
1. 文档内容可以被其他团队成员看到，要有价值，禁止记流水账
|
|
26
33
|
2. 你可以根据你的名字查到自己写的文档，并且禁止更改其他人写的文档
|
|
27
|
-
3.
|
|
34
|
+
3. 不要随便创建新文档，可以在已有文档的基础上添加内容（`SQL.md` 为后端 SQL 变更的固定交付文档，除外）
|
|
28
35
|
4. 文档不可删除，不可更新文档名称，在写入时要谨慎
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
- 「假设」仍有未确认项：**Read** `.apm/sessions/<会话ID>/messages.xml`，查找项目经理是否已回复确认；
|
|
11
11
|
- 项目经理已回复：先按 `.apm/skills/apm-write-plan/SKILL.md` 步骤 5 把确认结果**回填进计划文档并同步**（确认的假设移入「依据」，否定的修订实现步骤与白名单），然后再开发；
|
|
12
12
|
- 项目经理未回复：`@项目经理` 列出待确认假设，**停止本次开发**。
|
|
13
|
-
|
|
13
|
+
严禁带着未回填的澄清直接开发——项目经理在聊天里给过的口径若没落进计划，开发与 diff 评审都不会认。
|
|
14
14
|
|
|
15
15
|
### 步骤 2: 明确开发模式
|
|
16
16
|
|
|
@@ -36,15 +36,41 @@
|
|
|
36
36
|
- 按计划直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
|
|
37
37
|
- **白名单约束**：只改计划白名单内的文件。开发中确需新增文件或改动白名单外文件，先更新计划文档的白名单（写明原因），再动手；**禁止悄悄越界**。
|
|
38
38
|
- **Git**：实现与自洽验收通过后，若有代码改动，**立即 `git add` + `git commit` 一次**（Quick 通常为单次交付，**一次实现 = 一个 commit**；勿拆成无意义碎 commit）。提交信息建议包含 `sessionId`（可从 `session.yaml` 获取）与需求摘要。
|
|
39
|
-
-
|
|
39
|
+
- **后端 SQL 文档**（仅后端）：改动涉及 SQL 时，须 **Write** `docs/SQL.md`（见下文「后端 SQL 变更文档」）。
|
|
40
|
+
- 完成后在返回中说明：改了哪些路径、与白名单的对账结果（逐文件列出）、是否产出/更新 `SQL.md`、是否通过本地可执行的检查（若子 Agent 跑了构建/测试则写明结果）；若有 commit，写明 **short-sha** 与 **subject**，无代码改动则注明跳过 commit。
|
|
40
41
|
|
|
41
42
|
### 步骤 4: 如果前一步判定为 **Spec 开发** 才（在子 Agent 中）执行本步骤，否则执行下一步：
|
|
42
43
|
|
|
43
44
|
1. 父 Agent **Read** `.apm/skills/apm-propose/SKILL.md` 和 `.apm/skills/apm-apply-change/SKILL.md`
|
|
44
45
|
2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `plans/` 下生成 **proposal、design、specs、tasks** 等工件。
|
|
45
|
-
3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`plans/tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit
|
|
46
|
+
3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`plans/tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定；同样遵守计划「改动文件白名单」；**后端**改动涉及 SQL 时须产出 `docs/SQL.md`（见下文「后端 SQL 变更文档」）。
|
|
46
47
|
4. 若 **apm-propose** 未产出可用 **`plans/tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
|
|
47
48
|
|
|
49
|
+
### 后端 SQL 变更文档（仅后端工程师）
|
|
50
|
+
|
|
51
|
+
若本次改动涉及 SQL（DDL/DML、表结构、索引、数据修复、Mapper/XML 中新增或修改 SQL 语句等），开发阶段必须 **Write** `.apm/sessions/<会话ID>/docs/SQL.md`，内容包括：
|
|
52
|
+
|
|
53
|
+
- 变更摘要（改了什么表/数据、为什么）
|
|
54
|
+
- 完整 SQL 语句（按执行顺序排列；**每条须放在 ` ```sql ` 代码块中**，便于复制执行）
|
|
55
|
+
- 执行环境说明（测试/生产是否一致、是否需人工执行）
|
|
56
|
+
- 回滚方案（如适用；回滚 SQL 同样用 ` ```sql ` 代码块）
|
|
57
|
+
|
|
58
|
+
示例：
|
|
59
|
+
|
|
60
|
+
````markdown
|
|
61
|
+
## 变更摘要
|
|
62
|
+
|
|
63
|
+
为 inspection_class 表新增 is_project_add 字段。
|
|
64
|
+
|
|
65
|
+
## 执行 SQL
|
|
66
|
+
|
|
67
|
+
```sql
|
|
68
|
+
ALTER TABLE inspection_class ADD COLUMN is_project_add VARCHAR(1) DEFAULT '0';
|
|
69
|
+
```
|
|
70
|
+
````
|
|
71
|
+
|
|
72
|
+
`BACKEND-PLAN.md` 中不写大段 SQL，只可在实现步骤中注明「须产出 SQL.md」。若会话 `docs/` 下已有 `SQL.md`，在其上追加本次变更，勿另建其他 SQL 文档。
|
|
73
|
+
|
|
48
74
|
### 步骤 5: 提交并 push 代码，保证工作区干净
|
|
49
75
|
|
|
50
76
|
- Quick / Spec 子 Agent 完成且本地已有 commit 时，父 Agent **立即 `git push`**（当前分支首次 push 用 `git push -u origin HEAD`）。
|
|
@@ -55,7 +81,7 @@
|
|
|
55
81
|
开发完成的定义是以下三项**全部满足**，缺一不可：
|
|
56
82
|
|
|
57
83
|
1. **构建通过**：执行本仓库的构建/检查命令（见 AGENTS.md 或部署文档），失败必须修复后重试。
|
|
58
|
-
2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md`
|
|
84
|
+
2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；**后端**涉及 SQL 变更时，须在回复中引用 `docs/SQL.md`，并写明待执行的 SQL 文件名或执行顺序。
|
|
59
85
|
3. **白名单对账**：在回复中逐文件列出本次改动与计划白名单的对应关系。
|
|
60
86
|
|
|
61
87
|
**注意：不做联调。** 前后端各自按 API 契约交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
|
|
@@ -16,13 +16,14 @@
|
|
|
16
16
|
2. 在工作目录执行 `git log --oneline -20`，找到本任务相关的 commit（提交信息中含会话 ID 或需求关键词）。
|
|
17
17
|
3. `git diff <基线>..HEAD --stat` 与 `git diff <基线>..HEAD` 查看完整改动。
|
|
18
18
|
|
|
19
|
-
### 步骤 2
|
|
20
|
-
|
|
21
|
-
| 检查项 | 判定
|
|
22
|
-
| -------------- |
|
|
23
|
-
| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**
|
|
24
|
-
| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**
|
|
25
|
-
| **计划落实** | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**
|
|
19
|
+
### 步骤 2：四项检查
|
|
20
|
+
|
|
21
|
+
| 检查项 | 判定 |
|
|
22
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过** |
|
|
24
|
+
| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过** |
|
|
25
|
+
| **计划落实** | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过** |
|
|
26
|
+
| **SQL 文档** | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失或与改动不一致 → **不通过** |
|
|
26
27
|
|
|
27
28
|
注意事项：
|
|
28
29
|
|
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
1. **依据与假设**：每条关键口径标注来源（需求原文第几条 / 现有代码行为 / 已有文档）；标不出来源的就是「假设」，单独列出。
|
|
36
36
|
2. **改动文件白名单**：本次允许改动的文件完整列表。后续开发与 diff 评审都以此为准，**开发时改了白名单之外的文件会被打回**。
|
|
37
37
|
3. **后端专属——API 契约**：给前端看的接口定义（Path、参数、响应示例、错误码）。前端开发以契约为准，不等后端部署完成。
|
|
38
|
+
4. **后端专属——SQL 变更声明**（仅当涉及表结构/数据变更时）：在「实现步骤」中注明开发须产出 `docs/SQL.md`；计划本身不写大段 SQL，完整语句由后端开发阶段写入该文档。
|
|
38
39
|
|
|
39
40
|
### 步骤 4：回复
|
|
40
41
|
|
|
@@ -62,7 +63,7 @@
|
|
|
62
63
|
|
|
63
64
|
## 写作要求
|
|
64
65
|
|
|
65
|
-
- 篇幅 **40 ～ 100 行**，宁可少写；不要伪代码、不要大段 SQL
|
|
66
|
+
- 篇幅 **40 ～ 100 行**，宁可少写；不要伪代码、不要大段 SQL（完整语句写入 `docs/SQL.md`，由后端开发阶段产出）。
|
|
66
67
|
- 用产品语言描述行为，文件路径只出现在「改动文件白名单」。
|
|
67
68
|
- 前后端可同轮并行编写计划，不互相阻塞。
|
|
68
69
|
|
|
@@ -8,17 +8,17 @@
|
|
|
8
8
|
|
|
9
9
|
## 1. 需求理解
|
|
10
10
|
|
|
11
|
-
用 3～5 行复述本端要做什么（产品语言），不复制需求原文。
|
|
11
|
+
用 3 ～ 5 行复述本端要做什么（产品语言），不复制需求原文。
|
|
12
12
|
|
|
13
13
|
## 2. 依据与假设
|
|
14
14
|
|
|
15
15
|
### 依据（口径 + 来源）
|
|
16
16
|
|
|
17
|
-
| #
|
|
18
|
-
|
|
19
|
-
| 1
|
|
20
|
-
| 2
|
|
21
|
-
| 3
|
|
17
|
+
| # | 口径 | 来源 |
|
|
18
|
+
| --- | ------------------------------ | ----------------------------- |
|
|
19
|
+
| 1 | 「是否加分」与「是否扣分」互斥 | 需求原文第 1 条 |
|
|
20
|
+
| 2 | 加分项不汇总进分类分值 | 需求原文第 2 条 |
|
|
21
|
+
| 3 | 分值字段现状为 varchar | 代码现状：inspection_class 表 |
|
|
22
22
|
|
|
23
23
|
### 假设（待项目经理确认，确认前不开发）
|
|
24
24
|
|
|
@@ -31,7 +31,9 @@
|
|
|
31
31
|
|
|
32
32
|
1. 第一步做什么（对应哪条口径）
|
|
33
33
|
2. 第二步做什么
|
|
34
|
-
3. ...（通常 3～6 步，不写代码细节）
|
|
34
|
+
3. ...（通常 3 ～ 6 步，不写代码细节）
|
|
35
|
+
|
|
36
|
+
> **后端**：若涉及表结构或数据变更，在步骤中注明「开发须产出 `docs/SQL.md`」，SQL 语句不写在本计划内。
|
|
35
37
|
|
|
36
38
|
## 4. 改动文件白名单
|
|
37
39
|
|
|
@@ -49,13 +51,13 @@
|
|
|
49
51
|
- Path：`POST /inspection/project/save`
|
|
50
52
|
- 新增入参：
|
|
51
53
|
|
|
52
|
-
| 字段
|
|
53
|
-
|
|
54
|
-
| isProjectAdd | string | 否
|
|
54
|
+
| 字段 | 类型 | 必填 | 说明 |
|
|
55
|
+
| ------------ | ------ | ---- | -------------------------------- |
|
|
56
|
+
| isProjectAdd | string | 否 | "1"=加分项；与 isProjectDed 互斥 |
|
|
55
57
|
|
|
56
58
|
- 响应示例：
|
|
57
59
|
|
|
58
|
-
|
|
60
|
+
{ "success": true, "result": { "id": "xxx" } }
|
|
59
61
|
|
|
60
62
|
- 错误码：互斥冲突返回 `success=false, message="加分与扣分不可同时勾选"`
|
|
61
63
|
|