pi-web

Pi Web

中文文档

针对 pi coding agent（代码代理） 的本地 Web UI。Pi Web 读取你本地的 pi 会话文件，为你提供浏览器工作区，用于会话浏览、实时聊天、模型配置、技能管理以及项目文件预览。

CLI 与 Pi Web 中的同一个 pi 会话：结构化的工具调用、可读的 Markdown、会话浏览以及更清晰的结果。

快速开始

无需安装即可运行：

npx @agegr/pi-web@latest

或全局安装：

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

然后打开 http://localhost:30141。服务器就绪后，CLI 会自动尝试打开浏览器。

选项：

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 对话。
• 安全尝试不同方向：从更早的消息继续，或将一个会话 fork（分支）到独立的路线。
• 跨分支工作：从侧边栏切换 Git worktree（工作树），让新会话和 Explorer（文件浏览器）跟随你选中的检出（checkout）。
• 在项目旁聊天：左侧浏览文件，右侧预览源代码、文档、图片、音频和 PDF，同时 agent（代理）在工作。
• 清晰查看会话状态：上下文用量、成本、压缩状态和系统提示详情都可在顶栏看到。
• 减少终端配置：通过 Web UI 管理模型、登录/API 密钥、模型测试和技能开关。

注意事项

• 数据目录：Pi Web 默认读取 ~/.pi/agent/sessions。可通过设置 PI_CODING_AGENT_DIR 指向其他 pi agent 目录。
• 会话文件：文件存储为 ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl。
• 模型配置：Models（模型）面板会读取并写入 pi agent 目录下的 models.json。模型列表和默认值来自 pi 的配置。
• 文件访问：文件浏览和预览的范围限定于选中的项目目录以及会话中出现的工作目录。
• Git worktree：关于切换器何时出现、如何创建新的 worktree 以及移除操作的效果，请参阅 Pi Web 中的 Worktrees。
• Fork 与会话内分支：Fork 会创建一个新的 .jsonl 文件。“从此处编辑”会在同一个会话文件中创建另一个分支（branch）。

开发

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  # 项目选择器、会话树、Explorer（文件浏览器）
  ChatWindow.tsx      # 消息、SSE、图片拖拽、小地图
  ChatInput.tsx       # 输入栏、模型/工具/思考/压缩/斜杠控件
  MessageView.tsx     # 消息、思考、工具调用/结果渲染
  ModelsConfig.tsx    # 模型和认证配置面板
  SkillsConfig.tsx    # 技能管理面板
  FileExplorer.tsx    # 文件树
  FileViewer.tsx      # 源代码、差异（diff）、图片、音频、PDF、DOCX 预览
lib/
  rpc-manager.ts      # AgentSessionWrapper 生命周期和全局注册表
  session-reader.ts   # 解析 .jsonl 会话文件和分支上下文
  normalize.ts        # 规范化 toolCall 字段名称
  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 CLI 入口点