阶段 7 ｜高级系统专题¶

目标：按专题深入理解 Claude Code 的"扩展能力" —— MCP、plugins、skills、bridge、voice、vim、native 桥接。时长：按需，每个专题 0.5~2 天 前端类比：每个专题都是一个独立子系统，对应 Web 项目里的"插件系统 / 实时通信 / 设备 API"。

7.1 专题地图¶

专题	主目录	文件数	核心价值
MCP（Model Context Protocol）	`src/services/mcp/`	23	LLM 工具扩展标准
Bridge（IDE/Remote 桥接）	`src/bridge/`	20+	VSCode / JetBrains 集成
Server（直连）	`src/server/`	3	本地 HTTP 服务
Remote（远程会话）	`src/remote/`	4	云端 session 同步
Plugins（插件）	`src/plugins/`	2+	用户扩展点
Skills（技能）	`src/skills/`	4	任务级 prompt 模板
Ink 框架（fork）	`src/ink/`	50+ / 13306 行	TUI 渲染引擎
Native 桥接	`src/native-ts/` + `vendor/`	3 + 4	N-API / Rust 集成
Vim 模式	`src/vim/`	5	编辑器键位
Voice（语音）	`src/voice/`	1	功能标志

7.2 MCP（Model Context Protocol）¶

MCP 是 Anthropic 推动的 "LLM 工具扩展标准" —— 让任何外部服务以统一协议提供 LLM 工具。
Claude Code 是 MCP 的标杆实现。

7.2.1 服务端目录：`src/services/mcp/`¶

23 个文件 完整覆盖 MCP 全栈：

文件	职责
`MCPConnectionManager.tsx`	核心：MCP 连接管理（多 server、断线重连）
`client.ts`	MCP client 实现（stdio / HTTP / SSE）
`SdkControlTransport.ts`	SDK 控制传输
`InProcessTransport.ts`	进程内传输（同进程 MCP server）
`types.ts`	MCP 协议类型
`config.ts`	MCP 配置（`.mcp.json` 解析）
`auth.ts`	OAuth / API key 鉴权
`oauthPort.ts`	OAuth 回调端口管理
`xaa.ts` + `xaaIdpLogin.ts`	Cross-App Access 登录
`officialRegistry.ts`	官方 MCP registry（Claude.ai 集成）
`vscodeSdkMcp.ts`	VSCode SDK 适配
`claudeai.ts`	claude.ai 集成 MCP
`elicitationHandler.ts`	Elicit 请求处理（MCP 1.0 新特性）
`channelPermissions.ts`	Channel 权限
`channelAllowlist.ts`	Channel 白名单
`channelNotification.ts`	Channel 通知
`useManageMCPConnections.ts`	React hook：UI 管理连接
`utils.ts` + `mcpStringUtils.ts` + `normalization.ts` + `headersHelper.ts` + `envExpansion.ts`	工具

7.2.2 工具侧：`src/tools/MCPTool/`¶

MCPTool/ 把 MCP server 暴露的工具注册到本地工具系统 —— 当 LLM 调 mcp__github__create_issue，MCPTool 会路由到对应 MCP server。

关键洞察：MCP 是 Claude Code 最重要的扩展点。
加一个工具 = 装一个 MCP server = 0 行 Claude Code 改动。
前端类比：和 Web Components、Custom Elements 一样 —— 标准化的扩展协议。

7.2.3 MCP 协议特性¶

观察 elicitationHandler.ts 文件名 —— Elicitation 是 MCP 1.0 的特性：
MCP server 可以反过来问用户问题（"需要哪个项目？"），UI 弹 ElicitationDialog 让用户回答。
这是 MCP 的"双向通信"能力。

7.2.4 推荐阅读顺序¶

✅ src/services/mcp/types.ts（看协议）
✅ src/services/mcp/client.ts（看 client 实现）
✅ src/services/mcp/MCPConnectionManager.tsx（看连接管理）
✅ src/tools/MCPTool/MCPTool.tsx（看工具路由）
📌 src/services/mcp/oauthPort.ts（看 OAuth 流程）

7.3 Bridge（IDE / Remote 桥接）¶

Bridge 是 Claude Code 和外部世界通信的管道：VSCode、JetBrains、远程服务器。

7.3.1 核心文件（20+ 个）¶

文件	职责
`bridgeMain.ts`	桥接主控
`bridgeConfig.ts`	桥接配置
`bridgeEnabled.ts`	是否启用
`bridgeApi.ts`	Bridge API 定义
`bridgeMessaging.ts`	消息序列化
`bridgePermissionCallbacks.ts`	权限回调（IDE 接管）
`bridgeStatusUtil.ts`	状态查询
`bridgeDebug.ts` + `debugUtils.ts`	调试
`bridgePointer.ts`	指针协议
`bridgeUI.ts`	UI 集成
`codeSessionApi.ts`	Code session API
`createSession.ts`	创建 session
`initReplBridge.ts`	初始化 REPL 桥接
`envLessBridgeConfig.ts`	无 env 配置
`capacityWake.ts`	容量唤醒（保活）
`flushGate.ts`	flush 控制（背压）
`inboundMessages.ts` + `inboundAttachments.ts`	入站消息/附件
`jwtUtils.ts`	JWT 认证

7.3.2 双向通信设计¶

bridgeMessaging.ts + inboundMessages.ts / inboundAttachments.ts 是双向通信： - Claude Code → IDE：工具调用、文件 diff - IDE → Claude Code：用户选中、IDE 状态、文件保存事件

flushGate.ts 处理背压 —— 防止 IDE 跟不上 Claude Code 的速度。

capacityWake.ts`保活机制 —— 保持 Bridge 通道活跃。

7.3.3 关键洞察¶

Bridge 是 Claude Code 的"实时同步层"。
在 IDE 里选中一段代码，Claude Code 立刻能看到；Claude Code 改的文件，IDE 立刻刷新。
前端类比：和"协同编辑"的 CRDT 协议同种"实时双向同步"思想。

7.4 Server / Remote¶

7.4.1 `src/server/` —— Direct Connect¶

3 个文件：createDirectConnectSession.ts、directConnectManager.ts、types.ts

本地起一个 HTTP/WebSocket 服务，让其他进程（IDE、其他 CLI）直连 Claude Code 而不走远程 broker。
用途：本地开发、CI 集成。

7.4.2 `src/remote/` —— Remote Session¶

文件	职责
`RemoteSessionManager.ts`	远程 session 生命周期
`SessionsWebSocket.ts`	WebSocket 客户端
`sdkMessageAdapter.ts`	SDK 消息格式转换
`remotePermissionBridge.ts`	远程权限代理

场景：在 claude.ai 网页上启动的对话，可以 attach 到本地 CLI 继续。

7.5 Plugins 与 Skills¶

7.5.1 区别¶

维度	Plugins	Skills
粒度	完整功能扩展	任务级 prompt 模板
存储	`~/.claude/plugins/` 或 `.claude/plugins/`	`~/.claude/skills/` 或 `.claude/skills/`
实现	TypeScript 模块	Markdown + 资源
加载	启动时扫描	按需加载
调用	注入到工具系统	注入到 system prompt

7.5.2 关键文件¶

Plugins： - src/plugins/builtinPlugins.ts —— 内置插件清单 - src/plugins/bundled/ —— 内置插件实现 - AppStateStore.ts 里的 loadedPlugins: LoadedPlugin[]

Skills： - src/skills/loadSkillsDir.ts —— 扫描加载 - src/skills/bundledSkills.ts —— 内置 skill - src/skills/mcpSkillBuilders.ts —— 把 MCP 工具包成 skill

7.5.3 关键洞察¶

Skills ≈ Web 项目的"内容片段"（Prompt 模板）
Plugins ≈ Web 项目的"扩展应用"（完整功能）
两个层次让 Claude Code 既能"快速定制 prompt"（skill）也能"深度扩展能力"（plugin）。

7.6 Ink 框架（fork）¶

路径：src/ink/ 规模：13306 行 / 50+ 文件 角色：整套 React-for-CLI 框架的源码 fork

7.6.1 为什么 fork？¶

仓库无 package.json / node_modules，所有依赖必须以源码形式内嵌。Ink 是核心依赖，所以整 fork 进来。

7.6.2 子目录¶

目录	职责
`ink.tsx` (1722 行)	核心：React reconciler + 渲染调度
`events/` (10 文件)	事件系统（keyboard、click、focus、input、terminal）
`hooks/` (12 文件)	React hooks（useInput、useApp、useStdin、useSearchHighlight ...）
`layout/` (3 文件)	Yoga 布局引擎（Facebook flexbox）
`components/` (16 文件)	内置组件（Box、Text、ScrollBox、App、Button、Link ...）
`reconciler.ts`	React reconciler
`renderer.ts` + `render-to-screen.ts` + `render-node-to-output.ts`	渲染管线
`parse-keypress.ts`	按键解析（跨平台）
`stringWidth.ts` + `widest-line.ts` + `wrap-text.ts` + `wrapAnsi.ts`	文本宽度计算（CJK、Emoji、宽字符）
`Ansi.tsx` + `colorize.ts`	ANSI 颜色
`optimizer.ts` + `squash-text-nodes.ts` + `node-cache.ts` + `line-width-cache.ts`	渲染优化
`measure-element.ts` + `measure-text.ts` + `hit-test.ts`	测量 + 命中测试
`dom.ts` + `node.ts`	虚拟 DOM
`selection.ts` + `searchHighlight.ts`	选中 + 搜索高亮
`frame.ts` + `screen.ts` + `output.ts`	帧管理

7.6.3 关键技术¶

Yoga 布局 —— src/ink/layout/yoga.ts 集成了 Facebook 的 yoga-layout（N-API），实现 flexbox
CJK/Emoji 宽度 —— stringWidth.ts 实现了完整的 Unicode 宽度算法（这在 TUI 是必做的）
按 ANSI 优化 —— optimizer.ts 把连续的 Text 节点合并，避免重复的 escape code
节点缓存 —— node-cache.ts + line-width-cache.ts 减少重复计算
命中测试 —— hit-test.ts 实现"鼠标点击位置 → 哪个组件"（在支持鼠标的 TUI 里）

7.6.4 推荐阅读¶

读 Ink 源码是大型 TUI 项目必经之路。建议： 1. ✅ src/ink/ink.tsx（1722 行）—— 入口 2. ✅ src/ink/reconciler.ts —— React reconciler 适配 3. ✅ src/ink/renderer.ts + render-to-screen.ts —— 渲染流程 4. ✅ src/ink/parse-keypress.ts —— 键位解析 5. ✅ src/ink/stringWidth.ts —— 字符宽度 6. 📌 src/ink/layout/yoga.ts —— 布局引擎

💡 如果只想学 TUI 渲染基础，读 ink.tsx + reconciler.ts + renderer.ts 三个文件就够 90%。

7.7 Native 桥接¶

Claude Code 通过 N-API 调用原生代码（macOS / Windows / Linux）

7.7.1 项目内 N-API 绑定：`src/native-ts/`¶

src/native-ts/
├── color-diff/        颜色差异计算（N-API，用于 diff 颜色对比度）
├── file-index/        文件索引（加速 glob/grep）
└── yoga-layout/       Yoga 布局引擎（Facebook flexbox）

Yoga-layout 用 C++ 实现的 flexbox 算法，通过 N-API 暴露给 Node/Bun。
Claude Code 在终端里实现 <Box flexDirection="row" justifyContent="space-between"> 的关键。

7.7.2 外部 vendor：`vendor/`¶

vendor/
├── audio-capture-src/      音频捕获（macOS AVFoundation）
├── image-processor-src/    剪贴板图像处理
├── modifiers-napi-src/     键盘修饰键 N-API
└── url-handler-src/        URL scheme handler

audio-capture-src 揭秘¶

// vendor/audio-capture-src/index.ts
type AudioCaptureNapi = {
  startRecording(
    onData: (data: Buffer) => void,
    onEnd: () => void,
  ): boolean
  stopRecording(): void
  isRecording(): boolean
  // ... 录音 / 放音

  // TCC microphone authorization status (macOS only):
  // 0 = notDetermined, 1 = restricted, 2 = denied, 3 = authorized.
  microphoneAuthorizationStatus?(): number
}

关键洞察： - TCC 权限码（0-3）—— macOS 的 AVCaptureDevice 授权状态枚举 - callback 模式（onData、onEnd）—— N-API 经典风格 - 跨平台兼容 —— Linux 无 TCC API（永远返回 3），Windows 看注册表

💡 这段类型定义是读懂 N-API 集成的最佳标本。20 行讲清楚"原生模块要暴露什么 API、跨平台怎么处理"。

image-processor-src 揭秘¶

// vendor/image-processor-src/index.ts
export type ClipboardImageResult = {
  png: Buffer
  originalWidth: number
  originalHeight: number
  width: number
  height: number
}

// macOS only — older builds may not have these
export type NativeModule = {
  processImage: (input: Buffer) => Promise<ImageProcessor>
  readClipboardImage?: (maxWidth: number, maxHeight: number) => ClipboardImageResult | null
  hasClipboardImage?: () => boolean
}

关键洞察： - 可选属性（?:）—— 处理"老版本没有这个 API"的兼容 - Tree-shake 友好 —— 通过 feature() 在不需要的构建里清除 - Clipboard API 跨平台限制 —— 注释明确写 "macOS-only"

7.7.3 N-API 集成的"惯用法"¶

观察所有 vendor 模块的 TypeScript 类型： 1. N-API 模块 用 callback / Promise 暴露能力 2. JS 侧 用 type-only 定义接口 3. 跨平台 fallback —— 可选属性 + 注释说明 4. Lazy dlopen —— processImage: (input) => Promise<...> 而不是同步

💡 学习 N-API 集成就从 vendor/ 四个文件入手。

7.8 Vim 模式：`src/vim/`¶

5 个文件：motions.ts、operators.ts、textObjects.ts、transitions.ts、types.ts

实现了完整的 vim normal 模式：

文件	内容
`motions.ts`	移动命令：h/j/k/l/w/b/e/0/$/gg/G/...
`operators.ts`	操作符：d/c/y/>/<...
`textObjects.ts`	文本对象：iw/aw/i"/a"/i(/a(/...
`transitions.ts`	状态转换（normal → insert → visual）
`types.ts`	类型定义

前端类比：和 Monaco Editor / CodeMirror 的 vim mode 是同种实现。状态机 + 命令解析器是核心。

7.9 Voice（语音）¶

1 个文件：src/voice/voiceModeEnabled.ts

推测只是功能标志（决定 voice 模式是否启用），真正的实现可能在 N-API 模块里（参考 vendor/audio-capture-src）。

7.10 关键洞察¶

7.10.1 MCP 是"扩展协议"，Plugins 是"扩展实现"¶

Claude Code 选择支持 MCP 协议，比单独做 plugins 系统更有远见：
- MCP 是行业标准（OpenAI、Google 都支持） - Claude Code 既是 MCP client 也是 MCP server（双向） - 加一个新工具服务 = 0 行 Claude Code 改动

7.10.2 Bridge 是"实时双向同步"¶

bridgeMessaging.ts + flushGate.ts + capacityWake.ts 三件套实现了带背压的双向通信。
前端类比：和"协同编辑"的同步层是同种思想。

7.10.3 整套 Ink fork = "TUI 基础设施"¶

13306 行的 Ink 源码 = Claude Code 的"TUI 内核"。
学习 Claude Code 必然要读 Ink —— 不读 Ink 等于只学了一半。

7.10.4 N-API 集成的"惯用法"¶

观察 4 个 vendor 模块 + 3 个 native-ts 模块的共同模式： - JS 侧只写类型（type XxxNapi = { ... }） - callback / Promise 异步 - 跨平台 fallback 用可选属性 + 注释 - Tree-shake 友好

7.10.5 DCE/Ant-only 在高级系统里也密集¶

coordinator/coordinatorMode.ts
REPLTool (Ant-only)
RemoteTriggerTool (Ant-only)
SleepTool (feature('PROACTIVE') / feature('KAIROS'))
ScheduleCronTool/* (feature('AGENT_TRIGGERS'))

这些分支外部构建看不到，读源码时直接跳过。

7.11 阅读清单（按专题）¶

MCP（2~3 天）¶

✅ src/services/mcp/types.ts
✅ src/services/mcp/client.ts
✅ src/services/mcp/MCPConnectionManager.tsx
✅ src/tools/MCPTool/MCPTool.tsx
📌 src/services/mcp/elicitationHandler.ts

Bridge（1~2 天）¶

✅ src/bridge/bridgeMain.ts
✅ src/bridge/bridgeMessaging.ts
✅ src/bridge/inboundMessages.ts
📌 src/bridge/flushGate.ts（背压）

Ink 框架（3~5 天，可选修）¶

✅ src/ink/ink.tsx（1722 行入口）
✅ src/ink/reconciler.ts
✅ src/ink/renderer.ts + render-to-screen.ts
✅ src/ink/parse-keypress.ts + stringWidth.ts
📌 src/ink/layout/yoga.ts

Native 桥接（1~2 天）¶

✅ vendor/audio-capture-src/index.ts（20 行类型）—— N-API 集成的范本
✅ vendor/image-processor-src/index.ts
🔍 src/native-ts/yoga-layout/ —— 看 N-API 在 TS 侧的包装

Vim / Voice / 其他（按需）¶

src/vim/motions.ts 看 vim 模式怎么用 TS 实现
src/voice/voiceModeEnabled.ts 看功能标志模式

7.12 练习任务¶

MCP 通信序列图 —— 画一张"Claude Code 调 MCP 工具"的时序图：用户输入 → LLM 返回 tool_use → MCPTool 路由 → MCP server → 结果回传
Bridge 双向通信设计 —— 列出"Claude Code → IDE"和"IDE → Claude Code"分别传递什么数据
Ink 渲染管线 —— 从 ink.tsx 入口跟到终端输出，列出每一步做了什么
N-API 集成模板 —— 用 vendor/audio-capture-src/index.ts 的模式，写一个"屏幕截图"原生模块的类型定义
Vim 状态机 —— 列出 normal/insert/visual 三种模式的转换关系

7.13 学完 7 个阶段后¶

你将掌握： - ✅ TUI 应用的完整架构（前端工程师视角） - ✅ React 范式在非浏览器宿主上的应用 - ✅ 大型 TypeScript 项目的代码组织（1000+ 文件、200+ 业务模块） - ✅ 流式 API 客户端的"async generator"模式 - ✅ 多 agent 系统的协调 - ✅ 工具调用 / 权限 / 沙箱的安全模型 - ✅ N-API 原生模块集成 - ✅ MCP 行业标准协议 - ✅ 双向实时通信（Bridge / 背压） - ✅ Ink 框架的渲染原理

接下来可以： - 给 Claude Code 提 PR（修个小 bug 或加个翻译） - 用 Ink 写自己的 TUI 工具 - 用 MCP 协议写自己的工具服务器 - 把学到的模式用到自己的 Web 项目（这套架构思想在 Web 一样适用）

回到 00-index.md 导读 · 阶段 1：入口与启动链 · 阶段 2：REPL 主循环 · 阶段 3：状态管理 · 阶段 4：组件库与设计系统 · 阶段 5：工具调用系统 · 阶段 6：Agent 循环 + 流式 API

阶段 7 ｜ 高级系统专题¶