@wbline/pi-plan-build 0.0.1 → 0.0.2
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/CHANGELOG.md +62 -0
- package/README.md +10 -6
- package/package.json +2 -1
- package/src/core/guard.ts +98 -18
- package/src/core/schema.ts +5 -1
- package/src/core/state.ts +40 -18
- package/src/engine.ts +20 -7
- package/src/index.ts +20 -3
- package/src/lifecycle.ts +12 -8
- package/src/tools/plan-exit.ts +7 -2
- package/src/tools/plan-steps.ts +13 -11
- package/src/tools/plan-task.ts +10 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# 更新日志
|
|
2
|
+
|
|
3
|
+
本项目的所有显著变更都记录在此文件中。
|
|
4
|
+
|
|
5
|
+
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本遵循语义化版本。
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
(暂无)
|
|
10
|
+
|
|
11
|
+
## [0.0.2] - 2026-10-16
|
|
12
|
+
|
|
13
|
+
0.0.1 发 npm 后的全部修复与改进。
|
|
14
|
+
|
|
15
|
+
### 新增
|
|
16
|
+
|
|
17
|
+
- `/plan`、`/build` 直切模式命令(保留 `/plan-build` 菜单与 Alt+M)——IDE(ACP)桥接层 `setSessionMode` 按命令名调用,JetBrains AI 聊天的 Plan/Build 模式选择器依赖这两个命令
|
|
18
|
+
- 守卫覆盖 IDE 变更通道:`ide_webstorm_apply_patch`(解析 codex/unified diff 目标)、`ide_webstorm_create_new_file`(`pathInProject`)、`ide_webstorm_reformat_file`(`files[]`);`ide_webstorm_rename_refactoring` 波及面无法验证,Plan 模式一律阻断
|
|
19
|
+
- 持久化状态附带 `selectedMode` 字段,供 IDE 模式选择器同步显示
|
|
20
|
+
|
|
21
|
+
### 修复
|
|
22
|
+
|
|
23
|
+
- **IDE 模式切换不生效**:状态条目类型 `pi-plan-build:state` → `pi-plan-build-state`,与 pi-acp-jetbrain 桥接层契约对齐;此前 IDE 切模式报 "not installed"、选择器恒显示 build
|
|
24
|
+
- **空计划可通过 `plan_exit` 审批**:`nextPlanPath` 分配即建占位空文件使存在性检查恒真;现校验内容非空
|
|
25
|
+
- **Windows 路径大小写绕过/误拦**:win32 下守卫路径比较大小写不敏感
|
|
26
|
+
- **`acknowledge` 语义**:指认用户声明的已完成步不再要求先 `start`(新转移 `exec.step.ack`,ready/active 皆可)
|
|
27
|
+
- **`revise` 先改文件后校验**:改为先过状态机校验再同步计划文件;文件无对应标记时如实回报未同步
|
|
28
|
+
- **`plan_task new` 失败留孤儿占位文件**:失败路径回收空占位
|
|
29
|
+
- **损坏状态判定过宽**:仅"最新"状态条目损坏才进入只读保护,更早坏条目之后有合法状态则正常恢复
|
|
30
|
+
- **`defaultMode` 漏 `/new`**:`startup` 与 `new` 会话都应用默认模式;resume/fork/reload 尊重恢复出的状态
|
|
31
|
+
|
|
32
|
+
### 变更
|
|
33
|
+
|
|
34
|
+
- 显示名统一为首字母大写 `Plan` / `Build`(状态栏徽标 `📋 Plan` / `🔨 Build` 与 IDE 选择器一致);ID/协议层保持小写(`mode: "plan"`、`/plan`、ACP modeId)
|
|
35
|
+
- `FILE_MUTATION_TOOLS` 收敛为 pi 1.3.0 实际存在的 `edit/write`,移除不存在的 `replace/insert/undo_last_change`
|
|
36
|
+
|
|
37
|
+
### 文档
|
|
38
|
+
|
|
39
|
+
- README:命令表补充 `/plan` `/build` 及 IDE 依赖说明;权限边界更新为原生 + IDE 双通道语义
|
|
40
|
+
|
|
41
|
+
## [0.0.1] - 2026-10-16
|
|
42
|
+
|
|
43
|
+
npm 首发(`pi install npm:@wbline/pi-plan-build`)。针对 pi 1.3.0 的 v2 重写。
|
|
44
|
+
|
|
45
|
+
### 新增
|
|
46
|
+
|
|
47
|
+
- Plan/Build 双模式:只读规划 → 显式审批(本会话实现 / 分步实现 / 留在 Plan)→ 分步或整段实现 → 验证闭环
|
|
48
|
+
- 集中状态机:单一不可变 `State` + 唯一 `transition()` 入口,纯函数单测覆盖;状态经 `appendEntry` 持久化、会话恢复
|
|
49
|
+
- 7 个工具全模式常驻(prompt cache 友好,模式合法性由执行时守卫保证):`plan_task` / `plan_exit` / `plan_step_control` / `plan_step_complete` / `plan_complete` / `plan_set_outcome` / `plan_question`
|
|
50
|
+
- 计划文件落当前项目 `.pi/agent/plans/`,语义化命名 `<创建时刻yyyyMMdd-HHmm>-<标题slug>.md`,同名自动递增
|
|
51
|
+
- 交互:唯一命令 `/plan-build` 菜单(TUI 自绘组件 / RPC select 降级)、Alt+M 快捷键切换、底部状态栏模式徽标(📋/🔨)与分步进度 widget
|
|
52
|
+
- 权限守卫:`tool_call` 前拦截,路径归一化(`@`/`~`/相对路径)+ symlink 解析;Plan 只许写计划文件、无路径阻断;Build 保护已写盘计划文件
|
|
53
|
+
- 上下文锚定注入:计划块作为 user 消息插在最后一条真实用户消息之前,位置与内容稳定以命中前缀缓存
|
|
54
|
+
- `awaiting_validation` 结算后自动弹"必需验证是否通过?"确认(once 防重放)
|
|
55
|
+
- 提示词中/英双语(设置 `lang`),设置文件 `~/.pi/agent/pi-plan-build.json`
|
|
56
|
+
|
|
57
|
+
### 设计取舍
|
|
58
|
+
|
|
59
|
+
- 收敛为单一命令 + 交互菜单(不再有 `--pb-plan`/`--pb-build` 启动 flag、Alt+P 快捷键)
|
|
60
|
+
- 原生 UI(`setStatus`/`setWidget`/`ui.custom`),不接管 composer,与其它扩展零冲突
|
|
61
|
+
- 砍掉跨会话干净交接:换会话重新规划,计划文件本身可复用
|
|
62
|
+
- bash/powershell 不做命令分类沙箱,只读边界由提示词约束(诚实标注)
|
package/README.md
CHANGED
|
@@ -15,10 +15,11 @@ pi install npm:@wbline/pi-plan-build
|
|
|
15
15
|
|
|
16
16
|
| 命令 / 快捷键 | 说明 |
|
|
17
17
|
|---------------|--------------------------------------------------------------------------------------------------------------|
|
|
18
|
-
| `/plan-build` |
|
|
18
|
+
| `/plan-build` | 交互菜单:切换模式 / 查看状态 / 标记完成 / 放弃计划(原因必填,文件保留)/ 语言切换 / 设置文件 |
|
|
19
|
+
| `/plan` `/build` | 直切 Plan/Build 模式;IDE(ACP)桥接层按命令名调用,JetBrains AI 聊天的模式选择器依赖这两个命令 |
|
|
19
20
|
| `Alt+M` | 直接切换模式;默认模式由设置 `defaultMode` 决定 |
|
|
20
21
|
|
|
21
|
-
模式徽标(`📋
|
|
22
|
+
模式徽标(`📋 Plan` / `🔨 Build` + 计划标题与进度)显示在**底部状态栏**:Plan 为警告色、Build 为强调色。分步执行时步骤列表 widget 同步显示。
|
|
22
23
|
|
|
23
24
|
设置文件 `~/.pi/agent/pi-plan-build.json`:`{ "lang": "zh", "defaultMode": "build", "protectPlanFile": true }`。
|
|
24
25
|
|
|
@@ -30,7 +31,7 @@ pi install npm:@wbline/pi-plan-build
|
|
|
30
31
|
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
31
32
|
| `plan_task` | 任务生命周期:`new` 建计划(Plan 模式)、`include` 追加用户批准的范围、`update` 改名、`exclude` 记录排除、`abandon`、`list/show`。所有转移必须带 `expectedAttached`(当前 seq)做乐观并发,过期即拒 |
|
|
32
33
|
| `plan_exit` | **Plan 模式终点**。要求计划文件已写盘,然后弹出审批:本会话实现 / 分步实现 / 留在 Plan |
|
|
33
|
-
| `plan_step_control` | 分步执行:`start` 批准就绪步、`acknowledge`
|
|
34
|
+
| `plan_step_control` | 分步执行:`start` 批准就绪步、`acknowledge` 指认用户声明的已完成步(无需先 start)、`skip`、`revise` 修订未完成步(同步改文件)、`pause/resume`、`cancel`。一次只许一个转移 |
|
|
34
35
|
| `plan_step_complete` | 完成当前进行中的步(摘要必填),立即生效不等待验收;最后一步完成即自动收尾整计划 |
|
|
35
36
|
| `plan_complete` | 标记整计划完成——仅在全部工作与必需检查通过,或用户明确指示时 |
|
|
36
37
|
| `plan_set_outcome` | 记录未完成结局并保持计划开放:`awaiting_validation`(必填精确的 userAction)/ `blocked` / `waiting_for_input` / `still_working` |
|
|
@@ -53,10 +54,11 @@ pi install npm:@wbline/pi-plan-build
|
|
|
53
54
|
|
|
54
55
|
守卫在 `tool_call` 前拦截,路径先归一化(`@` 前缀、`~`、相对路径)再做 symlink 解析,不存在的文件解析最远存在父目录:
|
|
55
56
|
|
|
56
|
-
- **Plan
|
|
57
|
-
|
|
57
|
+
- **Plan 模式**:文件变更通道(原生 `edit/write` 与 IDE 通道
|
|
58
|
+
`ide_webstorm_apply_patch / create_new_file / reformat_file`)只许目标为当前计划文件;
|
|
59
|
+
**无路径或波及面无法验证(如语义重命名)的调用一律阻断**——宁可误拦不可放行
|
|
58
60
|
- **Build 模式**:已写盘的计划文件受保护(`protectPlanFile: false` 可关);修订计划请回 Plan 模式
|
|
59
|
-
- **bash/powershell
|
|
61
|
+
- **bash/powershell/终端命令不做分类沙箱**:Plan 模式的只读对 shell 是提示词约束而非硬拦截——与 pi 现有能力一致,诚实标注而非冒充沙箱
|
|
60
62
|
- 扩展自身对计划文件的修订(步骤 revise)走同一文件队列,绕过守卫但不绕过记录
|
|
61
63
|
|
|
62
64
|
## 设计取舍
|
|
@@ -82,6 +84,8 @@ npm test # 18 个纯函数单测:状态机 / 步骤解析 / 路径守
|
|
|
82
84
|
npm run smoke # 装配冒烟:stub ExtensionAPI 走完整流程(注册、守卫、菜单、注入)
|
|
83
85
|
```
|
|
84
86
|
|
|
87
|
+
历史更新见 [CHANGELOG.md](CHANGELOG.md)(Keep a Changelog 格式,随版本发布维护)。
|
|
88
|
+
|
|
85
89
|
## License
|
|
86
90
|
|
|
87
91
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wbline/pi-plan-build",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.2",
|
|
4
4
|
"description": "Plan/Build dual-mode for the Pi coding agent: read-only planning, explicit approval, step-wise execution.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "wongbin",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"files": [
|
|
26
26
|
"src",
|
|
27
27
|
"README.md",
|
|
28
|
+
"CHANGELOG.md",
|
|
28
29
|
"LICENSE"
|
|
29
30
|
],
|
|
30
31
|
"scripts": {
|
package/src/core/guard.ts
CHANGED
|
@@ -2,21 +2,27 @@
|
|
|
2
2
|
* 权限守卫(路径判定纯函数 + tool_call 接线放 lifecycle)。
|
|
3
3
|
*
|
|
4
4
|
* 语义沿用参考项目的边界,收敛为可测纯函数:
|
|
5
|
-
* - Plan
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* - Plan 模式:文件变更通道(原生 edit/write 与 IDE 的
|
|
6
|
+
* apply_patch/create_new_file/reformat_file)只许写当前计划文件;
|
|
7
|
+
* 无法验证目标(如语义重命名)一律阻断——宁可误拦不可放行。
|
|
8
|
+
* - Build 模式:保护计划文件不被改写(修订请回 Plan 模式)。
|
|
9
|
+
* - bash/powershell/终端命令不做硬沙箱(Plan 的只读由提示词约束,
|
|
10
|
+
* 这里不做任意命令分类——诚实标注而非冒充沙箱)。
|
|
8
11
|
*/
|
|
9
12
|
|
|
10
13
|
import fs from "node:fs";
|
|
11
14
|
import os from "node:os";
|
|
12
15
|
import path from "node:path";
|
|
13
16
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
"
|
|
17
|
+
/** 原生文件编辑工具(pi 1.3.0 实际存在的变更类工具)。 */
|
|
18
|
+
export const FILE_MUTATION_TOOLS = new Set(["edit", "write"]);
|
|
19
|
+
|
|
20
|
+
/** IDE(IntelliJ-first/ACP)会话的正规文件变更通道,Plan 守卫同等拦截。 */
|
|
21
|
+
export const IDE_MUTATION_TOOLS = new Set([
|
|
22
|
+
"ide_webstorm_apply_patch",
|
|
23
|
+
"ide_webstorm_create_new_file",
|
|
24
|
+
"ide_webstorm_reformat_file",
|
|
25
|
+
"ide_webstorm_rename_refactoring",
|
|
20
26
|
]);
|
|
21
27
|
|
|
22
28
|
/** 归一化模型给的路径:@ 前缀、~、相对路径 → 绝对路径。 */
|
|
@@ -28,31 +34,105 @@ export function normalizePath(raw: string, cwd: string): string {
|
|
|
28
34
|
return path.normalize(p);
|
|
29
35
|
}
|
|
30
36
|
|
|
37
|
+
/** Windows 路径大小写不敏感(盘符/目录大小写差异不构成绕过或误拦)。 */
|
|
38
|
+
function normCase(p: string): string {
|
|
39
|
+
return process.platform === "win32" ? p.toLowerCase() : p;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* 从工具输入提取写入目标的绝对路径列表。
|
|
44
|
+
* 返回 undefined = 该工具的波及面无法验证(如语义重命名);
|
|
45
|
+
* 空数组 = 看不到任何路径(按无路径处理)。
|
|
46
|
+
*/
|
|
47
|
+
export function extractMutationTargets(
|
|
48
|
+
toolName: string,
|
|
49
|
+
input: unknown,
|
|
50
|
+
cwd: string,
|
|
51
|
+
): string[] | undefined {
|
|
52
|
+
const inp = (input ?? {}) as Record<string, unknown>;
|
|
53
|
+
const one = (v: unknown): string[] =>
|
|
54
|
+
typeof v === "string" && v.trim() ? [normalizePath(v, cwd)] : [];
|
|
55
|
+
switch (toolName) {
|
|
56
|
+
case "edit":
|
|
57
|
+
case "write":
|
|
58
|
+
return one(inp.path);
|
|
59
|
+
case "ide_webstorm_create_new_file":
|
|
60
|
+
return one(inp.pathInProject);
|
|
61
|
+
case "ide_webstorm_reformat_file": {
|
|
62
|
+
const files = inp.files;
|
|
63
|
+
if (!Array.isArray(files)) return [];
|
|
64
|
+
return files
|
|
65
|
+
.filter((f): f is string => typeof f === "string" && f.trim() !== "")
|
|
66
|
+
.map((f) => normalizePath(f, cwd));
|
|
67
|
+
}
|
|
68
|
+
case "ide_webstorm_apply_patch": {
|
|
69
|
+
const text =
|
|
70
|
+
typeof inp.input === "string"
|
|
71
|
+
? inp.input
|
|
72
|
+
: typeof inp.patch === "string"
|
|
73
|
+
? inp.patch
|
|
74
|
+
: "";
|
|
75
|
+
if (!text.trim()) return [];
|
|
76
|
+
const targets = new Set<string>();
|
|
77
|
+
// codex apply_patch 格式:*** Update/Add/Delete File: <path>(*** Move to: 为重命名目标)
|
|
78
|
+
for (const m of text.matchAll(
|
|
79
|
+
/^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm,
|
|
80
|
+
))
|
|
81
|
+
targets.add(m[1].trim());
|
|
82
|
+
for (const m of text.matchAll(/^\*\*\* Move to: (.+)$/gm))
|
|
83
|
+
targets.add(m[1].trim());
|
|
84
|
+
// unified diff:+++ b/<path>
|
|
85
|
+
for (const m of text.matchAll(/^\+\+\+\s+(?:b\/)?(.+?)(?:\t.*)?\s*$/gm))
|
|
86
|
+
targets.add(m[1].trim());
|
|
87
|
+
return [...targets].map((p) => normalizePath(p, cwd));
|
|
88
|
+
}
|
|
89
|
+
case "ide_webstorm_rename_refactoring":
|
|
90
|
+
return undefined; // 语义重命名波及全部引用处,无法验证
|
|
91
|
+
default:
|
|
92
|
+
return undefined;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
31
96
|
export type GuardDecision =
|
|
32
97
|
| { action: "allow" }
|
|
33
98
|
| { action: "block"; reason: string };
|
|
34
99
|
|
|
35
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* 变更裁决。targets 为 extractMutationTargets 的结果:
|
|
102
|
+
* - Plan 模式:全部目标都必须是当前计划文件;undefined/空 一律阻断。
|
|
103
|
+
* - Build 模式:已写盘的计划文件受保护;无法验证的目标放行(沿用原语义)。
|
|
104
|
+
*/
|
|
36
105
|
export function decideFileMutation(
|
|
37
106
|
toolName: string,
|
|
38
107
|
mode: "plan" | "build",
|
|
39
108
|
planPath: string | null,
|
|
40
109
|
planSaved: boolean,
|
|
41
|
-
|
|
110
|
+
targets: string[] | undefined,
|
|
42
111
|
): GuardDecision {
|
|
43
|
-
if (!FILE_MUTATION_TOOLS.has(toolName)
|
|
44
|
-
|
|
112
|
+
if (!FILE_MUTATION_TOOLS.has(toolName) && !IDE_MUTATION_TOOLS.has(toolName))
|
|
113
|
+
return { action: "allow" };
|
|
114
|
+
const plan = planPath
|
|
115
|
+
? normCase(normalizePath(planPath, process.cwd()))
|
|
116
|
+
: null;
|
|
45
117
|
|
|
46
|
-
if (
|
|
118
|
+
if (targets === undefined) {
|
|
119
|
+
return mode === "plan"
|
|
120
|
+
? {
|
|
121
|
+
action: "block",
|
|
122
|
+
reason: `Plan 模式只读:${toolName} 的写入波及面无法验证,被阻断。如需修改项目文件,请先通过 plan_exit 审批切换到 Build 模式。`,
|
|
123
|
+
}
|
|
124
|
+
: { action: "allow" };
|
|
125
|
+
}
|
|
126
|
+
if (targets.length === 0) {
|
|
47
127
|
return {
|
|
48
128
|
action: "block",
|
|
49
|
-
reason: `${toolName}
|
|
129
|
+
reason: `${toolName} 调用没有可见的文件路径,无法验证写入目标。请使用带路径参数的编辑工具,明确指向目标文件。`,
|
|
50
130
|
};
|
|
51
131
|
}
|
|
52
|
-
const
|
|
132
|
+
const ts = targets.map((t) => normCase(normalizePath(t, process.cwd())));
|
|
53
133
|
|
|
54
134
|
if (mode === "plan") {
|
|
55
|
-
if (plan && t === plan) return { action: "allow" };
|
|
135
|
+
if (plan && ts.every((t) => t === plan)) return { action: "allow" };
|
|
56
136
|
return {
|
|
57
137
|
action: "block",
|
|
58
138
|
reason: planPath
|
|
@@ -62,7 +142,7 @@ export function decideFileMutation(
|
|
|
62
142
|
}
|
|
63
143
|
|
|
64
144
|
// build 模式:保护计划文件
|
|
65
|
-
if (plan && t === plan
|
|
145
|
+
if (plan && planSaved && ts.some((t) => t === plan)) {
|
|
66
146
|
return {
|
|
67
147
|
action: "block",
|
|
68
148
|
reason:
|
package/src/core/schema.ts
CHANGED
|
@@ -13,7 +13,11 @@ import {
|
|
|
13
13
|
type StepStatus,
|
|
14
14
|
} from "./state.ts";
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
/**
|
|
17
|
+
* 会话条目类型。与 pi-acp-jetbrain 桥接层约定一致:
|
|
18
|
+
* ACP 模式选择器按此 customType 读 data.selectedMode 展示当前 Plan/Build 模式。
|
|
19
|
+
*/
|
|
20
|
+
export const STATE_ENTRY_TYPE = "pi-plan-build-state";
|
|
17
21
|
|
|
18
22
|
const stepStatusValues = [
|
|
19
23
|
"pending",
|
package/src/core/state.ts
CHANGED
|
@@ -76,6 +76,7 @@ export type Transition =
|
|
|
76
76
|
| { t: "exec.start"; steps: string[] }
|
|
77
77
|
| { t: "exec.step.start" }
|
|
78
78
|
| { t: "exec.step.complete"; summary?: string }
|
|
79
|
+
| { t: "exec.step.ack"; summary?: string }
|
|
79
80
|
| { t: "exec.step.skip" }
|
|
80
81
|
| { t: "exec.step.revise"; n: number; text: string }
|
|
81
82
|
| { t: "exec.pause" }
|
|
@@ -122,6 +123,31 @@ function nextPending(steps: Step[]): Step | undefined {
|
|
|
122
123
|
return steps.find((x) => x.status === "pending");
|
|
123
124
|
}
|
|
124
125
|
|
|
126
|
+
/** 完成当前步并推进 ready;最后一步完成时整体收尾(complete/ack 共用)。 */
|
|
127
|
+
function finishStep(
|
|
128
|
+
s: State,
|
|
129
|
+
ex: Execution,
|
|
130
|
+
cur: Step,
|
|
131
|
+
summary?: string,
|
|
132
|
+
): TransitionResult {
|
|
133
|
+
cur.status = "completed";
|
|
134
|
+
cur.summary = summary;
|
|
135
|
+
const next = nextPending(ex.steps);
|
|
136
|
+
if (next) {
|
|
137
|
+
next.status = "ready";
|
|
138
|
+
return {
|
|
139
|
+
state: s,
|
|
140
|
+
note: `第 ${cur.n} 步完成;第 ${next.n} 步就绪(等待批准)`,
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
const done = ex.steps
|
|
144
|
+
.map((x) => ` ${x.n}. ${x.summary ?? x.text}`)
|
|
145
|
+
.join("\n");
|
|
146
|
+
s.execution = null;
|
|
147
|
+
s.plan = null;
|
|
148
|
+
return { state: s, note: `全部步骤完成,计划已收尾。\n${done}` };
|
|
149
|
+
}
|
|
150
|
+
|
|
125
151
|
/** 唯一转移入口。 */
|
|
126
152
|
export function transition(prev: State, ev: Transition): TransitionResult {
|
|
127
153
|
const s = clone(prev);
|
|
@@ -245,23 +271,19 @@ export function transition(prev: State, ev: Transition): TransitionResult {
|
|
|
245
271
|
throw new TransitionError(
|
|
246
272
|
"没有进行中的步骤。先 plan_step_control start。",
|
|
247
273
|
);
|
|
248
|
-
cur.
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
.join("\n");
|
|
262
|
-
s.execution = null;
|
|
263
|
-
s.plan = null;
|
|
264
|
-
return { state: s, note: `全部步骤完成,计划已收尾。\n${done}` };
|
|
274
|
+
return finishStep(s, ex, cur, ev.summary);
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
case "exec.step.ack": {
|
|
278
|
+
// 指认用户声明的已完成步:当前步(ready/active)直接记录,不要求先 start
|
|
279
|
+
const ex = requireExecution(s);
|
|
280
|
+
if (ex.paused)
|
|
281
|
+
throw new TransitionError("执行已暂停,先 plan_step_control resume。");
|
|
282
|
+
const cur = ex.steps.find(
|
|
283
|
+
(x) => x.status === "ready" || x.status === "active",
|
|
284
|
+
);
|
|
285
|
+
if (!cur) throw new TransitionError("没有可指认的步骤。");
|
|
286
|
+
return finishStep(s, ex, cur, ev.summary);
|
|
265
287
|
}
|
|
266
288
|
|
|
267
289
|
case "exec.step.skip": {
|
|
@@ -336,7 +358,7 @@ export function currentSeq(s: State): number | null {
|
|
|
336
358
|
|
|
337
359
|
/** 人类可读的一行状态(状态栏用)。 */
|
|
338
360
|
export function statusLine(s: State): string {
|
|
339
|
-
const mode = s.mode === "plan" ? "📋
|
|
361
|
+
const mode = s.mode === "plan" ? "📋 Plan" : "🔨 Build";
|
|
340
362
|
if (!s.plan) return mode;
|
|
341
363
|
if (s.execution) {
|
|
342
364
|
const done = s.execution.steps.filter(
|
package/src/engine.ts
CHANGED
|
@@ -55,18 +55,26 @@ export class PlanEngine {
|
|
|
55
55
|
restored: boolean;
|
|
56
56
|
corruptEntry?: boolean;
|
|
57
57
|
} {
|
|
58
|
-
|
|
58
|
+
// 仅"最新"状态条目损坏才视为损坏:更早的坏条目之后若有合法状态,不进入只读保护
|
|
59
59
|
let restoredState: State | undefined;
|
|
60
|
+
let corruptAfterLatest = false;
|
|
60
61
|
for (const entry of entries) {
|
|
61
|
-
if (entry.customType
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
62
|
+
if (entry.customType !== STATE_ENTRY_TYPE || entry.data === undefined)
|
|
63
|
+
continue;
|
|
64
|
+
const decoded = decodeState(entry.data);
|
|
65
|
+
if (decoded) {
|
|
66
|
+
restoredState = decoded;
|
|
67
|
+
corruptAfterLatest = false;
|
|
68
|
+
} else {
|
|
69
|
+
corruptAfterLatest = true;
|
|
65
70
|
}
|
|
66
71
|
}
|
|
67
72
|
this.state = restoredState ?? initialState;
|
|
68
73
|
this.corrupt = false;
|
|
69
|
-
return {
|
|
74
|
+
return {
|
|
75
|
+
restored: restoredState !== undefined,
|
|
76
|
+
corruptEntry: corruptAfterLatest,
|
|
77
|
+
};
|
|
70
78
|
}
|
|
71
79
|
|
|
72
80
|
apply(ev: Transition, ctx?: ExtensionContext): TransitionResult {
|
|
@@ -96,7 +104,12 @@ export class PlanEngine {
|
|
|
96
104
|
}
|
|
97
105
|
|
|
98
106
|
private persist(): void {
|
|
99
|
-
|
|
107
|
+
// 桥接契约:pi-acp-jetbrain 读 data.selectedMode 判断当前模式;
|
|
108
|
+
// decodeState 只挑已知字段,附加键不影响恢复。
|
|
109
|
+
this.pi.appendEntry(STATE_ENTRY_TYPE, {
|
|
110
|
+
...this.state,
|
|
111
|
+
selectedMode: this.state.mode,
|
|
112
|
+
});
|
|
100
113
|
}
|
|
101
114
|
|
|
102
115
|
refreshUI(ctx?: ExtensionContext, note?: string): void {
|
package/src/index.ts
CHANGED
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
* 设计原则:分层模块 + 集中状态机 + 原生 UI(setStatus/setWidget/custom),
|
|
5
5
|
* 不接管 composer/editor,与其它扩展零冲突。详见 README.md。
|
|
6
6
|
*
|
|
7
|
-
*
|
|
7
|
+
* 命令:/plan-build 交互菜单(切换模式/状态/完成/放弃/语言/设置);
|
|
8
|
+
* /plan、/build 直切模式(IDE/ACP 桥接层约定按命令名调用)。
|
|
8
9
|
* 快捷键:Alt+M 切换模式
|
|
9
10
|
*/
|
|
10
11
|
|
|
@@ -16,7 +17,7 @@ import type {
|
|
|
16
17
|
} from "@earendil-works/pi-coding-agent";
|
|
17
18
|
import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
|
|
18
19
|
import { configPath, loadConfig, saveConfig } from "./config.ts";
|
|
19
|
-
import { type State, statusLine } from "./core/state.ts";
|
|
20
|
+
import { type Mode, type State, statusLine } from "./core/state.ts";
|
|
20
21
|
import { PlanEngine } from "./engine.ts";
|
|
21
22
|
import { wireLifecycle } from "./lifecycle.ts";
|
|
22
23
|
import { registerAllTools } from "./tools/index.ts";
|
|
@@ -33,6 +34,20 @@ export default function planBuild(pi: ExtensionAPI): void {
|
|
|
33
34
|
},
|
|
34
35
|
});
|
|
35
36
|
|
|
37
|
+
// --- 直切命令:pi-acp-jetbrain 桥接层 setSessionMode 按名字查找并发送 /plan 或 /build ---
|
|
38
|
+
const setMode = async (mode: Mode, ctx: ExtensionContext): Promise<void> => {
|
|
39
|
+
const r = engine.tryApply({ t: "mode.set", mode }, ctx);
|
|
40
|
+
if ("error" in r) ctx.ui.notify(r.error, "error");
|
|
41
|
+
};
|
|
42
|
+
pi.registerCommand("plan", {
|
|
43
|
+
description: "切换到 Plan 模式(只读规划)",
|
|
44
|
+
handler: (_args, ctx) => setMode("plan", ctx),
|
|
45
|
+
});
|
|
46
|
+
pi.registerCommand("build", {
|
|
47
|
+
description: "切换到 Build 模式",
|
|
48
|
+
handler: (_args, ctx) => setMode("build", ctx),
|
|
49
|
+
});
|
|
50
|
+
|
|
36
51
|
// --- 工具与生命周期 ---
|
|
37
52
|
registerAllTools(pi, engine);
|
|
38
53
|
wireLifecycle(pi, engine);
|
|
@@ -49,7 +64,9 @@ export default function planBuild(pi: ExtensionAPI): void {
|
|
|
49
64
|
|
|
50
65
|
// --- 启动模式应用(在首个 session_start 时)---
|
|
51
66
|
pi.on("session_start", (event, ctx) => {
|
|
52
|
-
|
|
67
|
+
// startup(进程启动)与 new(/new 新会话)都是全新状态,应用默认模式;
|
|
68
|
+
// resume/fork/reload 尊重恢复出的状态
|
|
69
|
+
if (event.reason !== "startup" && event.reason !== "new") return;
|
|
53
70
|
const mode =
|
|
54
71
|
engine.state.mode === "plan" ? "plan" : loaded.config.defaultMode;
|
|
55
72
|
if (mode !== engine.state.mode) engine.apply({ t: "mode.set", mode }, ctx);
|
package/src/lifecycle.ts
CHANGED
|
@@ -6,8 +6,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
|
6
6
|
import { buildContextBlock, injectContext } from "./context.ts";
|
|
7
7
|
import {
|
|
8
8
|
decideFileMutation,
|
|
9
|
+
extractMutationTargets,
|
|
9
10
|
FILE_MUTATION_TOOLS,
|
|
10
|
-
|
|
11
|
+
IDE_MUTATION_TOOLS,
|
|
11
12
|
realpathLike,
|
|
12
13
|
} from "./core/guard.ts";
|
|
13
14
|
import type { PlanEngine } from "./engine.ts";
|
|
@@ -35,21 +36,24 @@ export function wireLifecycle(pi: ExtensionAPI, engine: PlanEngine): void {
|
|
|
35
36
|
|
|
36
37
|
// --- 权限守卫(tool_call 可拦截)---
|
|
37
38
|
pi.on("tool_call", (event, ctx) => {
|
|
38
|
-
if (!FILE_MUTATION_TOOLS.has(event.toolName)) return;
|
|
39
39
|
const s = engine.state;
|
|
40
|
+
const guarded =
|
|
41
|
+
FILE_MUTATION_TOOLS.has(event.toolName) ||
|
|
42
|
+
IDE_MUTATION_TOOLS.has(event.toolName);
|
|
43
|
+
if (!guarded) return;
|
|
40
44
|
if (s.mode === "build" && !engine.config.protectPlanFile) return; // 用户关闭保护
|
|
41
45
|
const planPath = s.plan?.path ? realpathLike(s.plan.path) : null;
|
|
42
|
-
const
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
46
|
+
const targets = extractMutationTargets(
|
|
47
|
+
event.toolName,
|
|
48
|
+
event.input,
|
|
49
|
+
ctx.cwd,
|
|
50
|
+
);
|
|
47
51
|
const decision = decideFileMutation(
|
|
48
52
|
event.toolName,
|
|
49
53
|
s.mode,
|
|
50
54
|
planPath,
|
|
51
55
|
s.plan?.saved ?? false,
|
|
52
|
-
|
|
56
|
+
targets,
|
|
53
57
|
);
|
|
54
58
|
if (decision.action === "block")
|
|
55
59
|
return { block: true, reason: decision.reason };
|
package/src/tools/plan-exit.ts
CHANGED
|
@@ -33,9 +33,14 @@ export function registerPlanExit(pi: ExtensionAPI, engine: PlanEngine): void {
|
|
|
33
33
|
`计划文件尚未写盘:${plan.path}。请先把完整计划写入该文件(用 write 工具),成功后调用 plan_exit。`,
|
|
34
34
|
);
|
|
35
35
|
}
|
|
36
|
-
if (!plan.saved) engine.apply({ t: "plan.saved" }, ctx);
|
|
37
|
-
|
|
38
36
|
const markdown = fs.readFileSync(plan.path, "utf8");
|
|
37
|
+
if (!markdown.trim()) {
|
|
38
|
+
// nextPlanPath 分配即建占位空文件,存在性检查恒真——必须校验内容非空
|
|
39
|
+
return fail(
|
|
40
|
+
`计划文件还是空的:${plan.path}。请先写入完整计划(含 ## 验证 小节与文末 "## 实现步骤" 编号列表),成功后再调用 plan_exit。`,
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
if (!plan.saved) engine.apply({ t: "plan.saved" }, ctx);
|
|
39
44
|
const parsed = parseSteps(markdown);
|
|
40
45
|
|
|
41
46
|
// 审阅渲染:把计划全文作为工具结果回显,模型轮结束后用户在对话里看到(无自定义 entry,减少 UI 接管)。
|
package/src/tools/plan-steps.ts
CHANGED
|
@@ -44,7 +44,7 @@ export function registerPlanStepTools(
|
|
|
44
44
|
name: "plan_step_control",
|
|
45
45
|
label: "Plan Step Control",
|
|
46
46
|
description:
|
|
47
|
-
"分步执行控制:start 批准并开始就绪步;acknowledge
|
|
47
|
+
"分步执行控制:start 批准并开始就绪步;acknowledge 指认用户声明的已完成步(当前步无需先 start;记录既有事实,不授权新工作,AI 自己完成当前步用 plan_step_complete);skip 跳过;revise 修订未完成步文本;pause/resume 暂停恢复;cancel 取消分步执行(计划保留)。一次一个转移。",
|
|
48
48
|
parameters: ControlParams,
|
|
49
49
|
async execute(_id, params, _signal, _onUpdate, ctx: ExtensionToolContext) {
|
|
50
50
|
switch (params.action) {
|
|
@@ -62,7 +62,7 @@ export function registerPlanStepTools(
|
|
|
62
62
|
}
|
|
63
63
|
case "acknowledge": {
|
|
64
64
|
const r = engine.tryApply(
|
|
65
|
-
{ t: "exec.step.
|
|
65
|
+
{ t: "exec.step.ack", summary: params.summary },
|
|
66
66
|
ctx,
|
|
67
67
|
);
|
|
68
68
|
if ("error" in r) return err(r.error);
|
|
@@ -81,20 +81,22 @@ export function registerPlanStepTools(
|
|
|
81
81
|
params.step ?? execution.steps.find((x) => x.status === "ready")?.n;
|
|
82
82
|
if (!n || !params.text)
|
|
83
83
|
return err("revise 需要 step(步骤号)和 text(新文本)。");
|
|
84
|
-
|
|
85
|
-
if (!st) return err(`不存在第 ${n} 步。`);
|
|
86
|
-
// 同步修订计划文件中的步骤文本(受保护文件的扩展自身修订,绕过守卫:直接写)
|
|
87
|
-
const planPath = s.plan?.path;
|
|
88
|
-
if (planPath && fs.existsSync(planPath)) {
|
|
89
|
-
const md = fs.readFileSync(planPath, "utf8");
|
|
90
|
-
const revised = reviseStepInMarkdown(md, n, params.text);
|
|
91
|
-
if (revised !== null) fs.writeFileSync(planPath, revised);
|
|
92
|
-
}
|
|
84
|
+
// 先过状态机校验(不存在/已完成/进行中的步骤会被拒绝),成功后再同步计划文件
|
|
93
85
|
const r = engine.tryApply(
|
|
94
86
|
{ t: "exec.step.revise", n, text: params.text },
|
|
95
87
|
ctx,
|
|
96
88
|
);
|
|
97
89
|
if ("error" in r) return err(r.error);
|
|
90
|
+
const savedPath = r.state.plan?.path;
|
|
91
|
+
if (savedPath && fs.existsSync(savedPath)) {
|
|
92
|
+
const md = fs.readFileSync(savedPath, "utf8");
|
|
93
|
+
const revised = reviseStepInMarkdown(md, n, params.text);
|
|
94
|
+
if (revised !== null) fs.writeFileSync(savedPath, revised);
|
|
95
|
+
else
|
|
96
|
+
return ok(
|
|
97
|
+
`第 ${n} 步已修订(状态);计划文件中未找到对应步骤标记,文件未同步。`,
|
|
98
|
+
);
|
|
99
|
+
}
|
|
98
100
|
return ok(`第 ${n} 步已修订:${params.text}`);
|
|
99
101
|
}
|
|
100
102
|
case "pause": {
|
package/src/tools/plan-task.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/** plan_task:任务生命周期元数据(new/title/include/exclude/abandon/list/show)。 */
|
|
2
2
|
|
|
3
|
+
import fs from "node:fs";
|
|
3
4
|
import { StringEnum } from "@earendil-works/pi-ai";
|
|
4
5
|
import type {
|
|
5
6
|
ExtensionAPI,
|
|
@@ -87,7 +88,15 @@ export function registerPlanTask(pi: ExtensionAPI, engine: PlanEngine): void {
|
|
|
87
88
|
},
|
|
88
89
|
ctx,
|
|
89
90
|
);
|
|
90
|
-
if ("error" in r)
|
|
91
|
+
if ("error" in r) {
|
|
92
|
+
// 占位文件已分配但计划未建(如已有未完成计划):回收空占位,不留孤儿文件
|
|
93
|
+
try {
|
|
94
|
+
if (fs.statSync(p).size === 0) fs.unlinkSync(p);
|
|
95
|
+
} catch {
|
|
96
|
+
// 回收失败不掩盖主错误
|
|
97
|
+
}
|
|
98
|
+
return err(r.error);
|
|
99
|
+
}
|
|
91
100
|
return text(
|
|
92
101
|
`计划已创建(seq=1)。canonical 路径:${p}\n请完成只读调研后把完整计划写入该文件,然后调用 plan_exit。`,
|
|
93
102
|
);
|