Pi Web 中文文档：功能丰富、操作便捷的 pi 编码助手本地 Web 用户界面

Pi Web 中文文档

Pi Web 是 pi 编码助手的本地 Web 用户界面。它会读取你本地的 pi 会话文件，为你提供一个基于浏览器的工作空间，支持会话浏览、实时聊天、模型配置、技能管理以及项目文件预览等功能。

在命令行界面（CLI）和 Pi Web 中，同一个 pi 会话具备以下特点：结构化的工具调用、易读的 Markdown 格式、会话浏览功能以及更清晰的结果展示。

快速开始

- 免安装运行：`npx @agegr/pi-web@latest`

- 全局安装：`npm install -g @agegr/pi-web`，然后运行 `pi-web`，接着打开 `http://localhost:30141`。服务器就绪后，命令行界面会尝试自动打开浏览器。

选项

- `pi-web --port 8080`：自定义端口。

- `pi-web --hostname 127.0.0.1`：仅允许本地访问。

- `pi-web -p 8080 -H 127.0.0.1`：组合使用选项。

- `pi-web --no-open`：不自动打开浏览器。

- `PORT=8080 pi-web`：也支持使用环境变量。

- `PI_WEB_NO_OPEN=1 pi-web`：在作为后台服务运行时很有用。

功能

- 恢复工作：按项目浏览之前的 pi 对话，无需在终端历史记录或会话路径中查找。

- 安全尝试不同方向：从之前的消息继续，或将会话分叉到单独的路径。

- 跨分支工作：通过侧边栏切换 Git 工作树，新会话和资源管理器会跟随你选择的检出状态。

- 在项目旁聊天：在代理工作时，左侧浏览文件，右侧预览源代码、文档、图像、音频和 PDF。

- 清晰查看会话状态：从顶部栏可以看到上下文使用情况、成本、压缩状态和系统提示详情。

- 减少在终端的配置操作：通过 Web 用户界面管理模型、登录/API 密钥、模型测试和技能开关。

注意事项

- 数据目录：Pi Web 默认读取 `~/.pi/agent/sessions`。可以设置 `PI_CODING_AGENT_DIR` 指向其他 pi 代理目录。

- 会话文件：文件存储为 `~/.pi/agent/sessions//_.jsonl`。

- 模型配置：模型面板会读取和写入 pi 代理目录中的 `models.json`。模型列表和默认设置来自 pi 的配置。

- 文件访问：文件浏览和预览范围限定于所选项目目录和会话中出现的工作目录。

- Git 工作树：关于切换器何时出现、如何创建新工作树以及删除操作的效果，请参考 Pi Web 中的“工作树”部分。

- 分叉与会话内分支：分叉会创建一个新的 `.jsonl` 文件，“从此处编辑”会在同一会话文件内创建另一个分支。

开发

- 安装依赖：`npm install`

- 启动开发服务器：`npm run dev`，本地开发服务器运行在 `http://localhost:30141`。

常见检查

- `node_modules/.bin/tsc --noEmit`

- `npm run lint`

在本地开发期间，避免运行 `next build` 或 `npm run build`，因为它们会写入 `.next/` 目录，可能干扰开发服务器，构建操作应留到发布时进行。

项目结构

- `app/`

- `api/`

- `agent/`：创建/驱动 `AgentSession` 并暴露服务器发送事件（SSE）。

- `auth/`：OAuth 和 API 密钥管理。

- `cwd/validate/`：自定义工作目录验证。

- `default-cwd/`：pi 默认工作目录查找。

- `files/`：文件列表、读取、预览和监控。

- `home/`：当前用户主目录。

- `models/`：可用模型、默认模型、思考级别。

- `models-config/`：读取/写入 `models.json` 并测试模型。

- `sessions/`：会话读取、重命名、删除、上下文、HTML 导出。

- `skills/`：技能列表、搜索、安装、启用/禁用。

- `components/`

- `AppShell.tsx`：主布局、URL 状态、顶部面板、文件标签。

- `SessionSidebar.tsx`：项目选择器、会话树、资源管理器。

- `ChatWindow.tsx`：消息、SSE、图像拖放、小地图。

- `ChatInput.tsx`：输入栏、模型/工具/思考/压缩/斜杠控制。

- `MessageView.tsx`：消息、思考、工具调用/结果渲染。

- `ModelsConfig.tsx`：模型和认证配置面板。

- `SkillsConfig.tsx`：技能管理面板。

- `FileExplorer.tsx`：文件树。

- `FileViewer.tsx`：源代码、差异、图像、音频、PDF、DOCX 预览。

- `lib/`

- `rpc-manager.ts`：`AgentSessionWrapper` 生命周期和全局注册表。

- `session-reader.ts`：解析 `.jsonl` 会话文件和分支上下文。

- `normalize.ts`：规范化工具调用字段名称。

- `file-access.ts`：文件读取安全边界。

- `file-paths.ts`：路径编码和相对路径辅助工具。

- `markdown.ts`：Markdown/Mermaid/KaTeX 插件配置。

- `pi-types.ts`：与 pi 相关的类型。

- `hooks/`

- `useAgentSession.ts`：会话加载、命令发送、SSE 状态机。

- `useAudio.ts`：完成音效。

- `useDragDrop.ts`：图像拖放。

- `useTheme.ts`：主题切换。

- `bin/`

- `pi-web.js`：npm 命令行界面入口点。