health-plugins

/health:plugins

诊断并修复 Claude Code 插件注册表的问题。此命令专门处理问题 #14202：项目级插件被错误地显示为全局安装。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方法……
修复插件注册表损坏（问题 #14202）	全面健康检查（使用 /health:check）
诊断项目级与全局插件问题	审查插件是否相关（使用 /health:audit）
清理孤立的插件条目	仅需验证设置
解决“插件已安装”错误	Agentic 优化审计（使用 /health:agentic-audit）
手动检查注册表 JSON	只需查看已安装的插件（读取注册表文件）

上下文

• 当前项目：!pwd
• 当前项目包含插件：!find . -maxdepth 2 -path '*/.claude-plugin/plugin.json' -type f
• 当前项目存在设置文件：!find . -maxdepth 1 -name '.claude/settings.json'
• 项目插件目录：!find . -maxdepth 1 -type d -name '.claude-plugin'

背景：问题 #14202

在一个项目中使用 --scope project 安装插件后，其他项目的 Marketplaces 视图会错误地将该插件显示为“（已安装）”。这是因为：

1. ~/.claude/plugins/installed_plugins.json 中的插件注册表会为项目级安装存储 projectPath
2. Marketplaces 视图只检查插件键是否存在，不会检查插件是否安装在当前项目中
3. 安装命令会拒绝安装，因为它认为该插件已存在

影响：用户无法在多个项目中以项目级隔离方式安装同一插件。

参数

从 $ARGUMENTS 中解析以下参数：

参数	描述
--fix	修复插件注册表
--dry-run	显示将要修复的内容，但不做任何更改
--plugin <name>	仅检查／修复指定插件

执行

运行以下脚本来执行插件注册表诊断。如果 $ARGUMENTS 中指定了 --plugin <name>，请传递该参数。

步骤 1：诊断注册表

bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--verbose]

解析输出中的 STATUS=、PLUGIN_COUNT=、ORPHANED_ENTRIES= 和 ISSUES: 行。=== PLUGINS === 部分会列出每个已安装插件的范围、版本、来源和 projectPath。

步骤 2：报告结果

打印结构化诊断报告，总结：

1. 注册表位置、有效性和插件数量（总数／全局／项目级）
2. 孤立条目（projectPath 目录不存在），并说明严重程度和建议的修复方法
3. 已在设置中启用、但不在注册表中的插件
4. 来自其他项目的插件（仅供参考，使用 --verbose 时显示）

以 ISSUES: 行作为问题的权威列表。

步骤 3：应用修复（如果指定 --fix）

如果 $ARGUMENTS 中包含 --fix：

1. 通过 AskUserQuestion 向用户确认要删除哪些孤立插件，除非同时指定了 --dry-run。

2. 运行修复脚本：

   bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--dry-run]
   

   修改注册表前，脚本会在 ~/.claude/plugins/installed_plugins.json.backup.<UTC-timestamp> 创建带时间戳的备份，验证生成的 JSON，并在发生任何错误时安全中止。

3. 解析 STATUS=、REMOVED=、REMOVED_COUNT= 和 BACKUP_PATH= 行，并报告所做的更改。

4. 提示持久性警告。 如果输出包含 SETTINGS_CHEZMOI_MANAGED=true，请将 WARNING= 行转告用户：编辑后的 ~/.claude/settings.json 由 chezmoi 管理，因此除非同时从 chezmoi 源文件中移除相同的键（显示为 SETTINGS_CHEZMOI_SOURCE=），否则下次运行 chezmoi apply 时修复会被还原。

步骤 4：处理“当前项目需要插件”的情况

当注册表中存在某个插件，但其 projectPath 与当前项目不同，而用户希望该插件在当前项目中可用时，请使用 AskUserQuestion 进行确认，然后：

1. 使用 Edit 工具，在 .claude/settings.json 的 enabledPlugins 下添加一个新条目。
2. 提醒用户通过 Claude Code UI 运行 /plugin install，以便正确注册到注册表中。

步骤 5：验证修复

应用修复后，重新运行步骤 1，并确认问题数量已减少。提醒用户重启 Claude Code，使更改生效。

注册表结构参考

{
  "version": 2,
  "plugins": {
    "plugin-name@marketplace-name": [
      {
        "scope": "project",
        "projectPath": "/path/to/project",
        "installPath": "~/.claude/plugins/cache/marketplace/plugin-name/1.0.0",
        "version": "1.0.0",
        "installedAt": "2024-01-15T10:30:00Z",
        "lastUpdated": "2024-01-15T10:30:00Z",
        "gitCommitSha": "abc123"
      }
    ]
  }
}

作用域类型：

• "scope": "project" — 包含 projectPath，仅在该项目中生效
• "scope": "user" — 不包含 projectPath，全局生效

手动解决方法

如果自动修复失败，用户可以手动编辑 ~/.claude/plugins/installed_plugins.json：

1. 在编辑器中打开文件
2. 找到插件条目
3. 执行以下操作之一：
   • 移除 projectPath，使其全局生效
   • 将 projectPath 更改为当前项目路径
   • 使用不同的键为当前项目添加一个新条目
4. 保存并重启 Claude Code

Agent 优化

上下文	命令
插件注册表诊断	/health:plugins
修复注册表问题	/health:plugins --fix
试运行模式	/health:plugins --dry-run
仅诊断（脚本）	bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"
仅修复（脚本）	bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"

标志

标志	说明
--fix	应用修复（需确认提示）
--dry-run	显示将要修复的内容，但不做任何更改
--plugin <name>	指定要操作的插件

另请参阅

• /health:check - 完整诊断扫描
• /health:settings - 设置文件验证
• 问题 #14202 - 上游 Bug 报告