Pi-Web

项目概述

Pi Web 是 pi 编程代理的本地浏览器界面。它复用 pi 的本地配置与会话文件，允许用户在浏览器中浏览和恢复对话、运行代理回合、配置模型与资源，并查看项目文件。

核心特性

• 会话工作区：按项目分组浏览、恢复、重命名、导出与删除会话，并展示运行状态、上下文用量、费用以及上下文压缩信息。
• 两种分支方式：New session 从早期消息创建独立会话文件；Edit from here 在当前会话内创建分支。
• 项目文件工具：浏览与上传文件、查看 Git diff，并预览源码、Markdown、图片、音频、PDF 与 DOCX 文件，支持自动刷新。
• Git Worktree：通过侧边栏切换 checkout，同一仓库下的会话仍归为一组。
• 网页端配置：在 Web 内管理 Provider 登录与 API Key、模型、模型测试、插件包与技能。
• 多语言界面：默认跟随浏览器语言，顶栏提供切换入口，支持英文与简体中文。

快速开始

需 Node.js 22.19.0 或更高版本。使用 node --version 检查版本后执行：

# 直接通过 npx 启动（推荐）
npx @agegr/pi-web@latest

# 或全局安装
npm install -g @agegr/pi-web@latest
pi-web

服务器就绪后会自动打开浏览器；若未打开可手动访问 http://127.0.0.1:30141。默认仅监听 127.0.0.1。若尚未配置模型 Provider，请进入 Models 面板登录或添加 API Key。

升级：按 Ctrl+C 停止进程后重新运行相同安装命令即可。卸载：npm uninstall -g @agegr/pi-web。

配置项

命令行选项的优先级高于对应环境变量。

选项 / 环境变量	作用	默认值
--port <port> / -p <port> / PORT	服务端口	30141
--hostname <host> / -H <host> / PI_WEB_HOSTNAME	绑定主机名	127.0.0.1
--no-open / PI_WEB_NO_OPEN=1	不自动打开浏览器	自动打开
PI_WEB_ALLOWED_HOSTS	额外的精确代理或自定义主机名（逗号分隔）	未设置
PI_WEB_PASSWORD	启用 HTTP Basic Auth，用户名固定为 pi	关闭

示例：

pi-web -p 8080 -H 0.0.0.0 --no-open

远程访问

绑定非回环地址将暴露可执行高权限操作的代理。在可信局域网内必须设置较长的随机密码：

PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0

Basic Auth 不会加密传输密码，请勿将 Pi Web 暴露在公网明文 HTTP 下；应通过受信反向代理或 VPN 使用 HTTPS。若反向代理转发外部主机名，需将其精确写入 PI_WEB_ALLOWED_HOSTS，该白名单不影响绑定地址。

HTTP 代理

服务端模型与 API 请求遵循 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY 标准环境变量。macOS/Linux 与 Windows PowerShell 示例：

# 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@latest

# Windows 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/agent 读取，会话存于 sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl；可通过 PI_CODING_AGENT_DIR 指定其他目录。
• 文件系统访问：Pi Web 需能读取代理数据目录以及各会话记录的工作目录，共享既有会话时应与 pi 运行在同一文件系统环境。
• 共享配置：Models 面板复用 pi 的模型、设置与凭据存储，两端修改互通。
• 文件访问边界：文件浏览器仅限已选工作目录以及已知项目/会话根，并非通用文件系统浏览器。
• Git 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();
  });
});

event.detail 包含 id、path、cwd、可选的 name、指针坐标，以及用于会话列表变更后刷新的 refresh() 回调。若无监听器取消该事件，Pi Web 保留浏览器原生右键菜单。该钩子运行在浏览器侧，与 Pi 代理扩展机制无关。

开发

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 UI 与 API 路由
components/      React UI 组件
hooks/           客户端状态与交互钩子
lib/             会话、代理、模型、文件、Git 与安全逻辑
public/          静态资源与 PWA 文件
bin/             npm CLI 入口与启动参数解析
docs/            用户与贡献者专题文档

详细架构说明与文件清单见 AGENTS.md。

许可证

MIT。