plugin-registry

Claude Code 插件注册表

用于理解和排查 Claude Code 插件注册表问题的专业知识。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他内容……
插件显示“已安装”，但无法正常工作	设置新插件（使用 /configure:claude-plugins）
需要了解插件作用域	配置插件权限（使用 settings-configuration 技能）
修复孤立的注册表条目	使用插件创建工作流（使用 github-actions-plugin）
调试安装失败

注册表位置

插件注册表存储在：

~/.claude/plugins/installed_plugins.json

此文件会跟踪所有项目中已安装的插件。

注册表结构（v2）

{
  "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" 或 "user"（全局）
projectPath	仅限项目	插件处于活动状态的目录
installPath	是	已安装插件文件的缓存路径
version	是	已安装的版本
installedAt	是	安装时间的 ISO 时间戳
lastUpdated	是	上次更新时间的 ISO 时间戳
gitCommitSha	是	已安装版本的 Git 提交

安装作用域

用户作用域（全局，默认）

/plugin install my-plugin@marketplace

• 注册表条目中为 "scope": "user"
• 没有 projectPath 字段
• 在所有项目中均可用

项目作用域

/plugin install my-plugin@marketplace --scope project

• 注册表条目中为 "scope": "project"
• projectPath 设置为安装目录
• 仅应在该项目中处于活动状态
• Bug #14202：在其他项目中仍会显示为“已安装”

已知问题：#14202

问题：项目作用域的插件被错误地显示为全局已安装。

根本原因：projectPath 检查不一致：

操作	是否检查 projectPath？	结果
Marketplace 中的“（已安装）”	否	在所有位置都显示为已安装
/plugin install	否	拒绝安装
已安装标签页列表	是	正确筛选

症状：

1. 插件在 Marketplace 视图中显示“（已安装）”勾选标记
2. /plugin install 提示“已安装”
3. 插件未出现在当前项目的“已安装”标签页中
4. 插件在当前项目中实际上无法正常工作

解决方法：手动编辑注册表，为当前项目添加一条记录。

手动操作注册表

查看注册表

jq . ~/.claude/plugins/installed_plugins.json

列出所有插件

jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json

查找项目作用域的插件

jq '.plugins | to_entries[] | .value[] | select(.scope == "project") | {projectPath, version}' ~/.claude/plugins/installed_plugins.json

查找孤立条目

使用 Read 工具读取 ~/.claude/plugins/installed_plugins.json，然后对每个 projectPath 执行 test -d 检查。

备份注册表

cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup

修复注册表问题

移除孤立条目

1. 使用 Read 工具读取 ~/.claude/plugins/installed_plugins.json
2. 使用 cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup 进行备份
3. 从 plugins 对象中移除孤立条目
4. 使用 Write 工具写入更新后的 JSON

为当前项目添加条目

1. 使用 Read 工具读取注册表
2. 在该插件的数组中添加一条新记录，并设置 scope: "project" 和当前的 projectPath
3. 使用 Write 工具写入更新后的 JSON

将项目作用域转换为用户（全局）作用域

1. 使用 Read 工具读取注册表
2. 将 "scope": "project" 更改为 "scope": "user"，并移除 projectPath
3. 使用 Write 工具写入更新后的 JSON

项目设置集成

项目作用域的插件还需要在 .claude/settings.json 中添加条目：

{
  "enabledPlugins": [
    "plugin-name@marketplace"
  ]
}

否则，即使项目作用域的插件已正确注册，也不会加载。

故障排查清单

1. 插件显示已安装，但无法使用

   • 检查 projectPath 是否与当前目录匹配
   • 检查 .claude/settings.json 中的 enabledPlugins
   • 运行 /health:plugins 进行诊断

2. 无法安装插件（已安装）

   • 检查注册表中是否已有对应条目
   • 检查条目中的 projectPath 是否不同
   • 使用 /health:plugins --fix 或手动编辑

3. 插件在一个项目中可用，但在另一个项目中不可用

   • 可能是项目范围的插件
   • 每个项目都需要单独的注册表条目
   • 或将其转换为全局范围

4. 注册表文件已损坏

   • 如果有备份，请从备份恢复
   • 或删除并重新安装插件
   • 位置：~/.claude/plugins/installed_plugins.json

Agent 优化

上下文	命令
查看注册表	jq -c . ~/.claude/plugins/installed_plugins.json
列出插件	jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json
检查指定插件	jq '.plugins."name@market"' ~/.claude/plugins/installed_plugins.json
项目插件	jq '.plugins | to_entries[] | .value[] | select(.scope=="project")' ~/.claude/plugins/installed_plugins.json

快速参考

注册表路径

~/.claude/plugins/installed_plugins.json

键格式

{plugin-name}@{marketplace-name}

范围指示符

• "scope": "project" + projectPath → 项目范围
• "scope": "user" → 全局（用户范围）

编辑后

始终重启 Claude Code，使注册表更改生效。