ECC 手动适配指南：把 Skills、命令与 Hook 纪律移植到非原生 Agent 框架

本文面向需要将 ECC（The agent harness performance optimization system）工作流引入 Grok 等非原生支持 harness 的开发者。ECC 的完整能力依赖 .claude/、.codex/、.opencode/、.cursor/ 等原生安装面，而当目标 harness 只接受系统提示词、上传文件或粘贴指令时，你需要通过 docs/MANUAL-ADAPTATION-GUIDE.md 描述的手动适配路径，以最小上下文包的形式重建 ECC 的核心行为——包括聚焦上下文、技能激活线索、命令意图和 Hook 纪律。读完后你将掌握一套可复制的技能打包、压缩、命令注册与 Hook 意图转写的完整流程。

适用场景：什么时候必须走手动适配

手动适配是面向非原生 harness 的回退路径（fallback path）。当目标 harness 满足以下任一条件时，才应使用本流程：

• 不会自动加载仓库目录（不识别 .claude/、.codex/ 等布局）；
• 不支持自定义斜杠命令（slash commands）；
• 不支持 hooks 自动化；
• 不支持仓库本地技能（skill）激活；
• 文件系统或工具访问能力部分缺失或完全缺失。

只要存在一等公民（first-class）支持，就优先走原生通道。ECC 当前的原生目标包括：Claude Code、Codex、Cursor、OpenCode、CodeBuddy、Antigravity。从 README 的平台支持矩阵看，ECC "works best with Claude Code today"，并针对 Codex 提供受支持的同步路径，针对 Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen 等提供能力受限的适配器——手动适配只应在确实没有原生布局可用时启用。

手动适配要复现的四件事

手动适配的目标不是镜像仓库里的每个文件，而是用尽可能小的上下文包重建四类有用行为：

1. 聚焦上下文：只装载任务真正需要的内容，而不是把整个仓库倒进上下文窗口；
2. 技能激活线索：显式告诉模型何时触发哪个工作流，而不是指望它自己猜；
3. 命令意图：在 harness 没有斜杠命令系统时，仍能表达 /plan、/tdd 这类调用意图；
4. Hook 纪律：在没有原生自动化时，把"写码前检查、收尾前验证"的操作性纪律固化成常驻指令。

最小技能包：从仓库本身做默认选择

默认策略是直接从仓库中手动挑选文件，只装载实际需要的内容：

• 一个语言或框架技能；
• 一个工作流技能；
• 若任务足够垂直，再加一个领域技能；
• 仅当 harness 从显式编排中受益时，才加一个 agent 或 command。

指南给出了三组经过验证的最小组合，这些文件在仓库中均真实存在：

任务类型	技能组合
Python 功能开发	python-patterns + tdd-workflow + verification-loop
TypeScript API 开发	backend-patterns + security-review + tdd-workflow
内容/外发工作	brand-voice + content-engine + crosspost

这些技能各自承担明确分工。从 SKILL.md 的 frontmatter 描述可以看到：python-patterns 覆盖 Pythonic 惯用法、PEP 8 与类型标注；tdd-workflow 强制测试先行并要求 80% 以上覆盖率（含单元、集成与 E2E）；verification-loop 提供"在完成声明前验证会话工作"的完整验证系统；backend-patterns 面向 Node.js/Express/Next.js API 路由的后端架构模式；security-review 则针对认证、用户输入、密钥、API 端点等安全敏感场景提供检查清单。也就是说，最小组合遵循"框架知识 + 开发纪律 + 收尾验证"的结构。

装载方式取决于 harness 能力：

• 支持文件上传：只上传选中的那几个文件；
• 只支持粘贴上下文：提取相关章节，粘贴压缩后的 bundle，而不是原始完整文件。

手动上下文打包：仓库即工具，无需额外依赖

打包不需要任何额外工具，直接用仓库本身即可。指南给出的标准流程是用 sed 截取每个技能的前 220 行（足够覆盖"何时激活 + 工作流步骤 + 关键示例"的核心段落），用 --- 分隔线拼接成一个文件：

cd /path/to/everything-claude-code

sed -n '1,220p' skills/tdd-workflow/SKILL.md > /tmp/ecc-context.md
printf '\n\n---\n\n' >> /tmp/ecc-context.md
sed -n '1,220p' skills/backend-patterns/SKILL.md >> /tmp/ecc-context.md
printf '\n\n---\n\n' >> /tmp/ecc-context.md
sed -n '1,220p' skills/security-review/SKILL.md >> /tmp/ecc-context.md

在打包之前，可以用 rg（ripgrep）先定位候选技能——这个正则正是利用 SKILL.md 中普遍存在的"激活条件"行文习惯：

rg -n "When to use|Use when|Trigger" skills -g 'SKILL.md'

在 ECC 仓库中实际执行该命令可以命中 300 余行匹配，覆盖全部 286 个 SKILL.md 中的描述性激活条件（如 motion-advanced 的 "Use when building drag and drop, gestures..."、golang-testing 的 "Use when writing Go tests" 等）。这验证了打包前提：ECC 的每个技能都自带可读的激活线索，因此"按激活条件筛选技能"本身就是可操作的选择策略。

可选地，如果你已经在使用 repomix 这类仓库打包器，它可以帮助把选定文件压缩成一份交接文档。但指南明确指出：这是便利工具，不是 ECC 的正统路径。

压缩规则：保留什么，删什么

手动打包时必须遵守的取舍顺序：

保留：

• 任务框架（task framing）；
• 激活条件（activation conditions）;
• 工作流步骤（workflow steps）；
• 关键示例（critical examples）。

删除（按顺序）：

1. 先删重复性散文；
2. 再删与当前任务无关的变体；
3. 避免粘贴整个目录——一两个技能通常就够。

需要更紧凑的提示格式时，可以把核心部分转写成结构化紧凑块。指南的示例是把 tdd-workflow 压缩为 XML 块：

<skill name="tdd-workflow">
  <when>New feature, bug fix, or refactor that should be test-first.</when>
  <steps>
    <step>Write a failing test.</step>
    <step>Make it pass with the smallest change.</step>
    <step>Refactor and rerun validation.</step>
  </steps>
</skill>

对照 skills/tdd-workflow/SKILL.md 的完整版本可以看到，压缩块保留了"RED → GREEN → REFACTOR"主循环，而省略了 Git 检查点规范、测试运行器检测（node scripts/setup-package-manager.js --detect）、runner 命令矩阵等仅在具备完整文件系统访问的 harness 中才可执行的细节——这正是"保留工作流骨架、按 harness 能力裁剪执行细节"的压缩思路。

复现命令：给 harness 提供显式调用句柄

当 harness 没有斜杠命令系统时，在系统提示词或会话前言（preamble）中定义一个小型命令注册表：

Command registry:
- /plan -> use planner-style reasoning, produce a short execution plan, then act
- /tdd -> follow the tdd-workflow skill
- /review -> switch into code-review mode and enumerate findings first
- /verify -> run a verification loop before claiming completion

这里不是实现真正的命令管道，而是给 harness 提供显式的调用句柄（invocation handles），把它们映射到 ECC 行为上。这些句柄有真实的仓库原型可对照：

• /plan 对应 commands/plan.md——重述需求、识别风险、分阶段规划，且在动手写代码前必须等待用户确认；其"planner-style reasoning"背后是 agents/planner.md 中定义的规划专家角色（需求分析 → 架构评审 → 依赖与风险识别）；
• /tdd 对应 skills/tdd-workflow；
• /verify 对应 skills/verification-loop。

复现 Hooks：把自动化意图转写成常驻指令

ECC 的原生 Hook 机制是事件驱动的自动化工具。从 hooks/README.md 可以看到其工作流：用户请求 → Claude 选择工具 → PreToolUse hook 运行 → 工具执行 → PostToolUse hook 运行，其中 PreToolUse hook 可以阻塞（exit code 2）或仅警告；hooks/hooks.json 中则配置了 Bash 预检分发器、文档文件警告、配置保护（阻止修改 linter 配置）、MCP 健康检查、GateGuard 事实核查等 PreToolUse/PreCompact/SessionStart 钩子。

当 harness 没有原生 hooks 时，正确做法是把 hook 的意图搬进常驻指令（standing instructions），例如：

Before writing code:
1. Check whether a relevant skill should be activated.
2. Check for security-sensitive changes.
3. Prefer tests before implementation when feasible.

Before finalizing:
1. Re-read the user request.
2. Verify the main changed paths.
3. State what was actually validated and what was not.

指南对此有清醒的定位：这不重建真正的自动化，但它捕获了 ECC 的操作纪律。"写码前"三条分别对应技能激活检查、安全敏感变更检查（呼应 security-review 技能）、测试先行偏好（呼应 tdd-workflow）；"收尾前"三条对应重读原始请求、验证主要变更路径、明确声明"验证了什么、没验证什么"（呼应 verification-loop 的核心主张）。

Harness 能力矩阵：原生 vs 手动

能力	原生 ECC 目标	手动适配目标
目录式安装	原生	无
斜杠命令	原生	提示词内模拟
Hooks	原生	提示词内模拟
技能激活	原生	手动
仓库本地工具	原生	取决于 harness
上下文打包	可选	必需

这张矩阵给出了清晰的决策规则：上下文打包在原生目标里是可选优化，而在手动适配中是硬性前提；命令和 hooks 则从"系统能力"降级为"提示词约定"。

实战：Grok 风格的接入五步法

1. 选出最小的有用技能包（参考前文三组最小组合）；
2. 把选中的 ECC 技能文件打包进一次上传或一个粘贴块（用前文的 sed 拼接流程）；
3. 加上简短的命令注册表；
4. 加上常驻的"hook 意图"指令；
5. 先从一个任务开始，验证 harness 确实遵循了工作流，再逐步扩大范围。

指南给出的起步 preamble 完整示例：

You are operating with a manually adapted ECC bundle.

Active skills:
- backend-patterns
- tdd-workflow
- security-review

Command registry:
- /plan
- /tdd
- /verify

Before writing code, follow the active skill instructions.
Before finalizing, verify what changed and report any remaining gaps.

注意最后两条指令是 preamble 的"钩子"：写码前遵循激活技能指令，收尾前核对变更并报告剩余缺口——这正是把 hooks/hooks.json 中 PreToolUse/收尾类自动化压缩成语义等价约定的最小实现。

限制：手动适配始终是一等支持之后的二等路径

指南最后明确列出了手动适配失去的能力：

• 自动安装与同步；
• 原生 hook 执行；
• 真正的命令管道；
• 运行时的可靠技能发现；
• 内置的多 agent / worktree 编排。

因此规则很简单：

• 需要把 ECC 行为带进非原生 harness 时，用手动适配；
• 需要完整系统能力时，用原生 ECC 目标（Claude Code、Codex、Cursor、OpenCode 等，各 harness 的具体安装方式见 README.md 的平台支持章节与 docs/ANTIGRAVITY-GUIDE.md 等专项指南）。

小结

ECC 手动适配的本质是一次语义迁移：把"文件系统布局 + 命令管道 + 事件钩子"这套机器可执行的基础设施，翻译成"最小技能 bundle + 命令注册表 + 常驻纪律指令"这套提示词可表达的约定。它的成功取决于三件事：技能选择足够小（一个框架技能 + 一个工作流技能 + 可选领域技能）、压缩时保留激活条件与工作流骨架、收尾时显式声明验证边界。对于只能接收系统提示词的聊天式 harness，这是当前在不做任何仓库改动的前提下引入 ECC 行为的最短路径。