# 传统 Codex 与 Claude Code 插件解析兼容方案

## 范围与基线

本轮只处理传统 Codex `.codex-plugin/plugin.json` 和 Claude Code `.claude-plugin/plugin.json`。Agent Plugins 1.0.0（根目录 `plugin.json`、独立 schema 及 portable MCP）单独立项，不属于 Codex 的本轮兼容范围。

| 平台 | 对照版本 | 标签与提交 | 发布日期（Asia/Shanghai） |
|---|---|---|---|
| Codex 传统格式 | 0.163.0 | `rust-v0.163.0` / `83086188ae0614bd882818ff1aa23f3194962012` | npm：2026-10-16 05:37:11.083；GitHub Release：2026-10-16 05:30:38 |
| Claude Code | 2.1.304 | `v2.1.304` / `772c6bee5c36f58be43bbb2b182862aeb22aceff` | npm：2026-10-20 03:47:15.337 |

官方在线文档查阅日期：2026-10-20，时区 Asia/Shanghai。CLI 源码提交和文档站查阅日期分别记录；Claude Code 仓库的提交不能冒充文档站提交。第三方插件的 `version`、本项目的 parser 版本和上游产品版本是三个独立概念。本项目历史版本没有固定上游版本记录，不追溯臆造兼容基线。

## 实施原则

- 保持 Source → 平台描述 → 统一能力 → Adapter 分层。平台先按自身规则合并，再检查跨格式等价和跨插件冲突。
- 区分配置非法、合法但运行未适配、可忽略展示字段；认证、权限、执行范围或阻断决策不能静默丢弃。
- 解析阶段只读配置，不执行 Hook、动态 Skill 命令、函数模块或依赖安装。
- 保存来源文件和 JSON Pointer，凭据不进入扫描缓存、列表或诊断。
- 不安装、启停或修改当前 DSH profile。

## Manifest 与 Marketplace

Codex 传统格式本地清单优先，缺失时使用 Marketplace 条目回退。有效显式 Skill 路径替换默认扫描；显式 Hook 路径或内联定义替换默认文件；MCP 显式路径、内联对象与缺省情况分别处理。空值、无效值和缺省值不能统一解释成关闭能力。校验 interface、apps、传统 OpenAI 扩展及 Marketplace policy；早期字段别名单独注明。

Claude Code：`commands`、`agents` 显式声明替换默认扫描，`skills` 追加；Hook 默认文件先加载，清单配置合并，Marketplace 同事件条目覆盖 Manifest 事件组；MCP 默认文件先加载，后声明的同名服务器覆盖，仅限同平台同插件。`strict:false` 检查 Marketplace 条目冲突，不清空本地清单。支持 Command 对象 `source` / `content` 互斥形式，独立记录运行状态。`defaultEnabled`、展示元数据、作者版本与组件命名空间分别遵循上游优先级。

合法的 npm、归档、command 来源与本项目是否支持获取分开诊断，不在解析阶段执行安装命令。

## Hook

分别建立平台事件目录、Handler 声明和 DSH 执行映射。合法但无 DSH 映射的事件标记为运行未适配。Codex 覆盖固定基线的 12 类事件，CC 按查阅日官方目录识别，包括模型切换与函数 Hook 模块。

落实 command Handler 关键字段、Codex 通配/精确/正则 matcher、完整 JSON 工具输入和结果、CC `onFailure` 和停止语义。非 command Handler，以及无法兑现的过滤、Shell、重唤醒和结果重写语义，明确诊断。`args` 的直接执行不能伪装成 Shell 字符串执行。当前 DSH Shell、Agent 初始化事件和会话读取作为必要运行边界适配，回归命令未执行却记录 pass 的旧问题。

## Skill 与 MCP

Codex 读取 `agents/openai.yaml` 并落实隐式调用策略；CC 识别 `when_to_use` 和平台布尔写法。高级约束及动态正文不能只存 metadata 后当普通 Skill 运行。

MCP 分平台解析字段及认证引用，保留延迟凭据。无法兑现的工具限制、审批或认证要求阻止启用。MCP bundle、其他 transport 和交互认证等未运行适配形式给出专用诊断，不引入 Agent Plugins portable MCP 规则。

## 验收

固定上游示例与提交，覆盖字段类型、缺省、空值、路径、优先级、合并和覆盖。重点回归 Codex `*`、非 Shell 工具 JSON、Skill 隐式调用限制和延迟认证；CC `strict`、事件覆盖、默认配置合并及 `onFailure:block`。检查凭据不进入缓存、跨插件不可覆盖、混合方言不重复执行。构建、完整测试和发布检查分别记录；未实测 Desktop 挂载、浏览器或远端 MCP 时明确注明。

最终实现状态与验证结果见《插件协议兼容验证报告》；本方案本身不是全部能力兼容声明。

## 官方依据

- [Codex 0.163.0](https://github.com/openai/codex/releases/tag/rust-v0.163.0)
- [Codex Manifest](https://github.com/openai/codex/blob/83086188ae0614bd882818ff1aa23f3194962012/codex-rs/core-plugins/src/manifest.rs)
- [Codex 组件发现](https://github.com/openai/codex/blob/83086188ae0614bd882818ff1aa23f3194962012/codex-rs/core-plugins/src/loader.rs)
- [Codex Hook](https://github.com/openai/codex/blob/83086188ae0614bd882818ff1aa23f3194962012/codex-rs/hooks/src/lib.rs)
- [Claude Code 更新记录](https://github.com/anthropics/claude-code/blob/772c6bee5c36f58be43bbb2b182862aeb22aceff/CHANGELOG.md)
- [Claude Code Manifest](https://code.claude.com/docs/en/plugins/manifest-reference)
- [Claude Code Marketplace](https://code.claude.com/docs/en/plugins/marketplace-reference)
- [Claude Code Hook](https://code.claude.com/docs/en/hooks)
- [Claude Code Skill](https://code.claude.com/docs/en/skills)