mirror of
https://github.com/sweetwisdom/everything-claude-code-zh.git
synced 2026-03-21 22:10:09 +00:00
chore: sync with upstream ae2c063 + update zh translations
This commit is contained in:
xuxiang
@@ -1,22 +1,22 @@
|
||||
# 插件清单模式（Manifest Schema）注意事项
|
||||
# 插件清单模式（Plugin Manifest Schema）说明
|
||||
|
||||
本文档记录了 Claude Code 插件清单校验器中**未见于文档但强制执行的约束**。
|
||||
本文档记录了 Claude Code 插件清单校验器（Validator）中**未公开但强制执行的约束条件**。
|
||||
|
||||
这些规则基于真实的安装失败案例、校验器行为以及与已知可用插件的对比。
|
||||
设置这些规则是为了防止隐性故障和重复的回归问题。
|
||||
这些规则基于真实的安装失败案例、校验器行为分析以及与已知可用插件的对比。
|
||||
它们的存在是为了防止隐性破坏（silent breakage）和重复出现的回归（regressions）问题。
|
||||
|
||||
如果你编辑 `.claude-plugin/plugin.json`，请先阅读本文。
|
||||
如果你需要编辑 `.claude-plugin/plugin.json`，请务必先阅读本文。
|
||||
|
||||
---
|
||||
|
||||
## 摘要（优先阅读）
|
||||
|
||||
Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
它执行了一些在公开模式（Schema）参考文档中未完全说明的规则。
|
||||
Claude 插件清单校验器非常**严格且具有确定性**。
|
||||
它强制执行了一些在公共模式（Schema）引用中未完全记录的规则。
|
||||
|
||||
最常见的失败模式是：
|
||||
|
||||
> 清单看起来很合理，但校验器以模糊的错误拒绝它，例如：
|
||||
> 清单看起来很合理，但校验器拒绝了它，并给出模糊的错误提示，例如
|
||||
> `agents: Invalid input`
|
||||
|
||||
本文档将解释其原因。
|
||||
@@ -25,11 +25,11 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
|
||||
## 必填字段
|
||||
|
||||
### `version`（强制性）
|
||||
### `version`（强制要求）
|
||||
|
||||
即便在某些示例中被省略，校验器也要求必须包含 `version` 字段。
|
||||
校验器要求必须包含 `version` 字段，即使在某些示例中省略了它。
|
||||
|
||||
如果缺失，在应用市场安装或 CLI 校验期间可能会失败。
|
||||
如果缺失该字段，在应用市场安装或 CLI 校验期间可能会失败。
|
||||
|
||||
示例：
|
||||
|
||||
@@ -50,9 +50,9 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
* `skills`
|
||||
* `hooks`（如果存在）
|
||||
|
||||
即便只有一个条目，**也不接受字符串（Strings）**。
|
||||
即使只有一个条目，**也不接受字符串（Strings）类型**。
|
||||
|
||||
### 错误写法（Invalid）
|
||||
### 错误示例（Invalid）
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -60,7 +60,7 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
}
|
||||
```
|
||||
|
||||
### 正确写法（Valid）
|
||||
### 正确示例（Valid）
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -68,17 +68,17 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
}
|
||||
```
|
||||
|
||||
这适用于所有组件路径字段。
|
||||
这一规则一致适用于所有组件路径字段。
|
||||
|
||||
---
|
||||
|
||||
## 路径解析规则（至关重要）
|
||||
## 路径解析规则（关键）
|
||||
|
||||
### Agents 必须使用显式文件路径
|
||||
|
||||
校验器**不接受 `agents` 使用目录路径**。
|
||||
校验器**不接受 `agents` 字段使用目录路径**。
|
||||
|
||||
即便如下写法也会失败：
|
||||
即使是以下写法也会失败：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -86,7 +86,7 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
}
|
||||
```
|
||||
|
||||
相反，你必须显式列举智能体（Agent）文件：
|
||||
相反，你必须显式枚举智能体（Agent）文件：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -100,21 +100,58 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
|
||||
这是校验错误最常见的来源。
|
||||
|
||||
### Commands 和 Skills
|
||||
### 命令（Commands）与技能（Skills）
|
||||
|
||||
* `commands` 和 `skills` 仅在**包裹在数组中**时才接受目录路径。
|
||||
* 使用显式文件路径是最安全且面向未来的做法。
|
||||
* `commands` 和 `skills` **仅在包裹在数组中时**接受目录路径。
|
||||
* 显式文件路径是最安全且最能兼容未来的做法。
|
||||
|
||||
---
|
||||
|
||||
## 校验器行为备注
|
||||
## 校验器行为注意事项
|
||||
|
||||
* `claude plugin validate` 比某些应用市场预览更严格。
|
||||
* 校验可能在本地通过，但如果路径含义模糊，则在安装时可能会失败。
|
||||
* 错误通常很笼统（`Invalid input`），且不指示根本原因。
|
||||
* `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` **绝不能**被声明。
|
||||
|
||||
---
|
||||
|
||||
@@ -123,16 +160,17 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
这些看起来正确但会被拒绝：
|
||||
|
||||
* 使用字符串值而非数组
|
||||
* 为 `agents` 提供目录数组
|
||||
* 在 `agents` 中使用目录数组
|
||||
* 缺失 `version`
|
||||
* 依赖推断路径
|
||||
* 假设应用市场的行为与本地校验一致
|
||||
* 假设应用市场行为与本地校验一致
|
||||
* **添加 `"hooks": "./hooks/hooks.json"`** —— 按约定自动加载，会导致重复错误
|
||||
|
||||
不要耍小聪明。请保持显式。
|
||||
不要尝试“取巧”，请保持显式声明。
|
||||
|
||||
---
|
||||
|
||||
## 最小已知有效示例
|
||||
## 最小已知可用示例
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -146,35 +184,37 @@ Claude 插件清单校验器**极其严格且具有主观性**。
|
||||
}
|
||||
```
|
||||
|
||||
该结构已通过 Claude 插件校验器的验证。
|
||||
此结构已通过 Claude 插件校验器的验证。
|
||||
|
||||
**重要提示：** 请注意这里**没有** `"hooks"` 字段。`hooks/hooks.json` 文件会按约定自动加载。显式添加它会导致重复错误。
|
||||
|
||||
---
|
||||
|
||||
## 对贡献者的建议
|
||||
## 贡献者建议
|
||||
|
||||
在提交涉及 `plugin.json` 的更改之前：
|
||||
在提交涉及 `plugin.json` 的更改前：
|
||||
|
||||
1. 为 agents 使用显式文件路径
|
||||
1. 为智能体（Agents）使用显式文件路径
|
||||
2. 确保所有组件字段均为数组
|
||||
3. 包含 `version`
|
||||
4. 运行：
|
||||
3. 包含 `version` 字段
|
||||
4. 运行以下命令：
|
||||
|
||||
```bash
|
||||
claude plugin validate .claude-plugin/plugin.json
|
||||
```
|
||||
|
||||
如有疑问，宁可繁琐也不要追求便利。
|
||||
如有疑问，宁可繁琐也不要为了方便而导致解析失败。
|
||||
|
||||
---
|
||||
|
||||
## 为什么存在此文件
|
||||
|
||||
此仓库被广泛 fork 并用作参考实现。
|
||||
此仓库被广泛 Fork 并作为参考实现。
|
||||
|
||||
在此记录校验器的特性：
|
||||
在此记录校验器的奇特行为（quirks）是为了：
|
||||
|
||||
* 防止重复出现的问题
|
||||
* 减少贡献者的挫败感
|
||||
* 随着生态系统的演进保持插件的稳定性
|
||||
|
||||
如果校验器发生变化，请首先更新本文档。
|
||||
如果校验器规则发生变化，请首先更新此文档。
|
||||
|
||||
5
.claude-plugin/README.md
Normal file
5
.claude-plugin/README.md
Normal file
@@ -0,0 +1,5 @@
|
||||
### 插件清单注意事项（Plugin Manifest Gotchas）
|
||||
|
||||
如果你计划编辑 `.claude-plugin/plugin.json`，请注意 Claude 插件验证器（plugin validator）强制执行了一些**未公开但严格的约束**，这些约束可能导致安装失败并显示模糊的错误（例如，`agents: Invalid input`）。特别是，组件字段必须是数组（arrays），`agents` 必须使用明确的文件路径而非目录，且为了实现可靠的验证和安装，必须包含 `version` 字段。
|
||||
|
||||
这些约束在公开示例中并不明显，且在过去曾多次导致安装失败。它们在 `.claude-plugin/PLUGIN_SCHEMA_NOTES.md` 中有详细记录，在对插件清单（plugin manifest）进行任何更改之前，应仔细阅读该文档。
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "everything-claude-code",
|
||||
"version": "1.0.0",
|
||||
"description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, commands, and rules evolved over 10+ months of intensive daily use",
|
||||
"version": "1.2.0",
|
||||
"description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, and rules evolved over 10+ months of intensive daily use",
|
||||
"author": {
|
||||
"name": "Affaan Mustafa",
|
||||
"url": "https://x.com/affaanmustafa"
|
||||
@@ -14,7 +14,6 @@
|
||||
"agents",
|
||||
"skills",
|
||||
"hooks",
|
||||
"commands",
|
||||
"rules",
|
||||
"tdd",
|
||||
"code-review",
|
||||
@@ -23,8 +22,7 @@
|
||||
"automation",
|
||||
"best-practices"
|
||||
],
|
||||
"commands": ["./commands/"],
|
||||
"skills": ["./skills/"],
|
||||
"skills": ["./skills/", "./commands/"],
|
||||
"agents": [
|
||||
"./agents/architect.md",
|
||||
"./agents/build-error-resolver.md",
|
||||
@@ -38,6 +36,5 @@
|
||||
"./agents/refactor-cleaner.md",
|
||||
"./agents/security-reviewer.md",
|
||||
"./agents/tdd-guide.md"
|
||||
],
|
||||
"hooks": "./hooks/hooks.json"
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user