@wbline/pi-plan-build 0.0.3 → 0.0.4
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 +6 -0
- package/README.md +70 -51
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@
|
|
|
4
4
|
|
|
5
5
|
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本遵循语义化版本。
|
|
6
6
|
|
|
7
|
+
## [0.0.4] - 2026-10-16
|
|
8
|
+
|
|
9
|
+
### 文档
|
|
10
|
+
|
|
11
|
+
- README 面向 [pi.dev/packages](https://pi.dev/packages) 画廊首页重写:一句话价值主张 + plan→审批→build 全流程图、"它解决什么问题"对照表、核心机制速览、设置表格化,技术细节(工具表/权限边界/设计取舍)完整保留后置。无代码变更
|
|
12
|
+
|
|
7
13
|
## [0.0.3] - 2026-10-16
|
|
8
14
|
|
|
9
15
|
借鉴 pi-plan-build 参考项目的两道硬机制(时序闸、事后对账),并对双模式链路做四轮深入排查(模式转移、守卫、对账、持久化、提示词、工具契约、测试卫生)。
|
package/README.md
CHANGED
|
@@ -1,82 +1,101 @@
|
|
|
1
1
|
# pi-plan-build
|
|
2
2
|
|
|
3
|
-
[Pi coding agent](https://github.com/earendil-works/pi-mono)
|
|
4
|
-
分步/整段实现 → 验证闭环**,针对 pi 1.3.0 重新设计。
|
|
3
|
+
> 让 agent 先规划、经你审批、再动手。为 [Pi coding agent](https://github.com/earendil-works/pi-mono) 设计的 plan/build 双模式工作流扩展。
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
**只读规划 → 显式审批 → 分步/整段实现 → 验证闭环。** 规划期间 agent 改不了你的项目;审批之前没有实现;每一步的完成与验证都有据可查。
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
```text
|
|
8
|
+
plan 模式(只读) 审批(三选一) build 模式
|
|
9
|
+
调研讨论 → 写计划文件 ──▶ plan_exit ──▶ 本会话 / 分步 / 留在 plan ──▶ 实现 → 验证 → plan_complete
|
|
10
|
+
▲ 守卫:只许写计划文件 ▲ 守卫:计划文件只读
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## 快速开始
|
|
9
14
|
|
|
10
15
|
```bash
|
|
11
16
|
pi install npm:@wbline/pi-plan-build
|
|
12
17
|
```
|
|
13
18
|
|
|
19
|
+
零配置,装上即用。计划文件自动落在当前项目 `.pi/agent/plans/`(`<创建时刻>-<标题>.md`,随项目走)。30 秒体验完整闭环:
|
|
20
|
+
|
|
21
|
+
1. **Alt+M** 切到 plan 模式:只读调研讨论,agent 的文件写入被守卫拦截
|
|
22
|
+
2. 让 agent 规划:`plan_task new` 建计划 → 写完整计划文件(含验证小节与实现步骤)→ `plan_exit` 提请审批
|
|
23
|
+
3. 你三选一:**本会话实现 / 分步实现 / 留在 plan**——选择之前 agent 劫不了代码
|
|
24
|
+
4. build 模式实现:计划文件受保护;分步模式下每一步都等你点头再开始
|
|
25
|
+
5. 验证闭环:能自动验证的当场跑;只能你验证的(登录、硬件、线上效果)记为 `awaiting_validation`,回合结束后主动弹窗问你
|
|
26
|
+
|
|
27
|
+
## 它解决什么问题
|
|
28
|
+
|
|
29
|
+
| 没有 plan-build | 有了 plan-build |
|
|
30
|
+
|---|---|
|
|
31
|
+
| agent 听完需求直接开改 | 规划期只读,写文件被守卫拦截 |
|
|
32
|
+
| "方案同意了"就等于开写 | 审批是显式的三选一,选择前零改动 |
|
|
33
|
+
| 计划与实现混在一个上下文里 | 双模式状态机,计划随会话持久化、可恢复 |
|
|
34
|
+
| "做完了"全靠 agent 自述 | 验证策略内置,必需的用户验证主动发问 |
|
|
35
|
+
|
|
36
|
+
## 核心机制
|
|
37
|
+
|
|
38
|
+
- 🔒 **双模式权限守卫**:`tool_call` 前拦截,路径归一化(`@`/`~`/相对路径)+ symlink 解析。plan 模式只许写计划文件,无路径或波及面无法验证(未知工具、语义重命名)一律阻断——宁可误拦不可放行
|
|
39
|
+
- 🏷️ **动态工具分类**:不写死工具名单,按配置覆盖 > 注解(`readOnlyHint`)> 名字动词约定分类;新增 IDE 变更工具不再漏拦
|
|
40
|
+
- ⏱️ **时序硬闸**:`plan_task` 生命周期转移未收尾时,依赖它的文件变更与生命周期工具一律先等——把"转移先于依赖动作"从提示词约束升级为硬拦截
|
|
41
|
+
- 📒 **事后对账**:放行波及面无法验证的工具(IDE 终端命令、shell)前记录计划文件基线,回合结束时文件被改动即警告核对
|
|
42
|
+
- 🪜 **分步执行**:计划里的实现步骤逐个就绪,你说"继续"才开工;侧栏实时显示 `○◉◐●↷` 进度
|
|
43
|
+
- ✅ **验证闭环**:`awaiting_validation` 结算后自动确认"必需验证是否通过?",通过才收尾,否则计划保持开放
|
|
44
|
+
- 🌐 **中英双语提示词**:菜单一键切换;7 个工具全模式常驻(稳定工具目录),模式切换不抖动工具列表,prompt cache 持续命中
|
|
45
|
+
|
|
14
46
|
## 命令
|
|
15
47
|
|
|
16
|
-
| 命令 / 快捷键 | 说明
|
|
17
|
-
|
|
48
|
+
| 命令 / 快捷键 | 说明 |
|
|
49
|
+
|---|---|
|
|
18
50
|
| `/plan-build` | 交互菜单:切换模式 / 查看状态 / 标记完成 / 放弃计划(原因必填,文件保留)/ 语言切换 / 设置文件 |
|
|
19
|
-
| `/plan` `/build` |
|
|
20
|
-
| `Alt+M`
|
|
51
|
+
| `/plan` `/build` | 直切模式;IDE(ACP)桥接层按命令名调用,JetBrains AI 聊天的模式选择器依赖这两个命令 |
|
|
52
|
+
| `Alt+M` | 直接切换模式;新会话默认模式由设置 `defaultMode` 决定 |
|
|
21
53
|
|
|
22
|
-
|
|
54
|
+
状态栏徽标(`📋 plan` / `🔨 build` + 计划标题与进度)显示在底部;分步执行时步骤列表 widget 同步显示。
|
|
23
55
|
|
|
24
|
-
|
|
56
|
+
## 工具
|
|
25
57
|
|
|
26
|
-
|
|
58
|
+
| 工具 | 说明 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `plan_task` | 任务生命周期:`new` 建计划(plan 模式)、`include` 追加用户批准的范围、`update` 改名、`exclude` 记录排除、`abandon`、`list/show`。所有转移必须带 `expectedAttached` 做乐观并发(`new` 传 null,其余传当前 seq),不匹配即拒 |
|
|
61
|
+
| `plan_exit` | **plan 模式终点**。要求计划文件已写盘,然后弹出审批:本会话实现 / 分步实现 / 留在 plan |
|
|
62
|
+
| `plan_step_control` | 分步执行:`start` 批准就绪步、`acknowledge` 指认用户声明的已完成步(无需先 start)、`skip`、`revise` 修订未完成步(同步改文件)、`pause/resume`、`cancel`。一次只许一个转移 |
|
|
63
|
+
| `plan_step_complete` | 完成当前进行中的步(摘要必填),立即生效不等待验收;最后一步完成即自动收尾整计划 |
|
|
64
|
+
| `plan_complete` | 标记整计划完成——仅在全部工作与必需检查通过,或用户明确指示时 |
|
|
65
|
+
| `plan_set_outcome` | 记录未完成结局并保持计划开放:`awaiting_validation`(必填精确的 userAction)/ `blocked` / `waiting_for_input` / `still_working` |
|
|
66
|
+
| `plan_question` | 结构化选择题,收集决策;无交互 UI 时自动降级为文本提问 |
|
|
27
67
|
|
|
28
|
-
##
|
|
68
|
+
## 设置
|
|
69
|
+
|
|
70
|
+
`~/.pi/agent/pi-plan-build.json`,全部可省略:
|
|
29
71
|
|
|
30
|
-
|
|
|
31
|
-
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `plan_complete` | 标记整计划完成——仅在全部工作与必需检查通过,或用户明确指示时 |
|
|
37
|
-
| `plan_set_outcome` | 记录未完成结局并保持计划开放:`awaiting_validation`(必填精确的 userAction)/ `blocked` / `waiting_for_input` / `still_working` |
|
|
38
|
-
| `plan_question` | 结构化选择题,收集决策;无交互 UI 时自动降级为文本提问 |
|
|
39
|
-
|
|
40
|
-
7 个工具全模式常驻(稳定工具目录),模式合法性由执行时守卫保证——模型看到的工具列表从不抖动,prompt cache 不因模式切换失效。
|
|
41
|
-
|
|
42
|
-
## 工作流
|
|
43
|
-
|
|
44
|
-
1. `/plan-build` 菜单选"切换模式"(或 Alt+M)进入 plan 模式:只读调研讨论;`edit/write` 只允许写计划文件本身。
|
|
45
|
-
2. 让 agent 规划:`plan_task new` 拿到 canonical 路径 → 写完整计划(含 `## 验证` 小节与文末 `## 实现步骤` 编号列表)→
|
|
46
|
-
`plan_exit`。
|
|
47
|
-
3. 审批三选一。选分步后:步骤 1 就绪 → 你说"继续" → `plan_step_control start` → 只做该步 → `plan_step_complete` →
|
|
48
|
-
下一步等待。侧栏实时显示 `○◉◐●↷` 进度。
|
|
49
|
-
4. 只能由你执行的验证(登录、硬件、线上效果):agent 用 `plan_set_outcome awaiting_validation` 记录精确步骤,本轮回合结束后弹 **"
|
|
50
|
-
必需验证是否通过?"**——确认即收尾,否则计划保持开放等你回报失败详情。
|
|
51
|
-
5. 完成后计划归档;`/plan-build` 菜单"查看状态"随时回看,历史进度在分步摘要里。
|
|
72
|
+
| 字段 | 默认 | 说明 |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| `lang` | `"zh"` | 提示词语言:`"zh"` / `"en"` |
|
|
75
|
+
| `defaultMode` | `"build"` | 新会话默认模式(startup/new 生效;resume 尊重恢复出的状态) |
|
|
76
|
+
| `protectPlanFile` | `true` | build 模式是否保护计划文件(关闭后对账一并停用) |
|
|
77
|
+
| `toolGuard` | — | 工具分类强制覆盖:`{ "readonly": [], "mutating": [] }`,列出的工具名优先级最高 |
|
|
52
78
|
|
|
53
79
|
## 权限边界
|
|
54
80
|
|
|
55
|
-
守卫在 `tool_call`
|
|
81
|
+
守卫在 `tool_call` 前拦截,路径先归一化再做 symlink 解析,不存在的文件解析最远存在父目录:
|
|
56
82
|
|
|
57
|
-
- **plan 模式**:文件变更通道(原生 `edit/write` 与 IDE 桥接工具)只许目标为当前计划文件。IDE
|
|
58
|
-
`toolGuard.readonly / mutating` 覆盖 > 工具注解
|
|
59
|
-
(`readOnlyHint`)> 名字动词约定(`get/search/list/…` 视为只读,未命中的 `ide_*` 保守视为变更通道);**无路径或波及面无法验证(未知变更工具、语义重命名)的调用一律阻断**——宁可误拦不可放行
|
|
83
|
+
- **plan 模式**:文件变更通道(原生 `edit/write` 与 IDE 桥接工具)只许目标为当前计划文件。IDE 工具动态分类不写死名单;**无路径或波及面无法验证(未知变更工具、语义重命名)的调用一律阻断**——宁可误拦不可放行
|
|
60
84
|
- **时序硬闸**:最近一条 assistant 消息里 `plan_task` 结构转移(new/include/update/exclude/abandon)未收尾时,文件变更与生命周期工具一律先等转移收尾(`list/show` 只读动作不拦)
|
|
61
|
-
- **事后对账**:build
|
|
62
|
-
- **模式边界**:`plan_task new` 仅限 plan 模式(build 下创建的计划无法走 plan_exit 审批);分步执行进行中禁止切回 plan 模式(避免"只读 + 实现第 N 步"
|
|
85
|
+
- **事后对账**:build 模式放行波及面无法验证的变更工具前记录计划文件内容基线,结算(agent_settled)时发现文件被改动即警告提示核对;bash/powershell 改写计划文件同样纳入
|
|
86
|
+
- **模式边界**:`plan_task new` 仅限 plan 模式(build 下创建的计划无法走 plan_exit 审批);分步执行进行中禁止切回 plan 模式(避免"只读 + 实现第 N 步"的矛盾注入)
|
|
63
87
|
- **build 模式**:已写盘的计划文件受保护(`protectPlanFile: false` 可关);修订计划请回 plan 模式;未列入的 IDE 变更工具同样过守卫(无法验证目标时放行)
|
|
64
88
|
- **bash/powershell/终端命令不做分类沙箱**:plan 模式的只读对 shell 是提示词约束而非硬拦截——与 pi 现有能力一致,诚实标注而非冒充沙箱
|
|
65
89
|
- 扩展自身对计划文件的修订(步骤 revise)不经 tool_call 守卫(守卫只拦模型调用),但受同一状态机校验并在计划文件上留痕
|
|
66
90
|
|
|
67
91
|
## 设计取舍
|
|
68
92
|
|
|
69
|
-
- **集中状态机而非分散闭包**:全部状态收敛为一个不可变 `State`(mode + plan + execution),唯一 `transition()`
|
|
70
|
-
|
|
71
|
-
-
|
|
72
|
-
|
|
73
|
-
-
|
|
74
|
-
|
|
75
|
-
- **宽容步骤解析**:编号 / checkbox /
|
|
76
|
-
短横线都接受,重复步骤去重;解析失败不报错,而是返回一段模型可执行的修复指引("在文件末尾追加 ##
|
|
77
|
-
实现步骤……")。代价是极端格式(嵌套列表)被忽略——它要求的是平铺的离散步骤
|
|
78
|
-
- **上下文锚定注入**:计划块作为 user 消息插在最后一条真实用户消息之前,文本不含时间戳等易变因素——块位置与内容稳定,前缀缓存持续命中;锚点被压缩/树导航移除时自然前移
|
|
79
|
-
- **awaiting_validation 问询只发一次**:内存 once 标志防重放(reload 后不重问)。代价是重启后需用户在对话里主动回报——比误重问的选择框更安静
|
|
93
|
+
- **集中状态机而非分散闭包**:全部状态收敛为一个不可变 `State`(mode + plan + execution),唯一 `transition()` 入口,纯函数单测全覆盖。代价是新增行为必须先定义转移事件——换来任何状态变化都有唯一出处
|
|
94
|
+
- **原生 UI 而非接管 composer**:只用 `setStatus` / `setWidget` / `ui.custom` / `ui.select`,不碰编辑器与消息栏——与任何其它扩展零冲突
|
|
95
|
+
- **砍掉干净会话交接**:跨会话 transfer/reconcile 的多段状态机收益低、分支爆炸,不做。要换会话,新会话里重新规划即可——计划文件本身可以复用
|
|
96
|
+
- **宽容步骤解析**:编号 / checkbox / 短横线都接受,重复步骤去重;解析失败不报错,而是返回一段模型可执行的修复指引
|
|
97
|
+
- **上下文锚定注入**:计划块作为 user 消息插在最后一条真实用户消息之前,位置与内容稳定——前缀缓存持续命中
|
|
98
|
+
- **awaiting_validation 问询只发一次**:内存 once 标志防重放(reload 后不重问),比误重问的选择框更安静
|
|
80
99
|
|
|
81
100
|
## 开发
|
|
82
101
|
|
package/package.json
CHANGED