内核始终是 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} />; }