Pi：不止编程，一套通用 Agent 框架

摘要

Pi 是 earendil-works 开源的 Agent 开发框架，很容易被”pi 命令行编程工具”这个第一印象带偏——它把”统一多模型 LLM API、通用 Agent 运行时、终端 UI、编程 Agent CLI”拆成四个独立又能组合使用的包，真正的通用能力在 pi-agent-core 这一层：一个带工具调用、状态管理和事件流的有状态 Agent 运行时，官方定位就是可以承载任意类型 Agent，而不是专为编程场景设计的。pi-coding-agent 只是官方基于这个运行时做出来的第一个应用；同一套底座上，官方还在做面向 Slack/聊天场景的 pi-chat，社区也在往上面装其他能力。项目本身对 npm 供应链安全下了狠功夫，并且鼓励把真实的 Agent 会话数据开源出来，反哺整个 Agent 生态。

核心优势

• 四个包，各自独立可用，编程 CLI 只是其中一个应用：pi-ai（统一多供应商 LLM API：OpenAI、Anthropic、Google 等）、pi-agent-core（通用的、带工具调用和状态管理的 Agent 运行时，不限定应用场景）、pi-tui（差分渲染的终端 UI 库）、pi-coding-agent（基于前三者搭出来的交互式编程 Agent CLI，是一个具体应用而非框架本身）——不想要完整 CLI，只用底层的 API 或运行时层完全没问题
• 供应链安全是一等公民，不是事后补丁：直接依赖锁定精确版本、.npmrc 设置 min-release-age=2 防止误装当天发布的新包、package-lock.json 作为唯一真相来源、CI 用 --ignore-scripts 安装并跑 npm audit signatures——这一整套机制在同类工具里相当少见
• 权限模型诚实透明：Pi 本身不带内置的文件系统/进程/网络权限限制，官方文档直接说明”默认以启动它的用户权限运行”，并给出 Gondolin 微虚拟机、纯 Docker、OpenShell 三种容器化方案供选择，而不是假装自己是安全的
• 推动 Agent 会话数据开源：项目明确鼓励用户通过 pi-share-hf 把真实编程会话发布到 Hugging Face，用真实工具调用、失败和修复过程来改进 Agent，而不是依赖玩具基准测试

不只是编程助手：pi-agent-core 之上能长出什么

pi-coding-agent 是官方基于 pi-agent-core 做出来的第一个应用，但不是唯一一个。同一个仓库里，官方还维护着面向 Slack/聊天场景自动化的 earendil-works/pi-chat，走的是完全不同的应用方向；社区也在往 pi-agent-core 上装其他能力，比如 pi-hermes-memory 这个扩展包，就是把 Nous Research 的 Hermes Agent 的持久记忆系统（MemoryStore 类、内容扫描器、后台审查循环、系统提示注入等设计）移植进了 Pi 生态。

顺带说清楚一个容易搞混的点：Nous Research 的 Hermes Agent 本身是一个完全独立的产品——自带终端 UI，还有 Telegram、Discord、Slack、WhatsApp、Email 等多渠道网关，支持 300+ 模型，并不是构建在 Pi 之上的，Pi 内部也不包含 Hermes 的代码。真实的关系是反过来的：pi-hermes-memory 是 Pi 社区借鉴、移植了 Hermes 的记忆系统设计，两者是各自独立、彼此借鉴的同行项目，不是谁包含谁。这个例子恰好说明 pi-agent-core 这层运行时的通用性——不同团队可以把不同来源的 Agent 能力，装进同一套底座里。

面向人群

• 想要一个可以自行扩展的终端编程 Agent、又不想被单一厂商 CLI 绑死的开发者
• 只需要”统一多模型调用”这一层能力、想直接复用 pi-ai 而不引入整个 Agent 框架的团队
• 想在自己的产品里嵌入通用 Agent 运行时（不限编程场景，工具调用 + 状态管理），拿 pi-agent-core 当底座自己搭 UI 或聊天机器人的开发者
• 关注 AI 工具供应链安全、想参考一套成熟 npm 依赖锁定/审计实践的团队

快速上手

安装并运行编程 Agent CLI：

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

pi 可以在任意目录下运行，进入交互式终端后直接用自然语言描述任务，Agent 会调用内置工具读写文件、执行命令。也可以从源码本地跑：

git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts
npm run build
./pi-test.sh   # 直接跑源码里的 pi，不用先发布安装

只需要统一的多模型 LLM 调用层，不需要完整 Agent：

npm install @earendil-works/pi-ai

import { complete } from '@earendil-works/pi-ai'

// 同一套接口，换 provider 只改 model 字符串
const response = await complete({
  model: 'anthropic/claude-sonnet-4-20250514',
  messages: [{ role: 'user', content: 'Hello!' }],
})

Skill：让 Agent 自我扩展

README 里”self extensible coding agent”这句话，具体落地就是 Pi 的 Skill 机制——和 Claude Code 的 Skill 几乎是同一套设计思路：把”该怎么做某类任务”写成一份 Markdown 说明书，让 Agent 按需自己去读、自己去用，而不是把每个新能力都硬编码进核心代码。

Skill 的发现位置（放对目录，Pi 启动时自动扫描，不需要额外注册）：

文件格式——一个 skill 就是一个目录，里面放一份带 YAML frontmatter 的 SKILL.md：

---
name: my-skill
description: 这个 skill 是做什么的、什么场景该用它
---
# 具体执行步骤、注意事项，Agent 会照着做

name 只能用小写字母、数字和连字符，1-64 个字符——和 npm 包名的命名限制类似，方便直接对应包名分发。

怎么被触发——两种模式：

• 自动匹配：所有已发现 skill 的 description 会被塞进系统提示词。用户描述任务时，Agent 判断和某个 skill 的 description 匹配，就自己去读完整的 SKILL.md 并按里面的步骤执行，不需要用户手动点名。
• 手动调用：想强制用某个 skill，直接 /skill:name 或带参数 /skill:name 具体参数。

配合前面提到的 npm 包分发方式，一个团队可以把内部约定的操作规范（比如”怎么发布内部服务""怎么走 code review 流程”）写成 skill，随 npm 包分发给所有用 Pi 的成员，效果类似”给 Agent 装插件”，但门槛只是写一份 Markdown。

进阶用法

容器化隔离——Pi 默认没有权限沙箱，官方给了三种按需选择的隔离方案：

# 方案一：Gondolin —— pi 和厂商鉴权留在宿主机，
# 内置工具与 `!` 命令路由进本地 Linux 微虚拟机
# 详见 packages/coding-agent/docs/containerization.md

# 方案二：纯 Docker —— 整个 pi 进程跑在容器里，隔离最简单
docker run -it --rm -v "$PWD":/workspace my-pi-image pi

# 方案三：OpenShell —— 整个 pi 进程跑在带策略控制的沙箱里

发布真实工作会话——用 pi-share-hf 把编程会话发布到 Hugging Face，帮助改进 Agent：

npm install -g badlogic/pi-share-hf
pi-share-hf --help   # 具体用法见该项目 README，需要 Hugging Face 账号 + CLI

供应链加固自查——项目自带的检查命令，接入自己的 CI 也适用：

npm run check   # lint、格式化、类型检查 + 已锁定依赖版本校验 + shrinkwrap 一致性
npm audit --omit=dev
npm audit signatures --omit=dev

Slack/聊天场景的自动化和工作流不在这个仓库里，单独在 earendil-works/pi-chat。