pi-extension-docs-skill

pi 插件：把系统提示里的 pi 文档注入块转成可复用的技能文件。pi 每次会话都会在系统提示里注入一大段「Pi documentation (read only …)」文档块（指向本机的 README/docs 路径），并要求 AI 按需读取。本插件把这块内容转成一个 pi-docs 技能：首次会话写出技能文件，之后技能随技能系统正常注册，注入块从系统提示里剥掉——文档内容仍在（AI 仍可按技能描述按需读取），但不再每次请求整段重复携带。

为什么需要它

pi 的文档注入块是每条系统提示都带的：每个会话、每次请求都重复发送这段「何时读文档」的说明。它本身只是一段指针信息（文档路径 + 使用规则），却持续占用提示 token。技能系统的机制正合适：技能文件只在磁盘上存一份，会话启动时只把一句描述注入系统提示，正文按需读取。

本插件做了两头的事：

• 转写：从注入块里提取标题（作为技能描述）和 bullet 列表（作为技能正文），写出 ~/.pi/agent/skills/pi-docs/SKILL.md。上游文档路径或措辞变了，技能文件自动跟着更新，不用手动维护。
• 剥离：技能文件注册后（下一个会话开始生效，技能在启动时扫描），从系统提示里剥掉注入块，换成一句更短的技能描述。

首次会话（技能还没注册时）不剥离：文档块保留，保证 AI 拿到的信息不丢。

安装

推荐通过 pi 的包管理安装（会自动进入 pi.dev/packages 包画廊索引）：

# npm 渠道
pi install npm:pi-extension-docs-skill

# 或 git 渠道（pi 会自动装依赖；默认跟踪默认分支，pi update 时随之更新）
pi install git:github.com/GreenHatHG/pi-extension-docs-skill

# 想锁定版本也可以锚定 tag（之后需手动 pi install <...>@新tag 才会升级）
pi install git:github.com/GreenHatHG/pi-extension-docs-skill@v1.0.0

# 不安装、临时体验当前目录的包
pi -e .

装完在 pi 里用 /reload 热加载（不用重启 pi 就能让插件生效），再开一个新会话即可看到剥离生效。已安装的包可用 pi list 查看、pi remove npm:pi-extension-docs-skill 卸载。

不想装包管理，也可以手动拷贝单文件：

# 全局：所有项目生效
cp index.ts ~/.pi/agent/extensions/pi-docs-skill.ts

# 或项目级：仅当前项目生效
mkdir -p .pi/extensions && cp index.ts .pi/extensions/pi-docs-skill.ts

本地开发：pnpm test（vitest；开发时用 pnpm run test:watch 自动重跑），pnpm typecheck 检查类型。

工作原理

监听 before_agent_start 事件，对系统提示做两件事：

1. 定位注入块：用正则匹配「Pi documentation (read only …」标题起、到下一个空行分隔段落（或结尾）止的内容。

2. 转写并写出：标题第一行（去掉结尾冒号）作为 description，bullet 列表作为正文，生成带 frontmatter 的 SKILL.md 写到 ~/.pi/agent/skills/pi-docs/。写入走「临时文件 + 原子重命名」，内容没变化时不重写。写失败（磁盘只读等）时发一条警告通知，注入块保留原样——宁可多花 token，不丢文档。

3. 剥离：只有当本会话启动时技能文件已存在（即技能已注册进系统提示）才剥离。剥离是逐会话的：before_agent_start 每轮返回修改后的提示，插件本身不改 pi 的注入逻辑，卸载插件后一切自动恢复。

环境变量

节省了多少

注入块本身约 60–80 token，随每次请求重复发送；技能化后只剩一句技能描述（约 20 token）随请求携带，正文只在 AI 真正需要查文档时读一次。按一天几百次请求算，省下的量不大但纯白赚；更重要的是系统提示更短、更聚焦。

更新日志

参见 CHANGELOG.md。

项目支持

社区支持