7万星的工程艺术：PiAgent agent CLI 赛道早挤满了 Claude Code、Cursor、Codex、OpenCode，但 2025 年 8 月才创建的 PiAgent 不到一年涨到七万多星。靠功能列表解释不了这种增长，答案在它贡献指南的第一句话——pi's core is minimal，核心极其精简。这期拆开它的骨架，看清"最小核心"四个字怎么落地成代码、换来了什么、又牺牲了什么。 分层上五个包互不感知，pi-ai 连 agent 是什么都不知道，正因如此能换层壳孵化出 Slack 自动化的 pi-chat；事件循环是一台朴素状态机，工具默认并行、还能 steer 打断 followUp 排队；最反直觉的是子代理、计划模式根本不在核心，而是躺在 examples/extensions 里的示例扩展。PiAgent 明确不做六件事——MCP、子代理、权限弹窗、计划模式、内置 TODO、后台 bash——共享一条判断标尺：这功能能否在核心外被不同人用不同方式实现，而不需要我替所有人拍板。代价是信任散落生态、功能分裂、贡献门槛被 deliberately 抬高，新 issue 和 PR 默认自动关闭，得维护者回 lgtm 才解锁。落点一句话：agent 系统的边界画在确定性高、复用价值大的地方，把见仁见智、场景强相关的彻底让渡出去。 #PiAgent #AIAgent #极简架构 #开源 #AgentFramework

大家好，欢迎来到今天的节目。今天咱们聊一个Agent CLI赛道里的狠角色。这个赛道啊，说实话早就挤满了顶尖对手，Aider、Cursor、Codex、OpenCode，各个都不是省油的灯。哎，但偏偏就有这么一个项目，2025年8月才创建，名字叫PAgent，不到一年时间，GitHub上直接干到了七万多星，八千八百多次Fork。这个增长速度，你光靠功能列表解释不了，真正的答案藏在它贡献指南的第一句话里。这句话是这么说的：PAgent core is minimal，PAgent核心极其精简。就这四个字，到底怎么落地成代码，换来了什么？又牺牲了什么？这就是咱们今天要拆开来讲的东西。 好，咱们先从架构看起，打开仓库的packages目录，一共五个包：LLM管大模型接口，PAgent core是Agent运行时，PTY管终端界面，Coding Agent是PAgent这个命令行的CLI，还有Orchestrator，一个实验性的多进程编排。乍一看，这不就是个普通的Monorepo吗？但你仔细想，这种切分方式本身就是一种态度，关键在哪儿呢？下面三层互相不知道对方的存在。PI只关心一件事：你给我一个context，我吐回流式的session message，它根本不在乎调用你的是终端程序还是Web后端。PAgent core呢，只管工具调用循环和消息状态，它连文件系统都不认识，read、write、edit这些工具是Coding Agent这一层才引入的。API更纯粹，只管在终端画字，对LLM是什么、工具调用怎么跑一无所知。最后是Coding Agent，把三层拼成产品，到这一层，PAgent这个名字才第一次出现。 这么拆的回报是什么？很实在。正因为PI足够独立，PAgent背后的团队又孵化出了PIChat，一个做Slack自动化的产品，同一套底层接口换一层壳，就长成了第二种形态。所以你看，分层架构的实际回报是什么？是复用边界清晰到能直接孵化出第二个产品。架构解决了代码怎么摆，但真正决定Agent行为的，是PAgent core里的事件循环。你发一次Prompt，背后发生的是这样一串事件：Agent start、Turn start、用户消息进、助手带工具调用的消息出、工具执行start、中间update、工具结果消息进、Turn end，接着下一轮Turn start。拆开看，就是个朴素的状态机，一个Turn等于什么？一次LLM调用，加上这一轮触发的工具执行。模型说我要读文件，工具跑完把结果塞回消息历史，再触发下一个Turn，直到模型只返回文本，不再调工具为止。 这里有两个细节特别容易被忽略。第一，工具默认是并行执行的，不是教程Demo里那样一个个排队跑，同一批调用并发执行。当然，你也可以给单个工具要sequential，整体里只要有一个要顺序，这批就退化成顺序模式，在跑得快和不踩踏之间找平衡。第二，有插队机制，Interrupt是打断式插话，当前工具一跑完就立刻处理；Follow up是排队式追加，等Agent完全闲下来再说。对应到使用上，就是Enter和Alt+Enter两种，发送一个打断，一个排队。 如果说事件循环是架构，那扩展系统就是这幅架构上唯一被允许开枝散叶的地方。Extension API暴露的能力有哪些？注册自定义工具，注册斜杠命令，监听生命周期事件，自定义界面组件。就这四样。最有意思的发现就在这里，你以为是Coding Agent标配的东西，哎，子代理、计划模式，在PAgent里根本不在核心里，它们躺在examples/extensions目录下，SubAgent和Plan Mode是官方维护的示例扩展。一个扩展能做多深？给你举个例子，监听shutdown这个事件，你就能执行任意Shell命令，读写完整会话历史，在界面上弹通知，70行代码就能实现。扩展拿到的权限和核心代码是同一个量级的，它把核心和扩展之间的墙做的足够薄，薄到你几乎分不清一个功能到底该放核心里，还是该放扩展里。 接下来这部分，我觉得比逐条学功能更有用。PAgent明确说了，有六件事它不做：哎，不做MCP，官方说给工具写个README，让模型当Skill读就够了，要MCP自己写扩展；不做子代理，用tmux拉起多个PAgent实例，或者自己写扩展；哎，不做权限弹窗，要隔离就容器化，文档给了三套方案：容器、微虚拟机、纯Docker，OpenShell核心默认继承调用者的完整权限；不做计划模式，直接把计划写进文件；不做内置Tree of Thoughts，它们会把模型搞糊涂，用TODO.md文件替代；不做后台常驻，用tmux保活，可观察、可直接交互。 这六条放在一起看，你会发现它们共享同一个判断标准：这个功能能不能在核心之外，被不同的人用不同的方式实现，而不需要PAgent替所有人做决定。与其在核心里做一个通用但平庸的实现，不如完全不做，把决定权交给使用者。 正因为核心和扩展泾渭分明，PAgent同时服务三类用户，打开方式完全不同。哎，如果你只是日常用Agent干活，要会的东西很少：四个内建工具加几个斜杠命令，再加上怎么装第三方包。但有一件事一定要记住，核心默认不控权限，第三方包是full system access运行的，装之前最好让模型帮你审一下源码，这跟装个VS Code插件不是一个信任量级。 如果你想写扩展，面对的就是Extension API：register_tool、register_command、on加事件名，再配上examples/extensions目录里七十多个示例文件，从最简单的Hello到复杂的子代理沙箱，这是性价比最高的入口。哎，如果你想自己搭一个Agent框架，可以完全绕开Coding Agent，只依赖PI，拿到统一的多Provider流式接口，或者再加PAgent core，拿到工具循环和状态管理，自己套一层完全不同的壳。 选择灵活就要承担灵活的代价，这里有三点：第一，新人门槛被分散到生态里，核心经过审查，但你实际跑起来的权限控制、子代理编排，很可能来自不同作者的第三方包，packages run with full system access，这句话分量很重，等于把NPM的信任问题原样带进了Agent场景。第二，功能是分裂而非收敛的，子代理没有官方标准，社区会长出互不兼容的方案，对想要生态可迁移性的人来说，这是隐性成本。第三，贡献门槛被人为拉高，新贡献者的Issue和PR默认自动关闭，要等维护者回复Approve才解锁。哎，配套的准入规则是，你必须透彻理解你的代码，提交未理解的AI生成垃圾代码会被关闭。这套治理明显在筛选贡献者，控制核心膨胀，跟它的架构哲学是一体两面。 哎，如果听完这期，你想去读源码，给你推荐一个顺序：先读CONTRIBUTING.md和Agent，建立价值观坐标系，再读Agent loop，看懂事件循环，最后挑两个感兴趣的扩展，对照类型定义，摸清边界。 回到开头那个问题，Agent系统的边界该画在哪儿？