agegr / pi-web

查看原文 / View Original 编辑 / Edit

agegr / pi-web

Pi Web is a local web UI for the pi coding agent. It reads your local pi session files and provides a browser-based workspace for session browsing, real-time chat, model configuration, skill management, and project file preview. It offers the same pi session experience as the CLI, featuring structured tool calls, readable Markdown, session browsing, and cleaner results.

Pi Web 是 pi 编码代理的本地 Web UI。它会读取你本地的 pi 会话文件，并提供一个基于浏览器的工作区，用于会话浏览、实时聊天、模型配置、技能管理和项目文件预览。它提供了与 CLI 相同的 pi 会话体验，包括结构化的工具调用、可读的 Markdown、会话浏览以及更整洁的输出结果。

Quick Start / 快速开始

Run without installing: 无需安装即可运行： npx @agegr/pi-web@latest

Or install globally: 或全局安装： npm install -g @agegr/pi-web pi-web

Then open http://localhost:30141. The CLI will try to open the browser automatically after the server is ready. 然后打开 http://localhost:30141。服务器就绪后，CLI 会尝试自动打开浏览器。

Options / 选项:

pi-web --port 8080          # custom port / 自定义端口
pi-web --hostname 127.0.0.1 # local access only / 仅限本地访问
pi-web -p 8080 -H 127.0.0.1 # combine options / 组合选项
pi-web --no-open            # do not open the browser automatically / 不自动打开浏览器
PORT=8080 pi-web            # environment variable is also supported / 也支持环境变量
PI_WEB_NO_OPEN=1 pi-web     # useful when running as a background service / 在后台服务运行时很有用

HTTP Proxy / HTTP 代理

Pi Web reads the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables for server-side model and API requests. Pi Web 会读取标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量，用于服务器端的模型和 API 请求。

On macOS or Linux: 在 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

On Windows PowerShell: 在 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

Features / 功能特性

  • Pick work back up: Browse previous pi conversations by project without digging through terminal history or session paths. 恢复工作： 按项目浏览之前的 pi 对话，无需翻阅终端历史记录或会话路径。
  • Try different directions safely: Continue from an earlier message or fork a session into a separate route. 安全地尝试不同方向： 从之前的消息继续，或将一个会话分叉（fork）到独立的路径中。
  • Work across branches: Switch Git worktrees from the sidebar so new sessions and the Explorer follow the checkout you choose. 跨分支工作： 从侧边栏切换 Git 工作树，使新会话和资源管理器跟随你选择的检出（checkout）版本。
  • Chat beside the project: Browse files on the left and preview source, docs, images, audio, and PDFs on the right while the agent works. 边聊天边开发： 在左侧浏览文件，并在代理工作时在右侧预览源代码、文档、图像、音频和 PDF。
  • See session state clearly: Context usage, cost, compaction state, and system prompt details are visible from the top bar. 清晰查看会话状态： 上方栏可显示上下文使用量、成本、压缩状态和系统提示词详情。
  • Configure less from the terminal: Manage models, login/API keys, model tests, and skill switches from the web UI. 减少终端配置： 通过 Web UI 管理模型、登录/API 密钥、模型测试和技能开关。

Notes / 注意事项

  • Data directory: Pi Web reads ~/.pi/agent/sessions by default. Set PI_CODING_AGENT_DIR to point at another pi agent directory. 数据目录： Pi Web 默认读取 ~/.pi/agent/sessions。设置 PI_CODING_AGENT_DIR 可指向其他 pi 代理目录。
  • Session files: Files are stored as ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl. 会话文件： 文件存储为 ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl。
  • Model config: The Models panel reads and writes models.json in the pi agent directory. Model lists and defaults come from pi’s config. 模型配置： “模型”面板会读取和写入 pi 代理目录中的 models.json。模型列表和默认值来自 pi 的配置。
  • File access: File browsing and preview are scoped to the selected project directory and working directories that appear in sessions. 文件访问： 文件浏览和预览仅限于选定的项目目录以及会话中出现的工作目录。
  • Git worktrees: See “Worktrees in Pi Web” for when the switcher appears, how new worktrees are created, and what removal does. Git 工作树： 查看“Pi Web 中的工作树”以了解切换器何时出现、如何创建新工作树以及移除操作的影响。
  • Forks vs in-session branches: Fork creates a new .jsonl file. “Edit from here” creates another branch inside the same session file. 分叉（Fork）与会话内分支： Fork 会创建一个新的 .jsonl 文件。“从此处编辑”会在同一个会话文件中创建另一个分支。

Development / 开发

npm install
npm run dev

The local dev server runs at http://localhost:30141. 本地开发服务器运行在 http://localhost:30141。

Common checks / 常用检查:

node_modules/.bin/tsc --noEmit
npm run lint

Avoid running next build / npm run build during local development. It writes to .next/ and can interfere with the dev server; leave builds for release work. 避免在本地开发期间运行 next build / npm run build。它会写入 .next/ 目录并可能干扰开发服务器；构建操作请留给发布阶段。

Project Structure / 项目结构

  • app/
    • api/: agent/ (creates/drives AgentSession and exposes SSE events), auth/ (OAuth and API key management), cwd/validate/ (custom working directory validation), default-cwd/ (pi default working directory lookup), files/ (file listing, reading, preview, and watching), home/ (current user home directory), models/ (available models, default model, thinking levels), models-config/ (read/write models.json and test models), sessions/ (session reads, rename, delete, context, HTML export), skills/ (skill listing, search, install, enable/disable).
    • components/: AppShell.tsx (main layout, URL state, top panels, file tabs), SessionSidebar.tsx (project selector, session tree, Explorer), ChatWindow.tsx (messages, SSE, image drag/drop, minimap), ChatInput.tsx (input bar, model/tools/thinking/compact/slash controls), MessageView.tsx (message, thinking, tool call/result rendering), ModelsConfig.tsx (model and auth configuration panel), SkillsConfig.tsx (skill management panel), FileExplorer.tsx (file tree), FileViewer.tsx (source, diff, image, audio, PDF, DOCX preview).
    • lib/: http-dispatcher.ts (HTTP(S) proxy setup for server-side fetch), rpc-manager.ts (AgentSessionWrapper lifecycle and global registry), session-reader.ts (parses .jsonl session files and branch contexts), normalize.ts (normalizes toolCall field names), file-access.ts (file read safety boundary), file-paths.ts (path encoding and relative path helpers), markdown.ts (Markdown/Mermaid/KaTeX plugin configuration), pi-types.ts (pi-related types).
    • hooks/: useAgentSession.ts (session loading, command sending, SSE state machine), useAudio.ts (completion sound), useDragDrop.ts (image drag/drop), useTheme.ts (theme switching).
    • bin/: pi-web.js (npm CLI entrypoint), instrumentation.ts (initializes the server HTTP dispatcher).
← 返回新闻列表 / Back to news list