第 28 课：跨平台适配与插件机制

王小酱
22 阅读6分钟

所属阶段：第六阶段「综合与创造」（第 28-30 课） 前置条件：第 11 课（Scripts 底层）、第 14-16 课（验证循环、上下文管理、多代理编排） 本课收获：理解 Plugin Manifest 格式，能选择安装 Profile

一、本课概述

从第 1 课起，我们就知道 ECC 支持 6 种 AI 编程助手。但之前的课程都聚焦于 Claude Code。本课深入跨平台的工程实现：

  1. Harness 支持表 — 每个平台支持什么、不支持什么
  2. Plugin Manifest 格式 — .claude-plugin/ 和 .codex-plugin/ 的结构
  3. 安装 Profile — 从 core 到 full 的五级选择
  4. JSON Schema 验证 — 如何用 Schema 确保配置正确
  5. 安装方式对比 — 不同安装方法的适用场景

理解跨平台机制后，你就具备了为任何 AI 编程助手配置 ECC 的能力。

二、Harness 支持表

2.1 六大平台支持对比

平台支持程度插件目录特殊说明
Claude Code完整支持.claude-plugin/主要目标平台，所有功能均可用
Codex完整支持.codex-plugin/macOS 应用和 CLI，Skill 共享
Cursor适配支持Hook adapter通过适配层桥接
OpenCode插件支持Plugin system原生插件系统对接
Gemini有限支持GEMINI.md仅通过配置文件提供指导
AntigravityIDE 集成—IDE 内集成

2.2 功能覆盖矩阵

功能Claude CodeCodexCursorOpenCodeGemini
Agents全部全部部分部分无
Skills全部全部部分全部无
Commands全部部分无部分无
Hooks全部部分适配部分无
Rules全部共享共享共享有限
MCP全部全部部分部分无

2.3 设计意义

ECC 的跨平台设计有一个核心洞察：知识是可迁移的，工具绑定是不可避免的。

  • Skill（知识）在所有平台都有价值 → 最大限度地共享
  • Hook（事件机制）依赖平台特性 → 需要适配层
  • Command（交互入口）是平台特定的 → 各自实现

三、Plugin Manifest 格式

3.1 Claude Code Plugin（.claude-plugin/plugin.json）

{
  "name": "ecc",
  "version": "1.10.0",
  "description": "Battle-tested Claude Code plugin...",
  "author": {
    "name": "Affaan Mustafa",
    "url": "https://x.com/affaanmustafa"
  },
  "homepage": "https://ecc.tools",
  "repository": "https://github.com/affaan-m/everything-claude-code",
  "license": "MIT",
  "keywords": ["claude-code", "agents", "skills", "hooks", ...],
  "agents": [
    "./agents/architect.md",
    "./agents/build-error-resolver.md",
    "./agents/code-reviewer.md"
  ],
  "skills": [
    "./skills/tdd-workflow/SKILL.md",
    "./skills/security-review/SKILL.md"
  ],
  "commands": [...],
  "hooks": "./hooks/",
  "rules": "./rules/"
}

3.2 Codex Plugin（.codex-plugin/plugin.json）

{
  "name": "ecc",
  "version": "1.10.0",
  "description": "Battle-tested Codex workflows...",
  "author": {
    "name": "Affaan Mustafa",
    "url": "https://x.com/affaanmustafa"
  },
  "license": "MIT",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Everything Claude Code",
    "shortDescription": "156 battle-tested ECC skills...",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "defaultPrompt": [
      "Use the tdd-workflow skill...",
      "Use the security-review skill...",
      "Use the verification-loop skill..."
    ]
  }
}

3.3 两种 Manifest 的差异

字段.claude-plugin.codex-plugin说明
agents逐个列出无Codex 不直接支持 Agent 列表
skills逐个列出目录引用Codex 用目录统一加载
commands有无Codex 没有 Command 概念
hooks有无Codex Hook 机制不同
mcpServers隐含显式引用Codex 需要明确声明
interface无有Codex 需要 UI 展示信息
defaultPrompt无有Codex 支持默认提示语

设计原则：每个 Manifest 针对目标平台优化，而不是强求统一格式。

四、安装 Profile

4.1 五级 Profile

ECC 不是"要么全装、要么不装"。它提供了五个安装级别：

core → developer → security → research → full
 │         │          │          │          │
 │         │          │          │          └─ 所有组件
 │         │          │          └─ + AI/Agent 实验 Skill
 │         │          └─ + 安全扫描、审计
 │         └─ + TDD、代码审查、构建修复
 └─ 基础 Rules + 核心 Skill

4.2 Profile 详情

Profile包含内容适用场景组件数量（约）
coreRules + 核心 Skill轻量使用、低配机器~30
developercore + TDD/Review Agent + 开发 Skill日常开发~100
securitydeveloper + 安全 Agent/Skill安全敏感项目~120
researchsecurity + AI 实验 SkillAI 研究和实验~200
full所有组件完整体验、高配机器~400+

4.3 Profile 选择建议

问：你的机器配置如何？
  ├── 低配（<8GB RAM） → core 或 developer
  └── 正常/高配 → 继续

问：你是否需要安全扫描？
  ├── 是 → security 或更高
  └── 否 → developer

问：你是否在做 AI/Agent 开发？
  ├── 是 → research 或 full
  └── 否 → security 或 developer

问：你是否想体验所有功能？
  ├── 是 → full（注意性能影响）
  └── 否 → 按需选择

重要警告：full Profile 在低配机器上可能导致性能问题，因为加载大量 Skill 和 Agent 会占用上下文窗口和内存。

五、JSON Schema 验证

ECC 使用 JSON Schema 来验证各种配置文件的正确性。

5.1 Schema 文件清单

schemas/ 目录中的 Schema 文件：

Schema 文件验证目标作用
plugin.schema.jsonPlugin Manifest验证插件配置格式
hooks.schema.jsonHook 配置验证 Hook 定义格式
install-profiles.schema.json安装 Profile验证 Profile 配置
install-components.schema.json安装组件验证组件清单
install-modules.schema.json安装模块验证模块定义
install-state.schema.json安装状态验证安装记录
ecc-install-config.schema.json安装配置验证整体安装配置
package-manager.schema.json包管理器验证包管理器配置
provenance.schema.json来源追踪验证组件来源信息
state-store.schema.json状态存储验证状态持久化

5.2 Schema 验证的价值

没有 Schema：
  修改了 hooks.json 中的一个字段名
      → 运行时才发现 Hook 不生效
      → 调试半小时才找到原因

有 Schema：
  修改了 hooks.json 中的一个字段名
      → 编辑器即时提示"字段名不合法"
      → 1 秒修复

5.3 使用方式

在支持 JSON Schema 的编辑器（如 VS Code）中，将 Schema 关联到对应的 JSON 文件：

// .vscode/settings.json
{
  "json.schemas": [
    {
      "fileMatch": ["hooks.json", ".claude/hooks.json"],
      "url": "./schemas/hooks.schema.json"
    },
    {
      "fileMatch": [".claude-plugin/plugin.json"],
      "url": "./schemas/plugin.schema.json"
    }
  ]
}

六、安装方式对比

6.1 四种安装方式

方式命令适用场景可定制性
一键安装npx ecc-install快速体验低
Profile 安装npx ecc-install --profile developer按需安装中
选择性安装npx ecc-install --select精细控制高
手动安装复制文件完全控制最高

6.2 安装位置

组件类型全局安装位置项目安装位置
Rules~/.claude/rules/.claude/rules/
Agents~/.claude/agents/.claude/agents/
Skills~/.claude/skills/.claude/skills/
Hooks~/.claude/settings.json.claude/settings.json
Commands~/.claude/commands/.claude/commands/

优先级：项目级配置 > 全局配置。当两者冲突时，项目级生效。

6.3 手动安装注意事项

手动安装时的关键警告：

# ✅ 正确：复制整个目录
cp -r rules/common ~/.claude/rules/common
cp -r rules/typescript ~/.claude/rules/typescript

# ❌ 错误：用 /* 展平目录
cp -r rules/common/* ~/.claude/rules/
cp -r rules/typescript/* ~/.claude/rules/
# 这会导致语言特定文件覆盖通用文件！
# 因为 common/ 和 typescript/ 中有同名文件

七、本课练习

练习 1：对比 Plugin Manifest（15 分钟）

这是本课最重要的练习。

阅读 .claude-plugin/plugin.json 和 .codex-plugin/plugin.json，列出至少 3 个关键差异：

# 查看 Claude Code Plugin
cat .claude-plugin/plugin.json

# 查看 Codex Plugin
cat .codex-plugin/plugin.json

对每个差异，解释为什么两个平台需要不同的设计。

练习 2：选择 Profile（10 分钟）

根据你自己的开发场景，选择一个安装 Profile，并解释为什么：

  • 你的机器配置如何？
  • 你最常用的工作流是什么？
  • 你是否需要安全扫描功能？
  • 你是否在做 AI Agent 开发？

练习 3：浏览 Schema（10 分钟）

打开 schemas/hooks.schema.json，回答：

  • Hook 配置中有哪些必填字段？
  • matcher 字段的合法值有哪些？
  • async 字段的默认值是什么？

练习 4（选做）：设计跨平台策略

假设你的团队同时使用 Claude Code 和 Codex。设计一个策略：

  • 哪些组件应该共享？
  • 哪些组件需要各自维护？
  • 如何保持两个平台的配置同步？

八、本课小结

你应该记住的内容
支持平台6 种：Claude Code（完整）、Codex（完整）、Cursor（适配）、OpenCode、Gemini、Antigravity
Manifest 差异Claude Code 列举组件，Codex 目录引用 + interface 字段
五级 Profilecore → developer → security → research → full
Schema 验证schemas/ 目录下 10 个 Schema 文件保证配置正确性
安装原则复制整个目录，不要用 /* 展平

九、下节预告

第 29 课：ECC 2.0 — Rust 控制面板与未来方向

跨平台适配是 ECC 1.x 的方案。ECC 2.0 用 Rust 重写了控制面板，引入了 TUI 仪表盘、多会话管理、SQLite 持久化。下节课你将了解 ECC 2.0 的架构、核心命令，以及为什么选择 Rust。

预习建议：浏览 ecc2/src/main.rs，感受一下 ECC 2.0 的命令结构。

avatar
文章
阅读
粉丝