13 — 扩展机制与辅助子系统

概述

本章覆盖 Claude Code 的 四大扩展机制（Skills、Plugins、Hooks、MCP）以及各种辅助子系统（Vim、快捷键、Memory、Voice 等）。

理解扩展机制的关键是理解它们的 定位差异：

扩展机制	复杂度	提供能力	适用场景
MCP	中等	新工具（远程 RPC）	连接外部服务（GitHub、数据库等）
Skills	低	可复用 prompt 模板	固化常用操作流程
Plugins	高	工具 + 命令 + 钩子 + MCP	完整功能扩展包
Hooks	低	Shell 钩子	安全检查、自动格式化等

MCP — 外部工具协议

MCP (Model Context Protocol) 是最主要的扩展机制。详细内容见 07-服务层，这里补充其作为扩展点的视角。

MCP 工具如何被模型使用

MCP 工具在模型看来与内置工具没有区别——它们共享相同的权限检查和执行管线。

MCP 配置方式

json

// .mcp.json (项目级) 或 ~/.claude/settings.json (全局)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  }
}

Skills 系统 (`src/skills/`)

Skill 是 可复用的 prompt 模板——本质上是预定义的指令，可以包含上下文收集、模型调用、甚至并行 Agent 启动。

Skill 接口

typescript

type BundledSkillDefinition = {
  name: string
  description: string
  aliases?: string[]
  allowedTools?: string[]           // 可用工具列表
  model?: string                    // 覆盖模型
  context?: 'inline' | 'fork'       // 执行模式
  isEnabled?: () => boolean         // 运行时开关
  
  getPromptForCommand(
    args: string,
    context: ToolUseContext,
  ): Promise<ContentBlockParam[]>   // 生成 prompt
}

执行模式

模式	说明	适用场景
`inline`	Skill prompt 注入当前对话	轻量操作，不需要隔离
`fork` (默认)	启动子代理执行 Skill	需要独立 token 预算的操作

内置 Skills

Skill	文件	说明
`simplify`	`simplify.ts`	代码简化审查——启动 3 个并行 Agent 检查复用性、质量、效率
`claude-api`	`claudeApi.ts`	Claude API 开发指导——检测语言、注入 SDK 文档
`keybindings`	`keybindings.ts`	快捷键配置帮助
`update-config`	`updateConfig.ts`	设置/Hook 配置引导
`loop`	`loop.ts`	循环执行命令（定时轮询）
`schedule`	`scheduleRemoteAgents.ts`	远程 Agent Cron 调度
`verify`	`verify.ts`	代码验证
`remember`	`remember.ts`	记忆保存
`batch`	`batch.ts`	批量处理
`debug`	`debug.ts`	调试辅助
`stuck`	`stuck.ts`	卡住时的帮助
`skillify`	`skillify.ts`	将操作提炼为新 Skill

Skills vs Commands 的区别

特性	Skills	Commands
调用方式	模型通过 `SkillTool` 或用户通过 `/skill`	用户通过 `/command`
实现	prompt 模板 + 可选 Agent	TypeScript 函数或 React 组件
能力	利用模型生成内容	直接操作系统/状态
扩展性	可从 Plugin、MCP、用户自定义	需要代码编写

Plugin 系统 (`src/plugins/`)

Plugin 是最重量级的扩展机制——一个 Plugin 可以同时提供 Skills、Hooks、MCP 服务器和自定义命令。

Plugin 结构

typescript

type LoadedPlugin = {
  name: string
  manifest: PluginManifest              // 名称、描述、版本
  path: string                          // 文件系统路径
  source: string                        // 来源 (github:owner/repo)
  enabled?: boolean
  
  // Plugin 可以提供的能力:
  skillsPaths?: string[]                // Skill 定义文件
  commandsPath?: string                 // 自定义命令
  hooksConfig?: HooksSettings           // Hook 配置
  mcpServers?: Record<string, McpServerConfig>  // MCP 服务器
  lspServers?: Record<string, LspServerConfig>  // LSP 服务器
  settings?: Record<string, unknown>    // 插件配置
}

安装与管理

文件	说明
`plugins/bundled/index.ts`	内置 Plugin 注册
`plugins/builtinPlugins.ts`	内置 Plugin 定义
`services/plugins/PluginInstallationManager.ts`	安装管理器
`services/plugins/pluginOperations.ts`	CRUD 操作
`services/plugins/pluginCliCommands.ts`	CLI 命令实现
`utils/plugins/`	Plugin 工具函数
`utils/dxt/`	DXT 格式支持（打包格式）

Hooks 系统 (`utils/hooks/`)

Hooks 的详细执行模型见 08-权限。这里补充其作为扩展点的用法：

常见 Hook 用例

用例	Hook 事件	实现
自动格式化	`PostToolUse` + matcher: `FileWrite`	`prettier --write $FILE`
安全审查	`PreToolUse` + matcher: `Bash`	自定义安全检查脚本
CI 集成	`PostToolUse` + matcher: `Bash`	触发 CI pipeline
日志记录	`PostToolUse` (all)	记录所有工具调用
测试运行	`PostToolUse` + matcher: `FileEdit`	文件修改后自动跑测试

Hook 可以修改工具行为

Hook 不仅仅是"旁观者"——PreToolUse Hook 返回 {"decision": "block"} 可以 阻止工具执行，PostToolUse Hook 可以 注入额外上下文 到模型的下一轮输入中。

Vim 模式 (`src/vim/`)

完整的 Vim 编辑模式，用于 REPL 输入框。

文件	说明
`types.ts`	模式状态 (Normal / Insert / Visual / Command)
`motions.ts`	光标移动 (w/b/e/0/$/ hjkl / gg/G 等)
`operators.ts`	操作符 (d/c/y/p 等)
`textObjects.ts`	文本对象 (iw/aw/i"/a" 等)
`transitions.ts`	模式转换 (i→Insert, Esc→Normal 等)

通过 /vim 命令切换开关。启用后，VimTextInput.tsx 替代普通的 TextInput.tsx。

快捷键系统 (`src/keybindings/`)

用户可自定义的快捷键系统。支持单键、组合键和 Chord（多步连击）。

文件	说明
`defaultBindings.ts`	默认快捷键表
`loadUserBindings.ts`	加载 `~/.claude/keybindings.json`
`schema.ts`	快捷键 Schema 验证
`parser.ts`	按键序列解析 (`ctrl+shift+p` → 结构化对象)
`match.ts`	按键匹配 (输入事件 → 绑定查找)
`resolver.ts`	绑定解析器 (合并默认+用户，处理冲突)
`validate.ts`	配置验证
`reservedShortcuts.ts`	系统保留的快捷键 (不可覆盖)
`KeybindingContext.tsx`	React Context
`KeybindingProviderSetup.tsx`	Provider 初始化
`useKeybinding.ts`	Hook: 注册快捷键
`useShortcutDisplay.ts`	Hook: 格式化显示

Memory 系统 (`src/memdir/`)

基于文件系统的持久化记忆，跨会话保持用户偏好和项目上下文。

记忆类型

类型	说明	示例
`user`	用户角色、偏好	"资深 Go 工程师，React 新手"
`feedback`	行为修正/确认	"不要在响应末尾加摘要"
`project`	项目动态	"3/5 起代码冻结"
`reference`	外部资源指针	"Bug 在 Linear 的 INGEST 项目"

文件结构

~/.claude/projects/<project>/memory/
├── MEMORY.md                # 索引文件 (每行一个指针)
├── user_role.md             # 记忆文件 (含 frontmatter)
├── feedback_testing.md
└── project_freeze.md

每个记忆文件有 YAML frontmatter（name, description, type），MEMORY.md 是索引。

记忆使用流程

文件	说明
`memdir.ts`	Memory 目录管理
`paths.ts`	路径计算
`memoryTypes.ts`	记忆类型定义
`findRelevantMemories.ts`	相关记忆查找
`memoryAge.ts`	记忆时效管理
`memoryScan.ts`	记忆扫描
`teamMemPrompts.ts`	团队记忆 Prompt
`teamMemPaths.ts`	团队记忆路径

Voice 系统

语音输入功能（Feature Flag: VOICE_MODE）。

文件	说明
`voice/voiceModeEnabled.ts`	语音模式启用判断
`services/voice.ts`	语音服务
`services/voiceStreamSTT.ts`	流式语音转文字 (STT)
`services/voiceKeyterms.ts`	关键词识别
`hooks/useVoice.ts`	Voice Hook
`hooks/useVoiceIntegration.tsx`	语音集成
`context/voice.tsx`	Voice Context

配置系统 (`src/utils/settings/`)

Claude Code 的配置来自多个来源，按优先级从高到低合并：

文件	说明
`settings.ts`	主配置逻辑
`types.ts`	`SettingsJson` 类型定义
`validation.ts`	配置验证
`settingsCache.ts`	缓存 (避免重复读文件)
`changeDetector.ts`	变更检测 (实时监听配置文件)
`applySettingsChange.ts`	应用变更
`mdm/`	MDM (企业设备管理) 设置读取

迁移 (`src/migrations/`)

每当配置格式或默认值变化时，迁移脚本确保旧版配置自动升级：

文件	说明
`migrateOpusToOpus1m.ts`	Opus → Opus 1M 模型迁移
`migrateSonnet45ToSonnet46.ts`	Sonnet 4.5 → 4.6
`migrateFennecToOpus.ts`	Fennec (内部代号) → Opus
`migrateBypassPermissionsAcceptedToSettings.ts`	权限配置格式变更
`migrateAutoUpdatesToSettings.ts`	自动更新设置迁移

其他辅助子系统

子系统	目录	说明
Buddy	`src/buddy/`	虚拟伙伴精灵 (ASCII 动画彩蛋)
Context Providers	`src/context/`	React Context：通知、模态框、邮箱、统计、FPS、语音
Native TS	`src/native-ts/`	纯 TS 实现的底层模块：Yoga Layout、Color Diff、File Index
Coordinator	`src/coordinator/`	协调者模式 (Feature Flag: `COORDINATOR_MODE`)
Assistant	`src/assistant/`	Kairos 助手模式 (Feature Flag: `KAIROS`)
OutputStyles	`src/outputStyles/`	可自定义的输出风格加载器
Query	`src/query/`	Query 引擎配置 (非交互模式的参数)
Moreright	`src/moreright/`	扩展右侧面板

`src/utils/` — 工具函数总览

utils/ 是项目中最大的目录（30+ 子目录），包含各种工具函数。以下是按功能分组的索引：

子目录	说明	主要被谁使用
`settings/`	配置管理	全局
`permissions/`	权限逻辑	Tool 执行
`swarm/`	Swarm/Teammate	TeamCreate
`hooks/`	用户钩子执行	Tool 执行
`sandbox/`	沙箱隔离	BashTool
`git/`	Git 操作	context.ts, 各种命令
`github/`	GitHub 集成	命令/工具
`model/`	模型选择/切换	main.tsx, /model
`messages/`	消息处理/序列化	query.ts, API
`processUserInput/`	用户输入路由	REPL
`bash/` / `powershell/` / `shell/`	Shell 执行辅助	BashTool, PowerShellTool
`memory/`	Memory 工具	memdir
`skills/`	Skills 工具	SkillTool
`plugins/`	Plugins 工具	Plugin 系统
`task/`	Task 工具	Task 系统
`todo/`	Todo 工具	TodoWriteTool
`background/`	后台任务	Remote Session
`telemetry/`	遥测	Analytics
`teleport/`	Teleport (跨设备)	/teleport
`suggestions/`	输入建议/补全	PromptInput
`computerUse/`	Computer Use	实验性
`claudeInChrome/`	Chrome 扩展集成	实验性
`deepLink/`	Deep Link 处理	桌面端
`dxt/`	DXT (插件打包格式)	Plugin 系统
`filePersistence/`	文件持久化	会话存储
`nativeInstaller/`	原生安装器	升级/安装
`secureStorage/`	安全存储 (Keychain)	认证
`ultraplan/`	Ultra Plan	实验性

13 — 扩展机制与辅助子系统 ​

概述 ​

MCP — 外部工具协议 ​

MCP 工具如何被模型使用 ​

MCP 配置方式 ​

Skills 系统 (src/skills/) ​

Skill 接口 ​

执行模式 ​

内置 Skills ​

Skills vs Commands 的区别 ​

Plugin 系统 (src/plugins/) ​

Plugin 结构 ​

安装与管理 ​

Hooks 系统 (utils/hooks/) ​

常见 Hook 用例 ​

Hook 可以修改工具行为 ​

Vim 模式 (src/vim/) ​

快捷键系统 (src/keybindings/) ​

Memory 系统 (src/memdir/) ​

记忆类型 ​

文件结构 ​

记忆使用流程 ​

Voice 系统 ​

配置系统 (src/utils/settings/) ​

迁移 (src/migrations/) ​

其他辅助子系统 ​

src/utils/ — 工具函数总览 ​