ECC 插件清单约束指南：Claude Code plugin.json 验证器的未公开规则与正确姿势

ECC 插件清单约束指南Claude Code plugin.json 验证器的未公开规则与正确姿势【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文围绕 ECC 仓库中的 PLUGIN_SCHEMA_NOTES.md 展开系统讲解 Claude Code 插件清单plugin.json验证器那些未在公开 schema 文档中记载、但实际强制执行的约束必填的version字段、必须为数组的组件字段、严禁添加的agents/hooks字段、用于 MCP 隔离的空mcpServers声明等。读完本文你能够安全地修改、校验 ECC 或任何 Claude Code 插件的清单文件避开「本地验证通过、安装时报Invalid input」这类隐蔽故障并理解 ECC 如何用回归测试把这些规则固化下来。背景一个「严格且有主见」的验证器Claude Code 插件清单验证器的典型故障模式是清单文件看起来完全合理但验证器却拒绝它只抛出一个模糊的错误例如agents: Invalid input这类问题很难排查因为公开 schema 参考并没有完整描述验证器的全部行为。ECC 仓库把基于真实安装失败、验证器实际行为、以及和已知可用插件对比得出的约束记录在 PLUGIN_SCHEMA_NOTES.md 中目的正是「防止静默破坏和重复回归」。该文档的定位很明确如果你要编辑 plugin.json先读这份笔记。必填字段versionversion字段是验证器的强制要求即使某些官方示例里省略了它。缺失时安装可能失败在 marketplace 安装阶段或 CLI 校验阶段。{ version: 1.1.0 }从仓库自身的 schema 可以进一步看出取值约束plugin.schema.json 中version的 pattern 为^[0-9]\.[0-9]\.[0-9](?:-[0-9A-Za-z.-])?$即标准 SemVer可选带预发布后缀。当前 ECC 的实际清单中version为2.2.1与 marketplace.json 中声明的版本保持一致——两处版本号同步也是仓库测试所约束的。字段形状规则commands/skills/hooks必须永远是数组以下字段必须始终是数组commandsskillshooks如果存在即使只有一个条目字符串值也不被接受。这条规则一致地适用于所有组件路径字段。仓库的 plugin.json 遵循了这一点{ name: ecc, version: 2.2.1, mcpServers: {}, skills: [./skills/], commands: [./commands/] }对应的回归测试位于 tests/plugin-manifest.test.jsclaude plugin.json commands is an array确保commands字段一旦退化为字符串就会被测试捕获。路径解析规则commands和skills接受目录路径但仅当它们被包裹在数组中显式文件路径最安全、也最具前瞻性most future-proof。这与「避免依赖推断路径」的防反模式列表一脉相承能用显式路径就不要让验证器去猜。Agent 的toolsfrontmatter使用标量而不是数组上一条数组规则只适用于plugin.json不适用于agent 的 Markdown frontmatter。Claude Code 的 agent 文件使用逗号分隔的标量来声明工具白名单tools: Read, Glob, Grep不要写成 YAML 序列例如tools: [Read, Glob, Grep]。省略tools字段会让 agent 获得所有工具的访问权限但 ECC 的 agent 都显式声明白名单且仓库验证器要求该字段存在。仓库中的 agent 文件与这一规则完全一致例如 agents/code-reviewer.md--- name: code-reviewer description: Expert code review specialist. ... tools: Read, Grep, Glob, Bash model: sonnet ---这里tools: Read, Grep, Glob, Bash正是标准的逗号分隔标量写法68 个 agent 文件均遵循同样的形状。agents字段不要添加警告不要在plugin.json中添加agents字段。Claude Code 插件验证器会完全拒绝它。agents不是 Claude Code 插件清单 schema 的一部分。它的任何形式——字符串路径、路径数组、目录数组——都会导致校验错误agents: Invalid inputagents/目录下的 agent.md文件会按约定自动发现与 hooks 的机制类似不需要在清单中声明。历史沿革本仓库曾把 agents 以文件路径数组的形式显式列入plugin.json。这种做法通过了仓库自己的 schema 校验却通不过 Claude Code 实际验证器——因为后者根本不认识这个字段。该字段已在 PR #1459 中移除。hooks字段不要添加有回归测试强制警告不要在plugin.json中添加hooks字段。这一条由回归测试强制保护。Claude Codev2.1会按约定自动加载任何已安装插件的hooks/hooks.json。如果你同时在plugin.json里再声明一次就会触发重复加载错误Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file. The standard hooks/hooks.json is loaded automatically, so manifest.hooks should only reference additional hook files.反复横跳的历史这条规则在仓库中造成了多轮「修复/回滚」循环Commit动作触发原因22ad036添加 hooks用户报告 hooks not loadinga7bc5f2移除 hooks用户报告 duplicate hooks error#52779085e添加 hooks用户报告 agents not loading#88e3a1306移除 hooks用户报告 duplicate hooks error#103根因Claude Code CLI 在不同版本间改变了行为——v2.1 之前需要在清单中显式声明hooksv2.1 及以后按约定自动加载重复声明会直接报错。当前规则由测试固化这个「不要再加回去」的规则被写进了两处回归测试tests/hooks/hooks.test.js 中的plugin.json does NOT have explicit hooks declaration断言plugin.json不含hooks字段tests/plugin-manifest.test.js 中的同名测试直接断言!(hooks in claudePlugin)并注明「Claude Code v2.1 按约定自动加载hooks/hooks.json」。注意边界如果你在添加的是额外的hook 文件不是hooks/hooks.json本身那些可以在清单中声明但标准的hooks/hooks.json绝不能声明。ECC 的 hook 入口正是 hooks/hooks.json配合hooks/codex-hooks.json支持 Codex 侧的安装。mcpServers字段保留显式的空对象MCP 隔离开关ECC 在仓库根目录保留 .mcp.json 用于 Codex 插件安装和手工 MCP 配置此外还有更完整的 mcp-configs/mcp-servers.json包含 GitHub、Jira、Supabase、firecrawl 等多个 server 定义。但 Claude Code 也会按约定自动发现插件根目录的.mcp.json这会把同样的 MCP server 打包进 Claude 插件安装。因此 plugin.json 中刻意保留了这个显式空对象{ mcpServers: {} }这个 opt-out 的作用是阻止 Claude 插件安装自动加载 ECC 根目录的 MCP 定义。为什么必须这样做因为 Claude 插件 slug 虽然已刻意取短名ecc但遗留安装和严格的 provider 网关在更长的插件标识符上会生成超长 MCP 工具名并直接拒绝。例如形如mcp__plugin_everything-claude-code_github__create_pull_request_review的工具名超过 64 个字符会被严格的 OpenAI 兼容网关拒收。这一行为被 tests/plugin-manifest.test.js 精确验证测试先断言该历史超长工具名确实超过 64 字符再断言mcpServers键必须显式存在且严格等于{}Object.prototype.hasOwnPropertydeepStrictEqual保证未来重构不会无意移除这个 opt-out。想要使用打包 MCP server 的用户应手动从 .mcp.json 或 mcp-configs/mcp-servers.json 配置。验证器行为特征小结claude plugin validate比部分 marketplace 预览更严格路径有歧义时本地验证可能通过、安装时却失败错误信息往往很笼统Invalid input不指示根因跨平台安装尤其是 Windows对路径假设更不宽容。一句话心态假定验证器是敌对且字面化的Assume the validator is hostile and literal。已知反模式清单以下写法「看起来正确」但会被拒绝用字符串值代替数组以任何形式添加agents—— 不是被识别的清单字段会报Invalid input缺少version依赖推断路径inferred paths假设 marketplace 行为与本地验证一致添加hooks: ./hooks/hooks.json—— 该文件已被约定自动加载会触发重复错误移除mcpServers: {}—— 会重新启用 Claude 插件安装的根目录.mcp.json自动发现可能产生超长的 MCP 工具名。原则避免取巧保持显式Avoid cleverness. Be explicit.。最小可用示例与 ECC 实际清单对照文档给出的「已知可用最小示例」{ version: 1.1.0, commands: [./commands/], skills: [./skills/] }该结构已经过 Claude 插件验证器验证。注意其中既没有hooks字段也没有agents字段——两者都按约定自动加载显式添加任何一个都会导致错误。ECC 实际发布的 plugin.json 在此骨架上额外携带了元数据description、author、homepage、repository、license、keywords和两个userConfig偏好项hooks_enabled布尔默认true控制是否启用本地 hook 自动化和hook_profile字符串取minimal/standard/strict非法值安全回退到standard。tests/plugin-manifest.test.js 专门断言userConfig只暴露这两个 key且字段形状固定为type/title/description/default四项——注释说明 Claude 的userConfig不支持enum所以hook_profile只能声明为string并在运行时做回退。贡献者检查清单在提交任何触碰plugin.json的变更之前确保所有组件字段都是数组包含version不要添加agents或hooks字段两者都按约定自动加载除非有意改变 Claude 插件的 MCP 打包行为否则保留mcpServers: {}运行验证claude plugin validate .claude-plugin/plugin.json如有疑问宁要冗长、不要方便choose verbosity over convenience。为什么这份文档值得长期维护ECC 是一个被广泛 fork、并常被当作参考实现的仓库把验证器的「怪癖」文档化可以阻止问题反复出现、降低贡献者的挫败感、并在生态演进时保住插件的稳定性。文档的最后一句规则值得记住如果验证器本身变了先更新这份文档——它和 tests/plugin-manifest.test.js、tests/hooks/hooks.test.js 中的断言一起构成了「文档 测试」双层防线防止上述任何一条约束在后续版本中被无意破坏。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考