为 pi 打造网页搜索扩展：从后端选型到 HTML 解析的实现#

为什么 pi 需要一个网页搜索工具#

Pi 是一个极简的终端编码 Agent，默认只给模型四个工具：read、write、edit、bash。这套工具足以操作本地文件系统，却无法触达互联网。当用户问「这个库最新版本是什么」「昨天某框架发布了什么」时，模型只能凭训练数据硬猜，而这正是 AI 编码 Agent 最容易翻车的地方。

Pi 的哲学是「不内置 MCP、不内置子 Agent，把能力交给扩展」。网页搜索这种高频需求，理应以一个 TypeScript 扩展的形式存在：模型按需调用 websearch 拿到结果，再用 webfetch 读取完整页面，整条链路完全在 Agent 循环内闭环。

本文记录我为 pi 编写 websearch.ts 扩展的完整思路：从后端选型、网络可达性实测、HTML 解析、代理支持，到 pi 扩展 API 的关键用法。整份扩展是一个 800 行左右的单文件，零外部 npm 依赖。

设计目标与约束#

在动手之前，先把约束钉死，避免后面返工：

• 开箱即用：不配任何 API Key 也能搜。用户多数时候不想为了搜个网页先去注册账号。
• 中国网络友好：默认后端必须在这个网络环境下可达。Google/Bing/DuckDuckGo/Tavily 的可达性差异巨大，不能想当然。
• 可升级：愿意配 Key 的用户能切到质量更高的付费后端（Brave、Tavily、SerpAPI），自建实例的用户能接 SearXNG。
• 上下文安全：搜索结果和抓取的网页正文都必须截断，不能把几十 KB 的 HTML 灌进模型上下文撑爆窗口。
• 可取消：用户按 Esc 能打断正在进行的网络请求，不能让 Agent 卡在一个 hang 住的 fetch 上。
• 零依赖：不引第三方 npm 包，只用 Node 内置能力 + pi 自带工具，保证放进 ~/.pi/agent/extensions/ 就能被 jiti 加载运行。

后端选型：从「想当然」到「实测可达」#

最初我打算用 DuckDuckGo 的 HTML 端点做零配置默认后端——免费、无需 Key、接口稳定。但实测打脸来得很快。

1
curl -sS -A "Mozilla/5.0 ..." "https://html.duckduckgo.com/html/" \
2
  --data-urlencode "q=pi coding agent" -o /tmp/ddg.html -w "%{http_code} %{size_download}"

1
curl -sS -A "Mozilla/5.0 ..." "https://www.bing.com/search?q=test&count=10"

Bing 结果解析：解一道 base64 重定向谜题#

抓 HTML 搜索引擎最棘手的不是取标题，而是还原真实 URL。Bing 不直接给你目标链接，而是包一层 bing.com/ck/a?...&u=a1<base64url>&... 的跳转。

1
import re, base64
2
href = "https://r.bing.com/...&u=a1aHR0cHM6Ly93d3cuc3BlZWR0ZXN0Lm5ldC8&ntb=1"
3
m = re.search(r'[?&]u=a1([^&]*)', href)
4
enc = m.group(1)
5
real = base64.urlsafe_b64decode(enc + '=' * (-len(enc) % 4)).decode('utf-8')
6
# real == "https://www.speedtest.net/"

1
function decodeBingUrl(href: string): string {
2
  const m = href.match(/[?&]u=a1([^&]*)/);
3
  if (!m) return href;
4
  try {
5
    const enc = m[1];
6
    const pad = enc.length % 4 === 0 ? enc : enc + "=".repeat(4 - (enc.length % 4));
7
    return Buffer.from(pad, "base64url").toString("utf8");
8
  } catch {
9
    return href;
10
  }
11
}

HTML 正文抽取：给模型一份干净的可读文本#

webfetch 要把一个网页变成模型能读的纯文本。直接 stripTags 会把导航栏、页脚、脚本里的文字混进正文，信噪比很差。所以抽取分两步：先删非内容块，再做格式化。

Why this way: 真正的正文几乎都在 <article>、<main>、<p> 里，而 <script>/<style>/<nav>/<footer>/<header>/<aside>/<form> 基本是噪声。先正则删掉这些整块标签，再做块级标签到换行符的转换，正文才会自然回流。

1
function htmlToText(html: string): { title: string; text: string } {
2
  let s = html;
3
  let title = "";
4
  const titleMatch = s.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
5
  if (titleMatch) title = decodeEntities(stripTags(titleMatch[1])).trim();
6

7
  // 删非内容块
8
  s = s.replace(/<script[\s\S]*?<\/script>/gi, " ");
9
  s = s.replace(/<style[\s\S]*?<\/style>/gi, " ");
10
  s = s.replace(/<(nav|footer|header|aside|form)[\s\S]*?<\/\1>/gi, " ");
11
  // ... 其余噪声块
12

13
  // 块级标签 -> 换行
14
  s = s.replace(/<(?:p|div|section|article|li|h[1-6]|br)[^>]*>/gi, "\n");
15
  // 剥离剩余标签
16
  s = s.replace(/<[^>]+>/g, " ");
17
  s = decodeEntities(s);
18
  // 收敛空白
19
  s = s.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
20
  return { title, text: s };
21
}

Key params:

• decodeEntities — 先解码 HTML 实体（&、'、数字实体等），避免正文里残留 " 这种乱码
• \u00a0 —   解码出来是不间断空格，要单独替换成普通空格，否则 [ \t]+ 收不拢

这套抽取不是 Readability 级别的正文识别，但对 Agent 够用了——重点是去掉脚本和导航噪声、让文字可读、控制长度。配合下面的截断策略，一条 webfetch 的返回稳定在 20KB 以内。

输出截断：复用 pi 的内置工具#

自定义工具最容易踩的坑是返回超大输出撑爆上下文。pi 文档反复强调「tools MUST truncate their output」，内置上限是 50KB / 2000 行。

Why this way: pi 直接导出了截断工具函数，扩展可以零成本复用，不必自己造轮子。

1
import {
2
  DEFAULT_MAX_BYTES,
3
  DEFAULT_MAX_LINES,
4
  formatSize,
5
  truncateHead,
6
} from "@earendil-works/pi-coding-agent";

Key params:

• truncateHead — 保留头部 N 行/N 字节，适合搜索结果（开头最重要）
• truncateTail — 保留尾部，适合日志（结尾最重要）
• formatSize — 人话化的体积显示，截断提示里用上

websearch 对拼好的结果文本跑一次 truncateHead，超了就在末尾追加一句「结果已截断，用 webfetch 读具体 URL」。webfetch 则是先按 max_chars（默认 20000）切片，再过一道 truncateHead 兜底，两层保险。截断时永远告诉模型「截断了、完整内容在哪」，模型才知道下一步该读哪里。

代理支持：绕开 Node fetch 的一个坑#

Node 的全局 fetch（基于 undici）有一个长期被吐槽的行为：它不读 HTTP_PROXY / HTTPS_PROXY 环境变量。在国内，很多用户靠系统级代理翻墙，如果扩展直连 fetch，代理形同虚设。

1
import { ProxyAgent, setGlobalDispatcher } from "undici";

1
if (PROXY_URL) {
2
  const args = ["-sS", "-L", "-m", "30", "--connect-timeout", "10",
3
    "-x", PROXY_URL, "-A", UA,
4
    "-w", "\n__PI_STATUS__:%{http_code}\n__PI_CT__:%{content_type}\n__PI_URL__:%{url_effective}",
5
    url];
6
  const res = await runCurl(args, signal);
7
  return parseCurlOutput(res, url);
8
}
9
// 没配代理时走全局 fetch
10
const res = await fetch(url, { headers, redirect: "follow", signal: controller.signal });

两个工具：search 与 fetch 的分工#

为什么分成 websearch 和 webfetch 两个工具，而不是合一个？因为它们对模型而言是两种不同的决策：

• websearch 回答「去哪儿找」——给关键词，拿回一堆候选 URL + 摘要。模型据此判断哪条值得深读。
• webfetch 回答「这页写了啥」——给一个 URL，拿回干净正文。模型据此综合答案。

合并成一个工具会让模型在「先搜后读」这条链上多绕一步；拆开则让模型自然地两步走：先 search 看摘要，再 fetch 读全文。每个工具都有 promptSnippet（系统提示里的一行简介）和 promptGuidelines（工具激活时的使用守则），明确告诉模型何时该用、不要凭空编 URL。

pi 扩展 API 的几个关键点#

1
pi.registerTool({
2
  name: "websearch",
3
  description: "Search the web for a query ...",
4
  promptSnippet: "Search the web (Bing by default; ...)",
5
  promptGuidelines: [
6
    "Use websearch when the user asks about recent events ...",
7
    "Prefer websearch + webfetch over guessing URLs. Don't fabricate links ...",
8
  ],
9
  parameters: Type.Object({ query: Type.String(), ... }),
10
  async execute(toolCallId, params, signal, onUpdate, ctx) { ... },
11
});

1
async execute(_toolCallId, params, signal, onUpdate, _ctx) {
2
  const query = params.query?.trim();
3
  if (!query) throw new Error("query is required");
4
  // ... 业务逻辑里所有失败也 throw
5
}

验证：从单测到真链路#

写完立刻验证，不靠「应该能跑」。分了三层：

1. 加载冒烟：用 pi 自带的 jiti 加载扩展文件，喂一个 mock 的 pi 对象，确认 websearch/webfetch 工具和 websearch 命令都注册成功。
2. 真链路工具执行：直接调用 websearch.execute，搜 Node.js LTS version 2026，拿到 5 条真实 Bing 结果，URL 解码正确；再对 https://example.com 跑 webfetch，正文和标题都对。
3. pi 启动加载：跑 pi --list-models，启动时扩展被自动发现并加载、无报错，说明 imports 解析和 pi 原生加载器都没问题。

最关键的一步是真链路执行——不真实跑一次 websearch，谁也不敢说 Bing 解析没写歪。验证时还顺手测了强制 PI_WEBSEARCH_BACKEND=wikipedia 走维基后端、非法 ftp:// URL 被拒、空 query 被拒等边界。

落地与使用#

扩展就一个文件，丢进 ~/.pi/agent/extensions/websearch.ts，pi 下次启动自动发现，运行中可用 /reload 热加载。默认走 Bing，开箱即搜。

想升级到更好的后端，配个环境变量即可：

1
# Brave（免费 2000 次/月，国内可直连）
2
export BRAVE_API_KEY=你的key
3
# 或自建 SearXNG，任何网络都稳
4
export SEARXNG_URL=https://searx.example.com
5
# 需要代理时
6
export PI_WEBSEARCH_PROXY=http://127.0.0.1:7890

配完在 pi 里 /reload，或直接对模型说「搜一下 xxx 最新进展」，模型会自己调 websearch + webfetch。也可以手动 /websearch pi coding agent 测一下当前后端通不通。

小结#

这次写 websearch.ts 的几个核心取舍：

• 选型靠实测，不靠想当然：DuckDuckGo 的 JS 验证墙、Tavily 的网络不通、undici 的不可导入，都是实测才暴露的。零配置默认后端从 DDG 换成 Bing，是这次最关键的一次纠偏。
• 零依赖优先：HTML 解析、代理、截断全靠 Node 内置 + pi 自带工具，不引一个 npm 包，换来的是「丢进 extensions 目录就能跑」的部署体验。
• search 与 fetch 分工：让模型在「找」和「读」两步上各自决策，比合并成一个工具更顺。
• 上下文安全是硬约束：复用 pi 的 truncateHead，两层截断 + 截断提示，绝不撑爆窗口。
• 失败要 throw、取消要透传：工具失败抛异常、signal 一路透到 fetch/curl，是 pi 扩展的两个容易踩错的约定。

Pi 的「极简内核 + 强扩展」哲学在这次实践里体现得很彻底：核心不给网页搜索，但 registerTool + promptGuidelines + 内置截断工具 + abort 信号透传，凑齐了写一个生产级搜索工具所需的全部积木。800 行单文件，开箱即搜，可按需升级——这就是 pi 想要的扩展形态。