Pi Agent Gateway 使用指南：给 Pi 配上可视化、可扩展的 Agent 工作台

使用 AI 编程工具时，真正影响日常体验的，往往是一些具体问题：对话记录怎么管理？Agent 正在读什么文件、执行什么工具？模型和扩展在哪里配置？如果想把这些能力接入自己的应用，需要重新写多少代码？

Pi Agent Gateway 为这些需求提供了一个实现起点：以 Pi Coding Agent 为运行基础，配上 Web 控制台，并将前后端通过 WebSocket 协议连接起来。

对使用者来说，它可以是一个本地 AI 编程工作台；对开发者来说，它也可以作为构建自定义 Agent 应用的参考工程。

项目地址：Fucheng-Wu/pi-agent-gateway

下面从实际需求、功能优势、上手方法和二次开发几个方面，看看这个项目适合怎样使用。

项目仓库提供的真实界面截图，使用全新配置，尚未进行模型对话。

一、它主要解决什么问题？

1. 希望在浏览器里使用 Pi，并查看执行过程

Pi Agent Gateway 提供了对话、模型选择、工具执行记录和会话切换等界面。如果更习惯图形化操作，可以在浏览器里完成这些操作，并查看流式回复和模型提供的思维输出。

这对于需要反复查看执行过程的任务比较有用。例如分析陌生代码库时，可以结合 Agent 的回复和工具记录，了解它读取了哪些文件，再判断分析是否有依据。

其中，模型调用和 Agent 执行能力来自 Pi 及其相关运行时；Gateway 的主要工作是组织后端服务、会话流程、权限处理和 Web 交互。

2. 希望把"分析方案"和"修改代码"分成两个阶段

直接让 Agent 处理任务时，有些使用者希望先讨论方案，明确范围，再进入实现。

项目提供 Plan / Build 主代理切换：

Plan 用于探索和规划，限制普通项目文件修改和命令执行。
Build 用于实施方案、修改代码和验证结果，具体执行范围由权限策略控制。

切换在会话空闲时进行，保留原会话历史、模型与思考强度。使用者不必为了从分析进入实现，重新创建一段对话或搬运上下文。

3. 希望集中配置模型和扩展资源

模型 Provider、Skills、插件、子代理、MCP，分别涉及不同的配置和资源。

Gateway 将这些管理入口放入设置界面，方便查看与调整。需要进一步定制时，仍然可以使用相应的文件配置和 TypeScript 扩展。

它更适合希望同时保留图形化入口和代码定制空间的使用者。

4. 想做自己的 Agent 应用，但不想从空目录起步

开发一个可交互的 Agent 应用，除了调用模型，还要处理会话创建与恢复、流式事件、工具记录、模型设置、断线状态和权限请求。

这个项目已经提供了一套贯通的前后端实现。二次开发时，可以沿用后端和共享协议，也可以参考它如何将 Pi SDK 的事件转成前端状态。

这可以减少一部分基础流程的重复实现；能节省多少工作，仍取决于目标应用与现有实现的差异。

二、从使用者角度看，有哪些优点？

优点	对日常使用或开发的意义
执行过程可见	可以查看文本、可用的思维输出、工具输入和结果，便于理解任务进展
Plan / Build 共享会话	从分析转入实现时可以保留上下文
模型配置有界面	可认证内置 Provider，或配置自定义兼容端点
保留 Pi 的资源机制	可以继续使用和组织 Skills、插件及相关扩展
支持角色定制	可围绕任务配置主代理、子代理、工具和技能范围
前后端分离	可以使用现有 Vue 界面，也可以接入自己的客户端
源码开放	采用 MIT 许可证，可在遵守许可条件的前提下修改和二次开发

这里的优势主要是操作入口集中、流程可见和可定制。代码生成质量、推理能力和响应速度，还会受到模型、提示词、上下文以及运行环境的影响。

关于权限确认，需要了解一个细节

当前内置 Build 角色默认允许常规的读取、检索、文件修改、命令执行及工具调用；通过文件或目录工具访问项目外路径、读取敏感环境文件时，会按策略请求确认。

所以，不能把它理解为"每次改代码都会弹窗"。如果希望对写入或命令执行采用更严格的确认方式，需要调整角色权限规则。

权限确认支持本次允许、本会话允许和拒绝，但它仍属于应用层控制，并不等同于操作系统沙箱。

设置页可管理模型、Skills、插件、子代理与 MCP。具体可用资源取决于运行时和本机配置。

三、适合哪些人群？

人群	适合的用法	需要具备的基础
已经使用 Pi 的开发者	增加 Web 操作入口，管理和查看本地会话	理解 Pi 的模型与项目配置
希望使用本地 AI 编程助手的程序员	阅读代码、讨论方案、修改项目、整理文档	会安装 Node.js、运行命令并配置模型
前端或全栈开发者	基于现有后端开发自己的 Agent 界面	熟悉 TypeScript 和 WebSocket；修改现有界面还需了解 Vue
学习 Agent 工程化的开发者	研究会话生命周期、事件转发、角色权限和扩展加载	能阅读前后端代码
需要定制工作流的个人或小型研发团队	在可信环境中验证角色、Skills 和工具组合	能维护本地服务并评估权限与数据边界

对于希望注册后立即使用、无需配置模型和开发环境的普通用户，目前仍有一定上手门槛。

如果目标是直接搭建面向多人的公共服务，还需要补充身份认证、租户隔离、工作目录限制和部署运维等能力。它目前更适合作为本地工作台或开发起点。

四、具体可以用它做什么？

场景一：理解一个刚接手的项目

将工作目录指向目标仓库，在 Plan 中提出：

阅读项目的入口、路由和核心模块，梳理一次请求的处理流程。给出相关文件路径，并说明还有哪些地方需要进一步确认。

可以结合工具记录核对它读取的文件，再继续追问某个模块。实际分析质量取决于模型能力和提供的上下文。

场景二：先讨论小改动，再进入实现

先让 Plan 明确影响范围：

找出这个表单校验逻辑的相关实现，提出一个最小修改方案，说明可能影响哪些调用位置，暂不修改代码。

确认方案后，等会话空闲，再切换到 Build：

按刚才确认的方案实现修改，并运行项目中已有的相关检查。说明修改了哪些文件，以及还有哪些结果需要人工确认。

这个流程适合希望参与决策、逐步推进任务的开发者。生成的改动和检查结果仍应自行审阅。

场景三：整理项目文档与重复任务

可以围绕已有项目，要求 Agent 整理接口说明、补充 README、解释配置项或提出测试建议。

对于反复执行的任务，还可以将约定整理成 Skills，例如文档格式、接口说明结构或代码审查关注点。后续通过相应资源加载机制复用这些指令。

场景四：定制职责明确的角色

项目支持自定义角色及工具、技能范围。例如，可以自行配置一个只读代码审查角色，专注于定位问题和输出建议；也可以为某个子代理配置专属 TypeScript 工具。

这里的"代码审查角色"是可自行配置的用法示例，不表示项目已经内置了完整的自动审查系统。

五、如何在本地使用？

第一步：准备环境并启动

需要 Git、Node.js 22.19+ 、pnpm 10.22.0，以及可用的模型服务。

如果没有安装 pnpm，可以执行：

bash 复制代码

npm install --global pnpm@10.22.0

然后克隆并启动：

bash 复制代码

git clone https://github.com/Fucheng-Wu/pi-agent-gateway.git
cd pi-agent-gateway
pnpm install
pnpm dev

浏览器打开：

text 复制代码

http://127.0.0.1:5173

开发模式下，前端会将 /ws 和 /api 转发至本地后端 127.0.0.1:3000。

第二步：连接模型

如果已经使用 Pi，后端默认读取 ~/.pi/agent/ 下的配置。

首次使用时，打开：

设置 → 模型 → 添加 Provider

可以选择内置 Provider 完成认证，也可以配置自定义兼容端点。自定义端点通常需要填写 API 类型、Base URL、API Key 和模型 ID；上游支持时，可以使用模型发现功能。

保存配置后，新建对话并选择模型。项目开源并不代表模型服务免费，调用使用自己的 Provider 凭证，可能产生上游费用。

第三步：指定要处理的项目

建议第一次尝试就设置目标项目路径，避免 Agent 操作了错误的目录。

停止开发服务，设置项目的绝对路径后重新启动。

Windows PowerShell：

powershell 复制代码

$env:PI_WORKSPACE_DIR = 'C:\path\to\your\project'
pnpm dev

macOS / Linux：

bash 复制代码

PI_WORKSPACE_DIR=/absolute/path/to/your/project pnpm dev

如果不设置，从仓库根目录执行 pnpm dev 时，Pi 默认使用 backend/ 作为工作目录。

第四步：从范围明确的任务开始

第一次使用时，可以选择 Plan，先要求它解释入口文件或梳理一个模块。确认工作目录、模型和会话行为符合预期后，再切换到 Build 处理小范围修改。

另外，PI_AGENT_DIR 可以指定独立的 Pi 配置与会话目录，适合希望把 Gateway 数据与其他 Pi 使用环境分开的场景。

六、能做哪些拓展？

下面的方向可以基于项目已有机制继续开发，并非全部已经开箱可用。

拓展方向	项目提供的基础	需要自行补充的部分
自定义 Web 工作台	独立后端、WebSocket 协议和共享类型	业务界面、交互流程与客户端状态处理
专用角色与子任务	主代理、子代理配置及工具、技能范围	具体提示词、工具实现和权限策略
面向特定任务的助手	Skills、插件、MCP 与 TypeScript 扩展入口	对应的数据源、服务接入和工作流验证
桌面客户端	可独立运行的本地后端	桌面外壳、打包、进程管理和更新机制
团队内部 Agent 服务	会话与事件处理的参考实现	身份认证、访问控制、数据隔离、审计和部署方案

例子：给自己的产品增加 Agent 面板

可以单独运行后端：

bash 复制代码

pnpm --filter ./backend dev

自己的客户端连接：

text 复制代码

ws://127.0.0.1:3000/ws

先完成 v1 握手：

json 复制代码

{"type":"init","protocolVersion":1,"requestId":"init-1"}

随后按协议创建或加载会话、选择模型与角色、发送任务，并消费带 sessionId 的事件。

完整接入还需要处理权限请求、错误和断线恢复。自定义浏览器客户端必须符合后端的 Origin 限制；换一个前端地址并不一定能直接连接。

协议与类型可参考：

例子：做一个面向项目知识的助手

可以通过自定义工具或 MCP 接入文档服务、搜索服务，再通过 Skills 约定回答结构。

但文档索引、检索质量、数据权限和更新机制，需要根据实际数据源实现。仅有 MCP 或 Skills 入口，并不意味着已经具备完整的知识库系统。

七、选用前还需要了解什么？

项目目前面向可信本地环境，默认监听 127.0.0.1，尚未提供用户身份验证和租户隔离。

此外，有几个会影响使用预期的行为：

会话保存有时机要求：Pi 在首次产生助手消息后才写出会话文件，空对话不会在后端重启后保留。
内存会话池有上限：最多保留 5 个活跃 AgentSession，被淘汰的会话可以从文件恢复；这不等于承诺五个并发任务的吞吐。
子代理暂不支持续跑：目前使用一次性执行的子会话。
构建与部署需要区分 ：pnpm build 检查后端类型并生成前端静态文件，不会自动生成前后端合一的生产服务器。
模型与扩展需要自行选择：模型质量、兼容性和工具能力取决于所配置的服务与资源。

如何判断它是否值得尝试？

如果需求是在本地以 Web 界面使用 Pi，查看执行过程，并逐步定制角色和工作流，Pi Agent Gateway 提供了比较集中的操作入口。

如果正在学习或开发 Agent 应用，它的前后端结构、共享协议和会话处理流程，也值得作为参考。

建议先用一个小项目验证安装、模型配置、Plan/Build 切换和任务执行，再判断是否适合日常使用或继续二次开发。

GitHub：Pi Agent Gateway

项目采用 MIT 许可证，是基于 Pi Coding Agent 的独立项目。使用或扩展时，可结合仓库的配置文档和当前代码了解具体行为。如果对工作流有帮助，可以通过 Star 收藏项目，通过 Issue 向维护者反馈问题。

本文依据项目当前代码与文档介绍功能，截图来自项目仓库。文中的任务提示词是使用示例，拓展方向是基于现有机制的开发建议，不代表相关产品能力已经全部实现。