@tt-a1i/openpi 0.1.0 → 0.2.0

package/README.md

@@ -1,117 +1,132 @@
 <p align="center">
-  <picture>
-    <source media="(max-width: 640px)" srcset="assets/readme-hero-mobile.svg">
-    <img src="assets/readme-hero.svg" alt="OpenPI — a Pi-native multi-agent workbench" width="100%" />
-  </picture>
+  <img src="assets/openpi-package.png" alt="OpenPI logo" width="240" />
 </p>
 
+<h1 align="center">OpenPI</h1>
+
 <p align="center">
-  <strong>给 Pi 补上后台执行、多 Agent 编排、持久任务和可观测终端，同时保留它原本的轻量与可控。</strong>
+  <strong>Small harness. Deep extensions. Clean context.</strong>
 </p>
 
 <p align="center">
-  <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>
-  <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">
-  <img alt="TypeScript strict" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white">
-  <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>
-  <img alt="Model neutral" src="https://img.shields.io/badge/models-user--selected-bc8cff?style=flat-square">
+  给 <a href="https://pi.dev">Pi</a> 加一层可靠运行时：后台执行、隔离 Subagent、可恢复 Workflow、持续任务与可观测终端。<br />
+  不替换 Pi，不替你选模型，也不把另一套 Agent 平台塞进来。
 </p>
 
 <p align="center">
-  一套在真实开发中持续使用的 <a href="https://pi.dev">Pi</a> 扩展包。<br />
-  不替你选模型，不强制主题，安装后也不会偷偷增加模型调用。
+  <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>
+  <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>
+  <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>
+  <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">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3fb950?style=flat-square"></a>
 </p>
 
 <p align="center">
-  <sub>OpenPI 是独立社区项目，与 Physical Intelligence 的 openpi 机器人项目及 Pi 官方均无关联。</sub>
+  <a href="#30-秒开始"><strong>30 秒开始</strong></a> ·
+  <a href="#openpi-解决什么">解决什么</a> ·
+  <a href="#能力地图">能力地图</a> ·
+  <a href="#运行模型">运行模型</a> ·
+  <a href="#三条执行路径">执行路径</a> ·
+  <a href="#workflow-不只是并行">Workflow</a> ·
+  <a href="#安全边界">安全边界</a> ·
+  <a href="#配置与参考">配置与参考</a>
 </p>
 
 <p align="center">
-  <a href="#快速开始"><strong>快速开始</strong></a> ·
-  <a href="#为什么装它">为什么装它</a> ·
-  <a href="#核心能力">核心能力</a> ·
-  <a href="#安全边界">安全边界</a> ·
-  <a href="#统一配置">统一配置</a> ·
-  <a href="#命令速查">命令速查</a> ·
-  <a href="#faq">FAQ</a>
+  <sub>OpenPI 是独立社区项目，与 Physical Intelligence 的 openpi 机器人项目及 Pi 官方均无关联。</sub>
 </p>
 
 ---
 
-## 快速开始
+## 30 秒开始
 
 ```bash
 pi install npm:@tt-a1i/openpi
 ```
 
-重启 Pi，或在当前 Session 运行 `/reload`。然后直接描述任务：
+重启 Pi，或在当前 Session 运行 `/reload`。然后直接描述真实任务：
 
 ```text
-启动前端 dev server；并行让两个子 Agent 检查 API 主链路和测试覆盖；
+启动前端 dev server；并行检查 API 主链路和测试覆盖；
 结果回来后汇总风险，主会话不要原地等待。
 ```
 
-Pi 会把长期进程放到后台，把独立任务交给隔离 Context 的子 Agent，并在结果完成时自动继续。Subagent 和 Workflow 状态显示在 Footer；后台终端有编辑器上方状态条，完整信息分别从 `/ps`、`/subagents` 和 `/workflows` 查看。
+OpenPI 会把长期进程放到后台，把独立任务交给隔离 Context 的 Pi Subagent，把多阶段依赖组织成 Workflow。状态会持续显示；完整运行可从 `/ps`、`/subagents` 和 `/workflows` 检查或终止。
 
 > [!IMPORTANT]
-> 默认安装是安静的：不修改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。所有用户偏好统一通过 `/my-pi-setup` 显式配置。
+> 默认安装是安静的：不改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。Capability discovery 默认 `explicit`；只有用户通过 `/openpi-setup` 选择 `adaptive` 后，模型才会常驻看到一个小型发现网关并可自主加载额外能力。
 
-> [!TIP]
-> `subagent_spawn` 会立即返回。主 Agent 应继续处理确定性工作；只有下一步确实依赖子 Agent 结果时，才调用 `subagent_wait`。
+```text
+/openpi-setup
+```
 
 ---
 
-## 为什么装它
-
-Pi 的价值在于小：Agent loop、工具、Session 和扩展 API 都有，但工作方式没有被平台写死。真实项目需要的，则是围绕这些原语的一层可靠运行时。
-
-<table>
-<tr>
-<td width="33%" valign="top">
-<strong>后台执行</strong><br/><br/>
-Dev server、watcher、build 和长测试不再占住主 Agent。日志可查，超时可控，退出自动回传。
-</td>
-<td width="33%" valign="top">
-<strong>干净委派</strong><br/><br/>
-Subagent 使用独立 Pi Context。调研、实现和审查可以并行，不把全部过程塞回主会话。
-</td>
-<td width="33%" valign="top">
-<strong>动态编排</strong><br/><br/>
-Workflow 支持 pipeline、parallel、结构化输出、显式验收、恢复执行和持久产物。
-</td>
-</tr>
-<tr>
-<td width="33%" valign="top">
-<strong>连续工作</strong><br/><br/>
-Tasks 记工作项，Goal 驱动持续目标，Context Pivot 在阶段变化时主动换一块干净工作面。
-</td>
-<td width="33%" valign="top">
-<strong>全程可见</strong><br/><br/>
-模型、Context、缓存、成本、Git、PR 与后台活动集中显示；每类运行都有检查和取消入口。
-</td>
-<td width="33%" valign="top">
-<strong>边界明确</strong><br/><br/>
-子 Agent 不能递归编排；未知工具、不可证明安全的 Replay、状态不明的 Worktree 一律 fail closed。
-</td>
-</tr>
-</table>
-
-### 运行模型
+## OpenPI 解决什么
+
+Pi 的价值在于小：Agent loop、工具、Session 与扩展 API 已经足够。真实项目缺的不是另一套平台，而是围绕这些原语的一层可靠运行时。
+
+| 开发现场                                | OpenPI 的处理方式                                                            | 保留的边界                         |
+| --------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- |
+| Dev server、watcher、长测试占住主 Agent | 后台 Terminal 管理进程树、日志、超时与完成通知                               | 无 stdin；Session 结束时有界清理   |
+| 调研、实现、审查互相污染 Context        | 每个 Subagent 使用独立的进程内 Pi SDK Session                                | Child 不能递归编排或拿回父级工具   |
+| 多阶段 fan-out 靠 Prompt 约定           | Workflow 提供 pipeline、schema、handoff、验收与持久产物                      | Sandbox 不暴露文件、网络或进程 API |
+| 重跑昂贵，却不能信任旧结果              | 只 Replay 在可观测边界内证明为只读且指纹未变的调用                           | 不确定就真实执行，不猜             |
+| 长任务跨回合后失去方向                  | Tasks、Goal、Plan Mode 与 Context Pivot 分别管理工作项、目标、批准和阶段切换 | 它们记录与控制，不伪造执行事实     |
+| 后台能力看不见、停不住                  | Footer、Dashboard、Artifacts 与完成通知统一展示状态                          | 每类运行都有检查、取消与唯一终态   |
+
+**核心原则：增强 Pi 的深度，不扩大隐式权限。** OpenPI 沿用用户已有的 Provider、模型、Skills、Trust 与 Session；Suggestion 只有用户开启后才运行，Subagent / Workflow 只在明确的任务动作后运行——主 Agent 调用对应工具，或用户在交互 TUI 中执行 `/btw`——不会因安装或启动自行消费模型。
+
+---
+
+## 能力地图
+
+OpenPI 把成熟 Coding Agent 的工作习惯做成 Pi-native 能力，但不复制另一套 Runtime：
+
+| 工作面       | 已包含的能力                                                                                              |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| 执行         | Background Terminal、Pi-native Subagent、Dynamic Workflow、隔离 Worktree                                  |
+| 编排         | `pipeline` / `parallel`、结构化输出、Result Handoff、Operator、Acceptance Ledger、Safe Replay、派生 Graph |
+| 连续性       | Tasks、Goal、Plan Mode、Context Pivot、Session Browser、Session-scoped Cron                               |
+| 自定义 Agent | `explorer` / `implementer` / `reviewer` / `advisor`，支持全局与项目角色文件、独立模型与 effort            |
+| 终端工作台   | 自定义 Footer 与任务栏、运行状态、紧凑 Tool Result、Next-action Suggestion、Git / PR 信号                 |
+| 快捷工作流   | `/btw` 旁路提问（TUI）、`/lg` 浏览 Diff（TUI）、`/pr` 查 PR、`/copy-all`、`fd`、`rg`                      |
+| 人类决策     | `ask_user` 草稿与最终复核、parent-only `human_handoff`、Plan Ready 实施门禁                               |
+| 跨 Session   | 可选 parent-only `pi-intercom`；父子通信仍走 Subagent / Workflow 原生通道                                 |
+| 统一配置     | `/openpi-setup` 管理 OpenPI 自有模型、并发、Footer、输出密度与 Post-edit 偏好                             |
+
+OpenPI 采用 [MIT License](LICENSE)；第三方来源与保留声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+---
+
+## 运行模型
 
 <p align="center">
   <picture>
-    <source media="(max-width: 640px)" srcset="assets/readme-runtime-mobile.svg">
-    <img src="assets/readme-runtime.svg" alt="OpenPI runtime model" width="100%" />
+    <source media="(max-width: 820px)" srcset="assets/readme-runtime-mobile.svg">
+    <img src="assets/readme-runtime.svg" alt="OpenPI runtime: one parent Pi session, three execution paths, continuity, and observability" width="100%" />
   </picture>
 </p>
 
-主 Pi Session 始终拥有用户交互、配置和生命周期。后台 Terminal、Subagent 与 Workflow 是三条执行路径；Tasks、Goal、Session 和 Context Pivot 保持连续性；Footer、Dashboard、Artifacts 与清理逻辑负责可观察性。
+主 Pi Session 始终拥有用户交互、配置和生命周期。Terminal、Subagent 与 Workflow 是三条执行路径；Tasks、Goal、Session 和 Context Pivot 保持连续性；Footer、Dashboard、Artifacts 与清理逻辑负责观察和控制。
+
+### 一项任务应该去哪里？
+
+```text
+长期进程                         → Background Terminal
+一项自包含、可继续对话的委派     → Subagent
+多阶段、依赖、fan-out 与综合      → Workflow
+跨回合工作项                     → Tasks
+持续自主目标                     → Goal
+同一 Session 的阶段切换          → Context Pivot
+真正跨顶层 Session               → pi-intercom（可选）
+```
 
 ---
 
-## 核心能力
+## 三条执行路径
 
-### 1. 后台终端：长期进程不再阻塞 Agent
+### Background Terminal：长期进程不阻塞 Agent
 
 ```text
 bg_start({
@@ -121,15 +136,17 @@ bg_start({
 ```
 
 - stdout / stderr 独立捕获，完整日志有私有、有界的临时落盘；
-- `/ps` 查看状态与日志，`bg_kill` 终止整个进程树；
+- `/ps` 查看状态，`bg_kill` 终止整个进程树；
 - 进程退出后自动通知，不需要轮询；
 - build、test、migration 可设置 `timeout_seconds`；
-- server 和 watcher 不设超时，用 `bg_watch` 等待 `Ready in|Traceback|ERROR` 一类字面签名；
-- 最多同时运行 8 个后台终端；Session 关闭或 Reload 时统一清理。
+- server 和 watcher 不设超时，可用 `bg_watch` 等待 `Ready in|Traceback|ERROR`；
+- 最多同时运行 8 个后台终端，Reload 或 Session Shutdown 时统一清理。
+
+后台进程没有 stdin。需要交互输入的命令应由用户直接运行，而不是放进后台。
 
-后台终端没有 stdin，因此不适合交互式程序。它适合 server、watch mode、长测试和流式构建。
+前台执行沿用 Pi 的 Bash 合同：`timeout` 可选且没有统一默认值，是否设置以及设置多长由模型或用户按命令语义决定。OpenPI 不再通过正则改写测试命令 timeout；确实需要有界执行时应显式传入 timeout，长期运行的 build、test、migration 或 server 可使用 Background Terminal 的生命周期能力。
 
-### 2. Pi-native Subagents：隔离 Context，而不是另起一套系统
+### Pi-native Subagent：隔离 Context，不另起系统
 
 ```text
 subagent_spawn({
@@ -141,28 +158,27 @@ subagent_spawn({
 
 每个 Subagent 都是新的进程内 Pi SDK Session：
 
-- 默认继承父会话的 Provider、模型和 Thinking Level；
-- 继承普通 child-safe 工具、Skills、项目说明与 Trust 决策，但不获得父级编排/交互工具；
-- 最多 4 个模型发起的 Subagent 并发运行；`/btw` 使用独立小池；
-- 结束后自动回传，可 `check`、`wait`、`cancel`；
-- `subagent_send` 可以继续指导运行中的 Agent，也能恢复刚结束的同一子会话；
-- 输入框下方展示实时摘要，空输入时按 `↓` 聚焦，`Enter` 或 `→` 打开管理界面。
+- 默认继承父会话的 Provider、模型与 Thinking Level；
+- 继承普通 child-safe 工具、Skills、项目说明与 Trust 决策；
+- 最多 4 个模型发起的 Subagent 并发运行，结束后自动回传；
+- 可 `check`、`wait`、`cancel`，也可用 `subagent_send` 继续同一子会话；
+- 输入框下方显示实时摘要，空输入时按 `↓` 聚焦，`Enter` 或 `→` 打开管理界面。
 
-内置角色由 harness 强制工具边界，不靠提示词自律：
+内置角色由 Harness 强制工具边界，不靠 Prompt 自律：
 
-| `agent_type`  | 用途           | 默认 effort | 强制能力                         |
-| ------------- | -------------- | ----------- | -------------------------------- |
-| `explorer`    | 代码追踪与探索 | high        | 只读发现工具                     |
-| `implementer` | 聚焦实现       | high        | read / bash / edit / write 等    |
-| `reviewer`    | 正确性与回归审查 | medium      | 只读发现工具                     |
-| `advisor`     | 深度技术建议   | xhigh       | 只读发现工具                     |
+| `agent_type`  | 适合             | 默认 effort | 强制能力                      |
+| ------------- | ---------------- | ----------- | ----------------------------- |
+| `explorer`    | 代码追踪与探索   | high        | 只读发现工具                  |
+| `implementer` | 聚焦实现         | high        | read / bash / edit / write 等 |
+| `reviewer`    | 正确性与回归审查 | medium      | 只读发现工具                  |
+| `advisor`     | 深度技术建议     | xhigh       | 只读发现工具                  |
 
-角色可由全局 `~/.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)。
+角色可由全局 `~/.pi/agent/agents/*.md` 或受信任项目 `.pi/agents/*.md` 覆盖。模型优先级是：显式调用 > Agent Type 文件 > `/openpi-setup` 角色模型 > 父模型继承。更高优先级定义损坏时会阻断 fallback，而不是悄悄退回更宽松的能力。
 
 <details>
 <summary><strong>并行写文件时如何隔离 Worktree？</strong></summary>
 
-默认并行 Agent 共享 checkout 和 git index。只读 fan-out 不受影响；会写文件的并行任务应开启：
+默认并行 Agent 共享 checkout 与 git index。只读 fan-out 不受影响；并行写入应使用：
 
 ```text
 subagent_spawn({
@@ -172,178 +188,135 @@ subagent_spawn({
 })
 ```
 
-Worktree 建在 `.git/pi-worktrees/`，拥有独立 checkout 和分支。Direct Subagent 的 checkout 与它的可恢复 Session 同寿命。退役时，已提交工作删除 checkout、保留分支；dirty/untracked/ignored 文件、detached HEAD、Git 探测失败或超时则保留 checkout 路径。只有完整证明为空时才全部回收。
+Worktree 建在 `.git/pi-worktrees/`，拥有独立 checkout 与分支。已提交工作会删除 checkout、保留分支；dirty、untracked、ignored 文件，detached HEAD，Git 探测失败或超时都会保留现场。只有完整证明为空时才回收。
 
-全新 checkout 不包含 `.env` 或其他 gitignored 内容。可用时会在 `.git/pi-worktrees/node_modules` 建立依赖 symlink，让 checkout 通过父目录解析依赖；Worktree 仍要求当前目录是 Git 仓库。
+全新 checkout 不包含 `.env` 或其他 gitignored 内容。可用时 OpenPI 会在 worktree 中建立 `node_modules` 依赖 symlink。
 
 </details>
 
-<details>
-<summary><strong>模型与 Agent Type 的优先级</strong></summary>
-
-模型：显式调用 > Agent Type 文件 > `/my-pi-setup` 的角色模型 > 父模型继承。
-
-Effort：显式调用 > Agent Type 默认值 > 父会话。
+### Dynamic Workflow：让多 Agent 工作有阶段、有证据、有产物
 
-同名角色定义：内置 < 全局 < 受信任项目。更高优先级文件如果损坏，会阻断 fallback，而不是悄悄退回更宽松的定义。工具白名单只能收窄，也无法重新拿回父会话专属工具。
-
-</details>
-
-### 3. Dynamic Workflows：让多 Agent 任务有阶段、有证据、有产物
-
-单个 Subagent 负责一项自包含委派。Workflow 处理多阶段、有依赖、需要 fan-out 和综合的任务：
+单个 Subagent 负责一项委派。Workflow 处理阶段依赖、动态 fan-out、结构化结果、恢复与综合：
 
 ```js
 phase("Scan");
 const checked = await pipeline(
   files,
   (file) =>
-    agent(`Trace ${file} for reliability risks with file:line evidence`, {
+    agent(`Trace ${file} for reliability risks`, {
       agent_type: "explorer",
       label: `scan:${file}`,
       schema: FINDING_SCHEMA,
     }),
   (scan, file) =>
     scan.ok
-      ? agent(`Verify these findings in ${file}: ${scan.output}`, {
+      ? agent(`Verify findings in ${file}`, {
           agent_type: "reviewer",
           label: `verify:${file}`,
+          inputs: [scan.ref],
         })
       : null,
 );
 
 phase("Report");
-log(`${checked.filter(Boolean).length}/${checked.length} files verified`);
-return await agent(`Synthesize: ${JSON.stringify(checked)}`, {
+const verified = checked.filter((result) => result?.ok);
+log(`${verified.length}/${checked.length} files verified`);
+return agent("Synthesize the verified findings", {
   agent_type: "advisor",
+  inputs: verified.map((result) => result.ref),
 });
 ```
 
-| 原语         | 作用                                                                 |
-| ------------ | -------------------------------------------------------------------- |
-| `phase()`    | 标记当前阶段                                                         |
-| `log()`      | 向实时界面与最终报告追加一行进度                                     |
-| `usage()`    | 读取累计 Token、缓存与成本的单调 lower bound；它不是预算限制器        |
-| `agent()`    | 启动一个隔离 Pi Agent，可指定 role、schema、acceptance 或 worktree    |
-| `pipeline()` | 每个 item 完成上一阶段后立即进入下一阶段；多阶段 fan-out 的默认选择   |
-| `parallel()` | 并发 barrier；只有下一阶段确实需要全部结果时使用                      |
+| 原语         | 作用                                                                       |
+| ------------ | -------------------------------------------------------------------------- |
+| `phase()`    | 标记当前阶段                                                               |
+| `log()`      | 向实时界面与最终报告追加一行进度                                           |
+| `usage()`    | 读取累计 Token、缓存与成本的单调 lower bound；不是预算器                   |
+| `agent()`    | 启动 Pi Agent；支持 role、schema、acceptance、inputs、operator 与 worktree |
+| `pipeline()` | 每个 item 完成上阶段后立即进入下一阶段；多阶段 fan-out 的默认选择          |
+| `parallel()` | 并发 barrier；只在下一阶段确实需要全部结果时使用                           |
 
-Workflow 默认并发 8 个 Agent、单次最多 128 次调用；可分别配置到 64 和 1024。Workflow DSL 不暴露文件、网络或进程 API；Sandbox 进程只保留启动所需的包目录读取权限。`usage()` 在 Agent 压缩 Context 后可能低估实际总量，只适合观察趋势。前台运行可实时查看，后台运行完成后自动回传；`/workflows` 检查阶段、Agent、Transcript、用量与产物，`workflow_stop` 或 Dashboard 中的 `x` 可以取消。
+Workflow 默认并发 8 个 Agent，单次最多 128 次调用；可配置到 64 和 1024。前台运行可实时查看，后台运行完成后自动回传；`/workflows` 展示阶段、Agent、Transcript、Graph、用量与产物。
 
-<details>
-<summary><strong>Replay、Acceptance Ledger 与隔离写入</strong></summary>
+---
 
-`resume_from_run_id` 只 Replay 能被完整证明为只读且上下文未变的调用。指纹覆盖 prompt、schema、model/provider/effort、规范化 cwd、仓库状态、已加载资源和 Trust。下列调用一定真实执行：
+## Workflow 不只是并行
 
-- 无 Agent Type 或工具范围无限制；
+OpenPI 把一次调用拆成可以审计的生命周期，而不是把“进程退出 0”当成业务成功。
+
+### Result Handoff 与派生 Graph
+
+成功调用返回同一 Run 内有效的 opaque `ref`。后续调用通过 `inputs: [previous.ref]` 显式接收上游结论；每个结论最多 16 KiB，合计最多 48 KiB，并标记为不可信数据。Artifacts 从这些引用派生只读 Graph，用来观察 lineage，不参与调度。
+
+### Invocation Ledger
+
+每次 `agent()` 独立记录 intent、admission 与 execution 状态。崩溃后仍未终结的调用恢复为 `uncertain`，不会猜成成功、失败或安全重试。这不是跨重启 exactly-once，也不伪装成 exactly-once。
+
+### Safe Replay
+
+`resume_from_run_id` 只 Replay 在 OpenPI 可观测边界内能证明为只读、且指纹未变的调用。指纹覆盖 prompt、schema、model/provider/effort、规范化 cwd、仓库状态、已加载资源与 Trust；外部进程造成但未进入这些观测面的变化不在保证范围内。
+
+以下调用一定真实执行：
+
+- 无 Agent Type，或工具范围无限制；
 - 带 `bash`、`edit`、`write` 或未知自定义工具；
-- 使用 `isolation: "worktree"`；
-- 存在会影响结果但无法纳入指纹的 ignored 文件；
-- 旧 journal、指纹失败，或与不可缓存调用发生不安全重叠。
+- 使用 per-call Worktree；
+- ignored 文件可能影响结果却无法纳入指纹；
+- Journal、资源、路径、并发重叠或指纹状态不确定。
 
-匹配依据是调用内容，不是调用序号，因此 `pipeline()` 的并发完成顺序变化不会把 A 的结果错配给 B。失败调用从不缓存。Journal 上限 2MB，超出后丢弃最旧条目并显式报告。
+匹配依据是调用内容，不是并发完成顺序。失败调用不缓存；Journal 有 2 MiB 上限。
 
-可选 `acceptance: { criteria: [...] }` 要求同一个 Agent 返回 evidence ledger。条件缺失、格式错误或被拒绝时，该调用 `ok: false`，但原始输出与 ledger 仍保留；不会暗中再启动 reviewer 或 shell。
+### Operator Continuity
 
-并行写入使用 `isolation: "worktree"`。Workflow 在清理 checkout 前原子保存有界 handoff manifest，包括 tracked binary patch、stat、branch/HEAD、untracked/ignored 清单和 cleanup receipt。状态不明时保留，不自动 merge、apply 或强删。
+`operator: "name"` 在同一 Run 内复用一个内存 Child Session，并把同名 activation 串行化。首个 activation 固定 model、role/tool surface、effort、structured mode 与 cwd。Operator 不与 per-call Worktree 或 Replay 混用，也不承诺跨重启持久记忆。
 
-</details>
+### Explicit Acceptance
 
----
+可选 `acceptance: { criteria: [...] }` 要求同一个 Agent 返回 evidence ledger。条件缺失、格式错误或被拒绝时，调用返回 `ok: false`，但原始输出与 ledger 仍保留。OpenPI 不会暗中再启动 reviewer、Shell 或额外 Judge 模型。
 
-## 连续性与交互
-
-<table>
-<tr>
-<td width="50%" valign="top">
-<strong>Session Tasks</strong><br/><br/>
-<code>tasks_add / tasks_update / tasks_list</code><br/>
-跨 Agent Run 和用户回合记录当前批次的工作意图。稳定 ID、可审计状态、Session 分支恢复；全部完成后关闭批次，下批从 T1 重新开始。Tasks 不执行工作。
-</td>
-<td width="50%" valign="top">
-<strong>Session Goal</strong><br/><br/>
-<code>/goal &lt;目标&gt;</code><br/>
-Codex 风格的持久自主目标。支持 pause、resume、edit、clear 和可选 Token budget；系统规则要求模型先完成证据审计再声明 complete，工具本身只记录声明。
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<strong>Context Pivot</strong><br/><br/>
-<code>/context-pivot &lt;下一阶段&gt;</code><br/>
-Context 超过约 30K Tokens 且任务切换阶段时，用自包含 Brief 替换旧阶段噪音，在同一 Session 继续。普通超长对话仍用 Pi 原生 <code>/compact</code>。
-</td>
-<td width="50%" valign="top">
-<strong>Session Browser</strong><br/><br/>
-<code>/sessions</code><br/>
-按名称、首条消息、Session ID 和目录搜索；预览 User、Assistant、Tool 与 Summary；通过 Pi 安全生命周期切换。
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<strong>Reviewed Human Input</strong><br/><br/>
-<code>ask_user</code> · <code>human_handoff</code><br/>
-<code>ask_user</code> 在 TUI/RPC 中收集 1–3 个结构化决策，支持 Notes、预览、草稿修改与提交前复核；空白自由输入会要求模型重写或拆分问题。只有用户能完成的登录、授权或硬件操作才使用 parent-only handoff，Done 后仍须验证完成信号。
-</td>
-<td width="50%" valign="top">
-<strong>Next-action Suggestion</strong><br/><br/>
-完整主 Agent Run 结束后，可在空编辑器首行显示一条暗色 inline 建议。行尾为中文 IME 预留预编辑区域，避免拼音覆盖建议；<code>Right</code> 只填入、不提交，其他输入取消。默认关闭且不写入 Session 或模型 Context。
-</td>
-</tr>
-</table>
-
-### Tasks 与 Goal 怎么分工
-
-- Tasks 是多个工作项的咨询性记录，不调度、不委派，也不参与 Goal 完成判定；
-- Goal 是一个持续到终态的自主目标，模型只能提交 `complete` 或经过连续审计的 `blocked`；
-- Subagent 与 Workflow 才执行工作；文件、Git、测试、Artifacts 和用户确认仍是事实来源。
-
-### Plan Mode、Cron 与 Post-edit
-
-- `/plan [目标]` 先做只读调研；模型以 `plan_ready` 显式提交完整计划后，`/plan` 才提供继续规划、当前 Session 实施或 Fresh Session 实施。两个实施入口都只填入可编辑 Prompt，不自动提交；Planning/Ready 状态按 Session branch 持久化并在 Reload、Resume、Tree navigation 后恢复；Plan Mode 使用严格命令白名单，不尝试“理解”任意 Shell 是否只读；
-- `/cron ...` 在当前 Session 中排定一次或周期性提示词；
-- Post-edit 可在成功 Write/Edit 的 Turn 后运行一条用户配置的命令，例如 `npm run format`。默认关闭，最多 500 字符，不猜测 Bash 是否改过文件。
+### Worktree Handoff
 
----
+Workflow 在清理隔离 checkout 前原子保存有界 Handoff Manifest：tracked binary patch、stat、branch/HEAD、untracked/ignored 清单与 cleanup receipt。状态不明就保留现场，不自动 merge、apply 或强删。
 
-## 终端体验
+设计细节见 [`docs/design/WORKFLOW_INVOCATION_GRAPH.md`](docs/design/WORKFLOW_INVOCATION_GRAPH.md)。
+
+---
 
-### 一行 Footer，持续显示真实状态
+## 连续工作，而不是堆 Context
 
-默认 Powerline Footer：
+| 能力          | 使用方式                                | 它负责什么                                                          |
+| ------------- | --------------------------------------- | ------------------------------------------------------------------- |
+| Tasks         | `tasks_add` / `tasks_update` / `/tasks` | 逐项同步当前批次工作意图并刷新完整快照；不推断完成、不执行工作      |
+| Goal          | `/goal <目标>`                          | 驱动一个持续到终态的自主目标；完成前要求证据审计                    |
+| Plan Mode     | `/plan [目标]`                          | 只读调研；`plan_ready` 后才准备可编辑的实施 Prompt，不自动执行      |
+| Context Pivot | `/context-pivot <下一阶段>`             | Context 超过约 30K Tokens 且任务换阶段时，用自包含 Brief 替换旧噪音 |
+| Sessions      | `/sessions`                             | 搜索、预览并通过 Pi 安全生命周期切换 Session                        |
+| Human Input   | `ask_user` / `human_handoff`            | 收集经复核的决策，或等待只有用户能完成的外部操作                    |
 
-```text
-cwd  model  thinking  context  cache  cost  throughput   git  PR
-```
+Tasks 是咨询性记录，Goal 是持续目标，Subagent 与 Workflow 才执行工作。文件、Git、测试、Artifacts 和用户确认始终是事实来源。
 
-支持 `powerline`、`powerline-mono` 与 `compact` 三个 preset，也可用 `footerLines` 自定义多行布局。终端变窄时按优先级隐藏次要指标，而不是机械截断尾部。
+Next-action Suggestion 是可选的：完整主 Agent Run 结束后，在空编辑器显示一条暗色 inline 建议；`Right` 只填入、不提交，其他输入取消。它默认关闭，不写入 Session，也不进入模型 Context。
 
-| 指标         | 内容                                     |
-| ------------ | ---------------------------------------- |
-| `cwd`        | 当前目录                                 |
-| `model`      | Provider / Model                         |
-| `thinking`   | Thinking 档位                            |
-| `context`    | Context 占用与容量；占用未知时只显示容量 |
-| `cache`      | Session 报告的 Prompt Cache 命中率       |
-| `cost`       | Session 累计成本                         |
-| `throughput` | 当前流式运行的估算 Token 速度            |
-| `git` / `pr` | 当前分支与对应 PR                        |
-| `flex`       | 同一行左右对齐的分隔点                   |
+---
 
-Subagent 与 Workflow 状态属于 Footer 的基础可观察性：活动时自动出现，空闲时不占空间。后台终端使用编辑器上方状态条和 `/ps`，不混进 Footer。本地 Git 状态自动刷新；GitHub PR 查询只有用户显式运行 `/pr` 时才会发起。Nerd Font 只改善 Powerline 分隔符 ``，不是硬依赖。
+## 终端体验
 
-### 输出密度按内容类型独立控制
+默认 Powerline Footer 把真实运行状态压进一行：
 
-- Subagent 结果默认完整显示；
-- Bash 默认折叠为单行命令、有限输出与最终状态；
-- Write/Edit 默认最多显示三行渲染内容；
-- 三类结果都能在 `/my-pi-setup` 中独立切换 `full` / `compact`；
-- 折叠内容用 Pi 当前的 `app.tools.expand` 快捷键临时展开，默认是 `Ctrl+O`。
+```text
+cwd  model  thinking  context  cache  cost  throughput   git  PR
+```
 
-### 文件搜索是一等工具
+- 支持 `powerline`、`powerline-mono`、`compact`，也支持自定义多行布局；
+- 终端变窄时按优先级隐藏次要指标，不机械截断尾部；
+- Subagent 与 Workflow 活动时自动出现，空闲时不占空间；
+- Bash、Write/Edit 与 Subagent 结果可独立选择 `full` 或 `compact`；
+- 折叠内容用 Pi 的 `app.tools.expand` 快捷键临时展开，默认 `Ctrl+O`；
+- Git 状态本地刷新；只有显式运行 `/pr` 才查询 GitHub PR。
 
-`fd` 与 `rg` 使用结构化参数，不拼接 Shell；默认遵守 `.gitignore`，支持 Glob、类型、Smart Case、固定字符串和上下文。结果限制为 50KB / 2000 行；不超过 10 MiB 的完整截断内容保存在 Session 临时文件中并于 Shutdown 时清理，超过该上限时搜索会终止且部分临时文件会立即删除。
+`fd` 与 `rg` 是结构化模型工具，不拼接 Shell。它们默认遵守 `.gitignore`，支持 Glob、类型、Smart Case、固定字符串与上下文；输出限制为 50 KiB / 2000 行，完整截断内容最多私有保存 10 MiB，并在 Session Shutdown 时清理。
 
-macOS/Linux 的 arm64 与 x64 环境缺少二进制时，会通过 HTTPS 下载固定官方版本、校验 SHA-256 后原子安装。其他架构和平台需自行提供 `fd` 与 `rg`。
+macOS/Linux arm64 与 x64 缺少二进制时，OpenPI 会从官方 Release 下载固定版本、校验 SHA-256 后原子安装。其他平台需自行提供 `fd` 与 `rg`。
 
 ---
 
@@ -351,174 +324,136 @@ macOS/Linux 的 arm64 与 x64 环境缺少二进制时，会通过 HTTPS 下载
 
 这里的安全不是一段 Prompt，而是运行时约束。
 
-| 边界                     | 行为                                                                 |
-| ------------------------ | -------------------------------------------------------------------- |
-| 子 Agent 递归编排        | 禁止。Subagent/Workflow child 不获得 `subagent_*`、`workflow` 等父级工具 |
-| Agent Type 工具          | Harness 强制白名单；声明不能突破父级 denylist                        |
-| 类型与工具预检           | 未知、损坏、错名或最终未注册的工具在首个 Token 前失败                 |
-| Workflow Sandbox         | DSL 无文件、网络、进程、import、eval 或 timer API；进程仅可读启动包目录 |
-| Replay                   | 只有可证明只读、上下文指纹完整且无不安全重叠的调用才缓存              |
-| Worktree 清理            | 未知即保留；Git 状态、handoff 或超时不确定时绝不删除                  |
-| 终端输出                 | 控制字符、方向格式符与超长内容在 ingress/render 边界清洗和限长         |
-| Shutdown                 | Terminal、Subagent、Workflow 都做有界取消、清理与唯一终态             |
-| 用户配置                 | 一个受限 typed tool 写入；没有散落的扩展私有入口                      |
-| 模型消费                 | Suggestion 默认关闭；Subagent/Workflow 只在任务显式触发时运行          |
-
-可选的 [pi-intercom](https://github.com/nicobailon/pi-intercom) 只在顶层 Pi Session 加载。它依赖进程级身份，而 Direct/Workflow child 是同一进程内的并发 Session；为避免身份串线，child Resource Loader 会移除 pi-intercom 的扩展与 Skill。
+| 边界             | 行为                                                                      |
+| ---------------- | ------------------------------------------------------------------------- |
+| Child 递归编排   | 禁止；Subagent / Workflow child 不获得父级编排、交互与状态工具            |
+| Agent Type 工具  | Harness 强制白名单；声明不能突破父级 denylist                             |
+| 类型与工具预检   | 未知、损坏、错名或最终未注册的工具在首个 Token 前失败                     |
+| Workflow Sandbox | 无文件、网络、进程、import、eval 或 timer API；进程仅可读启动包目录       |
+| Replay           | 只有可证明只读、指纹完整且无不安全重叠的调用才缓存                        |
+| Worktree 清理    | 未知即保留；Git、Handoff 或超时状态不确定时绝不删除                       |
+| 终端输出         | 控制字符、方向格式符与超长内容在 ingress / render 边界清洗、限长          |
+| Shutdown         | Terminal、Subagent、Workflow 都有有界取消、清理与唯一终态                 |
+| 用户配置         | 单一受限 typed tool 写入；不散落扩展私有配置入口                          |
+| 模型消费         | Suggestion 默认关闭；adaptive 仅在显式开启后允许模型自主加载能力           |
+
+可选的 [pi-intercom](https://github.com/nicobailon/pi-intercom) 只在顶层 Pi Session 加载。它使用进程级身份，而 OpenPI Child 是同一进程内的并发 Session；Child Resource Loader 会移除 pi-intercom 扩展与 Skill，避免身份串线。Replay 也不会复用其调用。
 
 ---
 
-## 统一配置
+## 配置与参考
 
-本包只有一个用户配置入口：
+### 一个配置入口
 
 ```text
-/my-pi-setup
+/openpi-setup
+/my-pi-setup  # legacy alias
 ```
 
-无参数时，当前模型先解释已有设置与影响，再引导修改。直接跟自然语言则只改指定项：
+无参数时，OpenPI 展示当前状态并引导修改；带自然语言时只改指定项：
 
 ```text
-/my-pi-setup 开启下一步预测，选择当前 Registry 里的轻量模型，minimal 推理
-/my-pi-setup workflow 同时跑 16 个 agent，总调用最多 256
-/my-pi-setup Footer 两行：cwd flex model / context cost flex git
-/my-pi-setup Footer 用 mono powerline
-/my-pi-setup Bash 展开，Write/Edit 保持紧凑
-/my-pi-setup 编辑后自动跑 npm run format
-/my-pi-setup 给 explorer 指定模型，让 reviewer 继承父模型
+/openpi-setup 开启下一步预测，选择 Registry 里的轻量模型，minimal 推理
+/openpi-setup 让模型在合适时自主发现并采用 OpenPI 能力
+/openpi-setup workflow 同时跑 16 个 agent，总调用最多 256
+/openpi-setup Footer 两行：cwd flex model / context cost flex git
+/openpi-setup Bash 展开，Write/Edit 保持紧凑
+/openpi-setup 编辑后自动跑 npm run format
+/openpi-setup 给 explorer 指定模型，让 reviewer 继承父模型
 ```
 
-配置保存在 `~/.pi/agent/my-pi-setup.json`，与包代码分离。升级不会覆盖。
-
-### 默认值
-
-| 配置                     | 默认值                                                       |
-| ------------------------ | ------------------------------------------------------------ |
-| Next-action suggestion   | 关闭；启用时必须显式选择 Registry 中可用的模型与 reasoning   |
-| Workflow 并发            | 8，硬上限 64                                                 |
-| Workflow 总 Agent 调用   | 128，硬上限 1024                                             |
-| 大型 Header              | 关闭                                                         |
-| Dashboard Footer         | 开启；单行 `powerline`                                       |
-| Subagent 结果            | `full`                                                       |
-| Bash 输出                | `compact`                                                    |
-| Write/Edit 输出          | `compact`                                                    |
-| Post-edit 命令           | 关闭；单条命令最多 500 字符                                  |
-| 内置角色模型             | `explorer / implementer / reviewer / advisor` 均继承父模型   |
-| 主题                     | 保留用户现有选择                                             |
+配置保存在 `~/.pi/agent/my-pi-setup.json`，与包代码分离，升级不会覆盖。
 
-任何新增的模型、开关、权限、并发或 UI 偏好都必须接入 `/my-pi-setup`。仓库的 [`AGENTS.md`](https://github.com/tt-a1i/my-pi-setup/blob/main/AGENTS.md) 用测试守住这份单一入口契约。
+一次 `/openpi-setup` episode 最多成功写入一次；成功后配置工具立即隐藏。若随后还要修改另一项，请重新执行 `/openpi-setup <自然语言请求>`，不要让模型重调已隐藏工具，也不要绕过入口直接编辑配置文件。
 
----
+<details>
+<summary><strong>默认值</strong></summary>
+
+| 配置                         | 默认值                                         |
+| ---------------------------- | ---------------------------------------------- |
+| Capability discovery         | `explicit`；`adaptive` 必须显式开启            |
+| Next-action Suggestion       | 关闭；启用时显式选择 Registry 模型与 reasoning |
+| Workflow 并发 / 总调用       | 8 / 128；硬上限 64 / 1024                      |
+| 大型 Header                  | 关闭                                           |
+| Dashboard Footer             | 开启；单行 `powerline`                         |
+| Subagent / Bash / Write/Edit | `full` / `compact` / `compact`                 |
+| Post-edit 命令               | 关闭；单条命令最多 500 字符                    |
+| 内置角色模型                 | 全部继承父模型                                 |
+| pi-intercom                  | 不静默安装；由用户明确选择                     |
+| 主题                         | 保留用户现有选择                               |
 
-## 安装与可选集成
+</details>
 
-### 要求
+### 安装要求与来源
 
 - Pi `0.84.1` 或更新版本；
-- Node.js 22.19.0 或更新版本；
-- macOS/Linux 的 arm64 或 x64 可自动安装 `fd` / `rg`；其他架构和平台需自行安装。
+- Node.js `22.19.0` 或更新版本；
+- npm 安装：`pi install npm:@tt-a1i/openpi`；
+- GitHub 安装：`pi install git:github.com/tt-a1i/openpi`。
 
-### Pi Package
+开发当前源码：
 
 ```bash
-pi install npm:@tt-a1i/openpi
+git clone https://github.com/tt-a1i/openpi.git ~/work/openpi
+cd ~/work/openpi
+bun install --frozen-lockfile
+pi install ~/work/openpi
 ```
 
-需要直接审计当前源码时，也可以从 GitHub 安装：
+安装或更新后重启 Pi，或运行 `/reload`。Host SDK 与 TypeBox 按 Pi Package 契约声明为 Peer Dependencies；仓库开发依赖不随包重复提供。
 
-```bash
-pi install git:github.com/tt-a1i/my-pi-setup
-```
+### 可选：顶层 Pi Session 通信
 
-开发本仓库时可以安装本地 checkout：
-
-```bash
-git clone https://github.com/tt-a1i/my-pi-setup.git ~/work/my-pi-setup
-cd ~/work/my-pi-setup
-npm install
-pi install ~/work/my-pi-setup
-```
-
-安装或更新后重启 Pi，或运行 `/reload`。Pi 提供的 `pi-ai`、`pi-coding-agent`、`pi-tui` 和 `typebox` 按官方 Package 契约声明为 Peer Dependencies；仓库中的开发依赖仅用于本地检查，不随包重复提供 Host SDK。
-
-### 可选：多个顶层 Pi Session 通信
+运行 `/openpi-setup`，在原生确认框中选择安装；也可手动执行：
 
 ```bash
 pi install npm:pi-intercom
 ```
 
-pi-intercom 通过本地 IPC 传递消息；传输本身不调用模型。快捷键、命令与 `inboundTrigger` 配置以当前安装版本的文档为准。
-
-本包只保证一件事：pi-intercom 留在顶层 Session，child 不加载它。跨顶层 Session 用 pi-intercom；父子委派继续使用 `subagent_*` 和 Workflow 原生结果通道。
-
-### 可选：GitHub Dark 主题
+新私有配置默认 `confirmSend: true`、`inboundTrigger: "replies"`；已有配置绝不重写。安装失败不显示成功，也不写配置；安装后需 `/reload`。跨顶层 Session 用 pi-intercom，父子委派继续使用 `subagent_*` 与 Workflow 原生结果通道。
 
-安装包会注册主题，但不会自动切换。通过 Pi `/settings` 选择 `github-dark-default`，或配置：
+### 命令速查
 
-```json
-{
-  "theme": "github-dark-default"
-}
-```
-
----
-
-## 命令速查
-
-| 命令                        | 作用                                                            |
-| --------------------------- | --------------------------------------------------------------- |
-| `/my-pi-setup [自然语言]`   | 查看或修改本包配置                                              |
-| `/ps`                       | 查看、跟踪和终止后台终端                                        |
-| `/subagents`                | 查看、取消或接管子 Agent                                        |
-| `/btw`                      | 在旁路 Pi Context 中提问，不打断主任务                          |
-| `/workflows`                | 查看阶段、Agent 与产物；`/workflows <id> stop` 取消运行         |
-| `/tasks`                    | 查看当前 Session 的工作项                                      |
-| `/goal ...`                 | 创建、查看、编辑、暂停或恢复持久 Goal                           |
-| `/context-pivot <下一阶段>` | 在同一 Session 中压缩旧阶段并继续                              |
-| `/sessions`                 | 搜索、预览并切换 Session                                        |
-| `/plan [目标]`              | 只读调研，进入 Plan Ready 后显式选择实施方式                     |
-| `/cron ...`                 | 为当前 Session 安排定时或周期性 Prompt                          |
-| `/lg` / `/pr`               | 浏览 Working Tree Diff / 刷新当前分支 PR                       |
-| `/copy-all`                 | 复制当前分支可见的 User / Assistant 对话                        |
+| 命令                       | 作用                                           |
+| -------------------------- | ---------------------------------------------- |
+| `/openpi-setup [自然语言]` | 查看或修改统一配置；可选择安装 pi-intercom     |
+| `/ps`                      | 查看、跟踪与终止后台终端                       |
+| `/subagents` / `/btw`      | 管理 Subagent / 在旁路 Context 中提问；仅 TUI  |
+| `/workflows`               | 查看阶段、Agent、Graph 与产物；可停止运行      |
+| `/tasks` / `/goal ...`     | 查看工作项 / 管理持续目标                      |
+| `/context-pivot <阶段>`    | 在同一 Session 中压缩旧阶段并继续              |
+| `/sessions`                | 搜索、预览与切换 Session                       |
+| `/plan [目标]`             | 只读调研；Plan Ready 后显式选择实施方式        |
+| `/cron ...`                | 为当前 Session 安排一次或周期性 Prompt         |
+| `/lg` / `/pr`              | 浏览 Diff（`/lg` 仅 TUI）/ 显式刷新当前分支 PR |
+| `/copy-all`                | 复制当前分支可见对话                           |
 
 <details>
 <summary><strong>模型工具速查</strong></summary>
 
-| 工具                                                                                                     | 用途                                |
-| -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `bg_start`, `bg_status`, `bg_list`, `bg_watch`, `bg_kill`                                                | 后台进程生命周期                    |
-| `subagent_spawn`, `subagent_check`, `subagent_list`, `subagent_wait`, `subagent_send`, `subagent_cancel` | 独立子 Agent                        |
-| `workflow`, `workflow_status`, `workflow_stop`                                                           | 动态多阶段编排与运行管理            |
-| `tasks_add`, `tasks_update`, `tasks_list`                                                                | Session 工作项                      |
-| `get_goal`, `create_goal`, `update_goal`                                                                 | Session Goal                        |
-| `context_pivot`                                                                                          | Context 阶段切换                    |
-| `ask_user`                                                                                               | TUI/RPC 中带草稿与提交前复核的结构化用户决策 |
-| `human_handoff`                                                                                          | 等待用户专属操作并返回待验证的状态          |
-| `plan_ready`                                                                                             | 显式完成计划，不自动开始实施                |
-| `fd`, `rg`                                                                                               | 文件发现与内容搜索                  |
-| `configure_my_pi_setup`                                                                                  | 受限配置写入                        |
-
-</details>
-
----
-
-## 设计原则
-
-### Pi-native first
+Capability discovery 默认是 `explicit`：普通父 Session 不常驻任何 OpenPI 模型工具，首轮保持 Pi 原生 `read`、`bash`、`edit`、`write`。用户明确要求结构化搜索、Subagent、Workflow、后台进程或 Session Goal/Tasks 时，OpenPI 在 `before_agent_start` 直接加载对应能力组；明确询问 OpenPI capabilities/tools/features 时显示 `openpi_load_tools`。可通过 `/openpi-setup` 显式选择 `adaptive`：此时只让小型 `openpi_load_tools` 网关常驻，模型可在判断任务确实受益时自主加载一个能力组。该选择也授权模型启动该组内的昂贵工作，因此不作为默认值。条件句（例如 “If you delegate…”）不会被当成显式委派意图。能力组在当前 Session 内单调保持，避免反复增删工具破坏缓存。组内管理工具仍只在资源成功创建或状态确实存在后出现。Mode / Setup / Context 工具独立跟随实时状态显示和隐藏。Background、Subagent 与 Workflow 的 Skill 文件仍随包发布，但只在对应能力触发后提示读取，不常驻普通系统 Prompt。
 
-子 Agent 是 Pi SDK Session，不是独立 CLI。Provider、模型、Skills、Trust 与普通 child-safe 工具沿用用户已有环境；编排、交互和父级状态工具明确移除。
+普通产品默认采用 Pi-native execution：保留 Pi 原生完整历史、工具输出上限、Session compaction、显式 Bash timeout 与 provider loop，不再额外做固定事务投影、成功 Bash 二次裁剪、测试 timeout 改写、重复失败硬拦或恢复/轨迹提示。OpenPI 只保留独立的工作区安全边界：阻止未授权删除 pre-existing 路径，并从实际文件状态识别本轮通过原生写入、文字重定向或 literal `mkdir -p` 创建的 scratch，避免误拦其清理。旧执行策略仅保留为受 benchmark root 门控的实验 profile，不会进入普通 Session。
 
-### Context 有明确去向
+| 工具                                                                                                     | 用途                           | 可见时机                         |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------- |
+| `openpi_load_tools`                                                                                      | 列出或加载可选工具组           | 明确询问；或启用 `adaptive`      |
+| `bg_start`, `bg_status`, `bg_list`, `bg_watch`, `bg_kill`                                                | 后台进程生命周期               | 明确意图或 adaptive；启动后展开  |
+| `subagent_spawn`, `subagent_check`, `subagent_list`, `subagent_wait`, `subagent_send`, `subagent_cancel` | 独立子 Agent                   | 明确意图或 adaptive；创建后展开  |
+| `workflow`, `workflow_status`, `workflow_stop`                                                           | 动态多阶段编排与运行管理       | 明确意图或 adaptive；运行后展开  |
+| `tasks_add`, `tasks_update`, `tasks_list`                                                                | Session 工作项                 | 明确意图或 adaptive；存在后展开  |
+| `get_goal`, `create_goal`, `update_goal`                                                                 | Session Goal                   | 明确意图或 adaptive；存在后展开  |
+| `context_pivot`                                                                                          | Context 阶段切换               | Context 达到阈值时               |
+| `ask_user`, `human_handoff`                                                                              | 经复核的用户决策与用户专属操作 | Plan 或 Setup 进行中             |
+| `plan_ready`                                                                                             | 显式完成计划，不自动开始实施   | Plan 调研阶段                    |
+| `fd`, `rg`                                                                                               | 文件发现与内容搜索             | 明确意图或 adaptive 加载 search  |
+| `configure_my_pi_setup`                                                                                  | 受限配置写入                   | `/openpi-setup` 进行中           |
 
-一项委派交给 Subagent；多阶段依赖交给 Workflow；阶段变化用 Context Pivot；真正跨 Session 用 Handoff；下一步建议只停留在编辑器 UI。
-
-### 后台能力必须可见，也必须能停
-
-Terminal、Subagent、Workflow 都有 ID、状态、检查入口、取消路径、有界 Shutdown 和一次性完成通知。无界后台工作不属于“方便”，只是把问题藏起来。
+</details>
 
-### 少猜一次，多拒绝一次
+### 可选主题
 
-不可证明只读就不 Replay，不能确认干净就不删 Worktree，损坏的高优先级角色定义不 fallback。拒绝会留下可见错误；猜错可能留下错误代码、旧结果或丢失数据。
+包内注册 `github-dark-default`，但不自动切换。通过 Pi `/settings` 选择即可。
 
 ---
 
@@ -527,117 +462,88 @@ Terminal、Subagent、Workflow 都有 ID、状态、检查入口、取消路径
 <details>
 <summary><strong>安装后会自动调用额外模型吗？</strong></summary>
 
-不会。Next-action suggestion 默认关闭；只有用户通过 `/my-pi-setup` 显式选择模型后，完整主 Agent Run 结束时才可能增加一次小型预测调用。Subagent 与 Workflow 也只在任务实际触发时运行。
+默认不会。Suggestion 默认关闭；Capability discovery 默认 `explicit`。如果用户显式开启 `adaptive`，网关本身不发模型请求，但主模型可以自主加载 Subagent 或 Workflow 并启动额外模型调用；并发和 Workflow 总调用上限仍然生效。
 
 </details>
 
 <details>
-<summary><strong>Pi Subagent 会阻塞主 Agent 吗？</strong></summary>
+<summary><strong>Subagent 会阻塞主 Agent 吗？</strong></summary>
 
-不会。`subagent_spawn` 立即返回，结束后自动回传。只有显式调用 `subagent_wait` 才会等待；它只适合下一步确实依赖结果的场景。
+`subagent_spawn` 立即返回，结束后自动回传。只有显式调用 `subagent_wait` 才会等待；它只适合下一步确实依赖结果的场景。
 
 </details>
 
 <details>
 <summary><strong>为什么同时提供 Subagent 和 Workflow？</strong></summary>
 
-Subagent 是一项可继续对话的自包含委派；Workflow 是多阶段编排，强调 fan-out、结构化结果、可恢复执行和持久产物。前者可以接管继续，后者更适合自动化流水线。
-
-</details>
-
-<details>
-<summary><strong>Plan Mode 下为什么 `git log` 能运行，`npm install` 不能？</strong></summary>
-
-Plan Mode 不分析“任意 Shell 是否只读”，而只放行由已知安全零件组成的命令。它允许窄白名单中的 `git` / `gh` 查询形式；Shell 元字符、未知 flag、安装、写入和无法证明的形式全部拒绝。这里的方向是单向的：放行意味着已证明只读，拒绝只表示未能证明。
-
-Plan Mode 仍可启动只读 Subagent，但会把工具收窄到发现工具；`subagent_send` 和 Workflow 会被拦截，因为它们可能恢复或创建拥有写权限的执行路径。
+Subagent 是一项可继续对话的自包含委派；Workflow 是多阶段编排，强调 fan-out、结构化结果、恢复、验收与持久产物。前者可以接管继续，后者更适合自动化流水线。
 
 </details>
 
 <details>
-<summary><strong>配置和升级会互相覆盖吗？</strong></summary>
+<summary><strong>Plan Mode 为什么允许 git log，却拒绝 npm install？</strong></summary>
 
-不会。包代码、Pi 自己的模型认证与 `~/.pi/agent/my-pi-setup.json` 相互分离。更新仓库不会重写用户配置。
+Plan Mode 不猜“任意 Shell 是否只读”，只放行由已知安全零件组成的命令。窄白名单内的 Git / GitHub 查询可以通过；Shell 元字符、未知 flag、安装、写入和无法证明的形式全部拒绝。
 
 </details>
 
 <details>
 <summary><strong>后台服务会不会变成孤儿进程？</strong></summary>
 
-正常的 `/new`、`/resume`、`/fork`、`/reload` 和退出都会触发 Session Shutdown。扩展会终止后台进程树并清理临时日志；也可随时用 `bg_kill` 或 `/ps` 手动管理。
+正常的 `/new`、`/resume`、`/fork`、`/reload` 与退出都会触发 Session Shutdown。扩展会终止后台进程树并清理临时日志；也可随时用 `bg_kill` 或 `/ps` 管理。
 
 </details>
 
 <details>
 <summary><strong>这是稳定 API 吗？</strong></summary>
 
-这是持续实际使用的独立发行版，不承诺扩展 API 永远不变。改动会经过 TypeScript、格式检查和专项测试；Pi 上游变化时，优先保持 Session 生命周期、工具边界、结果去重和资源清理这些行为不变量。
+这是持续实际使用的独立发行版，不承诺扩展 API 永远不变。改动会经过 TypeScript、格式检查与专项测试；Pi 上游变化时，优先保持 Session 生命周期、工具边界、结果去重与资源清理这些行为不变量。
 
 </details>
 
 ---
 
-## 仓库结构
+## 仓库结构与开发
 
 ```text
 extensions/
-├── setup/                 # /my-pi-setup 与受限配置工具
+├── setup/                 # /openpi-setup 与受限配置工具
+├── capabilities/          # 最小能力发现入口与 Session 工具面加载
 ├── background-terminals/  # 长进程、日志、/ps
 ├── subagents/             # Pi-native Backend、角色、/subagents
-├── workflows/             # DSL、Runner、Sandbox、Replay、Artifacts
-├── tasks/                 # Session 工作项
-├── goal/                  # 持久自主 Goal
+├── workflows/             # DSL、Ledger、Graph、Replay、Artifacts
+├── tasks/ + goal/         # 工作项与持续目标
 ├── context-pivot/         # 定向 Compaction
-├── plan-mode/             # 只读调研与批准门禁
-├── cron/                  # Session 内定时 Prompt
-├── post-edit/             # 成功编辑后的可选命令
-├── sessions/              # Session 搜索与切换
-├── ask-user/              # 结构化用户输入
+├── plan-mode/ + cron/     # 批准门禁与 Session 定时 Prompt
+├── ask-user/              # Reviewed input 与 Human Handoff
 ├── file-search/           # fd / rg 与安全二进制获取
-├── file-mutation-display/ # Bash / Write / Edit 紧凑渲染
+├── sessions/              # Session 搜索与切换
 ├── suggestions/           # Ephemeral next-action suggestion
-├── git-info/              # Git、PR 与 /lg
-├── model-info/            # Model、Context、Cost、Throughput
-├── turn-time/             # Turn 耗时
 ├── ui-customization/      # Header、Footer、Terminal title
-├── copy-all/              # 可见对话复制
 └── shared/                # Child policy、配置、Worktree、终端清洗
 
-skills/
-├── background-terminals/
-└── subagents/
-
-themes/
-└── github-dark-default.json
+skills/                    # Background terminal、Subagent 与 Workflow 指南
+themes/                    # github-dark-default
 ```
 
-扩展通过 Pi Event Bus 和小型共享状态通信。长生命周期资源绑定 Session Shutdown；Workflow JavaScript 在独立 Permission Sandbox 中运行；Agent child 使用 Pi SDK Session 和 Trust-aware Resource Loader。
-
----
-
-## 开发与验证
+开发工具链使用 Bun `1.3.14` 管理依赖和脚本，Biome 负责 TypeScript / JavaScript / JSON 格式与基础 lint；产品运行时仍是 Node，测试仍由 `node:test` 与 Vitest 执行：
 
 ```bash
-npm install
-npm run check
-npm run format:check
-npm test
+bun install --frozen-lockfile
+bun run check
+bun run test
 ```
 
-测试覆盖进程树终止与竞态、Subagent 生命周期与工具边界、Workflow Sandbox/Replay/Acceptance、Worktree 数据保全、文件搜索二进制校验、Session 状态恢复、配置迁移和 TUI 渲染。
+npm 仍用于发布包的 `pack` / clean-install 验证，因为用户通过 npm Registry 安装 OpenPI。
 
-设计记录与多模型评估见 [`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 边界。
+测试覆盖进程树终止与竞态、Subagent 生命周期与工具边界、Workflow Sandbox / Ledger / Graph / Replay / Acceptance、Worktree 数据保全、Session 状态恢复、配置迁移和 TUI 渲染。设计记录见 [`docs/design/`](docs/design/)，问题请提交到 [GitHub Issues](https://github.com/tt-a1i/openpi/issues)。
 
 ---
 
-## 来源与致谢
+## 来源、许可与致谢
 
 本项目最初基于 [davis7dotsh/my-pi-setup](https://github.com/davis7dotsh/my-pi-setup) 演进，现作为独立发行版维护。感谢原作者提供起点。
 
 `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)。
 
 本仓库目前没有项目级开源许可证；`THIRD_PARTY_NOTICES.md` 只记录第三方来源与各自许可，不等同于授予本项目使用许可。
-
-<p align="center">
-  <strong>Small harness. Deep extensions. Clean context.</strong>
-</p>