Pi Web 本地网页控制台
为 pi 编码代理提供本地浏览器界面，复用同一套配置与会话文件，随时浏览、续跑和分支对话。
- 源仓库
- agegr/pi-web
- Star 数
- ★ 8.1k
- 最近更新
- 2 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 53/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 已经用 pi 编码代理在本地积累了多个项目会话，希望用浏览器按项目浏览、续跑和整理这些历史记录。
- 不适合
- 希望用浏览器管理整台机器文件的用户
- 不愿自行配置 HTTPS 反向代理或 VPN 就暴露到公网的团队
- 源码审查
- 53/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Pi Web 是 pi coding agent 的本地浏览器 UI，直接读取 pi 的本地配置与会话文件，因此浏览器里看到的会话和历史与 pi 完全一致，可以继续已有的对话。它提供按项目分组的会话工作区，支持运行状态、上下文用量、成本和压缩信息的查看，并能在消息处开启新会话或就地编辑分支。除对话之外，它还内置项目文件工具与 Git 差异查看，可预览源码、Markdown、图片、音频、PDF 和 DOCX，并通过侧边栏切换 Git worktree。模型、凭据、插件包和技能都能在网页端配置，界面支持英文、简体中文和繁体中文。部署形态是一个只监听 127.0.0.1 的本地 Node 服务，默认端口 30141，通过 npx @agegr/pi-web@latest 启动。
Pi Web 启动一个 Next.js 服务（app/ 目录包含 UI 与 API 路由），读取 pi 代理目录（默认 ~/.pi/agent，可用 PI_CODING_AGENT_DIR 覆盖）中的 sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl 会话文件，并按项目分组渲染会话列表。用户可以恢复、重命名、导出和删除会话，查看运行状态、上下文用量、成本与压缩信息；通过“New session”从较早消息生成独立会话文件，或通过“Edit from here”在当前会话内创建分支。文件面板浏览并上传工作目录中的文件、查看 Git diff，并预览源码、Markdown、图片、音频、PDF、DOCX，且自动刷新；侧边栏可切换同一仓库的 Git worktree 检出。Models 面板复用 pi 的模型、设置和凭据存储，用于登录 provider、添加 API key、测试模型、管理插件包与技能。服务端模型与 API 请求遵循 HTTP_PROXY/HTTPS_PROXY/NO_PROXY；可选 PI_WEB_PASSWORD 开启浏览器登录，API 客户端可用用户名 pi 的 Basic Auth。
- 已经用 pi 编码代理在本地积累了多个项目会话，希望用浏览器按项目浏览、续跑和整理这些历史记录。
- 需要在某条历史消息处分叉试验不同方案：用“New session”另存独立会话，或用“Edit from here”在当前会话内建分支对比结果。
- 想在不开编辑器的情况下查看某次代理改动的 Git diff，并直接预览改动涉及的源码、Markdown 或图片文件。
- 同一仓库维护多个 Git worktree，需要从侧边栏切换检出，同时保持同一仓库的会话仍分组在一起。
- 要在网页端完成模型 provider 登录、API key 填写、模型测试和插件/技能管理，而不是在命令行里逐项配置。
- 在可信局域网内远程使用：绑定 0.0.0.0 并设置长随机密码，或通过 HTTPS 反向代理/VPN 访问。
如何安装或部署这个 Agent？
要求 Node.js 22.19.0 或更高版本，先用 node --version 确认。免安装运行：
npx @agegr/pi-web@latest全局安装命令行后可直接调用：
npm install -g @agegr/pi-web@latest
pi-web更新时先用 Ctrl+C 停止进程，再重新执行安装命令；卸载执行 npm uninstall -g @agegr/pi-web。CLI 在服务就绪后会自动打开浏览器，若未打开可手动访问 http://127.0.0.1:30141。若尚未配置模型 provider，先在 Models 面板登录或填入 API key。
如何使用这个 Agent？
默认启动：npx @agegr/pi-web@latest，服务只监听 127.0.0.1:30141。常用参数：pi-web --help 打印启动选项；--port/-p 或 PORT 改端口；--hostname/-H 或 PI_WEB_HOSTNAME 改绑定地址；--no-open 或 PI_WEB_NO_OPEN=1 禁止自动打开浏览器。远程访问示例：
PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0密码认证不加密连接，不要通过明文 HTTP 暴露到公网；反向代理转发外部主机名时需把该名称加入 PI_WEB_ALLOWED_HOSTS。其他环境变量：PI_WEB_SKIP_VERSION_CHECK=1 关闭更新检查，PI_WEB_IDLE_TIMEOUT_MS 设置空闲超时（默认 600000 毫秒，0 表示禁用）。代理配置示例：
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@latest源码开发：npm install 后 npm run dev，检查用 npm test、node_modules/.bin/tsc --noEmit、npm run lint；开发期间不要运行 next build 或 npm run build。
这个 Agent 有哪些优点和局限？
- 直接复用 pi 的本地模型、设置与凭据存储，网页端改动对两套界面同时生效，不需要迁移或同步账号。
- 会话管理粒度细：按项目分组，支持恢复、重命名、导出、删除，并区分“New session”独立文件和“Edit from here”会话内分支两种分叉方式。
- 文件侧能力完整，能看 Git diff、切换 Git worktree，并预览源码、Markdown、图片、音频、PDF、DOCX，还带自动刷新。
- 默认只监听 127.0.0.1，并提供 PI_WEB_PASSWORD、PI_WEB_ALLOWED_HOSTS、PI_WEB_IDLE_TIMEOUT_MS 等明确的访问与超时控制项。
- 浏览器界面支持英文、简体中文和繁体中文，并可按浏览器语言自动选择，团队协作的门槛较低。
- 强依赖 pi 编码代理的目录结构（默认 ~/.pi/agent 下的 jsonl 会话文件），Pi Web 必须与 pi 处于同一文件系统环境才能共享已有会话。
- 需要 Node.js 22.19.0 及以上版本，且服务端模型与 API 请求依赖网络，离线场景不可用。
- 密码认证只做访问控制、不加密传输；对外开放必须自行提供 HTTPS 反向代理或 VPN，并正确配置 PI_WEB_ALLOWED_HOSTS。
- 文件浏览器并非通用文件系统浏览器，只限于 Pi Web 中选定的工作目录以及它已知的项目/会话根目录。
- 开发期间禁止运行 next build/npm run build，否则会写入 .next/ 干扰开发服务器，构建流程与常规 Next.js 项目不同。
这个 Agent 与同类方案有什么区别？
文档明确提到上游的 pi coding agent（https://github.com/earendil-works/pi）：Pi Web 本身不执行代理逻辑，而是作为它的本地浏览器前端，共用同一份配置与会话文件；README 未提及其他同类替代品。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Pi Web 本地网页控制台 当前 | 53 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 8.1k | 2 天前 | TypeScript | — |
| zerostack | 57 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.7k | 2 天前 | Rust | OpenAI API · Claude API |
| Kooky | 47 · 缺口较多 | 桌面应用免费 | ★ 655 | 25 天前 | Swift | Codex · Claude Code |
| AgentDock | 32 · 缺口较多 | 开发框架免费 + 模型费 | ★ 1.8k | 3 个月前 | MDX | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
README 明确默认仅监听 127.0.0.1，文件浏览器限定于所选工作目录与已知项目根，模型测试路由也做了来源校验与 JSON Content-Type 校验，最小权限与数据流说明较清楚；但绑定 0.0.0.0 时仅靠可选 PI_WEB_PASSWORD 且明文 HTTP，缺少强制确认与加密，故 least_privilege 与 user_confirmation 未给满分。依赖多为固定版本但含 node-pty beta 与较新 next，未见审计或漏洞缓解说明，dependency_security 仅 1。外部副作用（模型调用、文件写入、git worktree）有描述但无回滚/撤销机制，rollback 仅 1。来源归属有 LICENSE 与仓库元数据，但发布者身份未验证，source_attribution 给 2。
README 与 package.json、CI 在 Node 版本、脚本、端口上互相一致，self_consistency 给 2；模型测试路由对超时、错误、缺失 API Key 返回结构化错误信息，failure_messages 给 2。依赖可用性依赖外部 @earendil-works 包与 beta 版 node-pty，未见锁定或镜像说明，dependency_availability 仅 1。
面向 pi 用户与本地开发者的场景描述清晰，能力边界（非通用文件浏览器、共享 pi 配置）有说明，environment_fit 覆盖 macOS/Linux/Windows 与代理设置，给 2；但触发条件（何时自动打开浏览器、worktree 切换条件）仅部分说明，trigger_precision 仅 1。
安装说明详尽（npx、全局安装、更新、卸载、选项表），license 完整为 MIT，均给 3；信息架构与仓库结构说明清楚给 2；命名稳定但版本仅 0.9.1 且无 CHANGELOG，versioning_changelog 仅 1；示例与 FAQ 较少，examples_and_faq 仅 1；已知限制有注意事项但未系统化，给 2；维护责任未明确（发布者未验证），maintenance_responsibility 仅 1。
输出可用性体现在会话浏览、导出、预览等具体功能，给 2；相对 pi CLI 的边际价值（浏览器 UI、多语言、worktree）明确，给 2；但成本收益缺少性能、资源占用或替代方案对比，cost_benefit 仅 1。
README 声明与代码/CI 部分可对应，但缺少测试结果、基准或第三方验证，claim_traceability 与 cross_source_corroboration 仅 1；事实与推断分离一般，fact_inference_separation 仅 1。
- 绑定 0.0.0.0 时仅靠可选明文密码，且不加密传输，暴露到网络会带来高风险，务必使用 HTTPS 反向代理或 VPN。
- 依赖包含 node-pty beta 与较新 next，未见漏洞审计或锁定文件，升级前应自行核查。
- 发布者身份未经验证，维护责任与更新路径不明确，长期维护存在不确定性。
- 缺少 CHANGELOG 与系统化已知限制，版本演进与兼容性变化难以追踪。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
中文 基于 v0.14.2..v0.15.0 的提交整理。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 运行中也能切换模型：聊天框的模型选择器在运行时不再禁用，与 pi 的 TUI 一样，切换从这次运行的下一个请求起生效，推理级别本来就是这样。(#1527) - 侧聊标签随主会话恢复：右侧面板里打开的侧聊标签按主会话保存在当前浏览器标签页中，回到该会话或刷新页面时恢复（已删除的侧聊不会恢复）；同一项目内切换会话时保留子代理标签；未命名的侧聊在标签栏和 Agents 切换器里统一叫「Side chat 1」「Side chat 2」。(#1512，感谢 Tiger) - 拖动重排右侧面板标签：文件、终端和代理聊天标签可以拖到其他标签前后，顺序只在页面内保留。(#1511，感谢 Tiger) - 重排自定义提供商的模型：Settings › Models 里 models.json 提供商的模型行可以在桌面上拖动、用 Alt+↑/↓ 移动，或点「+ 模型」旁的 A–Z 按名称排序一次；保存后写回文件顺序，选择器和 pi 的 /model 跟着变。(6386fa4, #1479) …在 GitHub 查看 ↗ -
发布说明摘录
中文 基于 v0.14.1..v0.14.2 的提交整理。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 模型选择器可切换「scoped | all」：设置了 enabledModels 时，聊天框的模型选择器顶部多出一行「scoped | all」，与 pi 的 /model 一样默认显示限定范围内的模型，点按或在筛选框里按 Tab 可切换到全部模型。选中范围外的模型会用于当前会话（新会话也可以从它开始），不会成为默认模型。(#1486, #1503，感谢 Salman Abdurrahman) - 在 Agents 列表里删除侧聊：侧聊行的标签切换按钮旁多了删除按钮，确认后只删除这个侧聊，主会话和其他侧聊保留；删除的正是主聊天里打开的侧聊时回到它的主会话。(#1507，感谢 谢凯文；48a158b) - 手机上的设置逐级全屏显示：手机上打开 Settings 先显示分区列表，再进入分区、再进入某一项的详情，每级全屏，标题栏有返回按钮和当前级别名称并居中显示；系统返回键返回上一级，切换时有滑动动画（开启减少动态效果时不动）。(9afc508, 1420b81) …在 GitHub 查看 ↗ -
发布说明摘录
中文 基于 v0.13.0..v0.14.1 的提交整理。v0.14.0 标签打出后发布被取消，没有发布到 npm，也没有 GitHub Release，所以本说明包含自 0.13.0 以来的全部改动。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 侧聊（side chat）：从当前会话分出一个侧聊，在右侧面板标签页里提问，带着主会话的全部上下文，主会话不受影响，运行中也能用。侧聊只保留主会话已有的只读和 shell 类工具（read、bash、grep、find、ls，Windows 上还有 powershell），不能编辑、写文件；只读的主会话分出的侧聊也没有 shell。入口有四个：/side 或 /side <问题>、选中文字后的「在侧聊询问」、运行中输入框旁的侧聊按钮、Agents 面板里的「新建侧聊」。侧聊不出现在侧栏里，在 Agents 列表中和子代理一起显示，第一条提问自动成为它的名字。(#1469，感谢 dingxiaobo；#1502) - 选中文字「引用」：选中回答里的文字后，原来的「在这里提问」改为「引用」，只插入 > 选中的文字，不再附带提问模板，提问、纠正、指示都可以接着写；多段引用各自成段。(#1502) …在 GitHub 查看 ↗