Pi on yzchen.space

oh-my-pi 功能详解：Pi 与 omp 的关系及特性

Thu, 23 Jul 2026 12:00:00 +0800

Pi 和 oh-my-pi 的关系

Pi 是 Mario Zechner 在 2025 年 8 月创建的编码代理项目，纯 TypeScript。oh-my-pi（omp）是 Can Bölük 从 Pi fork 出来的独立项目，两个项目各自发展。omp 会定期从 Pi 合并上游变更。

规模对比

Pi 至今约 20 万行 TypeScript，没有 Rust，4 个包，4,600 多个 commit。omp 约 112 万行 TypeScript 加 17 万行 Rust，16 个包加 8 个 Rust crate，14,000 多个 commit。

两个项目有四个同名包（fork 时的原始包），各自独立发展后规模差距很大：

包	Pi 当前	omp 当前
ai（LLM 接口）	58K	188K
agent（运行时）	14K	26K
coding-agent（CLI）	104K	631K
tui（终端 UI）	26K	61K

差距最大的 coding-agent，Pi 那边是 agent 的核心流程（会话管理、工具调度、RPC 模式），omp 在这个基础上加进了下面要介绍的所有功能。

PiAgent 系列 7：pi-subagents 工作流编排

Sun, 19 Jul 2026 12:00:00 +0800

上篇介绍了如何自定义 agent 以及 pi-subagents 的三个设计约束：systemPromptMode: replace、子 agent 不能自由嵌套、以及 contact_supervisor 反向通道。这些约束决定了 pi-subagents 的编排风格，多 agent 协作主要靠文件交接，复杂流程由父 session 显式编排。本文在此基础上，介绍两种核心编排模式：Parallel 并行与 Chain 链式，以及工作流的保存、复用、管理和诊断。

Parallel：并行编排

Parallel 是最简单的编排形式：多个 agent 同时跑，互不干扰。

基础并行

/parallel \
  reviewer "审查安全性" \
  -> reviewer "审查性能" \
  -> reviewer "审查可维护性"

三个 reviewer 同时开始，互不干扰。所有结果汇总后一条消息返回主会话。

共享任务

/parallel scout researcher -- 深度分析支付模块

scout 扫代码 + researcher 线上搜，同一个任务，两种角度，并行完成。

差异化配置

/parallel \
  reviewer[model=deepseek-v4-pro,skills=security] "审查安全性" \
  -> reviewer[model=deepseek-v4-flash] "审查代码风格"

同一个 agent 类型，不同模型和技能承担不同子任务。

并行结果的传递

并行步骤的子 agent 结果按以下格式汇总，用分隔线区分：

=== Parallel Task 1 (reviewer) ===
...审查结果...

=== Parallel Task 2 (reviewer) ===
...审查结果...

如果 parallel 是 chain 里的一步，汇总文本会作为整步的 {previous} 传给下一步。

PiAgent 系列 6：pi-subagents 自定义子智能体

Sat, 18 Jul 2026 12:00:00 +0800

上篇介绍了 pi-subagents 的概念、8 个内置角色、fork/fresh 机制与模型/技能继承。本文继续深入：如何定制 agent，以及 pi-subagents 为什么要这样设计——理解这些底层约束，是后续编排工作流的前提。

自定义 Agent

内置的 8 个角色已经覆盖了大多数场景，但实际项目中往往要微调：让 reviewer 用更强的模型、给 scout 关掉网络搜索、或者加一个只负责安全审计的专属角色。pi-subagents 提供了两类自定义方式：一类是通过配置项 agentOverrides 覆盖内置 agent 的元数据；另一类是通过 .md 文件创建或覆盖 agent 定义，同名文件会覆盖内置角色，新名字则作为补充角色。

通过配置覆盖：agentOverrides

agentOverrides 是 Pi settings 中 subagents 下的一个配置对象，写在项目 .pi/settings.json 或用户 ~/.pi/agent/settings.json 里。它用来覆盖内置 agent 的元数据，不需要新建 agent 文件。其特点是：不改 prompt，只调模型、thinking、默认上下文等配置。适合快速对齐不同项目的需求。

{
  "subagents": {
    "agentOverrides": {
      "reviewer": { "model": "deepseek-v4-pro", "thinking": "high", "defaultContext": "fork" },
      "scout": { "model": "deepseek-v4-flash" },
      "researcher": { "disabled": true }
    }
  }
}

disabled: true 隐藏不需要的内置 agent。subagents.disableBuiltins: true 一次性禁用所有内置 agent（如果只用自定义角色）。

通过 .md 文件创建或覆盖

在项目或用户目录创建 .md 文件即可定义 agent。如果文件名与内置 agent 同名，就会覆盖内置角色；如果取新名字，就会新增一个补充角色。

PiAgent 系列 5：用 pi-subagents 召唤子智能体

Thu, 16 Jul 2026 12:00:00 +0800

Pi 的 README 里有一段说明他们的 Philosophy，其中关于 sub-agent 的态度明确：

No sub-agents. There’s many ways to do this. Spawn pi instances via tmux, or build your own with [extensions], or install a package that does it your way.

翻译过来就是：核心不内置 sub-agent，因为做法有很多，有人想要 tmux 协同，有人想自己写扩展，有人喜欢树状分解。Pi 不替用户做选择，而是把扩展系统作为土壤，让社区或者用户长出自己想要的方案。

pi-subagents 就是其中一个实现，它的下载量跟 pi-web-access 差不多是安装量最多的几个 pi 社区插件之一，一是说明虽然 pi 故意留了白但是社区确实有这方面的需求，另一方面也是因为它的设计足够优秀。

举一个实际工作中的场景，在进行某个项目的开发中通常包括：

理解代码 → 制定计划 → 实施 → 审查 → 修复

每一步的输出是下一步的输入，每一步都可能需要不同的"专长"：理解代码要快准狠（低 thinking），审查要严谨全面（高 thinking），实施要精确改动（会写文件但不会越权做决策）。

这就是子 agent 的用武之地：把每一步交给最合适的"分身"去跑，主 agent 负责编排和决策。

实际效果：你只需要说一句「分析 auth 模块，制定重构方案，然后实施」，Pi 就会自动调起 scout → planner → worker 三条 agent 串行执行，然后坐等结果。

Pi 与沙箱

Wed, 15 Jul 2026 12:00:00 +0800

为什么只靠正则拦截命令不够

在之前介绍 pi 的扩展系统时，我展示了一个 permission-gate.ts 的例子，用正则表达式拦截危险命令：

// permission-gate 的思路：正则匹配，匹配到就弹窗确认
const rules = [
  { pattern: /\bfind\s+\/(?![a-zA-Z0-9_./])/i, label: "find-root" },
];

这种基于模式匹配的"权限门"看似有用，但在现代大模型面前形同虚设。一个足够聪明的 LLM 可以轻松绕过

# 绕过正则的方式：
find . -path '*'              # 等价 find /
x="f"; y="ind"; $x$y /        # 变量拼接绕过
exec 3<>/dev/tcp; ...          # 使用完全不同的原语
python -c "import os; ..."     # 用解释器写文件

Claude Code 和 Codex 等主流 agent 的做法是：在权限规则之外，再加一层操作系统层面的沙箱隔离。权限规则控制"能不能执行"，沙箱控制"执行后能碰什么"两者互补。一旦沙箱生效，不管 LLM 想出多诡异的命令，它也破坏不了沙箱允许范围之外的东西。

沙箱做什么

讲沙箱之前，先从最熟悉的 Docker 开始。

从 Docker 到沙箱

Docker 大家应该都用过docker run 起一个容器，里面有独立的文件系统，端口要显式映射才能访问。这其实就是一个比较重的沙箱实现。

但当前主流的 agent 的沙箱一般不用 Docker。原因是 agent 要把你的项目目录挂进去让 LLM 改代码，还要实时拿到 stdout/stderr 反馈给 LLM，每次跑一条命令就起一个容器实在太慢了。

用 Pi 学习 Agent 怎么运行

Thu, 09 Jul 2026 12:00:00 +0800

pi 是学习 harness 的好帮手

想搞懂一个 agent 到底怎么跑起来，最好的办法不是读别人的文章，而是拿一个真正可观察的 agent 自己跑一遍。

agent = model + harness。

model 做的事很单纯——收到一个 messages 列表，返回一段文本。它不知道文件系统在哪、不知道你项目里有什么、不知道上一次对话发生了什么。
harness（中文是缰绳还是线束什么的，随便把，反正是把模型和外部环境连起来的那一层）是让模型"变聪明"的关键：它把模型包进一个循环，负责拼装上下文、调用工具、把结果塞回下一轮对话。

harness 的核心是一个循环：

拼装 system prompt + 历史消息 → HTTP 请求体
发给模型 API，拿到响应
解析响应——是普通文本还是 tool call？是 tool call 就执行
把执行结果塞进下一轮的 messages，回到第 1 步
模型不再调工具，结束

想理解 agent，就得理解这个循环。而 pi 是学这个最好的工具。

例如可以让它帮你理解 harness 过程，因为它极度透明

大多数 agent 工具把和模型的对话过程藏起来，你只能看到最终输出的文本。pi 不一样：它把整个生命周期都暴露成事件——session 启动、消息拼装、API 请求发出去之前、响应回来之后、工具执行……每一个节点你都能插手。

换句话说，harness 在 pi 里不是黑盒，而是一组你能监听的事件。理解 agent 怎么运行，本质上就是理解 harness 在那个循环里做了什么——而 pi 让你直接看见它，甚至改写它。

比如我们可以让它展示在请求大模型时发送的 HTTP 内容

一个直接的例子：让 pi 展示它发给大模型 API 的完整请求。我写了一个 extension model-api-inspector 做这件事——监听 provider 的请求 / 响应事件，把每次调用的 request body 和 response body 都渲染到终端里：

Pi Web Access 介绍

Mon, 06 Jul 2026 12:00:00 +0800

这是什么

pi-web-access 是 Pi 生态里最常用的第三方 package，给 Pi 接入网络。本质上是把 web_search、网页抓取、GitHub 仓库、YouTube/本地视频分析、PDF 提取等能力，封装成 Pi 的 extension + skill，安装后 Pi 可以直接上网查资料。

作者是 Nico Bailon，仓库在 github.com/nicobailon/pi-web-access。

安装

pi install npm:pi-web-access

安装后放在 ~/.pi/agent/npm/node_modules/pi-web-access/，不是 ~/.pi/agent/extensions/ 目录。它作为 Pi Package 安装，不需要手动管理扩展文件。

零配置可用： 不需要任何 API key。默认走 Exa MCP（免费），如果你恰好有 Codex 订阅，OpenAI 搜索也能复用认证。

如果觉得不如意，可以给别的搜索提供商配 API key。

三个工具

安装后 Pi 会多出三个 LLM 可调用的工具。

1. web_search — 联网搜索

最常用。支持单条 query 或批量 queries（推荐一次搜 2-4 条不同角度，覆盖面更宽）：

web_search({ query: "rust async programming" })
web_search({ queries: ["react 性能优化 2025", "react concurrent mode 原理"] })
web_search({ query: "...", numResults: 10, recencyFilter: "week" })
web_search({ query: "...", domainFilter: ["github.com", "-reddit.com"] })
web_search({ query: "...", provider: "openai" })
web_search({ query: "...", includeContent: true })

工作流选项：

Pi Session 管理：tree、fork、clone 与 handoff

Sun, 05 Jul 2026 12:00:00 +0800

最喜欢 Pi 的特性之一就是对 session 的管理很方便。Pi 的 session 不是线性的——它是树形的。每次回溯到某个历史节点重新发消息，就会在那个点分出一个新分支。

先看 session 长什么样

下面是一段典型的对话树：

user: "帮我写一个排序函数"
└─ assistant: "这是冒泡排序..."
   ├─ user: "改成快排" → assistant: "这是快速排序..."
   │  └─ user: "加注释" → assistant: "已加注释"  ← 当前活跃
   └─ user: "用 Rust 写" → assistant: "这是 Rust 版本..."

你随时可以回到"帮我写一个排序函数"或"改成快排"那个点，走另一条路。走了新路之后，原来的分支不会消失——它还保存在同一个 session 文件里。这就是 Pi 的 /tree ，目前 Claude Code 和 Codex 都还没有到特性。

`/tree` — 同一Session内切换分支

不创建新 session 文件。 打开一个树形导航器，显示当前 session 的全部对话节点。

在 /tree 里你可以：

选一条用户消息：光标移到该消息的父节点，编辑器预填那条消息的原文，你可以修改后重新提交——形成新分支
选一条 assistant 消息或工具结果：光标移到该消息位置，编辑器为空，直接从那个点继续
切换分支时：Pi 可以（可选）把"被抛弃的分支"总结成一段摘要，附到新位置。这样不用回看旧分支也能知道那边发生了什么

常用按键：↑↓ 浏览、Enter 选择、Esc 取消、Shift+L 打标签、Ctrl+O 切换过滤模式（默认/隐藏工具结果/只看用户消息/只看有标签的）。

Pi Extensions 进阶：从安装社区扩展到自己定制

Sat, 04 Jul 2026 12:00:00 +0800

前一篇笔记讲了 extension 是什么、有什么示例、怎么写。这篇记录实际使用——怎么从官方和社区安装、以及怎么根据需求自己改造。

一、先自己写个简单的：show-system-prompt

动机

Agent 的系统提示词由多个来源拼合而成——角色定位、工具列表、AGENTS.md、项目上下文、技能清单。Claude/Openclaw 这样的 Agent 内置系统提示词就能吃掉几千个 token。但是像 Pi 这种我们可以轻松写一个 Extention 调试提示词效果，看一眼"LLM 当前实际收到的 prompt 到底是什么"。一个 /system-prompt 命令，把完整内容打印到终端。写

主要就两步：

捕获提示词。 通过 before_agent_start 事件捕获 Pi 发给 LLM 的完整 system prompt，存到变量里。这是"post-chained"的值——即所有 extension 修改之后、实际发送之前的版本。如果命令被调用时还没有 turn 跑过，就降级用 ctx.getSystemPrompt()。

全屏覆盖层显示。 用 ctx.ui.custom() 打开一个覆盖层，渲染 prompt 全文。handleInput 监听 Escape 或 q 关闭，render 用 wrapTextWithAnsi 处理终端宽度换行。加了宽度缓存，只在终端尺寸变化时重新计算。

示例代码

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Key, matchesKey, wrapTextWithAnsi } from "@earendil-works/pi-tui";

export default function (pi: ExtensionAPI) {
  let lastPrompt: string | undefined;

  pi.on("before_agent_start", (event) => {
    lastPrompt = event.systemPrompt;
  });

  pi.registerCommand("system-prompt", {
    description: "Print the current session's system prompt",
    handler: async (_args, ctx) => {
      const prompt = lastPrompt ?? ctx.getSystemPrompt();

      if (ctx.mode !== "tui") {
        ctx.ui.notify(prompt, "info");
        return;
      }

      await ctx.ui.custom<void>((_tui, _theme, _kb, done) => {
        let cachedWidth = 0;
        let cachedLines: string[] = [];

        return {
          render(width: number): string[] {
            if (width !== cachedWidth) {
              cachedWidth = width;
              cachedLines = wrapTextWithAnsi(prompt, width);
            }
            return cachedLines;
          },
          handleInput(data: string): void {
            if (matchesKey(data, Key.escape) || data === "q") done();
          },
          invalidate(): void { cachedWidth = 0; },
        };
      });
    },
  });
}

结果

输入 /system-prompt 后，终端全屏显示 Pi 当前 session 的完整系统提示词：

Pi Extensions 入门指南

Thu, 02 Jul 2026 12:00:00 +0800

Pi 的 Extension 是什么

Extension（扩展）是 Pi 的 TypeScript 插件系统，也是它可扩展性体系中最核心的一环。你可以把它理解成给 Pi 写"插件"，用来定制它的行为、添加新能力，或者接入外部系统。

Pi 的哲学是"不把工作流强加给你"，所以像权限控制、子代理、plan mode 这些其他工具内置的功能，Pi 全都不做——而是把能力交给 extension，让你自己决定怎么做。写一个 extension、或者装一个别人写好的 Pi Package，就能把 Pi 调整成你想要的形状，不需要 fork 源码。

具体来说，extension 能做这些事情：

注册自定义工具，让 LLM 在对话中可以调用 —— 比如一个 deploy 工具、一个 todo 工具
拦截事件，在关键节点插手 —— 比如 LLM 想执行 rm -rf 的时候弹窗问你要不要放行
和用户交互，弹确认框、选择列表、输入框、通知
构建自定义 UI，从简单的状态栏文字，到完全接管编辑器，到游戏覆盖层
注册命令，添加 /mycommand 这样的自定义斜杠命令
持久化状态，让数据跨重启存活，还能随着 session 的分支自动正确还原
自定义渲染，控制工具调用的结果在终端里怎么展示

它还覆盖了 Pi 运行的完整生命周期——从 session 启动、LLM 对话开始、每个 turn、每次工具调用、到 session 关闭，几乎所有环节都可以插入逻辑。所以 extension 不光能"加功能"，也能"改行为"。

快速看一眼代码

一个最简 extension 长这样。三件事：拦截危险命令、注册一个工具、注册一个命令：

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

export default function (pi: ExtensionAPI) {
  // 拦截危险 bash 命令
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("危险操作!", "允许 rm -rf 吗?");
      if (!ok) return { block: true, reason: "用户拒绝" };
    }
  });

  // 注册一个 LLM 可调用的工具
  pi.registerTool({
    name: "greet",
    description: "向某人打招呼",
    parameters: Type.Object({ name: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }] };
    },
  });

  // 注册一个用户可用的命令
  pi.registerCommand("hello", {
    description: "打招呼",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
    },
  });
}

放在 ~/.pi/agent/extensions/my-ext.ts，或者用 pi -e ./my-ext.ts 立即测试。

pi System Prompt 构成详解

Tue, 30 Jun 2026 12:00:00 +0800

pi 的 system prompt 采用分层拼装机制，启动时按固定顺序叠放各层，最终拼接为发送给 LLM 的完整系统提示。

拼装顺序

┌─────────────────────────────────────────────┐
│  ① 基础系统提示 (pi 内置)                     │
│     角色、工具说明、行为准则、文档路径           │
│     ↓ 可被替换                                │
│  ② SYSTEM.md (如存在)                        │
│     完全替换①，而非追加                        │
│     ~/.pi/agent/SYSTEM.md 或 .pi/SYSTEM.md    │
│     ↓                                        │
│  ③ APPEND_SYSTEM.md (如存在)                  │
│     追加在②之后                                │
│     ↓                                        │
│  ④ 上下文文件                                 │
│     AGENTS.md / CLAUDE.md 全部拼接            │
│     来源：全局 + 沿目录树向上收集                │
│     ↓                                        │
│  ⑤ 技能列表 (XML)                             │
│     仅名称 + 描述，遵循 Agent Skills 规范       │
│     ↓                                        │
│  ⑥ 最终 System Prompt → 发送给 LLM            │
└─────────────────────────────────────────────┘

工具 Schema 不在 system prompt 中

工具定义（read、write、edit、bash 及扩展注册的自定义工具）作为 API 请求的 tools 参数单独传递，不进入 system prompt 正文。system prompt 中只包含工具的简要描述说明。