Pi Coding Agent 完整指南

📄 源文

Pi Coding Agent 完整指南

一句话定位：pi 是 Earendil Inc. 出的极简终端 coding agent。哲学是"框架管核心、工作流靠你扩展"，刻意不内置 sub-agent / plan mode / MCP / 权限弹窗 / TODO，全靠 Skills + Extensions + Packages 三层组合自己拼。

同类对比：比 Claude Code / Codex / OpenCode 都更"裸"，但 SDK 钩子最完整——其他几个主要是 CLI，pi 是 CLI + SDK 双形态，能直接 import 进自己的 Node 进程。

Level 1 · 5 分钟跑起来

安装

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或
curl -fsSL https://pi.dev/install.sh | sh

--ignore-scripts 是官方推荐项，pi 自身不需要 install 阶段的 lifecycle script。

认证（二选一）

订阅登录（Claude Pro/Max、ChatGPT Plus/Pro Codex、GitHub Copilot）：

pi
/login

API Key：

export ANTHROPIC_API_KEY=sk-ant-...
pi

支持的 API key provider 几乎全：Anthropic / OpenAI / Azure / DeepSeek / Gemini / Vertex / Bedrock / Groq / Cerebras / xAI / OpenRouter / Vercel AI Gateway / HuggingFace / Fireworks / Together / Kimi / MiniMax / 小米 MiMo 等等。

首跑

cd /your/project
pi
> Summarize this repo and how to run its checks

默认四把工具：read / write / edit / bash。还能开 grep / find / ls（read-only，通过 tool options）。

Level 2 · 日常使用

TUI 四块布局

┌────────────────────────────────────────┐
│ Startup header (快捷键、加载的 skills) │
├────────────────────────────────────────┤
│ Messages (用户/助手/工具调用/通知)     │
│                                        │
├────────────────────────────────────────┤
│ Editor (输入区，边框颜色=思考级别)     │
├────────────────────────────────────────┤
│ Footer (cwd、session、token、cost、$$) │
└────────────────────────────────────────┘

编辑器小技能

操作 用法
引用文件 @ 触发模糊搜
路径补全 Tab
多行 Shift+Enter（Win Terminal 用 Ctrl+Enter）
贴图 Ctrl+V（Win 用 Alt+V），或拖入
Shell 命令 !cmd 跑且把输出喂给模型；!!cmd 跑但不喂
外部编辑器 Ctrl+G 开 $EDITOR

斜杠命令

命令 干什么
/login /logout 凭据
/model /scoped-models 切模型；scoped 是 Ctrl+P 循环列表
/settings 思考级别、主题、消息投递、传输
/new /resume /name /session 会话生命周期
/tree /fork /clone 会话树操作
/compact [自定义提示] 手动压缩历史
/copy /export [file] /share 导出
/reload 重载键位/扩展/skills/prompts/上下文文件
/hotkeys /changelog /quit 杂项

消息队列

agent 流式输出时你也能继续输入：

会话与树（pi 的杀手特性）

会话存到 ~/.pi/agent/sessions/--<cwd path>--/<ts>_<uuid>.jsonl，每条 entry 有 id + parentId，整个会话本质是一棵树存在单文件里。

pi -c                  # 接最近一次
pi -r                  # 浏览选一个
pi --no-session        # 不保存（一次性）
pi --session <id>      # 用特定 session（partial UUID 也行）
pi --fork <id>         # 复制一份新开

/tree 在 TUI 里直接走树，可以回到任何历史节点继续聊——不开新文件、原地分叉。这点比 Claude Code 的"不可逆 compaction"和 Codex 的"线性 history"都强。

/fork 从某条 user message 开新文件、/clone 把当前活跃分支复制到新文件。

上下文文件

替换默认 system prompt：放 .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）。追加（不替换）：用 APPEND_SYSTEM.md。

Compaction（自动 + 手动）

长会话超 context 时 pi 自己压。算法（源码 src/core/compaction/compaction.ts）：

  1. 从最新消息往回走，凑够 keepRecentTokens（默认 20k）的"保留段"
  2. 把"保留段"之前的消息打包给 LLM 写结构化摘要
  3. 写一条 CompactionEntry，下次 reload 用 摘要 + 保留段
  4. 原始 jsonl 完整保留，/tree 还能回去看

Compaction 是有损的，但树没动。这是为什么 pi 敢用——出错能回滚。

Level 3 · 定制四件套

1. Prompt Templates

~/.pi/agent/prompts/review.md：

Review this code for bugs, security, performance.
Focus on: {{focus}}

输入 /review 自动展开。也能放 .pi/prompts/ 项目级。

2. Skills（按需加载）

遵循 agentskills.io 标准：

~/.pi/agent/skills/my-skill/SKILL.md
~/.pi/agent/skills/my-skill/scripts/...
~/.pi/agent/skills/my-skill/references/...

触发：/skill:my-skill，或 agent 看上下文自己加载。

加载位置（按优先级）：

3. Extensions（最强）

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && /rm -rf/.test(event.input.command)) {
      const ok = await ctx.ui.confirm("Really run this?");
      if (!ok) return { block: true };
    }
  });
}

放 ~/.pi/agent/extensions/（auto-discover）或 .pi/extensions/。

官方明确鼓励用 extension 补 pi 没做的事：sub-agent、plan mode、permission gate、git checkpoint、SSH/sandbox 执行、MCP 集成、自定义 compaction、status line、自定义编辑器……

4. Themes

dark / light 内置，自己写就放 themes/。热重载——改文件 pi 立刻应用。

Pi Packages（把上面四样打包共享）

pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo
pi list
pi update              # 更新 pi 自己 + 包
pi update --self
pi config              # 启/禁单个资源
pi -e npm:@foo/bar     # 临时试用，不写 settings

-l flag 装到项目级（.pi/git/、.pi/npm/）。git 包默认 npm install --omit=dev，所以运行时依赖必须在 dependencies。

⚠️ 安全：包跑全权限。装第三方包前看源码。

Level 4 · 编程嵌入（pi 的差异化优势）

pi 跑四种模式：

模式 入口 适用
Interactive pi 终端日常
Print / JSON pi -p "..." 或 pi --mode json 一次性 / shell pipeline
RPC pi --mode rpc 非 Node 调用方走 stdin/stdout JSONL
SDK import Node.js 进程内嵌入

SDK 最小可跑

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

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage, modelRegistry,
});

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

await session.prompt("What files are here?");

几个核心类的分工

类 干什么
AgentSession 单次会话：消息流、模型、压缩、事件订阅
AgentSessionRuntime runtime 容器，能替换 session（/new /fork /resume /import 都在这）
SessionManager jsonl 持久化 + 树遍历
AuthStorage + ModelRegistry 凭据 + 模型发现，支持 setRuntimeApiKey() 不落盘
DefaultResourceLoader 加载 extensions/skills/prompts/themes/AGENTS.md
InteractiveMode 完整 TUI（pi 命令本体）

斜杠命令在 SDK 里的真相

三类，行为完全不同：

  1. TUI 内置命令 —— ❌ 不能当 prompt 字符串传，必须调对应 SDK 方法

    TUI 斜杠 SDK 等价
    /new runtime.newSession()
    /resume <id> runtime.switchSession(target)
    /fork <id> runtime.fork(entryId)
    /clone runtime.fork(entryId, { position: "at" })
    /model <id> session.setModel(...)
    /compact [prompt] session.compact(customInstructions?)
    /tree session.navigateTree(targetId, opts)

    铁律：会话替换操作必须走 AgentSessionRuntime，不在 AgentSession 上。

  2. 纯 UI 命令 —— /login /copy /share /export 等，服务端没意义，丢弃。

  3. 用户/扩展命令 —— ✅ /skill:xxx、/<template>、扩展的 /<cmd> 直接 session.prompt("/...") 即可。

必踩的 6 个坑

  1. 会话替换后事件订阅失效——必须 unsubscribe + re-subscribe。
  2. 流式中 prompt() 不带 streamingBehavior 会抛——必须显式 { streamingBehavior: "steer" | "followUp" }。
  3. 扩展命令不能 queue——必须非流式时执行。
  4. 每个聊天独立 cwd——别让所有聊天共享一个 cwd。
  5. runtime Map 并发要 mutex——同一 chatId 收两条快速消息会并发调 prompt()。
  6. API key 解析顺序：setRuntimeApiKey → auth.json → env → models.json fallback。临时换 key 用 setRuntimeApiKey（不持久化）。

多租户嵌入（飞书 bot / 多用户平台）

隔离层 调谁
资源根（auth/skills/extensions/sessions） agentDir 参数，或 PI_CODING_AGENT_DIR env
项目层（.pi/、AGENTS.md ancestor walk） cwd 参数
凭据 AuthStorage.create(customAuthPath) + setRuntimeApiKey()
自定义模型表 ModelRegistry.create(authStorage, customModelsPath)
进程隔离 / OS uid 隔离 / 资源限额 bwrap、systemd-run、容器（自己叠）

部署模式：

模式 隔离强度 适用
CLI spawn 进程级 飞书 bot 起步推荐
SDK 同进程多 session 应用层路径隔离 互信用户
SDK + 子进程 worker 进程级 + SDK 灵活性 既要隔离也要 SDK 钩子
SDK + bwrap/容器 内核级 互不信任

源码定位：

Level 5 · 自实现 /goal 循环

Codex 和 Claude Code 都内置了 /goal：持久目标 + 自动循环 + 评估器判完成。pi 官方核心不做这层。

补的方式两条：

  1. 装社区扩展：pi install npm:pi-goals（对标 Codex）或 pi install npm:@capyup/pi-goal（对标 Claude Code，意图先行）
  2. SDK 自实现：
async function runGoal(rt, condition, maxTurns = 20) {
  await rt.session.prompt(condition);
  for (let i = 0; i < maxTurns; i++) {
    while (rt.session.isStreaming) await new Promise(r => setTimeout(r, 200));
    // 评估器必须是另一个模型实例
    const verdict = await pi.sendMessage(
      `Has "${condition}" been satisfied? "YES: ..." or "NO: ..."`,
      { model: "claude-haiku" }
    );
    if (/^YES/i.test(verdict.text)) return { satisfied: true, turns: i + 1 };
    await rt.session.followUp("Continue working toward the goal.");
  }
  return { satisfied: false, turns: maxTurns };
}

关键：评估器必须是另一个模型实例，不要让干活的 session 自己评判——干活的模型容易自我说服"我做完了"。

Level 6 · 设计哲学

pi 主动不做这些（来自官方 README）：

整体逻辑：核心保持极简，不绑定工作流；扩展点足够强，让用户用代码塑形 pi。

Level 7 · 与同类对比速查

维度 pi Claude Code Codex CLI OpenCode
形态 CLI + SDK CLI CLI CLI
默认 provider 多家 Claude only OpenAI only 多家
内置 sub-agent ❌ ✅ ❌ ❌
内置 plan mode ❌ ✅ ✅ ❌
内置 /goal ❌（社区扩展） ✅ ✅ ❌
内置 MCP ❌ ✅ ✅ ❌
会话树 + 原地分叉 ✅（核心特色） ❌ ❌ ❌
Skills 标准 agentskills.io 自家 自家 无
扩展机制 TS extensions（最强） 有限 有限 有限
嵌入式 SDK ✅ ❌ ❌ ❌

什么时候选 pi：

什么时候不选 pi：

学习路径

Day 1: Level 1+2  —— 装上跑通，玩熟 TUI 和 /tree
Day 2: Level 3    —— 写一个 prompt template + 一个 skill
Day 3: Level 4    —— 写一个 extension 拦截 bash 危险命令
Week 2: Level 5+6 —— 嵌入到一个自己的项目、读一遍 src/config.ts

官方文档入口：

Hermes 配套 skill：skill_view(name='pi-coding-agent-sdk') 调出整理过的 SDK 集成手册（含飞书 bot 模板、多租户架构图、斜杠命令完整对照表）。