手把手写一个 Pi 插件：从模板到发布 npm

摘要：Pi 的核心只有 read / write / edit / bash 四个工具，所有高级能力都靠插件补齐。与其等别人写，不如自己动手。本文从零走通"初始化项目 → 注册自定义工具 → 本地调试 → 发布 npm → 安装使用"全流程，用一个真实可用的"字数统计"插件做示例。建议收藏。

一、为什么要自己写插件？

Pi 的设计哲学是"每个插件做一件事"。官方和社区已经提供了权限、撤销、联网、记忆、子 Agent、MCP、浏览器等插件——但它们解决的是通用场景。

你自己的私有场景，没人替你写：比如"统计当前项目代码行数"、"把提交信息统一成团队格式"、"自动查内部 API 文档"。这些事，写一个 Pi 插件，10 分钟搞定。

Pi 生态专栏 10 期预告：从入门到精通，一篇不漏全给你

Pi Coding Agent 的完整生态揭秘

Pi 编程 Agent 热门插件推荐：7 个装上就能开挂的扩展

二、先搞懂：Pi 插件到底是什么？

一个 Pi 插件，本质是一个 npm 包，里面导出 TypeScript 写的扩展。它能干的事远超你的想象：

• 注册自定义工具
  ：给 Agent 加一个它能调用的新能力
• 加命令 / 快捷键
  ：像 /extensions 一样的斜杠命令
• 注入 UI 面板
  ：在终端里加自定义视图
• 控制消息历史
  ：实现 RAG、长期记忆
• 拦截工具调用
  ：权限门控、审计

安装统一是 pi install npm:<包名>，卸载是 pi uninstall <包名>。

三、环境准备

需要 Node 22+ 和一个 npm 账号：

curl https://get.volta.sh | bash volta install node@22 npm login   # 用你的 npm 账号 

四、从零写一个"字数统计"插件

我们的目标：让 Pi 多一个工具，能统计某个文件的字数。

第 1 步：初始化项目

mkdir pi-wordcount && cd pi-wordcount npm init -y npm install -D typescript @types/node 

第 2 步：写扩展入口src/index.ts

下面是核心骨架（示意，具体 API 以 pi.dev 官方扩展文档为准）：

// 导出一个扩展定义，注册一个名为 wordcount 的工具 export default {   name: "pi-wordcount",   description: "统计文本文件字数",   tools: [     {       name: "wordcount",       description: "统计给定文件的字数",       parameters: { path: "string" },       async run({ path }) {         const fs = await import("node:fs");         const text = fs.readFileSync(path, "utf-8");         // 中文按字符数，英文按词数         const cn = (text.match(/[\u4e00-\u9fa5]/g) || []).length;         const en = (text.match(/[a-zA-Z]+/g) || []).length;         return `中文字符 ${cn} 个，英文单词 ${en} 个`;       },     },   ], }; 

第 3 步：编译

npx tsc --init --target es2022 --module esnext --moduleResolution bundler npx tsc 

五、本地测试

先把插件装到本地 Pi，验证工具能被识别：

pi install ./pi-wordcount pi list            # 应能看到 pi-wordcount 

然后在 Pi 里直接问它：

> 帮我统计 README.md 的字数 

Pi 会自动调用 wordcount 工具并返回结果。跑通了，再进入下一步。

六、发布到 npm

npm publish --access public 

发布成功后，任何 Pi 用户都能装：

pi install npm:pi-wordcount 

七、三个写插件时必踩的坑

1. 别把密钥写进插件
   ：插件的源码会随 npm 分发，Token、内网地址一律走环境变量。
2. 工具描述要写清楚
   ：Agent 是"看描述决定调不调用"的，描述模糊，工具就形同虚设。
3. 参数校验放第一行
   ：Agent 传进来的参数可能不符合预期，run 入口先校验，避免工具内部报错污染上下文。

尾声

Pi 最妙的地方，不是它给了你多少功能，而是它把"扩展自己"这件事做得足够简单。当你第一次写下 export default { tools: [...] }，Pi 就从"别人的工具"变成了"你的工具"。

这，才是那句 "this one is yours" 的真正含义。

💡 iTalks | 聚焦前端 · 探索 AI 应用 · 输出成熟技术方案🐧 关注我们，获取更多技术深度解读和实用开发指南💬 觉得有用？点个"在看"分享给更多开发者！

📌 下期预告：第 04 期《Pi 上下文工程》——用 AGENTS.md、SYSTEM.md 和自动压缩，让 Pi 真正懂你的项目。