| name | pi |
| description | Pi（earendil-works/pi）是开源、可扩展、终端优先的 AI 编码 Agent Harness，提供 coding-agent CLI、统一多模型 API、Agent 运行时与 TUI 组件，支持 Anthropic/OpenAI/Google 等多提供商、Extensions/Skills 扩展与容器化隔离部署。 |
| tags | ["ai","agent","coding-agent","terminal","llm","typescript","extension","pi"] |
项目地址： https://github.com/earendil-works/pi
官网 / 文档： https://pi.dev ｜ https://pi.dev/docs/latest
最新发布： v0.80.3（以 Releases 为准）
许可证： MIT
概述
Pi 是一个面向工程化场景的 Agent Harness，不仅是单一 CLI。
@earendil-works/pi-coding-agent：交互式终端编码 Agent@earendil-works/pi-agent-core：Agent 运行时（工具调用 + 状态管理）@earendil-works/pi-ai：统一多模型 Provider API@earendil-works/pi-tui：终端 UI 渲染库
适用场景：
- 终端内多步代码任务（读改代码、执行命令、追踪上下文）
- 自建可扩展 Agent（Extensions / Skills / Prompt Templates）
- 需要模型供应商可替换、可审计、可容器化的团队环境
环境与安装
前置要求
- Node.js
>=22.19.0
- npm（或等价 Node 包管理器）
常用安装方式
npm install -g @earendil-works/pi-coding-agent
pi --version
如需源码开发：
git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts
npm run build
上游仓库是 monorepo，官方开发流程以 npm install --ignore-scripts、npm run build、npm run check 为主。
核心能力速览
| 能力 | 说明 |
|---|
| 多模型统一接入 | OpenAI / Anthropic / Google 等 Provider 统一抽象 |
| Agent 运行时 | 工具调用、会话状态、任务分解与执行 |
| CLI + TUI | 终端交互式编码体验，适配日常研发流程 |
| 可扩展机制 | Extensions、Skills、Prompt 模板、主题 |
| 容器化方案 | Gondolin / Docker / OpenShell 等隔离模式 |
| 工程化发布 | Monorepo + release 流程 + 依赖锁定策略 |
常用命令
pi --help
pi --version
开发仓库常用校验命令（在 pi 源码目录）：
npm run build
npm run check
npm run test
典型工作流
1) 本地终端编码助手
- 在项目目录启动
pi
- 让 Agent 分析需求并分步执行
- 审阅改动与命令输出
- 人工确认后提交
2) 团队扩展能力
- 基于 Extensions 定义团队工具接入方式
- 把可复用提示流程沉淀为 Skills
- 在仓库内版本化管理配置，确保团队一致性
3) 强隔离执行
- 对高权限任务采用容器/沙箱模式
- 将内置工具与
! 命令路由到隔离环境
- 保留宿主机 Provider 凭据与审计链路
安全与最佳实践
Pi 默认继承启动进程权限，不自带强制权限沙箱。生产建议：
- 对不受信任的任务启用容器化（Docker / Gondolin / OpenShell）
- 将敏感凭据放在最小权限环境变量中
- 固定依赖版本并审查 lockfile 变更
- 在 CI 中执行
npm ci --ignore-scripts + 安全审计
常见问题（FAQ）
| 问题 | 解决建议 |
|---|
pi 命令不可用 | 检查 Node 版本与全局安装路径，重新安装 @earendil-works/pi-coding-agent |
| 依赖安装失败 | 使用官方推荐的 npm install --ignore-scripts，并检查网络代理 |
| 模型调用异常 | 核对 Provider API Key、Base URL 与模型名称配置 |
| 想限制工具权限 | 使用容器化/沙箱运行，不要直接在高权限宿主机执行不受信任的任务 |
| 团队想统一规范 | 将 Skills/模板/配置文件纳入仓库版本控制并走 PR 审查 |
AI 使用建议
- 用户提到「Pi」「Agent Harness」「终端编码代理」「多 Provider 统一接入」时优先加载本技能。
- 回答部署问题时先确认是 个人本地使用 还是 团队隔离部署。
- 涉及权限控制时明确说明：Pi 默认不提供强制沙箱，应结合容器方案。
- 涉及版本差异时提醒以
pi --version 与 Releases 页面为准。
参考资源
