Pi Agent Harness 实践

目标：搞清 Pi 是什么层、和手写 loop / [LangGraph](/docs/ai/Agent/LangGraph 编排实践) / Cursor 类产品差在哪、怎么安装与扩展。概念底座见 Agent 核心概念与架构；Skills 格式见 [Agent Skills 概览与实践](/docs/ai/Skills/Agent Skills 概览与实践)。官网：pi.dev，文档：pi.dev/docs。

Pi 是 最小 Agent Harness（套件）：核心很小，靠扩展、Skills、Prompt 模板、主题、npm/git 包去适配你的工作流，而不是反过来让你迁就产品功能清单。

目标与验收

验收项	标准
分层	能说出 `pi-ai` / `pi-agent-core` / `pi-coding-agent` / `pi-tui` 各管什么
对照	能对比「Pi vs LangGraph vs Cursor」：Harness / 编排框架 / 完整 IDE Agent
能跑	`pi` 进项目目录，完成一次带工具的问答
能扩展	知道 Skills、`AGENTS.md`、`SYSTEM.md`、extensions、四种运行模式

它是什么、不是什么

名称	类型	解决什么
Pi	可扩展的 coding agent harness	统一多模型 API + Agent 循环 + TUI/CLI + 可嵌入 SDK
LangGraph	编排框架	用状态图表达规划→行动→观察
Cursor / Claude Code	产品级编码 Agent	编辑器一体、权限弹窗、Plan 模式等开箱功能
手写 loop	教学基线	看清 Orchestrator，见最小可运行项目

记忆口诀：LangGraph 管「图怎么画」；Pi 管「终端里这套 Agent 怎么跑、怎么自己改自己」。Pi 刻意不做 子 Agent、Plan 模式、权限弹窗、内置 TODO、后台 bash——要这些就自己用扩展/包做，或用容器隔离。

仓库定位（earendil-works/pi）：

@earendil-works/pi-ai            统一多厂商 LLM API
@earendil-works/pi-agent-core    Agent 运行时：tool calling + 状态
@earendil-works/pi-coding-agent  交互式编码 Agent CLI（用户日常装这个）
@earendil-works/pi-tui           终端差分渲染 UI
@earendil-works/pi-telemetry     厂商无关的遥测契约

Slack/聊天自动化另见 pi-chat，不是本篇范围。

和本站其它篇怎么接

手写 loop（理解循环）
    → LangGraph（把循环画成状态图，适合业务 Agent / 人审节点）
    → Pi（终端 coding harness：自己改工具、Skills、SDK 嵌入）

业务系统里「检索 + 审批 + 多工具」：优先 LangGraph。
本地改代码、要可拆可装的 CLI Agent：看 Pi。
私有知识：Pi 可用扩展在每轮前注入消息、过滤历史、做 RAG；检索实现仍见 [LangChain RAG 实践](/docs/ai/RAG/LangChain RAG 实践)。

安装与第一次跑

官方推荐 npm（安装时关掉依赖生命周期脚本）：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

macOS / Linux 也可用：

curl -fsSL https://pi.dev/install.sh | sh

进入项目目录：

pi

认证：交互里 /login（订阅类厂商），或事先设置如 ANTHROPIC_API_KEY。会话中 /model 或 Ctrl+L 换模型。卸载：npm uninstall -g @earendil-works/pi-coding-agent。

--ignore-scripts 是供应链习惯：Pi 正常安装不依赖 install 脚本。仓库本身也把依赖变更当代码审查，详见上游 README。

四种运行模式

模式	用法	适合
Interactive	`pi`	完整 TUI
Print / JSON	`pi -p "query"`，`--mode json`	脚本、事件流
RPC	stdin/stdout 上的 JSON 协议	非 Node 宿主
SDK	`@earendil-works/pi-coding-agent` 里 `createAgentSession`	嵌进自己的应用

SDK 最小形态（版本与 API 以官方 SDK 文档为准）：

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("当前目录有哪些文件？");

官网把 OpenClaw 当作真实嵌入案例。需要子 Agent 时，文档建议用 SDK 自己 spawn，而不是等核心内置。

上下文工程（默认就很小）

Pi 强调 system prompt 极简 + 你控制窗口里有什么：

机制	作用
`AGENTS.md`	启动时从 `~/.pi/agent/`、父目录、当前目录加载项目指令
`SYSTEM.md`	按项目替换或追加默认 system prompt
Compaction	接近上下文上限时自动摘要旧消息；可用扩展换成按主题/代码感知摘要
Skills	按需加载的能力包（指令 + 工具），渐进披露，少打 prompt cache
Prompt templates	Markdown 可复用提示，`/name` 展开
Dynamic context	扩展可在每轮前注入消息、过滤历史、接 RAG / 长期记忆

会话是树：/tree 回到任意历史点继续，分支在同一文件。/export 出 HTML，/share 可传到 gist。

运行中可插话：Enter 发 steering（当前工具结束后送达，并打断后续工具）；Alt+Enter 发 follow-up（等本轮跑完再送）。

扩展与「刻意没有」

扩展是能碰工具、命令、快捷键、事件和 TUI 的 TypeScript 模块。可打包成 Pi package，从 npm 或 git 安装：

pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom

别人常内置	Pi 的默认态度
MCP	默认没有；用带 README 的 CLI + Skills，或自己写扩展加 MCP。协议层见 MCP 概览与实践
子 Agent	用 tmux 再开一个 `pi`，或扩展/包自己做
权限弹窗	默认没有内置权限系统，进程权限 = 启动用户；要隔离用容器
Plan / TODO / 后台 bash	写文件、扩展、或 tmux

权限与容器（上游写得很直白）：默认不限制文件系统、进程、网络、凭据。更强边界见仓库 packages/coding-agent/docs/containerization.md：

Gondolin：host 上留 pi 和厂商登录，内置工具和 ! 命令进本地 Linux micro-VM
Plain Docker：整个 pi 进容器
OpenShell：策略可控的沙箱

这和工具调用与评测实践里「不可逆动作要闸门」是同一类问题：Pi 把闸门留给你的环境，而不是做成产品弹窗。

常见坑

把 Pi 当 LangGraph：Pi 是可跑的 harness + CLI；LangGraph 是库级状态机。业务审批流仍用手画图更清晰。
默认等于安全：无内置权限模型；本机直接 pi = 用户能删的它也能删。生产/不可信仓库先容器化。
抱怨没有 MCP / Plan：这是设计，不是漏做；用 Skills/扩展补，或换产品级 IDE Agent。
API 漂移：包名曾随组织迁移，安装以 @earendil-works/pi-coding-agent 和文档为准。
给开源贡献 PR：新贡献者的 issue/PR 可能被自动关闭，维护者会按日回看，见上游 CONTRIBUTING.md。

实践要点

先会讲 Agent 循环，再把 Pi 映射到「现成的 Orchestrator + Tool Registry + 可插拔上下文」。
本地：装 CLI → /login → 用 AGENTS.md / Skills 约束项目习惯。
嵌入产品：SDK / RPC / JSON 模式；不要从 TUI 里抠协议。
要可复用能力：优先标准 [Skills](/docs/ai/Skills/Agent Skills 概览与实践)，再写 TypeScript 扩展。
面试挂钩：能说清「最小 harness + 扩展，而不是功能大全」以及默认无权限弹窗的安全含义。

面试速记

Pi 是什么？ 开源 Agent Harness：统一 LLM API、Agent 循环、TUI/CLI，核心刻意小，靠扩展和包长功能。
和 LangGraph？ LangGraph 编排业务状态图；Pi 是终端/可嵌入的 coding agent 运行时。可并存，不替代。
和 Cursor？ Cursor 是带权限、Plan、编辑器集成的产品；Pi 是可改内核的套件，默认不做那些产品功能。
四种模式？ Interactive、Print/JSON、RPC、SDK。
安全怎么答？ 默认跟随启动用户权限；要隔离就 Docker / micro-VM / 策略沙箱，而不是指望弹窗。

目标与验收​

它是什么、不是什么​

和本站其它篇怎么接​

安装与第一次跑​

四种运行模式​

上下文工程（默认就很小）​

扩展与「刻意没有」​

常见坑​

实践要点​

面试速记​