Claude Code 中文教程网

外观

21.3 插件开发 API

约 1586 字大约 5 分钟

概述

Claude Code 提供了一套强大的插件开发 API，允许开发者扩展和定制系统功能。本章节将详细介绍核心 API 接口、使用方法和最佳实践。

核心 API 接口

IPlugin 接口

IPlugin 是所有插件必须实现的核心接口：

/**
 * 插件接口
 */
export interface IPlugin {
  /**
   * 插件元数据
   */
  metadata: PluginMetadata;

  /**
   * 插件配置
   */
  config: PluginConfig;

  /**
   * 插件状态
   */
  status: PluginStatus;

  /**
   * 初始化插件
   * @param context 插件上下文
   */
  initialize(context: PluginContext): Promise<void>;

  /**
   * 启动插件
   */
  start(): Promise<void>;

  /**
   * 停止插件
   */
  stop(): Promise<void>;

  /**
   * 清理插件
   */
  cleanup(): Promise<void>;

  /**
   * 处理插件消息
   * @param message 消息内容
   */
  handleMessage(message: PluginMessage): Promise<PluginMessageResponse>;

  /**
   * 获取插件功能
   */
  getCapabilities(): PluginCapabilities;
}

PluginMetadata 接口

插件元数据定义了插件的基本信息：

/**
 * 插件元数据
 */
export interface PluginMetadata {
  /**
   * 插件唯一标识符
   */
  id: string;

  /**
   * 插件名称
   */
  name: string;

  /**
   * 插件版本
   */
  version: string;

  /**
   * 插件描述
   */
  description: string;

  /**
   * 插件作者
   */
  author?: string;

  /**
   * 插件许可证
   */
  license?: string;

  /**
   * 插件主页
   */
  homepage?: string;

  /**
   * 插件依赖
   */
  dependencies?: PluginDependency[];

  /**
   * 插件兼容性
   */
  compatibility?: PluginCompatibility;
}

PluginContext 接口

插件上下文提供了插件与系统交互的能力：

/**
 * 插件上下文
 */
export interface PluginContext {
  /**
   * 系统服务提供者
   */
  services: ServiceProvider;

  /**
   * 日志服务
   */
  logger: Logger;

  /**
   * 配置服务
   */
  configService: ConfigService;

  /**
   * 事件总线
   */
  eventBus: EventBus;

  /**
   * 插件管理器
   */
  pluginManager: PluginManager;

  /**
   * 资源管理器
   */
  resourceManager: ResourceManager;

  /**
   * 获取系统信息
   */
  getSystemInfo(): SystemInfo;

  /**
   * 发送系统通知
   */
  sendNotification(notification: Notification): Promise<void>;

  /**
   * 执行系统命令
   */
  executeCommand(command: Command): Promise<CommandResult>;
}

工具 API

ITool 接口

ITool 接口用于创建可复用的工具：

/**
 * 工具接口
 */
export interface ITool {
  /**
   * 工具元数据
   */
  metadata: ToolMetadata;

  /**
   * 工具配置
   */
  config: ToolConfig;

  /**
   * 执行工具
   * @param parameters 工具参数
   */
  execute(parameters: ToolParameters): Promise<ToolResult>;

  /**
   * 验证参数
   * @param parameters 工具参数
   */
  validate(parameters: ToolParameters): ToolValidationResult;

  /**
   * 获取工具帮助信息
   */
  getHelp(): ToolHelp;
}

ToolMetadata 接口

/**
 * 工具元数据
 */
export interface ToolMetadata {
  /**
   * 工具唯一标识符
   */
  id: string;

  /**
   * 工具名称
   */
  name: string;

  /**
   * 工具描述
   */
  description: string;

  /**
   * 工具类型
   */
  type: ToolType;

  /**
   * 工具参数
   */
  parameters: ToolParameter[];

  /**
   * 工具返回结果
   */
  returns: ToolReturn;

  /**
   * 工具示例
   */
  examples: ToolExample[];
}

命令 API

ICommand 接口

ICommand 接口用于实现 CLI 命令：

/**
 * 命令接口
 */
export interface ICommand {
  /**
   * 命令元数据
   */
  metadata: CommandMetadata;

  /**
   * 执行命令
   * @param args 命令参数
   * @param options 命令选项
   */
  execute(args: string[], options: CommandOptions): Promise<CommandResult>;

  /**
   * 验证命令参数
   * @param args 命令参数
   * @param options 命令选项
   */
  validate(args: string[], options: CommandOptions): CommandValidationResult;

  /**
   * 获取命令帮助信息
   */
  getHelp(): CommandHelp;
}

CommandMetadata 接口

/**
 * 命令元数据
 */
export interface CommandMetadata {
  /**
   * 命令名称
   */
  name: string;

  /**
   * 命令描述
   */
  description: string;

  /**
   * 命令别名
   */
  aliases?: string[];

  /**
   * 命令参数
   */
  arguments: CommandArgument[];

  /**
   * 命令选项
   */
  options: CommandOption[];

  /**
   * 命令示例
   */
  examples: CommandExample[];

  /**
   * 命令类别
   */
  category?: string;

  /**
   * 命令可见性
   */
  visible?: boolean;
}

钩子 API

IHook 接口

IHook 接口用于实现事件驱动功能：

/**
 * 钩子接口
 */
export interface IHook {
  /**
   * 钩子元数据
   */
  metadata: HookMetadata;

  /**
   * 执行钩子
   * @param context 钩子上下文
   */
  execute(context: HookContext): Promise<HookResult>;

  /**
   * 注册钩子
   */
  register(): void;

  /**
   * 注销钩子
   */
  unregister(): void;
}

HookMetadata 接口

/**
 * 钩子元数据
 */
export interface HookMetadata {
  /**
   * 钩子名称
   */
  name: string;

  /**
   * 钩子描述
   */
  description: string;

  /**
   * 钩子类型
   */
  type: HookType;

  /**
   * 钩子触发点
   */
  triggerPoint: string;

  /**
   * 钩子优先级
   */
  priority: number;

  /**
   * 钩子参数
   */
  parameters: HookParameter[];

  /**
   * 钩子返回结果
   */
  returns: HookReturn;
}

API 使用示例

创建简单插件

import { IPlugin, PluginMetadata, PluginContext } from '@claude-code/plugin-sdk';

export class HelloWorldPlugin implements IPlugin {
  metadata: PluginMetadata = {
    id: 'hello-world-plugin',
    name: 'Hello World Plugin',
    version: '1.0.0',
    description: 'A simple hello world plugin',
    author: 'Claude Code Team',
    license: 'MIT'
  };

  config: any = {};
  status: any = {};

  async initialize(context: PluginContext): Promise<void> {
    context.logger.info('Hello World Plugin initialized');
  }

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

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

  async cleanup(): Promise<void> {
    console.log('Hello World Plugin cleaned up');
  }

  async handleMessage(message: any): Promise<any> {
    return { message: 'Hello from plugin' };
  }

  getCapabilities(): any {
    return { features: ['hello-world'] };
  }
}

创建工具

import { ITool, ToolMetadata, ToolParameters } from '@claude-code/plugin-sdk';

export class CalculatorTool implements ITool {
  metadata: ToolMetadata = {
    id: 'calculator-tool',
    name: 'Calculator Tool',
    description: 'A simple calculator tool',
    type: 'utility',
    parameters: [
      { name: 'operation', type: 'string', description: 'Operation to perform' },
      { name: 'a', type: 'number', description: 'First number' },
      { name: 'b', type: 'number', description: 'Second number' }
    ],
    returns: { type: 'number', description: 'Calculation result' },
    examples: [
      { input: { operation: 'add', a: 1, b: 2 }, output: 3 },
      { input: { operation: 'multiply', a: 3, b: 4 }, output: 12 }
    ]
  };

  config: any = {};

  async execute(parameters: ToolParameters): Promise<any> {
    const { operation, a, b } = parameters;
    
    switch (operation) {
      case 'add':
        return a + b;
      case 'subtract':
        return a - b;
      case 'multiply':
        return a * b;
      case 'divide':
        return a / b;
      default:
        throw new Error(`Unknown operation: ${operation}`);
    }
  }

  validate(parameters: ToolParameters): any {
    if (!parameters.operation) {
      return { valid: false, error: 'Operation is required' };
    }
    return { valid: true };
  }

  getHelp(): any {
    return { description: 'A simple calculator tool' };
  }
}

API 最佳实践

1. 接口设计原则

  • 单一职责：每个接口只负责一个功能
  • 最小依赖：减少接口之间的耦合
  • 明确契约：清晰定义输入输出
  • 版本管理：使用语义化版本控制

2. 错误处理

// 推荐的错误处理方式
try {
  // 执行操作
} catch (error) {
  context.logger.error('Operation failed', error);
  throw new PluginError('OPERATION_FAILED', 'Failed to perform operation', error);
}

3. 性能优化

  • 异步操作：使用 Promise 和 async/await
  • 缓存策略：缓存频繁使用的数据
  • 批量处理：减少系统调用次数
  • 资源管理：及时释放资源

4. 安全性

  • 输入验证：验证所有外部输入
  • 权限控制：检查用户权限
  • 数据加密：保护敏感数据
  • 审计日志：记录重要操作

常见问题

Q: 如何处理 API 版本兼容性？

A: 使用版本号管理 API，提供向后兼容的实现：

// 版本兼容示例
if (context.getSystemInfo().version >= '2.0.0') {
  // 使用新 API
} else {
  // 使用兼容 API
}

Q: 如何扩展现有 API？

A: 使用装饰器或适配器模式扩展 API：

// 使用装饰器扩展 API
@decorate(ITool)
export class EnhancedTool extends BaseTool {
  // 扩展功能
}

Q: 如何调试 API 调用？

A: 使用日志和调试工具：

// 调试日志
context.logger.debug('API call', { parameters, result });

总结

Claude Code 插件开发 API 提供了一套完整的扩展机制，允许开发者创建强大的插件和工具。通过遵循最佳实践和设计原则，可以创建出高质量、可维护的插件。

下一章将介绍高级插件开发技术，包括插件通信、数据持久化和性能优化。

公众号
小红书