earendil-works/pi —— AI代理工具包：统一LLM API、代理循环、TUI、编码代理CLI

这是什么

Pi 是一个由 earendil-works 团队维护的开源编码代理框架（GitHub 上拥有 72713 颗星，主语言 TypeScript）。其核心是一个“自扩展编码代理”（self extensible coding agent），即代理本身能够根据任务需要动态扩展自身能力。项目采用 monorepo 结构，包含三个主要包：

• @earendil-works/pi-coding-agent：交互式编码代理 CLI，开发者可直接在终端中与代理对话。
• @earendil-works/pi-agent-core：代理运行时，提供工具调用、状态管理、多轮对话等底层能力。
• @earendil-works/pi-ai：统一的多提供商 LLM API 封装，支持 OpenAI、Anthropic、Google 等多个模型，允许开发者灵活切换后端。

项目官网为 pi.dev，提供在线演示和完整文档。此外，还有 earendil-works/pi-chat 用于 Slack/聊天自动化和工作流集成。

解决的问题

传统编码代理通常将工具调用、状态管理、LLM 提供商绑定在一起，导致扩展性差、迁移成本高。Pi 解决的核心问题包括：

• 工具与运行时分离：pi-agent-core 提供通用运行时，工具调用和状态管理独立于具体 LLM 提供商，开发者可以自由组合不同模型。
• 自扩展能力：代理可以根据任务需求动态加载新工具或修改自身行为，避免硬编码固定能力集。
• 多提供商统一接口：pi-ai 屏蔽了不同 LLM API 的差异，开发者只需一套代码即可调用 OpenAI、Anthropic、Google 等模型，轻松切换或混合使用。
• 依赖管理严格性：项目对 npm 依赖采用精确版本锁定，通过 save-exact=true 和 min-release-age=2 避免同一天发布的新版本造成问题，并强制 package-lock.json 为依赖真实来源，防止未审查的锁文件被提交。

核心功能

1. 交互式编码代理 CLI：通过 pi 命令启动，代理可以执行代码生成、调试、重构、解释等任务，支持多轮对话。用户可以直接询问代理自身的工作原理（“ask the agent to explain itself”）。
2. 工具调用与状态管理：代理运行时支持注册自定义工具、维护对话历史和上下文状态，并支持工具链编排。
3. 统一 LLM 接口：支持 OpenAI、Anthropic、Google 等主流模型，用户可通过环境变量或配置文件切换提供商，无需修改代码。
4. 容器化与沙箱模式：项目不内置权限系统，默认以启动进程的权限运行。但提供了三种隔离方案：
   • Gondolin 扩展：在宿主机保留 pi 和提供商认证信息，将内置工具和命令路由到本地 Linux 微型虚拟机中。
   • Plain Docker：将整个 pi 进程运行在 Docker 容器中，实现简单隔离。
   • OpenShell：在策略控制的沙箱中运行整个 pi 进程。
5. 严格的依赖审查流程：所有 npm 依赖变更视为代码变更，需经过审查。npm run check 会验证直接依赖是否精确锁定、原生 TypeScript 导入兼容性以及生成的 shrinkwrap 文件。发布前通过 npm run release:local 进行本地构建、打包、创建隔离安装环境进行烟雾测试。
6. 会话分享机制：鼓励用户将使用 Pi（或其他编码代理）进行开源工作的会话数据分享到 Hugging Face，以帮助改进编码代理的真实世界表现。提供 badlogic/pi-share-hf 工具简化发布流程。

亮点 / 与同类相比

• 自扩展架构：与大多数静态定义工具集的编码代理不同，Pi 的代理可以在运行时动态引入新工具或修改行为，这使其更适合处理非结构化、需求多变的任务。
• LLM 提供商中立：不绑定任何特定模型，用户可自由选择或混合使用多种 LLM，降低对单一供应商的依赖，也更方便对比不同模型效果。
• 无内置权限系统：这是一个有意识的取舍——Pi 将安全边界交给用户自行选择容器化方案，而不是在代码层抽象出复杂的权限模型，从而保持核心轻量、灵活。相比之下，许多编码代理内置了文件系统、网络、进程的访问控制，但可能过度复杂或限制真实场景。
• 依赖管理极致严谨：精确锁定、禁止未审查锁文件、shrinkwrap 生成允许列表等机制，在开源项目中很少见，适合对稳定性要求高的生产环境使用。
• 开源社区协作友好：新贡献者的 issue 和 PR 默认自动关闭，但维护者每天审查，确保代码质量；同时明确要求分享会话数据以回馈生态，形成良性循环。

适合谁用 / 上手

适合人群：

• 需要将编码代理集成到现有工作流中的开发者，尤其是需要灵活切换多个 LLM 的场景。
• 希望构建自扩展工具链的团队，如自动化代码审查、CI/CD 辅助、文档生成等。
• 对 LLM 依赖管理有严格要求的项目（如需要精确锁定版本、避免供应商锁定）。
• 开源项目维护者，希望利用编码代理辅助日常开发，并愿意分享会话数据促进社区进步。

上手步骤：

1. 克隆仓库：git clone https://github.com/earendil-works/pi.git
2. 安装依赖并构建：npm install --ignore-scripts && npm run build
3. 运行测试：./test.sh（跳过依赖 LLM 的测试，若无 API 密钥）
4. 启动代理：./pi-test.sh（可从任意目录运行）
5. 配置 LLM 提供商：设置环境变量（如 OPENAI_API_KEY），或使用 pi-ai 支持的其他提供商。
6. 如需隔离，参考 packages/coding-agent/docs/containerization.md 选择 Docker、Gondolin 或 OpenShell 方案。

项目文档完善，官网有 Demo，且代理本身可以解释自身的运作方式，上手门槛较低。