Tutorial on yzchen.space

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 立即测试。