21.1 插件开发环境搭建

21.1.1 系统要求#

基本要求#

软件依赖#

21.1.2 安装开发工具#

1. 安装 Node.js#

推荐使用 nvm 进行 Node.js 版本管理：

bash
复制
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# 安装并使用 Node.js 18
nvm install 18
nvm use 18

# 验证安装
node --version
npm --version

2. 安装 Python#

macOS

bash
复制
brew install python@3.10

Ubuntu/Debian

bash
复制
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip

Windows

从 Python 官方网站 下载安装程序。

bash
复制
# 验证安装
python3 --version
pip3 --version

3. 安装 Git#

macOS

bash
复制
brew install git

Ubuntu/Debian

bash
复制
sudo apt install git

Windows

从 Git 官方网站 下载安装程序。

bash
复制
# 验证安装
git --version

4. 安装 Claude Code CLI#

bash
复制
# 使用 npm 安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

21.1.3 安装插件开发工具#

1. 安装插件脚手架工具#

bash
复制
# 安装插件脚手架
npm install -g @claude-code/plugin-scaffold

# 验证安装
claude-plugin-scaffold --version

2. 安装插件开发工具#

bash
复制
# 安装开发工具
npm install -g @claude-code/plugin-devtools

# 验证安装
claude-plugin-devtools --version

3. 安装插件测试工具#

bash
复制
# 安装测试工具
npm install -g @claude-code/plugin-test

# 验证安装
claude-plugin-test --version

21.1.4 创建开发环境#

1. 创建项目目录#

bash
复制
# 创建插件项目目录
mkdir my-plugin
cd my-plugin

# 初始化项目
npm init -y

2. 安装开发依赖#

bash
复制
# 安装插件 SDK
npm install @claude-code/plugin-sdk --save-dev

# 安装 TypeScript（推荐）
npm install typescript @types/node --save-dev

# 安装测试框架
npm install jest @types/jest --save-dev

# 安装代码检查工具
npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

3. 配置 TypeScript#

json
复制
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

4. 配置 ESLint#

json
复制
// .eslintrc.json
{
  "parser": "@typescript-eslint/parser",
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "warn"
  }
}

5. 配置 Jest#

json
复制
// jest.config.json
{
  "preset": "ts-jest",
  "testEnvironment": "node",
  "roots": ["<rootDir>/src"],
  "testMatch": ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
  "collectCoverageFrom": [
    "src/**/*.ts",
    "!src/**/*.d.ts",
    "!src/**/*.test.ts"
  ]
}

6. 配置 package.json#

json
复制
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My Claude Code Plugin",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint src/**/*.ts",
    "lint:fix": "eslint src/**/*.ts --fix",
    "clean": "rm -rf dist"
  },
  "keywords": [
    "claude-code",
    "plugin"
  ],
  "author": "Your Name",
  "license": "MIT",
  "devDependencies": {
    "@claude-code/plugin-sdk": "^1.0.0",
    "@types/jest": "^29.0.0",
    "@types/node": "^18.0.0",
    "@typescript-eslint/eslint-plugin": "^5.0.0",
    "@typescript-eslint/parser": "^5.0.0",
    "eslint": "^8.0.0",
    "jest": "^29.0.0",
    "ts-jest": "^29.0.0",
    "typescript": "^4.9.0"
  }
}

21.1.5 创建插件项目结构#

标准项目结构#

bash
复制
my-plugin/
├── src/
│   ├── index.ts              # 插件入口
│   ├── plugin.ts            # 插件主类
│   ├── tools/               # 工具定义
│   │   ├── tool1.ts
│   │   └── tool2.ts
│   ├── commands/            # 命令定义
│   │   ├── command1.ts
│   │   └── command2.ts
│   ├── utils/               # 工具函数
│   │   └── helpers.ts
│   └── types/               # 类型定义
│       └── index.ts
├── __tests__/               # 测试文件
│   ├── plugin.test.ts
│   ├── tools/
│   │   └── tool1.test.ts
│   └── commands/
│       └── command1.test.ts
├── dist/                    # 编译输出
├── templates/               # 模板文件
├── docs/                    # 文档
├── examples/                # 示例
├── .eslintrc.json          # ESLint 配置
├── .gitignore              # Git 忽略文件
├── jest.config.json        # Jest 配置
├── package.json            # 项目配置
├── plugin.yaml             # 插件清单
├── tsconfig.json           # TypeScript 配置
└── README.md               # 项目说明

创建目录结构#

bash
复制
# 创建目录结构
mkdir -p src/tools src/commands src/utils src/types __tests__/tools __tests__/commands dist templates docs examples

# 创建基本文件
touch src/index.ts src/plugin.ts src/types/index.ts
touch .eslintrc.json jest.config.json tsconfig.json plugin.yaml README.md
touch .gitignore

配置 .gitignore#

gitignore
复制

# Dependencies
node_modules/

# Build output
dist/

# Test coverage
coverage/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

# Environment
.env
.env.local

# Temporary files
*.tmp
.cache/

21.1.6 配置开发环境#

1. 配置 IDE#

VS Code 配置

json
复制
// .vscode/settings.json
{
"typescript.tsdk": "node_modules/typescript/lib",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"files.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/coverage": true
}
}

VS Code 扩展推荐

json
复制
// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next"
  ]
}

VS Code 任务

json
复制
// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "build",
      "problemMatcher": "$tsc",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "type": "npm",
      "script": "test",
      "problemMatcher": "$tsc",
      "group": {
        "kind": "test",
        "isDefault": true
      }
    },
    {
      "type": "npm",
      "script": "lint",
      "problemMatcher": "$eslint-stylish",
      "group": "build"
    }
  ]
}

2. 配置调试#

json
复制
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Plugin",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "name": "Debug Tests",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test:watch"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

3. 配置 Git Hooks#

bash
复制
# 安装 husky
npm install husky --save-dev

# 初始化 husky
npx husky install

# 添加 pre-commit hook
npx husky add .husky/pre-commit "npm run lint && npm run test"

21.1.7 创建插件清单#

plugin.yaml 配置#

yaml
复制
# plugin.yaml
name: my-plugin
version: 1.0.0
description: My Claude Code Plugin
author: Your Name
license: MIT
homepage: https://github.com/yourname/my-plugin
repository: https://github.com/yourname/my-plugin

# 插件入口
main: dist/index.js
types: dist/index.d.ts

# 插件权限
permissions:
  file:
    - read: "/"
  network:
    - https: ["api.example.com"]

# 插件依赖
dependencies:
  claude-code: ">=1.0.0"

# 开发依赖
devDependencies:
  typescript: "^4.9.0"
  jest: "^29.0.0"

# 插件配置
config:
  timeout: 30
  retries: 3

# 插件元数据
metadata:
  category: development
  tags:
    - code-generation
    - productivity
  keywords:
    - plugin
    - claude-code

21.1.8 验证开发环境#

1. 创建测试文件#

typescript
复制
// src/index.ts
export * from './plugin';

typescript
复制
// src/plugin.ts
import { Plugin } from '@claude-code/plugin-sdk';

export class MyPlugin extends Plugin {
  constructor() {
    super({
      name: 'my-plugin',
      version: '1.0.0',
      description: 'My Claude Code Plugin'
    });
  }

  async initialize(): Promise<void> {
    console.log('Plugin initialized');
  }

  async start(): Promise<void> {
    console.log('Plugin started');
  }

  async stop(): Promise<void> {
    console.log('Plugin stopped');
  }
}

2. 编译项目#

bash
复制
# 编译 TypeScript
npm run build

# 检查编译输出
ls -la dist/

3. 运行测试#

bash
复制
# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test -- --coverage

4. 运行代码检查#

bash
复制
# 运行 ESLint
npm run lint

# 自动修复问题
npm run lint:fix

21.1.9 开发工作流#

1. 开发流程#

bash
复制
# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发功能
# 编辑代码...

# 3. 运行测试
npm test

# 4. 运行代码检查
npm run lint

# 5. 编译项目
npm run build

# 6. 提交更改
git add .
git commit -m "Add new feature"

# 7. 推送到远程
git push origin feature/new-feature

# 8. 创建 Pull Request

2. 调试流程#

bash
复制
# 1. 启动开发模式
npm run dev
# 2. 在 VS Code 中设置断点
# 3. 按 F5 启动调试
# 4. 在调试控制台中查看输出

3. 测试流程#

bash
复制
# 1. 编写测试
# 创建测试文件...

# 2. 运行测试
npm test

# 3. 查看测试覆盖率
npm run test -- --coverage

# 4. 运行特定测试
npm test -- --testNamePattern="MyPlugin"

21.1.10 常见问题解决#

1. TypeScript 编译错误#

bash
复制
# 清理编译缓存
npm run clean
npm run build

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

2. 测试失败#

bash
复制
# 更新 Jest 配置
npm install --save-dev jest@latest ts-jest@latest

# 清理 Jest 缓存
npm test -- --clearCache

3. ESLint 错误#

bash
复制
# 自动修复 ESLint 错误
npm run lint:fix

# 更新 ESLint 配置
npm install --save-dev @typescript-eslint/parser@latest @typescript-eslint/eslint-plugin@latest

4. 插件无法加载#

bash
复制
# 检查插件清单
cat plugin.yaml

# 验证编译输出
ls -la dist/

# 重新编译
npm run clean
npm run build