Pi 编程助手

Pi Agent Harness 概览

Pi 是一个自扩展的编程 Agent 框架，以 monorepo 形式组织多个包，覆盖 Agent 运行时、多家 LLM 提供商统一接口、终端 UI 与可观测性等核心能力。

核心包结构

• @earendil-works/pi-coding-agent：交互式编程 Agent CLI，面向终端用户的入口。
• @earendil-works/pi-agent-core：Agent 运行时，负责工具调用与状态管理，可被嵌入其他系统复用。
• @earendil-works/pi-ai：统一多提供商 LLM API，屏蔽 OpenAI、Anthropic、Google 等厂商差异。
• @earendil-works/pi-tui：基于差异渲染的终端 UI 库。
• @earendil-works/pi-telemetry：与厂商无关的可观测性契约、参考适配器、一致性测试与类型化 Schema。

Slack/聊天自动化与工作流相关能力见 earendil-works/pi-chat。

权限与容器化

Pi 不内置文件系统、进程、网络或凭证权限管控，默认以启动它的用户与进程权限运行。如需更强隔离，建议通过外部沙箱运行，文档给出了三种模式：

• Gondolin 扩展：pi 与提供方鉴权保留在宿主机，内置工具和 ! 命令被路由进本地 Linux micro-VM。
• 普通 Docker：将整个 pi 进程跑在本地容器中，适合简单隔离。
• OpenShell：将整个 pi 进程跑在策略受控的沙箱里。

本地开发

# 安装依赖（跳过生命周期脚本）
npm install --ignore-scripts

# 刷新模型数据后构建全部包
npm run build

# 离线构建（复用已有模型数据）
npm run build:offline

# 代码检查：lint、格式、类型
npm run check

# 运行测试（无 API key 时跳过依赖 LLM 的用例）
./test.sh

# 直接从源码运行 pi（可在任意目录执行）
./pi-test.sh

基于发布源码构建独立二进制

GitHub 发布物附带版本化的源码压缩包与 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"

源码包已包含发布时的提供商模型快照，--offline-model-data 会使用该快照而非重新拉取线上目录。脚本会安装依赖、构建 monorepo、编译 Bun 可执行文件并归置其运行时资源。若由打包方另行提供依赖，可追加 --skip-install --skip-deps。

供应链加固

• 直接外部依赖锁定精确版本，内部 workspace 包保留版本范围。
• .npmrc 启用 save-exact=true 与 min-release-age=2，避免 npm 解析引入同日发布。
• package-lock.json 作为依赖事实来源；提交前钩子阻止 lockfile 误提交，除非设置 PI_ALLOW_LOCKFILE_CHANGE=1。
• npm run check 校验直接依赖钉版本、原生 TypeScript 导入兼容性以及生成的 coding-agent shrinkwrap。
• 发布的 CLI 包附带 packages/coding-agent/npm-shrinkwrap.json，由根 lockfile 生成，为 npm 用户钉住传递依赖。
• 发布冒烟测试通过 npm run release:local 在仓库外完成打包与隔离安装，再做打 tag。
• 本地发布安装、文档化的 npm 安装与 pi update --self 在支持的环境下使用 --ignore-scripts。
• CI 使用 npm ci --ignore-scripts；定时任务执行 npm audit --omit=dev 与 npm audit signatures --omit=dev。
• Shrinkwrap 生成对依赖生命周期脚本设有显式白名单，未经审核的新生命周期脚本依赖会使校验失败。

许可

MIT。