【Claude基础】插件开发与生产部署:构建可分发的能力包

1. 插件设计理念

1.1 为什么需要插件

前面几篇文章分别讲了 Skills、Hooks、MCP Servers、子代理。用了一段时间你会发现一个问题：这些东西散落在 .claude/ 目录的各个角落。

一个完整的工作流往往需要多个组件配合。拿"代码审查"举例，你可能需要：

• 一个 Skill 定义审查流程和清单
• 一个 Hook 在 PR 提交时自动触发审查
• 一个 MCP Server 连接 GitHub API 拉取 PR 信息
• 一个子代理负责安全扫描
• 若干配置项控制行为细节

这些文件分布在 .claude/skills/、.claude/hooks.json、.mcp.json、.claude/agents/ 等不同位置。你自己用没问题，但要分享给团队其他人就麻烦了——得写一份安装文档，告诉别人"把这个文件复制到这里，那个文件复制到那里，别忘了改这个配置"。

插件就是把这些东西打成一个包。一条命令安装，一条命令卸载，版本可控，配置隔离。

1.2 插件 = 能力的打包单元

一个 Claude Code 插件本质上是以下组件的集合：

插件不要求包含所有组件。一个只有 Skill 的插件也是合法的。但插件的价值在于，它能把多个组件组织成一个有凝聚力的能力单元，统一安装、统一配置、统一版本管理。

1.3 插件 vs 直接配置 .claude/ 目录

1.4 何时该写插件 vs 何时直接配置

经验法则：

直接配置 .claude/ 的场景：

• 项目特有的规范（编码风格、目录结构约定）
• 只在当前仓库生效的 Hook
• 一次性或实验性的工作流

写成插件的场景：

• 需要在多个项目中复用
• 要分享给团队或社区
• 包含多个组件的复杂工作流
• 需要用户自定义配置（API Key、服务地址等）
• 需要版本管理和更新机制

一句话总结：如果你发现自己在第二个项目里复制粘贴 .claude/ 下的文件，就该把它做成插件了。

2. 插件目录结构详解

一个完整的插件目录结构如下：

my-plugin/├── .claude-plugin/│   └── plugin.json          # 必需 — 插件清单文件├── skills/│   ├── review/│   │   └── SKILL.md         # 技能定义│   └── security-scan/│       └── SKILL.md├── agents/│   └── security-auditor.md  # 子代理定义├── commands/│   └── review-pr.md         # 自定义斜杠命令├── hooks/│   └── hooks.json           # 钩子配置├── .mcp.json                # MCP 服务器声明├── .lsp.json                # LSP 集成配置├── settings.json            # 设置覆盖├── bin/│   ├── check-coverage.sh    # 辅助脚本│   └── parse-report.py├── README.md                # 插件文档└── LICENSE

逐个说明每个部分的职责。

2.1 .claude-plugin/plugin.json — 插件清单

这是唯一的必需文件。没有它，目录就不会被识别为插件。它声明了插件的元数据、依赖、配置选项等核心信息。详细字段下一节单独讲。

2.2 skills/ — 技能定义

结构和 .claude/skills/ 完全一致。每个子目录包含一个 SKILL.md 文件，可以附带 templates/ 和 scripts/ 子目录。

插件安装后，这些 Skill 会被注册到 Claude Code 的技能索引中，用户可以通过斜杠命令或自动匹配触发。Skill 的命名空间会自动加上插件前缀，避免和其他插件或用户自定义 Skill 冲突。比如插件名叫 code-review，Skill 名叫 review，实际注册的名字是 code-review:review。

2.3 agents/ — 子代理定义

放置 Markdown 格式的子代理定义文件。每个 .md 文件定义一个子代理的角色、任务边界和工具权限。格式参考第 08 篇的自定义代理部分。

2.4 commands/ — 自定义命令

定义插件提供的斜杠命令。每个 .md 文件对应一个命令。文件名就是命令名——review-pr.md 对应 /review-pr。安装后同样会加上插件前缀，变成 /code-review:review-pr，但如果没有冲突，也可以直接用 /review-pr。

2.5 hooks/hooks.json — 钩子配置

格式和 .claude/hooks.json 一致。插件安装时，这些 Hook 会被合并到用户的 Hook 配置中。插件卸载时自动移除。

{"hooks": {"PostToolUse": [      {"matcher": "git_commit","command": "node ${CLAUDE_PLUGIN_ROOT}/bin/post-commit-check.js"      }    ]  }}

注意 ${CLAUDE_PLUGIN_ROOT} 环境变量——它指向插件的安装路径，后面会详细讲。

2.6 .mcp.json — MCP 服务器声明

声明插件依赖的 MCP 服务器。安装时，这些 MCP 服务器会被添加到用户的 MCP 配置中。

{"mcpServers": {"github-review": {"command": "node","args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp-github.js"],"env": {"GITHUB_TOKEN": "${userConfig.github_token}"      }    }  }}

这里的 ${userConfig.github_token} 引用了用户配置，安装插件时会提示用户输入。

2.7 .lsp.json — LSP 集成

声明插件提供的 LSP（Language Server Protocol）集成。这个在 v2.1.90+ 版本引入，可以让插件为特定语言提供实时诊断能力。

{"lsp": {"security-linter": {"command": "node","args": ["${CLAUDE_PLUGIN_ROOT}/bin/security-lsp.js"],"languages": ["javascript", "typescript"],"diagnosticSeverity": "warning"    }  }}

配置后，Claude Code 在编辑这些语言的文件时会实时接收 LSP 诊断结果，作为上下文信息辅助代码生成。

2.8 settings.json — 设置覆盖

插件可以提供默认的设置覆盖。比如一个安全审查插件可能要求更严格的权限模型：

{"permissions": {"allow": ["Read", "Grep", "Glob"],"deny": ["Edit", "Write", "Bash"]  },"model": "claude-sonnet-4-20250514"}

这些设置只在插件提供的 Skill 和 Agent 执行期间生效，不会影响用户的全局设置。

2.9 bin/ — 辅助脚本

放置 Hook、MCP Server 和 Skill 引用的脚本文件。建议按功能命名，给脚本加上可执行权限。

3. plugin.json 清单详解

plugin.json 是插件的身份证。一个完整的示例：

{"name": "code-review","version": "1.2.0","description": "团队代码审查工作流，含自动化安全扫描和覆盖率检查","author": "your-team","license": "MIT","minCliVersion": "2.1.80","keywords": ["review", "security", "quality"],"userConfig": {"github_token": {"type": "string","description": "GitHub Personal Access Token","required": true,"sensitive": true    },"coverage_threshold": {"type": "number","description": "最低测试覆盖率（百分比）","default": 80    },"auto_approve": {"type": "boolean","description": "低风险变更是否自动通过","default": false    }  },"monitors": {"coverage-watch": {"command": "node ${CLAUDE_PLUGIN_ROOT}/bin/coverage-monitor.js","interval": "5m","events": ["file:save"],"condition": "glob:src/**/*.{ts,js}"    }  },"dependencies": {"plugins": ["mcp-github >= 0.5.0"],"npm": ["@octokit/rest@^7.0.0"],"system": ["git >= 2.30"]  }}

3.1 基础字段

name 的命名规范：只允许小写字母、数字和连字符。这个名字会成为命名空间前缀，影响 Skill 和命令的注册名，所以起名时要考虑简洁性。code-review 比 my-awesome-super-code-review-tool 好得多。

3.2 userConfig — 用户可配置选项

这是插件和直接配置 .claude/ 的关键区别之一。userConfig 让插件在安装时收集用户特定的配置值。

每个配置项支持的属性：

sensitive: true 的配置项（如 API Token、密码）不会明文存储在配置文件里，而是存入操作系统的密钥链（macOS Keychain / Windows Credential Manager / Linux Secret Service）。插件运行时通过 ${userConfig.xxx} 引用，Claude Code 会从密钥链中读取并注入。

安装时的交互流程：

$ claude plugin install code-reviewInstalling code-review@1.2.0...Configuration required:  GitHub Personal Access Token (required, sensitive):  > ghp_xxxxxxxxxxxx  ← 输入后不回显  最低测试覆盖率（百分比） [80]:  > 90  低风险变更是否自动通过 [false]:  > (enter)  ← 使用默认值✓ Installed code-review@1.2.0  1 skill, 1 agent, 1 hook, 1 MCP server registered

用户后续想改配置：

claude plugin config code-review coverage_threshold 85claude plugin config code-review github_token  # 敏感值会提示重新输入

3.3 环境变量

插件运行时可以使用两个特殊环境变量：

CLAUDE_PLUGIN_ROOT 是只读的，指向插件代码本身的安装位置。典型用法是在 Hook 和 MCP 配置中引用脚本：

"command": "node ${CLAUDE_PLUGIN_ROOT}/bin/check.js"

CLAUDE_PLUGIN_DATA 是可写的，用于存放插件运行过程中产生的数据——缓存、日志、临时文件等。这个目录在插件卸载时可以选择是否保留。

// 在插件脚本中使用const dataDir = process.env.CLAUDE_PLUGIN_DATA;const cacheFile = path.join(dataDir, 'review-cache.json');

3.4 monitors — 后台监控（v2.1.105+）

monitors 允许插件注册后台监控任务。和 Hook 不同，Hook 是事件触发的一次性执行，monitors 是持续运行的后台进程。

"monitors": {"type-check": {"command": "npx tsc --watch --noEmit 2>&1 | node ${CLAUDE_PLUGIN_ROOT}/bin/parse-tsc.js","events": ["file:save"],"condition": "glob:src/**/*.ts","debounce": "3s"  }}

监控任务的输出会被注入到 Claude Code 的上下文中。比如上面的配置，每次保存 .ts 文件后 3 秒，TypeScript 编译器的错误输出就会出现在 Claude 的上下文里，它可以主动修复这些错误。

3.5 内联插件（v2.1.80+）

不是所有插件都需要独立的目录。对于简单的功能扩展，可以在 settings.json 中内联定义：

{"plugins": {"inline": [      {"source": "settings","name": "quick-test","version": "0.1.0","skills": {"run-tests": {"description": "运行当前文件的单元测试","command": "pytest ${file} -v --tb=short"          }        }      }    ]  }}

内联插件适合小型、单一功能的场景。当功能变复杂了，再拆成独立插件。

4. 开发与调试流程

4.1 本地开发模式

开发插件时，不需要先安装再测试。用 --plugin-dir 参数直接加载本地目录：

# 加载本地插件目录claude --plugin-dir ./my-plugin# 加载多个插件claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b

这样 Claude Code 启动后就会识别并注册插件中的所有组件。修改插件文件后，不需要重启 Claude Code。

4.2 热重载

在会话中修改了插件的 Skill、Hook 或其他配置后，执行：

/reload-plugins

Claude Code 会重新扫描并加载所有插件，无需退出重进。这个命令在开发迭代时非常有用——改了 SKILL.md，/reload-plugins，立刻生效。

如果只想重载特定插件：

/reload-plugins code-review

4.3 验证

在发布之前，用验证命令检查插件结构和配置：

claude plugin validate ./my-plugin

验证内容包括：

• plugin.json 格式和必需字段
• 版本号是否符合 SemVer 规范
• 引用的文件是否存在（Skill、脚本、模板等）
• Hook 配置语法
• MCP 服务器配置语法
• userConfig 字段定义是否合法
• 依赖声明是否可解析

验证通过会输出插件的摘要信息：

✓ Plugin validation passedcode-review@1.2.0  Skills:    2 (review, security-scan)  Agents:    1 (security-auditor)  Commands:  1 (review-pr)  Hooks:     1 (PostToolUse)  MCP:       1 (github-review)  Config:    3 options (1 sensitive)

4.4 调试技巧

查看插件日志：

# 查看所有插件日志claude plugin logs# 查看特定插件日志claude plugin logs code-review# 实时跟踪claude plugin logs code-review --follow

逐模块测试：

开发复杂插件时，建议按模块分步测试：

1. 先测 Skill：只保留 skills/ 目录和最小 plugin.json，验证 Skill 触发和执行正常
2. 再测 Hook：加入 hooks/hooks.json，手动触发相关事件，验证 Hook 被正确调用
3. 然后测 MCP：加入 .mcp.json，验证 MCP Server 能正常启动和响应
4. 最后测 Agent：加入 agents/，验证子代理能正确执行和返回结果
5. 集成测试：所有组件一起跑，验证组件间的协作

环境变量调试：

在脚本中打印环境变量，确认值是否正确注入：

#!/bin/bashecho"PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}" >&2echo"PLUGIN_DATA: ${CLAUDE_PLUGIN_DATA}" >&2echo"GitHub Token set: $([ -n "${GITHUB_TOKEN}" ] && echo yes || echo no)" >&2

输出到 stderr 不会干扰正常的数据流，同时会被记录到插件日志中。

5. 分发渠道

插件开发完成后，有多种方式分发给用户。

5.1 官方市场

Claude Code 有一个内置的插件市场。发布到市场需要经过审核：

# 提交到市场claude plugin publish ./my-plugin# 用户安装/plugin install code-review

市场插件有几个好处：

• 自动更新通知
• 安全审核
• 下载统计和评价
• 全局搜索可发现

提交审核大约需要 1-3 个工作日。审核内容包括安全性检查（不执行恶意代码）、权限合理性（不申请过多权限）和基本功能验证。

5.2 GitHub 仓库

最灵活的方式，适合团队内部使用或开源项目：

# 从 GitHub 安装claude plugin install github:username/code-review-plugin# 指定版本/分支/tagclaude plugin install github:username/code-review-plugin@v1.2.0claude plugin install github:username/code-review-plugin@main

安装过程会 clone 仓库到本地插件目录，后续用 claude plugin update 拉取最新版本。

5.3 npm 包

如果你的插件包含 Node.js 脚本（MCP Server、Hook 处理器等），发布为 npm 包是一个自然的选择：

# 发布到 npmcd my-plugin && npm publish# 用户安装claude plugin install npm:@your-scope/code-review

npm 分发的优势是可以利用 npm 生态的版本管理、依赖解析和发布工具链。

5.4 本地路径

团队内部共享最简单的方式——直接指向本地目录或打包文件：

# 从本地目录安装（会复制到插件目录）/plugin install ./path/to/my-plugin# 从本地目录链接（不复制，直接引用原路径）/plugin install --link ./path/to/my-plugin

--link 模式在团队共享仓库中很有用——所有人 clone 同一个仓库，然后 link 安装，插件代码随仓库更新而更新。

5.5 第三方市场

除了官方市场，Claude Code 支持接入第三方插件市场：

# 添加第三方市场/plugin marketplace add owner/repo-name# 从第三方市场安装/plugin install --marketplace owner/repo-name plugin-name

企业可以搭建私有插件市场，只允许安装经过内部审核的插件。

6. 版本管理与生命周期

完整的插件生命周期管理命令：

# 列出已安装插件claude plugin listclaude plugin list --verbose    # 显示详细信息（版本、来源、组件数）# 启用/禁用（不卸载，只是暂停）claude plugin disable code-reviewclaude plugin enable code-review# 更新claude plugin update code-review           # 更新到最新版claude plugin update code-review@1.3.0     # 更新到指定版本claude plugin update --all                 # 更新所有插件# 卸载claude plugin uninstall code-reviewclaude plugin uninstall code-review --keep-data  # 保留持久化数据# 清理无用数据claude plugin prune    # 清理已卸载插件的残留数据# 验证claude plugin validate ./my-plugin         # 验证本地插件claude plugin validate code-review         # 验证已安装插件# 版本标签（发布者使用）claude plugin tag code-review latest       # 设置 latest 标签claude plugin tag code-review stable       # 设置 stable 标签

版本锁定：

在团队场景中，可能需要锁定插件版本以确保一致性：

// .claude/plugin-lock.json{"code-review": {"version": "1.2.0","source": "github:team/code-review-plugin","integrity": "sha256-xxxxx"  }}

这个锁文件提交到仓库后，团队成员安装时会自动使用锁定的版本。

7. 企业级部署

7.1 组织级策略管理

企业环境下，管理员需要控制哪些插件可以使用。Claude Code 通过 managed-mcp.json 和组织策略文件实现这一点。

在组织的管理后台或配置文件中定义策略：

{"pluginPolicy": {"allowedSources": ["marketplace", "github:your-org/*"],"deniedPlugins": ["untrusted-plugin","another-risky-plugin"    ],"enabledPlugins": ["code-review@>=1.0.0","security-scan@>=2.0.0"    ],"requireApproval": {"permissions": ["Bash", "Write"],"sensitiveConfig": true    }  }}

deniedPlugins 是黑名单——明确禁止安装的插件。用于封杀已知有安全问题的插件。

enabledPlugins 是白名单——只允许安装列表中的插件。比黑名单更严格，适合高安全要求的环境。两者同时配置时，白名单优先。

allowedSources 限制插件来源。比如只允许从官方市场和组织的 GitHub 安装，禁止从 npm 或本地路径安装。

requireApproval 要求特定权限的插件需要管理员审批。一个插件如果声明了 Bash 工具权限或有 sensitive 配置项，安装时会进入审批流程。

7.2 合规审计

组织需要追踪插件的使用情况和来源。Claude Code 提供审计日志：

# 查看插件安装/卸载历史claude audit plugins --since 2025-01-01# 输出示例2025-03-15 10:23  INSTALL   code-review@1.2.0   source:github:team/cr   user:alice2025-03-15 14:07  CONFIG    code-review          key:coverage_threshold  user:alice2025-03-16 09:00  UPDATE    code-review@1.3.0    source:github:team/cr   user:bob2025-04-01 11:30  DISABLE   code-review          reason:policy-update    user:admin

审计日志记录了谁在什么时候安装/更新/配置/禁用了哪个插件，来源是什么。这对合规审查至关重要。

7.3 安全审查流程

对于申请使用 Bash、Write 等高权限工具的插件，建议建立审批流程：

1. 开发者提交插件到组织私有市场
2. 安全团队审查：检查脚本代码、权限声明、依赖链
3. 审批/拒绝：审批通过后加入 enabledPlugins 白名单
4. 版本更新重审：主版本号更新（如 1.x → 2.x）需要重新审查

这个流程用 managed-mcp.json 的 requireApproval 配置来强制执行。未经审批的高权限插件，用户安装时会收到"需要管理员审批"的提示。

8. 成本优化策略

插件在生产环境运行，Token 消耗是一个实际问题。尤其是包含子代理和复杂 Skill 的插件，不做优化的话，一次执行可能烧掉好几美元。

8.1 /cost 监控

Claude Code 内置了成本监控：

/cost

输出当前会话的 Token 消耗明细：

Session cost breakdown:  Input tokens:   45,230  ($0.135)  Output tokens:  12,870  ($0.193)  Cache read:     28,100  ($0.028)  Cache write:     8,400  ($0.032)  Total:                  ($0.388)By component:  Main session:           ($0.142)  Skill: review           ($0.098)  Agent: security-audit   ($0.148)

按组件分拆的成本数据，能帮你定位哪个组件最耗钱，然后有针对性地优化。

8.2 模型分级策略

不是所有任务都需要最贵的模型。一个审查插件的合理分级：

在插件的 Agent 定义中指定模型：

---name: preprocessmodel: claude-haiku-4-20250514tools: [Read, Glob, Grep]---你是一个预处理代理。任务是分析 git diff，提取变更文件列表，按风险等级分类（高/中/低），过滤掉自动生成的文件和配置文件变更。只输出结构化的分类结果，不做代码审查。

---name: security-auditmodel: claude-opus-4-20250514tools: [Read, Grep, Glob]---你是一个安全审计专家。只在预处理代理标记为"高风险"的文件上执行。检查 OWASP Top 10 漏洞、注入风险、认证绕过可能性。

这样，大量简单的文件分类工作由 Haiku 处理（几乎不花钱），只有真正需要深度分析的文件才用 Opus。成本可以降低 60-80%。

8.3 Prompt Caching 在插件中的应用

Prompt Caching 是 Anthropic API 的一个特性——相同的 prompt 前缀在多次调用间复用，缓存命中时输入 token 的价格降到原来的 1/10。

插件天然适合利用这个机制，因为 Skill 的系统提示词（SKILL.md 内容）在同一个会话中不会变。Claude Code 会自动将 Skill 指令标记为可缓存内容。

你可以进一步优化：把不变的内容放在 SKILL.md 前面，把变化的参数放在后面。 因为缓存是按前缀匹配的。

---name: reviewdescription: 代码审查---## 审查标准（不变 — 会被缓存）1. 命名规范：变量名使用 camelCase...2. 错误处理：所有 async 函数必须...3. 安全检查：不允许 eval()...（...200 行审查清单...）## 当前任务（每次不同 — 不缓存）审查以下文件的变更：$ARGUMENTS

这 200 行审查清单在第一次执行后会被缓存，后续审查其他文件时直接命中缓存，只为变化的部分付费。

8.4 Effort 参数

Claude Code 支持通过 --effort 参数控制模型的思考深度：

claude --effort low    # 快速回答，token 消耗少claude --effort medium # 默认claude --effort high   # 深度思考，token 消耗多

在插件中，可以为不同的 Skill 和 Agent 设置不同的 effort 级别：

// settings.json{"skills": {"review": { "effort": "medium" },"security-scan": { "effort": "high" },"format-check": { "effort": "low" }  }}

格式检查用 low 就够了——它只是看代码风格有没有问题。安全扫描则需要 high——漏洞检测需要深度推理。

8.5 上下文压缩（Compaction）策略

长时间运行的插件会话会积累大量上下文。Claude Code 支持配置自动压缩策略：

// settings.json{"compaction": {"threshold": 80,"strategy": "summarize","preserveRecent": 10  }}

当上下文占用率超过 80% 时，自动压缩旧内容——保留最近 10 轮对话的原文，更早的内容压缩为摘要。

在插件中，可以通过 @contextHint 标记哪些输出是临时的、可以压缩的，哪些是关键的、必须保留的：

<!-- @contextHint: compressible -->中间处理日志...文件 A 通过检查...文件 B 通过检查...<!-- @contextHint: preserve -->## 最终审查结果发现 3 个问题：1. src/auth.ts:42 — SQL 注入风险2. ...

9. 实战：开发并发布一个完整插件

把前面讲的所有概念串起来，从零开发一个团队代码审查插件。

9.1 目标

开发一个名为 team-review 的插件，具备以下能力：

• Skill：定义代码审查流程和清单
• Agent：安全扫描子代理（只读权限，Opus 模型）
• Hook：提交 commit 后自动运行快速检查
• MCP：连接项目管理工具获取 issue 上下文

9.2 创建项目结构

mkdir -p team-review/{.claude-plugin,skills/review,agents,commands,hooks,bin}

目录结构：

team-review/├── .claude-plugin/│   └── plugin.json├── skills/│   └── review/│       ├── SKILL.md│       └── templates/│           └── report.md├── agents/│   └── security-auditor.md├── commands/│   └── review.md├── hooks/│   └── hooks.json├── .mcp.json├── settings.json├── bin/│   ├── post-commit-check.sh│   └── mcp-project.js└── README.md

9.3 编写 plugin.json

{"name": "team-review","version": "0.1.0","description": "团队代码审查插件，含自动安全扫描和提交检查","author": "your-team","license": "MIT","minCliVersion": "2.1.80","keywords": ["review", "security", "team"],"userConfig": {"project_api_url": {"type": "string","description": "项目管理工具的 API 地址","required": true    },"project_api_token": {"type": "string","description": "项目管理工具的 API Token","required": true,"sensitive": true    },"severity_threshold": {"type": "string","description": "报告的最低严重级别","enum": ["info", "warning", "error"],"default": "warning"    }  },"dependencies": {"system": ["git >= 2.30"]  }}

9.4 编写 Skill

skills/review/SKILL.md：

---name: reviewdescription: "执行团队代码审查，检查代码质量、安全性和规范合规性"when_to_use: "当用户要求审查代码、检查 PR 质量、做代码评审时使用"---# 团队代码审查流程## 第一步：收集变更1. 运行 `git diff main...HEAD --name-only` 获取变更文件列表2. 运行 `git diff main...HEAD --stat` 获取变更统计3. 如果变更文件超过 20 个，先用 Explore 代理做全局分析## 第二步：分类评估按以下分类对每个变更文件评估风险等级：| 类别 | 风险 | 处理方式 ||------|------|---------|| 认证/授权相关 | 高 | 派安全审计子代理 || 数据库操作 | 高 | 检查 SQL 注入、锁表 || API 接口变更 | 中 | 检查向后兼容性 || 业务逻辑 | 中 | 检查边界条件 || UI/样式 | 低 | 检查命名规范 || 测试代码 | 低 | 检查断言覆盖 || 文档/配置 | 低 | 格式检查 |## 第三步：逐文件审查对每个文件执行以下检查：### 代码质量- [ ] 函数长度不超过 50 行- [ ] 单个文件不超过 300 行- [ ] 没有硬编码的魔数或字符串- [ ] 错误处理完整（async 函数有 try-catch 或 .catch）- [ ] 没有被注释掉的代码块### 安全检查- [ ] 没有 eval() 或 new Function()- [ ] 用户输入已做验证和转义- [ ] 没有在前端暴露敏感信息- [ ] API 端点有鉴权检查- [ ] 文件操作使用安全路径### 规范合规- [ ] 命名遵循项目约定- [ ] 新的公共 API 有 JSDoc/注释- [ ] 没有 console.log（应使用项目的日志框架）- [ ] import 顺序符合规范## 第四步：生成报告使用 `templates/report.md` 模板生成审查报告。报告包括：- 变更概览（文件数、代码行数）- 按严重级别分类的问题列表- 每个问题的修复建议- 总体评估（通过/需修改/拒绝）

skills/review/templates/report.md：

# 代码审查报告**分支**: {{branch}}**审查时间**: {{timestamp}}**变更文件数**: {{file_count}}**代码行变更**: +{{lines_added}} / -{{lines_removed}}## 问题汇总| 级别 | 数量 ||------|------|| 🔴 Error | {{error_count}} || 🟡 Warning | {{warning_count}} || 🔵 Info | {{info_count}} |## 详细问题列表{{#issues}}### {{severity}} — {{file}}:{{line}}**问题**: {{description}}**建议**: {{suggestion}}

{{code_snippet}}

{{/issues}}## 总体评估{{verdict}}

9.5 编写安全审计 Agent

agents/security-auditor.md：

---name: security-auditormodel: claude-opus-4-20250514tools: [Read, Grep, Glob]effort: high---你是一个资深安全工程师。你的任务是对指定的代码文件进行深度安全审计。## 约束- 你只有只读权限，不能修改任何文件- 只关注安全问题，忽略代码风格和性能问题- 每个发现必须包含：文件路径、行号、漏洞类型、严重级别、利用方式描述、修复建议## 检查清单### 注入类- SQL 注入（包括 ORM 的 raw query）- 命令注入（child_process、exec）- 模板注入（服务端模板引擎）- LDAP 注入- XSS（反射型、存储型、DOM 型）### 认证与授权- 硬编码凭据- JWT 配置不当（弱密钥、不验证过期）- 权限提升路径- IDOR（不安全的直接对象引用）### 数据保护- 敏感数据明文传输- 日志中泄露敏感信息- 不安全的随机数生成- 密码学误用### 配置安全- CORS 配置过于宽松- 安全头缺失- Debug 模式暴露- 默认凭据## 输出格式对每个发现，使用以下格式：

[SEVERITY] VULN_TYPE — file:line Description: ... Exploit: ... Fix: ...

如果没有发现安全问题，明确说明"未发现安全问题"并简要说明检查了哪些方面。

9.6 编写 Hook

hooks/hooks.json：

{"hooks": {"PostToolUse": [      {"matcher": "git_commit","command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/post-commit-check.sh","timeout": 30000      }    ]  }}

bin/post-commit-check.sh：

#!/bin/bash# 提交后快速检查：检测是否有敏感信息被提交LAST_COMMIT=$(git log -1 --format="%H")DIFF=$(git diff-tree --no-commit-id -r -p "$LAST_COMMIT")ISSUES=""# 检查硬编码密钥ifecho"$DIFF" | grep -iE '(api_key|apikey|secret|password|token)\s*[:=]\s*["\x27][^"\x27]{8,}' > /dev/null 2>&1; then    ISSUES="${ISSUES}\n⚠️ 疑似硬编码凭据"fi# 检查私钥文件ifecho"$DIFF" | grep -E 'BEGIN (RSA |DSA |EC )?PRIVATE KEY' > /dev/null 2>&1; then    ISSUES="${ISSUES}\n🔴 私钥文件被提交"fi# 检查 .env 文件if git diff-tree --no-commit-id --name-only -r "$LAST_COMMIT" | grep -E '\.env(\.|$)' > /dev/null 2>&1; then    ISSUES="${ISSUES}\n⚠️ .env 文件被提交"fiif [ -n "$ISSUES" ]; thenecho"提交安全检查发现问题："echo -e "$ISSUES"echo""echo"建议运行 /team-review:review 进行完整审查"fi

9.7 编写 MCP 配置

.mcp.json：

{"mcpServers": {"project-context": {"command": "node","args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp-project.js"],"env": {"API_URL": "${userConfig.project_api_url}","API_TOKEN": "${userConfig.project_api_token}"      }    }  }}

bin/mcp-project.js（简化示例）：

#!/usr/bin/env nodeimport { Server } from"@modelcontextprotocol/sdk/server/index.js";import { StdioServerTransport } from"@modelcontextprotocol/sdk/server/stdio.js";const server = new Server({name: "project-context",version: "0.1.0"}, {capabilities: { tools: {} }});// 提供获取 issue 详情的工具server.setRequestHandler("tools/list", async () => ({tools: [{name: "get_issue",description: "获取项目管理工具中的 issue 详情",inputSchema: {type: "object",properties: {issue_id: { type: "string", description: "Issue ID" }      },required: ["issue_id"]    }  }]}));server.setRequestHandler("tools/call", async (request) => {if (request.params.name === "get_issue") {const { issue_id } = request.params.arguments;const response = await fetch(`${process.env.API_URL}/issues/${issue_id}`,      { headers: { "Authorization": `Bearer ${process.env.API_TOKEN}` } }    );const issue = await response.json();return {content: [{type: "text",text: JSON.stringify(issue, null, 2)      }]    };  }});const transport = new StdioServerTransport();await server.connect(transport);

9.8 编写 settings.json

{"skills": {"review": {"effort": "medium"    }  },"agents": {"security-auditor": {"effort": "high"    }  }}

9.9 本地测试

# 验证插件结构claude plugin validate ./team-review# 以本地模式加载插件claude --plugin-dir ./team-review# 在会话中测试# > /team-review:review# > 帮我审查一下当前分支的代码变更

逐步验证各个组件：

# 测试 Hook：做一次 commit，观察是否触发 post-commit-check.shgit add . && git commit -m "test commit"# 测试 Skill：直接调用# > /team-review:review# 测试 Agent：在 Skill 执行中观察是否正确派出安全审计子代理# 测试 MCP：# > 用 get_issue 工具查询 issue #123

9.10 发布到 GitHub

cd team-review# 初始化 git 仓库git initgit add .git commit -m "feat: team-review plugin v0.1.0"# 推送到 GitHubgit remote add origin git@github.com:your-org/team-review-plugin.gitgit push -u origin main# 创建 release taggit tag v0.1.0git push --tags

团队成员安装：

claude plugin install github:your-org/team-review-plugin@v0.1.0

安装过程会提示输入配置：

Installing team-review@0.1.0...Configuration required:  项目管理工具的 API 地址 (required):  > https://your-project-tool.com/api  项目管理工具的 API Token (required, sensitive):  > ****  报告的最低严重级别 [warning]:  > (enter)✓ Installed team-review@0.1.0  1 skill, 1 agent, 1 hook, 1 MCP server registered

9.11 迭代更新

修复 Bug 或添加功能后：

# 更新 plugin.json 中的版本号# "version": "0.1.0" → "0.2.0"git add .git commit -m "feat: add coverage check to review skill"git tag v0.2.0git push && git push --tags

用户端更新：

claude plugin update team-review

如果是破坏性更新（不兼容旧配置），升主版本号：

# "version": "0.2.0" → "1.0.0"

plugin.json 中的 userConfig 如果新增了 required 字段，更新时会自动提示用户补充配置。

小结

插件系统把 Claude Code 从一个"个人工具"变成了一个"可扩展平台"。它的核心价值不是技术复杂度，而是解决了一个工程问题：怎么把一个人摸索出来的好用工作流，低成本地复制给整个团队。

写插件的思路和写库一样：先在项目里内联着用（直接配置 .claude/），等发现第二个项目也需要的时候，再抽成独立插件。别上来就想着写一个万能插件——从小做起，解决一个具体问题，然后逐步迭代。

成本控制方面，模型分级和 Prompt Caching 是投入产出比最高的两个优化手段。前者是架构层面的决策（什么任务用什么模型），后者几乎是免费的（Skill 指令自动缓存）。这两个做好了，日常使用的 Token 成本可以控制在合理范围内。

企业部署的关键是策略管理和审计追踪。白名单机制确保只有审核过的插件能进入生产环境，审计日志让安全团队对插件的使用情况有完整的可见性。