Claude Code 的工程化落地：插件（Plugin）篇

写代码写久了就会发现，团队里最容易沉淀下去的不是代码，而是那些被反复验证过的流程：代码审查怎么查、部署怎么推、脚手架怎么生成。这些东西抽象出来，就是 Claude Code 的插件。插件的本质是复用------当团队需要使用成熟且验证过的 commands 和 Skill 等时，直接装一个插件，而不是从头再开发一遍。

一、插件是什么

一个插件，本质上就是把你在 .claude/ 下攒下来的那套配置（commands、agents、hooks、skills）打包成一个可发布、可安装的单元。目录结构和你本地的 .claude/ 基本一致，区别在于多了一个入口文件和市场配置文件。

dev-toolkit/
├── .claude-plugin/
│   ├── marketplace.json # 插件市场信息
│   └── plugin.json      # 插件入口文件
├── .mcp.json            # mcp 配置
├── .gitignore           # 忽略文件
├── README.md            # 插件说明文档
├── commands/
│   ├── review.md        # /review --- 对齐 CLAUDE.md 全审查清单
│   ├── deploy.md        # /deploy --- 匹配 deploy.sh (git pull → build:staging → pm2)
│   └── new-page.md      # /new-page --- 生成 page.tsx+fetch.ts+store.tsx+scss 骨架
├── agents/
│   ├── code-reviewer.md  # Server Component/Zustand/px-vw/JSBridge/httpv2 逐项检查
│   └── security-scanner.md # XSS·敏感泄露·JSBridge注入·小程序安全·npm audit
├── hooks/
│   ├── hooks.json        # Stop 门禁 + PreToolUse(Bash) 高危拦截
│   ├── quality-gate.mjs  # next lint + type-check 双检查
│   └── guard-dangerous-bash.mjs  # rm -rf / git push -f / pm2 delete
└── skills/
    └── react-patterns/SKILL.md

其中最关键的是 .claude-plugin/plugin.json，它是插件的入口，描述名称、版本、作者、依赖等信息，作用类似 npm 的 package.json。而 marketplace.json 是插件市场的入口清单，负责把你的 Git 仓库「注册成一个可被添加的市场源」。

skills、mcp 这些组件，前面几篇文章已经详细介绍过了，这里不再展开。

二、plugin.json 与 marketplace.json

plugin.json

{
  "name": "dev-toolkit",
  "version": "0.1.0",
  "description": "开发工具集：代码审查、自动部署、页面脚手架、安全扫描、质量门禁，适配 Next.js 14 + Zustand + SCSS Modules 技术栈。",
  "author": {
    "name": "libo",
    "email": "you@example.com"
  },
  "homepage": "https://your-private-git.example.com/your-org/dev-toolkit",
  "repository": "https://your-private-git.example.com/your-org/dev-toolkit.git",
  "license": "UNLICENSED",
  "keywords": [
    "h5"
  ]
}

字段说明：

字段	必需	说明
name	是	插件唯一标识，安装时使用
version	是	语义化版本号
description	是	简短描述，显示在市场中
author	否	作者或团队名称
repository	否	源代码仓库地址
license	否	开源协议
keywords	否	搜索关键词

marketplace.json

{
  "name": "h5-dev-toolkit",          // 市场源名称（必填），用于 `marketplace add/remove/list` 引用的标识符
  "description": "H5 项目通用 Claude Code 插件市场",  // 市场的描述（可选，建议填）
  "owner": {                         // 所有者信息（可选）
    "name": "libo02"                 // 作者/组织名
  },
  "plugins": [                       // 本市场提供的插件列表（必填，至少一项）
    {
      "name": "h5-dev-toolkit",       // 插件名（必填），安装时写 `claude plugin install <此名>`
      "source": "./",                 // 插件代码相对仓库根目录的路径（必填）；"." 表示仓库根即插件根
      "description": "...",           // 插件描述（可选）
      "version": "1.0.0"              // 插件版本（可选）
    }
  ]
}

三、私服插件的发布与安装

Claude Code 插件通过 marketplace 机制管理：先把 Git 仓库添加为插件源，再安装插件。下面以我的插件 dev-toolkit 为例。

1. 添加插件源

前提：确保 .claude-plugin/marketplace.json 和 .claude-plugin/plugin.json 已提交并推送到远程仓库。

claude plugin marketplace add <git-repo-url>

如需限制仅在当前项目可用，加 --scope project（默认 user）：

claude plugin marketplace add <git-repo-url> --scope project

如果插件位于更大的 Monorepo 子目录中，可用 --sparse 只检出相关目录：

claude plugin marketplace add <git-repo-url> --sparse plugin/dev-toolkit

2. 安装插件

推荐用 --scope project 把插件限定到某个项目，启用配置会写入该项目的 .claude/settings.json，不影响其他项目：

cd /path/to/your-project
claude plugin install dev-toolkit --scope project

其他作用域：

claude plugin install dev-toolkit                 # 默认 user（本机所有项目）
claude plugin install dev-toolkit --scope local   # 仅当前目录

安装完成后需 重启 Claude Code ，再执行 claude plugin list 验证。

3. 更新插件

claude plugin update dev-toolkit

指定项目更新：

claude plugin update dev-toolkit@dev-toolkit -s project

更新后同样需要重启 Claude Code 才能生效。

如果更新后仍是旧版（常见于缓存未刷新），先强制刷新源 claude plugin marketplace update dev-toolkit，再重跑 update。

四、删除 / 卸载

关键：插件名带 @源名 后缀，且 scope 必须匹配

Claude Code 内部以 插件名@源名 作为唯一标识（本插件即 dev-toolkit@dev-toolkit）。

# project 作用域（本项目安装方式）
claude plugin remove dev-toolkit@dev-toolkit -s project

# user 作用域
claude plugin remove dev-toolkit@dev-toolkit -s user

手动兜底清理（命令仍失败时）

当插件因 plugin.json 配置错误被禁用、导致 remove 异常时，可手动删干净：

# 1. 删除缓存
rm -rf ~/.claude/plugins/cache/dev-toolkit

# 2. 删除项目级启用配置（project 作用域）
rm -f <你的项目>/.claude/settings.json

# 3. 清空注册表残留条目
#    编辑 ~/.claude/plugins/installed_plugins.json，把 "plugins" 置为 {} 后保存

移除插件源

claude plugin marketplace remove dev-toolkit

源名称可通过 claude plugin marketplace list 查看。

五、已知坑位（排查记录）

做插件这块踩过的坑，先记下来，免得后面团队里有人再撞一遍：

• plugin add 不存在 ：当前 CLI 没有 claude plugin add 子命令，正确流程是 marketplace add + install。
• 缺少 marketplace.json ：claude plugin marketplace add <git> 会克隆仓库解析 .claude-plugin/marketplace.json，仓库根目录必须有此文件，否则报 Marketplace file not found。
• hooks 字段重复加载 ：hooks/hooks.json 会被 Claude Code 自动加载，不要 在 plugin.json 里再写 "hooks": "./hooks/hooks.json"，否则报 Duplicate hooks file detected 并导致插件被 disabled。标准目录（commands/、agents/、skills/、hooks/）均自动扫描，无需在 plugin.json 显式声明。
• 卸载无效 ：裸名 remove dev-toolkit 匹配不到，必须用 dev-toolkit@dev-toolkit 且指定正确的 --scope。
• 缓存不刷新 ：更新后若仍是旧版，先 claude plugin marketplace update dev-toolkit 强制拉取远程最新提交。

Mac 下插件的存储位置

• 存储位置：/Users/macos/.claude/plugins/cache/dev-toolkit/dev-toolkit/1.0.0/
• 注册位置：/Users/macos/.claude/plugins/installed_plugins.json

总结

回过头看，插件的整套流程其实就是一句话：把你本地反复打磨好的组件，发布到私服，再到其他项目里一键安装。说到底，是组件的复用和知识的沉淀。

写到这里，Claude Code 的工程化落地系列就告一段落了。后面打算手搓一个简单的模型。祝大家在 AI 时代里，一路顺风。