@tt-a1i/openpi 0.1.0 → 0.1.1

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 (24) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +281 -390
  3. package/SETUP.md +20 -20
  4. package/THIRD_PARTY_NOTICES.md +3 -4
  5. package/assets/readme-hero-mobile.svg +2 -2
  6. package/assets/readme-hero.svg +10 -10
  7. package/extensions/setup/index.ts +149 -39
  8. package/extensions/setup/intercom-fs-helper.cjs +130 -0
  9. package/extensions/setup/intercom.ts +603 -0
  10. package/extensions/shared/child-session.ts +2 -1
  11. package/extensions/shared/setup-config.ts +5 -1
  12. package/extensions/subagents/index.ts +1 -1
  13. package/extensions/workflows/artifacts.ts +6 -1
  14. package/extensions/workflows/dashboard.ts +138 -27
  15. package/extensions/workflows/graph-projection.ts +238 -0
  16. package/extensions/workflows/handoff.ts +194 -0
  17. package/extensions/workflows/index.ts +242 -55
  18. package/extensions/workflows/invocation-ledger.ts +362 -0
  19. package/extensions/workflows/model.ts +52 -0
  20. package/extensions/workflows/operator.ts +131 -0
  21. package/extensions/workflows/prompt.ts +8 -6
  22. package/extensions/workflows/runner.ts +10 -2
  23. package/extensions/workflows/sandbox.ts +5 -0
  24. package/package.json +6 -6
package/README.md CHANGED
@@ -1,117 +1,132 @@
1
1
  <p align="center">
2
- <picture>
3
- <source media="(max-width: 640px)" srcset="assets/readme-hero-mobile.svg">
4
- <img src="assets/readme-hero.svg" alt="OpenPI — a Pi-native multi-agent workbench" width="100%" />
5
- </picture>
2
+ <img src="assets/openpi-package.png" alt="OpenPI logo" width="240" />
6
3
  </p>
7
4
 
5
+ <h1 align="center">OpenPI</h1>
6
+
8
7
  <p align="center">
9
- <strong>给 Pi 补上后台执行、多 Agent 编排、持久任务和可观测终端，同时保留它原本的轻量与可控。</strong>
8
+ <strong>Small harness. Deep extensions. Clean context.</strong>
10
9
  </p>
11
10
 
12
11
  <p align="center">
13
- <a href="https://github.com/earendil-works/pi-mono"><img alt="Pi 0.84.1+" src="https://img.shields.io/badge/Pi-0.84.1%2B-2f81f7?style=flat-square"></a>
14
- <img alt="Node.js 22.19+" src="https://img.shields.io/badge/Node.js-22.19%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white">
15
- <img alt="TypeScript strict" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white">
16
- <a href="https://github.com/tt-a1i/my-pi-setup/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/tt-a1i/my-pi-setup/actions/workflows/ci.yml/badge.svg"></a>
17
- <img alt="Model neutral" src="https://img.shields.io/badge/models-user--selected-bc8cff?style=flat-square">
12
+ 给 <a href="https://pi.dev">Pi</a> 加一层可靠运行时：后台执行、隔离 Subagent、可恢复 Workflow、持续任务与可观测终端。<br />
13
+ 不替换 Pi，不替你选模型，也不把另一套 Agent 平台塞进来。
18
14
  </p>
19
15
 
20
16
  <p align="center">
21
- 一套在真实开发中持续使用的 <a href="https://pi.dev">Pi</a> 扩展包。<br />
22
- 不替你选模型，不强制主题，安装后也不会偷偷增加模型调用。
17
+ <a href="https://www.npmjs.com/package/@tt-a1i/openpi"><img alt="npm version" src="https://img.shields.io/npm/v/@tt-a1i/openpi?style=flat-square&color=cb3837"></a>
18
+ <a href="https://github.com/tt-a1i/openpi/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/tt-a1i/openpi/actions/workflows/ci.yml/badge.svg"></a>
19
+ <a href="https://github.com/earendil-works/pi-mono"><img alt="Pi 0.84.1+" src="https://img.shields.io/badge/Pi-0.84.1%2B-2f81f7?style=flat-square"></a>
20
+ <img alt="Node.js 22.19+" src="https://img.shields.io/badge/Node.js-22.19%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white">
21
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3fb950?style=flat-square"></a>
23
22
  </p>
24
23
 
25
24
  <p align="center">
26
- <sub>OpenPI 是独立社区项目，与 Physical Intelligence 的 openpi 机器人项目及 Pi 官方均无关联。</sub>
25
+ <a href="#30-秒开始"><strong>30 秒开始</strong></a> ·
26
+ <a href="#openpi-解决什么">解决什么</a> ·
27
+ <a href="#能力地图">能力地图</a> ·
28
+ <a href="#运行模型">运行模型</a> ·
29
+ <a href="#三条执行路径">执行路径</a> ·
30
+ <a href="#workflow-不只是并行">Workflow</a> ·
31
+ <a href="#安全边界">安全边界</a> ·
32
+ <a href="#配置与参考">配置与参考</a>
27
33
  </p>
28
34
 
29
35
  <p align="center">
30
- <a href="#快速开始"><strong>快速开始</strong></a> ·
31
- <a href="#为什么装它">为什么装它</a> ·
32
- <a href="#核心能力">核心能力</a> ·
33
- <a href="#安全边界">安全边界</a> ·
34
- <a href="#统一配置">统一配置</a> ·
35
- <a href="#命令速查">命令速查</a> ·
36
- <a href="#faq">FAQ</a>
36
+ <sub>OpenPI 是独立社区项目，与 Physical Intelligence 的 openpi 机器人项目及 Pi 官方均无关联。</sub>
37
37
  </p>
38
38
 
39
39
  ---
40
40
 
41
- ## 快速开始
41
+ ## 30 秒开始
42
42
 
43
43
  ```bash
44
44
  pi install npm:@tt-a1i/openpi
45
45
  ```
46
46
 
47
- 重启 Pi，或在当前 Session 运行 `/reload`。然后直接描述任务：
47
+ 重启 Pi，或在当前 Session 运行 `/reload`。然后直接描述真实任务：
48
48
 
49
49
  ```text
50
- 启动前端 dev server；并行让两个子 Agent 检查 API 主链路和测试覆盖；
50
+ 启动前端 dev server；并行检查 API 主链路和测试覆盖；
51
51
  结果回来后汇总风险，主会话不要原地等待。
52
52
  ```
53
53
 
54
- Pi 会把长期进程放到后台，把独立任务交给隔离 Context 的子 Agent，并在结果完成时自动继续。Subagent 和 Workflow 状态显示在 Footer；后台终端有编辑器上方状态条，完整信息分别从 `/ps`、`/subagents` 和 `/workflows` 查看。
54
+ OpenPI 会把长期进程放到后台，把独立任务交给隔离 Context 的 Pi Subagent，把多阶段依赖组织成 Workflow。状态会持续显示；完整运行可从 `/ps`、`/subagents` 和 `/workflows` 检查或终止。
55
55
 
56
56
  > [!IMPORTANT]
57
- > 默认安装是安静的：不修改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。所有用户偏好统一通过 `/my-pi-setup` 显式配置。
57
+ > 默认安装是安静的：不改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。OpenPI 自有偏好统一通过 `/openpi-setup` 显式配置。
58
+
59
+ ```text
60
+ /openpi-setup
61
+ ```
62
+
63
+ ---
64
+
65
+ ## OpenPI 解决什么
66
+
67
+ Pi 的价值在于小：Agent loop、工具、Session 与扩展 API 已经足够。真实项目缺的不是另一套平台，而是围绕这些原语的一层可靠运行时。
68
+
69
+ | 开发现场 | OpenPI 的处理方式 | 保留的边界 |
70
+ | --------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- |
71
+ | Dev server、watcher、长测试占住主 Agent | 后台 Terminal 管理进程树、日志、超时与完成通知 | 无 stdin；Session 结束时有界清理 |
72
+ | 调研、实现、审查互相污染 Context | 每个 Subagent 使用独立的进程内 Pi SDK Session | Child 不能递归编排或拿回父级工具 |
73
+ | 多阶段 fan-out 靠 Prompt 约定 | Workflow 提供 pipeline、schema、handoff、验收与持久产物 | Sandbox 不暴露文件、网络或进程 API |
74
+ | 重跑昂贵，却不能信任旧结果 | 只 Replay 在可观测边界内证明为只读且指纹未变的调用 | 不确定就真实执行，不猜 |
75
+ | 长任务跨回合后失去方向 | Tasks、Goal、Plan Mode 与 Context Pivot 分别管理工作项、目标、批准和阶段切换 | 它们记录与控制，不伪造执行事实 |
76
+ | 后台能力看不见、停不住 | Footer、Dashboard、Artifacts 与完成通知统一展示状态 | 每类运行都有检查、取消与唯一终态 |
77
+
78
+ **核心原则：增强 Pi 的深度，不扩大隐式权限。** OpenPI 沿用用户已有的 Provider、模型、Skills、Trust 与 Session；Suggestion 只有用户开启后才运行，Subagent / Workflow 只在明确的任务动作后运行——主 Agent 调用对应工具，或用户在交互 TUI 中执行 `/btw`——不会因安装或启动自行消费模型。
58
79
 
59
- > [!TIP]
60
- > `subagent_spawn` 会立即返回。主 Agent 应继续处理确定性工作；只有下一步确实依赖子 Agent 结果时，才调用 `subagent_wait`。
80
+ ---
81
+
82
+ ## 能力地图
83
+
84
+ OpenPI 把成熟 Coding Agent 的工作习惯做成 Pi-native 能力，但不复制另一套 Runtime：
85
+
86
+ | 工作面 | 已包含的能力 |
87
+ | ------------ | --------------------------------------------------------------------------------------------------------- |
88
+ | 执行 | Background Terminal、Pi-native Subagent、Dynamic Workflow、隔离 Worktree |
89
+ | 编排 | `pipeline` / `parallel`、结构化输出、Result Handoff、Operator、Acceptance Ledger、Safe Replay、派生 Graph |
90
+ | 连续性 | Tasks、Goal、Plan Mode、Context Pivot、Session Browser、Session-scoped Cron |
91
+ | 自定义 Agent | `explorer` / `implementer` / `reviewer` / `advisor`，支持全局与项目角色文件、独立模型与 effort |
92
+ | 终端工作台 | 自定义 Footer 与任务栏、运行状态、紧凑 Tool Result、Next-action Suggestion、Git / PR 信号 |
93
+ | 快捷工作流 | `/btw` 旁路提问（TUI）、`/lg` 浏览 Diff（TUI）、`/pr` 查 PR、`/copy-all`、`fd`、`rg` |
94
+ | 人类决策 | `ask_user` 草稿与最终复核、parent-only `human_handoff`、Plan Ready 实施门禁 |
95
+ | 跨 Session | 可选 parent-only `pi-intercom`；父子通信仍走 Subagent / Workflow 原生通道 |
96
+ | 统一配置 | `/openpi-setup` 管理 OpenPI 自有模型、并发、Footer、输出密度与 Post-edit 偏好 |
97
+
98
+ OpenPI 采用 [MIT License](LICENSE)；第三方来源与保留声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
61
99
 
62
100
  ---
63
101
 
64
- ## 为什么装它
65
-
66
- Pi 的价值在于小：Agent loop、工具、Session 和扩展 API 都有，但工作方式没有被平台写死。真实项目需要的，则是围绕这些原语的一层可靠运行时。
67
-
68
- <table>
69
- <tr>
70
- <td width="33%" valign="top">
71
- <strong>后台执行</strong><br/><br/>
72
- Dev server、watcher、build 和长测试不再占住主 Agent。日志可查，超时可控，退出自动回传。
73
- </td>
74
- <td width="33%" valign="top">
75
- <strong>干净委派</strong><br/><br/>
76
- Subagent 使用独立 Pi Context。调研、实现和审查可以并行，不把全部过程塞回主会话。
77
- </td>
78
- <td width="33%" valign="top">
79
- <strong>动态编排</strong><br/><br/>
80
- Workflow 支持 pipeline、parallel、结构化输出、显式验收、恢复执行和持久产物。
81
- </td>
82
- </tr>
83
- <tr>
84
- <td width="33%" valign="top">
85
- <strong>连续工作</strong><br/><br/>
86
- Tasks 记工作项，Goal 驱动持续目标，Context Pivot 在阶段变化时主动换一块干净工作面。
87
- </td>
88
- <td width="33%" valign="top">
89
- <strong>全程可见</strong><br/><br/>
90
- 模型、Context、缓存、成本、Git、PR 与后台活动集中显示；每类运行都有检查和取消入口。
91
- </td>
92
- <td width="33%" valign="top">
93
- <strong>边界明确</strong><br/><br/>
94
- 子 Agent 不能递归编排；未知工具、不可证明安全的 Replay、状态不明的 Worktree 一律 fail closed。
95
- </td>
96
- </tr>
97
- </table>
98
-
99
- ### 运行模型
102
+ ## 运行模型
100
103
 
101
104
  <p align="center">
102
105
  <picture>
103
- <source media="(max-width: 640px)" srcset="assets/readme-runtime-mobile.svg">
104
- <img src="assets/readme-runtime.svg" alt="OpenPI runtime model" width="100%" />
106
+ <source media="(max-width: 820px)" srcset="assets/readme-runtime-mobile.svg">
107
+ <img src="assets/readme-runtime.svg" alt="OpenPI runtime: one parent Pi session, three execution paths, continuity, and observability" width="100%" />
105
108
  </picture>
106
109
  </p>
107
110
 
108
- 主 Pi Session 始终拥有用户交互、配置和生命周期。后台 Terminal、Subagent 与 Workflow 是三条执行路径；Tasks、Goal、Session 和 Context Pivot 保持连续性；Footer、Dashboard、Artifacts 与清理逻辑负责可观察性。
111
+ 主 Pi Session 始终拥有用户交互、配置和生命周期。Terminal、Subagent 与 Workflow 是三条执行路径；Tasks、Goal、Session 和 Context Pivot 保持连续性；Footer、Dashboard、Artifacts 与清理逻辑负责观察和控制。
112
+
113
+ ### 一项任务应该去哪里？
114
+
115
+ ```text
116
+ 长期进程 → Background Terminal
117
+ 一项自包含、可继续对话的委派 → Subagent
118
+ 多阶段、依赖、fan-out 与综合 → Workflow
119
+ 跨回合工作项 → Tasks
120
+ 持续自主目标 → Goal
121
+ 同一 Session 的阶段切换 → Context Pivot
122
+ 真正跨顶层 Session → pi-intercom（可选）
123
+ ```
109
124
 
110
125
  ---
111
126
 
112
- ## 核心能力
127
+ ## 三条执行路径
113
128
 
114
- ### 1. 后台终端：长期进程不再阻塞 Agent
129
+ ### Background Terminal：长期进程不阻塞 Agent
115
130
 
116
131
  ```text
117
132
  bg_start({
@@ -121,15 +136,15 @@ bg_start({
121
136
  ```
122
137
 
123
138
  - stdout / stderr 独立捕获，完整日志有私有、有界的临时落盘；
124
- - `/ps` 查看状态与日志，`bg_kill` 终止整个进程树；
139
+ - `/ps` 查看状态，`bg_kill` 终止整个进程树；
125
140
  - 进程退出后自动通知，不需要轮询；
126
141
  - build、test、migration 可设置 `timeout_seconds`；
127
- - server 和 watcher 不设超时，用 `bg_watch` 等待 `Ready in|Traceback|ERROR` 一类字面签名；
128
- - 最多同时运行 8 个后台终端；Session 关闭或 Reload 时统一清理。
142
+ - server 和 watcher 不设超时，可用 `bg_watch` 等待 `Ready in|Traceback|ERROR`；
143
+ - 最多同时运行 8 个后台终端，Reload 或 Session Shutdown 时统一清理。
129
144
 
130
- 后台终端没有 stdin，因此不适合交互式程序。它适合 server、watch mode、长测试和流式构建。
145
+ 后台进程没有 stdin。需要交互输入的命令应由用户直接运行，而不是放进后台。
131
146
 
132
- ### 2. Pi-native Subagents：隔离 Context，而不是另起一套系统
147
+ ### Pi-native Subagent：隔离 Context，不另起系统
133
148
 
134
149
  ```text
135
150
  subagent_spawn({
@@ -141,28 +156,27 @@ subagent_spawn({
141
156
 
142
157
  每个 Subagent 都是新的进程内 Pi SDK Session：
143
158
 
144
- - 默认继承父会话的 Provider、模型和 Thinking Level；
145
- - 继承普通 child-safe 工具、Skills、项目说明与 Trust 决策，但不获得父级编排/交互工具；
146
- - 最多 4 个模型发起的 Subagent 并发运行；`/btw` 使用独立小池；
147
- - 结束后自动回传，可 `check`、`wait`、`cancel`；
148
- - `subagent_send` 可以继续指导运行中的 Agent，也能恢复刚结束的同一子会话；
149
- - 输入框下方展示实时摘要，空输入时按 `↓` 聚焦，`Enter` 或 `→` 打开管理界面。
159
+ - 默认继承父会话的 Provider、模型与 Thinking Level；
160
+ - 继承普通 child-safe 工具、Skills、项目说明与 Trust 决策；
161
+ - 最多 4 个模型发起的 Subagent 并发运行，结束后自动回传；
162
+ - 可 `check`、`wait`、`cancel`，也可用 `subagent_send` 继续同一子会话；
163
+ - 输入框下方显示实时摘要，空输入时按 `↓` 聚焦，`Enter` 或 `→` 打开管理界面。
150
164
 
151
- 内置角色由 harness 强制工具边界，不靠提示词自律：
165
+ 内置角色由 Harness 强制工具边界，不靠 Prompt 自律：
152
166
 
153
- | `agent_type` | 用途 | 默认 effort | 强制能力 |
154
- | ------------- | -------------- | ----------- | -------------------------------- |
155
- | `explorer` | 代码追踪与探索 | high | 只读发现工具 |
156
- | `implementer` | 聚焦实现 | high | read / bash / edit / write 等 |
157
- | `reviewer` | 正确性与回归审查 | medium | 只读发现工具 |
158
- | `advisor` | 深度技术建议 | xhigh | 只读发现工具 |
167
+ | `agent_type` | 适合 | 默认 effort | 强制能力 |
168
+ | ------------- | ---------------- | ----------- | ----------------------------- |
169
+ | `explorer` | 代码追踪与探索 | high | 只读发现工具 |
170
+ | `implementer` | 聚焦实现 | high | read / bash / edit / write 等 |
171
+ | `reviewer` | 正确性与回归审查 | medium | 只读发现工具 |
172
+ | `advisor` | 深度技术建议 | xhigh | 只读发现工具 |
159
173
 
160
- 角色可由全局 `~/.pi/agent/agents/*.md` 或受信任项目 `.pi/agents/*.md` 完整覆盖。精确格式、工具清单与优先级见 [`extensions/subagents/docs/agent-types.md`](https://github.com/tt-a1i/my-pi-setup/blob/main/extensions/subagents/docs/agent-types.md)。
174
+ 角色可由全局 `~/.pi/agent/agents/*.md` 或受信任项目 `.pi/agents/*.md` 覆盖。模型优先级是：显式调用 > Agent Type 文件 > `/openpi-setup` 角色模型 > 父模型继承。更高优先级定义损坏时会阻断 fallback，而不是悄悄退回更宽松的能力。
161
175
 
162
176
  <details>
163
177
  <summary><strong>并行写文件时如何隔离 Worktree？</strong></summary>
164
178
 
165
- 默认并行 Agent 共享 checkout 和 git index。只读 fan-out 不受影响；会写文件的并行任务应开启：
179
+ 默认并行 Agent 共享 checkout 与 git index。只读 fan-out 不受影响；并行写入应使用：
166
180
 
167
181
  ```text
168
182
  subagent_spawn({
@@ -172,353 +186,263 @@ subagent_spawn({
172
186
  })
173
187
  ```
174
188
 
175
- Worktree 建在 `.git/pi-worktrees/`，拥有独立 checkout 和分支。Direct Subagent 的 checkout 与它的可恢复 Session 同寿命。退役时，已提交工作删除 checkout、保留分支；dirty/untracked/ignored 文件、detached HEAD、Git 探测失败或超时则保留 checkout 路径。只有完整证明为空时才全部回收。
176
-
177
- 全新 checkout 不包含 `.env` 或其他 gitignored 内容。可用时会在 `.git/pi-worktrees/node_modules` 建立依赖 symlink，让 checkout 通过父目录解析依赖；Worktree 仍要求当前目录是 Git 仓库。
178
-
179
- </details>
180
-
181
- <details>
182
- <summary><strong>模型与 Agent Type 的优先级</strong></summary>
183
-
184
- 模型：显式调用 > Agent Type 文件 > `/my-pi-setup` 的角色模型 > 父模型继承。
185
-
186
- Effort：显式调用 > Agent Type 默认值 > 父会话。
189
+ Worktree 建在 `.git/pi-worktrees/`，拥有独立 checkout 与分支。已提交工作会删除 checkout、保留分支；dirty、untracked、ignored 文件，detached HEAD，Git 探测失败或超时都会保留现场。只有完整证明为空时才回收。
187
190
 
188
- 同名角色定义：内置 < 全局 < 受信任项目。更高优先级文件如果损坏，会阻断 fallback，而不是悄悄退回更宽松的定义。工具白名单只能收窄，也无法重新拿回父会话专属工具。
191
+ 全新 checkout 不包含 `.env` 或其他 gitignored 内容。可用时 OpenPI 会在 worktree 中建立 `node_modules` 依赖 symlink。
189
192
 
190
193
  </details>
191
194
 
192
- ### 3. Dynamic Workflows：让多 Agent 任务有阶段、有证据、有产物
195
+ ### Dynamic Workflow：让多 Agent 工作有阶段、有证据、有产物
193
196
 
194
- 单个 Subagent 负责一项自包含委派。Workflow 处理多阶段、有依赖、需要 fan-out 和综合的任务：
197
+ 单个 Subagent 负责一项委派。Workflow 处理阶段依赖、动态 fan-out、结构化结果、恢复与综合：
195
198
 
196
199
  ```js
197
200
  phase("Scan");
198
201
  const checked = await pipeline(
199
202
  files,
200
203
  (file) =>
201
- agent(`Trace ${file} for reliability risks with file:line evidence`, {
204
+ agent(`Trace ${file} for reliability risks`, {
202
205
  agent_type: "explorer",
203
206
  label: `scan:${file}`,
204
207
  schema: FINDING_SCHEMA,
205
208
  }),
206
209
  (scan, file) =>
207
210
  scan.ok
208
- ? agent(`Verify these findings in ${file}: ${scan.output}`, {
211
+ ? agent(`Verify findings in ${file}`, {
209
212
  agent_type: "reviewer",
210
213
  label: `verify:${file}`,
214
+ inputs: [scan.ref],
211
215
  })
212
216
  : null,
213
217
  );
214
218
 
215
219
  phase("Report");
216
- log(`${checked.filter(Boolean).length}/${checked.length} files verified`);
217
- return await agent(`Synthesize: ${JSON.stringify(checked)}`, {
220
+ const verified = checked.filter((result) => result?.ok);
221
+ log(`${verified.length}/${checked.length} files verified`);
222
+ return agent("Synthesize the verified findings", {
218
223
  agent_type: "advisor",
224
+ inputs: verified.map((result) => result.ref),
219
225
  });
220
226
  ```
221
227
 
222
- | 原语 | 作用 |
223
- | ------------ | -------------------------------------------------------------------- |
224
- | `phase()` | 标记当前阶段 |
225
- | `log()` | 向实时界面与最终报告追加一行进度 |
226
- | `usage()` | 读取累计 Token、缓存与成本的单调 lower bound；它不是预算限制器 |
227
- | `agent()` | 启动一个隔离 Pi Agent，可指定 role、schema、acceptance 或 worktree |
228
- | `pipeline()` | 每个 item 完成上一阶段后立即进入下一阶段；多阶段 fan-out 的默认选择 |
229
- | `parallel()` | 并发 barrier；只有下一阶段确实需要全部结果时使用 |
228
+ | 原语 | 作用 |
229
+ | ------------ | -------------------------------------------------------------------------- |
230
+ | `phase()` | 标记当前阶段 |
231
+ | `log()` | 向实时界面与最终报告追加一行进度 |
232
+ | `usage()` | 读取累计 Token、缓存与成本的单调 lower bound；不是预算器 |
233
+ | `agent()` | 启动 Pi Agent；支持 role、schema、acceptance、inputs、operator 与 worktree |
234
+ | `pipeline()` | 每个 item 完成上阶段后立即进入下一阶段；多阶段 fan-out 的默认选择 |
235
+ | `parallel()` | 并发 barrier；只在下一阶段确实需要全部结果时使用 |
230
236
 
231
- Workflow 默认并发 8 个 Agent、单次最多 128 次调用；可分别配置到 64 和 1024。Workflow DSL 不暴露文件、网络或进程 API；Sandbox 进程只保留启动所需的包目录读取权限。`usage()` 在 Agent 压缩 Context 后可能低估实际总量，只适合观察趋势。前台运行可实时查看，后台运行完成后自动回传；`/workflows` 检查阶段、Agent、Transcript、用量与产物，`workflow_stop` 或 Dashboard 中的 `x` 可以取消。
232
-
233
- <details>
234
- <summary><strong>Replay、Acceptance Ledger 与隔离写入</strong></summary>
235
-
236
- `resume_from_run_id` 只 Replay 能被完整证明为只读且上下文未变的调用。指纹覆盖 prompt、schema、model/provider/effort、规范化 cwd、仓库状态、已加载资源和 Trust。下列调用一定真实执行：
237
-
238
- - 无 Agent Type 或工具范围无限制；
239
- - 带 `bash`、`edit`、`write` 或未知自定义工具；
240
- - 使用 `isolation: "worktree"`；
241
- - 存在会影响结果但无法纳入指纹的 ignored 文件；
242
- - 旧 journal、指纹失败，或与不可缓存调用发生不安全重叠。
237
+ Workflow 默认并发 8 个 Agent，单次最多 128 次调用；可配置到 64 和 1024。前台运行可实时查看，后台运行完成后自动回传；`/workflows` 展示阶段、Agent、Transcript、Graph、用量与产物。
243
238
 
244
- 匹配依据是调用内容，不是调用序号，因此 `pipeline()` 的并发完成顺序变化不会把 A 的结果错配给 B。失败调用从不缓存。Journal 上限 2MB，超出后丢弃最旧条目并显式报告。
239
+ ---
245
240
 
246
- 可选 `acceptance: { criteria: [...] }` 要求同一个 Agent 返回 evidence ledger。条件缺失、格式错误或被拒绝时，该调用 `ok: false`，但原始输出与 ledger 仍保留；不会暗中再启动 reviewer 或 shell。
241
+ ## Workflow 不只是并行
247
242
 
248
- 并行写入使用 `isolation: "worktree"`。Workflow 在清理 checkout 前原子保存有界 handoff manifest，包括 tracked binary patch、stat、branch/HEAD、untracked/ignored 清单和 cleanup receipt。状态不明时保留，不自动 merge、apply 或强删。
243
+ OpenPI 把一次调用拆成可以审计的生命周期，而不是把“进程退出 0”当成业务成功。
249
244
 
250
- </details>
245
+ ### Result Handoff 与派生 Graph
251
246
 
252
- ---
247
+ 成功调用返回同一 Run 内有效的 opaque `ref`。后续调用通过 `inputs: [previous.ref]` 显式接收上游结论；每个结论最多 16 KiB，合计最多 48 KiB，并标记为不可信数据。Artifacts 从这些引用派生只读 Graph，用来观察 lineage，不参与调度。
253
248
 
254
- ## 连续性与交互
255
-
256
- <table>
257
- <tr>
258
- <td width="50%" valign="top">
259
- <strong>Session Tasks</strong><br/><br/>
260
- <code>tasks_add / tasks_update / tasks_list</code><br/>
261
- 跨 Agent Run 和用户回合记录当前批次的工作意图。稳定 ID、可审计状态、Session 分支恢复；全部完成后关闭批次，下批从 T1 重新开始。Tasks 不执行工作。
262
- </td>
263
- <td width="50%" valign="top">
264
- <strong>Session Goal</strong><br/><br/>
265
- <code>/goal &lt;目标&gt;</code><br/>
266
- Codex 风格的持久自主目标。支持 pause、resume、edit、clear 和可选 Token budget；系统规则要求模型先完成证据审计再声明 complete，工具本身只记录声明。
267
- </td>
268
- </tr>
269
- <tr>
270
- <td width="50%" valign="top">
271
- <strong>Context Pivot</strong><br/><br/>
272
- <code>/context-pivot &lt;下一阶段&gt;</code><br/>
273
- Context 超过约 30K Tokens 且任务切换阶段时，用自包含 Brief 替换旧阶段噪音，在同一 Session 继续。普通超长对话仍用 Pi 原生 <code>/compact</code>。
274
- </td>
275
- <td width="50%" valign="top">
276
- <strong>Session Browser</strong><br/><br/>
277
- <code>/sessions</code><br/>
278
- 按名称、首条消息、Session ID 和目录搜索；预览 User、Assistant、Tool 与 Summary；通过 Pi 安全生命周期切换。
279
- </td>
280
- </tr>
281
- <tr>
282
- <td width="50%" valign="top">
283
- <strong>Reviewed Human Input</strong><br/><br/>
284
- <code>ask_user</code> · <code>human_handoff</code><br/>
285
- <code>ask_user</code> 在 TUI/RPC 中收集 1–3 个结构化决策，支持 Notes、预览、草稿修改与提交前复核；空白自由输入会要求模型重写或拆分问题。只有用户能完成的登录、授权或硬件操作才使用 parent-only handoff，Done 后仍须验证完成信号。
286
- </td>
287
- <td width="50%" valign="top">
288
- <strong>Next-action Suggestion</strong><br/><br/>
289
- 完整主 Agent Run 结束后，可在空编辑器首行显示一条暗色 inline 建议。行尾为中文 IME 预留预编辑区域，避免拼音覆盖建议；<code>Right</code> 只填入、不提交，其他输入取消。默认关闭且不写入 Session 或模型 Context。
290
- </td>
291
- </tr>
292
- </table>
293
-
294
- ### Tasks 与 Goal 怎么分工
295
-
296
- - Tasks 是多个工作项的咨询性记录，不调度、不委派，也不参与 Goal 完成判定；
297
- - Goal 是一个持续到终态的自主目标，模型只能提交 `complete` 或经过连续审计的 `blocked`；
298
- - Subagent 与 Workflow 才执行工作；文件、Git、测试、Artifacts 和用户确认仍是事实来源。
299
-
300
- ### Plan Mode、Cron 与 Post-edit
301
-
302
- - `/plan [目标]` 先做只读调研；模型以 `plan_ready` 显式提交完整计划后，`/plan` 才提供继续规划、当前 Session 实施或 Fresh Session 实施。两个实施入口都只填入可编辑 Prompt，不自动提交；Planning/Ready 状态按 Session branch 持久化并在 Reload、Resume、Tree navigation 后恢复；Plan Mode 使用严格命令白名单，不尝试“理解”任意 Shell 是否只读；
303
- - `/cron ...` 在当前 Session 中排定一次或周期性提示词；
304
- - Post-edit 可在成功 Write/Edit 的 Turn 后运行一条用户配置的命令，例如 `npm run format`。默认关闭，最多 500 字符，不猜测 Bash 是否改过文件。
249
+ ### Invocation Ledger
305
250
 
306
- ---
251
+ 每次 `agent()` 独立记录 intent、admission 与 execution 状态。崩溃后仍未终结的调用恢复为 `uncertain`，不会猜成成功、失败或安全重试。这不是跨重启 exactly-once，也不伪装成 exactly-once。
307
252
 
308
- ## 终端体验
253
+ ### Safe Replay
309
254
 
310
- ### 一行 Footer，持续显示真实状态
255
+ `resume_from_run_id` 只 Replay 在 OpenPI 可观测边界内能证明为只读、且指纹未变的调用。指纹覆盖 prompt、schema、model/provider/effort、规范化 cwd、仓库状态、已加载资源与 Trust；外部进程造成但未进入这些观测面的变化不在保证范围内。
311
256
 
312
- 默认 Powerline Footer：
257
+ 以下调用一定真实执行：
313
258
 
314
- ```text
315
- cwd model thinking context cache cost throughput git PR
316
- ```
259
+ - 无 Agent Type，或工具范围无限制；
260
+ - 带 `bash`、`edit`、`write` 或未知自定义工具；
261
+ - 使用 per-call Worktree；
262
+ - ignored 文件可能影响结果却无法纳入指纹；
263
+ - Journal、资源、路径、并发重叠或指纹状态不确定。
317
264
 
318
- 支持 `powerline`、`powerline-mono` 与 `compact` 三个 preset，也可用 `footerLines` 自定义多行布局。终端变窄时按优先级隐藏次要指标，而不是机械截断尾部。
265
+ 匹配依据是调用内容，不是并发完成顺序。失败调用不缓存；Journal 有 2 MiB 上限。
319
266
 
320
- | 指标 | 内容 |
321
- | ------------ | ---------------------------------------- |
322
- | `cwd` | 当前目录 |
323
- | `model` | Provider / Model |
324
- | `thinking` | Thinking 档位 |
325
- | `context` | Context 占用与容量；占用未知时只显示容量 |
326
- | `cache` | Session 报告的 Prompt Cache 命中率 |
327
- | `cost` | Session 累计成本 |
328
- | `throughput` | 当前流式运行的估算 Token 速度 |
329
- | `git` / `pr` | 当前分支与对应 PR |
330
- | `flex` | 同一行左右对齐的分隔点 |
267
+ ### Operator Continuity
331
268
 
332
- Subagent 与 Workflow 状态属于 Footer 的基础可观察性：活动时自动出现，空闲时不占空间。后台终端使用编辑器上方状态条和 `/ps`，不混进 Footer。本地 Git 状态自动刷新；GitHub PR 查询只有用户显式运行 `/pr` 时才会发起。Nerd Font 只改善 Powerline 分隔符 ``，不是硬依赖。
269
+ `operator: "name"` 在同一 Run 内复用一个内存 Child Session，并把同名 activation 串行化。首个 activation 固定 model、role/tool surface、effort、structured mode 与 cwd。Operator 不与 per-call Worktree 或 Replay 混用，也不承诺跨重启持久记忆。
333
270
 
334
- ### 输出密度按内容类型独立控制
271
+ ### Explicit Acceptance
335
272
 
336
- - Subagent 结果默认完整显示；
337
- - Bash 默认折叠为单行命令、有限输出与最终状态；
338
- - Write/Edit 默认最多显示三行渲染内容；
339
- - 三类结果都能在 `/my-pi-setup` 中独立切换 `full` / `compact`；
340
- - 折叠内容用 Pi 当前的 `app.tools.expand` 快捷键临时展开，默认是 `Ctrl+O`。
273
+ 可选 `acceptance: { criteria: [...] }` 要求同一个 Agent 返回 evidence ledger。条件缺失、格式错误或被拒绝时，调用返回 `ok: false`，但原始输出与 ledger 仍保留。OpenPI 不会暗中再启动 reviewer、Shell 或额外 Judge 模型。
341
274
 
342
- ### 文件搜索是一等工具
275
+ ### Worktree Handoff
343
276
 
344
- `fd` 与 `rg` 使用结构化参数，不拼接 Shell；默认遵守 `.gitignore`，支持 Glob、类型、Smart Case、固定字符串和上下文。结果限制为 50KB / 2000 行；不超过 10 MiB 的完整截断内容保存在 Session 临时文件中并于 Shutdown 时清理，超过该上限时搜索会终止且部分临时文件会立即删除。
277
+ Workflow 在清理隔离 checkout 前原子保存有界 Handoff Manifest：tracked binary patch、stat、branch/HEAD、untracked/ignored 清单与 cleanup receipt。状态不明就保留现场，不自动 merge、apply 或强删。
345
278
 
346
- macOS/Linux 的 arm64 与 x64 环境缺少二进制时，会通过 HTTPS 下载固定官方版本、校验 SHA-256 后原子安装。其他架构和平台需自行提供 `fd` 与 `rg`。
279
+ 设计细节见 [`docs/design/WORKFLOW_INVOCATION_GRAPH.md`](docs/design/WORKFLOW_INVOCATION_GRAPH.md)。
347
280
 
348
281
  ---
349
282
 
350
- ## 安全边界
283
+ ## 连续工作，而不是堆 Context
351
284
 
352
- 这里的安全不是一段 Prompt，而是运行时约束。
285
+ | 能力 | 使用方式 | 它负责什么 |
286
+ | ------------- | --------------------------------------- | ------------------------------------------------------------------- |
287
+ | Tasks | `tasks_add` / `tasks_update` / `/tasks` | 跨 Agent Run 与用户回合记录当前批次工作意图；不执行工作 |
288
+ | Goal | `/goal <目标>` | 驱动一个持续到终态的自主目标；完成前要求证据审计 |
289
+ | Plan Mode | `/plan [目标]` | 只读调研；`plan_ready` 后才准备可编辑的实施 Prompt，不自动执行 |
290
+ | Context Pivot | `/context-pivot <下一阶段>` | Context 超过约 30K Tokens 且任务换阶段时，用自包含 Brief 替换旧噪音 |
291
+ | Sessions | `/sessions` | 搜索、预览并通过 Pi 安全生命周期切换 Session |
292
+ | Human Input | `ask_user` / `human_handoff` | 收集经复核的决策，或等待只有用户能完成的外部操作 |
353
293
 
354
- | 边界 | 行为 |
355
- | ------------------------ | -------------------------------------------------------------------- |
356
- | 子 Agent 递归编排 | 禁止。Subagent/Workflow child 不获得 `subagent_*`、`workflow` 等父级工具 |
357
- | Agent Type 工具 | Harness 强制白名单；声明不能突破父级 denylist |
358
- | 类型与工具预检 | 未知、损坏、错名或最终未注册的工具在首个 Token 前失败 |
359
- | Workflow Sandbox | DSL 无文件、网络、进程、import、eval 或 timer API；进程仅可读启动包目录 |
360
- | Replay | 只有可证明只读、上下文指纹完整且无不安全重叠的调用才缓存 |
361
- | Worktree 清理 | 未知即保留；Git 状态、handoff 或超时不确定时绝不删除 |
362
- | 终端输出 | 控制字符、方向格式符与超长内容在 ingress/render 边界清洗和限长 |
363
- | Shutdown | Terminal、Subagent、Workflow 都做有界取消、清理与唯一终态 |
364
- | 用户配置 | 一个受限 typed tool 写入；没有散落的扩展私有入口 |
365
- | 模型消费 | Suggestion 默认关闭；Subagent/Workflow 只在任务显式触发时运行 |
366
-
367
- 可选的 [pi-intercom](https://github.com/nicobailon/pi-intercom) 只在顶层 Pi Session 加载。它依赖进程级身份，而 Direct/Workflow child 是同一进程内的并发 Session；为避免身份串线，child Resource Loader 会移除 pi-intercom 的扩展与 Skill。
294
+ Tasks 是咨询性记录，Goal 是持续目标，Subagent 与 Workflow 才执行工作。文件、Git、测试、Artifacts 和用户确认始终是事实来源。
295
+
296
+ Next-action Suggestion 是可选的：完整主 Agent Run 结束后，在空编辑器显示一条暗色 inline 建议；`Right` 只填入、不提交，其他输入取消。它默认关闭，不写入 Session，也不进入模型 Context。
368
297
 
369
298
  ---
370
299
 
371
- ## 统一配置
300
+ ## 终端体验
372
301
 
373
- 本包只有一个用户配置入口：
302
+ 默认 Powerline Footer 把真实运行状态压进一行：
374
303
 
375
304
  ```text
376
- /my-pi-setup
305
+ cwd model thinking context cache cost throughput git PR
377
306
  ```
378
307
 
379
- 无参数时，当前模型先解释已有设置与影响，再引导修改。直接跟自然语言则只改指定项：
308
+ - 支持 `powerline`、`powerline-mono`、`compact`，也支持自定义多行布局；
309
+ - 终端变窄时按优先级隐藏次要指标，不机械截断尾部；
310
+ - Subagent 与 Workflow 活动时自动出现，空闲时不占空间；
311
+ - Bash、Write/Edit 与 Subagent 结果可独立选择 `full` 或 `compact`；
312
+ - 折叠内容用 Pi 的 `app.tools.expand` 快捷键临时展开，默认 `Ctrl+O`；
313
+ - Git 状态本地刷新；只有显式运行 `/pr` 才查询 GitHub PR。
380
314
 
381
- ```text
382
- /my-pi-setup 开启下一步预测，选择当前 Registry 里的轻量模型，minimal 推理
383
- /my-pi-setup workflow 同时跑 16 个 agent，总调用最多 256
384
- /my-pi-setup Footer 两行：cwd flex model / context cost flex git
385
- /my-pi-setup Footer 用 mono powerline
386
- /my-pi-setup Bash 展开，Write/Edit 保持紧凑
387
- /my-pi-setup 编辑后自动跑 npm run format
388
- /my-pi-setup 给 explorer 指定模型，让 reviewer 继承父模型
389
- ```
315
+ `fd` 与 `rg` 是结构化模型工具，不拼接 Shell。它们默认遵守 `.gitignore`，支持 Glob、类型、Smart Case、固定字符串与上下文；输出限制为 50 KiB / 2000 行，完整截断内容最多私有保存 10 MiB，并在 Session Shutdown 时清理。
390
316
 
391
- 配置保存在 `~/.pi/agent/my-pi-setup.json`，与包代码分离。升级不会覆盖。
317
+ macOS/Linux arm64 与 x64 缺少二进制时，OpenPI 会从官方 Release 下载固定版本、校验 SHA-256 后原子安装。其他平台需自行提供 `fd` 与 `rg`。
392
318
 
393
- ### 默认值
319
+ ---
394
320
 
395
- | 配置 | 默认值 |
396
- | ------------------------ | ------------------------------------------------------------ |
397
- | Next-action suggestion | 关闭；启用时必须显式选择 Registry 中可用的模型与 reasoning |
398
- | Workflow 并发 | 8，硬上限 64 |
399
- | Workflow 总 Agent 调用 | 128，硬上限 1024 |
400
- | 大型 Header | 关闭 |
401
- | Dashboard Footer | 开启；单行 `powerline` |
402
- | Subagent 结果 | `full` |
403
- | Bash 输出 | `compact` |
404
- | Write/Edit 输出 | `compact` |
405
- | Post-edit 命令 | 关闭；单条命令最多 500 字符 |
406
- | 内置角色模型 | `explorer / implementer / reviewer / advisor` 均继承父模型 |
407
- | 主题 | 保留用户现有选择 |
321
+ ## 安全边界
408
322
 
409
- 任何新增的模型、开关、权限、并发或 UI 偏好都必须接入 `/my-pi-setup`。仓库的 [`AGENTS.md`](https://github.com/tt-a1i/my-pi-setup/blob/main/AGENTS.md) 用测试守住这份单一入口契约。
323
+ 这里的安全不是一段 Prompt，而是运行时约束。
324
+
325
+ | 边界 | 行为 |
326
+ | ---------------- | ------------------------------------------------------------------------- |
327
+ | Child 递归编排 | 禁止；Subagent / Workflow child 不获得父级编排、交互与状态工具 |
328
+ | Agent Type 工具 | Harness 强制白名单；声明不能突破父级 denylist |
329
+ | 类型与工具预检 | 未知、损坏、错名或最终未注册的工具在首个 Token 前失败 |
330
+ | Workflow Sandbox | 无文件、网络、进程、import、eval 或 timer API；进程仅可读启动包目录 |
331
+ | Replay | 只有可证明只读、指纹完整且无不安全重叠的调用才缓存 |
332
+ | Worktree 清理 | 未知即保留；Git、Handoff 或超时状态不确定时绝不删除 |
333
+ | 终端输出 | 控制字符、方向格式符与超长内容在 ingress / render 边界清洗、限长 |
334
+ | Shutdown | Terminal、Subagent、Workflow 都有有界取消、清理与唯一终态 |
335
+ | 用户配置 | 单一受限 typed tool 写入；不散落扩展私有配置入口 |
336
+ | 模型消费 | Suggestion 默认关闭；Subagent / Workflow 只在工具调用或用户 `/btw` 后运行 |
337
+
338
+ 可选的 [pi-intercom](https://github.com/nicobailon/pi-intercom) 只在顶层 Pi Session 加载。它使用进程级身份，而 OpenPI Child 是同一进程内的并发 Session；Child Resource Loader 会移除 pi-intercom 扩展与 Skill，避免身份串线。Replay 也不会复用其调用。
410
339
 
411
340
  ---
412
341
 
413
- ## 安装与可选集成
342
+ ## 配置与参考
414
343
 
415
- ### 要求
344
+ ### 一个配置入口
416
345
 
417
- - Pi `0.84.1` 或更新版本；
418
- - Node.js 22.19.0 或更新版本；
419
- - macOS/Linux 的 arm64 或 x64 可自动安装 `fd` / `rg`；其他架构和平台需自行安装。
346
+ ```text
347
+ /openpi-setup
348
+ /my-pi-setup # legacy alias
349
+ ```
420
350
 
421
- ### Pi Package
351
+ 无参数时，OpenPI 展示当前状态并引导修改；带自然语言时只改指定项：
422
352
 
423
- ```bash
424
- pi install npm:@tt-a1i/openpi
353
+ ```text
354
+ /openpi-setup 开启下一步预测，选择 Registry 里的轻量模型，minimal 推理
355
+ /openpi-setup workflow 同时跑 16 个 agent，总调用最多 256
356
+ /openpi-setup Footer 两行：cwd flex model / context cost flex git
357
+ /openpi-setup Bash 展开，Write/Edit 保持紧凑
358
+ /openpi-setup 编辑后自动跑 npm run format
359
+ /openpi-setup 给 explorer 指定模型，让 reviewer 继承父模型
425
360
  ```
426
361
 
427
- 需要直接审计当前源码时，也可以从 GitHub 安装：
362
+ 配置保存在 `~/.pi/agent/my-pi-setup.json`，与包代码分离，升级不会覆盖。
428
363
 
429
- ```bash
430
- pi install git:github.com/tt-a1i/my-pi-setup
431
- ```
364
+ <details>
365
+ <summary><strong>默认值</strong></summary>
366
+
367
+ | 配置 | 默认值 |
368
+ | ---------------------------- | ---------------------------------------------- |
369
+ | Next-action Suggestion | 关闭；启用时显式选择 Registry 模型与 reasoning |
370
+ | Workflow 并发 / 总调用 | 8 / 128；硬上限 64 / 1024 |
371
+ | 大型 Header | 关闭 |
372
+ | Dashboard Footer | 开启；单行 `powerline` |
373
+ | Subagent / Bash / Write/Edit | `full` / `compact` / `compact` |
374
+ | Post-edit 命令 | 关闭；单条命令最多 500 字符 |
375
+ | 内置角色模型 | 全部继承父模型 |
376
+ | pi-intercom | 不静默安装；由用户明确选择 |
377
+ | 主题 | 保留用户现有选择 |
432
378
 
433
- 开发本仓库时可以安装本地 checkout：
379
+ </details>
434
380
 
435
- ```bash
436
- git clone https://github.com/tt-a1i/my-pi-setup.git ~/work/my-pi-setup
437
- cd ~/work/my-pi-setup
438
- npm install
439
- pi install ~/work/my-pi-setup
440
- ```
381
+ ### 安装要求与来源
441
382
 
442
- 安装或更新后重启 Pi，或运行 `/reload`。Pi 提供的 `pi-ai`、`pi-coding-agent`、`pi-tui` 和 `typebox` 按官方 Package 契约声明为 Peer Dependencies；仓库中的开发依赖仅用于本地检查，不随包重复提供 Host SDK。
383
+ - Pi `0.84.1` 或更新版本；
384
+ - Node.js `22.19.0` 或更新版本；
385
+ - npm 安装：`pi install npm:@tt-a1i/openpi`；
386
+ - GitHub 安装：`pi install git:github.com/tt-a1i/openpi`。
443
387
 
444
- ### 可选：多个顶层 Pi Session 通信
388
+ 开发当前源码：
445
389
 
446
390
  ```bash
447
- pi install npm:pi-intercom
391
+ git clone https://github.com/tt-a1i/openpi.git ~/work/openpi
392
+ cd ~/work/openpi
393
+ npm install
394
+ pi install ~/work/openpi
448
395
  ```
449
396
 
450
- pi-intercom 通过本地 IPC 传递消息；传输本身不调用模型。快捷键、命令与 `inboundTrigger` 配置以当前安装版本的文档为准。
451
-
452
- 本包只保证一件事：pi-intercom 留在顶层 Session，child 不加载它。跨顶层 Session 用 pi-intercom；父子委派继续使用 `subagent_*` 和 Workflow 原生结果通道。
397
+ 安装或更新后重启 Pi，或运行 `/reload`。Host SDK 与 TypeBox 按 Pi Package 契约声明为 Peer Dependencies；仓库开发依赖不随包重复提供。
453
398
 
454
- ### 可选：GitHub Dark 主题
399
+ ### 可选：顶层 Pi Session 通信
455
400
 
456
- 安装包会注册主题，但不会自动切换。通过 Pi `/settings` 选择 `github-dark-default`，或配置：
401
+ 运行 `/openpi-setup`，在原生确认框中选择安装；也可手动执行：
457
402
 
458
- ```json
459
- {
460
- "theme": "github-dark-default"
461
- }
403
+ ```bash
404
+ pi install npm:pi-intercom
462
405
  ```
463
406
 
464
- ---
407
+ 新私有配置默认 `confirmSend: true`、`inboundTrigger: "replies"`；已有配置绝不重写。安装失败不显示成功，也不写配置；安装后需 `/reload`。跨顶层 Session 用 pi-intercom，父子委派继续使用 `subagent_*` 与 Workflow 原生结果通道。
408
+
409
+ ### 命令速查
465
410
 
466
- ## 命令速查
467
-
468
- | 命令 | 作用 |
469
- | --------------------------- | --------------------------------------------------------------- |
470
- | `/my-pi-setup [自然语言]` | 查看或修改本包配置 |
471
- | `/ps` | 查看、跟踪和终止后台终端 |
472
- | `/subagents` | 查看、取消或接管子 Agent |
473
- | `/btw` | 在旁路 Pi Context 中提问，不打断主任务 |
474
- | `/workflows` | 查看阶段、Agent 与产物；`/workflows <id> stop` 取消运行 |
475
- | `/tasks` | 查看当前 Session 的工作项 |
476
- | `/goal ...` | 创建、查看、编辑、暂停或恢复持久 Goal |
477
- | `/context-pivot <下一阶段>` | 在同一 Session 中压缩旧阶段并继续 |
478
- | `/sessions` | 搜索、预览并切换 Session |
479
- | `/plan [目标]` | 只读调研，进入 Plan Ready 后显式选择实施方式 |
480
- | `/cron ...` | 为当前 Session 安排定时或周期性 Prompt |
481
- | `/lg` / `/pr` | 浏览 Working Tree Diff / 刷新当前分支 PR |
482
- | `/copy-all` | 复制当前分支可见的 User / Assistant 对话 |
411
+ | 命令 | 作用 |
412
+ | -------------------------- | ---------------------------------------------- |
413
+ | `/openpi-setup [自然语言]` | 查看或修改统一配置；可选择安装 pi-intercom |
414
+ | `/ps` | 查看、跟踪与终止后台终端 |
415
+ | `/subagents` / `/btw` | 管理 Subagent / 在旁路 Context 中提问；仅 TUI |
416
+ | `/workflows` | 查看阶段、Agent、Graph 与产物；可停止运行 |
417
+ | `/tasks` / `/goal ...` | 查看工作项 / 管理持续目标 |
418
+ | `/context-pivot <阶段>` | 在同一 Session 中压缩旧阶段并继续 |
419
+ | `/sessions` | 搜索、预览与切换 Session |
420
+ | `/plan [目标]` | 只读调研；Plan Ready 后显式选择实施方式 |
421
+ | `/cron ...` | 为当前 Session 安排一次或周期性 Prompt |
422
+ | `/lg` / `/pr` | 浏览 Diff（`/lg` 仅 TUI）/ 显式刷新当前分支 PR |
423
+ | `/copy-all` | 复制当前分支可见对话 |
483
424
 
484
425
  <details>
485
426
  <summary><strong>模型工具速查</strong></summary>
486
427
 
487
- | 工具 | 用途 |
488
- | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
489
- | `bg_start`, `bg_status`, `bg_list`, `bg_watch`, `bg_kill` | 后台进程生命周期 |
490
- | `subagent_spawn`, `subagent_check`, `subagent_list`, `subagent_wait`, `subagent_send`, `subagent_cancel` | 独立子 Agent |
491
- | `workflow`, `workflow_status`, `workflow_stop` | 动态多阶段编排与运行管理 |
492
- | `tasks_add`, `tasks_update`, `tasks_list` | Session 工作项 |
493
- | `get_goal`, `create_goal`, `update_goal` | Session Goal |
494
- | `context_pivot` | Context 阶段切换 |
495
- | `ask_user` | TUI/RPC 中带草稿与提交前复核的结构化用户决策 |
496
- | `human_handoff` | 等待用户专属操作并返回待验证的状态 |
497
- | `plan_ready` | 显式完成计划，不自动开始实施 |
498
- | `fd`, `rg` | 文件发现与内容搜索 |
499
- | `configure_my_pi_setup` | 受限配置写入 |
428
+ | 工具 | 用途 |
429
+ | -------------------------------------------------------------------------------------------------------- | ------------------------------ |
430
+ | `bg_start`, `bg_status`, `bg_list`, `bg_watch`, `bg_kill` | 后台进程生命周期 |
431
+ | `subagent_spawn`, `subagent_check`, `subagent_list`, `subagent_wait`, `subagent_send`, `subagent_cancel` | 独立子 Agent |
432
+ | `workflow`, `workflow_status`, `workflow_stop` | 动态多阶段编排与运行管理 |
433
+ | `tasks_add`, `tasks_update`, `tasks_list` | Session 工作项 |
434
+ | `get_goal`, `create_goal`, `update_goal` | Session Goal |
435
+ | `context_pivot` | Context 阶段切换 |
436
+ | `ask_user`, `human_handoff` | 经复核的用户决策与用户专属操作 |
437
+ | `plan_ready` | 显式完成计划，不自动开始实施 |
438
+ | `fd`, `rg` | 文件发现与内容搜索 |
439
+ | `configure_my_pi_setup` | 受限配置写入 |
500
440
 
501
441
  </details>
502
442
 
503
- ---
504
-
505
- ## 设计原则
506
-
507
- ### Pi-native first
508
-
509
- 子 Agent 是 Pi SDK Session，不是独立 CLI。Provider、模型、Skills、Trust 与普通 child-safe 工具沿用用户已有环境；编排、交互和父级状态工具明确移除。
510
-
511
- ### Context 有明确去向
512
-
513
- 一项委派交给 Subagent；多阶段依赖交给 Workflow；阶段变化用 Context Pivot；真正跨 Session 用 Handoff；下一步建议只停留在编辑器 UI。
514
-
515
- ### 后台能力必须可见，也必须能停
516
-
517
- Terminal、Subagent、Workflow 都有 ID、状态、检查入口、取消路径、有界 Shutdown 和一次性完成通知。无界后台工作不属于“方便”，只是把问题藏起来。
443
+ ### 可选主题
518
444
 
519
- ### 少猜一次，多拒绝一次
520
-
521
- 不可证明只读就不 Replay，不能确认干净就不删 Worktree，损坏的高优先级角色定义不 fallback。拒绝会留下可见错误；猜错可能留下错误代码、旧结果或丢失数据。
445
+ 包内注册 `github-dark-default`，但不自动切换。通过 Pi `/settings` 选择即可。
522
446
 
523
447
  ---
524
448
 
@@ -527,117 +451,84 @@ Terminal、Subagent、Workflow 都有 ID、状态、检查入口、取消路径
527
451
  <details>
528
452
  <summary><strong>安装后会自动调用额外模型吗？</strong></summary>
529
453
 
530
- 不会。Next-action suggestion 默认关闭；只有用户通过 `/my-pi-setup` 显式选择模型后，完整主 Agent Run 结束时才可能增加一次小型预测调用。Subagent 与 Workflow 也只在任务实际触发时运行。
454
+ 不会。Suggestion 默认关闭；只有用户显式选择模型后，完整主 Agent Run 结束时才可能增加一次小型预测调用。Subagent 与 Workflow 也只在任务实际触发时运行。
531
455
 
532
456
  </details>
533
457
 
534
458
  <details>
535
- <summary><strong>Pi Subagent 会阻塞主 Agent 吗？</strong></summary>
459
+ <summary><strong>Subagent 会阻塞主 Agent 吗？</strong></summary>
536
460
 
537
- 不会。`subagent_spawn` 立即返回，结束后自动回传。只有显式调用 `subagent_wait` 才会等待；它只适合下一步确实依赖结果的场景。
461
+ `subagent_spawn` 立即返回，结束后自动回传。只有显式调用 `subagent_wait` 才会等待；它只适合下一步确实依赖结果的场景。
538
462
 
539
463
  </details>
540
464
 
541
465
  <details>
542
466
  <summary><strong>为什么同时提供 Subagent 和 Workflow？</strong></summary>
543
467
 
544
- Subagent 是一项可继续对话的自包含委派；Workflow 是多阶段编排，强调 fan-out、结构化结果、可恢复执行和持久产物。前者可以接管继续，后者更适合自动化流水线。
545
-
546
- </details>
547
-
548
- <details>
549
- <summary><strong>Plan Mode 下为什么 `git log` 能运行，`npm install` 不能？</strong></summary>
550
-
551
- Plan Mode 不分析“任意 Shell 是否只读”，而只放行由已知安全零件组成的命令。它允许窄白名单中的 `git` / `gh` 查询形式；Shell 元字符、未知 flag、安装、写入和无法证明的形式全部拒绝。这里的方向是单向的：放行意味着已证明只读，拒绝只表示未能证明。
552
-
553
- Plan Mode 仍可启动只读 Subagent，但会把工具收窄到发现工具；`subagent_send` 和 Workflow 会被拦截，因为它们可能恢复或创建拥有写权限的执行路径。
468
+ Subagent 是一项可继续对话的自包含委派；Workflow 是多阶段编排，强调 fan-out、结构化结果、恢复、验收与持久产物。前者可以接管继续，后者更适合自动化流水线。
554
469
 
555
470
  </details>
556
471
 
557
472
  <details>
558
- <summary><strong>配置和升级会互相覆盖吗？</strong></summary>
473
+ <summary><strong>Plan Mode 为什么允许 git log，却拒绝 npm install？</strong></summary>
559
474
 
560
- 不会。包代码、Pi 自己的模型认证与 `~/.pi/agent/my-pi-setup.json` 相互分离。更新仓库不会重写用户配置。
475
+ Plan Mode 不猜“任意 Shell 是否只读”，只放行由已知安全零件组成的命令。窄白名单内的 Git / GitHub 查询可以通过；Shell 元字符、未知 flag、安装、写入和无法证明的形式全部拒绝。
561
476
 
562
477
  </details>
563
478
 
564
479
  <details>
565
480
  <summary><strong>后台服务会不会变成孤儿进程？</strong></summary>
566
481
 
567
- 正常的 `/new`、`/resume`、`/fork`、`/reload` 和退出都会触发 Session Shutdown。扩展会终止后台进程树并清理临时日志；也可随时用 `bg_kill` 或 `/ps` 手动管理。
482
+ 正常的 `/new`、`/resume`、`/fork`、`/reload` 与退出都会触发 Session Shutdown。扩展会终止后台进程树并清理临时日志；也可随时用 `bg_kill` 或 `/ps` 管理。
568
483
 
569
484
  </details>
570
485
 
571
486
  <details>
572
487
  <summary><strong>这是稳定 API 吗？</strong></summary>
573
488
 
574
- 这是持续实际使用的独立发行版，不承诺扩展 API 永远不变。改动会经过 TypeScript、格式检查和专项测试；Pi 上游变化时，优先保持 Session 生命周期、工具边界、结果去重和资源清理这些行为不变量。
489
+ 这是持续实际使用的独立发行版，不承诺扩展 API 永远不变。改动会经过 TypeScript、格式检查与专项测试；Pi 上游变化时，优先保持 Session 生命周期、工具边界、结果去重与资源清理这些行为不变量。
575
490
 
576
491
  </details>
577
492
 
578
493
  ---
579
494
 
580
- ## 仓库结构
495
+ ## 仓库结构与开发
581
496
 
582
497
  ```text
583
498
  extensions/
584
- ├── setup/ # /my-pi-setup 与受限配置工具
499
+ ├── setup/ # /openpi-setup 与受限配置工具
585
500
  ├── background-terminals/ # 长进程、日志、/ps
586
501
  ├── subagents/ # Pi-native Backend、角色、/subagents
587
- ├── workflows/ # DSL、Runner、Sandbox、Replay、Artifacts
588
- ├── tasks/ # Session 工作项
589
- ├── goal/ # 持久自主 Goal
502
+ ├── workflows/ # DSL、Ledger、Graph、Replay、Artifacts
503
+ ├── tasks/ + goal/ # 工作项与持续目标
590
504
  ├── context-pivot/ # 定向 Compaction
591
- ├── plan-mode/ # 只读调研与批准门禁
592
- ├── cron/ # Session 内定时 Prompt
593
- ├── post-edit/ # 成功编辑后的可选命令
594
- ├── sessions/ # Session 搜索与切换
595
- ├── ask-user/ # 结构化用户输入
505
+ ├── plan-mode/ + cron/ # 批准门禁与 Session 定时 Prompt
506
+ ├── ask-user/ # Reviewed input 与 Human Handoff
596
507
  ├── file-search/ # fd / rg 与安全二进制获取
597
- ├── file-mutation-display/ # Bash / Write / Edit 紧凑渲染
508
+ ├── sessions/ # Session 搜索与切换
598
509
  ├── suggestions/ # Ephemeral next-action suggestion
599
- ├── git-info/ # Git、PR 与 /lg
600
- ├── model-info/ # Model、Context、Cost、Throughput
601
- ├── turn-time/ # Turn 耗时
602
510
  ├── ui-customization/ # Header、Footer、Terminal title
603
- ├── copy-all/ # 可见对话复制
604
511
  └── shared/ # Child policy、配置、Worktree、终端清洗
605
512
 
606
- skills/
607
- ├── background-terminals/
608
- └── subagents/
609
-
610
- themes/
611
- └── github-dark-default.json
513
+ skills/ # Background terminal 与 Subagent 指南
514
+ themes/ # github-dark-default
612
515
  ```
613
516
 
614
- 扩展通过 Pi Event Bus 和小型共享状态通信。长生命周期资源绑定 Session Shutdown；Workflow JavaScript 在独立 Permission Sandbox 中运行；Agent child 使用 Pi SDK Session 和 Trust-aware Resource Loader。
615
-
616
- ---
617
-
618
- ## 开发与验证
619
-
620
517
  ```bash
621
518
  npm install
622
- npm run check
623
519
  npm run format:check
520
+ npm run check
624
521
  npm test
625
522
  ```
626
523
 
627
- 测试覆盖进程树终止与竞态、Subagent 生命周期与工具边界、Workflow Sandbox/Replay/Acceptance、Worktree 数据保全、文件搜索二进制校验、Session 状态恢复、配置迁移和 TUI 渲染。
628
-
629
- 设计记录与多模型评估见 [`docs/design/`](https://github.com/tt-a1i/my-pi-setup/tree/main/docs/design)。欢迎通过 [Issues](https://github.com/tt-a1i/my-pi-setup/issues) 提交可复现 Bug 或真实工作流；新增能力应优先复用 Pi 原生原语，并遵守 [`AGENTS.md`](https://github.com/tt-a1i/my-pi-setup/blob/main/AGENTS.md) 的单一配置入口与 child-session 边界。
524
+ 测试覆盖进程树终止与竞态、Subagent 生命周期与工具边界、Workflow Sandbox / Ledger / Graph / Replay / Acceptance、Worktree 数据保全、Session 状态恢复、配置迁移和 TUI 渲染。设计记录见 [`docs/design/`](docs/design/)，问题请提交到 [GitHub Issues](https://github.com/tt-a1i/openpi/issues)。
630
525
 
631
526
  ---
632
527
 
633
- ## 来源与致谢
528
+ ## 来源、许可与致谢
634
529
 
635
530
  本项目最初基于 [davis7dotsh/my-pi-setup](https://github.com/davis7dotsh/my-pi-setup) 演进，现作为独立发行版维护。感谢原作者提供起点。
636
531
 
637
532
  `extensions/sessions/` 改编自 [jayshah5696/pi-agent-extensions](https://github.com/jayshah5696/pi-agent-extensions)。可选的顶层 Session 通信由 [pi-intercom](https://github.com/nicobailon/pi-intercom) 提供。完整第三方说明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
638
533
 
639
534
  本仓库目前没有项目级开源许可证；`THIRD_PARTY_NOTICES.md` 只记录第三方来源与各自许可，不等同于授予本项目使用许可。
640
-
641
- <p align="center">
642
- <strong>Small harness. Deep extensions. Clean context.</strong>
643
- </p>