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

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

一、本课概述

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

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

理解跨平台机制后，你就具备了为任何 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`）

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`）

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 不是"要么全装、要么不装"。它提供了五个安装级别：

sql 复制代码

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 选择建议

sql 复制代码

问：你的机器配置如何？
  ├── 低配（<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 验证的价值

markdown 复制代码

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

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

5.3 使用方式

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

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 手动安装注意事项

手动安装时的关键警告：

bash 复制代码

# ✅ 正确：复制整个目录
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 个关键差异：

bash 复制代码

# 查看 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 的命令结构。

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

一、本课概述

二、Harness 支持表

2.1 六大平台支持对比

2.2 功能覆盖矩阵

2.3 设计意义

三、Plugin Manifest 格式

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

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

3.3 两种 Manifest 的差异

四、安装 Profile

4.1 五级 Profile

4.2 Profile 详情

4.3 Profile 选择建议

五、JSON Schema 验证

5.1 Schema 文件清单

5.2 Schema 验证的价值

5.3 使用方式

六、安装方式对比

6.1 四种安装方式

6.2 安装位置

6.3 手动安装注意事项

七、本课练习

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

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

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

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

八、本课小结

九、下节预告

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

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