新闻详情

新闻详情

首页 / 资讯中心 / 详情

Pi Agent Web 使用教程:用 npx 把本地 Pi Coding Agent 搬进浏览器

发布时间:2026/11/17 19:44:42来源:尧图网络
Pi Agent Web 使用教程:用 npx 把本地 Pi Coding Agent 搬进浏览器
1. 为什么要把 Pi Coding Agent 搬进浏览器如果你已经在本地用 Pi Coding Agent 写过代码大概率遇到过这种场景终端里跑了一堆会话想回头找上周那次重构的记录得在~/.pi/agent/sessions里翻.jsonl文件想对比两个方案的对话分支只能靠记忆想一边看 Agent 改的文件、一边继续追问还得在编辑器和终端之间来回切。命令行本身没问题但会话一多管理成本就上来了。Pi Agent Web 解决的就是这件事。它是一个跑在本地的 Next.js 前端通过npx一条命令就能启动把本地 Pi Coding Agent 的会话数据、工具调用、模型配置、文件浏览全部搬到浏览器里。你依然用的是本地 Agent 的能力只是查看历史、继续对话、Fork 分支、切换模型这些操作变得可视化了。适合谁经常用 AI 编程 Agent 做多轮任务、需要管理大量会话、或者想给团队做一个本地 Agent 控制台的开发者。这篇教程按“能跟做”的标准来写先讲清楚它和 Pi 的关系再给出三种启动方式npx、全局安装、源码运行然后重点讲 Next.js 环境变量和 API 转发怎么配最后用一次真实的代码任务执行来验证整条链路通不通。中间会穿插我踩过的坑比如端口占用、会话目录读不到、next build污染开发环境这些。2. TaoToken 前置给 Pi Agent 准备一个稳定的模型入口Pi Agent Web 本身只是界面层真正干活的是背后的 Pi Coding Agent而 Agent 要调用大模型才能工作。所以在你启动 Web 界面之前得先确保本地 Pi 已经配好了可用的模型。这里我用 TaoToken 来做模型接入。它的作用是提供一个统一的 API 入口你拿到 Key 之后在 Pi 的模型配置里填上 base URL 和 KeyAgent 就能正常发起请求了。对于 Pi Agent Web 来说它读取的是本地~/.pi/agent/models.json和~/.pi/agent/settings.json所以只要 Pi 那边配通了Web 界面里新建会话时就能直接选到模型。具体操作分两步。第一步去 TaoToken 控制台创建一个 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时给它起个能认出来的名字比如pi-agent-local方便以后区分。第二步把 Key 填进 Pi 的模型配置。如果你还没配过可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 base URL 和请求格式的说明。注意Pi Agent Web 不会替你管理 Key它只是读取本地已有的配置。所以务必先在 Pi 侧确认模型能正常对话再启动 Web 界面否则你会看到界面能打开、但发消息没反应的情况。配好之后你可以先在终端里用 Pi 跑一句简单对话验证确认模型通了再进入下一步。这一步别跳过后面排查问题时能省很多事。3. 可复制配置npx 启动 Next.js 环境变量 API 转发3.1 用 npx 直接启动最快路径最省事的方式是直接用npx拉最新版npx maddie1/pi-agent-weblatest启动成功后浏览器打开http://localhost:30141。如果你用的是国内 npm 镜像新版本可能还没同步会报 404 或者拉到旧版本这时候临时指定官方源npx maddie1/pi-agent-weblatest --registry https://registry.npmjs.org我实测下来第一次拉包会慢一点因为要下载 Next.js 相关依赖耐心等终端出现Ready字样再访问。3.2 全局安装后启动适合常用如果你打算长期用全局装更顺手npm install -g maddie1/pi-agent-web装完可以用pi-web或pi-agent-web启动。默认端口 30141想换端口和 hostpi-web --port 8080 --hostname 127.0.0.1短参数也行pi-web -p 8080 -H 127.0.0.1。3.3 Next.js 环境变量配置Pi Agent Web 默认读取~/.pi/agent/sessions作为会话目录。如果你的 Agent 数据不在默认路径需要指定PI_CODING_AGENT_DIR。macOS / LinuxPI_CODING_AGENT_DIR/path/to/agent-dir npm run devWindows PowerShell$env:PI_CODING_AGENT_DIRD:\your-agent-dir npm run dev端口也可以用环境变量覆盖避免和已有服务冲突PORT8080 pi-webPowerShell 下$env:PORT8080 pi-web3.4 API 转发配置说明Pi Agent Web 的后端接口都在app/api下前端通过 SSE 接收流式事件。核心链路是这样的浏览器发起请求 → Next.js API Routes →AgentSessionWrapper→ Pi 的AgentSession→ 读取本地 JSONL 文件。你不需要手动配反向代理但如果你把 Web 界面部署到别的机器、想连回本地的 Agent 服务就要注意hostname别只绑127.0.0.1否则外部访问不到。本地开发保持默认即可。如果你需要二次开发克隆源码后git clone https://github.com/MaddieMo1/Pi-Agent-Web.git cd Pi-Agent-Web npm install npm run dev开发时检查类型和 lintnode_modules/.bin/tsc --noEmit npm run lint注意开发过程中不要运行next build。它会生成.next/构建产物可能污染开发服务导致npm run dev出现异常。这是项目说明里明确提醒的我踩过一次清掉.next/才恢复。4. 验证请求浏览器访问、会话连通与一次代码任务执行启动之后先确认界面能打开。浏览器访问http://localhost:30141左侧应该出现会话列表按工作目录分组。如果本地已经有 Pi 的会话数据这里会直接列出来点进去能看到历史消息、工具调用记录。接着验证会话连通。在底部输入框发一句简单的话比如“列出当前目录下的文件”。发送后服务端会通过startRpcSession()创建或复用一个内存中的AgentSession前端通过 SSE 接收实时事件。你应该看到的是流式输出而不是等半天一次性返回。如果消息发出去没反应先回第 2 步确认模型配置。然后做一次真实的代码任务验证。我试过让它读一个项目文件并做小改动流程是这样的在输入框里写“读取package.json把 name 字段改成pi-agent-demo然后告诉我改了哪一行”。Agent 会调用文件读取工具界面上能看到工具调用和结果改完后给出说明。这一步能同时验证三件事模型通了、工具调用正常、文件读写权限没问题。如果你想验证模型对话本身是否正常也可以直接用模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认 Key 和模型都没问题再回到 Pi Agent Web 里操作。验证通过后你可以试试 Fork 功能在某条用户消息上点 Fork会从该节点创建一个新的独立会话文件侧边栏以子会话形式展示。适合“想从某个历史问题重新尝试另一种方案”的场景。会话内分支切换则不会创建新文件只是在同一会话里切换不同后续路径两者区别可以这样记Fork 产生新.jsonl分支切换不产生。5. 本篇常见错排查页面打开后没有历史会话。先确认~/.pi/agent/sessions存在。如果 Agent 数据在别处用PI_CODING_AGENT_DIR指定。另外如果某个会话文件第一行不是合法 header页面会标记为orphaned这是不完整会话不是 bug。npx 启动失败。大概率是国内镜像没同步新版本加--registry https://registry.npmjs.org重试。如果还失败检查 Node.js 版本建议 18 以上。端口被占用。默认 30141 被占时用pi-web --port 8080换端口或者用PORT环境变量。Windows 下$env:PORT8080; pi-web。发消息没反应。九成是模型配置问题。回第 2 步确认~/.pi/agent/models.json里的 base URL 和 Key 正确先在终端用 Pi 验证一次。开发时npm run dev异常。检查是不是跑过next build如果是删掉.next/目录再重启开发服务。想长期跑编码任务或 Agent 工作流。如果你不只是体验界面而是要把 Pi Agent 用在日常编码、多轮 Agent 任务上可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它在长会话和连续任务场景下更省心。接入相关的细节都在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到配置问题先翻文档比到处搜快。最后提醒一句Pi Agent Web 是本地 Agent 的可视化控制台不是替代编辑器也不是让你把生产库直连进去的工具。把它当成“会话管理和任务下发的浏览器入口”来用边界清晰出问题也好定位。
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/17 7:04:08

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/17 5:42:44

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/17 19:43:34

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/17 6:55:04

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/17 5:57:47

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/17 19:43:32

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉