Skip to content
HeRockOnePublic
forked from agegr/pi-web

About

Web UI for the pi coding agent

Resources

Stars

2 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Pi Web

English

pi 编程智能体的本地浏览器界面。Pi Web 与 pi 共用本机配置和会话文件,可在浏览器中查找和继续对话、运行智能体、配置模型与资源,并查看项目文件。

中文微信群:请查看 GitHub Discussions 帖子。

Pi Web 展示包含结构化 Markdown、工具调用和项目导航的 pi 会话

功能

  • 会话工作区:按项目查找、继续、重命名、导出和删除对话,并查看运行状态、上下文占用、花费和压缩信息。
  • 两种分支方式:新会话会从较早的消息创建独立会话文件;从此处编辑会在当前会话内创建分支。
  • 项目文件工具:浏览和上传文件、查看 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.0

Basic Auth 不会加密传输中的密码。不要通过明文 HTTP 将 Pi Web 暴露到互联网;远程访问应使用可信反向代理提供 HTTPS,或通过可信 VPN。如果反向代理传递外部主机名,请把该名称精确加入 PI_WEB_ALLOWED_HOSTS。这个白名单不会改变 Pi Web 的监听地址。

HTTP 代理

服务端的模型和 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@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 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,详细内容按需读取:

许可证

MIT

About

Web UI for the pi coding agent

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages