Claude Code Plugin开发与发布全实战

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

# 创建插件根目录
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

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

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

# 代码审查 Skill

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

## 审查维度

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

## 审查目标

$ARGUMENTS

## 输出格式

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

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

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

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

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

---
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验证方法
- 修复建议和代码示例
- 整体安全评分

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

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

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

#!/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);

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": {
    "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": "提交前扫描敏感信息和安全漏洞"
      }
    ]
  }
}

#!/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);
});

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                    # 文档（可选）

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

# 方式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

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

# 在会话中逐一测试：

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

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

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

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

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

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

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

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

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

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

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

# 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

# 使用语义化版本号
# 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

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

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

审查目标：$ARGUMENTS

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

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

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

审查目标：$ARGUMENTS

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

{
  "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"
  }
}

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

# 加载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的工具

<!-- 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 执行。

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 }

# 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
    }
  }
}

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

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