Pi 与 Pi Web

1. 项目组合概览

1.1 两个项目是什么关系

可以把它们理解为：

• pi 是“引擎”和“终端工作台”。
• pi-web 是“浏览器控制台”和“会话/项目可视化层”。
• 二者共享 Pi 的本地配置、模型、技能和会话文件，典型数据目录是 ~/.pi/agent/sessions。

需要注意一个细节：pi-web README 中的链接仍写着 badlogic/pi-mono，但它的依赖和当前项目描述都指向 @earendil-works/pi-* 包；从当前 GitHub 元数据和 npm package 看，售前时建议以 earendil-works/pi 作为 Pi 主仓库来讲。

1.2 当前开源活跃度信号

检查日期：2026-07-25。以下 Stars、Forks、Release、最近提交时间均来自 GitHub API，属于会变化的信息。

2. 它主要能做什么

2.1 Pi：最小核心、强扩展的 Coding Agent

Pi 官方文档把它定义为 “minimal terminal coding harness”。它不是把所有能力都塞进核心，而是保留一个较小的内核，然后通过 TypeScript Extensions、Skills、Prompt Templates、Themes 和 Pi Packages 让用户按工作流扩展。

Pi 的核心组成：

Pi 默认给模型四类主要工具：read、write、edit、bash。除此之外，它支持通过 Skills 和 Extensions 加载更多能力。它的哲学很鲜明：不内置 MCP、不内置子 Agent、不内置权限弹窗、不内置 plan mode、不内置 todo，而是让用户通过扩展、容器、tmux、外部包或自己的工作流来实现。

这会让 Pi 更像“可编程 Agent Harness”，而不是“一站式全家桶 Agent 产品”。

2.2 Pi 的终端交互体验

Pi 的交互模式截图如下：

Pi 的 TUI 包含启动头、消息区、输入编辑器、底部状态栏。底部会显示工作目录、会话名、token/cache 使用、成本、上下文占用和当前模型。对开发者而言，这比普通命令行聊天更适合长时间编码任务。

它支持：

• @ 引用项目文件。
• Tab 补全路径。
• Shift+Enter 多行输入。
• Ctrl+G 打开外部编辑器。
• Ctrl+L 打开模型选择器。
• /model 切换模型。
• /resume 选择历史会话。
• /tree 在会话树中跳转。
• /compact 手动压缩上下文。
• /share 分享会话。
• pi -p 非交互一次性输出。
• pi --mode json 输出 JSON event stream。
• pi --mode rpc 通过 stdin/stdout JSONL 做进程集成。

2.3 Pi 的会话树与分支能力

Pi 会话以 JSONL 保存，支持树结构，每条 entry 有 id 和 parentId。用户可以在同一个会话文件里从历史节点继续，形成分支；也可以 fork 到新的会话文件。

这对 Coding Agent 很关键：真实开发中经常需要从某个中间点尝试另一种方案，而不是简单线性聊天。Pi 的 /tree、/fork、/clone 能把“探索不同实现路径”变成一等能力。

2.4 Pi 的 SDK / RPC 嵌入能力

Pi 不只是 CLI。它提供：

• SDK：Node.js 应用可以直接 createAgentSession()。
• RPC Mode：非 Node.js 应用可以通过 pi --mode rpc 用 LF 分隔的 JSONL 协议集成。
• JSON Mode：一次性任务输出结构化事件。
• @earendil-works/pi-agent-core：独立 Agent runtime，可用于自建应用。
• @earendil-works/pi-ai：独立多模型调用库，可用于非 Pi Agent 场景。

这让 Pi 适合作为企业内部 Agent 工具链的底层库，而不仅是一个可执行 CLI。

2.5 Pi Web：本地浏览器工作台

Pi Web 是 Pi Coding Agent 的本地 Web UI。它读取本机 Pi 会话文件，提供会话管理、实时对话、模型配置、技能管理和项目文件预览。

项目原生关键截图如下：

Pi Web 解决的是纯 CLI 的可视化短板：

• 按项目浏览历史会话，不用翻 ~/.pi/agent/sessions。
• 从历史消息继续、fork 会话、探索不同路线。
• 左侧浏览项目文件，右侧预览源码、Markdown、图片、音频、PDF、DOCX。
• 查看上下文占用、成本、压缩状态、系统提示。
• 在 Web UI 中管理模型、登录/API Key、模型测试和技能开关。
• 支持 Git worktree 切换，让不同分支/checkout 的新会话和 Explorer 跟随选定工作区。
• 通过 SSE 与后端 AgentSession 实时通信。

3. 支持的模型和 Provider

Pi 的 @earendil-works/pi-ai 支持大量 provider。官方 README 明确列出包括：

• OpenAI
• Azure OpenAI
• OpenAI Codex
• Anthropic
• Google Gemini
• Google Vertex AI
• DeepSeek
• NVIDIA NIM
• Mistral
• Groq
• Cerebras
• Cloudflare AI Gateway / Workers AI
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI Coding Plan
• MiniMax
• Together AI
• Hugging Face
• Moonshot AI / Kimi For Coding
• GitHub Copilot
• Amazon Bedrock
• Fireworks
• Xiaomi MiMo
• OpenAI-compatible APIs：Ollama、vLLM、LM Studio 等

Pi Coding Agent README 还提到可通过 /login 使用订阅类 provider，例如 Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro（Codex）、GitHub Copilot；也可以使用 API Key provider。对售前来说，这个点非常有价值：它让客户可以从已有订阅或 API Key 开始，也可以对接内部模型网关。

4. 适用场景

场景一：研发团队的本地 Coding Agent

适合对象：研发工程师、技术负责人、AI 编程工具探索团队。

Pi 的优势在于轻量、终端原生、会话可分支、模型可切换、工具可扩展。它适合：

• 在本地项目目录中让 Agent 阅读、修改、搜索代码。
• 用 @file 引用关键文件，配合 read/edit/bash 完成任务。
• 用 /tree 回到某个历史节点尝试不同实现。
• 用 /compact 管理长上下文。
• 用 Pi Web 复盘会话、查看变更文件、预览文档和图片。

场景二：Agent 平台团队的底层 Harness

适合对象：正在自研 Agent 平台、AI IDE、代码助手、内部自动化工具的团队。

Pi 的 pi-ai 和 pi-agent-core 可拆开使用：

• pi-ai 解决多 provider 统一调用、认证、事件流、token/cost、工具调用兼容。
• pi-agent-core 解决 Agent 状态、事件流、工具执行、hook、上下文转换。
• Coding Agent CLI 是一个完整参考实现。

售前可以把它当作“TypeScript 技术栈下的 Agent Runtime 参考实现”来讲。

场景三：需要可视化会话复盘的 Agent 使用团队

Pi Web 的价值在于把终端里的 Agent 会话变成可浏览、可管理、可复盘的工作台。

适合：

• 需要从历史会话继续工作的开发者。
• 想对比多个实现路线的工程师。
• 希望向团队展示 Agent 如何完成某个任务的人。
• 希望把代码、Markdown、图片、PDF 预览与 Agent 聊天放在一个界面中的用户。

场景四：多模型评估与 Agent 工作流实验

Pi 支持快速切模型、模型列表刷新、成本/上下文可见、会话导出、JSON/RPC 模式，适合做：

• 不同模型在同一代码任务上的效果比较。
• 工具调用策略实验。
• Prompt Template / Skills / Extensions 实验。
• Agent 会话数据采集和复盘。

场景五：内部工具包/Agent 包生态探索

Pi Packages 可以把 extensions、skills、prompts、themes 打包，通过 npm 或 git 分享。对企业内部来说，可以沉淀为：

• 团队编码规范包。
• 内部部署/发布包。
• 安全审计工具包。
• 项目专属 Prompt Template。
• 内部 API 工具扩展。

5. 不太适合的场景

6. 核心能力清单

6.1 Pi 能力矩阵

6.2 Pi Web 能力矩阵

7. 架构、部署与集成方式

7.1 逻辑架构

7.2 部署方式

Pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi

Linux/macOS installer：

curl -fsSL https://pi.dev/install.sh | sh

Pi Web：

npx @agegr/pi-web@latest

或全局安装：

npm install -g @agegr/pi-web
pi-web

默认打开：

http://localhost:30141

常用参数：

pi-web --port 8080
pi-web --hostname 127.0.0.1
pi-web --no-open

PORT=8080 pi-web
PI_WEB_NO_OPEN=1 pi-web

7.3 安全隔离方式

Pi README 明确说明：Pi 不包含内置权限系统来限制文件系统、进程、网络或凭证访问；默认以启动它的用户和进程权限运行。如果需要更强边界，要容器化或沙箱化。

官方 containerization 文档给了三种模式：

售前时要讲清楚：Pi 的“无内置权限弹窗”是产品哲学，不是缺陷本身；但企业落地必须通过容器、沙箱或扩展补权限边界。

8. 怎么用

8.1 Pi 快速上手

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以先启动后用：

/login

选择 provider 后使用订阅或 API Key。

常见命令：

/model       切换模型
/resume      选择历史会话
/new         新会话
/tree        在当前会话树里跳转
/fork        从历史消息创建新会话
/compact     压缩上下文
/settings    修改设置
/share       分享会话
/export      导出 HTML 或 JSONL
/reload      重新加载扩展、技能、提示词、主题、上下文文件

非交互模式：

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi --mode json "Review this project"
pi --mode rpc

只读审查：

pi --tools read,grep,find,ls -p "Review the code"

8.2 Pi Web 快速上手

npx @agegr/pi-web@latest

打开：

http://localhost:30141

如果 Pi 的目录不在默认位置：

PI_CODING_AGENT_DIR=/path/to/pi-agent npx @agegr/pi-web@latest

代理环境：

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @agegr/pi-web@latest

8.3 SDK 示例

Pi Coding Agent SDK：

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

await session.prompt("What files are in the current directory?");

Agent Core 示例：

import { Agent } from "@earendil-works/pi-agent-core";
import { createModels } from "@earendil-works/pi-ai";
import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";

const models = createModels();
models.setProvider(anthropicProvider());
const model = models.getModel("anthropic", "claude-sonnet-4-6");

const agent = new Agent({
  initialState: {
    systemPrompt: "You are a helpful assistant.",
    model,
  },
  streamFn: models.streamSimple.bind(models),
});

await agent.prompt("Hello!");

9. 售前可以怎么讲

9.1 一句话话术

Pi + Pi Web 是一套偏开发者本地场景的 Coding Agent 工作台：Pi 负责多模型 Agent 执行、终端交互和扩展机制，Pi Web 负责把本地会话、项目文件、模型配置和技能管理可视化，适合用于研发团队探索可控、可扩展、可复盘的 AI 编码助手。

9.2 客户痛点映射

9.3 与其他 Coding Agent 的差异

10. 常见客户问题

11. PoC 建议

PoC A：研发个人效率工作台

目标：验证开发者用 Pi + Pi Web 完成真实代码任务的体验。

步骤：

1. 在一个中等规模 TypeScript/Python/Go 项目中安装 Pi。
2. 配置一个主力模型，例如 Claude、OpenAI、OpenRouter 或企业内部 OpenAI-compatible endpoint。
3. 让 Pi 完成“理解模块、修改 bug、补测试、运行命令、解释变更”的任务。
4. 用 /tree 从中途改走另一种方案。
5. 用 Pi Web 打开会话，查看文件变更、工具调用、Markdown 输出和上下文成本。

成功指标：

PoC B：企业内部 Agent Harness 验证

目标：评估 pi-ai 和 pi-agent-core 是否适合作为内部 Agent runtime 参考。

步骤：

1. 用 pi-ai 接两个以上模型 provider。
2. 用 pi-agent-core 自定义一个简单 Agent，接入内部只读工具。
3. 用 SDK 或 RPC 模式接入现有平台。
4. 记录事件流、工具调用、错误处理和成本统计。

成功指标：

• 模型 provider 切换是否顺畅。
• 工具 schema 与执行流是否满足内部需求。
• 事件流是否能驱动自研 UI。
• 认证和密钥管理能否符合企业要求。

PoC C：Pi Web 会话复盘与工作流培训

目标：验证 Pi Web 是否能帮助团队学习和复盘 AI 编码过程。

步骤：

1. 选择一个已完成的 Pi 会话。
2. 用 Pi Web 展示结构化 Markdown、tool calls、项目文件导航。
3. 从历史消息 fork 一条新路线。
4. 使用 Git worktree 切换，在不同分支上比较实现。

成功指标：

• 团队成员是否能理解 Agent 采取了哪些步骤。
• 历史会话是否容易找到。
• 文件预览是否减少终端上下文切换。
• Worktree 是否适合并行试验。

12. 风险和注意事项

12.1 权限与安全

Pi 默认以启动用户权限运行，不内置权限系统。售前时必须明确：

• 不要在高权限目录中无隔离运行。
• 不要让不可信 prompt 或不可信代码直接驱动本机高权限操作。
• 第三方 Pi Packages、Extensions、Skills 都需要审查。
• 若涉及企业源代码、凭证、内部网络，建议先用 Docker、Gondolin 或 OpenShell。

12.2 Pi Web 的边界

Pi Web 是本地 Web UI，不是企业级 SaaS。要注意：

• 文件访问被设计为围绕选定项目目录和会话工作目录，但仍运行在本机服务进程中。
• 如果绑定到非本机地址，需要额外考虑访问控制、网络暴露和凭证风险。
• 当前更适合个人/小团队本地使用，不适合直接作为企业多人平台交付。

12.3 生态成熟度

Pi 的 Release 非常活跃，Pi Web 也在快速演进。活跃是优点，但也意味着：

• API 和依赖版本可能变化较快。
• Pi Web 当前依赖 Pi 0.81.1，而 Pi 最新为 0.82.1，需要关注兼容性。
• 新功能适合试点，正式落地要锁版本。

12.4 与客户期望的匹配

如果客户期待的是“开箱即用、有中央管理、有审批、有审计、有多人权限”的企业产品，Pi + Pi Web 需要额外封装。它更适合技术团队构建自己的 Agent 工作流，而不是直接卖给非技术业务部门作为最终产品。

13. 我的售前判断

Pi + Pi Web 这组项目最适合放在“AI 编码助手底层能力”和“开发者本地 Agent 工作台”两个方向来讲。

Pi 的最大亮点是设计取舍清晰：它不追求大而全，而是把多模型 API、Agent runtime、终端体验、会话树、扩展机制做好，再让用户通过 TypeScript Extensions、Skills、Prompt Templates 和 Packages 自己扩展。对于技术能力强的客户，这是优点，因为它不会强行规定工作流；对于想快速采购成品平台的客户，这反而是门槛。

Pi Web 的价值是把 Pi 从纯终端体验推进到“可视化工作台”：历史会话、文件预览、Git worktree、模型配置、技能管理、上下文/成本状态都在浏览器中可见。它非常适合 demo、复盘、团队培训和降低 CLI 使用门槛。

售前推荐策略：

• 面向研发团队：强调“更透明、可分支、可复盘的 Coding Agent”。
• 面向平台团队：强调 pi-ai + pi-agent-core 可作为 TypeScript Agent runtime 参考。
• 面向安全客户：先讲清默认无权限系统，再给 Docker/Gondolin/OpenShell 隔离方案。
• 面向非技术业务客户：不建议直接推荐，除非已做产品化封装。

14. 参考资料

• earendil-works/pi GitHub
• Pi 官方文档
• Pi Coding Agent README
• Pi Agent Core README
• Pi AI README
• Pi Containerization
• Pi Release v0.82.1
• agegr/pi-web GitHub
• Pi Web README
• Pi Web 中文 README
• Pi Web Worktrees
• Pi Web Release v0.8.0