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

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

本文适合想在浏览器里管理、查看和继续使用本地 Pi Coding Agent 会话的同学。教程会从安装启动、界面使用、模型配置、会话管理和常见问题几个角度展开。

一、Pi Agent Web 是什么？

Pi Agent Web 是一个用于本地 Pi Coding Agent 的 Web 界面。

简单说，它可以让你不用一直盯着命令行，而是在浏览器里完成这些操作：

• 查看本地历史会话
• 继续和 Agent 对话
• 查看 Agent 的流式输出
• 展示工具调用过程
• 管理模型配置
• 浏览当前工作目录文件
• 对会话进行 Fork、分支切换和压缩

项目默认读取本地 Pi Agent 的会话目录：

~/.pi/agent/sessions

也就是说，只要你的本机已经有 Pi Coding Agent 的会话数据，Pi Agent Web 就可以把这些会话以更直观的方式展示出来。

二、Pi 是什么？

Pi 这里指的是 Pi Coding Agent，可以理解为一个运行在本地开发环境里的 AI 编程助手。

它的核心作用不是简单聊天，而是围绕真实项目进行开发协作。比如你可以让它：

• 阅读项目代码
• 分析 Bug
• 修改文件
• 执行命令
• 运行测试
• 总结项目结构
• 根据上下文继续完成开发任务

和普通网页聊天机器人不同，Pi Coding Agent 更贴近“本地开发助手”。它能在你的项目目录中工作，理解当前仓库的文件结构，并把每一次会话保存成本地记录。

这些会话记录通常存放在：

~/.pi/agent/sessions

每个会话本质上是一个.jsonl文件，里面保存了用户消息、助手回复、工具调用、模型切换、压缩记录等信息。

可以这样理解两者关系：

Pi Coding Agent 负责真正执行 AI 编程任务 Pi Agent Web 负责把这些会话和操作可视化

也就是说，Pi Agent Web 不是替代 Pi，而是给 Pi 加了一个浏览器界面。你依然使用的是本地 Pi Agent 的能力，只是查看历史、继续对话、管理模型和文件会更方便。

三、整体工作流程

下面这张图可以帮助理解 Pi Agent Web 的工作方式：

四、环境准备

使用前建议准备好：

• Node.js
• npm
• 已经可用的 Pi Coding Agent 环境
• Windows、macOS 或 Linux 均可

如果你只是想体验 Web 界面，最简单的方式是直接用npx启动。

五、方式一：直接通过 npx 启动

打开终端，执行：

npx @maddie1/pi-agent-web@latest

启动成功后，在浏览器中打开：

http://localhost:30141

如果你使用的是国内 npm 镜像，新版本可能还没有同步，可以临时指定官方源：

npx @maddie1/pi-agent-web@latest--registryhttps://registry.npmjs.org

启动成功会是这样。

六、方式二：全局安装后启动

如果你经常使用，可以全局安装：

npminstall-g@maddie1/pi-agent-web

安装完成后，可以使用下面任意一个命令启动：

pi-web

或者：

pi-agent-web

默认访问地址依然是：

http://localhost:30141

如果想指定端口：

pi-web--port8080

如果想指定 host：

pi-web--hostname127.0.0.1

也可以同时指定：

pi-web-p8080-H127.0.0.1

七、方式三：运行源码项目

如果你想二次开发或者调试源码，可以克隆项目后本地运行：

链接: GitHub 源码地址

gitclone https://github.com/MaddieMo1/Pi-Agent-Web.gitcdPi-Agent-Webnpminstallnpmrun dev

开发服务默认运行在：

http://localhost:30141

项目中的常用检查命令：

node_modules/.bin/tsc--noEmitnpmrun lint

注意：开发过程中不建议运行next build。项目开发说明中明确提到，next build会生成.next/构建产物，可能影响本地开发服务。

八、Windows 一键启动

如果你在 Windows 上使用，可以直接双击项目根目录下的：

启动 Pi Agent.bat。

这个脚本会自动做几件事：

1. 检查项目目录是否正确
2. 检查项目内置技能文件是否存在
3. 创建桌面快捷方式
4. 检查系统依赖
5. 如果没有node_modules，自动执行npm install
6. 启动开发服务
7. 等服务可访问后自动打开浏览器

也就是说，Windows 用户不熟悉命令行也可以比较轻松地启动项目。

下载解压之后双击这个.bat 文件就能一键启动了。

当然第一次启动之后，桌面也会有一个快捷方式，下次启动可以直接双击桌面快捷方式。

九、界面功能介绍

进入 Web 页面后，你会看到一个类似本地 Agent 控制台的界面。整体可以理解为三块：

• 左侧：会话列表和文件浏览
• 中间：聊天窗口
• 底部：输入框、模型选择、工具设置和压缩控制

1. 查看历史会话

Pi Agent Web 会读取本地会话目录：

~/.pi/agent/sessions

会话文件一般长这样：

~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl

左侧边栏会按照工作目录分组展示会话。点击某个会话后，中间区域会显示该会话的消息内容。

如果某个会话文件第一行无法解析为合法 header，页面会把它标记为 orphaned，也就是不完整会话。

2. 继续对话

选择一个已有会话后，可以直接在底部输入框继续发送消息。

发送消息时，服务端会通过startRpcSession()创建或复用一个内存中的 AgentSession，然后前端通过 SSE 接收实时事件。

这意味着你在浏览器中看到的不是一次性返回结果，而是流式输出。

3. 查看工具调用

Agent 在执行任务时可能会调用工具，比如读取文件、执行命令、搜索内容等。

Pi Agent Web 会把工具调用和工具结果展示出来，方便你理解 Agent 到底做了什么。

这一点对调试非常有用。因为你不仅能看到最终回答，还能看到中间过程。

工具调用。

4. Fork 会话

在某条用户消息上点击 Fork，可以从这个节点创建一个新的独立会话。

Fork 适合下面这些场景：

• 想从某个历史问题重新尝试另一种方案
• 不想破坏原来的对话上下文
• 想保留多个并行探索方向

Fork 创建的是新的.jsonl会话文件，侧边栏中会以子会话形式展示。

5. 会话内分支切换

除了 Fork，Pi Agent Web 还支持同一个会话文件内的分支导航。

它和 Fork 的区别是：

如果你在同一个节点下产生了多个后续回复，可以通过 BranchNavigator 进行切换。

你可以悬浮在对话上然后点击分支按钮。

6. 模型配置

Pi Agent Web 可以读取和编辑本地模型配置：

~/.pi/agent/models.json

新建会话时，默认模型来自：

~/.pi/agent/settings.json

在界面中可以打开模型配置面板，查看当前可用模型、默认模型等信息。

左下角点击模型按钮

点击添加提供商

选择你有的APIKey ，推荐DeepSeek，当然如果有你 OpenRouter 就可以选择任何一家模型了。

7. 工具预设

新建会话时，可以传入工具列表：

toolNames[]

项目里预置了几种工具模式，例如：

• 不启用工具
• 默认工具
• 完整工具

如果完全禁用工具，后端会注入一个极简 system prompt，让 Agent 在无工具环境下也能正常回复。

8. 文件浏览

左侧边栏还提供了文件浏览能力。

你可以查看当前工作目录下的文件，并在标签页中打开文件内容。

这对于代码项目非常实用：一边和 Agent 对话，一边查看项目文件，不需要频繁切换编辑器和终端。

项目文件夹里面有多少文件，在网页上就会显示多少文件。

十、内置 Skills 简单应用案例

Pi Agent Web 项目里还内置了一组常用 skills。可以把 skill 理解成 Agent 的“专业能力包”：当用户提出某类任务时，Agent 会读取对应 skill 的说明，然后按照更专业的流程完成任务。

你截图里的内置 skills 包括：

edge-tts find-skills hyperframes pdf skill-creator tavily-search

1. edge-tts：把文字转成语音

edge-tts适合做文本转语音，比如把一段讲稿生成中文语音、给视频生成旁白、把长文本转成音频方便收听。

示例需求：

请用 edge-tts 把下面这段文字生成中文语音，声音使用 zh-CN-XiaoxiaoNeural： 欢迎使用 Pi Agent Web，这是一个用于本地 Pi Coding Agent 的浏览器界面。

它背后常用的命令类似：

uvx edge-tts--text"欢迎使用 Pi Agent Web"--write-media output.mp3--voicezh-CN-XiaoxiaoNeural

如果想调整语速：

uvx edge-tts--text"欢迎使用 Pi Agent Web"--write-media output.mp3--rate=+20%

典型应用：

• 生成课程旁白
• 生成短视频解说音频
• 把博客内容转成可收听版本
• 给产品演示视频配音

2. find-skills：发现更多可安装技能

find-skills适合在你不知道有没有现成能力包时使用。

比如你想让 Agent 支持 React 性能优化、自动写测试、部署 Vercel、生成变更日志，就可以先找有没有现成 skill。

示例需求：

有没有适合做 React 性能优化的 skill？帮我找一下。

它常用的命令类似：

npx skillsfindreact performance

如果找到了合适的 skill，可以继续安装：

npx skillsadd<skill-package>

典型应用：

• 给 Agent 扩展新能力
• 查找特定领域的工作流
• 给团队统一安装常用 skills
• 发现别人已经整理好的最佳实践

3. hyperframes：生成视频和动画内容

hyperframes用来创建 HTML 驱动的视频内容。它比较适合做标题片、产品介绍视频、字幕动画、音频响应动画、转场动画等。

示例需求：

用 hyperframes 做一个 15 秒的 Pi Agent Web 介绍视频，放在单独的文件夹内。 第一幕展示标题，第二幕展示三项功能：历史会话、实时对话、文件浏览。 最后一幕显示访问地址 http://localhost:30141。

它的核心思路是：用 HTML、CSS 和 GSAP 动画描述视频画面，再通过渲染工具导出视频。

典型应用：

• 生成产品宣传短片
• 制作课程片头
• 给技术教程生成动态封面
• 做带字幕的演示视频

输入完需求之后，如果你还有需要补充的可以直接在对话框中输入需求，然后点击插入按钮就好了。 插入按钮的作用就是在当前需求中优先解决当前需求。 排队按钮的作用是，解决完当前需求之后，再解决提出的新需求。

任务完成之后会输出详情，包括如何启动以及文件地址等。

运行效果。

4. pdf：读取、生成和检查 PDF

pdf适合处理 PDF 文件，尤其是需要关注版式、排版和视觉效果的场景。

示例需求：

帮我读取这个 PDF 的内容，总结主要章节，并检查里面的表格有没有排版错乱。

如果是生成 PDF，可以这样提需求：

请把这篇 Pi Agent Web 使用教程整理成 PDF，要求包含标题、目录、代码块和截图占位。

它常用的处理方式包括：

• 用pdfplumber或pypdf提取文字
• 用reportlab生成 PDF
• 用pdftoppm把 PDF 渲染成图片检查版式

典型应用：

• 阅读论文或报告
• 提取 PDF 表格和正文
• 生成项目说明书
• 检查 PDF 是否有文字遮挡、图片模糊或排版错乱

鼠标悬浮在文件上可以点击引用。

说完需求会自动调用 skill 来进行分析。

5. skill-creator：创建自己的专属技能

skill-creator用来创建、修改和优化 skills。适合把你经常重复做的工作流程沉淀成一个可复用能力包。

示例需求：

我经常要把项目 README 改写成 CSDN 博客。 请帮我创建一个 skill，以后遇到类似需求时自动生成教程结构、截图建议和发布标题。

一个 skill 通常包含：

my-skill/ SKILL.md references/ scripts/ assets/

其中SKILL.md是核心说明文件，会告诉 Agent：

• 什么时候触发这个 skill
• 应该按什么步骤执行
• 输出格式是什么
• 是否需要使用脚本或模板

典型应用：

• 给团队沉淀固定开发流程
• 创建项目专属代码审查规范
• 创建写作、发布、测试、部署类工作流
• 把个人经验变成 Agent 可复用的能力

6. tavily-search：联网搜索资料

tavily-search适合需要联网检索资料的场景。相比普通搜索结果，它更偏向给 LLM 使用，会返回结构化结果、摘要片段、相关性分数和元数据。

示例需求：

帮我搜索 Pi Coding Agent 的相关资料，并整理成适合写博客引用的要点。

常用命令类似：

tvly search"Pi Coding Agent tutorial"--json

如果只想看最近一周新闻：

tvly search"AI coding agent news"--time-range week--topicnews--json

如果想限制来源域名：

tvly search"Next.js SSE tutorial"--include-domains nextjs.org,vercel.com--json

典型应用：

• 写博客前查资料
• 查最新技术动态
• 搜索官方文档
• 收集竞品信息
• 给文章补充引用来源

搜索结果汇总。

7. 一个组合使用案例：生成一篇带视频和语音的教程

这些 skills 可以组合起来使用。比如你想做一篇更完整的 Pi Agent Web 教程，可以这样安排：

1. 用 tavily-search 搜索相关资料，补充背景信息 2. 用 pdf 把最终教程导出成 PDF 3. 用 edge-tts 把教程摘要生成语音 4. 用 hyperframes 把语音和画面合成一个 30 秒短视频 5. 用 skill-creator 把这套流程沉淀成“技术博客发布 skill” 6. 用 find-skills 继续寻找 SEO、封面设计、社媒发布等扩展能力

示例完整需求：

请帮我把 Pi Agent Web 项目整理成一套发布材料： 先联网补充资料，再写 CSDN 教程； 然后生成一份 PDF 版本； 再把摘要转成中文语音； 最后设计一个 30 秒短视频脚本，方便发到视频平台。

这样一来，Pi Agent Web 就不只是一个聊天界面，而是可以逐步扩展成一个本地 AI 工作台。

十一、项目目录结构

核心目录大致如下：

app/ api/ agent/ Agent 会话创建、命令发送、SSE 事件流 sessions/ 历史会话列表、详情、删除、上下文读取 files/ 本地文件读取 models/ 模型列表和默认模型 models-config/ 模型配置读写 components/ AppShell.tsx 主布局、URL 状态、标签页管理 ChatWindow.tsx 消息加载、发送、流式事件处理 ChatInput.tsx 输入框、模型、工具、压缩控制 SessionSidebar.tsx 会话树和文件浏览器 MessageView.tsx 单条消息渲染 BranchNavigator.tsx 会话内分支导航 lib/ rpc-manager.ts AgentSession 生命周期和 registry session-reader.ts 解析本地 .jsonl 会话文件 normalize.ts 标准化 toolCall 字段 types.ts 共享类型 scripts/ bootstrap-deps.ps1 create-desktop-shortcut.ps1 wait-and-open.ps1

如果你只是使用，不需要理解所有源码。重点记住：

• app/api是后端接口
• components是前端界面
• lib/rpc-manager.ts负责真实 Agent 会话
• lib/session-reader.ts负责读取历史会话

十二、常见问题

1. 页面打开后没有历史会话？

先确认本地是否存在会话目录：

~/.pi/agent/sessions

如果你的 Agent 数据目录不是默认路径，可以通过环境变量指定：

PI_CODING_AGENT_DIR=/path/to/agent-dirnpmrun dev

Windows PowerShell 可以这样写：

$env:PI_CODING_AGENT_DIR="D:\your-agent-dir"npm run dev

2. npx 启动失败？

如果你使用国内 npm 镜像，可能是新版本还没有同步。可以指定官方源：

npx @maddie1/pi-agent-web@latest--registryhttps://registry.npmjs.org

3. 端口被占用怎么办？

默认端口是：

30141

你可以换一个端口：

pi-web--port8080

或者：

PORT=8080pi-web

Windows PowerShell：

$env:PORT="8080"pi-web

4. 开发时可以运行 next build 吗？

不建议。

项目开发说明里明确提醒：开发时不要运行next build，因为它会污染.next/目录，可能导致npm run dev出现异常。

日常开发建议使用：

npmrun dev

检查类型：

node_modules/.bin/tsc--noEmit

检查代码：

npmrun lint

十三、总结

Pi Agent Web 的价值在于：它把本地 Pi Coding Agent 的使用体验从命令行扩展到了浏览器。

如果你只是普通用户，可以直接用：

npx @maddie1/pi-agent-web@latest

然后打开：

http://localhost:30141

如果你是 Windows 用户，也可以直接双击：

启动 Pi Agent.bat

如果你是开发者，则可以从源码运行，进一步研究它的会话读取、SSE 流式通信、AgentSession 生命周期管理和分支机制。

整体来看，这个项目非常适合作为本地 Agent 的可视化控制台：既能看历史，又能继续对话，还能管理模型、工具和文件。对于经常使用 AI 编程 Agent 的开发者来说，会明显降低管理多轮会话的成本。

暂时先这样吧，如果实在看不明白就留言，看到我会回复的。希望这个教程对您有帮助！
路漫漫其修远，与君共勉。