Extensions on yzchen.space

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