这是一个面向 Claude Code 的插件注册表诊断与修复技能,主要解决上游 issue #14202 所述问题:在某项目以 --scope project 安装插件后,其他项目在 Marketplaces 视图中仍错误显示为“(installed)”,导致无法跨项目安装同一插件。原因是注册表 ~/.claude/plugins/installed_plugins.json 为项目级安装保存了 projectPath,而 Marketplaces 视图只检查插件键是否存在,安装命令随后误判插件已存在。
适用场景包括:修复插件注册表损坏、排查项目作用域与全局作用域插件问题、清理孤立插件条目、解决“plugin already installed”错误、手动检查注册表 JSON。若需要全面健康检查、插件相关性审计、仅做设置校验或仅查看已安装插件,应改用 /health:check、/health:audit 等其他命令。
使用方式:命令为 /health:plugins,参数支持 --fix(应用修复,会先确认)、--dry-run(仅展示将修复的内容)、--plugin <name>(仅检查或修复指定插件)。执行分步进行:先运行诊断脚本 check-registry.sh,参数为 --home-dir "$HOME" --project-dir "$(pwd)",可附加 [--plugin <name>] [--verbose];解析 STATUS=、PLUGIN_COUNT=、ORPHANED_ENTRIES= 与 ISSUES: 行并生成结构化报告;若带 --fix,则运行 fix-registry.sh,参数同样包含 --home-dir 与 --project-dir,可加 --plugin 与 --dry-run。修复脚本会在修改前于 ~/.claude/plugins/installed_plugins.json.backup.<UTC-timestamp> 创建时间戳备份,校验生成 JSON,出错时安全中止,并回读 STATUS=、REMOVED=、REMOVED_COUNT=、BACKUP_PATH=。若输出 SETTINGS_CHEZMOI_MANAGED=true,需转达 WARNING:被编辑的 ~/.claude/settings.json 由 chezmoi 管理,下次 chezmoi apply 会还原,除非同时从 chezmoi 源移除同一键(见 SETTINGS_CHEZMOI_SOURCE=)。修复后需重新运行诊断确认问题数下降,并重启 Claude Code 生效。
注册表结构为 version 2,plugins 下以 "plugin-name@marketplace-name" 为键,条目包含 scope、projectPath、installPath、version、installedAt、lastUpdated、gitCommitSha;scope 为 project 时带 projectPath 且仅在该项目生效,为 user 时无 projectPath 全局生效。若自动修复失败,可手动编辑注册表:删除 projectPath 使其全局化、修改 projectPath 为当前项目路径,或新增不同键的条目后重启。