Back to Details

health-plugins

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/health:plugins

/health:plugins

Diagnose and fix issues with the Claude Code plugin registry. This command specifically addresses issue #14202 where project-scoped plugins incorrectly appear as globally installed.
诊断并修复Claude Code插件注册表的问题。此命令专门解决问题#14202：项目范围的插件错误地显示为全局安装。

When to Use This Skill

何时使用此技能

Use this skill when...Use another approach when...
Fixing plugin registry corruption (issue #14202)Comprehensive health check (use 
/health:check
)
Diagnosing project-scope vs global plugin issuesAuditing plugins for relevance (use 
/health:audit
)
Cleaning up orphaned plugin entriesSettings validation only needed
Resolving "plugin already installed" errorsAgentic optimization audit (use 
/health:agentic-audit
)
Manually inspecting registry JSONJust viewing installed plugins (read registry file)
适合使用此技能的场景...适合使用其他方法的场景...
修复插件注册表损坏（问题#14202）全面健康检查（使用
/health:check
）
诊断项目范围与全局插件的问题审核插件相关性（使用
/health:audit
）
清理孤立的插件条目仅需验证设置
解决“插件已安装”错误智能体优化审核（使用
/health:agentic-audit
）
手动检查注册表JSON仅查看已安装插件（直接读取注册表文件）

Context

上下文

  • Current project: !
    pwd
  • Plugin registry exists: !
    find ~/.claude/plugins -maxdepth 1 -name 'installed_plugins.json' 2>/dev/null
  • Project settings exists: !
    find . -maxdepth 1 -name '.claude/settings.json' 2>/dev/null
  • Project plugins dir: !
    find . -maxdepth 1 -type d -name \'.claude-plugin\' 2>/dev/null
  • 当前项目: !
    pwd
  • 插件注册表是否存在: !
    find ~/.claude/plugins -maxdepth 1 -name 'installed_plugins.json' 2>/dev/null
  • 项目设置是否存在: !
    find . -maxdepth 1 -name '.claude/settings.json' 2>/dev/null
  • 项目插件目录: !
    find . -maxdepth 1 -type d -name \'.claude-plugin\' 2>/dev/null

Background: Issue #14202

背景：问题#14202

When a plugin is installed with 
--scope project
in one project, other projects incorrectly show the plugin as "(installed)" in the Marketplaces view. This happens because:
  1. The plugin registry at 
    ~/.claude/plugins/installed_plugins.json
    stores 
    projectPath
    for project-scoped installs
  2. The Marketplaces view only checks if a plugin key exists, not whether it's installed for the current project
  3. The install command refuses to install because it thinks the plugin already exists
Impact: Users cannot install the same plugin across multiple projects with project-scope isolation.
当在某个项目中使用
--scope project
参数安装插件时，其他项目会在市场视图中错误地显示该插件为“已安装”。原因如下：
  1. 位于
    ~/.claude/plugins/installed_plugins.json
    的插件注册表会为项目范围的安装记录
    projectPath
  2. 市场视图仅检查插件密钥是否存在，而不验证它是否为当前项目安装的
  3. 安装命令会拒绝安装，因为它认为插件已存在
影响: 用户无法在多个项目中以项目范围隔离的方式安装同一个插件。

Parameters

参数

ParameterDescription
--fix
Apply fixes to the plugin registry
--dry-run
Show what would be fixed without making changes
--plugin <name>
Check/fix a specific plugin only
参数描述
--fix
对插件注册表应用修复
--dry-run
显示会修复的内容但不实际修改
--plugin <name>
仅检查/修复指定插件

Execution

执行步骤

Execute this plugin registry diagnostic:
执行此插件注册表诊断：

Step 1: Read the plugin registry

步骤1：读取插件注册表

  1. Read 
    ~/.claude/plugins/installed_plugins.json
  2. Parse each plugin entry to extract: plugin name and source, whether it has a 
    projectPath
    (project-scoped), and the installation timestamp and version
  1. 读取
    ~/.claude/plugins/installed_plugins.json
  2. 解析每个插件条目，提取：插件名称和来源、是否包含
    projectPath
    （项目范围）、安装时间戳和版本

Step 2: Identify issues in the registry

步骤2：识别注册表中的问题

Check for these issue types:
Issue TypeDetectionSeverity
Orphaned projectPath
projectPath
directory doesn't exist		WARN
Missing from current projectPlugin has different 
projectPath
than current directory		INFO
Duplicate scopesSame plugin installed both globally and per-projectWARN
Invalid entryMissing required fields or malformed dataERROR
检查以下问题类型：
问题类型检测方式严重程度
孤立的projectPath
projectPath
对应的目录不存在		警告
当前项目中缺失插件的
projectPath
与当前目录不同		信息
重复范围同一插件同时安装了全局和项目版本警告
无效条目缺少必填字段或数据格式错误错误

Step 3: Report findings

步骤3：报告检测结果

Print a structured diagnostic report listing all installed plugins with scope and status, followed by issues found with severity, details, and suggested fixes.
打印结构化诊断报告，列出所有已安装插件的范围和状态，然后按严重程度列出发现的问题、详细信息和建议修复方案。

Step 4: Apply fixes (if --fix flag)

步骤4：应用修复（如果使用--fix参数）

For each issue, apply the appropriate fix:
  1. Orphaned projectPath -- remove the orphaned entry from installed_plugins.json
  2. Plugin needed in current project -- ask user which plugins to install, add new entry with current 
    projectPath
    , update 
    .claude/settings.json
    with 
    enabledPlugins
    if needed
Before making changes:
  1. Create backup: 
    ~/.claude/plugins/installed_plugins.json.backup
  2. Validate JSON after modifications
  3. Report what was changed
针对每个问题，应用相应的修复：
  1. 孤立的projectPath -- 从installed_plugins.json中删除孤立条目
  2. 当前项目需要的插件 -- 询问用户要安装哪些插件，添加带有当前
    projectPath
    的新条目，必要时更新
    .claude/settings.json
    中的
    enabledPlugins
在进行修改前：
  1. 创建备份：
    ~/.claude/plugins/installed_plugins.json.backup
  2. 修改后验证JSON格式
  3. 报告已修改的内容

Step 5: Verify the fix

步骤5：验证修复效果

After applying fixes:
  1. Re-read the registry
  2. Confirm issues are resolved
  3. Remind user to restart Claude Code for changes to take effect
应用修复后：
  1. 重新读取注册表
  2. 确认问题已解决
  3. 提醒用户重启Claude Code以使更改生效

Registry Structure Reference

注册表结构参考

json
{
  "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 types:
  • "scope": "project"
    — has 
    projectPath
    , only active in that project
  • "scope": "user"
    — no 
    projectPath
    , active globally
json
{
  "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
    ，全局生效

Manual Workaround

手动解决方法

If automatic fix fails, users can manually edit 
~/.claude/plugins/installed_plugins.json
:
  1. Open the file in an editor
  2. Find the plugin entry
  3. Either:
    • Remove 
      projectPath
      to make it global
    • Change 
      projectPath
      to current project path
    • Add a new entry with different key for current project
  4. Save and restart Claude Code
如果自动修复失败，用户可以手动编辑
~/.claude/plugins/installed_plugins.json
：
  1. 在编辑器中打开该文件
  2. 找到插件条目
  3. 选择以下操作之一：
    • 删除
      projectPath
      使其变为全局插件
    • 将
      projectPath
      修改为当前项目路径
    • 为当前项目添加一个带有不同密钥的新条目
  4. 保存并重启Claude Code

Agentic Optimizations

智能体优化建议

ContextCommand
Plugin registry diagnostics
/health:plugins
Fix registry issues
/health:plugins --fix
Dry-run mode
/health:plugins --dry-run
Inspect registry
jq '.' ~/.claude/plugins/installed_plugins.json 2>/dev/null
Check specific plugin
jq '.["plugin-name"]' ~/.claude/plugins/installed_plugins.json 2>/dev/null
List orphaned paths
jq -r 'to_entries[] | select(.value.projectPath? and (.value.projectPath | test("."))) | .value.projectPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null
场景命令
插件注册表诊断
/health:plugins
修复注册表问题
/health:plugins --fix
试运行模式
/health:plugins --dry-run
检查注册表
jq '.' ~/.claude/plugins/installed_plugins.json 2>/dev/null
检查指定插件
jq '.["plugin-name"]' ~/.claude/plugins/installed_plugins.json 2>/dev/null
列出孤立路径
jq -r 'to_entries[] | select(.value.projectPath? and (.value.projectPath | test("."))) | .value.projectPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null

Flags

标识

FlagDescription
--fix
Apply fixes (with confirmation prompts)
--dry-run
Show what would be fixed without changes
--plugin <name>
Target a specific plugin
标识描述
--fix
应用修复（带确认提示）
--dry-run
显示会修复的内容但不实际修改
--plugin <name>
目标为指定插件

See Also

另请参阅

  • /health:check
    - Full diagnostic scan
  • /health:settings
    - Settings file validation
  • Issue #14202 - Upstream bug report
  • /health:check
    - 完整诊断扫描
  • /health:settings
    - 设置文件验证
  • Issue #14202 - 上游Bug报告