# Pi Web

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

本项目是 [@agegr/pi-web](https://github.com/agegr/pi-web) 的 fork。

## 快速开始

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

**无需安装，直接运行：**

```bash
npx @rainmanhhh/pi-web@latest
```

**或全局安装后使用：**

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

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

**可选参数：**

```bash
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` 必须写在包名**之前**：

```bash
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](./docs/worktrees.md)。
- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；"Edit from here" 是同一会话文件里的分支。
- **国际化**：翻译使用与新增语言/UI 文案的方法见 [Internationalization](./docs/i18n.md)。
- **代理支持**：Pi Web **不会**读取 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。需要让服务端请求走代理时，请改用系统层方案（TUN / 透明代理）——无需应用配合，且覆盖所有请求。

## 开发

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

```bash
bun install
```

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

```bash
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](http://127.0.0.1:30001)。

## 项目结构

```text
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）
```