Plugins 与扩展分发

结论

插件是"能力的打包与分发"层，两家都已成体系，而且出现了罕见的直接格式兼容：Codex 的 manifest 发现逻辑同时接受 .codex-plugin/plugin.json 和 .claude-plugin/plugin.json——CC 插件可以原样被 Codex 装载（取交集的组件）。组件面上 CC 更宽：commands/agents/skills/hooks/mcpServers/outputStyles/lspServers 七类；Codex 是 skills/mcp_servers/apps/hooks 四类，但额外有一整套 interface 商店化元数据（logo/截图/品牌色/隐私政策链接），并且把"发现与安装插件"做成了模型可调用的工具（list_available_plugins_to_install / request_plugin_install）——agent 自己给自己装插件。harness 应把 marketplace 索引、插件启停和信任审计做成一等功能。

研究问题

• 两家 plugin manifest 的组件清单与文件布局？
• marketplace 的索引格式、安装位置与更新机制？
• 插件的启停、命名空间与信任问题怎么解？

各 Agent 设计与实现

Claude Code

Manifest：.claude-plugin/plugin.json。 [一手源码] src_2026-03-31/utils/plugins/schemas.ts：元数据 name/version/description/author（schemas.ts:274-296）；组件七类，每类既有约定目录又可在 manifest 里补充路径或内联：

• commands/（含 skill 目录格式，schemas.ts:429-439）、agents/（:460）、skills/（:484）、hooks/hooks.json + manifest 内联 hooks（:328-368）、mcpServers（:543）、outputStyles（:507）、lspServers（:799）。

最小 manifest 对照（同一文件双方都能读，注意组件键名差异）：

// .claude-plugin/plugin.json — CC 读全部组件；Codex 读 skills/mcp/hooks 子集
{
  "name": "review-kit",
  "version": "0.1.0",
  "description": "Code review bundle",
  "commands": "./commands",      // CC only
  "agents": "./agents",          // CC only
  "skills": "./skills",          // 双方生效
  "mcpServers": "./mcp.json",    // CC 键名；Codex 侧为 mcp_servers
  "hooks": "./hooks/hooks.json"  // 双方生效（Codex 走信任门）
}

命名空间。 [一手源码] utils/plugins/loadPluginCommands.ts:73-95：命令名为 ${pluginName}:${namespace}:${commandBaseName}，namespace 来自插件内子目录路径（/ 换 :）；skill 为 ${pluginName}:${skillName}（:726）。这保证插件资产与 user/project 资产永不重名。

Marketplace。 [一手源码] schemas.ts:905-987：marketplace 源支持 直接 URL / GitHub repo / git repo / npm 包 / 本地路径 / 本地目录 六种，默认索引路径 .claude-plugin/marketplace.json（:929）。每个插件条目用相对 marketplace 根的路径定位（:1065）。安装后启停由 settings 的 enabledPlugins: {"plugin@marketplace": true|false} 控制（[一手文档] docs/plugins.md）。另有插件自动更新（pluginAutoupdate.ts）、阻断名单（pluginBlocklist.ts）、官方 marketplace 启动检查（officialMarketplaceStartupCheck.ts）。

变量注入与用户配置：插件文件内可用 ${CLAUDE_PLUGIN_ROOT}（插件根）、${CLAUDE_PLUGIN_DATA}（更新后仍保留的持久数据目录）（[一手文档] docs/mcp.md:245、plugins-reference.md）；插件还可声明用户可填选项，hook 命令里以 ${user_config.X}（schema 校验）与 CLAUDE_PLUGIN_OPTION_* 环境变量消费（[一手源码] utils/hooks.ts:818，存储在 pluginOptionsStorage.ts）。

质量与治理工装齐全。 [一手源码] utils/plugins/ 目录本身就是一张治理清单：validatePlugin.ts（结构校验，/plugin validate 的实现）、dependencyResolver.ts（插件间依赖，对应文档 plugin-dependencies.md）、pluginVersioning.ts、orphanedPluginFilter.ts（marketplace 移除后的孤儿插件清理）、pluginFlagging.ts + pluginBlocklist.ts（风险标记与封禁）、zipCache.ts（分发包缓存）。harness 不必重造这些轮子，但要知道它们的存在边界——全部只对 CC 生效。

Codex CLI

Manifest：双格式兼容。 [一手源码] codex-rs/utils/plugins/src/plugin_namespace.rs:8：

const DISCOVERABLE_PLUGIN_MANIFEST_PATHS: &[&str] =
    &[".codex-plugin/plugin.json", ".claude-plugin/plugin.json"];

字段（core-plugins/src/manifest.rs:14-53）：name/version/description/keywords + 组件路径 skills / mcp_servers / apps / hooks（路径或内联 HooksFile），必须用 ./ 相对路径并在插件根内（路径穿越校验）。

interface：商店化元数据（CC 无）。 [一手源码] manifest.rs:61-77：display_name / short_description / long_description / developer_name / category / capabilities / website_url / privacy_policy_url / terms_of_service_url / default_prompt(≤3 条、各 ≤128 字符) / brand_color / composer_icon / logo / screenshots。插件在 Codex 里是面向最终用户的"应用"，不只是开发者资产包。

Marketplace 与安装。 [一手源码] core-plugins/src/installed_marketplaces.rs:11：marketplace 安装在 $CODEX_HOME/.tmp/marketplaces；marketplace_add.rs/marketplace_remove.rs/marketplace_upgrade.rs 提供全生命周期；startup_sync.rs 做启动期同步。启停写 config.toml：[plugins."demo@market"]（config/src/plugin_edit.rs:201），toggles.rs 管理开关。远程分发支持 bundle 归档（plugin_bundle_archive.rs、remote_bundle.rs）。

模型自助安装插件。 [一手源码] core/src/tools/handlers/list_available_plugins_to_install.rs 与 request_plugin_install.rs——这两个是注册给模型的工具：agent 可以列出可装插件并发起安装请求（经用户确认）。CC 没有等价工具（插件操作走 /plugin UI 与 CLI）。

信任联动：插件 hooks 带 plugin_id 分组进入 hooks 信任体系（见 hooks 章），来源标记 HookSource::Plugin。

分发通道分层。 [一手源码] core-plugins/src/ 的 remote 模块族：remote_bundle.rs（云端 bundle）与 remote_legacy.rs（旧通道）并存，discoverable.rs 负责"可发现插件"清单（喂给上文的模型工具），store.rs 管本地安装态。配合 connectors crate（ChatGPT connectors）可见 Codex 插件体系的终态对标的是 ChatGPT Apps 生态，而非开发者脚本包 [推断]。

差异矩阵

最小复现

# 验证 Codex 读 CC 插件 manifest（格式兼容性）
mkdir -p /tmp/demo-plugin/.claude-plugin /tmp/demo-plugin/skills/hello
cat > /tmp/demo-plugin/.claude-plugin/plugin.json <<'EOF'
{ "name": "demo-plugin", "skills": "./skills" }
EOF
cat > /tmp/demo-plugin/skills/hello/SKILL.md <<'EOF'
---
name: hello
description: demo skill from plugin
---
Say hello.
EOF
# Codex 装载后 skill 应带 demo-plugin 命名空间（plugin_namespace.rs 上溯 plugin.json 取 name）
# （未实测安装流程；manifest 双路径常量为一手源码证据）

Harness 接入建议（Yoda 实践）

1. 把插件当独立资产层：Yoda 的 harness 视图目前扫 project 级裸资产（skills/commands/agents），应增加 plugin 维度——CC 读 settings enabledPlugins + 插件缓存目录，Codex 读 config.toml [plugins.*] + $CODEX_HOME/.tmp/marketplaces。展示"资产来自哪个插件"比平铺资产更重要，因为启停是插件粒度的。
2. 跨 runtime 复用检测：发现 .claude-plugin/plugin.json 时，可同时标注"Codex 可装载（skills/mcp/hooks 三类生效，commands/agents/outputStyles/lsp 会被忽略）"——这是 Yoda 能提供的独特价值：告诉用户一个插件在每个 runtime 里实际生效的子集。
3. 校验：manifest JSON schema 校验 + 路径规则（Codex 要求 ./ 前缀且不得越界，直接复用其报错语义）；hooks 组件要联动 hooks 信任校验（Codex 侧装完插件 hook 仍可能因 Untrusted 不跑）。
4. 信任审计：marketplace 来源（git URL / npm 包名）+ 插件内 hooks/MCP 命令清单，做成安装前 review 界面——两家 runtime 都没有给出"装前看清单"的完整 UI，这是 harness 的补位点。

失效条件

• Codex 移除 .claude-plugin/plugin.json 兼容路径（plugin_namespace.rs:8 常量变更）
• Codex 插件组件扩展到 commands/agents（与 CC 组件面对齐）
• CC marketplace 索引默认路径或 enabledPlugins 格式变更
• Codex marketplace 安装目录 .tmp/marketplaces 转正（路径含 .tmp，明显是过渡命名）

参考资料

• CC 源码：src_2026-03-31/utils/plugins/schemas.ts、loadPluginCommands.ts、loadPluginHooks.ts、marketplaceManager.ts、pluginLoader.ts
• Codex 源码：codex/codex-rs/core-plugins/src/{manifest.rs,marketplace.rs,installed_marketplaces.rs,toggles.rs,startup_sync.rs}、utils/plugins/src/plugin_namespace.rs、config/src/plugin_edit.rs、core/src/tools/handlers/request_plugin_install.rs
• 文档：claude-code-docs/docs/plugins.md、plugins-reference.md、plugin-marketplaces.md、discover-plugins.md