默认轻，按需强

OpenPI 最强的地方，不是工具多，而是复杂度只在值得的时候出现。

普通编码任务继续走 Pi 原生路径：read、bash、edit、write，完整历史、Session compaction、工具输出边界、显式 Bash timeout 与 Provider loop。OpenPI 不额外投影历史，不改写测试超时，也不向模型塞恢复提示；只保留独立的工作区删除保护。

任务一旦需要长期进程、并行调研、隔离实现、多阶段协作或跨回合推进，高级能力仍然完整存在。用户直接提出需求，OpenPI 就在当轮加载对应能力；没用到的能力不会常驻模型工具面。

轻路径不缴复杂度税，重任务不缺工程能力。 这不是一套替代 Pi 的 Agent Runtime，而是一组遵守 Pi 生命周期、Session、Provider、模型与 Trust 边界的 Pi-native 深扩展。

| 使用场景 | 模型看到什么 | OpenPI 的行为 | | ---------------------------- | ------------------------------------------------- | ------------------------------------------------- | | 普通编码任务 | Pi 原生 read / bash / edit / write | 默认不常驻任何 OpenPI 模型工具 | | 用户明确要求委派或高级能力 | 仅与意图匹配的能力组 | 在当轮开始前直接加载，不要求用户记住工具名 | | 用户主动开启 adaptive | 一个小型 openpi_load_tools 网关 | 主模型判断确有收益时，可自主加载一个能力组 | | 后台任务或子 Agent 已经运行 | 对应的状态、等待、继续与停止工具 | 管理面随真实资源出现，资源结束后按生命周期收敛 |

这套设计保住了两件通常很难同时拥有的东西：Pi 的清爽基本面，以及完整工程工作台的能力上限。

30 秒开始

pi install npm:@tt-a1i/openpi

重启 Pi，或在当前 Session 运行 /reload。然后直接描述真实任务：

在后台启动前端 dev server；用子代理并行检查 API 主链路和测试覆盖；
结果回来后汇总风险，主会话不要原地等待。

OpenPI 会把长期进程放到后台，把独立任务交给隔离 Context 的 Pi Subagent，把多阶段依赖组织成 Workflow。状态会持续显示；完整运行可从 /ps、/subagents 和 /workflows 检查或终止。

[!TIP] Capability discovery 默认 explicit：明确说出能力意图才会加载对应组。英文 subagent 与 workflow 是保留授权词，单独输入也会加载对应能力。 例如 subagent, workflow → 同时加载两组；「在后台运行 dev server」→ 后台终端；「用/使用子代理检查」→ Subagent；「用工作流编排」→ Workflow；「用 fd/rg 搜索」或「用 git diff 比较分支」→ 搜索与只读 Git 工具。 关键是把意图说清楚（说「用子代理」「后台运行」这类带动作的短语），不需要记住任何工具名。 在交互输入框中，保留词 Subagent / Workflow，以及已被识别的中文能力请求，会使用 Claude Code 风格的薰衣草紫显示；浅色终端自动使用更深的紫色以维持可读性。变色表示提交后会加载对应能力。因为英文名称本身就是授权词，讨论中写出它们也会开闸；条件句和否定句仍保持普通显示，Suggestion 幽灵文字也要在用户接受进输入框后才参与识别。

[!IMPORTANT] 默认安装是安静的：不改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。Capability discovery 默认 explicit；只有用户通过 /openpi-setup 选择 adaptive 后，模型才会常驻看到一个小型发现网关并可自主加载额外能力。

/openpi-setup

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、只读 Git 工具 | | 人类决策 | ask_user 草稿与最终复核、parent-only human_handoff、Plan Ready 实施门禁 | | 跨 Session | 可选 parent-only pi-intercom；父子通信仍走 Subagent / Workflow 原生通道 | | 统一配置 | /openpi-setup 管理 OpenPI 自有模型、并发、Footer、输出密度与 Post-edit 偏好 |

OpenPI 采用 MIT License；第三方来源与保留声明见 THIRD_PARTY_NOTICES.md。

运行模型

主 Pi Session 始终拥有用户交互、配置和生命周期。Terminal、Subagent 与 Workflow 是三条执行路径；Tasks、Goal、Session 和 Context Pivot 保持连续性；Footer、Dashboard、Artifacts 与清理逻辑负责观察和控制。

一项任务应该去哪里？

长期进程                         → Background Terminal
一项自包含、可继续对话的委派     → Subagent
多阶段、依赖、fan-out 与综合      → Workflow
跨回合工作项                     → Tasks
持续自主目标                     → Goal
同一 Session 的阶段切换          → Context Pivot
真正跨顶层 Session               → pi-intercom（可选）

三条执行路径

Background Terminal：长期进程不阻塞 Agent

bg_start({
  command: "npm run dev",
  title: "web dev server"
})

• stdout / stderr 独立捕获，完整日志有私有、有界的临时落盘；
• /ps 查看状态，bg_kill 终止整个进程树；
• 进程退出后自动通知，不需要轮询；
• build、test、migration 可设置 timeout_seconds；
• server 和 watcher 不设超时，可用 bg_watch 等待 Ready in|Traceback|ERROR；
• 最多同时运行 8 个后台终端，Reload 或 Session Shutdown 时统一清理。

后台进程没有 stdin。需要交互输入的命令应由用户直接运行，而不是放进后台。

前台执行沿用 Pi 的 Bash 合同：timeout 可选且没有统一默认值，是否设置以及设置多长由模型或用户按命令语义决定。OpenPI 不再通过正则改写测试命令 timeout；确实需要有界执行时应显式传入 timeout，长期运行的 build、test、migration 或 server 可使用 Background Terminal 的生命周期能力。

Pi-native Subagent：隔离 Context，不另起系统

subagent_spawn({
  agent_type: "explorer",
  name: "audit auth flow",
  prompt: "Trace src/auth end to end and report file:line evidence."
})

每个 Subagent 都是新的进程内 Pi SDK Session：

• 默认继承父会话的 Provider 与模型；用户可明确指定 Thinking Level，否则模型根据角色建议、任务难度与目标模型实际支持的档位选择；
• 继承普通 child-safe 工具、Skills、项目说明与 Trust 决策；
• 最多 4 个模型发起的 Subagent 并发运行，结束后自动回传；
• 可 check、wait、cancel，也可用 subagent_send 继续同一子会话；
• 输入框下方显示实时摘要，空输入时按 ↓ 聚焦，Enter 或 → 打开管理界面。

内置角色由 Harness 强制工具边界，不靠 Prompt 自律：

| agent_type | 适合 | 相对 effort 建议 | 强制能力 | | ------------- | ---------------- | ------------------- | ----------------------------- | | explorer | 代码追踪与探索 | 中等，难题可提高 | 只读发现工具 | | implementer | 聚焦实现 | 中高，按范围与风险调整 | read / bash / edit / write 等 | | reviewer | 正确性与回归审查 | 较高 | 只读发现工具 | | advisor | 深度技术建议 | 较高 | 只读发现工具 |

上述只是模型的相对选择提示，不会为内置角色写死具体档位。用户明确指定的 reasoning_effort 始终优先；否则模型结合任务难度，从目标模型实际支持的档位中选择。

角色可由全局 ~/.pi/agent/agents/*.md 或受信任项目 .pi/agents/*.md 覆盖。模型优先级是：显式调用 > Agent Type 文件 > /openpi-setup 角色模型 > 父模型继承。更高优先级定义损坏时会阻断 fallback，而不是悄悄退回更宽松的能力。

默认并行 Agent 共享 checkout 与 git index。只读 fan-out 不受影响；并行写入应使用：

subagent_spawn({
  name: "implement retry",
  isolation: "worktree",
  prompt: "Implement the retry path, test it, and commit the result."
})

Worktree 建在 .git/pi-worktrees/，拥有独立 checkout 与分支。已提交工作会删除 checkout、保留分支；dirty、untracked、ignored 文件，detached HEAD，Git 探测失败或超时都会保留现场。只有完整证明为空时才回收。

全新 checkout 不包含 .env 或其他 gitignored 内容。可用时 OpenPI 会在 worktree 中建立 node_modules 依赖 symlink。

Dynamic Workflow：让多 Agent 工作有阶段、有证据、有产物

单个 Subagent 负责一项委派。Workflow 处理阶段依赖、动态 fan-out、结构化结果、恢复与综合：

phase("Scan");
const checked = await pipeline(
  files,
  (file) =>
    agent(`Trace ${file} for reliability risks`, {
      agent_type: "explorer",
      label: `scan:${file}`,
      schema: FINDING_SCHEMA,
    }),
  (scan, file) =>
    scan.ok
      ? agent(`Verify findings in ${file}`, {
          agent_type: "reviewer",
          label: `verify:${file}`,
          inputs: [scan.ref],
        })
      : null,
);

phase("Report");
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、缓存、成本及本轮并发/调用余量；Token 是 lower bound，不是预算器 | | agent() | 启动 Pi Agent；支持 role、schema、acceptance、inputs、operator 与 worktree | | pipeline() | 每个 item 完成上阶段后立即进入下一阶段；多阶段 fan-out 的默认选择 | | parallel() | 并发 barrier；只在下一阶段确实需要全部结果时使用 |

Workflow 默认并发 8 个 Agent，单次最多 128 次调用；可配置到 64 和 1024。前台运行可实时查看，后台运行完成后自动回传；/workflows 展示阶段、Agent、Transcript、Graph、用量与产物。

Workflow 不只是并行

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 或未知自定义工具；
• 使用 per-call Worktree；
• ignored 文件可能影响结果却无法纳入指纹；
• Journal、资源、路径、并发重叠或指纹状态不确定。

匹配依据是调用内容，不是并发完成顺序。失败调用不缓存；Journal 有 2 MiB 上限。

Operator Continuity

operator: "name" 在同一 Run 内复用一个内存 Child Session，并把同名 activation 串行化。首个 activation 固定 model、role/tool surface、effort、structured mode 与 cwd。Operator 不与 per-call Worktree 或 Replay 混用，也不承诺跨重启持久记忆。

Explicit Acceptance

可选 acceptance: { criteria: [...] } 要求同一个 Agent 返回 evidence ledger。条件缺失、格式错误或被拒绝时，调用返回 ok: false，但原始输出与 ledger 仍保留。OpenPI 不会暗中再启动 reviewer、Shell 或额外 Judge 模型。

Worktree Handoff

Workflow 在清理隔离 checkout 前原子保存有界 Handoff Manifest：tracked binary patch、stat、branch/HEAD、untracked/ignored 清单与 cleanup receipt。状态不明就保留现场，不自动 merge、apply 或强删。

设计细节见 docs/design/WORKFLOW_INVOCATION_GRAPH.md。

连续工作，而不是堆 Context

| 能力 | 使用方式 | 它负责什么 | | ------------- | --------------------------------------- | ------------------------------------------------------------------- | | 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 | 收集经复核的决策，或等待只有用户能完成的外部操作 |

Tasks 是咨询性记录，Goal 是持续目标，Subagent 与 Workflow 才执行工作。文件、Git、测试、Artifacts 和用户确认始终是事实来源。

Next-action Suggestion 是可选的：完整主 Agent Run 结束后，在空编辑器显示一条暗色 inline 建议；Right 只填入、不提交，其他输入取消。它默认关闭，不写入 Session，也不进入模型 Context。

终端体验

默认 Footer 把真实运行状态压进一行，指标自带小图标（无需 Nerd Font):

 model   context                ⎇ git  PR   cwd

Footer 使用一套 Codicon 线性图标： 模型、 context、 目录；⎇ 表示分支。thinking、cache、cost、throughput 也是可选指标，可通过 /openpi-setup 加入自定义布局。未安装包含 Codicons 的 Nerd Font 时，图标可能显示为空框，但后面的文字指标仍然完整可读。

• 默认把高频的模型与 context 放在最左侧，把项目定位信息归到右侧，并以当前目录作为最右锚点；支持 powerline、powerline-mono、compact，也支持自定义多行布局；
• 终端变窄时按优先级隐藏次要指标，不机械截断尾部；
• Subagent 与 Workflow 活动时自动出现，空闲时不占空间；
• Bash、Write/Edit 与 Subagent 结果可独立选择 full 或 compact；普通 read、grep、find、ls 以及 compact Bash/Write/Edit 默认显示一行语义活动摘要，包含目标、状态与关键规模；Nerd Font 可为读取、终端、编辑、搜索和目录动作显示 Codex 风格线框图标，未安装时动词与全部信息仍保持可读；
• 折叠内容用 Pi 的 app.tools.expand 快捷键临时展开（默认 Ctrl+O），展开后直接恢复 Pi 原生参数、输出、错误、diff、耗时与 full-output 证据；
• Git 状态本地刷新；只有显式运行 /pr 才查询 GitHub PR。

fd 与 rg 是结构化模型工具，不拼接 Shell。它们默认遵守 .gitignore，支持 Glob、类型、Smart Case、固定字符串与上下文。git_show、git_diff、git_log 以结构化参数提供只读提交、差异和历史检查，并禁用仓库配置的 external diff/textconv。两类工具的输出均限制为 50 KiB / 2000 行，完整截断内容最多私有保存 10 MiB，并在 Session Shutdown 时清理。

macOS/Linux arm64 与 x64 缺少二进制时，OpenPI 会从官方 Release 下载固定版本、校验 SHA-256 后原子安装。其他平台需自行提供 fd 与 rg。

安全边界

这里的安全不是一段 Prompt，而是运行时约束。

| 边界 | 行为 | | ---------------- | ------------------------------------------------------------------------- | | 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 只在顶层 Pi Session 加载。它使用进程级身份，而 OpenPI Child 是同一进程内的并发 Session；Child Resource Loader 会移除 pi-intercom 扩展与 Skill，避免身份串线。Replay 也不会复用其调用。

配置与参考

一个配置入口

/openpi-setup
/my-pi-setup  # legacy alias

无参数时，OpenPI 展示当前状态并引导修改；带自然语言时只改指定项：

/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，与包代码分离，升级不会覆盖。

一次 /openpi-setup episode 最多成功写入一次；成功后配置工具立即隐藏。若随后还要修改另一项，请重新执行 /openpi-setup <自然语言请求>，不要让模型重调已隐藏工具，也不要绕过入口直接编辑配置文件。

| 配置 | 默认值 | | ---------------------------- | ---------------------------------------------- | | Capability discovery | explicit；adaptive 必须显式开启 | | Next-action Suggestion | 关闭；启用时显式选择 Registry 模型与 reasoning | | Workflow 并发 / 总调用 | 8 / 128；硬上限 64 / 1024 | | 大型 Header | 关闭 | | Dashboard Footer | 开启；单行 plain | | Subagent / Bash / Write/Edit | full / compact / compact | | Post-edit 命令 | 关闭；单条命令最多 500 字符 | | 内置角色模型 | 全部继承父模型 | | pi-intercom | 不静默安装；由用户明确选择 | | 主题 | 保留用户现有选择 |

安装要求与来源

• Pi 0.84.1 或更新版本；
• Node.js 22.19.0 或更新版本；
• npm 安装：pi install npm:@tt-a1i/openpi；
• GitHub 安装：pi install git:github.com/tt-a1i/openpi。

开发运行时：区分 npm 与当前源码

npm 制品、GitHub 安装和本地 checkout 是三个不同的运行资产。源码目录更新、测试通过或版本号相同，都不能证明当前 Pi 已经加载这份代码。所有本地开发、Provider 兼容排查、手工 smoke 和 UI 验收都使用下面这一条证据链。

1. 先固定源码和加载来源

git status --short --branch
git rev-parse --short HEAD
pi list

完成标准：知道正在修改哪个 checkout、分支和提交；pi list 中只有一个 OpenPI 来源，并能明确它是 npm、GitHub 还是某个本地绝对路径。其他 Pi package（例如 pi-intercom）不属于重复 OpenPI 来源。

2. 开发时让 Pi 直接加载当前 checkout

git clone https://github.com/tt-a1i/openpi.git ~/work/openpi
cd ~/work/openpi
bun install --frozen-lockfile

# 若 pi list 显示了旧 OpenPI，把变量设为它显示的 package spec 或绝对路径。
OLD_OPENPI_SOURCE=/absolute/path/to/old/openpi
pi remove "$OLD_OPENPI_SOURCE"
pi install "$PWD"
pi list

已经安装当前 checkout 时，不需要反复 remove/install。切换分支或修改源码后，运行 /reload 或重启 Pi 才会重载扩展。/reload 之前的界面和工具集合只证明旧内存状态。

完成标准：pi list 唯一的 OpenPI 路径就是当前 checkout，且该路径的 HEAD 与预期提交一致。不要修改 ~/.pi/agent/npm/node_modules/@tt-a1i/openpi 来冒充源码修复。

3. 分层验证改动

# 开发环：先运行与改动最接近的测试，并沿用 package.json 的 runner。
node --test --experimental-strip-types path/to/relevant.test.ts
bunx vitest run path/to/relevant.spec.ts

# 仓库门禁：提交或交付前两项都要通过。
bun run check
bun run test

自动化通过只证明代码、类型和测试合同。涉及运行时或界面时，还要在已 /reload 的真实 Pi 中完成对应 smoke：

• 工具或生命周期改动：在普通工具模式实际触发成功、失败和结束路径；
• Provider 兼容改动：保留正常工具 Schema，不用 --no-tools 绕过问题；
• UI 改动：在真实 TUI 触发目标状态并肉眼检查，必要时保存截图；
• 配置改动：通过 /openpi-setup 写入，再核对无参数状态输出和实际行为。

完成标准：分别记录 checkout HEAD、pi list 来源、专项测试、bun run check、完整测试和手工 smoke。没有执行的层级写成“未验证”，不能用另一层的绿色结果代替。

4. 保持工作区可恢复

• 开始前检查 dirty worktree；保存用户的未提交、未跟踪和 ignored 文件；
• 本地 Benchmark、日志和原始结果可以通过 .git/info/exclude 隐藏，但 ignore 不是备份；
• 使用 git clean -nd 只能预览普通未跟踪文件；不要运行会删除 ignored 资产的 git clean -fdx；
• 稳定运行副本和开发 checkout 只有在确有隔离需求时才并存，并始终用 pi list 说明 Pi 加载哪一个；
• 提交前复查 diff，确保本地配置、密钥、模型结果和评测原始数据没有进入版本控制。

Host SDK 与 TypeBox 按 Pi Package 契约声明为 Peer Dependencies；仓库开发依赖不随包重复提供。

可选：顶层 Pi Session 通信

运行 /openpi-setup，在原生确认框中选择安装；也可手动执行：

pi install npm:pi-intercom

新私有配置默认 confirmSend: true、inboundTrigger: "replies"；已有配置绝不重写。安装失败不显示成功，也不写配置；安装后需 /reload。跨顶层 Session 用 pi-intercom，父子委派继续使用 subagent_* 与 Workflow 原生结果通道。

命令速查

| 命令 | 作用 | | -------------------------- | ---------------------------------------------- | | /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 | 复制当前分支可见对话 |

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 内单调保持，避免反复增删工具破坏缓存。Delegate 一经加载便一次性开放完整、稳定的 Subagent 工具族；资源不存在时由工具执行层明确返回空状态或 fail-closed，而不再按实例生命周期改变模型接口。其他组内管理工具仍只在资源成功创建或状态确实存在后出现。Mode / Setup / Context 工具独立跟随实时状态显示和隐藏。Background、Subagent 与 Workflow 的 Skill 文件仍随包发布，但只在对应能力触发后提示读取，不常驻普通系统 Prompt。

普通产品默认采用 Pi-native execution：保留 Pi 原生完整历史、工具输出上限、Session compaction、显式 Bash timeout 与 provider loop，不再额外做固定事务投影、成功 Bash 二次裁剪、测试 timeout 改写、重复失败硬拦或恢复/轨迹提示。OpenPI 只保留独立的工作区安全边界：阻止未授权删除 pre-existing 路径，并从实际文件状态识别本轮通过原生写入、文字重定向或 literal mkdir -p 创建的 scratch，避免误拦其清理。旧执行策略仅保留为受 benchmark root 门控的实验 profile，不会进入普通 Session。

| 工具 | 用途 | 可见时机 | | -------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------- | | 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, git_show, git_diff, git_log | 文件、内容与只读 Git 检查 | 明确意图或 adaptive 加载 search | | configure_my_pi_setup | 受限配置写入 | /openpi-setup 进行中 |

可选主题

包内注册 github-dark-default，但不自动切换。通过 Pi /settings 选择即可。

FAQ

默认不会。Suggestion 默认关闭；Capability discovery 默认 explicit。如果用户显式开启 adaptive，网关本身不发模型请求，但主模型可以自主加载 Subagent 或 Workflow 并启动额外模型调用；并发和 Workflow 总调用上限仍然生效。

subagent_spawn 立即返回，结束后自动回传并重新唤醒主 Agent。交互会话没有其他工作时，主 Agent 应结束当前轮、让用户继续交互；“下一步依赖结果”本身不是阻塞理由。只有用户明确要求当前回复等完，或非交互自动化必须在同一次调用中返回完整结果时，才应调用 subagent_wait。

Subagent 是一项可继续对话的自包含委派；Workflow 是多阶段编排，强调 fan-out、结构化结果、恢复、验收与持久产物。前者可以接管继续，后者更适合自动化流水线。

Plan Mode 不猜“任意 Shell 是否只读”，只放行由已知安全零件组成的命令。窄白名单内的 Git / GitHub 查询可以通过；Shell 元字符、未知 flag、安装、写入和无法证明的形式全部拒绝。

正常的 /new、/resume、/fork、/reload 与退出都会触发 Session Shutdown。扩展会终止后台进程树并清理临时日志；也可随时用 bg_kill 或 /ps 管理。

这是持续实际使用的独立发行版，不承诺扩展 API 永远不变。改动会经过 TypeScript、格式检查与专项测试；Pi 上游变化时，优先保持 Session 生命周期、工具边界、结果去重与资源清理这些行为不变量。

仓库结构与开发

extensions/
├── setup/                 # /openpi-setup 与受限配置工具
├── capabilities/          # 最小能力发现入口与 Session 工具面加载
├── background-terminals/  # 长进程、日志、/ps
├── subagents/             # Pi-native Backend、角色、/subagents
├── workflows/             # DSL、Ledger、Graph、Replay、Artifacts
├── tasks/ + goal/         # 工作项与持续目标
├── context-pivot/         # 定向 Compaction
├── plan-mode/ + cron/     # 批准门禁与 Session 定时 Prompt
├── ask-user/              # Reviewed input 与 Human Handoff
├── file-search/           # fd / rg 与安全二进制获取
├── git-read/              # 只读 git show / diff / log
├── sessions/              # Session 搜索与切换
├── suggestions/           # Ephemeral next-action suggestion
├── ui-customization/      # Header、Footer、Terminal title
└── shared/                # Child policy、配置、Worktree、终端清洗

skills/                    # Background terminal、Subagent 与 Workflow 指南
themes/                    # github-dark-default

开发工具链使用 Bun 1.3.14 管理依赖和脚本，Biome 负责 TypeScript / JavaScript / JSON 格式与基础 lint；产品运行时仍是 Node，测试仍由 node:test 与 Vitest 执行：

bun install --frozen-lockfile
bun run check
bun run test

npm 仍用于发布包的 pack / clean-install 验证，因为用户通过 npm Registry 安装 OpenPI。

测试覆盖进程树终止与竞态、Subagent 生命周期与工具边界、Workflow Sandbox / Ledger / Graph / Replay / Acceptance、Worktree 数据保全、Session 状态恢复、配置迁移和 TUI 渲染。设计记录见 docs/design/，问题请提交到 GitHub Issues。

来源、许可与致谢

本项目最初基于 davis7dotsh/my-pi-setup 演进，现作为独立发行版维护。感谢原作者提供起点。

extensions/sessions/ 改编自 jayshah5696/pi-agent-extensions。可选的顶层 Session 通信由 pi-intercom 提供。完整第三方说明见 THIRD_PARTY_NOTICES.md。

本项目以 MIT 许可证发布（见 LICENSE）；THIRD_PARTY_NOTICES.md 记录第三方来源与各自许可。