Pi Agent：统一多模型 LLM API 的 AI 编程 Agent 工具链

新贡献者提交的 issue 和 PR 默认会被自动关闭。维护者每天会审查被自动关闭的 issue。参见 CONTRIBUTING.md。

这是 Pi agent harness 项目的所在地，包含我们的自扩展编程 Agent。

@earendil-works/pi-coding-agent：交互式编程 Agent CLI

@earendil-works/pi-agent-core：具备工具调用和状态管理功能的 Agent 运行时

@earendil-works/pi-ai：统一多提供商 LLM API（OpenAI、Anthropic、Google……）

了解更多关于 Pi 的信息：

访问 pi.dev，那是附带演示的项目官网

阅读文档，你也可以直接让 Agent 自我解释

关于 Slack/聊天自动化和工作流，参见 earendil-works/pi-chat。

权限与容器化

Pi 不内置权限系统来限制文件系统、进程、网络或凭证的访问。默认情况下，它以启动它的用户和进程的权限运行。

如果需要更强的隔离，请将 Pi 容器化或沙箱化。参见 packages/coding-agent/docs/containerization.md，里面有三种模式：

Gondolin 扩展：将 pi 和提供商认证保留在宿主机上，而将内置工具和 ! 命令路由到一个本地 Linux 微虚拟机中。

Plain Docker：在本地容器中运行整个 pi 进程，实现简单隔离。

OpenShell：在策略控制的沙箱中运行整个 pi 进程。

参见 CONTRIBUTING.md 了解贡献指南，AGENTS.md 了解项目规则（对人类和 Agent 均适用）。Pi 的长期规划可在 RFC 中找到。

构建

npm install --ignore-scripts  # 安装所有依赖，但不运行生命周期脚本
npm run build         # 刷新模型数据，然后构建所有包
npm run build:offline # 使用现有模型数据重建，无需网络访问
npm run check         # Lint、格式化和类型检查
./test.sh            # 运行测试（没有 API key 时跳过依赖 LLM 的测试）
./pi-test.sh         # 从源码运行 pi（可从任意目录执行）

从发布源码构建独立二进制

GitHub release 包含一个带版本号的源码压缩包，其完整性由 release 的 SHA256SUMS 文件保障。解压后，运行与官方独立二进制相同的构建脚本：

VERSION="<release-version>"
tar -xzf "pi-${VERSION}-source.tar.gz"
cd "pi-${VERSION}"
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"

压缩包包含了 release 的模型数据和原生预编译产物。--offline-model-data 使用该模型数据而不刷新提供商目录。脚本会安装依赖并构建可执行文件及其运行时资源；如果依赖已提供，可传入 --skip-install 跳过安装。

供应链加固

我们把 npm 依赖变更视为经过审查的代码变更。

直接外部依赖精确锁定版本。内部 workspace 包保持版本范围格式。

.npmrc 设置 save-exact=true 和 min-release-age=2，以在 npm 解析期间避免同日依赖发布。

package-lock.json 是依赖的事实来源。pre-commit 阻止意外提交 lockfile（除非设置了 PI_ALLOW_LOCKFILE_CHANGE=1）。

npm run check 验证直接依赖的精确版本锁定、原生 TypeScript 导入兼容性以及生成的 coding-agent shrinkwrap。

发布的 CLI 包包含 packages/coding-agent/npm-shrinkwrap.json，它是从根 lockfile 生成的，用于锁定 npm 用户的可传递依赖。

Release 冒烟测试使用 npm run release:local 构建、打包，并在仓库外创建隔离的 npm 和 Bun 安装环境，然后才给 release 打标签。

本地 release 安装、文档记录的 npm 安装以及 pi update --self 都在支持的地方使用 --ignore-scripts。

CI 使用 npm ci --ignore-scripts 安装，计划的 GitHub workflow 运行 npm audit --omit=dev 加上 npm audit signatures --omit=dev。

Shrinkwrap 生成对依赖生命周期脚本有一个明确的允许列表；新的生命周期脚本依赖会触发检查失败，直至被审查通过。

分享你的开源编程 Agent 会话

如果你在开源工作中使用 Pi 或其他编程 Agent，请分享你的会话。

真实开源会话数据有助于用真实任务、工具使用、失败和修复来改进编程 Agent，而不是玩具基准测试。

完整说明参见 X 上的这篇帖子。

要发布会话，请使用 badlogic/pi-share-hf。阅读其 README.md 了解设置说明。你只需要一个 Hugging Face 账号、Hugging Face CLI 和 pi-share-hf。

你也可以观看这个视频，里面展示了我如何发布我的 pi-mono 会话。

我定期在这里发布我自己的 pi-mono 工作会话：

badlogicgames/pi-mono on Hugging Face

pi.dev 域名由 exe.dev 慷慨捐赠。