Pi-Mono

极简终端编码 harness 的 monorepo——自扩展、不 fork，缺功能让 agent 自己造

更新于 2026-08-14 · 作者 badlogic（Mario Zechner）

一句话定位

让 agent 适配你的工作流，而不是反过来

Pi 是一个极简终端编码 harness，整个项目以 monorepo 形式提供五件套：统一多 provider LLM API、有状态 agent runtime、差分渲染终端 UI、交互式编码 CLI、遥测契约。核心理念是自扩展——缺 sub-agents / plan mode 这类功能？不 fork 改内核，用 TypeScript Extensions / Skills / Prompt Templates / Themes 扩展，或装第三方 Pi 包。适合不想被某个 agent 工具锁死、追求定制自由的开发者。

Monorepo 五件套架构

分层清晰：底层 LLM API → agent runtime → UI/CLI。每层独立成包，可单独引用。

AgentMessage ↔ LLM Message 双层桥接

Pi 的关键设计：agent 工作在灵活的 AgentMessage 上（支持自定义类型），但 LLM 只懂 user/assistant/toolResult。两个函数桥接这个鸿沟。

这个分层让你能在 agent 内部塞任意结构化消息（Q&A 交互、计划节点、审批记录…），而模型只看到它能理解的标准格式——UI 状态与 LLM 输入解耦。

事件流：prompt 的一生

理解事件序列是构建响应式 UI 的关键。prompt() 触发一个 turn；若调工具，循环继续到下一 turn。

prompt("读 config.json")  # 带工具调用
├─ agent_start
├─ turn_start
│   ├─ message_start/end { userMessage }          # 你的输入
│   ├─ message_start { assistantMessage + toolCall }
│   ├─ message_update { 部分结果… }                # 流式 chunk
│   ├─ message_end { assistantMessage }
│   ├─ tool_execution_start { toolCallId, toolName, args }
│   ├─ tool_execution_update { partialResult }    # 工具流式（若有）
│   ├─ tool_execution_end { toolCallId, result }
│   ├─ message_start/end { toolResultMessage }
│   └─ turn_end { message, toolResults: [toolResult] }
│
├─ turn_start                                     # 下一回合
│   └─ message_start…end { assistantMessage }     # 模型回应工具结果
├─ turn_end
└─ agent_end { messages: [...] }

工具执行模式可配：parallel（默认，预检→并发执行→按源序持久化）或 sequential（逐个执行）。beforeToolCall 可拦截，shouldStopAfterTurn 可在 turn 后决定是否续。

一个 CLI，四种运行形态

交互模式界面：启动头 → 消息区 → 编辑器（边框色表示思考层级）→ 页脚（工作目录/会话/ token 用量/成本/上下文/当前模型）。编辑器可被扩展 UI 临时替换（如结构化 Q&A 工具）。

不 fork，缺什么造什么

Pi 故意不内置 sub-agents 和 plan mode。理由：与其塞一堆「正确答案」功能，不如给你造功能的机制。

缺 sub-agents？装个第三方 Pi 包，或让 agent 自己写一个。内核保持极简，能力由生态组装。

30+ provider，统一接口

pi-ai 抽象层统一了几乎所有主流 LLM provider，且只收录支持 tool calling 的模型（agentic 必需）。

跨 provider handoff：会话中途切模型。自动 auth 解析、token/成本追踪、上下文序列化跨模型传递。任何 OpenAI 兼容 API（Ollama/vLLM/LM Studio）也开箱即用。

无内置权限系统，靠容器隔离

Pi 不内置限制文件系统/进程/网络/凭证的权限系统，默认以启动它的用户/进程权限运行。要强边界？容器化或沙箱化。

详见 packages/coding-agent/docs/containerization.md。

把 npm 依赖当代码审查

• 直接依赖精确锁版——内部 workspace 包保持版本区间，外部直接依赖钉死
• 防同日发布——.npmrc 设 save-exact=true + min-release-age=2，避免供应链投毒的「同日发布」攻击窗口
• lockfile 是真相之源——pre-commit 拦截意外 lockfile 提交（除非 PI_ALLOW_LOCKFILE_CHANGE=1）
• 发布冒烟测试——npm run release:local 在仓库外建隔离的 npm/Bun 安装验证，发布安装和 pi update --self 都用 --ignore-scripts
• 生命周期脚本白名单——shrinkwrap 生成对依赖生命周期脚本有显式白名单，新脚本依赖过不了 check 直到审查

适合谁用

需要权衡

• 安全模型激进——「无内置权限，默认用户权限」对谨慎用户是隐患。沙箱化是可选而非默认，需主动配置容器
• 极简 = 前期手动——开箱功能少于 Claude Code 这类成品（无 sub-agents/plan mode），初学者要花时间组装生态包
• provider 列表庞大但维护重——30+ provider 意味着每家 API 变动都得跟，配置目录需定期刷新（pi update --models）
• Bun/Node 双运行时——独立二进制用 Bun 编译，npm 分发走 Node，双轨增加潜在不一致

三步开跑

# 1. 全局安装（--ignore-scripts 禁用生命周期脚本）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或：curl -fsSL https://pi.dev/install.sh | sh

# 2. 认证（API key 或订阅）
export ANTHROPIC_API_KEY=sk-ant-...   # API key 方式
pi /login                            # 订阅方式（Claude/ChatGPT/Copilot）

# 3. 直接对话，默认 4 工具：read/write/edit/bash
pi

# SDK 嵌入（编程式）
import { Agent } from "@earendil-works/pi-agent-core";
import { createModels } from "@earendil-works/pi-ai";

文档：pi.dev/docs/latest · 源码结构：packages/ 五件套各自独立 README。

未来空间

Pi-Mono 代表了 agent 工具的极简 + 可组合流派——与 DeepSeek Harness 的「重型插件框架」、Claude Code 的「成品优先」形成三足鼎立。它的 AgentMessage/LLM Message 双层桥接、30+ provider 统一抽象、供应链硬化（防同日发布攻击）都是工程上的亮点。风险在单维护者 + 无内置安全的激进选择。若生态（Pi Packages）能起来，会成为「不想被锁定、要自己造轮子」的开发者的首选底盘。