# 传统 Codex 与 Claude Code 插件兼容矩阵

## 1. 兼容基线和范围

| 平台 | 核对版本 | 固定源码 | 官方文档基线 |
|---|---|---|---|
| 传统 Codex 插件 | Codex 0.163.0，`rust-v0.163.0` | `83086188ae0614bd882818ff1aa23f3194962012` | 2026-10-20 查阅，传统清单加载行为以该源码为准 |
| Claude Code 插件 | Claude Code 2.1.304，`v2.1.304` | `772c6bee5c36f58be43bbb2b182862aeb22aceff` | 2026-10-20 的官方 Manifest、Marketplace、Hook 和 Skill 文档 |

这里只声明下表列出的功能子集。第三方插件 `version` 是作者版本；本项目传统规则修订时的 Plugin parser / Source parser 为 `3.0.0`，独立格式接入后为 `3.1.0`，是缓存失效与内部语义版本，不是上游协议版本。旧工作区没有固定上游版本的历史记录，不追溯猜测。Claude Code 的 `$schema` 用于编辑器提示，不能视为运行时协议协商。

**Agent Plugins 1.0.0 是独立格式，不属于 Codex 兼容。** 已通过根 `plugin.json`、独立本地 schema 和固定 Skill/MCP 组件接入，详见[独立格式兼容说明](<Agent Plugins 1.0.0 兼容说明.md>)。传统规则保持独立，不套用到 portable 格式。

方案与证据见[传统插件解析兼容方案](传统插件解析兼容方案.md)，本轮验证及限制见[插件协议兼容验证报告](插件协议兼容验证报告.md)。文档中“识别”不代表“执行”。

## 2. Source、Manifest 与 Marketplace

| 项目 | Codex 传统格式 | Claude Code |
|---|---|---|
| 清单入口 | `.codex-plugin/plugin.json` | `.claude-plugin/plugin.json` |
| Marketplace | `.agents/plugins/marketplace.json` | `.claude-plugin/marketplace.json` |
| 无本地清单 | 使用 Marketplace 条目回退；没有条目则报缺失 | 条目作为清单；普通目录推断有明确 warning |
| 本地清单优先级 | 有本地清单不叠加条目内联能力 | 按 `strict`、组件和元数据各自规则处理 |
| Skill 显式路径 | 有效非空路径替换默认 roots；无有效路径时按固定加载器规则回退，并对非法值诊断 | 显式路径追加默认 `skills/`；共享 Source 根条目显式路径作为插件边界 |
| Hook 显式声明 | 路径、路径数组、内联、内联数组；有效显式配置替换默认文件 | 文件与 inline 形式可混合，默认文件先加载后合并 |
| MCP 显式声明 | 路径或对象按各自形态替换默认文件 | 默认 `.mcp.json` 先加载；后声明同名服务器覆盖 |
| Command / Agent 默认发现 | 历史兼容扩展与运行不支持状态明确注明 | 显式字段替换默认；Agent 路径须为 Markdown 文件 |
| `commands` 对象 | 不冒充 Codex 现行标准组件 | 接受 `source` / `content` 互斥定义，inline 正文只保留位置引用 |
| `defaultEnabled` | 依 Marketplace 安装策略与用户选择 | 条目覆盖本地清单；用户显式选择优先 |
| 重名能力 | 跨插件禁止覆盖；跨格式等价才合并 | 同平台同插件 MCP 内部覆盖先完成，再检查跨格式/跨插件冲突 |

CC `strict:false` 且有本地清单时，检查条目是否额外声明冲突能力，不删除本地清单能力；`strict:true` 下，条目同事件 Hook 替换低优先级事件组，其余事件保留。替换通过来源过滤实现。Marketplace 内联延迟 JSON 引用保存 `base:source`，运行时由当前安装布局提供 Source 根；组件路径仍相对插件根。这样嵌套插件和外部 Git 插件不会把 Marketplace 文件误读成插件内同名文件，缓存也不携带安装暂存目录绝对路径。

相对目录、Git、`github`（CC）和 git-subdir 继续使用既有安全获取器。npm、远端 archive、command 等合法来源有安装未适配诊断，不在扫描时下载或执行。多插件来源仍必须明确选择。字段类型、`./` 语法、存在性、真实路径和符号链接边界分别检查。

## 3. Hook 事件、Handler 和运行状态

Codex 识别固定版本的 12 类事件：`PreToolUse`、`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、`SessionStart`、`SessionEnd`、`UserPromptSubmit`、`SubagentStart`、`SubagentStop`、`Stop`、`Interrupt`。早期 snake_case 是带诊断的兼容别名。

Claude Code 识别查阅日官方事件目录，包括模型切换、压缩、任务、权限、工作区、文件与 MCP elicitation 事件。事件合法性和 DSH 运行映射独立。

| 可运行事件 | DSH 边界 |
|---|---|
| `SessionStart` | `agent/created`，串行等待初始化 |
| `UserPromptSubmit` | `agent/pre-step` |
| `PreToolUse` | `tools/pre-execute` |
| `PostToolUse` | `tools/post-execute`，只对成功工具结果触发 |
| `Stop` | `agent/turn-stopping` |
| `SubagentStart` | `subagent/start`，限可找到的本进程子代理，初始化等待保证与宿主 emit 边界不同 |

`SubagentStop` 只解析不运行：当前 `subagent/end` 是子代理已经结束后的通知，不能兑现上游停止前等待、阻断或续步保证，因此以合法但运行未适配的 error 阻止启用。

其他合法事件保留可检查声明并给出 `HOOK_EVENT_RUNTIME_UNSUPPORTED`；未知事件为 `HOOK_EVENT_UNKNOWN`。当前只运行 command Handler。Codex 的 `mcp_tool` 及 CC 的 `http`、`mcp_tool`、`prompt`、`agent` 合法但运行未适配，产生 error。CC 函数 Hook `modules` 给专用 error，即使与普通 hooks 同文件也不静默忽略、不导入模块。

### 支持与限制

- matcher 区分匹配全部、精确名称/列表、正则；Codex `*` 合法，纯字母数字下划线及 `|` 按精确列表处理。CC 按事件的 matcher 语法处理；无 matcher 语义的事件会明确提示忽略。正则执行使用 JavaScript 引擎，与 Codex Rust regex 不完全等价；不支持的语法明确诊断，未声明完整引擎兼容。
- 工具输入和输出保留完整公开 JSON，不裁成 command，不包含模型私有推理。
- `args` 存在即直接 argv 执行，包括空数组；缺少直接执行服务时失败，不降级为 Shell。无 args 保持 Shell 语义。显式选择尚未保证的 Shell 有明确未适配状态。
- `onFailure:block` 在有效的 CC 阻断事件上，对启动失败、超时、异常退出及无效 JSON 阻止继续。Stop/SubagentStop 等上游不采纳该字段的事件不扩大其效果；后台阻断组合不伪装支持。
- `continue:false` 通过取消当前 Agent 工作并阻止后续派发处理；Stop 的 block 或 additionalContext 通过完整 UserMessage steering 请求继续，携带 stop_hook_active 并限制连续八次续步，两者不能混淆。
- SessionStart/UserPromptSubmit 普通 stdout 可以形成上下文；`systemMessage` 在 Host 日志提示，不声明完整终端通知支持。
- `if`、`asyncRewake`、函数模块等未兑现的行为给明确 error。展示文本可提示省略，不复制任意文本进入扫描缓存。
- 输入或 MCP 结果重写、延迟工具执行等未实现输出不会被静默当作 allow；运行时明确阻断并说明原因。
- Codex PreToolUse `ask` 在固定版本的实际行为中不受支持；收到它会明确拒绝，不沿用旧桥的静默放行。
- Hook 生命周期仍复用共享协议的输出解析、合并和日志词汇；执行桥支持当前 Shell `execute().result()`，并兼容旧 `run()`。不把协议库版本当成 Codex/CC 协议号。
- 当前 DSH 从 session projection 读取轮次与公开回复，旧 Host 才使用原有 `session.events`。执行失败记为 error 或阻断决策，并更新健康状态。

## 4. Skill

| 项目 | 状态 |
|---|---|
| SKILL.md、正文与资源 | 按需读取，保留原正文，不安装时执行 |
| 名称、描述、调用控制 | 校验上游字段；DSH 名称限制单独诊断，不自动改名 |
| CC `when_to_use` | 支持，并保留早期拼写兼容 |
| CC 宽松布尔 | 对对应字段接受 yes/no/on/off/1/0，不改变整个 YAML 的平台语义 |
| Codex `agents/openai.yaml` | 校验 interface、dependencies、policy |
| Codex `allow_implicit_invocation:false` | 映射为禁止模型自动调用 |
| Codex 展示字段 | 保留已校验信息，明确 DSH 未渲染的部分 |
| Codex 工具依赖与产品限制 | 未兑现时阻止启用，不自动安装或授权依赖 |
| CC 高级执行字段 | 工具限制、模型/effort、fork/agent、hooks、paths、动态命令及参数替换等未实现语义有专用诊断 |

合法但未支持的限制记录在 `runtimeUnsupported`，Provider 也防御拒绝注册。不能把 metadata 保留等同于运行兼容。frontmatter 与 sidecar 使用本项目显式 YAML 子集，覆盖本轮固定样例中的 map/list/块文本；重复键拒绝，未声明完整 YAML 规范兼容。

## 5. MCP

stdio 与 streamable-http 使用 DSH 子插件生命周期；支持 command、args、cwd、env、已实现的超时和重连字段。CC `headers` 与 Codex 传统 `http_headers`、`env_http_headers`、`bearer_token_env_var` 分别解析；环境 Header 非空时覆盖静态 Header，bearer 最后覆盖 Authorization，Header 名不区分大小写。

`${NAME}`、路径变量及支持的 `${NAME:-default}` 延迟解析。含敏感字面或 fallback 的模板只保存包内位置，运行时才展开。未实现的 user_config/模板语法有明确诊断。

未兑现的认证、工具审批/白名单、依赖或关键运行约束产生 error；展示差异和可公开忽略的差异产生 warning。SSE、其他未支持 transport、MCP bundle、交互认证和 Header helper 不会伪装运行。`.mcpb` / `.dxt` 路径或 URL 有专用诊断。这里只适配 MCP 配置，不宣称通过所有 MCP wire protocol 版本或远端服务握手。

## 6. 其他能力与诊断

Command、Agent 可解析及检查，但本轮仍不注册运行。Workflow、Output Style、LSP、Theme、Monitor、Channel 等维持明确诊断；CC userConfig、插件依赖、会改变执行语义的 settings 未复现时阻止启用。

error 阻止插件启用，但可保存安装记录检查；warning 允许运行并公开差异；info 只在 Host 保留。解析、安装、启用、网络连通和完整运行是不同结果。运行支持状态不能从“字段能读出”或“父 Fiber 已创建”推断。

## 7. 当前宿主边界

本轮覆盖传统协议解析和相关 Hook/Skill/MCP 接入，未执行当前 profile 的安装或浏览器端到端测试。构建依赖中的旧 Typert 生成格式与当前 Desktop 注册契约有已知差异，Web 兼容不能由本轮解析测试替代。具体结果以[本轮验证报告](插件协议兼容验证报告.md)为准。