摘要
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：
bash
npm install -g @earendil-works/pi-coding-agent
pipi 可以在任意目录下运行，进入交互式终端后直接用自然语言描述任务，Agent 会调用内置工具读写文件、执行命令。也可以从源码本地跑：
bash
git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts
npm run build
./pi-test.sh # 直接跑源码里的 pi，不用先发布安装只需要统一的多模型 LLM 调用层，不需要完整 Agent：
bash
npm install @earendil-works/pi-ai
ts
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 启动时自动扫描，不需要额外注册）：
| 位置 | 用途 |
|---|---|
~/.pi/agent/skills/、~/.agents/skills/ |
全局 skill，所有项目都能用 |
.pi/skills/、.agents/skills/ |
项目级 skill（项目需先被信任） |
npm 包 package.json 里的 skills/ 目录 |
随包分发，npm install 即带上 |
--skill <path> |
运行时临时指定，不用挪目录 |
文件格式 ------一个 skill 就是一个目录，里面放一份带 YAML frontmatter 的 SKILL.md：
yaml
---
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 默认没有权限沙箱，官方给了三种按需选择的隔离方案：
bash
# 方案一：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：
bash
npm install -g badlogic/pi-share-hf
pi-share-hf --help # 具体用法见该项目 README，需要 Hugging Face 账号 + CLI供应链加固自查------项目自带的检查命令，接入自己的 CI 也适用：
bash
npm run check # lint、格式化、类型检查 + 已锁定依赖版本校验 + shrinkwrap 一致性
npm audit --omit=dev
npm audit signatures --omit=devSlack/聊天场景的自动化和工作流不在这个仓库里，单独在 earendil-works/pi-chat。