Claude Code Plugin全栈开发：从零构建到生态发布的完整实战

# 确认Claude Code版本
claude --version
# 应显示 1.0.50 或更高

graph TD
    A["阶段一：原子扩展<br/>Skills / Hooks / MCP"] --> B["阶段二：项目级配置<br/>settings.json + CLAUDE.md"]
    B --> C["阶段三：Plugin系统<br/>三合一打包分发"]

    A1["Skills: 指令模板<br/>轻量级，纯文本"] --> A
    A2["Hooks: 事件钩子<br/>确定性Shell/HTTP"] --> A
    A3["MCP: 工具服务<br/>运行时能力扩展"] --> A

    C --> C1["单一manifest<br/>plugin.json"]
    C --> C2["可版本化<br/>Git tag/release"]
    C --> C3["可分发<br/>Marketplace/Git"]
    C --> C4["可组合<br/>多Plugin共存"]

    style C fill:#4A90D9,color:#fff
    style C1 fill:#6AB0DE,color:#fff
    style C2 fill:#6AB0DE,color:#fff
    style C3 fill:#6AB0DE,color:#fff
    style C4 fill:#6AB0DE,color:#fff

my-quality-plugin/
├── .claude-plugin/
│   └── plugin.json          # 核心清单文件（必须）
├── skills/
│   ├── review.md            # Skill：代码审查指令
│   └── fix-quality.md       # Skill：质量修复指令
├── hooks/
│   └── format-on-save.sh    # Hook脚本：自动格式化
├── agents/
│   └── reviewer.yaml        # Agent定义：审查Agent
├── mcp/
│   └── quality-server/      # MCP Server源码
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           └── index.ts
├── commands/
│   └── quality-check.md     # 斜杠命令定义
├── CLAUDE.md                # Plugin级上下文指令
└── README.md                # 使用说明

{
  "name": "code-quality-guardian",
  "version": "1.2.0",
  "description": "Automated code quality enforcement with linting, formatting, and review",
  "author": "your-name",
  "license": "MIT",
  "repository": "https://github.com/your-org/code-quality-guardian",

  "components": {
    "skills": [
      { "path": "skills/review.md", "command": "review" },
      { "path": "skills/fix-quality.md", "command": "fix-quality" }
    ],
    "hooks": [
      {
        "event": "PostToolUse",
        "matcher": "Edit|Write",
        "command": "bash hooks/format-on-save.sh",
        "description": "Auto-format after file edits"
      }
    ],
    "agents": [
      { "path": "agents/reviewer.yaml", "name": "code-reviewer" }
    ],
    "mcpServers": {
      "quality-tools": {
        "command": "node",
        "args": ["mcp/quality-server/dist/index.js"],
        "description": "Code quality analysis tools"
      }
    },
    "commands": [
      { "path": "commands/quality-check.md", "name": "quality-check" }
    ]
  },

  "dependencies": {
    "node": ">=18.0.0"
  },

  "settings": {
    "permissions": {
      "allow": [
        "Bash(npx prettier --write *)",
        "Bash(npx eslint --fix *)"
      ]
    }
  }
}

# 创建项目目录
mkdir code-quality-guardian && cd code-quality-guardian

# 初始化Git
git init

# 创建Plugin清单目录
mkdir -p .claude-plugin

# 创建组件目录
mkdir -p skills hooks agents mcp/quality-server/src commands

cat > .claude-plugin/plugin.json << 'MANIFEST'
{
  "name": "code-quality-guardian",
  "version": "1.0.0",
  "description": "Code quality enforcement: auto-format, lint, complexity analysis, and review",
  "author": "dev-team",
  "license": "MIT",
  "components": {
    "skills": [
      { "path": "skills/review.md", "command": "review" },
      { "path": "skills/fix-quality.md", "command": "fix-quality" }
    ],
    "hooks": [
      {
        "event": "PostToolUse",
        "matcher": "Edit|Write",
        "command": "bash hooks/format-on-save.sh",
        "description": "Auto-format edited files"
      },
      {
        "event": "PreToolUse",
        "matcher": "Bash",
        "command": "bash hooks/block-destructive.sh",
        "description": "Block destructive shell commands"
      }
    ],
    "agents": [
      { "path": "agents/reviewer.yaml", "name": "code-reviewer" }
    ],
    "mcpServers": {
      "complexity-analyzer": {
        "command": "node",
        "args": ["mcp/quality-server/dist/index.js"],
        "description": "Code complexity and quality analysis"
      }
    },
    "commands": [
      { "path": "commands/quality-check.md", "name": "quality-check" }
    ]
  },
  "settings": {
    "permissions": {
      "allow": [
        "Bash(npx prettier --write *)",
        "Bash(npx eslint --fix *)",
        "Bash(node mcp/quality-server/dist/index.js *)"
      ]
    }
  }
}
MANIFEST

---
name: review
description: Perform a comprehensive code quality review
---

You are a senior code reviewer. Analyze the current codebase or specified files for:

1. **Code Smells**: Long functions, deep nesting, duplicate logic
2. **Security Issues**: SQL injection, XSS, hardcoded secrets
3. **Performance**: N+1 queries, unnecessary re-renders, memory leaks
4. **Type Safety**: Missing type annotations, `any` types, unsafe casts
5. **Test Coverage**: Untested edge cases, missing assertions

For each finding:
- Rate severity: 🔴 Critical / 🟡 Warning / 🔵 Info
- Show the exact file and line
- Suggest a concrete fix with code

Output a summary with:
- Total findings by severity
- Top 3 priority fixes
- Overall quality score (0-100)

---
name: fix-quality
description: Automatically fix code quality issues
---

You are an automated code quality fixer. Based on the issues identified:

1. Read the files that need fixing
2. Apply fixes in priority order:
   - 🔴 Critical security issues first
   - 🟡 Warnings next
   - 🔵 Info items last
3. For each fix:
   - Use the Edit tool to make changes
   - Add a brief comment explaining the fix
4. After all fixes, run the project's test suite
5. Report: files changed, fixes applied, test results

Rules:
- Never change business logic, only quality improvements
- Preserve existing comments unless they're misleading
- Run tests after every 3 file changes
- If a fix breaks tests, revert immediately and report

#!/usr/bin/env bash
# format-on-save.sh - PostToolUse Hook for auto-formatting
# Reads JSON from stdin, formats the edited file

set -euo pipefail

# 读取Hook输入（JSON格式）
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 如果没有文件路径，退出
[[ -z "$FILE_PATH" ]] && exit 0

# 根据文件扩展名选择格式化工具
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
    # 检查prettier是否可用
    if command -v npx &>/dev/null; then
      npx --yes prettier --write "$FILE_PATH" 2>/dev/null || true
    fi
    ;;
  *.py)
    if command -v black &>/dev/null; then
      black "$FILE_PATH" 2>/dev/null || true
    fi
    ;;
  *.go)
    if command -v gofmt &>/dev/null; then
      gofmt -w "$FILE_PATH" 2>/dev/null || true
    fi
    ;;
esac

# 返回JSON输出（可选：包含格式化结果）
echo "{\"status\": \"formatted\", \"file\": \"$FILE_PATH\"}"

#!/usr/bin/env bash
# block-destructive.sh - PreToolUse Hook to block dangerous commands

set -euo pipefail

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危险命令模式
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "rm -rf *"
  "git push --force"
  "git reset --hard"
  "DROP TABLE"
  ":(){:|:&};:"
  "dd if=/dev/zero"
  "mkfs"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    # 输出拒绝消息到stderr（退出码2 = 阻止操作）
    echo "{\"decision\": \"block\", \"reason\": \"Blocked dangerous command: $pattern\"}" >&2
    exit 2
  fi
done

# 允许操作
exit 0

{
  "name": "complexity-analyzer",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.12.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.7.0"
  }
}

#!/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 fs from "fs/promises";
import path from "path";

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

// Tool 1: 分析文件复杂度
server.tool(
  "analyze-complexity",
  "Analyze cyclomatic complexity of a source file",
  { filePath: z.string().describe("Absolute path to the source file") },
  async ({ filePath }) => {
    const content = await fs.readFile(filePath, "utf-8");
    const lines = content.split("\n");

    // 计算基础指标
    const totalLines = lines.length;
    const codeLines = lines.filter(
      (l) => l.trim() && !l.trim().startsWith("//") && !l.trim().startsWith("*")
    ).length;
    const commentLines = totalLines - codeLines;

    // 简化的圈复杂度计算（基于分支关键词）
    const branchKeywords = ["if", "else if", "for", "while", "case", "catch", "&&", "||", "?"];
    let complexity = 1;
    for (const line of codeLines) {
      for (const keyword of branchKeywords) {
        if (line.includes(keyword)) complexity++;
      }
    }

    // 函数数量和最大函数长度
    const funcMatches = content.match(/(function\s+\w+|const\s+\w+\s*=\s*(?:async\s+)?\(|=>)/g);
    const funcCount = funcMatches ? funcMatches.length : 0;

    const rating = complexity <= 10 ? "LOW" : complexity <= 20 ? "MEDIUM" : "HIGH";

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            file: filePath,
            metrics: {
              totalLines,
              codeLines,
              commentLines,
              cyclomaticComplexity: complexity,
              complexityRating: rating,
              estimatedFunctions: funcCount,
              commentRatio: (commentLines / totalLines * 100).toFixed(1) + "%",
            },
            recommendation: complexity > 20
              ? "Consider breaking this file into smaller modules"
              : complexity > 10
                ? "Some functions may benefit from extraction"
                : "Good complexity level",
          }, null, 2),
        },
      ],
    };
  }
);

// Tool 2: 项目级质量报告
server.tool(
  "quality-report",
  "Generate a quality report for all source files in a directory",
  {
    dirPath: z.string().describe("Directory to scan"),
    extensions: z.string().default(".ts,.tsx,.js,.jsx").describe("File extensions to include"),
  },
  async ({ dirPath, extensions }) => {
    const exts = extensions.split(",").map((e) => e.trim());
    const files: string[] = [];

    async function walk(dir: string) {
      const entries = await fs.readdir(dir, { withFileTypes: true });
      for (const entry of entries) {
        const fullPath = path.join(dir, entry.name);
        if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
          await walk(fullPath);
        } else if (entry.isFile() && exts.some((ext) => entry.name.endsWith(ext))) {
          files.push(fullPath);
        }
      }
    }

    await walk(dirPath);

    const totalFiles = files.length;
    let totalLines = 0;
    let highComplexity = 0;

    for (const file of files.slice(0, 100)) {
      const content = await fs.readFile(file, "utf-8");
      totalLines += content.split("\n").length;
      const branchCount = (content.match(/\b(if|else if|for|while|case|catch)\b/g) || []).length;
      if (branchCount > 20) highComplexity++;
    }

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            directory: dirPath,
            summary: {
              filesScanned: totalFiles,
              totalLinesOfCode: totalLines,
              highComplexityFiles: highComplexity,
              avgLinesPerFile: totalFiles > 0 ? Math.round(totalLines / totalFiles) : 0,
              healthScore: Math.max(0, 100 - highComplexity * 10),
            },
          }, null, 2),
        },
      ],
    };
  }
);

// 启动Server
const transport = new StdioServerTransport();
await server.connect(transport);

cd mcp/quality-server

# 安装依赖
npm install

# 创建tsconfig.json
cat > tsconfig.json << 'TSCONFIG'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}
TSCONFIG

# 编译
npx tsc

# 验证编译产物
ls dist/index.js

name: code-reviewer
description: "Specialized agent for deep code review with quality enforcement"
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Task

instructions: |
  You are a code quality reviewer agent. Your job is to:

  1. Scan the specified files or directories
  2. Use the complexity-analyzer MCP tools to get metrics
  3. Read the actual code and identify specific issues
  4. Generate a structured review report

  Output format:
  ## Review Summary
  - Files reviewed: N
  - Issues found: N (🔴 Critical: N, 🟡 Warning: N, 🔵 Info: N)
  - Quality score: N/100

  ## Issues
  For each issue:
  - **File**: path/to/file:line
  - **Severity**: 🔴/🟡/🔵
  - **Category**: Security/Performance/Maintainability/Testing
  - **Description**: What's wrong
  - **Suggestion**: How to fix (with code snippet)

  ## Top Priority Fixes
  List the 3 most impactful fixes to make.

---
name: quality-check
description: Run a full quality check on the codebase
---

Run a comprehensive code quality check:

1. Use the `quality-report` MCP tool to scan the current directory
2. For any files with HIGH complexity, use `analyze-complexity` for details
3. Apply the `/review` skill to the top 3 most complex files
4. Generate a summary with:
   - Overall health score
   - Top issues by severity
   - Suggested next actions
5. Save the report to `quality-report.md`

# Code Quality Guardian Plugin

This plugin enforces code quality standards.

## Available Commands
- `/review` — Run a code quality review
- `/fix-quality` — Auto-fix quality issues  
- `/quality-check` — Full quality check with report

## MCP Tools
- `analyze-complexity` — Analyze single file complexity
- `quality-report` — Generate project-level quality report

## Auto-formatting
Files are automatically formatted after edits (PostToolUse hook).
Dangerous commands are blocked before execution (PreToolUse hook).

## Quality Standards
- Max cyclomatic complexity: 10 per function
- Min comment ratio: 10%
- All files must pass linting

# 在Plugin项目根目录
cd code-quality-guardian

# 方式1：通过Git URL安装（推荐，模拟真实安装流程）
claude plugin add https://github.com/your-org/code-quality-guardian

# 方式2：通过本地路径安装（开发调试用）
claude plugin add ./path/to/code-quality-guardian

# 验证安装
claude plugin list
# 应显示：
# code-quality-guardian  1.0.0  Code quality enforcement...

# 查看已注册的Skills
claude /review --help
claude /fix-quality --help
claude /quality-check --help

# 在安装了Plugin的项目中启动Claude Code
claude

# 测试PostToolUse Hook：让Claude编辑一个文件
# 输入: "Edit src/utils.ts and add a formatDate function"
# 预期：文件编辑后自动触发格式化

# 测试PreToolUse Hook：尝试运行危险命令
# 输入: "Run rm -rf /tmp/test"
# 预期：命令被阻止，显示"Blocked dangerous command"

# 检查MCP Server是否正确注册
claude /mcp
# 应显示 complexity-analyzer server，状态为 connected

# 手动测试MCP工具
# 在Claude Code中输入:
# "Use the analyze-complexity tool on src/main.ts"
# 预期：返回文件的复杂度指标JSON

# 查看Claude Code日志
cat ~/.claude/logs/*.log | grep "hook"

# 在Hook脚本中添加调试输出
echo "DEBUG: file=$FILE_PATH" >&2

# 安装MCP Inspector
npx @modelcontextprotocol/inspector node mcp/quality-server/dist/index.js

# 在浏览器中打开Inspector UI
# 可以手动调用每个工具并查看响应

# 1. 确保所有组件就绪
git add -A
git commit -m "feat: code-quality-guardian v1.0.0"

# 2. 打版本标签
git tag v1.0.0
git push origin main --tags

# 3. 确保package.json有正确的repository字段
# 4. README.md包含安装说明

# Code Quality Guardian

Auto-format, lint, complexity analysis, and code review for Claude Code.

## Install

claude plugin add https://github.com/your-org/code-quality-guardian

## Commands
| Command | Description |
|---------|-------------|
| `/review` | Code quality review |
| `/fix-quality` | Auto-fix issues |
| `/quality-check` | Full quality report |

## MCP Tools
- `analyze-complexity` — Per-file complexity metrics
- `quality-report` — Project-wide quality scan

## Hooks
- Auto-format on file edit (Prettier/Black/gofmt)
- Block dangerous shell commands

# 提交到Anthropic官方目录（需要审核）
# Fork https://github.com/anthropics/claude-code-plugins
# 添加你的Plugin信息到registry.json
# 提交PR

// marketplace.json
{
  "name": "Team Plugin Hub",
  "plugins": [
    {
      "name": "code-quality-guardian",
      "version": "1.0.0",
      "description": "Code quality enforcement",
      "repository": "https://github.com/your-org/code-quality-guardian",
      "tags": ["quality", "linting", "review"]
    }
  ]
}

# 将marketplace.json托管到内部服务器
# 团队成员配置Marketplace源
claude config set pluginMarketplaces '["https://internal.example.com/marketplace.json"]'

# 然后直接从Marketplace安装
claude plugin add code-quality-guardian

# 修改代码后更新版本号
# 在plugin.json中: "version": "1.1.0"

git commit -am "feat: add Python complexity analysis"
git tag v1.1.0
git push origin main --tags

# 已安装的用户更新
claude plugin update code-quality-guardian

flowchart TB
    subgraph 开发阶段["开发阶段"]
        A[创建项目结构] --> B[编写plugin.json]
        B --> C[实现Skills]
        C --> D[实现Hooks]
        D --> E[实现MCP Server]
        E --> F[定义Agents]
        F --> G[编写Commands]
    end

    subgraph 测试阶段["测试阶段"]
        G --> H[本地安装Plugin]
        H --> I[验证Skills注册]
        I --> J[触发Hook测试]
        J --> K[MCP Inspector测试]
        K --> L[端到端集成测试]
    end

    subgraph 发布阶段["发布阶段"]
        L --> M[Git tag版本]
        M --> N{分发渠道}
        N --> O[官方Directory]
        N --> P[自建Marketplace]
        N --> Q[私有Git仓库]
    end

    subgraph 使用阶段["使用阶段"]
        O --> R[claude plugin add]
        P --> R
        Q --> R
        R --> S[团队协作开发]
    end

    style 开发阶段 fill:#E8F5E9
    style 测试阶段 fill:#E3F2FD
    style 发布阶段 fill:#FFF3E0
    style 使用阶段 fill:#F3E5F5

#!/usr/bin/env bash
# hooks/smart-format.sh - 根据项目类型选择格式化工具

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[[ -z "$FILE_PATH" ]] && exit 0

# 检测项目根目录
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")

# TypeScript/JavaScript项目
if [[ -f "$PROJECT_ROOT/tsconfig.json" ]] || [[ -f "$PROJECT_ROOT/package.json" ]]; then
  case "$FILE_PATH" in
    *.ts|*.tsx|*.js|*.jsx)
      npx --yes prettier --write "$FILE_PATH" 2>/dev/null || true
      npx --yes eslint --fix "$FILE_PATH" 2>/dev/null || true
      ;;
  esac
# Python项目
elif [[ -f "$PROJECT_ROOT/pyproject.toml" ]] || [[ -f "$PROJECT_ROOT/setup.py" ]]; then
  case "$FILE_PATH" in
    *.py)
      command -v black &>/dev/null && black "$FILE_PATH" 2>/dev/null || true
      command -v isort &>/dev/null && isort "$FILE_PATH" 2>/dev/null || true
      ;;
  esac
fi

// MCP Server内部可以读取Plugin上下文
const pluginName = process.env.CLAUDE_PLUGIN_NAME;
const pluginVersion = process.env.CLAUDE_PLUGIN_VERSION;
const projectRoot = process.env.CLAUDE_PROJECT_ROOT;

// 基于项目上下文提供更智能的分析
server.tool(
  "smart-analyze",
  "Context-aware code analysis",
  { target: z.string().describe("File or directory to analyze") },
  async ({ target }) => {
    const fullPath = path.join(projectRoot || ".", target);
    // ... 基于完整项目上下文的分析逻辑
  }
);