Cross-Harness 架构——一套配置跑 7 种 AI 编码工具

清水寺小和尚
11 阅读34分钟

Cross-Harness 架构——一套配置跑 7 种 AI 编码工具

前四篇讲的能力（token 管理、memory、learning、安全）都是在一个工具内的优化。但现实是：AI 编码工具百花齐放。你的团队里可能有人用 Claude Code、有人用 Cursor、有人用 Codex——每个工具的配置格式完全不同，最佳实践无法跨工具共享。

ECC 从一开始的 "Everything Claude Code" 进化成了 "ecc-universal"——一个跨 7 种 AI 编码工具的"Agent 操作系统"。它的核心设计问题是：怎么让同一套 agents/skills/rules/hooks 在不同 harness 上运行？

源仓库：affaan-m/everything-claude-code

碎片化问题

2026 年中，主流的 AI 编码工具（agent harness）至少有这些：

工具配置方式约束格式
Claude Code.claude/ + CLAUDE.md + settings.jsonSkills: Markdown, Hooks: JSON
OpenAI Codex.codex/config.toml + agents/*.tomlTOML + Markdown
Cursor.cursor/rules/ + hooks.jsonMarkdown + JS hooks
Gemini CLI.gemini/GEMINI.md单文件 Markdown
Zed编辑器内配置编辑器 API
OpenCodeTypeScript 插件TS/JS
Copilot CLI.github/copilot-instructions.mdMarkdown

同一个"写代码前先写测试"的规则，在每个工具里要写一遍、格式各不相同。更新了一处，其他 6 处没同步——配置漂移。

ECC 的分层架构设计

ECC 的解法是共享核心层 + 适配层：

┌─────────────────────────────────────────────────┐
│              Shared Core Layer                    │
│  agents/  skills/  rules/  hooks/hooks.json      │
│  AGENTS.md  SOUL.md  agent.yaml                  │
└─────────────────────────────────────────────────┘
        │           │           │           │
        ▼           ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│Claude Code│ │  Codex   │ │  Cursor  │ │ Gemini   │
│.claude-   │ │.codex/   │ │.cursor/  │ │.gemini/  │
│plugin/    │ │config.toml│ │hooks.json│ │GEMINI.md │
│plugin.json│ │agents/*.  │ │rules/   │ │          │
│           │ │toml      │ │hooks/*.js│ │          │
└──────────┘ └──────────┘ └──────────┘ └──────────┘

核心原则：真相只有一份，适配器负责翻译。

来源：整个仓库的目录结构

共享核心层

这些文件是"单一事实源"——所有适配器从这里读取内容：

agents/（64 个专用 Agent）

agents/
├── planner.md              # 功能实现规划
├── architect.md            # 系统设计
├── tdd-guide.md            # 测试驱动开发
├── code-reviewer.md        # 代码审查
├── security-reviewer.md    # 安全分析
├── build-error-resolver.md # 构建错误修复
├── e2e-runner.md           # E2E 测试
└── ... (64 个)

skills/（262 个能力单元）

每个 skill 是一个目录，包含 SKILL.md：

skills/
├── tdd-workflow/SKILL.md
├── security-review/SKILL.md
├── strategic-compact/SKILL.md
├── continuous-learning-v2/SKILL.md
└── ... (262 个)

rules/（20 种语言/框架的编码规则）

rules/
├── common/         # 通用规则
├── typescript/     # TypeScript 特有
├── golang/         # Go 特有
├── python/         # Python 特有
├── rust/           # Rust 特有
└── ... (20 种)

hooks/hooks.json（统一 Hook 定义）

所有 hook 的逻辑在 scripts/hooks/*.js 中实现——一套 Node.js 实现，然后各 harness 通过各自的机制调用它们。

SOUL.md / AGENTS.md / agent.yaml

SOUL.md     → 身份：核心原则和设计哲学
AGENTS.md   → 操作规范：agents/skills/hooks 的使用规则
agent.yaml  → gitagent 规范导出：跨工具的统一元数据描述

各工具的适配方式

Claude Code：原生插件

Claude Code 有原生的插件系统——.claude-plugin/plugin.json 是入口：

{
  "name": "ecc",
  "version": "2.0.0",
  "description": "Harness-native ECC plugin for engineering teams - 64 agents, 262 skills...",
  "skills": ["./skills/"],
  "commands": ["./commands/"]
}

安装后，Claude Code 自动加载所有 skills 和 commands。Hooks 通过 hooks/hooks.json 注册。这是最无缝的集成——因为 ECC 本身就是从 Claude Code 生态里长出来的。

来源：.claude-plugin/plugin.json

OpenAI Codex：TOML 配置 + Agent 角色

Codex 用 .codex/config.toml 做项目配置，用 .codex/agents/*.toml 定义多角色 Agent：

# .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "live"
persistent_instructions = "Follow project AGENTS.md guidelines."

Agent 角色定义示例（reviewer）：

# .codex/agents/reviewer.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Review like an owner.
Prioritize correctness, security, behavioral regressions, and missing tests.
Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
"""

此外，.agents/skills/*/agents/openai.yaml 提供了 Codex 专用的 skill 元数据：

# .agents/skills/tdd-workflow/agents/openai.yaml
interface:
  display_name: "TDD Workflow"
  short_description: "Test-driven development with coverage gates"
  brand_color: "#22C55E"
  default_prompt: "Use $tdd-workflow to drive the change with tests before implementation."
policy:
  allow_implicit_invocation: true

来源：.codex/ 和 .agents/skills/

Cursor：Rules 平铺 + JS Hooks

Cursor 的配置格式不同——它不支持嵌套的 skill 目录，而是把 rules 平铺为单个 Markdown 文件：

.cursor/rules/
├── common-agents.md
├── common-coding-style.md
├── common-development-workflow.md
├── common-git-workflow.md
├── common-hooks.md
├── common-patterns.md
├── common-security.md
├── common-testing.md
└── golang-coding-style.md

Hooks 通过 .cursor/hooks.json 注册，但事件名不同（sessionStart/sessionEnd/beforeShellExecution 而不是 SessionStart/Stop/PreToolUse）：

{
  "version": 1,
  "hooks": {
    "sessionStart": [{
      "command": "node .cursor/hooks/session-start.js",
      "description": "Load previous context and detect environment"
    }],
    "beforeShellExecution": [{
      "command": "node .cursor/hooks/before-shell-execution.js",
      "description": "Tmux reminder, git push review"
    }]
  }
}

适配逻辑：.cursor/hooks/*.js 是轻量包装器，内部调用共享的 scripts/hooks/ 实现。

来源：.cursor/

Gemini CLI：单文件注入

Gemini CLI 的配置极简——只有一个 .gemini/GEMINI.md 文件。所有规则、工作流、安全检查都压缩在这一个文件里：

# ECC for Gemini CLI

## Core Workflow
1. Plan before editing large features.
2. Prefer test-first changes for bug fixes and new functionality.
3. Review for security before shipping.
4. Keep changes self-contained, readable, and easy to revert.

## Coding Standards
- Prefer immutable updates over in-place mutation.
- Keep functions small and files focused.
- Validate user input at boundaries.
...

## ECC Areas To Reuse
- `AGENTS.md` for repo-wide operating rules
- `skills/` for deep workflow guidance
- `commands/` for slash-command patterns worth adapting
- `mcp-configs/` for shared connector baselines

Gemini 不支持 hooks 或 subagents——所以 ECC 对它的适配是"提供指令参考 + 指向共享资源"。

来源：.gemini/GEMINI.md

agent.yaml 与 gitagent 规范

agent.yaml 是 ECC 尝试建立的跨工具统一描述格式——一个 "gitagent surface"：

spec_version: "0.1.0"
name: ecc
version: 2.0.0
description: "Initial gitagent export surface for ECC's shared skill catalog..."
author: affaan-m
license: MIT
model:
  preferred: claude-opus-4-6
  fallback:
    - claude-sonnet-4-6
skills:
  - agent-architecture-audit
  - agent-eval
  - tdd-workflow
  - security-review
  - ...  # 262 个 skill 的列表

这个文件的意义不是"某个特定工具用它"——而是作为统一的元数据描述，让任何工具都能从中提取需要的信息。

ECC SOUL.md 对此的描述：

This gitagent surface is an initial portability layer for ECC's shared 
identity, governance, and skill catalog. Native agents, commands, and 
hooks remain authoritative in the repository until full manifest 
coverage is added.

翻译：这个 gitagent surface 是 ECC 共享身份、治理和 skill catalog 的初始可移植层。原生 agents、commands 和 hooks 在仓库中仍是权威的，直到完整的 manifest 覆盖被添加。

来源：agent.yaml 和 SOUL.md

npm 包分发：ecc-universal

ECC 通过 npm 包 ecc-universal 分发，暴露三个 CLI：

{
  "name": "ecc-universal",
  "description": "Harness-native agent operating system for Codex, OpenCode, Cursor, Gemini, Claude Code, and terminal",
  "bin": {
    "ecc": "scripts/ecc.js",
    "ecc-control-pane": "scripts/control-pane.js",
    "ecc-install": "scripts/install-apply.js"
  }
}
  • ecc：主 CLI，管理 skills/agents/hooks
  • ecc-control-pane：dashboard 控制面板入口
  • ecc-install：安装器，检测当前使用的 harness 并应用对应适配

来源：package.json

ECC 2.0：Rust 控制面板

ECC 2.0 的野心是"管理多个 Agent session 的统一界面"——不管你用什么工具，都可以从一个 TUI dashboard 里看到所有 session 的状态。

ecc2/
├── Cargo.toml
├── src/
└── README.md

已实现的功能：

  • Terminal UI dashboard
  • SQLite session store
  • Session start / stop / resume
  • Background daemon mode
  • Observability 和 risk-scoring 原语
  • Worktree-aware session scaffolding
  • 基本的多 session 状态和输出追踪

目标：

- manage many agent sessions from one surface
- keep session state, output, and risk visible
- add orchestration, worktree management, and review controls
- support Claude Code first without blocking future harness interoperability

翻译：

  • 从一个界面管理多个 agent session
  • 保持 session 状态、输出和风险可见
  • 添加编排、worktree 管理和 review 控制
  • 先支持 Claude Code，不阻断未来的跨 harness 互操作

来源：ecc2/README.md

便携性层级：什么最容易跨工具复用

不是所有 ECC 组件都一样"便携"。实际的便携性从高到低：

组件便携性原因
Skills（Markdown）极高任何支持 context 注入的工具都能读 Markdown
Rules（Markdown）极高同上——就是 Markdown 文件
CLAUDE.md / GEMINI.md高本质是 system prompt，格式标准化
agents/*.md（定义）中高Markdown 定义通用，但调用机制不同
agent.yaml中标准化元数据，但各工具解析方式不同
hooks/低强依赖 harness 的生命周期 API（事件名、stdin 格式不同）
Plugin 格式最低每个工具完全不同（JSON/TOML/TS）

实践建议：如果你想跨工具复用配置，优先投入 Skills 和 Rules——它们是 Markdown，任何地方都能用。Hooks 基本需要为每个工具写适配器。

实践：怎么让你的配置跨工具复用

最小方案：共享 Rules + Skills

  1. 创建一个共享的 rules/ 目录，按语言/关注点组织
  2. 创建 skills/ 目录，每个 skill 有 SKILL.md
  3. 对每个工具写一个适配入口：
    • Claude Code：CLAUDE.md 引用 rules 和 skills 路径
    • Cursor：把 rules 复制（或 symlink）到 .cursor/rules/
    • Gemini：把核心规则压缩进 .gemini/GEMINI.md
    • Codex：在 persistent_instructions 中引用 AGENTS.md

进阶方案：安装脚本

写一个脚本，根据检测到的工具自动生成适配文件：

#!/bin/bash
# detect-and-apply.sh

if [ -d ".claude" ] || command -v claude &>/dev/null; then
  echo "Detected Claude Code → applying .claude-plugin/"
  # symlink or copy skills/rules
fi

if [ -d ".cursor" ]; then
  echo "Detected Cursor → applying .cursor/rules/"
  # flatten rules to individual files
fi

if [ -f ".gemini/GEMINI.md" ] || command -v gemini &>/dev/null; then
  echo "Detected Gemini → updating .gemini/GEMINI.md"
  # regenerate GEMINI.md from rules/
fi

关键原则

  • Skills 是最便携的单元——投入时间写好 skill，它在任何工具里都能用
  • Hook 逻辑写一次，入口写多次——把逻辑放在 scripts/hooks/*.js，每个工具的适配层只是调用入口
  • agent.yaml 作为 manifest——即使工具不直接读它，它也是你的"配置目录"
  • 不要在适配层里写业务逻辑——适配层越薄越好，所有知识都放核心层

ECC 的启示：配置即代码

ECC 的跨 harness 架构带来了一个更深层的洞察：Agent 的配置（skills/rules/hooks）应该像代码一样管理。

  • 版本控制：放在 git 里，有变更历史
  • 模块化：按关注点分离，避免巨型单文件
  • DRY：不在多处重复同一条规则
  • 测试：用 Superpowers 的 TDD 方式验证 skill 是否有效
  • 分发：通过 npm/plugin marketplace 安装
  • CI/CD：配置变更也应该有 review 流程

这正是 ECC 从"一个 CLAUDE.md 配置文件"进化为"一个带 262 个 skill 的包管理系统"的原因——配置的复杂度增长到了需要工程化管理的程度。

总结：整个系列的核心理念

五篇文章走完，ECC 的设计哲学可以提炼为：

给 Agent 配装备，但要配得聪明、配得安全、配得可移植。

  1. Token 经济学：不是塞越多工具越好——按需加载，用完释放
  2. Memory Persistence：session 结束不等于遗忘——提取精华，有限注入
  3. Continuous Learning：纠正一次应该够——自动提取模式，内化为行为
  4. 安全攻防：便利不能跑在隔离前面——假设会被攻击，确保可以存活
  5. Cross-Harness：真相只有一份——核心层通用，适配层翻译

和 Superpowers 系列对比：Superpowers 解决的是"Agent 怎么做对事"（纪律），ECC 解决的是"Agent 怎么做更多事"（能力）。两者完全互补——你可以把 Superpowers 的 14 个 skill 装进 ECC 的 skill 层，同时获得纪律约束和能力扩展。

直接拿走：跨工具复用的最小方案

不需要 ECC 的完整 Cross-Harness 架构。记住一个优先级：

你可以现在就做的：

  1. 把通用的编码规范写成 Markdown rules，放在项目根目录的 下
  2. Claude Code 用户：软链接到
  3. Cursor 用户：软链接到
  4. Codex 用户：加到 的 字段
  5. Copilot 用户：加到

同一个文件，5 个工具都能读。不需要适配层——Markdown 本身就是适配层。

复杂的 hooks 和 tool-specific 的配置（settings.json vs config.toml）确实需要适配，但那些只占 10%。80% 的规则、skill、规范——Markdown 就够了。

这是 ECC 系列的最后一篇。5 篇文章覆盖了 Agent 工程化的三个层面：效率（Token 管理 + Memory 持久化）、智能（Continuous Learning）、安全与通用（Security + Cross-Harness）。三个层面的共同基础是同一个认知：Agent 不是一次性的聊天工具，而是需要持续维护的基础设施。

本文素材来源：affaan-m/everything-claude-code 的 .claude-plugin/、.codex/、.cursor/、.gemini/、agent.yaml、ecc2/、package.json

系列所有文章的源码参考：github.com/affaan-m/ev…

avatar
文章
阅读
粉丝