Pi Web

pi 编程智能体（核心 npm 包 @earendil-works/pi-ai）的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。

本项目是 @agegr/pi-web 的 fork。

快速开始

Pi Web 要求 Node.js 24.0.0 或更高版本。可通过 node --version 检查当前版本。

无需安装，直接运行：

npx @rainmanhhh/pi-web@latest

或全局安装后使用：

npm install -g @rainmanhhh/pi-web
pi-web

发布版服务默认监听 http://127.0.0.1:31415 并绑定 127.0.0.1，单进程同时提供 API 和构建后的前端；加 --open 可在服务就绪后自动打开浏览器。

可选参数：

pi-web --port 8080              # 自定义端口
pi-web --hostname 0.0.0.0       # 在可信网络中开放访问
pi-web -p 8080 -H 0.0.0.0       # 组合使用
pi-web --open                   # 服务就绪后自动打开浏览器
pi-web --agent-dir ~/.pi/agent  # 指定其他 pi agent 目录
pi-web -d                       # 输出调试日志（同时写入 server.log）

PORT=8080 pi-web                # 也支持环境变量
HOST=0.0.0.0 pi-web             # 显式开放网络访问
PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # 允许指定的代理或自定义主机名
PI_WEB_PASSWORD='足够长的随机密码' pi-web  # 启用 Basic Auth（用户名固定为 pi）

设置 PI_WEB_PASSWORD 后，网页和所有 API 端点都会启用 HTTP Basic Auth，用户名固定为 pi。未设置或设置为空值时不启用认证。

Pi Web 可以调用高权限智能体。Basic Auth 不会加密传输中的密码，因此不要把明文 HTTP 暴露到互联网。远程访问时应使用可信反向代理提供 HTTPS，或通过可信 VPN 访问。 API 请求仅接受 loopback 名称、IP 字面量，以及 PI_WEB_ALLOWED_HOSTS 中以逗号分隔的精确主机名。可信反向代理使用不同的外部主机名时，请配置该变量。PI_WEB_HOSTNAME 是该白名单的旧别名，不控制监听地址（绑定地址请用 HOST）。

运行时：Node.js 还是 Bun

发布产物里声明的是 #!/usr/bin/env node，各启动器都会遵循这个 shebang —— Windows 的 npm shim 调用 Node，Bun 也会启动 Node 进程来执行。因此默认运行时始终是 Node。

Pi Web 同样支持 Bun，且启动更快（会话文件很多的项目收益最明显）。Bun 默认尊重 shebang，所以要显式指定，--bun 必须写在包名之前：

bunx --bun @rainmanhhh/pi-web@latest   # 无需安装，直接运行
bunx --bun pi-web                      # 已全局安装时

直接 bunx pi-web 仍然跑在 Node 上。Node 是经过充分测试的配置；如果在 Bun 下出现异常，请先换回 Node 复现，以区分运行时差异与程序缺陷。

功能介绍

• 把历史工作接回来：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
• 放心试不同方向：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
• 跨分支工作：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
• 边聊边看项目文件：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
• 随时掌握会话状态：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
• 少离开当前界面：模型、登录/API key、模型测试、思考级别和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
• 在 Explorer 里更快提交：网页内完成暂存、提交和推送，还能用 AI 生成符合 Conventional Commits 的提交信息——可以固定用一个小模型，也可以跟随当前会话的主模型。活动工作区的远端由服务端在后台自动 fetch（间隔可在 设置 → Git 里调整），随时都能看到是否有内容可拉取。
• 更新自动提醒：打开应用时自动检查 pi-web 和已装插件是否有新版本——有更新时聊天区顶部横幅提示，设置中心的更新分区也能随时手动检查；检测可在设置中关闭，某个版本也可以单独忽略。
• 界面语言可选：在顶部栏切换界面支持的 UI 语言。

注意事项

• 数据目录：默认读取 ~/.pi/agent/sessions 下的会话文件。可通过环境变量 PI_CODING_AGENT_DIR 指定其他 pi agent 目录。
• 会话文件：路径形如 ~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl。
• 模型配置：Models 面板读写 pi agent 目录下的 models.json，模型列表和默认模型由 pi 的配置解析得到；从服务商 /models 端点同步的模型列表缓存在 <agentDir>/pi-web/provider/ 下。
• 偏好配置：UI 偏好（滚动步长、自动刷新、长块折叠等）保存在 pi agent 目录下的 pi-web/config.json（默认 ~/.pi/agent/pi-web/config.json）。浏览器 localStorage 是前端副本，服务端文件是其他客户端读取的权威来源。旧版 pi-web-preferences.json 会在启动时一次性迁移。
• 文件访问：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
• Git worktree：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 Pi Web 里的 Worktree。
• Fork 与会话内分支不同：Fork 会创建新的 .jsonl 文件；"Edit from here" 是同一会话文件里的分支。
• 国际化：翻译使用与新增语言/UI 文案的方法见 Internationalization。
• 代理支持：Pi Web 不会读取 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。需要让服务端请求走代理时，请改用系统层方案（TUN / 透明代理）——无需应用配合，且覆盖所有请求。

开发

为什么依赖 @earendil-works/pi-tui

pi-tui 是传递依赖（@earendil-works/pi-coding-agent 的直接依赖，pi-coding-agent/package.json deps 含 @earendil-works/pi-tui），因此不可移除——它随 pi-coding-agent 原样装进 node_modules，删除本项目 package.json 里的顶层声明不会减少任何安装体积。它也不是可选/遗留包。

真正承载 PlainTextTheme 的类是 Theme（@earendil-works/pi-coding-agent 导出，见 src/lib/rpc/plain-theme.ts:1），不在 pi-tui 里；项目对 pi-tui 的唯一直接 import 在 src/lib/rpc/plain-theme.ts:3-6：

import { TUI_KEYBINDINGS, KeybindingsManager } from "@earendil-works/pi-tui";
export const CUSTOM_UI_KEYBINDINGS = new KeybindingsManager(TUI_KEYBINDINGS);

用途：构造 CUSTOM_UI_KEYBINDINGS，经 src/lib/rpc/extension-ui.ts:59 作为第三参传给扩展 custom UI factory：factory(tui, PLAIN_TEXT_THEME, CUSTOM_UI_KEYBINDINGS, done)。

现实边界：本项目没有真正的 custom TUI 渲染——createHeadlessCustomUiTui（custom-ui-terminal.ts）只提供 { terminal, requestRender }，无 addChild/setFocus/组件树，pi-tui 官方示例式组件（Input/SelectList 等）跑不起来；custom UI 只桥接自渲染纯文本组件（{ render, handleInput?, dispose? } 契约）。因此 CUSTOM_UI_KEYBINDINGS 当前无实际消费方（全项目仅定义点与传参点两处引用，extension-ui-custom.ts 的 handleInput 不读取它）——它仅为未来支持真实 custom TUI 渲染预留的桥，扩展组件若能按其纯文本契约运行，也可自行 kb.matches(...) 解析按键。

注意：项目里其它提到 "pi-tui" 的地方（src/lib/ansi.test.ts、src/lib/terminal-input.test.ts、src/lib/file-fuzzy.ts 注释）只是测试名/注释，不是 import；createHeadlessCustomUiTui（custom-ui-terminal.ts）是本地手写的无头 TUI，也不依赖 pi-tui。

升级时 pi-tui 必须与其他 @earendil-works/pi-* 包同步同版本（顶层显式声明 0.87.0 钉住版本，避免 pi-coding-agent 的 ^0.87 deps 解析出与顶层不一致的版本）。（这段曾写"扩展靠 keybinding 注册按键处理"，经核实不准确：扩展体系里 keybinding 本就走真终端 pi 的 TUI，且 Theme 类源自 pi-coding-agent 而非 pi-tui。）

需要 Bun 和 Node.js 24.0.0+。面向开发者的调试指南（手动端口隔离、fixture URL 参数、手动验证场景、e2e 技巧）见 docs/development.md，发布流程见 docs/release.md。

bun install

两个终端分别跑 API 服务和 Vite dev server：

bun run api     # Hono API 服务，http://127.0.0.1:30002
bun run dev     # Vite dev server，http://127.0.0.1:30001（/api 代理到 :30002）

打开 http://127.0.0.1:30001。

项目结构

src/
  components/   # React UI：AppShell、SessionSidebar、ChatWindow、ChatInput、
                #   MessageView、ModelsConfig、SkillsConfig、FileExplorer、FileViewer 等
  hooks/        # useAgentSession（WebSocket 总线状态机）、useTheme、useDragDrop 等
  lib/          # 会话 .jsonl 解析、RPC manager、文件访问安全边界、
                #   请求安全、i18n、markdown 配置
  main.tsx      # 前端入口
server/
  main.ts       # API 入口 + pi-web CLI（Bun 或 Node，支持 PORT/HOST、
                #   --port/--hostname/--open/--agent-dir）
  index.ts      # Hono app 装配
  routes/       # API 处理器：agent、auth、cwd、files、git、models、
                #   sessions、skills、worktrees、preferences、project-trust 等
  static.ts     # 生产环境提供 dist/static（单进程模式）
  mount.ts      # 路由模块（每个路径一个 route.ts）到 Hono 的适配
scripts/        # e2e-stop、cdp-capture、prune-fonts（build 后清理字体）等辅助脚本
tests/e2e/      # Playwright 测试与 fixtures
vite.config.ts        # dev server（:30001）、/api 代理 → :30002、build outDir
playwright.config.ts  # e2e webServer（API + Vite）