@tt-a1i/openpi

---

默认轻，按需强

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 检查或终止。

[!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
人类决策	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	代码追踪与探索	high	只读发现工具
implementer	聚焦实现	high	read / bash / edit / write 等
reviewer	正确性与回归审查	medium	只读发现工具
advisor	深度技术建议	xhigh	只读发现工具

角色可由全局 ~/.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、缓存与成本的单调 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。

---

终端体验

默认 Powerline Footer 把真实运行状态压进一行：

cwd  model  thinking  context  cache  cost  throughput   git  PR

• 支持 powerline、powerline-mono、compact，也支持自定义多行布局；
• 终端变窄时按优先级隐藏次要指标，不机械截断尾部；
• Subagent 与 Workflow 活动时自动出现，空闲时不占空间；
• Bash、Write/Edit 与 Subagent 结果可独立选择 full 或 compact；Subagent 的 compact 模式只显示状态摘要，不暴露原始子 Agent 正文；
• 折叠内容用 Pi 的 app.tools.expand 快捷键临时展开，默认 Ctrl+O；
• Git 状态本地刷新；只有显式运行 /pr 才查询 GitHub PR。

fd 与 rg 是结构化模型工具，不拼接 Shell。它们默认遵守 .gitignore，支持 Glob、类型、Smart Case、固定字符串与上下文；输出限制为 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。

开发当前源码：

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

安装或更新后重启 Pi，或运行 /reload。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 内单调保持，避免反复增删工具破坏缓存。组内管理工具仍只在资源成功创建或状态确实存在后出现。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	文件发现与内容搜索	明确意图或 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 与安全二进制获取
├── 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。

本仓库目前没有项目级开源许可证；THIRD_PARTY_NOTICES.md 只记录第三方来源与各自许可，不等同于授予本项目使用许可。