内核始终是 pi。无论你的自定义 agent（经 SDK runRpcMode），还是通用 pi --mode rpc，对外都说同一套 RPC 协议；pi-web 只在协议之上为 pi 添一层 Web 延展——桥接完全复用，pi 的扩展、skills 与工具原样直通。
# 指向任意 pi agent 源，即得一站 $ npx pi-web ./examples/aigc-agent ✓ 解析源 · 探测到 index.ts → custom 模式 ✓ 会话进程已就绪 ➜ http://localhost:3000
一个 index.ts，默认导出一份 AgentDefinition——系统提示、自定义工具、模型，皆为字段。 defineAgent() 只为类型推断，零运行时强依赖；省略 model 即继承你 pi 登录的默认。
import { defineAgent } from "@blksails/pi-web-agent-kit"; import { defineTool } from "@earendil-works/pi-coding-agent"; const echo = defineTool({ name: "echo", description: "Echo the text back.", async execute(_id, { text }) { return { content: [{ type: "text", text }] }; }, }); export default defineAgent({ // model 省略 → 继承 ~/.pi/agent 默认 systemPrompt: "You are a helpful agent.", customTools: [echo], });
那些重复且昂贵的前端工程，pi-web 已替你备好。
图片/文件上传落对象存储、签名分发；base64 喂 LLM 识别，或文件交服务端工具处理。
工具经 attachmentId 解析文件、执行、落库回流，产出可在下一轮再次引用——闭环。
图像、报告、网页以独立画布呈现于侧栏，可切换代码与预览，并随对话实时更新。
pi-web 复用 pi 的 Provider 体系——一个 Provider 即一处模型来源。 OpenAI、Anthropic、Google 等内置 Provider 开箱直连； 自定义 Provider（如 阿里云百炼、DeepSeek 等国内服务，或 NewAPI 这类 OpenAI 兼容网关）， 只需在 ~/.pi/agent/models.json 登记 baseUrl 与 apiKey。模型即现于设置页 按 provider 分组、可搜索的下拉里。
{
"providers": {
"my-gateway": {
"name": "My Gateway",
"baseUrl": "https://example.com/v1",
"apiKey": "sk-...",
"api": "openai-completions",
"models": [
{ "id": "some-model", "name": "Some Model" }
]
}
}
}
语言无关的 HTTP/SSE 协议 + 单向收敛的分层包 + 渲染器注册表。从协议到组件逐层解耦—— 既能整站起，也能把 Headless hooks 嵌进你自己的 React 栈。
import { PiChat } from "@blksails/pi-web-ui"; import { usePiSession } from "@blksails/pi-web-react"; export function App() { const session = usePiSession({ source: "./my-agent" }); return <PiChat session={session} />; }
仓库内置一个 pi-web 开发 skill——架构地图、命令速查、高频坑一应俱全。 把右侧这段提示词发给 Claude Code，它就把这个 skill 装进你项目的本地 .claude/skills/ 目录，日后开发 pi-web 时自动唤起。
安装 github.com/blksails/pi-web 的 pi-web 开发 skill： 把仓库里的 .claude/skills/pi-web/SKILL.md 取到我项目的 .claude/skills/pi-web/SKILL.md。 装好后开发 pi-web 时自动唤起。
桌面版开箱即用，双击就跑；命令行则让任何一处目录，即刻成为一个可对外的 Web 应用。
基于 Tauri 的原生外壳，内置 Node 运行时——无需预装任何环境，下载即用。
安装包尚未做代码签名，首次打开会被系统拦下：macOS 提示「无法验证开发者」，
到系统设置 › 隐私与安全性点「仍要打开」；Windows 的 SmartScreen 提示时，
点更多信息 › 仍要运行。Linux 的 AppImage 需先 chmod +x。
# 全局安装 npm i -g @blksails/pi-web # 指向任一 agent 目录，起一个 Web 应用 pi-web ./my-agent # 或直接把当前目录当作 agent cd my-agent && pi-web
需要 Node >=22.19.0。CLI 自带完整的前端产物与服务端，
不依赖仓库源码；--port 改端口，--watch 在 agent 改动时热重载。