项目简介

pi（earendil-works/pi）是一套终端 AI 编码工具集，由 libGDX 作者 Mario Zechner 主导开发。TypeScript 编写，MIT 许可，GitHub 93579 stars、11580 forks。

• 原项目：https://github.com/earendil-works/pi
• 中文版：https://github.com/yangshun2005/pi-cn
• 官网：https://pi.dev

核心定位：一个可自我扩展的编码代理，让 pi 适应你的工作流，而不是反过来。

核心包结构

pi 是 monorepo，由几个可独立使用的包组成：

快速开始

# 安装编码代理 CLI
npm install -g @earendil-works/pi-coding-agent

# 交互模式运行
pi

从源码开发：

npm install --ignore-scripts   # 安装依赖（不运行生命周期脚本）
npm run build                   # 刷新模型数据并构建所有包
npm run build:offline           # 使用现有模型数据离线构建
npm run check                   # Lint、格式化、类型检查
./test.sh                       # 运行测试（无 API key 时跳过 LLM 依赖测试）
./pi-test.sh                    # 从源码运行 pi

四种运行模式

pi 的 coding-agent 支持四种运行方式，覆盖不同场景：

1. 交互模式：默认终端体验，带编辑器、命令、键盘快捷键。
2. 打印 / JSON 模式：脚本化和 CI 场景，结构化输出。
3. RPC 模式：进程集成，远程调用驱动 pi。
4. SDK 模式：把 pi 嵌入你自己的应用。

核心能力：不 Fork 就能扩展

pi 提供四种扩展手段，全部用 TypeScript 编写：

• 扩展（extensions）：扩展 pi 的能力。
• 技能（skills）：定义可复用的工作流。
• 提示模板（prompt templates）：定制提示。
• 主题（themes）：定制终端外观。

这些可以打包成 Pi 包（Pi packages），通过 npm 或 git 分享。pi 刻意省略了子代理和计划模式，让你按需构建或安装第三方包。

会话管理

• 分支：在对话节点分叉探索路径，合并或丢弃。
• 压缩：上下文过长时压缩历史，控制 token 消耗。

容器化与安全

pi 默认不包含权限系统，以启动它的用户权限运行。需要隔离时，提供三种模式：

• Gondolin 扩展：pi 和提供商认证留在主机，内置工具和 ! 命令路由到本地 Linux 微虚拟机。
• 纯 Docker：整个 pi 进程放进本地容器。
• OpenShell：策略控制的沙箱运行。

供应链加固

• 直接外部依赖固定精确版本，.npmrc 设 save-exact=true、min-release-age=2。
• package-lock.json 是依赖最终依据，npm run check 验证固定依赖。
• 发布包用 npm-shrinkwrap.json 固定传递依赖。
• CI 有计划性 npm audit 工作流。

中文版说明

中文版保留了全部代码和功能，仅对 README 与核心文档做了完整中文化，包结构、运行模式、容器化方案、供应链加固说明、开发命令均可直接以中文阅读。

如果这个项目对你有帮助，也欢迎动动小手去原仓库点个 Star，支持作者持续维护。