Pi Pocket 扩展API参考：host、web 与 pocket 三大接口全解析

Pi Pocket 是一款构建在 Pi Durable 之上的持久化、多人协作、移动端优先的 Web 应用，用于管理 Pi 智能体会话。它的扩展 API是官方为二次开发提供的三大核心接口：host（服务端读取与上报）、web（注册路由、页面与命令）、pocket（浏览器模块 UI 开发）。掌握这组 Pi Pocket 扩展API，你就能在不改动核心代码的前提下，为应用添加工具、按钮、页面和自定义命令。

快速认识：三大接口各司其职

每个扩展模块都是一个 TypeScript 文件，其默认导出函数会收到两个参数：host和web；而浏览器模块（JavaScript 文件）则收到第三个对象pocket。三者的分工如下：

所有类型定义集中在 types/pocket.d.ts，编辑器可直接导入获得补全。

host 接口：如何读取数据目录、模型与事件

host是模块的"读取器"：模块通过它从 Pi Pocket 获取信息，并向它报告情况。注意host只在服务器重启时变化，模块热重载后不变，因此使用较新版本才有的成员前应先判断其是否存在。

常用稳定成员速览

• 路径：host.dataDir（默认~/.pi-pocket）与host.agentDir（Pi 的~/.pi/agent）
• 模型：host.resolveModel()按provider/modelId解析模型；host.modelInfo()读取上下文窗口、价格等元数据；host.modelProblem()用文字说明模型为何不可用
• 通知：host.notice(level, message)向服务器日志和应用上报info/warning/error
• 事件：host.on("run.ended", listener)（0.22.0 起，实验性）监听会话创建、消息发送、运行开始/结束等事件

实验性高阶能力

0.22.0 引入了几个实验性成员：host.ask()在会话中以卡片向用户索要密码等敏感值；host.hide()将敏感值从 Pi 和人眼中隐藏；host.fetchPublic()是带 SSRF 防护的公网请求；host.browser()直接操控会话浏览器页面。

web 接口：注册路由、浏览器模块与命令的最快方法

web让模块"往应用里加东西"。所有注册调用只允许在模块加载期间进行，之后调用会抛错；注册的内容随模块版本更替或关闭而自动移除。

注册三步走

1. web.route(method, path, handle)：在/api/x/<模块名>/下添加路由，默认仅owner可访问，可用access: "steer" | "view"放宽
2. web.client(entry)：声明该模块唯一的浏览器模块文件（.js或含index.js的文件夹）
3. web.command(name, command)：为消息框添加/name斜杠命令，在服务端运行，无需 Pi 参与

通信与生命周期

• web.send(event, data)：向浏览器模块推送实时事件，对应端用pocket.on()接收
• web.error(status, message)：构造带 HTTP 状态的错误抛给调用者
• web.onDispose(fn)：模块卸载时清理定时器、关闭连接
• web.settings(fields)/web.setting(name)（实验性）：声明并读取模块设置，由核心保存到config.json并显示在 Menu → Extensions

此外web.publicPage()与web.links可创建免登录的公开分享链接页面，详见 Public pages。

pocket 接口：三步添加侧栏按钮、页面与命令

pocket是浏览器模块专属的 API，它提供应用自带的 Preact 运行时（html、useState、useEffect等），让扩展 UI 与应用原生组件保持一致。

给应用"加件"的方法

• pocket.rail(spec)：在侧栏工具栏后添加按钮，可带badge角标
• pocket.menu(spec)/pocket.launcher(spec)：添加菜单行与 Ctrl/⌘+K 启动器动作
• pocket.page(spec)/pocket.sheet(spec)：添加全屏页面与弹窗
• pocket.panel(spec)/pocket.status(spec)（实验性）：添加会话旁面板与消息框下状态栏条目
• pocket.sessionChips/sessionAction/sessionFilter：在会话列表中添加标签、操作与过滤器

调用自有路由与接收事件

pocket.api(path, body)用于调用本模块的web.route路由；pocket.on(event, run)接收web.send推送的数据。每个添加物都有id，重复使用同一id即替换旧项。

三大接口如何配合：一个完整示例

官方示例 docs/examples/server-status.ts 演示了完整链路：

• 服务端用web.route("GET", "status", …)暴露机器负载、内存数据；
• 用web.client("server-status.js")加载浏览器模块；
• 用setInterval+web.send("status", …)每 5 秒推送，并在web.onDispose中清理定时器；
• 浏览器模块中用pocket.rail添加按钮、pocket.page添加页面、pocket.on("status")实时刷新。

把这两个文件复制到~/.pi-pocket/extensions/，再到 Menu → Extensions 打开即可，无需改动任何 Pi Pocket 源码。更多可运行示例见 docs/examples/。

版本与兼容性：pocketApi 与稳定性标记

• 扩展 API 当前版本为2（web.api/pocket.version），模块通过export const pocketApi = 2;声明所需版本，旧版 Pi Pocket 会拒绝加载并在 Extensions 面板说明原因，见 API 版本说明
• 每个成员都标注Since x.y.0与Stable / Experimental：Stable 成员按稳定性策略演进；Experimental 成员可能在任一 minor 版本中变化
• 内置模块位于 src/server/extensions/，可作为编写规范时直接参考的"活文档"

参考资料清单

• 完整类型定义：types/pocket.d.ts
• 编写扩展总览：docs/extensions.md
• 添加应用功能教程：docs/extensions/app.md
• 路由与权限：docs/extensions/routes.md
• API 稳定性策略：docs/extensions/policies/api-stability.md

只需记住一句话：host负责"读"，web负责"挂"，pocket负责"画"——三者组合即可覆盖 Pi Pocket 扩展开发的全部场景。