开源项目第187期：Pi — 哲学驱动的极简 AI Coding Agent，86k Stars，30+ LLM 提供商，无限扩展

引言“Adapt pi to your workflows, not the other way around.”这是「每日一个开源项目」系列的第 187 篇。今天的项目是Pi—— 一个极简哲学驱动的 AI coding agent harness86,334 颗 Star由游戏开发者 Mario ZechnerlibGDX 作者创建。Pi 有一个不寻常的 README 章节叫「Philosophy」里面逐条列出了它刻意不做的事没有 MCP、没有子 agent、没有权限弹窗、没有计划模式、没有内置待办列表、没有后台 bash。每条后面跟着理由以及「如果你真的需要用扩展自己做」。这不是功能缺失而是一种设计立场核心保持极简所有定制通过扩展层完成不强迫用户接受工具作者的工作流偏好。86k Stars2025 年 8 月创建MIT 许可。你会学到什么Pi 的 5 个 npm 包和各自的职责四种运行模式交互/打印/JSON/RPC/SDK会话分支树Session Tree的设计扩展生态Extensions、Skills、Prompt Templates、Pi PackagesPi 的哲学刻意不内置什么以及为什么30 LLM 提供商列表和切换方式前提知识基本的终端/命令行使用经验了解 AI coding agent 的基本概念工具调用、系统提示TypeScript 基础知识对理解扩展开发有帮助项目背景概述Pi 是一个 AI coding agent 的「harness」—— 这个词很准确它是一个驾驭 LLM 的框架而不是一个固定的产品。它把 LLM 接入、agent 循环、TUI 渲染、会话管理做成了独立的 npm 包让用户可以根据需要选择和扩展。项目信息作者: Mario ZechnerbadlogiclibGDX 游戏框架作者主语言: TypeScript许可证: MIT官网: pi.dev项目数据⭐ GitHub Stars:86,334 Forks: 10,721 许可证: MIT 创建时间: 2025-08-09五个 npm 包Pi 是一个 monorepo核心功能拆分成五个独立的 npm 包包名功能earendil-works/pi-ai统一多提供商 LLM APIOpenAI、Anthropic、Google 等earendil-works/pi-agent-coreAgent 运行时工具调用循环 状态管理earendil-works/pi-coding-agent交互式 coding agent CLI面向用户的主入口earendil-works/pi-tui差分渲染 TUI 库earendil-works/pi-telemetry厂商中立遥测合约、参考适配器、合规测试这种拆分让用户可以只用pi-ai做 LLM API 统一层或者只用pi-agent-core嵌入到自己的应用里不必接受整个 coding agent CLI。快速上手npminstall-g--ignore-scripts earendil-works/pi-coding-agent# 或者curl-fsSLhttps://pi.dev/install.sh|sh设置 API Key 或直接登录订阅账号exportANTHROPIC_API_KEYsk-ant-... pipi /login# 选择提供商支持订阅账号Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot默认开箱即用的工具read、bash、edit、write、grep、find、ls。不需要任何配置直接对话。30 LLM 提供商Pi 内置的提供商列表是目前 coding agent 工具里最全的之一订阅账号无需 API KeyAnthropic Claude Pro/MaxOpenAI ChatGPT Plus/ProCodexGitHub CopilotAPI Key 接入Anthropic、OpenAI、Azure OpenAI、DeepSeekGoogle Gemini、Google Vertex、Amazon BedrockMistral、Groq、Cerebras、xAICloudflare AI Gateway、Cloudflare Workers AIOpenRouter、Vercel AI GatewayHugging Face、Fireworks、Together AI、BasetenNVIDIA NIM、Kimi For Coding、MiniMax小米 MiMo含中国区、阿姆斯特丹、新加坡节点ZAI Coding Plan全球/中国、OpenCode Zen/GoAnt Ling本地推理llama.cpp router server/login llama.cpp/llama管理模型下载切换模型用CtrlL打开选择器或命令行pi--modelopenai/gpt-4o帮我重构这段代码pi--modelsonnet:high解决这个复杂问题# 带思考级别四种运行模式交互模式默认带 TUI 的交互终端从上到下启动头部快捷键提示、已加载的 AGENTS.md、模板、技能、扩展消息区对话、工具调用结果、错误、扩展 UI编辑器边框颜色标示思考级别底部状态栏工作目录、会话名、token 用量↑ 输入/↓ 输出/R 缓存读/W 缓存写/CH 缓存命中率、成本、当前模型打印模式非交互pi-p总结这个代码库catREADME.md|pi-p总结这段文字# 支持管道 stdinJSON 模式pi--modejson帮我分析这个问题# 输出所有事件为 JSONL适合脚本处理RPC 模式pi--moderpc# stdin/stdout JSONL 协议适合非 Node.js 进程集成SDK 模式嵌入使用import{createAgentSession,ModelRuntime,SessionManager}fromearendil-works/pi-coding-agent;constmodelRuntimeawaitModelRuntime.create();const{session}awaitcreateAgentSession({sessionManager:SessionManager.inMemory(),modelRuntime,});awaitsession.prompt(当前目录有哪些文件);会话系统会话存储会话以 JSONL 文件形式保存在~/.pi/agent/sessions/按工作目录分组。每条记录有id和parentId天然支持分支结构不需要创建多个文件。pi-c# 继续最近的会话pi-r# 浏览并选择历史会话pi --no-session# 临时模式不保存pi--name任务名# 命名会话会话分支树Session Tree这是 Pi 的一个独特设计按Escape两次打开/tree视图可以在整个会话历史树中导航跳到任意历史节点继续工作。/tree 快捷键 搜索输入关键词 折叠/展开分支Ctrl← / Ctrl→ 翻页← / → 过滤模式CtrlO默认→无工具→仅用户→仅标签→全部 复制消息CtrlX 添加书签ShiftL/fork从历史节点创建新会话文件修改后重新发送。/clone复制当前分支到新会话文件从当前位置继续。Context Compaction上下文压缩长会话超出上下文窗口时Pi 支持自动或手动压缩/compact# 手动压缩/compact 专注 API# 带自定义指令的压缩自动压缩默认开启在接近上下文限制时触发或上下文溢出时恢复重试。完整历史仍在 JSONL 文件中通过/tree可回溯。扩展生态ExtensionsTypeScript 扩展扩展是 Pi 最强大的机制TypeScript 模块可以添加自定义工具、命令、快捷键、事件处理、UI 组件。exportdefaultfunction(pi:ExtensionAPI){pi.registerTool({name:deploy,...});pi.registerCommand(stats,{...});pi.on(tool_call,async(event,ctx){...});}扩展能做的事README 列举的部分自定义工具或完全替换内置工具子 agent 和计划模式自定义上下文压缩和摘要权限门控和路径保护自定义编辑器和 UI 组件状态栏、头部、底部、覆盖层Git 检查点和自动提交SSH 和沙箱执行MCP server 集成让 Pi 看起来像 Claude Code游戏在等待期间玩 Doom —— 有人真的实现了扩展放在~/.pi/agent/extensions/全局或.pi/extensions/项目级。Skills技能包遵循 Agent Skills 标准按需加载的能力包Markdown 格式!-- ~/.pi/agent/skills/my-skill/SKILL.md -- # My Skill 当用户询问 X 时使用此技能。 ## Steps 1. 做这个 2. 然后那个通过/skill:名称手动调用或由 agent 根据 SKILL.md 描述自动选择。Prompt Templates提示词模板!-- ~/.pi/agent/prompts/review.md -- 检查这段代码中的 Bug、安全问题和性能问题。 重点关注{{focus}}编辑器里输入/review自动展开。Pi Packages将扩展、技能、模板、主题打包通过 npm 或 git 分享piinstallnpm:foo/pi-tools piinstallgit:github.com/user/repo piinstallgit:github.com/user/repov1# 固定版本pi list pi update--allpi config# 启用/禁用扩展、技能、模板⚠️安全警告Pi Packages 以完整系统权限运行。安装第三方包前请审查源代码。Pi 的哲学刻意不做什么Pi 的 Philosophy 章节逐条列出了它不内置的功能以及背后的原因刻意不做为什么如何满足需求MCP见这篇博文CLI 工具 README 更直接用扩展自己实现 MCP 支持子 agent实现方式各异不应由工具强制用 tmux 启动多个 pi 实例或扩展实现权限弹窗应与执行环境和安全需求契合不该是通用弹窗在容器里运行或扩展实现符合场景的确认流计划模式各有偏好把计划写进文件或扩展实现内置待办会让模型困惑用 TODO.md或扩展实现后台 bashtmux 有完整可见性和直接交互用 tmux这种「刻意极简」的设计哲学意味着 Pi 的核心不会随着功能膨胀而变得难以理解也不会强迫用户接受一套固定的工作流。代价是新用户的开箱体验不如功能全面的工具需要花时间配置才能达到理想状态。供应链安全Pi 对依赖安全的处理值得单独提精确版本锁定所有直接外部依赖固定到精确版本save-exacttrue内部 workspace 包使用范围版本最小发布年龄.npmrc设置min-release-age2避免安装当天刚发布的依赖package-lock.json 作为唯一真相pre-commit hook 阻止意外的 lockfile 修改需要PI_ALLOW_LOCKFILE_CHANGE1显式解除shrinkwrap发布的 CLI 包含npm-shrinkwrap.json对 npm 用户锁定传递依赖CI 审计定期运行npm audit --omitdevnpm audit signatures --omitdevLifecycle script 许可名单有明确允许列表新的 lifecycle script 依赖会导致检查失败直到被审查消息队列在 Agent 工作时发送一个细节设计在 agent 正在执行工具调用时可以提前排队消息Enter— 排队一条「引导」消息在当前工具调用完成后立即发送AltEnter— 排队一条「后续」消息在 agent 完成所有工作后发送Escape— 中止并把排队消息恢复到编辑器这解决了「agent 跑偏了但我又不想粗暴中断」的常见场景。参考资源官方链接GitHub: earendil-works/pi官网: pi.dev文档: pi.dev/docs/latestnpm: earendil-works/pi-coding-agentDiscord: discord.com/invite/3cU7Bz4UPx✍️作者博文: mariozechner.at/posts/2025-11-30-pi-coding-agent总结Pi 是一个有清晰设计立场的工具宁可核心极简、需要用户自己配置也不要一个充满内置功能但难以修改的黑盒。86k Star 说明这个立场找到了对应的用户群。几个工程决策值得记录Philosophy 章节主动声明不做什么并给出理由这在开源工具里比较少见。它让用户在安装前就能判断这个工具是否适合自己而不是安装后发现缺少某个「标准功能」。5 个独立 npm 包TUI、LLM API、agent 运行时各自独立意味着你可以只用pi-ai做多提供商统一层或者用pi-agent-core把 agent 循环嵌入自己的应用。不需要接受整个 CLI。会话分支树JSONL parentId的树形结构让分支不需要多文件所有历史都在一个文件里通过/tree视图随时导航。在其他 coding agent 工具里这种设计不常见。供应链安全的投入依赖精确锁定、lockfile pre-commit 保护、CI 定期审计、shrinkwrap 锁定传递依赖 —— 这个重视程度超过了大多数开发工具。如果你对 Claude Code、Codex 这类工具的工作流有自己的想法并且愿意花一点时间配置而不是开箱即用Pi 的扩展系统给了你足够的空间把它改造成你想要的样子。探索 PrimeSkills —— 精选 AI agent 和技能工具每一个都经过真实工作流验证。没有炒作只有真正好用的工具。访问我的个人主页获取更多见解和有趣的产品。