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

---

一、本课概述

从第 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	仅通过配置文件提供指导
Antigravity	IDE 集成	—	IDE 内集成

2.2 功能覆盖矩阵

功能	Claude Code	Codex	Cursor	OpenCode	Gemini
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	包含内容	适用场景	组件数量（约）
core	Rules + 核心 Skill	轻量使用、低配机器	~30
developer	core + TDD/Review Agent + 开发 Skill	日常开发	~100
security	developer + 安全 Agent/Skill	安全敏感项目	~120
research	security + AI 实验 Skill	AI 研究和实验	~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.json	Plugin Manifest	验证插件配置格式
hooks.schema.json	Hook 配置	验证 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 字段
五级 Profile	core → 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 的命令结构。