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

[Pi Agent Web 使用教程：把本地 Pi Coding Agent 搬进浏览器](#Pi Agent Web 使用教程：把本地 Pi Coding Agent 搬进浏览器)
- [一、Pi Agent Web 是什么？](#一、Pi Agent Web 是什么？)
- [二、Pi 是什么？](#二、Pi 是什么？)
- 三、整体工作流程
- 四、环境准备
- [五、方式一：直接通过 npx 启动](#五、方式一：直接通过 npx 启动)
- 六、方式二：全局安装后启动
- 七、方式三：运行源码项目
- [八、Windows 一键启动](#八、Windows 一键启动)
- 九、界面功能介绍
- - [1. 查看历史会话](#1. 查看历史会话)
  - [2. 继续对话](#2. 继续对话)
  - [3. 查看工具调用](#3. 查看工具调用)
  - [4. Fork 会话](#4. Fork 会话)
  - [5. 会话内分支切换](#5. 会话内分支切换)
  - [6. 模型配置](#6. 模型配置)
  - [7. 工具预设](#7. 工具预设)
  - [8. 文件浏览](#8. 文件浏览)
- [十、内置 Skills 简单应用案例](#十、内置 Skills 简单应用案例)
- - [1. edge-tts：把文字转成语音](#1. edge-tts：把文字转成语音)
  - [2. find-skills：发现更多可安装技能](#2. find-skills：发现更多可安装技能)
  - [3. hyperframes：生成视频和动画内容](#3. hyperframes：生成视频和动画内容)
  - [4. pdf：读取、生成和检查 PDF](#4. pdf：读取、生成和检查 PDF)
  - [5. skill-creator：创建自己的专属技能](#5. skill-creator：创建自己的专属技能)
  - [6. tavily-search：联网搜索资料](#6. tavily-search：联网搜索资料)
  - [7. 一个组合使用案例：生成一篇带视频和语音的教程](#7. 一个组合使用案例：生成一篇带视频和语音的教程)
- 十一、项目目录结构
- 十二、常见问题
- - [1. 页面打开后没有历史会话？](#1. 页面打开后没有历史会话？)
  - [2. npx 启动失败？](#2. npx 启动失败？)
  - [3. 端口被占用怎么办？](#3. 端口被占用怎么办？)
  - [4. 开发时可以运行 next build 吗？](#4. 开发时可以运行 next build 吗？)
- 十三、总结

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

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

一、Pi Agent Web 是什么？

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

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

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

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

text 复制代码

~/.pi/agent/sessions

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

二、Pi 是什么？

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

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

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

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

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

text 复制代码

~/.pi/agent/sessions

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

可以这样理解两者关系：

text 复制代码

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

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

推荐配图：

markdown 复制代码

![Pi 与 Pi Agent Web 的关系](这里替换为关系说明图)

三、整体工作流程

下面这张图可以帮助理解 Pi Agent Web 的工作方式：
浏览器界面
Next.js API Routes
AgentSessionWrapper
Pi AgentSession
本地 JSONL 会话文件
读取本地文件系统

四、环境准备

使用前建议准备好：

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

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

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

打开终端，执行：

bash 复制代码

npx @maddie1/pi-agent-web@latest

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

text 复制代码

http://localhost:30141

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

bash 复制代码

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

javascript 复制代码

启动成功会是这样。

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

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

bash 复制代码

npm install -g @maddie1/pi-agent-web

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

bash 复制代码

pi-web

或者：

bash 复制代码

pi-agent-web

默认访问地址依然是：

text 复制代码

http://localhost:30141

如果想指定端口：

bash 复制代码

pi-web --port 8080

如果想指定 host：

bash 复制代码

pi-web --hostname 127.0.0.1

也可以同时指定：

bash 复制代码

pi-web -p 8080 -H 127.0.0.1

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

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

链接: GitHub 源码地址

bash 复制代码

git clone https://github.com/MaddieMo1/Pi-Agent-Web.git
cd Pi-Agent-Web
npm install
npm run dev

开发服务默认运行在：

text 复制代码

http://localhost:30141

项目中的常用检查命令：

bash 复制代码

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

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

八、Windows 一键启动

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

text 复制代码

启动 Pi Agent.bat。

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

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

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

javascript 复制代码

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

javascript 复制代码

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

九、界面功能介绍

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

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

1. 查看历史会话

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

text 复制代码

~/.pi/agent/sessions

会话文件一般长这样：

text 复制代码

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

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

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

2. 继续对话

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

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

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

3. 查看工具调用

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

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

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

javascript 复制代码

工具调用。

4. Fork 会话

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

Fork 适合下面这些场景：

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

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

5. 会话内分支切换

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

它和 Fork 的区别是：

功能	作用	是否创建新会话文件
Fork	创建独立会话	是
会话内分支	在同一个会话里切换不同后续路径	否

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

javascript 复制代码

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

6. 模型配置

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

text 复制代码

~/.pi/agent/models.json

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

text 复制代码

~/.pi/agent/settings.json

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

javascript 复制代码

左下角点击模型按钮

javascript 复制代码

点击添加提供商

javascript 复制代码

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

7. 工具预设

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

text 复制代码

toolNames[]

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

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

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

8. 文件浏览

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

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

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

javascript 复制代码

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

十、内置 Skills 简单应用案例

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

你截图里的内置 skills 包括：

text 复制代码

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

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

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

示例需求：

text 复制代码

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

它背后常用的命令类似：

bash 复制代码

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

如果想调整语速：

bash 复制代码

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

典型应用：

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

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

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

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

示例需求：

text 复制代码

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

它常用的命令类似：

bash 复制代码

npx skills find react performance

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

bash 复制代码

npx skills add <skill-package>

典型应用：

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

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

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

示例需求：

text 复制代码

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

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

典型应用：

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

javascript 复制代码

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

javascript 复制代码

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

javascript 复制代码

运行效果。

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

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

示例需求：

text 复制代码

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

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

text 复制代码

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

它常用的处理方式包括：

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

典型应用：

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

javascript 复制代码

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

javascript 复制代码

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

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

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

示例需求：

text 复制代码

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

一个 skill 通常包含：

text 复制代码

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

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

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

典型应用：

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

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

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

示例需求：

text 复制代码

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

常用命令类似：

bash 复制代码

tvly search "Pi Coding Agent tutorial" --json

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

bash 复制代码

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

如果想限制来源域名：

bash 复制代码

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

典型应用：

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

javascript 复制代码

搜索结果汇总。

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

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

text 复制代码

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

示例完整需求：

text 复制代码

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

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

十一、项目目录结构

核心目录大致如下：

text 复制代码

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. 页面打开后没有历史会话？

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

text 复制代码

~/.pi/agent/sessions

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

bash 复制代码

PI_CODING_AGENT_DIR=/path/to/agent-dir npm run dev

Windows PowerShell 可以这样写：

powershell 复制代码

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

2. npx 启动失败？

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

bash 复制代码

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

3. 端口被占用怎么办？

默认端口是：

text 复制代码

你可以换一个端口：

bash 复制代码

pi-web --port 8080

或者：

bash 复制代码

PORT=8080 pi-web

Windows PowerShell：

powershell 复制代码

$env:PORT="8080"
pi-web

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

不建议。

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

日常开发建议使用：

bash 复制代码

npm run dev

检查类型：

bash 复制代码

node_modules/.bin/tsc --noEmit

检查代码：

bash 复制代码

npm run lint

十三、总结

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

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

bash 复制代码

npx @maddie1/pi-agent-web@latest

然后打开：

text 复制代码

http://localhost:30141

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

text 复制代码

启动 Pi Agent.bat

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

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

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

路漫漫其修远，与君共勉。