5.6 KiB
插件清单模式（Plugin Manifest Schema）说明
本文档记录了 Claude Code 插件清单校验器（Validator）中未公开但强制执行的约束条件。
这些规则基于真实的安装失败案例、校验器行为分析以及与已知可用插件的对比。 它们的存在是为了防止隐性破坏（silent breakage）和重复出现的回归（regressions）问题。
如果你需要编辑 .claude-plugin/plugin.json，请务必先阅读本文。
摘要（优先阅读）
Claude 插件清单校验器非常严格且具有确定性。 它强制执行了一些在公共模式（Schema）引用中未完全记录的规则。
最常见的失败模式是：
清单看起来很合理，但校验器拒绝了它，并给出模糊的错误提示，例如
agents: Invalid input
本文档将解释其原因。
必填字段
version（强制要求）
校验器要求必须包含 version 字段，即使在某些示例中省略了它。
如果缺失该字段，在应用市场安装或 CLI 校验期间可能会失败。
示例：
{
"version": "1.1.0"
}
字段形态规则
以下字段必须始终为数组（Arrays）：
agentscommandsskillshooks（如果存在）
即使只有一个条目，也不接受字符串（Strings）类型。
错误示例（Invalid）
{
"agents": "./agents"
}
正确示例（Valid）
{
"agents": ["./agents/planner.md"]
}
这一规则一致适用于所有组件路径字段。
路径解析规则（关键）
Agents 必须使用显式文件路径
校验器不接受 agents 字段使用目录路径。
即使是以下写法也会失败：
{
"agents": ["./agents/"]
}
相反，你必须显式枚举智能体（Agent）文件：
{
"agents": [
"./agents/planner.md",
"./agents/architect.md",
"./agents/code-reviewer.md"
]
}
这是校验错误最常见的来源。
命令（Commands）与技能（Skills）
commands和skills仅在包裹在数组中时接受目录路径。- 显式文件路径是最安全且最能兼容未来的做法。
校验器行为注意事项
claude plugin validate比某些应用市场预览（marketplace previews）更严格。- 校验可能在本地通过，但如果路径含义模糊，在安装时可能会失败。
- 错误提示通常很通用（
Invalid input），且不会指出根本原因。 - 跨平台安装（尤其是 Windows）对路径假设的容忍度较低。
请假设校验器是严苛且完全按字面意思理解的。
hooks 字段：请勿添加
⚠️ 关键（CRITICAL）： 请勿在
plugin.json中添加"hooks"字段。这是一个回归测试强制要求的规则。
为什么这很重要
按照约定，Claude Code v2.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.
反复变更的历史
这曾导致此仓库中出现多次“修复/回滚”循环：
| 提交 | 动作 | 触发原因 |
|---|---|---|
22ad036 |
添加（ADD）hooks | 用户报告“钩子未加载” |
a7bc5f2 |
移除（REMOVE）hooks | 用户报告“重复钩子错误” (#52) |
779085e |
添加（ADD）hooks | 用户报告“智能体未加载” (#88) |
e3a1306 |
移除（REMOVE）hooks | 用户报告“重复钩子错误” (#103) |
根本原因： Claude Code CLI 在不同版本间更改了行为：
- v2.1 之前：需要显式声明
hooks。 - v2.1+：按约定自动加载，显式声明会导致重复错误。
当前规则（由测试强制执行）
tests/hooks/hooks.test.js 中的测试 plugin.json does NOT have explicit hooks declaration 会阻止重新引入此声明。
如果你要添加额外的钩子文件（非 hooks/hooks.json），可以声明它们。但标准路径 hooks/hooks.json 绝不能被声明。
已知的反模式（Anti-Patterns）
这些看起来正确但会被拒绝：
- 使用字符串值而非数组
- 在
agents中使用目录数组 - 缺失
version - 依赖推断路径
- 假设应用市场行为与本地校验一致
- 添加
"hooks": "./hooks/hooks.json"—— 按约定自动加载，会导致重复错误
不要尝试“取巧”，请保持显式声明。
最小已知可用示例
{
"version": "1.1.0",
"agents": [
"./agents/planner.md",
"./agents/code-reviewer.md"
],
"commands": ["./commands/"],
"skills": ["./skills/"]
}
此结构已通过 Claude 插件校验器的验证。
重要提示： 请注意这里没有 "hooks" 字段。hooks/hooks.json 文件会按约定自动加载。显式添加它会导致重复错误。
贡献者建议
在提交涉及 plugin.json 的更改前：
- 为智能体（Agents）使用显式文件路径
- 确保所有组件字段均为数组
- 包含
version字段 - 运行以下命令：
claude plugin validate .claude-plugin/plugin.json
如有疑问，宁可繁琐也不要为了方便而导致解析失败。
为什么存在此文件
此仓库被广泛 Fork 并作为参考实现。
在此记录校验器的奇特行为（quirks）是为了：
- 防止重复出现的问题
- 减少贡献者的挫败感
- 随着生态系统的演进保持插件的稳定性
如果校验器规则发生变化，请首先更新此文档。