@wbline/pi-plan-build 0.0.8 → 0.1.0

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/README.md CHANGED
@@ -1,116 +1,119 @@
1
- # pi-plan-build
2
-
3
- > 让 agent 先规划、经你审批、再动手。为 [Pi coding agent](https://github.com/earendil-works/pi-mono) 设计的 plan/build 双模式工作流扩展。
4
-
5
- **只读规划 → 显式审批 → 分步/整段实现 → 验证闭环。** 规划期间 agent 改不了你的项目;审批之前没有实现;每一步的完成与验证都有据可查。
6
-
7
- ```text
8
- plan 模式(只读) 审批(三选一) build 模式
9
- 调研讨论 → 写计划文件 ──▶ plan_exit ──▶ 本会话 / 分步 / 留在 plan ──▶ 实现 → 验证 → plan_complete
10
- ▲ 守卫:只许写计划文件 ▲ 守卫:计划文件只读
11
- ```
12
-
13
- ## 快速开始
14
-
15
- ```bash
16
- pi install npm:@wbline/pi-plan-build
17
- ```
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
- - 🚪 **全链路显式决策**:`plan_task new` 先问「创建计划还是直接执行」(明确要求规划可传参跳过),`plan_exit` 后问「本会话/分步/留下」;build 模式建计划、build 中途修订计划(`plan_task revise`)、plan 模式被守卫拦截时各有一道确认门——每次模式转换都由用户一键拍板
42
- - 📒 **事后对账**:放行波及面无法验证的工具(IDE 终端命令、shell)前记录计划文件基线,回合结束时文件被改动即警告核对
43
- - 🪜 **分步执行**:计划里的实现步骤逐个就绪,你说"继续"才开工,说「剩下的都做完」即授权连跑自动推进;侧栏实时显示 `[待办]/[就绪]/[进行]/[完成]/[跳过]` 进度
44
- - ✅ **验证闭环**:`awaiting_validation` 结算后,在你下一条消息时确认一次「必需验证通过了吗?」,通过才收尾,否则计划保持开放——不会在你还没开始验证时就弹窗
45
- - 🌐 **中英双语提示词与工具描述**:菜单一键切换;7 个工具全模式常驻(稳定工具目录),模式切换不抖动工具列表,prompt cache 持续命中
46
-
47
- ## 命令
48
-
49
- | 命令 / 快捷键 | 说明 |
50
- |---|---|
51
- | `/plan-build` | 交互菜单:切换模式 / 查看状态 / 标记完成 / 放弃计划(原因必填,文件保留)/ 语言切换 / 设置文件 |
52
- | `/plan` `/build` | 直切模式;IDE(ACP)桥接层按命令名调用,JetBrains AI 聊天的模式选择器依赖这两个命令 |
53
- | `Alt+M` | 直接切换模式;新会话默认模式由设置 `defaultMode` 决定 |
54
-
55
- 状态栏徽标(`📋 plan` / `🔨 build` + 计划标题与进度)显示在底部;分步执行时步骤列表 widget 同步显示。
56
-
57
- ## 工具
58
-
59
- | 工具 | 说明 |
60
- |---|---|
61
- | `plan_task` | 任务生命周期:`new` 建计划(plan 模式)、`revise` 请求切回 plan 修订当前计划(弹窗确认,build 中途修计划的专用通道)、`include` 追加用户批准的范围、`update` 改名、`exclude` 记录排除、`abandon`、`list/show`。所有转移必须带 `expectedAttached` 做乐观并发(`new` 传 null,其余传当前 seq),不匹配即拒。`new` 内置入口询问:用户未明确要求规划(传 `planningRequested: true` 可跳过)时,先弹窗让用户选「创建计划 / 直接执行」,选直接执行即自动切 build、不建计划;build 模式调用 `new` 会先弹窗确认切到 plan。`new` 支持 `fromFile` 恢复既有计划文件(plans 目录内原地接管,外部文件复制并在原文件标记「已接管」;换会话后接着干);`list` 附带 plans 目录历史计划与归档结局 |
62
- | `plan_exit` | **plan 模式终点**。要求计划文件已写盘,然后弹出审批:本会话连续实现 / 分步实现 / 留在 plan 模式。取消对话框 ≠ 主动留下(模型会向你询问意图);无交互 UI(print/json)时跳过审批门自动选本会话连续实现 |
63
- | `plan_step_control` | 分步执行:`start` 批准就绪步(`advance: "all"` 一次授权连跑剩余步骤,遇阻塞才停)、`acknowledge` 指认用户声明的已完成步(无需先 start)、`skip`、`revise` 修订未完成步(同步改文件)、`pause/resume`、`cancel`。一次只许一个转移 |
64
- | `plan_step_complete` | 完成当前进行中的步(摘要必填),立即生效不等待验收;最后一步完成即自动收尾整计划 |
65
- | `plan_complete` | 标记整计划完成——仅在全部工作与必需检查通过,或用户明确指示时。收尾时在计划文件文末写入状态块(`> **状态:已完成**(日期)` + 摘要),放弃同理(含原因),历史计划单看文件即可知结局 |
66
- | `plan_set_outcome` | 记录未完成结局并保持计划开放:`awaiting_validation`(必填精确的 userAction)/ `blocked` / `waiting_for_input` / `still_working` |
67
- | `plan_question` | 结构化选择题,收集决策;选择列表末尾自动附「✏️ 自行输入…」入口,用户可跳出选项自由作答(空提交/Esc 返回选项);无交互 UI 时自动降级为文本提问 |
68
-
69
- ## 设置
70
-
71
- `~/.pi/agent/pi-plan-build.json`,全部可省略:
72
-
73
- | 字段 | 默认 | 说明 |
74
- |---|---|---|
75
- | `lang` | `"zh"` | 提示词语言:`"zh"` / `"en"` |
76
- | `defaultMode` | `"build"` | 新会话默认模式(startup/new 生效;resume 尊重恢复出的状态) |
77
- | `protectPlanFile` | `true` | build 模式是否保护计划文件(关闭后对账一并停用) |
78
- | `toolGuard` | — | 工具分类强制覆盖:`{ "readonly": [], "mutating": [] }`,列出的工具名优先级最高 |
79
-
80
- ## 权限边界
81
-
82
- 守卫在 `tool_call` 前拦截,路径先归一化再做 symlink 解析,不存在的文件解析最远存在父目录:
83
-
84
- - **管辖范围**:只守卫 pi 内置工具与 JetBrains IDE 桥接工具(`ide_` 前缀)——内置 8 个全量显式分类(edit/write 变更、bash/powershell 执行面、read/find/grep/ls 只读),`ide_*` 动态分类;其它扩展/MCP 工具不守卫(codemode 的嵌套调用走 pi 同一 tool_call 管线,仍受守卫约束)
85
- - **plan 模式**:文件变更通道(原生 `edit/write` 与 IDE 桥接工具)只许目标为当前计划文件。IDE 工具动态分类不写死名单;**无路径或波及面无法验证(未知变更工具、语义重命名)的调用一律阻断**——宁可误拦不可放行;有 UI 时拦截会弹确认门,用户确认即切 build 放行本次修改,拒绝则本回合只拦不再问(回合结束重置)
86
- - **时序硬闸**:最近一条 assistant 消息里 `plan_task` 结构转移(new/revise/include/update/exclude/abandon 等非只读动作)未收尾时,文件变更与生命周期工具一律先等转移收尾(`list/show` 只读动作不拦)
87
- - **事后对账**:build 模式放行波及面无法验证的变更工具前记录计划文件内容基线,结算(agent_settled)时发现文件被改动即警告提示核对;bash/powershell 与 IDE 执行面工具改写计划文件同样纳入
88
- - **模式边界**:`plan_task new` 仅限 plan 模式(build 下创建的计划无法走 plan_exit 审批);分步执行进行中禁止切回 plan 模式(避免"只读 + 实现第 N 步"的矛盾注入);plan 模式且无计划时,`new` 先弹窗询问「创建计划 / 直接执行」(用户明确要求规划可跳过),选直接执行自动切 build;build 模式调用 `new` 也会弹窗确认切到 plan(拒绝则保持 build);build 中途修订计划走 `plan_task revise`(弹窗确认切回 plan)——所有模式转换都由用户拍板
89
- - **build 模式**:已写盘的计划文件受保护(`protectPlanFile: false` 可关);修订计划调用 `plan_task revise`(确认门切回 plan)或由用户 /plan;未列入的 IDE 变更工具同样过守卫(无法验证目标时放行)
90
- - **bash/powershell 与 IDE 执行面工具不做分类沙箱**:终端命令、运行配置、构建、SQL 执行、inspection KTS 的目标不可提取且能力与 shell 等价——plan 模式为提示词约束,build 模式放行并纳入事后对账;诚实标注而非冒充沙箱
91
- - 扩展自身对计划文件的修订(步骤 revise、终态状态块)不经 tool_call 守卫(守卫只拦模型调用),但受同一状态机校验并在计划文件上留痕;终态归档 append-only,文件为空或写失败则静默跳过
92
-
93
- ## 设计取舍
94
-
95
- - **集中状态机而非分散闭包**:全部状态收敛为一个不可变 `State`(mode + plan + execution),唯一 `transition()` 入口,纯函数单测全覆盖。代价是新增行为必须先定义转移事件——换来任何状态变化都有唯一出处
96
- - **原生 UI 而非接管 composer**:只用 `setStatus` / `setWidget` / `ui.custom` / `ui.select`,不碰编辑器与消息栏——与任何其它扩展零冲突
97
- - **砍掉干净会话交接**:跨会话 transfer/reconcile 的多段状态机收益低、分支爆炸,不做。换会话后用 `plan_task new fromFile` 恢复既有计划文件接着干(`list` 可查历史计划与结局)
98
- - **宽容步骤解析**:编号 / checkbox / 短横线都接受,重复步骤去重;解析失败不报错,而是返回一段模型可执行的修复指引
99
- - **上下文锚定注入**:计划块作为 user 消息插在最后一条真实用户消息之前,位置与内容稳定——前缀缓存持续命中
100
- - **验证问询等下一条消息**:`awaiting_validation` 结算后不在回合刚结束时弹窗(那时你还没验证),而在你下一次发消息时确认一次;未通过不自动重问,重新结算才重置——比误重问的选择框更安静
101
- - **无 UI 跳过审批门**:print/json 模式没有可交互的用户,入口询问与 `plan_exit` 审批门一致跳过(后者自动选本会话连续实现)——不会出现"计划建了却永远拿不到实现授权"的死锁
102
-
103
- ## 开发
104
-
105
- ```bash
106
- npm install # 安装开发依赖(含 pi 1.3.0 类型)
107
- npm run check # biome + tsc 双检查
108
- npm test # 26 个纯函数单测:状态机 / 步骤解析 / 路径守卫 / 持久化解码
109
- npm run smoke # 装配冒烟:stub ExtensionAPI 走完整流程(注册、守卫、菜单、注入)
110
- ```
111
-
112
- 历史更新见 [CHANGELOG.md](CHANGELOG.md)(Keep a Changelog 格式,随版本发布维护)。
113
-
114
- ## License
115
-
116
- MIT
1
+ # pi-plan-build
2
+
3
+ > 让 agent 先规划、经你审批、再动手。为 [Pi coding agent](https://github.com/earendil-works/pi-mono) 设计的 plan/build 双模式工作流扩展。
4
+
5
+ **只读规划 → 显式审批 → 分步/整段实现 → 验证闭环。** 规划期间 agent 改不了你的项目;审批之前没有实现;每一步的完成与验证都有据可查。
6
+
7
+ ```text
8
+ plan 模式(只读) 审批(三选一) build 模式
9
+ 调研讨论 → 写计划文件 ──▶ plan_exit ──▶ 本会话 / 分步 / 留在 plan ──▶ 实现 → 验证 → plan_complete
10
+ ▲ 守卫:只许写计划文件 ▲ 守卫:计划文件只读
11
+ ```
12
+
13
+ ## 快速开始
14
+
15
+ ```bash
16
+ pi install npm:@wbline/pi-plan-build
17
+ ```
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
+ - 🚪 **全链路显式决策**:`plan_task new` 先问「创建计划还是直接执行」(明确要求规划可传参跳过),`plan_exit` 后问「本会话/分步/留下」;build 模式建计划、build 中途修订计划(`plan_task revise`)、plan 模式被守卫拦截时各有一道确认门——每次模式转换都由用户一键拍板
42
+ - 📒 **事后对账**:放行波及面无法验证的工具(IDE 终端命令、shell)前记录计划文件基线,回合结束时文件被改动即警告核对
43
+ - 🪜 **分步执行**:计划里的实现步骤逐个就绪,你说"继续"才开工,说「剩下的都做完」即授权连跑自动推进;侧栏实时显示 `[待办]/[就绪]/[进行]/[完成]/[跳过]` 进度
44
+ - ✅ **验证闭环**:`awaiting_validation` 结算后,在你下一条消息时确认一次「必需验证通过了吗?」,通过才收尾,否则计划保持开放——不会在你还没开始验证时就弹窗
45
+ - 💬 **弹窗选项带说明**:所有选择弹窗(审批三选一、入口询问、`plan_question`)在选项下方渲染 dim 小字说明——选项是什么、选了会发生什么,不用猜。TUI 原生渲染;IDE 桥接下说明内联进选项文本
46
+ - 🌐 **中英双语提示词与工具描述**:菜单一键切换;7 个工具全模式常驻(稳定工具目录),模式切换不抖动工具列表,prompt cache 持续命中
47
+
48
+ ## 命令
49
+
50
+ | 命令 / 快捷键 | 说明 |
51
+ |---|---|
52
+ | `/plan-build` | 交互菜单:切换模式 / 查看状态 / 标记完成 / 放弃计划(原因必填,文件保留)/ 语言切换 / 设置文件 |
53
+ | `/plan` `/build` | 直切模式;IDE(ACP)桥接层按命令名调用,JetBrains AI 聊天的模式选择器依赖这两个命令 |
54
+ | `Alt+M` | 直接切换模式;新会话默认模式由设置 `defaultMode` 决定 |
55
+
56
+ 状态栏徽标(`📋 plan` / `🔨 build` + 计划标题与进度)显示在底部;分步执行时步骤列表 widget 同步显示。
57
+
58
+ ## 工具
59
+
60
+ | 工具 | 说明 |
61
+ |---|---|
62
+ | `plan_task` | 任务生命周期:`new` 建计划(plan 模式)、`revise` 请求切回 plan 修订当前计划(弹窗确认,build 中途修计划的专用通道)、`include` 追加用户批准的范围、`update` 改名、`exclude` 记录排除(随状态持久化并注入上下文)、`abandon`(有 UI 时需确认)、`list/show`。所有转移必须带 `expectedAttached` 做乐观并发(`new` 传 null,其余传当前 seq,结构转移递增 seq),不匹配即拒。`new` 内置入口询问:用户未明确要求规划(传 `planningRequested: true` 可跳过)时,先弹窗让用户选「创建计划 / 直接执行」,选直接执行即自动切 build、不建计划;build 模式调用 `new` 会先弹窗确认切到 plan。`new` 支持 `fromFile` 恢复既有计划文件(plans 目录内原地接管,外部文件复制到 canonical 路径并在文末注明来源,原文件保留不改动;换会话后接着干);`list` 附带 plans 目录历史计划与归档结局 |
63
+ | `plan_exit` | **plan 模式终点**。要求计划文件已写盘,然后弹出审批:本会话连续实现 / 分步实现 / 留在 plan 模式。取消对话框 ≠ 主动留下(模型会向你询问意图);无交互 UI(print/json)时跳过审批门自动选本会话连续实现 |
64
+ | `plan_step_control` | 分步执行:`start` 批准就绪步(`advance: "all"` 一次授权连跑剩余步骤,遇阻塞才停;`advance: "one"` 显式撤回连跑授权,后续步恢复逐个批准)、`acknowledge` 指认用户声明的已完成步(无需先 start)、`skip`、`revise` 修订未完成步(同步改文件)、`pause/resume`、`cancel`。一次只许一个转移 |
65
+ | `plan_step_complete` | 完成当前进行中的步(摘要必填),立即生效不等待验收;最后一步完成即自动收尾整计划 |
66
+ | `plan_complete` | 标记整计划完成——仅在全部工作与必需检查通过,或用户明确指示时;有交互 UI 时弹确认门(分步执行中会列出未完成步骤,拒绝则计划保持开放)。收尾时在计划文件文末写入状态块(`> **状态:已完成**(日期)` + 摘要),放弃同理(含原因),历史计划单看文件即可知结局 |
67
+ | `plan_set_outcome` | 记录未完成结局并保持计划开放:`awaiting_validation`(必填精确的 userAction)/ `blocked` / `waiting_for_input` / `still_working` |
68
+ | `plan_question` | 结构化选择题,收集决策;选择列表末尾自动附「✏️ 自行输入…」入口,用户可跳出选项自由作答(空提交/Esc 返回选项);无交互 UI 时自动降级为文本提问 |
69
+
70
+ ## 设置
71
+
72
+ `~/.pi/agent/pi-plan-build.json`,全部可省略:
73
+
74
+ > 设置文件在扩展加载时读取一次:改完需重启 pi 生效(菜单里的语言切换除外,立即生效)。
75
+
76
+ | 字段 | 默认 | 说明 |
77
+ |---|---|---|
78
+ | `lang` | `"zh"` | 提示词语言:`"zh"` / `"en"` |
79
+ | `defaultMode` | `"build"` | 新会话默认模式(startup/new 生效;resume 尊重恢复出的状态) |
80
+ | `protectPlanFile` | `true` | build 模式是否保护计划文件(关闭后对账一并停用) |
81
+ | `toolGuard` | — | 工具分类强制覆盖:`{ "readonly": [], "mutating": [] }`,列出的工具名优先级最高 |
82
+
83
+ ## 权限边界
84
+
85
+ 守卫在 `tool_call` 前拦截,路径先归一化再做 symlink 解析,不存在的文件解析最远存在父目录:
86
+
87
+ - **管辖范围**:只守卫 pi 内置工具与 JetBrains IDE 桥接工具(`ide_` 前缀)——内置 8 个全量显式分类(edit/write 变更、bash/powershell 执行面、read/find/grep/ls 只读),`ide_*` 动态分类;其它扩展/MCP 工具不守卫(codemode 的嵌套调用走 pi 同一 tool_call 管线,仍受守卫约束)。计划文件在任何模式下不可删除(`apply_patch` 的 Delete File 目标命中计划文件即阻断),收尾走 `plan_complete` / `plan_task abandon`
88
+ - **plan 模式**:文件变更通道(原生 `edit/write` 与 IDE 桥接工具)只许目标为当前计划文件。IDE 工具动态分类不写死名单;**无路径或波及面无法验证(未知变更工具、语义重命名)的调用一律阻断**——宁可误拦不可放行;有 UI 时拦截会弹确认门,用户确认即切 build 放行本次修改,拒绝则本回合只拦不再问(回合结束重置)
89
+ - **时序硬闸**:最近一条 assistant 消息里 `plan_task` 结构转移(new/revise/include/update/exclude/abandon 等非只读动作)未收尾时,文件变更与生命周期工具一律先等转移收尾(`list/show` 只读动作不拦)
90
+ - **事后对账**:build 模式放行波及面无法验证的变更工具前记录计划文件内容基线,结算(agent_settled)时发现文件被改动即警告提示核对;bash/powershell 与 IDE 执行面工具改写计划文件同样纳入
91
+ - **模式边界**:`plan_task new` 仅限 plan 模式(build 下创建的计划无法走 plan_exit 审批);分步执行进行中禁止切回 plan 模式(避免"只读 + 实现第 N 步"的矛盾注入);plan 模式且无计划时,`new` 先弹窗询问「创建计划 / 直接执行」(用户明确要求规划可跳过),选直接执行自动切 build;build 模式调用 `new` 也会弹窗确认切到 plan(拒绝则保持 build);build 中途修订计划走 `plan_task revise`(弹窗确认切回 plan)——所有模式转换都由用户拍板
92
+ - **build 模式**:计划文件写盘前后都受保护(`protectPlanFile: false` 可关)——未写盘的计划同样不许绕过审阅改写;修订计划调用 `plan_task revise`(确认门切回 plan)或由用户 /plan;波及面无法从输入验证(undefined 或空 targets)的变更工具放行并纳入事后对账
93
+ - **bash/powershell 与 IDE 执行面工具不做分类沙箱**:终端命令、运行配置、构建、SQL 执行、inspection KTS 的目标不可提取且能力与 shell 等价——plan 模式为提示词约束,build 模式放行并纳入事后对账;诚实标注而非冒充沙箱
94
+ - 扩展自身对计划文件的修订(步骤 revise、终态状态块)不经 tool_call 守卫(守卫只拦模型调用),但受同一状态机校验并在计划文件上留痕;终态归档 append-only,文件为空或写失败则静默跳过
95
+
96
+ ## 设计取舍
97
+
98
+ - **集中状态机而非分散闭包**:全部状态收敛为一个不可变 `State`(mode + plan + execution),唯一 `transition()` 入口,纯函数单测全覆盖。代价是新增行为必须先定义转移事件——换来任何状态变化都有唯一出处
99
+ - **原生 UI 而非接管 composer**:只用 `setStatus` / `setWidget` / `ui.custom` / `ui.select`,不碰编辑器与消息栏——与任何其它扩展零冲突
100
+ - **砍掉干净会话交接**:跨会话 transfer/reconcile 的多段状态机收益低、分支爆炸,不做。换会话后用 `plan_task new fromFile` 恢复既有计划文件接着干(`list` 可查历史计划与结局)
101
+ - **宽容步骤解析**:编号 / checkbox / 短横线都接受,重复步骤去重;解析失败不报错,而是返回一段模型可执行的修复指引
102
+ - **上下文锚定注入**:计划块作为 user 消息插在最后一条真实用户消息之前,位置与内容稳定——前缀缓存持续命中
103
+ - **验证问询等下一条消息**:`awaiting_validation` 结算后不在回合刚结束时弹窗(那时你还没验证),而在你下一次发消息时确认一次;未通过不自动重问,重新结算才重置——比误重问的选择框更安静
104
+ - **无 UI 跳过审批门**:print/json 模式没有可交互的用户,入口询问与 `plan_exit` 审批门一致跳过(后者自动选本会话连续实现)——不会出现"计划建了却永远拿不到实现授权"的死锁
105
+
106
+ ## 开发
107
+
108
+ ```bash
109
+ npm install # 安装开发依赖(含 pi 1.3.0 类型)
110
+ npm run check # biome + tsc 双检查
111
+ npm test # 26 个纯函数单测:状态机 / 步骤解析 / 路径守卫 / 持久化解码
112
+ npm run smoke # 装配冒烟:stub ExtensionAPI 走完整流程(注册、守卫、菜单、注入)
113
+ ```
114
+
115
+ 历史更新见 [CHANGELOG.md](CHANGELOG.md)(Keep a Changelog 格式,随版本发布维护)。
116
+
117
+ ## License
118
+
119
+ MIT
package/index.ts CHANGED
@@ -1,6 +1,6 @@
1
- /**
2
- * 包根入口薄壳:pi.extensions 指向 ./index.ts,
3
- * 让 pi 显示干净的包名 @wbline/pi-plan-build(无 :src 路径后缀)。
4
- * 实现在 src/index.ts,此处仅 re-export。
5
- */
6
- export { default } from "./src/index.ts";
1
+ /**
2
+ * 包根入口薄壳:pi.extensions 指向 ./index.ts,
3
+ * 让 pi 显示干净的包名 @wbline/pi-plan-build(无 :src 路径后缀)。
4
+ * 实现在 src/index.ts,此处仅 re-export。
5
+ */
6
+ export { default } from "./src/index.ts";
package/package.json CHANGED
@@ -1,53 +1,53 @@
1
- {
2
- "name": "@wbline/pi-plan-build",
3
- "version": "0.0.8",
4
- "description": "Plan/Build dual-mode for the Pi coding agent: read-only planning, explicit approval, step-wise execution.",
5
- "license": "MIT",
6
- "author": "wongbin",
7
- "keywords": [
8
- "pi-package",
9
- "pi-extension",
10
- "plan-mode",
11
- "build-mode",
12
- "planning",
13
- "task-management"
14
- ],
15
- "type": "module",
16
- "main": "./index.ts",
17
- "engines": {
18
- "node": ">=22.6"
19
- },
20
- "pi": {
21
- "extensions": [
22
- "./index.ts"
23
- ]
24
- },
25
- "files": [
26
- "index.ts",
27
- "src",
28
- "README.md",
29
- "CHANGELOG.md",
30
- "LICENSE"
31
- ],
32
- "scripts": {
33
- "check": "biome check src test && tsc --noEmit",
34
- "test": "node --test test/state.test.ts test/steps-guard.test.ts",
35
- "test:watch": "node --test --watch test/state.test.ts test/steps-guard.test.ts",
36
- "smoke": "node test/smoke.mjs",
37
- "prepack": "npm run check && npm test"
38
- },
39
- "peerDependencies": {
40
- "@earendil-works/pi-coding-agent": ">=1.3.0",
41
- "@earendil-works/pi-tui": "*",
42
- "typebox": "*"
43
- },
44
- "devDependencies": {
45
- "@biomejs/biome": "^2.5.15",
46
- "@earendil-works/pi-coding-agent": "1.3.0",
47
- "@earendil-works/pi-tui": "1.3.0",
48
- "@types/node": "^22.0.0",
49
- "jiti": "^2.7.0",
50
- "typebox": "^1.3.27",
51
- "typescript": "^5.9.3"
52
- }
53
- }
1
+ {
2
+ "name": "@wbline/pi-plan-build",
3
+ "version": "0.1.0",
4
+ "description": "Plan/Build dual-mode for the Pi coding agent: read-only planning, explicit approval, step-wise execution.",
5
+ "license": "MIT",
6
+ "author": "wongbin",
7
+ "keywords": [
8
+ "pi-package",
9
+ "pi-extension",
10
+ "plan-mode",
11
+ "build-mode",
12
+ "planning",
13
+ "task-management"
14
+ ],
15
+ "type": "module",
16
+ "main": "./index.ts",
17
+ "engines": {
18
+ "node": ">=22.6"
19
+ },
20
+ "pi": {
21
+ "extensions": [
22
+ "./index.ts"
23
+ ]
24
+ },
25
+ "files": [
26
+ "index.ts",
27
+ "src",
28
+ "README.md",
29
+ "CHANGELOG.md",
30
+ "LICENSE"
31
+ ],
32
+ "scripts": {
33
+ "check": "biome check src test && tsc --noEmit",
34
+ "test": "node --test test/state.test.ts test/steps-guard.test.ts",
35
+ "test:watch": "node --test --watch test/state.test.ts test/steps-guard.test.ts",
36
+ "smoke": "node test/smoke.mjs",
37
+ "prepack": "npm run check && npm test"
38
+ },
39
+ "peerDependencies": {
40
+ "@earendil-works/pi-coding-agent": ">=1.3.0",
41
+ "@earendil-works/pi-tui": "*",
42
+ "typebox": "*"
43
+ },
44
+ "devDependencies": {
45
+ "@biomejs/biome": "^2.5.15",
46
+ "@earendil-works/pi-coding-agent": "1.3.0",
47
+ "@earendil-works/pi-tui": "1.3.0",
48
+ "@types/node": "^22.0.0",
49
+ "jiti": "^2.7.0",
50
+ "typebox": "^1.3.27",
51
+ "typescript": "^5.9.3"
52
+ }
53
+ }
package/src/context.ts CHANGED
@@ -39,18 +39,24 @@ export function buildContextBlock(
39
39
  const plan = state.plan;
40
40
  if (!plan) return undefined; // 收窄:plan 模式无计划已在上方返回
41
41
  parts.push(``, `## 范围`, clampScope(plan.scope));
42
+ if (plan.excludes?.length)
43
+ parts.push(
44
+ ``,
45
+ `## 已排除话题(不要展开)`,
46
+ ...plan.excludes.map((x) => `- ${clampLine(x)}`),
47
+ );
42
48
  if (plan.outcome) {
43
49
  if (plan.outcome.kind === "awaiting_validation") {
44
50
  parts.push(
45
51
  ``,
46
52
  P.awaitingValidation,
47
53
  ``,
48
- `需要用户执行:${plan.outcome.userAction}`,
54
+ `需要用户执行:${clampLine(plan.outcome.userAction)}`,
49
55
  );
50
56
  } else {
51
57
  parts.push(
52
58
  ``,
53
- `计划结局(${plan.outcome.kind}):${plan.outcome.reason}`,
59
+ `计划结局(${plan.outcome.kind}):${clampLine(plan.outcome.reason)}`,
54
60
  );
55
61
  }
56
62
  }
@@ -82,6 +88,11 @@ export function buildContextBlock(
82
88
  return parts.join("\n");
83
89
  }
84
90
 
91
+ /** 单行截断:排除话题按行注入,超长行截断(与 scope 截断同理,保持注入稳定)。 */
92
+ function clampLine(s: string): string {
93
+ return s.length <= 200 ? s.replace(/\s+/g, " ") : `${s.slice(0, 200)}…`;
94
+ }
95
+
85
96
  /**
86
97
  * 返回注入后的消息数组(不修改入参)。
87
98
  * 注入点:最后一条 role==="user" 的真实用户消息之前;没有则最前。
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import fs from "node:fs";
6
6
  import path from "node:path";
7
+ import { LIMITS } from "./limits.ts";
7
8
 
8
9
  export function archivePlanFile(
9
10
  path: string,
@@ -25,23 +26,6 @@ export function archivePlanFile(
25
26
  }
26
27
  }
27
28
 
28
- /** fromFile 外部恢复的接管标记:原文件文末追加「已接管」块(append-only,失败静默)。 */
29
- export function markSuperseded(sourcePath: string, newPath: string): boolean {
30
- try {
31
- if (!fs.readFileSync(sourcePath, "utf8").trim()) return false;
32
- const d = new Date();
33
- const p = (n: number) => String(n).padStart(2, "0");
34
- const date = `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
35
- fs.appendFileSync(
36
- sourcePath,
37
- `\n---\n\n> **状态:已接管**(${date}):此计划已复制到新计划文件继续:${newPath}\n`,
38
- );
39
- return true;
40
- } catch {
41
- return false;
42
- }
43
- }
44
-
45
29
  export interface HistoricalPlan {
46
30
  path: string;
47
31
  title: string;
@@ -65,6 +49,15 @@ export function listPlanFiles(cwd: string, limit = 20): HistoricalPlan[] {
65
49
  const p = path.join(dir, name);
66
50
  try {
67
51
  const st = fs.statSync(p);
52
+ if (st.size > LIMITS.listFileBytes) {
53
+ // 异常大文件不读内容:标题退化为文件名、结局未知,列表保持完整
54
+ items.push({
55
+ path: p,
56
+ title: name.replace(/\.md$/, ""),
57
+ mtimeMs: st.mtimeMs,
58
+ });
59
+ continue;
60
+ }
68
61
  const content = fs.readFileSync(p, "utf8");
69
62
  const title =
70
63
  /^#\s+(.+)$/m.exec(content)?.[1]?.trim() || name.replace(/\.md$/, "");
package/src/core/guard.ts CHANGED
@@ -209,6 +209,8 @@ export function planTaskPendingInLastAssistant(
209
209
  export function normalizePath(raw: string, cwd: string): string {
210
210
  let p = raw.trim();
211
211
  if (p.startsWith("@")) p = p.slice(1).trim();
212
+ // Windows 长路径前缀:剥掉后再比较,防 \\?\ 形式绕过计划文件匹配
213
+ if (p.startsWith("\\\\?\\")) p = p.slice(4);
212
214
  if (p.startsWith("~/") || p === "~") p = path.join(os.homedir(), p.slice(1));
213
215
  if (!path.isAbsolute(p)) p = path.resolve(cwd, p);
214
216
  return path.normalize(p);
@@ -291,6 +293,42 @@ export type GuardDecision =
291
293
  | { action: "allow" }
292
294
  | { action: "block"; reason: string; summary: string };
293
295
 
296
+ /**
297
+ * 提取补丁类工具声明要删除的文件(codex 格式 `*** Delete File:`)。
298
+ * 删除计划文件在任何模式下都不允许(收尾走 plan_complete / plan_task abandon),
299
+ * 与"允许写计划文件"分开裁决;其他工具无删除语义,返回空数组。
300
+ */
301
+ export function extractDeletionTargets(
302
+ toolName: string,
303
+ input: unknown,
304
+ cwd: string,
305
+ ): string[] {
306
+ if (!toolName.endsWith("_apply_patch")) return [];
307
+ const inp = (input ?? {}) as Record<string, unknown>;
308
+ const text =
309
+ typeof inp.input === "string"
310
+ ? inp.input
311
+ : typeof inp.patch === "string"
312
+ ? inp.patch
313
+ : "";
314
+ const targets: string[] = [];
315
+ for (const m of text.matchAll(/^\*\*\* Delete File: (.+)$/gm))
316
+ targets.push(normalizePath(m[1].trim(), cwd));
317
+ // unified diff 的删除:`--- <path>` 紧跟 `+++ /dev/null`(与 extractMutationTargets
318
+ // 的成对规则一致,正文里的伪文件头不成对不误判)
319
+ const lines = text.split(/\r?\n/);
320
+ for (let i = 0; i < lines.length - 1; i++) {
321
+ const del = (lines[i] ?? "").match(/^--- (?:a\/)?(.+?)(?:\t.*)?$/);
322
+ if (!del) continue;
323
+ const add = (lines[i + 1] ?? "").match(/^\+\+\+ (?:b\/)?(.+?)(?:\t.*)?$/);
324
+ if (add && add[1].trim() === "/dev/null") {
325
+ const v = del[1].trim();
326
+ if (v) targets.push(normalizePath(v, cwd));
327
+ }
328
+ }
329
+ return targets;
330
+ }
331
+
294
332
  /**
295
333
  * 变更裁决。targets 为 extractMutationTargets 的结果:
296
334
  * - Plan 模式:全部目标都必须是当前计划文件;undefined/空 一律阻断。
@@ -320,6 +358,9 @@ export function decideFileMutation(
320
358
  : { action: "allow" };
321
359
  }
322
360
  if (targets.length === 0) {
361
+ // 空数组与 undefined 同类:该调用的波及面无法从输入验证。
362
+ // plan 模式宁可误拦;build 放行并由事后对账兜底。
363
+ if (mode === "build") return { action: "allow" };
323
364
  return {
324
365
  action: "block",
325
366
  reason: `${toolName} 调用没有可见的文件路径,无法验证写入目标。请使用带路径参数的编辑工具,明确指向目标文件。`,
@@ -342,12 +383,15 @@ export function decideFileMutation(
342
383
  }
343
384
 
344
385
  // build 模式:保护计划文件
345
- if (plan && planSaved && ts.some((t) => t === plan)) {
386
+ if (plan && ts.some((t) => t === plan)) {
346
387
  return {
347
388
  action: "block",
348
- reason:
349
- "计划文件在 build 模式受保护。修订计划:调用 plan_task revise(用户确认后切回 plan),或由用户 /plan 切换。",
350
- summary: `${toolName} 要改写受保护的计划文件`,
389
+ reason: planSaved
390
+ ? "计划文件在 build 模式受保护。修订计划:调用 plan_task revise(用户确认后切回 plan),或由用户 /plan 切换。"
391
+ : "计划尚未写盘审阅,build 模式不开放计划文件写入。请回 plan 模式(用户 /plan,或 plan_task revise 确认切换)完成计划后经 plan_exit 审批。",
392
+ summary: planSaved
393
+ ? `${toolName} 要改写受保护的计划文件`
394
+ : `${toolName} 要写入尚未审阅的计划文件`,
351
395
  };
352
396
  }
353
397
  return { action: "allow" };
@@ -0,0 +1,31 @@
1
+ /**
2
+ * 工具参数与文件读取的大小上限:防失控输出缓慢撑爆会话条目与模型上下文。
3
+ * 上限刻意宽松(正常使用量的数十倍),只拦失控与滥用,不约束正常工作流。
4
+ */
5
+ export const LIMITS = {
6
+ /** 计划文件读入/回显上限(plan_exit、fromFile)。 */
7
+ planFileBytes: 512 * 1024,
8
+ /** 历史计划列表的单文件内容解析上限(超出降级:标题取文件名、结局未知)。 */
9
+ listFileBytes: 1024 * 1024,
10
+ /** 计划标题。 */
11
+ title: 200,
12
+ /** 计划范围(new/include)。 */
13
+ scope: 64 * 1024,
14
+ /** 排除话题。 */
15
+ excludeTopic: 500,
16
+ /** 放弃原因、结局 reason/userAction。 */
17
+ reason: 2 * 1024,
18
+ /** 步骤文本与摘要。 */
19
+ stepText: 2 * 1024,
20
+ } as const;
21
+
22
+ /** 超限时返回面向模型的错误文本,否则 undefined。 */
23
+ export function overLimit(
24
+ label: string,
25
+ value: string,
26
+ max: number,
27
+ ): string | undefined {
28
+ return value.length > max
29
+ ? `${label}过长(${value.length} 字符,上限 ${max}):请精简后重试。`
30
+ : undefined;
31
+ }
@@ -54,6 +54,14 @@ export function decodeState(data: unknown): State | undefined {
54
54
  )
55
55
  return undefined;
56
56
  if (p.seq < 1 || !p.title || !p.path) return undefined;
57
+ const excludes =
58
+ p.excludes === undefined
59
+ ? undefined
60
+ : Array.isArray(p.excludes) &&
61
+ p.excludes.every((x) => typeof x === "string")
62
+ ? (p.excludes as string[])
63
+ : undefined;
64
+ if (p.excludes !== undefined && !excludes) return undefined;
57
65
  const outcome = decodeOutcome(p.outcome);
58
66
  if (p.outcome !== undefined && !outcome) return undefined;
59
67
  if (data.execution === null) {
@@ -66,6 +74,7 @@ export function decodeState(data: unknown): State | undefined {
66
74
  scope: p.scope,
67
75
  path: p.path,
68
76
  saved: p.saved,
77
+ ...(excludes ? { excludes } : {}),
69
78
  ...(outcome ? { outcome } : {}),
70
79
  },
71
80
  execution: null,
@@ -82,6 +91,7 @@ export function decodeState(data: unknown): State | undefined {
82
91
  scope: p.scope,
83
92
  path: p.path,
84
93
  saved: p.saved,
94
+ ...(excludes ? { excludes } : {}),
85
95
  ...(outcome ? { outcome } : {}),
86
96
  },
87
97
  execution,