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

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	是	插件唯一标识符，全小写，连字符分隔
version	是	语义化版本号（SemVer）
description	是	一句话描述，会显示在市场列表中
author	否	作者或团队名
license	否	开源协议
minCliVersion	否	最低 CLI 版本要求
keywords	否	搜索关键词

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

3.2 userConfig --- 用户可配置选项

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

每个配置项支持的属性：

属性	说明
type	值类型：string / number / boolean / array
description	配置说明，安装时显示给用户
required	是否必填
default	默认值（有默认值时安装不会询问）
sensitive	是否敏感信息
enum	可选值列表
validate	验证正则表达式

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

安装时的交互流程：

$ claude plugin install code-review

Installing 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 85
claude plugin config code-review github_token  # 敏感值会提示重新输入

3.3 环境变量

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

变量	说明
${CLAUDE_PLUGIN_ROOT}	插件的安装路径。引用插件内部文件时用这个
${CLAUDE_PLUGIN_DATA}	插件的持久化数据目录。存放运行时生成的数据

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 passed

code-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/bash
echo "PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}" >&2
echo "PLUGIN_DATA: ${CLAUDE_PLUGIN_DATA}" >&2
echo "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

# 指定版本/分支/tag
claude plugin install github:username/code-review-plugin@v1.2.0
claude plugin install github:username/code-review-plugin@main

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

5.3 npm 包

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

# 发布到 npm
cd 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 list
claude plugin list --verbose    # 显示详细信息（版本、来源、组件数）

# 启用/禁用（不卸载，只是暂停）
claude plugin disable code-review
claude 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-review
claude 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:alice
2025-03-15 14:07  CONFIG    code-review          key:coverage_threshold  user:alice
2025-03-16 09:00  UPDATE    code-review@1.3.0    source:github:team/cr   user:bob
2025-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 模型分级策略

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

阶段	模型	用途	成本
预处理	Haiku	提取 diff、分类文件、过滤无关变更	极低
主工作	Sonnet	代码审查、问题检测、建议生成	中等
复杂验证	Opus	安全漏洞深度分析、架构级评审	较高

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

---
name: preprocess
model: claude-haiku-4-20250514
tools: [Read, Glob, Grep]
---

你是一个预处理代理。任务是分析 git diff，提取变更文件列表，
按风险等级分类（高/中/低），过滤掉自动生成的文件和配置文件变更。
只输出结构化的分类结果，不做代码审查。

---
name: security-audit
model: claude-opus-4-20250514
tools: [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: review
description: 代码审查
---

## 审查标准（不变 --- 会被缓存）

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: review
description: "执行团队代码审查，检查代码质量、安全性和规范合规性"
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-auditor
model: claude-opus-4-20250514
tools: [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: ... ```bash 如果没有发现安全问题，明确说明"未发现安全问题"并简要说明检查了哪些方面。 ``` ### 9.6 编写 Hook `hooks/hooks.json`： ```bash { "hooks": { "PostToolUse": [ { "matcher": "git_commit", "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/post-commit-check.sh", "timeout": 30000 } ] } } ``` `bin/post-commit-check.sh`： ```bash #!/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 文件被提交" fi if [ -n "$ISSUES" ]; then echo"提交安全检查发现问题：" echo -e "$ISSUES" echo"" echo"建议运行 /team-review:review 进行完整审查" fi ``` ### 9.7 编写 MCP 配置 `.mcp.json`： ```bash { "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`（简化示例）： ```bash #!/usr/bin/env node import { 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 ```bash { "skills": { "review": { "effort": "medium" } }, "agents": { "security-auditor": { "effort": "high" } } } ``` ### 9.9 本地测试 ```bash # 验证插件结构 claude plugin validate ./team-review # 以本地模式加载插件 claude --plugin-dir ./team-review # 在会话中测试 # > /team-review:review # > 帮我审查一下当前分支的代码变更 ``` 逐步验证各个组件： ```bash # 测试 Hook：做一次 commit，观察是否触发 post-commit-check.sh git add . && git commit -m "test commit" # 测试 Skill：直接调用 # > /team-review:review # 测试 Agent：在 Skill 执行中观察是否正确派出安全审计子代理 # 测试 MCP： # > 用 get_issue 工具查询 issue #123 ``` ### 9.10 发布到 GitHub ```bash cd team-review # 初始化 git 仓库 git init git add . git commit -m "feat: team-review plugin v0.1.0" # 推送到 GitHub git remote add origin git@github.com:your-org/team-review-plugin.git git push -u origin main # 创建 release tag git tag v0.1.0 git push --tags ``` 团队成员安装： ```bash claude plugin install github:your-org/team-review-plugin@v0.1.0 ``` 安装过程会提示输入配置： ```bash 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 或添加功能后： ```bash # 更新 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.0 git push && git push --tags ``` 用户端更新： ```bash claude plugin update team-review ``` 如果是破坏性更新（不兼容旧配置），升主版本号： ```bash # "version": "0.2.0" → "1.0.0" ``` `plugin.json` 中的 `userConfig` 如果新增了 `required` 字段，更新时会自动提示用户补充配置。 *** ** * ** *** ## 小结 插件系统把 Claude Code 从一个"个人工具"变成了一个"可扩展平台"。它的核心价值不是技术复杂度，而是解决了一个工程问题：**怎么把一个人摸索出来的好用工作流，低成本地复制给整个团队。** 写插件的思路和写库一样：先在项目里内联着用（直接配置 `.claude/`），等发现第二个项目也需要的时候，再抽成独立插件。别上来就想着写一个万能插件------从小做起，解决一个具体问题，然后逐步迭代。 成本控制方面，模型分级和 Prompt Caching 是投入产出比最高的两个优化手段。前者是架构层面的决策（什么任务用什么模型），后者几乎是免费的（Skill 指令自动缓存）。这两个做好了，日常使用的 Token 成本可以控制在合理范围内。 企业部署的关键是策略管理和审计追踪。白名单机制确保只有审核过的插件能进入生产环境，审计日志让安全团队对插件的使用情况有完整的可见性。