<!-- title: Claude Code Plugin开发与发布全实战 -->

# Claude Code Plugin开发与发布全实战

## 概述

本教程面向希望将Claude Code扩展能力封装、分发、团队共享的开发者。你将学会从零创建一个完整的Plugin，包含自定义Skill、Subagent、Hooks和MCP Server，最终发布到社区Marketplace。学完可独立交付生产级Claude Code扩展包。

**适用人群**：已掌握Claude Code基础操作和Skill开发的开发者，希望构建可复用、可分发的扩展模块。

---

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code版本 | v2.1.154+（Plugin系统在该版本稳定） |
| Node.js | v18+（用于运行本地MCP Server） |
| Git | 已安装，用于版本管理和Marketplace发布 |
| Claude Code认证 | 已登录并激活付费计划 |
| 基础知识 | 熟悉Claude Code基本操作、Skill开发 |

---

## 一、为什么需要Plugin？

### 1.1 Plugin vs 独立配置

在开始之前，先理解两种扩展方式的本质区别：

```mermaid
flowchart LR
    A[Claude Code扩展] --> B[独立配置 .claude/]
    A --> C[Plugin插件包]

    B --> B1[个人工作流]
    B --> B2[项目定制]
    B --> B3[快速实验]

    C --> C1[团队共享]
    C --> C2[社区分发]
    C --> C3[版本管理]
    C --> C4[跨项目复用]

    style C fill:#e8f5e9,stroke:#4caf50
    style B fill:#fff3e0,stroke:#ff9800
```

**独立配置（`.claude/`目录）**：适合个人快速实验，Skill名短（如`/hello`），但无法跨项目复用、无法版本管理。

**Plugin插件包**：自包含目录，带`plugin.json`清单，可包含Skill、Agent、Hook、MCP Server等多种组件。Skill自动加命名空间前缀（如`/my-plugin:hello`），避免冲突。适合团队共享、社区分发、版本发布。

**决策原则**：先用`.claude/`快速迭代验证，成熟后转换为Plugin发布。

### 1.2 Plugin的核心能力

一个Plugin可以包含以下任意组合：

| 组件 | 目录 | 功能 |
|------|------|------|
| Skills | `skills/` | 自定义命令和提示词模板 |
| Commands | `commands/` | 旧式Skill（扁平Markdown文件） |
| Agents | `agents/` | 自定义Subagent定义 |
| Hooks | `hooks/` | 事件处理器（`hooks.json`） |
| MCP Server | `.mcp.json` | 工具服务器配置 |
| LSP Server | `.lsp.json` | 代码智能服务配置 |
| Monitors | `monitors/` | 后台监控配置 |
| Bin | `bin/` | 加入PATH的可执行文件 |
| Settings | `settings.json` | 默认设置 |

---

## 二、从零创建第一个Plugin

### 2.1 创建Plugin目录结构

```bash
# 创建插件根目录
mkdir -p code-review-helper
cd code-review-helper

# 创建Plugin清单目录（注意：必须在 .claude-plugin/ 下）
mkdir -p .claude-plugin

# 创建各组件目录
mkdir -p skills/review
mkdir -p agents
mkdir -p hooks
```

**⚠️ 常见错误**：不要把`skills/`、`agents/`等放在`.claude-plugin/`目录内。`.claude-plugin/`下只能有`plugin.json`。

### 2.2 编写Plugin清单

创建 `.claude-plugin/plugin.json`：

```json
{
  "name": "code-review-helper",
  "description": "代码审查助手 - 自动化代码审查、安全扫描和风格检查",
  "version": "1.0.0",
  "author": {
    "name": "你的名字",
    "email": "you@example.com"
  },
  "homepage": "https://github.com/yourname/code-review-helper",
  "repository": "https://github.com/yourname/code-review-helper.git",
  "license": "MIT"
}
```

**关键字段说明**：

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | ✅ | 唯一标识符，也是Skill的命名空间前缀 |
| `description` | ✅ | 在Plugin管理器中显示的描述 |
| `version` | 推荐 | 语义化版本号。如省略，git分发的Plugin用commit SHA做版本 |
| `author` | 推荐 | 作者信息 |
| `homepage` | 可选 | 项目主页URL |
| `repository` | 可选 | Git仓库URL，用于Marketplace分发 |

### 2.3 创建第一个Skill

创建 `skills/review/SKILL.md`：

```markdown
---
description: 对指定文件或目录进行全面的代码审查
---

# 代码审查 Skill

你是一位资深代码审查专家。请对用户指定的代码进行以下维度的审查：

## 审查维度

1. **正确性**：逻辑错误、边界条件、异常处理
2. **安全性**：SQL注入、XSS、敏感数据泄露、权限控制
3. **性能**：N+1查询、内存泄漏、不必要的计算
4. **可维护性**：命名规范、代码重复、复杂度过高
5. **风格一致性**：与项目现有代码风格是否统一

## 审查目标

$ARGUMENTS

## 输出格式

对每个发现的问题：
- 文件路径和行号
- 问题严重程度（🔴 严重 / 🟡 警告 / 🔵 建议）
- 问题描述
- 修复建议（含代码示例）
```

### 2.4 本地测试Plugin

```bash
# 使用 --plugin-dir 加载本地Plugin
claude --plugin-dir ./code-review-helper

# 在Claude Code会话中测试
# > /code-review-helper:review src/auth/login.ts
```

你也可以将Plugin放在skills目录中自动加载：

```bash
# 使用内置命令初始化
claude plugin init code-review-helper

# 这会在 ~/.claude/skills/code-review-helper/ 创建插件骨架
# 下次启动自动加载，显示为 code-review-helper@skills-dir
```

---

## 三、进阶：添加自定义Subagent

### 3.1 为什么需要自定义Subagent？

当你有一个特定领域的任务需要反复执行（如安全审计、性能分析、文档生成），自定义Subagent能让Claude以专门的"人格"和工具集来处理。

### 3.2 创建Agent定义文件

创建 `agents/security-auditor.md`：

```markdown
---
name: security-auditor
description: 专注安全漏洞审计的专家Agent
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebSearch
---

# 安全审计专家

你是一位专注应用安全的高级工程师。你的唯一目标是发现代码中的安全漏洞。

## 审计范围

按照OWASP Top 10标准，重点检查：

1. **A01 - 权限控制失效**：越权访问、IDOR
2. **A02 - 加密失败**：明文存储、弱算法
3. **A03 - 注入攻击**：SQL注入、命令注入、XSS
4. **A04 - 不安全设计**：业务逻辑漏洞
5. **A05 - 安全配置错误**：默认密码、调试模式开启
6. **A07 - 身份认证失败**：弱密码策略、会话管理
7. **A08 - 数据完整性失败**：不安全的反序列化

## 工作流程

1. 使用Glob扫描目标目录，识别所有代码文件
2. 使用Grep搜索高风险模式（eval、exec、innerHTML等）
3. 使用Read逐文件审查关键逻辑
4. 使用WebSearch查询已知CVE
5. 汇总报告，每个漏洞给出CVSS评分和修复建议

## 输出格式

返回结构化的安全审计报告，包含：
- 漏洞列表（按严重程度排序）
- 每个漏洞的PoC验证方法
- 修复建议和代码示例
- 整体安全评分
```

### 3.3 Agent工具权限控制

Agent定义中的`tools`字段精确控制Agent可以使用哪些工具：

```yaml
# 最小权限原则 - 只读审计
tools:
  - Read      # 读取文件
  - Grep      # 搜索代码
  - Glob      # 查找文件
  - WebSearch # 查询漏洞库

# 修复型Agent - 允许编辑
tools:
  - Read
  - Edit
  - Bash      # 运行测试
  - Grep
  - Glob
```

---

## 四、集成MCP Server到Plugin

### 4.1 Plugin内嵌MCP Server

Plugin可以直接捆绑MCP Server，用户安装Plugin后自动获得工具能力。

在Plugin根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "code-metrics": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/metrics-server.js"],
      "env": {
        "METRICS_CONFIG": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}
```

### 4.2 实战：创建代码度量MCP Server

创建 `servers/metrics-server.js`：

```javascript
#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "child_process";
import fs from "fs";
import path from "path";

const server = new McpServer({
  name: "code-metrics",
  version: "1.0.0",
});

// 工具1：计算代码复杂度
server.tool(
  "calculate_complexity",
  "计算指定文件的圈复杂度和认知复杂度",
  {
    filePath: z.string().describe("要分析的文件路径"),
    language: z.enum(["javascript", "typescript", "python", "go", "java"])
      .describe("编程语言"),
  },
  async ({ filePath, language }) => {
    try {
      const content = fs.readFileSync(filePath, "utf-8");
      const lines = content.split("\n").length;
      const functions = (content.match(/function\s|=>\s|def\s|func\s/g) || []).length;
      const classes = (content.match(/class\s|struct\s/g) || []).length;
      const imports = (content.match(/import\s|require\s/g) || []).length;
      
      // 简化的圈复杂度估算
      const branches = (content.match(/if\s|else|switch|case|for\s|while\s|catch/g) || []).length;
      const cyclomatic = branches + 1;
      
      const report = `# 代码度量报告: ${filePath}

## 基本信息
- 语言: ${language}
- 总行数: ${lines}
- 函数数: ${functions}
- 类/结构体数: ${classes}
- 导入数: ${imports}

## 复杂度指标
- 圈复杂度: ${cyclomatic}
- 平均函数复杂度: ${functions > 0 ? (cyclomatic / functions).toFixed(1) : 'N/A'}
- 代码密度: ${((functions / lines) * 100).toFixed(2)}%

## 建议
${cyclomatic > 10 ? '⚠️ 圈复杂度超过10，建议拆分函数' : '✅ 复杂度在合理范围内'}
${lines > 300 ? '⚠️ 文件行数超过300行，建议拆分模块' : '✅ 文件长度合理'}
`;
      
      return { content: [{ type: "text", text: report }] };
    } catch (error) {
      return { 
        content: [{ type: "text", text: `分析失败: ${error.message}` }],
        isError: true 
      };
    }
  }
);

// 工具2：依赖分析
server.tool(
  "analyze_dependencies",
  "分析项目依赖关系和潜在冲突",
  {
    projectPath: z.string().describe("项目根目录路径"),
  },
  async ({ projectPath }) => {
    const packageJsonPath = path.join(projectPath, "package.json");
    
    if (!fs.existsSync(packageJsonPath)) {
      return { 
        content: [{ type: "text", text: "未找到 package.json 文件" }],
        isError: true 
      };
    }
    
    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
    const deps = Object.entries(pkg.dependencies || {});
    const devDeps = Object.entries(pkg.devDependencies || {});
    
    const report = `# 依赖分析报告: ${projectPath}

## 生产依赖 (${deps.length})
${deps.map(([name, version]) => `- ${name}: ${version}`).join("\n")}

## 开发依赖 (${devDeps.length})
${devDeps.map(([name, version]) => `- ${name}: ${version}`).join("\n")}

## 统计
- 总依赖数: ${deps.length + devDeps.length}
- 生产依赖占比: ${((deps.length / (deps.length + devDeps.length)) * 100).toFixed(0)}%
`;
    
    return { content: [{ type: "text", text: report }] };
  }
);

// 启动服务
const transport = new StdioServerTransport();
await server.connect(transport);
```

### 4.3 环境变量占位符

Plugin内嵌MCP Server支持三个特殊环境变量：

| 变量 | 指向 | 用途 |
|------|------|------|
| `${CLAUDE_PLUGIN_ROOT}` | Plugin根目录 | 引用打包的脚本和配置文件 |
| `${CLAUDE_PLUGIN_DATA}` | Plugin持久化数据目录 | 存储需要跨更新保留的状态 |
| `${CLAUDE_PROJECT_DIR}` | 当前项目根目录 | 解析项目相对路径 |

```mermaid
flowchart TB
    subgraph Plugin["code-review-helper Plugin"]
        A[plugin.json<br/>清单文件]
        B[skills/review/SKILL.md<br/>审查技能]
        C[agents/security-auditor.md<br/>安全审计Agent]
        D[.mcp.json<br/>MCP Server配置]
        E[servers/metrics-server.js<br/>度量工具服务]
        F[settings.json<br/>默认设置]
    end

    subgraph Load["加载流程"]
        G[Claude Code启动] --> H{发现Plugin}
        H --> I[读取 plugin.json]
        I --> J[注册Skills<br/>code-review-helper:review]
        I --> K[注册Agents<br/>security-auditor]
        I --> L[启动MCP Server<br/>code-metrics]
        I --> M[应用Settings]
    end

    Plugin --> Load

    style Plugin fill:#e3f2fd,stroke:#1976d2
    style Load fill:#f1f8e9,stroke:#689f38
```

---

## 五、添加Hooks事件处理器

### 5.1 Plugin中的Hooks

在Plugin根目录创建 `hooks/hooks.json`：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/post-edit-check.js",
        "description": "编辑文件后自动运行格式化和lint检查"
      }
    ],
    "PreCommit": [
      {
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit-scan.js",
        "description": "提交前扫描敏感信息和安全漏洞"
      }
    ]
  }
}
```

### 5.2 实战：提交前安全扫描Hook

创建 `scripts/pre-commit-scan.js`：

```javascript
#!/usr/bin/env node

// 从stdin读取Hook输入
let input = "";
process.stdin.on("data", (chunk) => {
  input += chunk;
});
process.stdin.on("end", () => {
  const hookData = JSON.parse(input);
  const message = hookData.commit_message || "";
  const files = hookData.files || [];
  
  // 敏感模式检测
  const sensitivePatterns = [
    { pattern: /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]+['"]/gi, 
      name: "明文密码", severity: "CRITICAL" },
    { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]+['"]/gi, 
      name: "API密钥泄露", severity: "CRITICAL" },
    { pattern: /(?:secret|token)\s*[:=]\s*['"][^'"]+['"]/gi, 
      name: "敏感Token", severity: "HIGH" },
    { pattern: /BEGIN\s+(RSA|DSA|EC|OPENSSH)\s+PRIVATE\s+KEY/gi, 
      name: "私钥文件", severity: "CRITICAL" },
    { pattern: /mongodb(?:\+srv)?:\/\/[^:]+:[^@]+@/gi, 
      name: "数据库连接串含凭证", severity: "HIGH" },
  ];
  
  const findings = [];
  
  for (const file of files) {
    try {
      const content = require("fs").readFileSync(file, "utf-8");
      for (const { pattern, name, severity } of sensitivePatterns) {
        const matches = content.match(pattern);
        if (matches) {
          findings.push({ file, name, severity, count: matches.length });
        }
      }
    } catch (e) {
      // 文件可能已删除或二进制文件，跳过
    }
  }
  
  if (findings.length > 0) {
    const critical = findings.filter(f => f.severity === "CRITICAL");
    const blocked = critical.length > 0;
    
    const report = findings.map(f => 
      `${f.severity}: ${f.name} 在 ${f.file} 中发现 ${f.count} 处`
    ).join("\n");
    
    if (blocked) {
      console.error(`⛔ 提交被阻止 - 发现严重安全问题:\n${report}`);
      process.exit(2); // exit code 2 = 阻止提交
    } else {
      console.log(`⚠️ 警告 - 发现潜在安全问题:\n${report}`);
      process.exit(0); // exit code 0 = 允许但警告
    }
  }
  
  process.exit(0);
});
```

---

## 六、Plugin完整项目结构

经过以上步骤，你的Plugin目录结构如下：

```
code-review-helper/
├── .claude-plugin/
│   └── plugin.json              # Plugin清单
├── skills/
│   └── review/
│       └── SKILL.md             # 代码审查技能
├── agents/
│   └── security-auditor.md      # 安全审计Agent
├── hooks/
│   └── hooks.json               # Hook事件配置
├── scripts/
│   ├── post-edit-check.js       # 编辑后检查脚本
│   └── pre-commit-scan.js       # 提交前扫描脚本
├── servers/
│   └── metrics-server.js        # MCP Server（代码度量）
├── .mcp.json                    # MCP Server入口配置
├── settings.json                # 默认设置
├── package.json                 # Node.js项目配置（可选）
└── README.md                    # 文档（可选）
```

创建 `settings.json`（Plugin默认设置）：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm test:*)"
    ]
  },
  "hooks": {
    "enabled": true
  }
}
```

---

## 七、测试与调试

### 7.1 本地开发测试

```bash
# 方式1：使用 --plugin-dir 直接加载
claude --plugin-dir ./code-review-helper

# 方式2：放到skills目录自动加载
claude plugin init code-review-helper
# 然后将开发中的文件复制过去
cp -r ./code-review-helper/* ~/.claude/skills/code-review-helper/

# 方式3：symlink方式（推荐，实时同步）
ln -s $(pwd)/code-review-helper ~/.claude/skills/code-review-helper
```

### 7.2 验证各组件

```bash
# 启动后验证
claude --plugin-dir ./code-review-helper

# 在会话中逐一测试：

# 1. 测试Skill
> /code-review-helper:review src/

# 2. 查看已注册Agent
> /agents

# 3. 查看MCP Server状态
> /mcp

# 4. 查看已加载Plugin
> /plugin list
```

### 7.3 调试MCP Server

```bash
# 使用MCP Inspector测试MCP Server
npx @modelcontextprotocol/inspector node ./code-review-helper/servers/metrics-server.js

# Inspector会在浏览器中打开，可以：
# - 查看注册的工具列表
# - 手动调用工具并查看返回
# - 检查输入Schema验证
```

### 7.4 常见问题排查

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| Skill不显示 | `SKILL.md`格式错误 | 检查frontmatter的`description`字段 |
| MCP Server连接失败 | Node依赖未安装 | 在Plugin目录执行`npm install` |
| Agent工具调用被拒 | 工具不在allowlist | 在`settings.json`中添加权限 |
| Hook未触发 | `hooks.json`路径错误 | 确认在`hooks/`目录下 |
| 命名空间不对 | `plugin.json`的`name`与目录不匹配 | 检查`name`字段 |

---

## 八、发布到Marketplace

### 8.1 发布流程总览

```mermaid
flowchart TD
    A[本地开发测试] --> B[完善plugin.json]
    B --> C[添加README文档]
    C --> D[Git仓库推送]
    D --> E{发布方式}

    E --> F[团队Marketplace<br/>私有分发]
    E --> G[社区Marketplace<br/>公开分发]

    F --> F1[配置Marketplace]
    F1 --> F2[team install]

    G --> G1[提交到Anthropic审核]
    G1 --> G2[审核通过]
    G2 --> G3[公开上架]

    style E fill:#fff9c4,stroke:#f9a825
    style G2 fill:#c8e6c9,stroke:#43a047
```

### 8.2 团队Marketplace（私有分发）

如果你的团队有内部Plugin需要分发，可以搭建自己的Marketplace：

```bash
# 1. 创建Marketplace仓库
# 在Git仓库中维护plugin-index.json和Plugin包

# 2. 注册Marketplace
claude plugin marketplace add your-org/your-marketplace

# 3. 团队成员安装
claude plugin install code-review-helper
```

Marketplace的索引文件结构：

```json
{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "code-review-helper",
      "version": "1.0.0",
      "source": "https://github.com/your-org/code-review-helper",
      "description": "代码审查助手"
    }
  ]
}
```

### 8.3 社区Marketplace（公开分发）

提交到Anthropic官方社区Marketplace：

```bash
# 1. 确保Plugin目录是独立的Git仓库
cd code-review-helper
git init
git add .
git commit -m "Initial release v1.0.0"
git remote add origin https://github.com/yourname/code-review-helper.git
git push -u origin main

# 2. 提交到社区Marketplace
# 在Anthropic Directory提交你的Plugin信息
# 地址：https://claude.com/docs/connectors/building
```

### 8.4 版本管理最佳实践

```bash
# 使用语义化版本号
# MAJOR.MINOR.PATCH
# 1.0.0 -> 1.0.1 (Bug修复)
# 1.0.0 -> 1.1.0 (新功能，向后兼容)
# 1.0.0 -> 2.0.0 (破坏性变更)

# 打Tag发布
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
```

---

## 九、实战案例：完整的代码审查Plugin

让我们把所有组件整合，构建一个完整可用的代码审查Plugin。

### 9.1 增强Skill：添加多个审查模式

创建 `skills/quick-review/SKILL.md`：

```markdown
---
description: 快速代码审查，只关注严重问题
---

快速审查以下代码，只报告🔴严重和🟡警告级别的问题。
关注点：安全漏洞、逻辑错误、数据丢失风险。

审查目标：$ARGUMENTS
```

创建 `skills/perf-review/SKILL.md`：

```markdown
---
description: 性能审查，专注性能瓶颈和优化建议
---

以性能专家的角度审查以下代码，重点关注：

1. 算法复杂度（时间/空间）
2. N+1查询问题
3. 不必要的同步操作
4. 内存泄漏风险
5. 缓存策略
6. 数据库查询优化

审查目标：$ARGUMENTS

输出格式：
- 📊 性能评分（1-10）
- 🔍 发现的瓶颈（含具体位置）
- 💡 优化建议（含代码示例）
- 📈 预估优化效果
```

### 9.2 完整的settings.json

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm test:*)",
      "Bash(npx eslint:*)",
      "Bash(npx prettier --check:*)",
      "Bash(git diff:*)"
    ]
  },
  "env": {
    "REVIEW_SEVERITY_THRESHOLD": "warning",
    "REVIEW_MAX_FILES": "50"
  }
}
```

### 9.3 完整的.mcp.json

```json
{
  "mcpServers": {
    "code-metrics": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/metrics-server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_ROOT}/node_modules"
      }
    }
  }
}
```

### 9.4 使用完整Plugin

```bash
# 加载Plugin
claude --plugin-dir ./code-review-helper

# 全面审查
> /code-review-helper:review src/auth/

# 快速审查（只看严重问题）
> /code-review-helper:quick-review src/utils/helper.ts

# 性能审查
> /code-review-helper:perf-review src/api/

# 使用安全审计Agent（通过/agents面板调用）
> /agents
# 选择 security-auditor，指向目标目录

# MCP工具自动可用 - 调用代码度量
> 计算一下 src/auth/login.ts 的代码复杂度
# Claude会自动调用code-metrics MCP Server的工具
```

---

## 十、Plugin与Dynamic Workflow的协同

### 10.1 从Plugin触发Workflow

Plugin中的Skill可以引导Claude创建Dynamic Workflow，实现大规模自动化：

```markdown
<!-- skills/full-audit/SKILL.md -->
---
description: 对整个项目进行全面审计（使用Workflow并行执行）
---

# 全项目审计

请使用 Dynamic Workflow 对项目进行全面审计。

## 工作流设计

### Phase 1: 发现
- 扫描项目结构，识别所有源文件
- 分类文件类型和模块

### Phase 2: 并行审查
对每个模块并行启动Agent审查：
- 安全审计Agent
- 性能审查Agent
- 代码风格审查Agent

### Phase 3: 交叉验证
- 对各Agent的发现进行交叉验证
- 过滤误报

### Phase 4: 汇总报告
- 合并所有发现
- 按严重程度排序
- 生成可操作的修复建议

审计目标：$ARGUMENTS

使用 ultracode 关键词触发 Workflow 执行。
```

### 10.2 Workflow脚本示例

当用户调用`/code-review-helper:full-audit src/`时，Claude可能生成如下Workflow脚本：

```javascript
export const meta = {
  name: 'full-code-audit',
  description: '全项目代码审计 - 安全、性能、风格三维度并行',
  phases: [
    { title: 'Discover', detail: '扫描项目文件结构' },
    { title: 'Audit', detail: '三维度并行审计' },
    { title: 'Verify', detail: '交叉验证审计结果' },
  ],
}

phase('Discover')
const files = await agent(
  '扫描 src/ 目录，列出所有源文件，按模块分组。使用Glob和Read工具。',
  { label: 'discover', phase: 'Discover', schema: FILES_SCHEMA }
)

log(`发现 ${files.modules.length} 个模块，共 ${files.totalFiles} 个文件`)

phase('Audit')
const DIMENSIONS = [
  { key: 'security', prompt: '作为安全专家，审查代码中的安全漏洞...' },
  { key: 'performance', prompt: '作为性能专家，审查代码中的性能瓶颈...' },
  { key: 'style', prompt: '作为代码风格专家，审查代码风格问题...' }
]

const auditResults = await parallel(
  DIMENSIONS.map(d => () =>
    agent(d.prompt, { label: `audit:${d.key}`, phase: 'Audit', schema: FINDINGS_SCHEMA })
  )
)

phase('Verify')
const allFindings = auditResults
  .filter(Boolean)
  .flatMap(r => r.findings)

const verified = await parallel(
  allFindings.map(f => () =>
    agent(`验证此发现是否为真实问题: ${f.title} - ${f.description}`, 
      { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT_SCHEMA })
  )
)

const confirmed = verified
  .filter(Boolean)
  .filter(v => v.isReal)
  .map(v => v.finding)

return { confirmed, total: allFindings.length, verified: confirmed.length }
```

---

## 十一、Plugin开发最佳实践

### 11.1 设计原则

| 原则 | 说明 |
|------|------|
| **最小权限** | Agent只声明必需的工具，不要给`Bash`等危险工具 |
| **单一职责** | 每个Skill/Agent只做一件事，做好一件事 |
| **防御性编程** | MCP Server要验证所有输入，处理所有异常 |
| **文档即代码** | Skill描述写清楚触发条件和使用方法 |
| **渐进增强** | 先用`.claude/`验证，再封装为Plugin |

### 11.2 性能优化

```bash
# 1. MCP Server启动优化
# 在package.json中使用ESM和top-level await
{
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.29.0",
    "zod": "^3.23.0"
  }
}

# 2. 避免在Plugin加载时执行重计算
# 把初始化逻辑放到工具首次调用时

# 3. 使用per-server timeout控制长时间运行
# .mcp.json中：
{
  "mcpServers": {
    "code-metrics": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/metrics-server.js"],
      "timeout": 60000
    }
  }
}
```

### 11.3 安全注意事项

```bash
# 1. 不要在Plugin代码中硬编码密钥
# 2. 使用环境变量引用敏感信息
# 3. 在hooks.json中限制命令执行范围
# 4. MCP Server返回结果前过滤敏感字段
# 5. settings.json中的permissions遵循最小权限原则
```

---

## 十二、Plugin生态系统全景

```mermaid
flowchart TB
    subgraph Ecosystem["Claude Code 扩展生态"]
        direction TB

        subgraph Core["核心扩展机制"]
            S[Skills<br/>自定义命令]
            A[Subagents<br/>专业化Worker]
            W[Workflows<br/>编排脚本]
        end

        subgraph Integration["集成层"]
            M[MCP Servers<br/>外部工具/数据源]
            H[Hooks<br/>事件处理器]
            L[LSP Servers<br/>代码智能]
        end

        subgraph Distribution["分发渠道"]
            P[Plugin包<br/>打包以上所有组件]
            MK[Marketplace<br/>团队/社区市场]
            GH[Git仓库<br/>版本管理]
        end
    end

    Core --> P
    Integration --> P
    P --> MK
    P --> GH

    style Ecosystem fill:#fafafa,stroke:#666
    style Core fill:#e8eaf6,stroke:#3f51b5
    style Integration fill:#e8f5e9,stroke:#4caf50
    style Distribution fill:#fff3e0,stroke:#ff9800
```

---

## 延伸阅读

- [Claude Code Plugin开发官方文档](https://code.claude.com/docs/en/plugins) — Anthropic官方Plugin创建指南
- [MCP Server构建指南](https://modelcontextprotocol.io/docs/develop/build-server) — MCP协议服务端开发规范
- [Dynamic Workflows文档](https://code.claude.com/docs/en/workflows) — Workflow编排机制详解
- [Claude Code Agents并行工作](https://code.claude.com/docs/en/agents) — Subagent和Agent Teams对比
- [OWASP MCP安全速查表](https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html) — MCP Server安全最佳实践

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI开发工具训练营、DevOps自动化训练营、团队效能提升工作坊 |
| 教学时长 | 4-6小时（含实操练习） |
| 难度级别 | ⭐⭐⭐⭐ 中高级 |
| 实操占比 | 70%（大量动手创建Plugin组件） |
| 前置要求 | Claude Code基础操作、JavaScript/TypeScript基础、Git操作 |

---

## 参考来源

1. [Create plugins - Claude Code Docs](https://code.claude.com/docs/en/plugins) — Anthropic官方Plugin创建完整指南，包含清单文件、目录结构、发布流程
2. [Orchestrate subagents at scale with dynamic workflows](https://code.claude.com/docs/en/workflows) — Dynamic Workflow脚本编排官方文档，覆盖agent()、pipeline()、parallel()等API
3. [Run agents in parallel](https://code.claude.com/docs/en/agents) — Subagent、Agent View、Agent Teams、Workflows四种并行方案的对比选择指南
4. [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) — MCP服务器配置参考，包含stdio/HTTP/SSE/WebSocket四种传输层配置
5. [FastMCP in Python: Build a Real MCP Server (2026 Guide)](https://www.danilchenko.dev/posts/fastmcp-mcp-server/) — Python FastMCP框架实战教程，包含@tool装饰器、资源定义、OAuth集成

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)