为控制台 AI 编程助手 pi 打造的便捷 Web 界面
在终端中工作很棒，只要上下文能在一屏内显示。控制台编程助手 pi 非常适合快速编辑，但一个小时的调试会话会变成函数调用、生成的代码和错误信息的混乱大杂烩。想在那堆信息流中找到模型偏离轨道的那个点？或者记得二十分钟前它在编辑哪个文件？祝你好运。
开发者 agegr 用一种非常实用的方式解决了这个问题：他们编写了一个名为 pi-web 的本地 Web Shell。这个工具读取 pi 代理的日志文件，并在浏览器中启动一个便捷的可视化仪表板。
什么是 pi-web，它是如何工作的
从本质上讲，pi-web 是控制台代理 pi 的一个包装器。作者没有重写代理本身，而是创建了一个解析 .jsonl 文件的前端，这些文件来自 ~/.pi/agent/sessions 目录。
应用程序完全在本地运行。你可以用一条命令启动它，无需任何预先安装：
npx @agegr/pi-web@latest
服务器将在 30141 端口启动，并自动在浏览器中打开一个标签页。如果端口被占用或你需要仅本地访问，可以通过 flags 轻松更改参数：
pi-web --port 8080 --hostname 127.0.0.1
工作流程中有哪些变化
控制台 AI 对话的主要问题是结构的丢失。在终端中，一切看起来都是一堵密不透风的文字墙。Web 界面将同一个会话分解成清晰、可视化的块。
可视化会话分支
当 AI 代理开始走进死胡同时，在控制台你要么重置对话，要么生成一长串重试历史。Pi-web 有两条安全实验的路径：
- Fork 创建一个独立的会话
.jsonl文件。你可以在保留旧结果的同时走一条新路。 - 从选定的消息进行编辑会在同一会话中创建额外的分支。
在聊天旁边查看文件
当代理编辑代码或编写文档时，你可以在旁边的面板中直接跟踪更改。项目浏览器在左侧，预览区域在右侧。内置查看器不仅能显示源文件和 diff，还能轻松处理图片、音频、PDF 和 DOCX 文档。
透明的 Token 和设置控制
顶部栏显示已消耗的 Token、会话成本和上下文压缩状态。不再需要猜测已使用了多少限额，以及当前激活的是哪个系统提示词。
模型和 API 密钥管理也已从控制台的 JSON 文件转移到图形界面。通过设置面板，你可以更改默认模型、测试连接，以及切换代理技能。
Git worktrees 支持
如果你使用 Git worktrees 在多个分支上并行工作，pi-web 侧边栏可以动态切换环境。文件浏览器和新会话会自动适应所选的 checkout。
架构是如何设计的
该项目使用 TypeScript 和 Next.js 框架编写。仓库结构简单直接。
app/api 文件夹包含与代理交互的端点：
agent/处理会话启动和通过 Server-Sent Events (SSE) 进行事件流传输。files/处理文件读取、diff 和变更跟踪。models-config/和skills/管理代理配置。
安全性由 lib/file-access.ts 模块处理。它将文件管理器限制在当前项目和会话涉及的目录内。你无法通过 UI 读取随机的系统文件。
谁会发现这个项目有用
如果你积极使用 pi 编程助手，你应该尝试一下 pi-web。这个项目解决了 CLI 工具的主要问题——缺乏视觉清晰度。
界面在以下两种情况下特别方便：
- 调试复杂任务时，需要频繁返回过去的步骤并比较解决方案变体。
- 处理媒体文件和文档时，能够在浏览器中快速预览结果可以节省时间。
该工具正在积极开发中：已在 GitHub 上获得超过 16,000 颗星，且最近有提交记录。你只需要安装 Node.js 和 pi 代理即可运行它，所以设置实际上只需要几分钟。
相关项目