# 插件与技能系统

Claude Code 提供了强大的插件系统和技能系统来扩展功能。本文档详细介绍这两个系统的架构和实现。

## 1. 插件系统 (plugins/)

### 1.1 插件加载机制

Claude Code 的插件系统支持内置插件和第三方插件。

**关键文件：**
- `/src/plugins/builtinPlugins.ts` - 内置插件注册表
- `/src/utils/plugins/pluginLoader.ts` - 插件加载器
- `/src/utils/plugins/loadPluginHooks.ts` - 插件钩子加载

**插件结构：**
```typescript
interface LoadedPlugin {
  name: string                    // 插件名称
  manifest: {                     // 插件清单
    name: string
    description: string
    version: string
  }
  path: string                   // 插件路径
  source: string                 // 来源标识
  repository: string             // 仓库地址
  enabled: boolean               // 是否启用
  isBuiltin: boolean             // 是否为内置插件
  hooksConfig?: HooksSettings    // 钩子配置
  mcpServers?: MCPServer[]       // MCP 服务器配置
}
```

### 1.2 内置插件 (builtinPlugins.ts)

内置插件是与 Claude Code CLI 一起打包的插件，可以通过 `/plugin` UI 启用/禁用。

**与 Bundled Skills 的区别：**
| 特性 | 内置插件 | Bundled Skills |
|------|----------|----------------|
| 出现位置 | `/plugin` UI 的 "Built-in" 部分 | `/skills` 列表 |
| 用户控制 | 可启用/禁用（持久化到用户设置） | 始终可用 |
| 组件类型 | 可提供多种组件（skills, hooks, MCP servers） | 仅 skills |

**插件 ID 格式：**
- 内置插件：`{name}@builtin`
- 市场插件：`{name}@{marketplace}`

**核心函数：**
```typescript
// 注册内置插件
registerBuiltinPlugin(definition: BuiltinPluginDefinition): void

// 检查是否为内置插件
isBuiltinPluginId(pluginId: string): boolean

// 获取所有内置插件（分启用/禁用）
getBuiltinPlugins(): { enabled: LoadedPlugin[]; disabled: LoadedPlugin[] }

// 获取内置插件提供的技能命令
getBuiltinPluginSkillCommands(): Command[]
```

### 1.3 插件注册和执行流程

**注册流程：**
1. 在启动时调用 `initBuiltinPlugins()` 注册所有内置插件
2. 插件定义包含：`name`, `description`, `version`, `isAvailable()`, `defaultEnabled`, `skills`, `hooks`, `mcpServers`

**加载流程 (loadPluginHooks.ts)：**
```typescript
export const loadPluginHooks = memoize(async (): Promise<void> => {
  const { enabled } = await loadAllPluginsCacheOnly()
  // 转换插件钩子配置为匹配器
  const pluginMatchers = convertPluginHooksToMatchers(plugin)
  // 清除旧钩子并注册新钩子（原子操作）
  clearRegisteredPluginHooks()
  registerHookCallbacks(allPluginHooks)
})
```

**钩子事件类型：**
- `PreToolUse` - 工具执行前
- `PostToolUse` - 工具执行后
- `PermissionDenied` - 权限被拒绝
- `SessionStart/SessionEnd` - 会话开始/结束
- `SubagentStart/SubagentStop` - 子智能体启动/停止
- `TaskCreated/TaskCompleted` - 任务创建/完成

### 1.4 第三方插件支持

第三方插件通过市场安装，支持以下功能：
- 自定义 skills
- 钩子系统
- MCP 服务器

## 2. 技能系统 (skills/)

### 2.1 技能定义和格式

**技能定义结构 (BundledSkillDefinition)：**
```typescript
type BundledSkillDefinition = {
  name: string                    // 技能名称
  description: string             // 技能描述
  aliases?: string[]              // 别名
  whenToUse?: string              // 使用建议
  argumentHint?: string           // 参数提示
  allowedTools?: string[]         // 允许的工具
  model?: string                  // 模型覆盖
  disableModelInvocation?: boolean // 禁用模型调用
  userInvocable?: boolean         // 用户可调用
  isEnabled?: () => boolean      // 启用检查函数
  hooks?: HooksSettings           // 钩子设置
  context?: 'inline' | 'fork'     // 执行上下文
  agent?: string                  // 代理类型
  files?: Record<string, string>  // 参考文件
  getPromptForCommand: (args: string, context: ToolUseContext) => Promise<ContentBlockParam[]>
}
```

### 2.2 技能执行机制 (SkillTool)

**关键文件：** `/src/tools/SkillTool/SkillTool.ts`

**执行模式：**

1. **Inline 模式（内联执行）**
   - 技能内容直接注入对话
   - 使用 `processPromptSlashCommand` 处理
   - 支持 `!command` 和 `$ARGUMENTS` 扩展

2. **Fork 模式（分叉执行）**
   - 在独立子智能体中运行技能
   - 拥有独立 token 预算
   - 通过 `executeForkedSkill` 实现

**SkillTool 输入/输出：**
```typescript
// 输入
input: {
  skill: string   // 技能名称，如 "commit", "review-pr"
  args?: string   // 可选参数
}

// 输出
output: {
  success: boolean
  commandName: string
  status: 'inline' | 'forked'
  agentId?: string  // fork 模式下的子智能体 ID
  result?: string   // fork 模式下的执行结果
}
```

**权限检查：**
- 技能执行需要权限检查
- 支持规则匹配（前缀匹配如 `review:*`）
- 自动允许安全属性的技能

### 2.3 内置技能

**位置：** `/src/skills/bundled/`

**内置技能列表：**
| 技能名 | 描述 |
|--------|------|
| `remember` | 记忆技能 |
| `loremIpsum` | 生成占位文本 |
| `verify` | 验证技能 |
| `loop` | 循环执行技能 |
| `claudeApi` | Claude API 相关 |
| `debug` | 调试技能 |
| `stuck` | 处理卡住情况 |
| `batch` | 批量处理 |
| `updateConfig` | 更新配置 |
| `keybindings` | 快捷键 |
| `simplify` | 简化代码 |
| `skillify` | 技能化 |

### 2.4 用户自定义技能

用户可以在 `~/.claude/skills/` 目录下创建自定义技能。

**技能文件结构：**
```
~/.claude/skills/
└── my-skill/
    └── SKILL.md      # 技能定义文件
```

**注册流程：**
```typescript
// 注册技能
registerBundledSkill(definition: BundledSkillDefinition): void

// 获取所有已注册技能
getBundledSkills(): Command[]

// 技能文件提取（用于有参考文件的技能）
async function extractBundledSkillFiles(
  skillName: string,
  files: Record<string, string>
): Promise<string | null>
```

### 2.5 技能与命令的转换

技能在内部被转换为 `Command` 对象：

```typescript
function skillDefinitionToCommand(definition: BundledSkillDefinition): Command {
  return {
    type: 'prompt',
    name: definition.name,
    description: definition.description,
    source: 'bundled',
    loadedFrom: 'bundled',
    hooks: definition.hooks,
    context: definition.context,
    agent: definition.agent,
    // ...
  }
}
```

## 3. 插件与技能的协同

### 3.1 插件提供技能

插件可以通过内置技能机制提供技能：
```typescript
// 插件定义
const myPlugin: BuiltinPluginDefinition = {
  name: 'my-plugin',
  description: 'My custom plugin',
  skills: [skill1, skill2],
  // ...
}
```

### 3.2 钩子在技能执行中的应用

技能执行时会触发各种钩子：
- `PreToolUse` - 检查技能是否允许使用特定工具
- `PostToolUse` - 记录技能执行结果
- `Stop` - 技能执行完成

## 4. MCP 集成

技能系统支持 MCP (Model Context Protocol) 技能构建器：

```typescript
// 位置：/src/skills/mcpSkillBuilders.ts
export function createMcpSkill(
  serverName: string,
  toolName: string
): BundledSkillDefinition
```

## 5. 权限与安全

### 5.1 技能白名单

`SAFE_SKILL_PROPERTIES` 定义了安全属性列表，只包含以下属性的技能会自动获得权限：
- `type`, `progressMessage`, `contentLength`, `argNames`, `model`, `effort`
- `source`, `pluginInfo`, `disableNonInteractive`, `skillRoot`, `context`, `agent`
- `getPromptForCommand`, `frontmatterKeys`
- `name`, `description`, `hasUserSpecifiedDescription`, `isEnabled`, `isHidden`
- `aliases`, `isMcp`, `argumentHint`, `whenToUse`, `paths`, `version`
- `disableModelInvocation`, `userInvocable`, `loadedFrom`, `immediate`, `userFacingName`

### 5.2 远程技能 (实验性)

启用 `EXPERIMENTAL_SKILL_SEARCH` 后支持远程技能：
- 技能定义存储在远程服务器
- 通过 `_canonical_<slug>` 格式引用
- 支持 GCS、HTTP/HTTPS、S3 等协议