pi 编程智能体的本地浏览器界面。Pi Web 与 pi 共用本机配置和会话文件,可在浏览器中查找和继续对话、运行智能体、配置模型与资源,并查看项目文件。
中文微信群:请查看 GitHub Discussions 帖子。
- 会话工作区:按项目查找、继续、重命名、导出和删除对话,并查看运行状态、上下文占用、花费和压缩信息。
- 两种分支方式:新会话会从较早的消息创建独立会话文件;从此处编辑会在当前会话内创建分支。
- 项目文件工具:浏览和上传文件、查看 Git Diff,并预览源码、Markdown、图片、音频、PDF 和 DOCX;文件变化后会自动刷新。
- Git worktree:从侧边栏切换 checkout,同时把同一仓库不同 worktree 的会话归在一起。
- 用量统计:按供应商追踪花费、余额与缓存命中率。可为每个供应商设置余额,其下所有模型共享该余额并统一扣减;消息行会显示真实花费与剩余余额。
- 供应商级 HTTP 代理:被墙的供应商可在模型面板单独配置代理(如
http://127.0.0.1:7890),只让该供应商的流量走代理,其他供应商保持直连。 - 网页配置:无需离开 Pi Web,即可管理 Provider 登录和 API Key、模型、模型测试、插件包及技能。
- 英文、简体中文和繁体中文界面:Pi Web 首次打开时跟随浏览器语言,也可从顶部栏切换语言。
基于官方 v0.9.1 的本地主线(fork 自 agegr/pi-web),本仓库在官方版本之外新增/增强的功能:
- 会话文件树:侧边栏会话按项目文件夹以文件树展示,折叠状态跨刷新持久化(
36533e5、93e0fa1) - 浏览器式会话标签页:多个会话像浏览器标签页一样在顶栏切换(
a9a6fba) - 三段式顶栏布局:顶栏重构为三个分区,点击外部或按 Esc 收起面板;默认折叠的系统提示词组成面板(
12de342、0a5c22f、96bcd1c、a687c36)
- 用量统计面板:缓存命中率卡片、按供应商的余额追踪、上下文用量 used/total 紧凑展示(
1dd312e、814599e、b220298、83a863f、492e3f7) - 消息级余额快照:每条 assistant 消息显示完成时刻的余额快照与真实花费、缓存命中率(4 位小数);每次运行后自动刷新余额(
173216e、dabc868、a12818f、cd6b6b5)
- 文件浏览器移入右侧面板作为固定标签;操作按钮收进文件浏览器工具栏;修复 Windows CRLF 与 node-pty 测试兼容、样式水合不一致(
10db5f8、bba4616、3435e21、f475369) - 文件查看器内联编辑:直接在文件查看器里编辑并保存文件;消息级缓存命中率(
45bd97f) - 拖放/选择的文件解析为绝对路径(
80e6dd5)
- 供应商与逐消息思考等级显示在 assistant 消息头;带 think 标签的推理拆分为思考块(
1b8296c、f825f66、a426d90) - 分层系统提示词组成:按插件归因、显示 token 估算(
801d625、09c3056)
- 供应商级 HTTP 代理路由:可为单个被墙的供应商单独配置代理(
a506306)
- 编辑器草稿跨会话持久化 + 上下文仪表(
79096a7) - Web 主题系统、UX 打磨与准确工具耗时;合并上游 v0.9.0 并适配(
33952d2、3e2c3f3、6b720de)
- README 中英双语(默认中文);AGENTS.md 规则与重文档拆分(
b04bcfa、cae5156) - 缓存命中率分析脚本(
scripts/,e977cc5、70043a0、185525b)
Pi Web 要求 Node.js 22.19.0 或更高版本。先用 node --version 检查版本,然后运行:
npx @agegr/pi-web@latest服务就绪后,命令行会尝试自动打开浏览器。如果没有打开,请访问 http://127.0.0.1:30141。Pi Web 默认仅监听 127.0.0.1。
如果尚未配置模型 Provider,请打开**模型(Models)**面板登录或添加 API Key。
如需全局安装 pi-web 命令:
npm install -g @agegr/pi-web@latest
pi-web更新前先用 Ctrl+C 停止正在运行的进程,再次执行同一条安装命令。卸载时运行 npm uninstall -g @agegr/pi-web。
端口和主机名以命令行参数为准,优先于对应的环境变量。--no-open 与 PI_WEB_NO_OPEN=1 中任意一个都会关闭自动打开浏览器。运行 pi-web --help(或 -h)可打印启动选项并以退出码 0 结束,不会启动服务;未知参数会报错并以退出码 1 结束。
| 参数或环境变量 | 用途 | 默认值 |
|---|---|---|
--help、-h |
打印启动选项并退出 | — |
--port <端口>、-p <端口> 或 PORT |
服务端口 | 30141 |
--hostname <主机>、-H <主机> 或 PI_WEB_HOSTNAME |
监听主机名 | 127.0.0.1 |
--no-open 或 PI_WEB_NO_OPEN=1 |
不自动打开浏览器 | 自动打开 |
PI_WEB_SKIP_VERSION_CHECK=1 |
禁用 Pi Web 更新检查 | 未设置 |
PI_WEB_ALLOWED_HOSTS |
额外允许的代理或自定义主机名,多个值用逗号分隔,必须精确匹配 | 未设置 |
PI_WEB_PASSWORD |
启用 HTTP Basic Auth,用户名固定为 pi |
不启用认证 |
PI_WEB_IDLE_TIMEOUT_MS |
会话空闲超时毫秒数,最大 2147483647;0 禁用空闲关闭;无效或越界值使用默认值。设置后覆盖「设置 › 会话」里的选择 |
600000(10 分钟) |
会话寿命和 MCP 连接方式在「设置 › 会话」里改,写入 <agentDir>/pi-web-sessions.json:
| 设置 | 可选值 | 默认 |
|---|---|---|
| 面板打开时保活 | 开 / 关 | 开:聊天面板打开时通过心跳租约阻止空闲释放 |
| 空闲释放时间 | 10 分钟 / 30 分钟 / 1 小时 / 从不 | 10 分钟 |
| MCP 服务器 | 每个会话一个 / 全局共享 | 每个会话一个;共享时所有会话复用一个 stdio 子进程(HTTP 服务器始终按会话各自连接) |
例如:
pi-web --help
pi-web -p 8080 -H 0.0.0.0 --no-open监听非回环地址会暴露一个可执行高权限操作的智能体。在可信局域网中使用时,请设置足够长的随机密码:
PI_WEB_PASSWORD='足够长的随机密码' pi-web --hostname 0.0.0.0Basic Auth 不会加密传输中的密码。不要通过明文 HTTP 将 Pi Web 暴露到互联网;远程访问应使用可信反向代理提供 HTTPS,或通过可信 VPN。如果反向代理传递外部主机名,请把该名称精确加入 PI_WEB_ALLOWED_HOSTS。这个白名单不会改变 Pi Web 的监听地址。
服务端的模型和 API 请求会读取标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。
macOS 或 Linux:
HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @agegr/pi-web@latestWindows PowerShell:
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest- 智能体数据:Pi Web 默认读取
~/.pi/agent下的 pi 数据,包括sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl中的会话文件。可通过PI_CODING_AGENT_DIR指定其他 pi agent 目录。 - 文件系统访问:Pi Web 必须能读取智能体数据目录及会话记录中的工作目录。与现有 pi 会话共用数据时,请让 Pi Web 运行在与 pi 相同的文件系统环境中。
- 共享配置:模型面板使用 pi 的模型、设置和凭据存储,因此两种界面都能看到相关更改。
- 文件访问边界:文件浏览器仅能访问在 Pi Web 中选择过的工作目录,以及它已识别的项目或会话根目录;它不是通用的文件系统浏览器。
- Git worktree:切换器何时显示、如何创建 worktree,以及删除会产生什么影响,见 Pi Web 里的 Worktree。
Electron 包装器和其他下游集成可以在不修改 SessionSidebar 的情况下提供会话行右键菜单。监听可取消的 pi-web:session-row-contextmenu 浏览器事件,集成处理时同步调用 preventDefault():
window.addEventListener("pi-web:session-row-contextmenu", (event) => {
event.preventDefault();
const { id, path, cwd, name, clientX, clientY, refresh } = event.detail;
void openSessionMenu({ id, path, cwd, name, clientX, clientY }).then((changed) => {
if (changed) refresh();
});
});detail 对象包含 id、path、cwd、可选的 name、指针坐标,以及一个用于更改会话列表操作的 refresh() 回调。如果没有监听器取消该扩展事件,Pi Web 保留浏览器的原生右键菜单。这个钩子在浏览器端工作,与 pi agent 扩展无关。
带有分离工作的服务端 pi 扩展可以通过带版本号的全局注册表阻止自动空闲会话淘汰:
const liveness = globalThis[Symbol.for("@agegr/pi-web/session-liveness/v1")];
const release = liveness?.version === 1
? liveness.register({
name: "my-extension",
sessionId,
sessionFile: sessionFile || undefined,
isActive: () => detachedJobs.size > 0,
})
: () => {};每个活动的扩展会话注册一次,并在会话关闭、替换或重载时调用返回的幂等 release 函数。isActive 必须是同步、廉价且限定在所提供的精确会话 id 或文件上的。Provider 错误时安全失败,保留该会话。此租约只影响自动空闲淘汰;显式关闭和 Stop 回退清理仍然优先。
npm install
npm run dev开发服务器运行在 http://127.0.0.1:30141。常用检查命令:
npm test
node_modules/.bin/tsc --noEmit
npm run lint日常开发时不要运行 next build 或 npm run build。它们会写入 .next/,可能干扰开发服务器;仅在发布流程中执行构建。
app/ Next.js 界面和 API 路由
components/ React 界面组件
hooks/ 客户端状态和交互 hooks
lib/ 会话、智能体、模型、文件、Git 和安全逻辑
public/ 静态资源和 PWA 文件
bin/ npm CLI 入口及启动参数解析
docs/ 面向用户和贡献者的专题文档
启动时加载的开发规则见 AGENTS.md,详细内容按需读取:
- 架构与设计决策 — 组件总览、关键陷阱(AgentSession 生命周期、fork、分支、worktree、文件访问)、dev server 排障
- 会话文件格式与 CSS 变量 —
.jsonl结构与主题令牌 - 面向贡献者:国际化 与 发布流程
