7. Services 层全景：26 个子服务的职责地图

源码位置：src/services/（26 个子目录 + 15 个直属文件）

一句话理解

src/services/ 是 Claude Code 的"中间件层"：连接核心引擎（src/query.ts）、工具系统（src/tools/）、外部 API（Anthropic/GrowthBook/OAuth）的所有服务。

服务全景地图

src/services/
  ├── api/               ← 与 Anthropic API 通信的所有逻辑
  ├── compact/           ← 上下文压缩（autoCompact/microCompact/snip）
  ├── analytics/         ← 遥测（GrowthBook/OTel/DataDog/1P事件）
  ├── autoDream/         ← KAIROS Dream 记忆整合
  ├── mcp/               ← MCP 协议客户端管理
  ├── oauth/             ← OAuth 认证流程
  ├── SessionMemory/     ← 会话记忆（压缩集成）
  ├── AgentSummary/      ← 子代理对话摘要
  ├── extractMemories/   ← 自动记忆提取（EXTRACT_MEMORIES）
  ├── lsp/               ← Language Server Protocol（代码诊断）
  ├── MagicDocs/         ← 文档魔法工具
  ├── PromptSuggestion/  ← 输入框提示词建议
  ├── skillSearch/       ← 技能搜索（MCP_SKILLS）
  ├── teamMemorySync/    ← 团队记忆同步（TEAMMEM）
  ├── settingsSync/      ← 设置同步（远程）
  ├── remoteManagedSettings/ ← 企业策略设置
  ├── plugins/           ← 插件注册系统
  ├── policyLimits/      ← 速率限制策略
  ├── tools/             ← 工具调度层（StreamingToolExecutor）
  ├── contextCollapse/   ← 上下文折叠（CONTEXT_COLLAPSE）
  ├── toolUseSummary/    ← 工具使用摘要
  ├── tips/              ← 使用提示系统
  └── voice.ts 等直属文件  ← 语音/通知/诊断等

一：api/ — Anthropic API 通信核心

claude.ts（122 KB！）

整个项目最大的单文件，是所有 API 调用的总入口：

// 核心函数（简化）
  messages: Message[],
  systemPrompt: string,
  tools: Tool[],
  options: APIRequestOptions,
): AsyncGenerator<StreamEvent>

关键职责：

withRetry.ts（27 KB）

所有 API 调用必须经过的重试层：

// 三层退避策略
// 1. 429（速率限制）：指数退避 + jitter，最多 10 次
// 2. 529（过载）：只有前台查询重试，最多 3 次
// 3. 5xx（服务器错误）：ant 用户额外重试逻辑

// 重试不适用于：
// - 4xx 客户端错误（不能重试没意义）
// - 后台任务（摘要、标题、分类器）的 529

设计亮点：FOREGROUND_529_RETRY_SOURCES——明确列出哪些 QuerySource 在 API 过载时应该重试。防止后台任务在过载时形成"重试雪崩"。

errors.ts（40 KB）

专门处理 API 错误的模块，将原始 Anthropic 错误转换为用户友好的消息：

// 错误类型层次
APIError
  ├── 429 RateLimitError → "Rate limited, waiting..."
  ├── 529 OverloadedError → "Claude is busy..." 
  ├── 401 AuthenticationError → "Invalid API key"
  ├── 402 PaymentRequired → "Credit balance..."
  └── prompt_too_long → 触发 REACTIVE_COMPACT

filesApi.ts（21 KB）

Files API 客户端，支持上传文件给 Claude 处理（代替 base64 内联）：

// 上传文件到 Anthropic Files API
// Claude 通过 file_id 引用文件（减少 token 消耗）
// 支持缓存：相同内容的文件只上传一次

二：compact/ — 上下文压缩引擎

四种压缩策略（详见第三章）

文件策略触发方式
autoCompact.tsAutoCompact超过阈值（上下文 85%+）
reactiveCompact.tsReactiveCompactAPI 返回 prompt_too_long
snipCompact.tsSnipCompactHISTORY_SNIP feature
microCompact.tsMicroCompact精确压缩单个工具输出

compact.ts（59 KB）

核心压缩实现：

// 压缩流程
// 1. 找到最优分割点（messageGroupBoundary）
// 2. 用 Claude 生成上半段摘要
// 3. 摘要 + 完整后半段 = 新对话历史
// 4. 触发 PostCompact hook
// 5. 更新 sessionStorage

sessionMemoryCompact.ts（20 KB）

与 KAIROS 会话记忆集成的特殊压缩：在压缩时顺带提取长期记忆，写入记忆文件。

三：analytics/ — 遥测与 A/B 测试

growthbook.ts（39 KB）

GrowthBook SDK 封装：

firstPartyEventLogger.ts + firstPartyEventLoggingExporter.ts（共 40 KB）

一方（1P）事件日志——Anthropic 自己的遥测管道：

// 事件生命周期
logEvent(name, metadata)
  → firstPartyEventLogger 批处理 (每 10s 或 100 条 flush)
  → firstPartyEventLoggingExporter 发送 POST /v1/events
  → 服务器聚合分析

类型安全保证：AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

datadog.ts（8 KB）

DataDog 集成——监控指标推送：

四：mcp/ — MCP 服务器管理

子目录结构

src/services/mcp/
  ├── MCPClientManager.ts   ← 连接池管理
  ├── MCPServerManager.tsx  ← React 组件（权限确认 UI）
  ├── types.ts              ← MCPServerConnection 类型
  └── ...

MCPClientManager 管理所有活跃的 MCP 服务器连接：

五：lsp/ — 语言服务器集成

Language Server Protocol 集成，为文件编辑提供代码诊断（错误提示、类型检查等）：

// 工作原理
// 1. Claude 编辑文件后，LSP 客户端触发诊断
// 2. 获取 TypeScript/ESLint/... 的实时错误
// 3. 将诊断信息传给 Claude（作为工具结果的附加信息）
// 4. Claude 可以立即看到自己写的代码有没有类型错误

这是 Claude Code 区别于普通 AI 编程助手的重要能力——能实时感知代码质量。

六：SessionMemory/ — 会话记忆

KAIROS 的短期记忆层——比日志更结构化，比 Dream 整合更快：

会话过程中
  → 关键信息 → SessionMemory 文件（项目目录下）
  → 压缩时 → sessionMemoryCompact 提取到长期记忆

七：其他重要直属文件

文件功能
voice.ts语音交互核心（见 5.5）
diagnosticTracking.ts诊断事件追踪（网络/API 健康）
claudeAiLimits.tsclaude.ai 订阅限制管理
mockRateLimits.ts速率限制模拟（内部测试用）
tokenEstimation.tsToken 数量快速估算（不调用 API）
vcr.tsVCR（录制回放）—— API 调用录制用于测试
notifier.ts系统通知（macOS/Linux/Windows）
preventSleep.ts防止系统休眠（长时间 Agent 任务时）
awaySummary.ts离开摘要（KAIROS 空闲时间摘要）

下一步