plugins

Plugins 允许通过 TypeScript 代码扩展 Claude Code 的功能。

设计理念

Skills 提供上下文，但无法添加新功能。Plugins 提供完整的扩展能力：

• 添加新工具

• 修改核心行为

• 集成外部系统

• 自定义 UI 组件

Plugin 结构

基本格式

// .kiro/plugins/my-plugin.ts

import { Plugin, Tool } from '@anthropic-ai/claude-code';

export default {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',
  
  // 提供的工具
  tools: [
    new MyCustomTool(),
  ],
  
  // 生命周期钩子
  onLoad: async (context) => {
    console.log('Plugin loaded');
  },
  
  onUnload: async () => {
    console.log('Plugin unloaded');
  },
} satisfies Plugin;

Plugin 接口

interface Plugin {
  name: string;
  version: string;
  description: string;
  
  // 工具
  tools?: Tool[];
  
  // 生命周期
  onLoad?: (context: PluginContext) => Promise<void>;
  onUnload?: () => Promise<void>;
  
  // 配置
  config?: PluginConfig;
}

创建自定义工具

实现 Tool 接口

import { Tool, ToolContext, ToolResult } from '@anthropic-ai/claude-code';
import { z } from 'zod';

class MyCustomTool implements Tool {
  name = 'myTool';
  description = 'Does something useful';
  
  inputSchema = z.object({
    input: z.string(),
  });
  
  async execute(
    input: z.infer<typeof this.inputSchema>,
    context: ToolContext
  ): Promise<ToolResult> {
    try {
      // 工具逻辑
      const result = await doSomething(input.input);
      
      return {
        success: true,
        output: result,
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }
}

使用外部库

import axios from 'axios';

class APITool implements Tool {
  name = 'callAPI';
  description = 'Call external API';
  
  inputSchema = z.object({
    endpoint: z.string(),
    method: z.enum(['GET', 'POST']),
    data: z.any().optional(),
  });
  
  async execute(input, context) {
    const response = await axios({
      method: input.method,
      url: input.endpoint,
      data: input.data,
    });
    
    return {
      success: true,
      output: JSON.stringify(response.data, null, 2),
    };
  }
}

Plugin 生命周期

onLoad

Plugin 加载时调用：

onLoad: async (context: PluginContext) => {
  // 初始化资源
  await initializeDatabase();
  
  // 注册事件监听
  context.on('fileEdited', handleFileEdit);
  
  // 加载配置
  const config = await loadConfig();
}

onUnload

Plugin 卸载时调用：

onUnload: async () => {
  // 清理资源
  await closeDatabase();
  
  // 保存状态
  await saveState();
}

Plugin 配置

配置文件

// .kiro/plugins/my-plugin.config.json
{
  "apiKey": "...",
  "endpoint": "https://api.example.com",
  "timeout": 5000
}

读取配置

async function loadPluginConfig(
  pluginName: string
): Promise<any> {
  const configPath = path.join(
    '.kiro',
    'plugins',
    `${pluginName}.config.json`
  );
  
  const content = await fs.readFile(configPath, 'utf-8');
  return JSON.parse(content);
}

示例 Plugin

数据库查询工具

// .kiro/plugins/database.ts

import { Plugin, Tool } from '@anthropic-ai/claude-code';
import { Pool } from 'pg';
import { z } from 'zod';

class DatabaseQueryTool implements Tool {
  name = 'queryDatabase';
  description = 'Execute SQL query';
  
  inputSchema = z.object({
    query: z.string(),
  });
  
  private pool: Pool;
  
  constructor(pool: Pool) {
    this.pool = pool;
  }
  
  async execute(input, context) {
    try {
      const result = await this.pool.query(input.query);
      
      return {
        success: true,
        output: JSON.stringify(result.rows, null, 2),
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }
}

export default {
  name: 'database-plugin',
  version: '1.0.0',
  description: 'Database query tools',
  
  tools: [],
  
  onLoad: async (context) => {
    const config = await loadPluginConfig('database');
    
    const pool = new Pool({
      host: config.host,
      database: config.database,
      user: config.user,
      password: config.password,
    });
    
    // 动态添加工具
    context.registerTool(new DatabaseQueryTool(pool));
  },
  
  onUnload: async () => {
    await pool.end();
  },
} satisfies Plugin;

Plugin 发现

自动加载

async function loadPlugins(): Promise<Plugin[]> {
  const pluginsDir = path.join(context.cwd, '.kiro', 'plugins');
  const files = await fs.readdir(pluginsDir);
  
  const plugins = [];
  
  for (const file of files) {
    if (file.endsWith('.ts') || file.endsWith('.js')) {
      const plugin = await import(path.join(pluginsDir, file));
      plugins.push(plugin.default);
    }
  }
  
  return plugins;
}

下一步

• 了解 MCP 集成 的外部工具

• 探索 Hooks 系统 的自动化

• 查看 工具接口 的详细设计