Plugins

Plugins 模块实现 Claude Code 的内置插件系统，通过 builtinPlugins.ts 管理以 {name}@builtin 格式标识的内置插件。每个插件可包含 Skills（命令）、Hooks（生命周期钩子）和 MCP Servers（外部工具服务器）三种组件。插件支持用户级启用/禁用（持久化到 settings），支持可用性检测（isAvailable），并通过 bundled/ 目录承载实际的插件实现。插件系统与 Marketplace 插件共享 LoadedPlugin 接口，但通过 isBuiltin 标志区分来源。

职责与设计理念

职责说明

内置插件注册表，管理可启用/禁用的内置插件生态

设计理念

插件即能力单元——每个插件是 Skills + Hooks + MCP 的原子组合，用户可以像开关一样控制 AI 的能力边界。内置与市场插件共享接口，差异仅在来源。

架构决策

为什么内置插件和市场插件共享同一个接口？

统一 LoadedPlugin 接口，通过 isBuiltin 标志区分来源

对消费者（Commands、UI）来说，插件的来源不影响使用方式。统一接口让命令发现、权限检查、UI 渲染等逻辑只需写一份。来源差异只在加载和更新时有意义。

为什么插件支持 isAvailable 检测？

运行时可用性检测，而非编译时排除

某些插件依赖外部工具（如 GitHub CLI），这些工具可能未安装。isAvailable 在运行时检测环境，让插件在不满足条件时优雅隐藏，而非报错。

文件清单

文件名	用途
builtinPlugins.ts	内置插件注册表，管理注册、查询、启用/禁用和 Skill 转换
bundled/	内置插件实现目录，承载各插件的具体逻辑

使用场景

/config 管理插件

用户在设置面板中启用/禁用内置插件，状态持久化到 settings.json

命令补全时

已启用插件的 Skills 自动出现在 / 命令列表中

getCommands() → getBuiltinPluginSkillCommands() → 聚合到命令列表

插件提供 MCP Server

插件注册的 MCP Server 自动启动，其工具可在对话中使用

依赖关系

Commands — 斜杠命令系统，管理 80+ 个子命令的注册、发现与执行
Context — 9 个 React Context Provider，管理 UI 层的全局状态分发
Hooks — 80+ 个 React Hooks 库，覆盖 AI 交互、IDE 集成、语音、任务等全场景

关键代码片段

内置插件注册与加载

type BuiltinPluginDefinition = {
  name: string
  description: string
  version: string
  defaultEnabled?: boolean
  isAvailable?: () => boolean
  skills?: BundledSkillDefinition[]
  hooks?: HooksConfig
  mcpServers?: McpServerConfig[]
}

function registerBuiltinPlugin(def: BuiltinPluginDefinition) {
  BUILTIN_PLUGINS.set(def.name, def)
}

function getBuiltinPlugins(): {
  enabled: LoadedPlugin[], disabled: LoadedPlugin[]
} {
  for (const [name, def] of BUILTIN_PLUGINS) {
    if (def.isAvailable && !def.isAvailable()) continue
    const isEnabled = userSetting ?? def.defaultEnabled ?? true
    // ...分流到 enabled/disabled
  }
}

插件三要素（Skills/Hooks/MCP）+ 用户级开关 + 可用性检测的完整生命周期

插件能力组合模式

// 一个插件可以同时提供命令、钩子和 MCP 服务器
const codeReviewPlugin: BuiltinPluginDefinition = {
  name: 'code-review',
  description: 'AI-powered code review',
  version: '1.0.0',
  skills: [
    { name: 'review', description: 'Review PR changes' }
  ],
  hooks: {
    preCommit: async (ctx) => { /* 提交前自动审查 */ }
  },
  mcpServers: [
    { name: 'github', config: { /* GitHub API 配置 */ } }
  ],
}

插件是 Skills + Hooks + MCP 的原子组合，三种能力可任意搭配

技术笔记

edge-case

插件版本冲突

内置插件和市场插件可能同名。内置插件通过 {name}@builtin 命名空间隔离，市场插件通过 {name}@{author} 隔离。