pi、ECC、superpowers 三个 Agent 项目的分层对照
本文基于三个仓库的以下版本梳理：pi commit 027a584、ECC commit 591ab5c、superpowers commit 44c9b2d（均为 2026-07 下旬）。三个项目都在持续迭代，具体行为以各自仓库最新代码与文档为准。
很多人把 pi、ECC、superpowers 拿来问”选哪个”，这个问题本身问错了——它们分处三层，理论上可以同时装在一台机器上，而且 superpowers 的 README 里就写着怎么装进 pi。 搞不清层次，就会出现”我已经用了 ECC，还要不要 superpowers”这类没法回答的问题；层次分清之后，你会发现该问的是”我缺的是运行时、是流程资产，还是流程本身”。
站内此前写过 Agent 框架横向对照 和 多 Agent 框架怎么选型，那两篇讲的是通用方法论——用什么维度去比、选型流程怎么走。这篇不重复那套框架，而是拿三个你现在就能 git clone 下来逐行核对的真实项目，看方法论落到具体仓库时会长成什么样。
一、三者不在同一层
先给结论，再讲依据。
pi 的 README 标题是 Pi Agent Harness，第一句说这是 pi agent harness 项目的所在地，“including our self extensible coding agent”。它自己就是那个会调模型、会调工具、会渲染终端界面的东西。仓库 packages/ 下实际躺着 agent、ai、coding-agent、evals、server、storage、tui 七个包，README 的包列表明确写了其中四个的职责：@earendil-works/pi-coding-agent 是交互式编码 Agent CLI，@earendil-works/pi-agent-core 是带工具调用和状态管理的 agent runtime，@earendil-works/pi-ai 是统一的多 provider LLM API，@earendil-works/pi-tui 是带差分渲染的终端 UI 库。没有别的 Agent 它也能跑。
ECC 的 README 在介绍自己的第一句就把关系说得很直白：你的 agent 已经会写代码，ECC 给它的是一套协同的工程系统和工具箱。它不提供模型调用循环，它假设你已经有一个能跑的 harness。README 里那行流程图 plan -> test -> implement -> review -> verify -> remember -> improve 描述的是装上去之后 agent 的工作方式，不是 ECC 自己的执行流程。
superpowers 的 README 开头写的是”a complete software development methodology for your coding agents”，构建在一组可组合的技能和一小段保证 agent 真去用它们的初始指令之上。它连工具都不带——skills/ 下 14 个目录，每个目录以 SKILL.md 为核心，辅助文件多寡不一（using-git-worktrees 这类只有 SKILL.md 一个文件，systematic-debugging 则带了十来个条目）；hooks/hooks.json 里只有一条 SessionStart hook，matcher 是 startup|clear|compact，做的事情是执行 hooks/run-hook.cmd session-start。真正干活的工具（读文件、跑测试、开 subagent）全部来自宿主 harness。
| 对照维度 | pi | ECC | superpowers | 依据文件 |
|---|---|---|---|---|
| 自身定位 | Agent 本体与运行时 | 装进已有 harness 的工程系统与工具箱 | 只给流程与技能的方法论 | 三个仓库各自的 README.md |
| 能否独立运行 | 能，本身就是 CLI | 不能，需要宿主 harness | 不能，需要宿主 harness | 同上 |
| 主要交付物 | npm 包与可执行文件 | agents / skills / commands / rules / hooks 资产 | 14 个 SKILL.md 与一条 SessionStart hook | pi/packages/、ECC/skills/、superpowers/skills/ |
| 扩展方式 | TypeScript 扩展注册工具与命令 | 安装脚本按 profile 与 target 铺文件 | 技能靠描述自动触发 | pi/packages/coding-agent/docs/extensions.md、ECC/install.sh、superpowers/skills/using-superpowers/SKILL.md |
| 资产规模 | 7 个 workspace 包 | 281 个 skills、67 个 agents、94 个 commands | 14 个 skills | 三个仓库对应目录直接数得出 |
| 权限与隔离 | 不内置权限系统，靠容器化或沙箱 | 通过 hook 与 AgentShield 扫描配置面 | 交给宿主 harness | pi/packages/coding-agent/docs/containerization.md、ECC/README.md、superpowers/README.md |
表里的数量都是在仓库里数出来的：ECC 的 skills/、agents/、commands/ 三个目录条目数分别是 281、67、94，和它 README 表格里写的数字对得上；superpowers 的 skills/ 下是 brainstorming、dispatching-parallel-agents、executing-plans、finishing-a-development-branch、receiving-code-review、requesting-code-review、subagent-driven-development、systematic-debugging、test-driven-development、using-git-worktrees、using-superpowers、verification-before-completion、writing-plans、writing-skills 这 14 个。
二、pi 这一层：扩展点本身就是产品
本体层要解决的问题是：模型调用、工具执行、会话状态、终端渲染这几件事得有人做，而且做得足够稳，别人才敢往上叠东西。
pi 的做法是把这几件事拆成独立的 npm 包，再把扩展点做成一等公民。packages/coding-agent/docs/extensions.md 里写得很清楚：扩展是 TypeScript 模块，可以订阅生命周期事件、通过 pi.registerTool() 注册 LLM 可调用的自定义工具、通过 pi.registerCommand() 注册 /mycommand 这样的命令、通过 pi.appendEntry() 存储跨重启的会话状态、通过 ctx.ui.custom() 做完整的 TUI 组件。文档里列的用例包括权限门（在 rm -rf、sudo 之前确认）、git checkpoint（每轮 stash、切分支时恢复）、路径保护（阻止写入 .env、node_modules/）、自定义压缩。放在 ~/.pi/agent/extensions/ 或项目的 .pi/extensions/ 里的扩展可以用 /reload 热重载。
技能这块 pi 走的是标准兼容路线。packages/coding-agent/docs/skills.md 说 pi 实现了 Agent Skills standard，对大多数违规只告警而不拒绝，并且明确放宽了一条：允许技能名和父目录名不一致，理由是”那条规则对跨多个 agent harness 共用的技能目录来说不合适”。它的技能加载位置包括全局的 ~/.pi/agent/skills/ 和 ~/.agents/skills/，以及项目受信任后才生效的 .pi/skills/ 和 .agents/skills/。文档还专门给了一段，教你怎么在 settings 的 skills 数组里直接填 ~/.claude/skills 和 ~/.codex/skills，把别的 harness 的技能拿过来用。
包管理是 packages.md 里那套：pi install npm:@foo/bar@1.0.0、pi install git:github.com/user/repo@v1，也支持本地绝对路径和相对路径；pi -e 装到临时目录只跑当前这一次。默认写用户设置 ~/.pi/agent/settings.json，加 -l 写项目设置 .pi/settings.json，项目设置可以和团队共享，项目受信任后 pi 启动时会自动补装缺失的包。
这对你意味着什么：如果你的诉求是”我要在 Agent 循环里插一段自己的逻辑”，本体层是唯一能满足的一层。上面两层再怎么写流程，也改不了工具调用被拦截时的行为。
三、ECC 这一层：把工程资产铺进宿主
套件层要解决的问题是：一个能跑的 Agent 不等于一个能交付的工程流程。计划散在聊天记录里、TDD 靠嘴说、写代码和评审用同一份上下文——这些都是运行时之上的事。
ECC 的答案是把这些事变成可安装的文件。它自己的概念分工表把四类资产讲得挺清楚：skills 是按需加载的可复用工作流，agents 是有自己上下文和工具权限的受限工人，rules 是永远加载的持久标准，hooks 是由 harness 事件触发、在模型上下文之外运行的脚本，instincts 是从真实会话里学到、带置信度分数的模式。区分点在于对上下文的占用方式——rules 永远占，skills 用到才占，hooks 完全不占。这也是它反复提醒”rules 要选择性安装”的原因：README 里给的建议是先装 rules/common，再加一个你实际在用的语言包。
安装路径是这一层最啰嗦也最容易出事的地方。Claude Code 走插件：/plugin marketplace add https://github.com/affaan-m/ECC 再 /plugin install ecc@ecc。但 README 专门指出，Claude Code 插件没法分发 rules，所以规则得自己 clone 仓库然后 cp -R rules/common ~/.claude/rules/ecc/。Codex 走另一条路，bash scripts/sync-ecc-to-codex.sh，合并 AGENTS.md、skills、prompts、agents 和参考配置进 ~/.codex，会创建带时间戳的备份。其他 harness 走 ./install.sh --target <目标> 这条线，README 表格里逐个列了 Cursor、OpenCode、Gemini CLI、Zed、Antigravity、Qwen CLI、Hermes、OpenClaw、Kimi Code、CodeBuddy、JoyCode 各自的命令——注意 profile 并不统一，多数是 --profile minimal，OpenCode 那行则要先 npm run build:opencode 构建插件负载再走 --profile full。抄命令的时候别只抄前半截。
跨 harness 的上下文搬运是它最近在推的部分。Memory Vault 用一种叫 ecc.memory.v1 的 Markdown 格式，项目和团队记忆放 .ecc/memory/，用户记忆放 ~/.ecc/memory/，命令是 ecc memory init --scope project、ecc memory search、ecc memory doctor、ecc memory handoff。它对信任边界的表述值得单独抄一遍：记忆是未经审阅的上下文，不是可执行的策略；agent 必须对照权威来源核实重要断言，绝不能把召回的内容当作可执行指令。记忆正文只接受 --stdin 或 --body-file 传入，不接受命令行值。关于分层记忆本身的设计取舍，站内 Agent 记忆怎么分层 讲过一套通用判断。
这对你意味着什么：套件层给的是现成资产，不是能力。它假设你的 harness 已经支持 skills、agents、hooks 这些概念，装进去之后你多的是”别人写好的 281 个工作流”，少的是”我自己拆分工作流的时间”。
四、superpowers 这一层：只讲流程，工具全靠宿主
方法论层要解决的问题更窄：agent 知道该干什么，但不按顺序干；你告诉它先写测试，它转头就先写实现。
superpowers 的做法是把顺序写死成技能之间的触发链。README 里那七步就是主线：brainstorming 在写代码之前激活，用提问把粗想法磨细，分段展示设计让你逐段确认，然后存下设计文档；using-git-worktrees 在设计通过后建隔离工作区并验证测试基线干净；writing-plans 把工作拆成 2 到 5 分钟一个的小任务，每个任务带确切文件路径、完整代码和验证步骤；接着是 subagent-driven-development 或 executing-plans；test-driven-development 在实现期间强制 RED-GREEN-REFACTOR，README 里那句”Deletes code written before tests”说得毫不含糊；requesting-code-review 在任务之间按严重程度报问题，critical 级别阻塞后续；finishing-a-development-branch 在任务完成后验证测试、给出合并/PR/保留/丢弃的选项并清理 worktree。
强制力靠的是技能文本本身。skills/using-superpowers/SKILL.md 里有一段用 <EXTREMELY-IMPORTANT> 标签包起来的话：只要你觉得某个技能有 1% 的可能适用，就绝对必须调用它；如果技能适用于你的任务，你没有选择权。同一份文件还写了”在任何回应或行动之前调用技能——包括澄清提问、探索代码库、检查文件”。README 那句”Mandatory workflows, not suggestions”不是宣传语，是文件里真这么写的。
skills/subagent-driven-development/SKILL.md 里的执行模型也值得看：每个任务派一个全新的 implementer subagent，每个任务之后跟一次任务级评审（先查规格符合度，再查代码质量），最后再做一次覆盖整个分支的宽评审。它对 subagent 的理由讲得很实在——subagent 不该继承你这个会话的上下文和历史，你要精确构造它需要的那部分，这同时也保住了你自己的上下文用于协调。文件里还有一条硬规定：任务之间不要停下来向人确认，“Should I continue?”这类提示是在浪费对方时间。关于工作区隔离本身怎么做，站内 Agent 工作区隔离 有更一般的讨论。
它对宿主的依赖在 Pi 那一节暴露得最清楚。README 说用 pi install git:github.com/obra/superpowers 安装，Pi 包会加载 Superpowers 技能和一个小扩展，在会话启动时以及压缩之后注入 using-superpowers 引导；因为”Pi 有原生技能，所以不需要兼容用的 Skill 工具”；而 subagent 和任务列表工具”仍然是可选的 Pi 配套包”。也就是说，那七步流程里的第四步能不能跑，取决于宿主给不给你 subagent 能力。
五、边界与代价
三个项目各自放弃了一些东西，而且都写在明面上。
pi 明确不做权限系统。 README 的 Permissions & Containerization 一节直说：pi 不包含用于限制文件系统、进程、网络或凭据访问的内置权限系统，默认以启动它的用户和进程的权限运行。需要更强边界，就去容器化或沙箱化，packages/coding-agent/docs/containerization.md 给了三种模式：Gondolin 扩展把 pi 和 provider 认证留在宿主机、把内置工具和 ! 命令路由进本地 Linux 微虚拟机；纯 Docker 把整个 pi 进程塞进本地容器；OpenShell 把整个进程放进策略受控的沙箱。这是一个清晰的取舍——不在产品里做半吊子权限，把隔离交给专门做隔离的层。代价是你不能默认它安全，得自己搭一层。站内 最小权限设计 讲的原则在这里全都得你自己落实。
pi 的另一处取舍在依赖管理上：直接外部依赖被固定到确切版本，.npmrc 设了 save-exact=true 和 min-release-age=2 以避开 npm 解析时当天发布的依赖，package-lock.json 是依赖的唯一真相，发布的 CLI 包里带一份 packages/coding-agent/npm-shrinkwrap.json。好处是供应链风险小，副作用是依赖升级不会自己发生，得有人推。
ECC 的代价是安装面和上下文占用。 README 用了一整节讲”每个 harness 只选一条安装路径”，并且列了哪些组合会出事：Claude Code 插件加 Codex sync 可以，Claude Code 插件加完整手动安装不行，Codex sync 加 Codex marketplace 插件不行。把 ECC 往同一个 harness 装两遍，会重复技能、命令、hook 或配置。它甚至给了收拾残局的顺序：先删插件安装，再从仓库根跑 uninstall 清掉 install-state 管理的文件，再删你手抄的规则目录，最后按单一路径重装一次。
还有几处明确”不管”：multi-* 那组命令不在基础安装范围内，要用 /multi-plan、/multi-execute 这些就得另外装 ccg-workflow 运行时（npx ccg-workflow），否则跑不对；Claude 插件安装故意不自动启用 ECC 自带的 MCP server 定义；ECC 只默认带一个连接器 chrome-devtools，其余都是包 CLI/REST 的技能或需要主动选择的目录条目，规则写在 docs/MCP-CONNECTOR-POLICY.md；Codex 那边”还没有 Claude 式的 hook 执行对等能力”，enforcement 只能靠 AGENTS.md 和沙箱审批设置。资产多也意味着上下文成本，这也是它给出 ECC_SESSION_START_MAX_CHARS、ECC_MAX_INJECTED_INSTINCTS、ECC_INSTINCT_CONFIDENCE_THRESHOLD 这些环境变量的原因。
superpowers 的代价是速度和话密。 这一条它自己 README 没细写，但从流程本身能推出来，而且是你实际会撞上的：brainstorming 要来回问、writing-plans 要拆到 2 到 5 分钟粒度、每个任务后要评审、最后还有一次全分支评审——改一个文案、调一个常量、修一处拼写，这套流程从头走一遍纯属过度设计。它对小改动不适用，你需要有意识地判断什么时候不启动它。同样，被逐段确认设计、被要求先看失败的测试再看实现，会让整个交互比”直接改”啰嗦得多；换来的是过程留痕，代价是你的耐心。
它还有两处边界写在明面上：贡献指南说通常不接受新技能的贡献，且对技能的任何修改必须在所有支持的 coding agent 上都能工作——这意味着你想加自己的流程，多半得 fork 或者另起一套。以及可视化伴侣功能默认会从项目网站加载一个带版本号的 logo 作为使用量估计，README 说它不包含项目、提示词或 coding agent 的任何细节，关掉的方式是把 SUPERPOWERS_DISABLE_TELEMETRY 设成任意真值，它也遵守 DISABLE_TELEMETRY 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。
六、上手与避坑清单
别按”选一个”来决策，按”缺哪一层”来决策。 会踩是因为三者的宣传语听起来都像”让你的 Agent 更强”。避法很简单：你缺的是能拦截工具调用、能注册自定义工具的运行时，那是 pi 那一层的事；你缺的是现成的评审 agent、语言规则、记忆搬运，那是 ECC 那一层；你缺的是”别让它上来就写代码”的顺序约束，那是 superpowers 那一层。三者可以叠，superpowers 的 README 里就有装进 Pi 的完整命令。
ECC 千万别用两种方式装进同一个 harness。 会踩是因为插件装完之后，很多人看到 rules 装不进去，顺手又跑了一遍 ./install.sh --profile full，结果技能和 hook 各有两份，hook 重复执行。避法是照 README 的话做：装了插件就只手动补 rules 目录，不要再跑完整安装脚本；已经叠了就先 node scripts/ecc.js list-installed 看清管理了哪些文件，再 doctor、repair，实在不行按它给的四步顺序清干净重装一次。
ECC 的 rules 别一次全装。 会踩是因为 rules/ 下语言包很多，看着都有用就全 cp 了。但 rules 是永远加载的上下文，装多少就占多少。避法是按它自己的建议只装 common 加一个你在用的语言包，而且手动复制时要整个语言目录一起复制（比如 rules/common 或 rules/golang），不是复制目录里的文件——否则相对引用会断、文件名还可能撞。
ECC 的 Claude 手动安装别把技能塞进嵌套目录。 会踩是因为看到别的资产都归到 ecc/ 子目录下就想统一。但 Claude Code 只从 ~/.claude/skills/ 的直接子目录发现技能，塞进 ~/.claude/skills/ecc/ 就等于没装。避法是手动安装时技能一律平铺到 ~/.claude/skills/<skill-name>/。
superpowers 装进 Pi 之前先确认 subagent 能力在不在。 会踩是因为七步流程的第四步 subagent-driven-development 需要真的能派 subagent，而 README 说 subagent 和任务列表工具是”可选的 Pi 配套包”。没装的话你会看到流程走到一半降级成手工执行，还以为是模型不听话。避法是先把配套包配好，或者一开始就用 executing-plans 那条批次加人工检查点的路线。
pi 别拿默认配置跑不受信任的代码。 会踩是因为它默认就是你当前用户的权限，而扩展和技能都能执行任意代码——packages.md 和 skills.md 里各有一段安全提示，说 pi 包以完整系统访问权限运行、技能可以指示模型执行任何动作，安装第三方包前要看源码。避法是把隔离当作前置条件而不是可选项，按 containerization.md 里三种模式挑一种，先搭好再开工。
pi 加载别的 harness 的技能之前先读一遍。 会踩是因为把 ~/.claude/skills 填进 settings 太方便了，一行配置就全拿过来。但那些技能里可能有你没审过的可执行脚本。避法是当成引入新依赖来对待，逐个过一遍再加进 skills 数组，而不是整个目录一挂了事。
收尾
真要动手之前，先自问三个问题：我要改的是 Agent 循环内部的行为，还是循环之上的流程？我团队里已经有能跑的 harness 吗？我现在缺的是流程本身，还是别人写好的流程资产？
三个问题的答案分别对应本体层、套件层、方法论层。答案落在哪一层，就先去读那一层的哪个文件——想清楚扩展点够不够用，读 pi/packages/coding-agent/docs/extensions.md；想清楚装进去会占多少上下文，读 ECC README 里那张概念分工表和 rules/README.md；想清楚流程会不会太重，读 superpowers/skills/writing-plans/SKILL.md 里对任务粒度的要求，拿你手头最近一次改动去对一遍，看这套流程是帮你省了返工，还是给一个五分钟的改动套了两小时的仪式。
文中三个项目各有中文专题：pi 开源编程 Agent、ECC 增强套件、superpowers 方法论。