07 — 服务层 — Services

概述

src/services/ 包含所有后端服务逻辑。它的职责是封装外部通信（API 调用、MCP 连接、LSP 协议）和内部后台服务（上下文压缩、记忆提取、遥测）。

服务层与核心逻辑层的边界是：核心逻辑层负责"做什么"（调哪个工具、何时压缩），服务层负责"怎么做"（HTTP 请求细节、MCP 传输协议、压缩算法）。

服务架构总览

API 服务 (services/api/)

API 服务是 Claude Code 与 Anthropic 服务器通信的唯一通道。

claude.ts — 核心 API 调用

这是最关键的文件。它的核心函数 query() 执行一次 Claude Messages API 流式调用：

关键行为：

• 消息规范化 (normalizeMessagesForAPI): 确保每个 tool_use 后面都有对应的 tool_result（API 要求严格配对）
• Tool Schema 转换 (toolToAPISchema): 将内部 Tool 对象转为 API 需要的 JSON Schema 格式
• Betas 管理 (getMergedBetas): 根据模型和 feature flag 动态启用/禁用 beta 功能
• 缓存分段 (splitSysPromptPrefix): 在 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 处分割 system prompt，实现静态部分的 prompt cache

其他 API 文件

文件	说明	与其他模块的关系
client.ts	Anthropic SDK 客户端创建/配置	被 claude.ts 使用
bootstrap.ts	启动时预取的配置数据（费率、限制等）	被 main.tsx 在启动阶段调用
usage.ts	Token 用量查询	被 /usage 命令调用
filesApi.ts	文件上传/下载（share、teleport）	被 Share/Teleport 功能调用
errors.ts / errorUtils.ts	API 错误分类和处理	被 query.ts 的恢复逻辑使用
withRetry.ts	指数退避重试逻辑	通用基础设施
promptCacheBreakDetection.ts	检测 prompt cache 是否失效	优化 Token 费用
referral.ts	推荐/邀请码	账户相关
sessionIngress.ts	远程会话入口	Bridge 使用
grove.ts	Grove 集成	文件共享

MCP 服务 (services/mcp/)

MCP (Model Context Protocol) 允许 Claude Code 连接 外部工具服务器——这是最主要的扩展机制。

MCP 连接生命周期

传输类型

MCP 支持多种传输协议，根据服务器配置自动选择：

传输类型	说明	使用场景
stdio	启动子进程，通过 stdin/stdout 通信	本地 MCP 服务器（最常见）
HTTP (Streamable)	HTTP 请求/响应 + SSE	远程 MCP 服务器
SSE	Server-Sent Events 长连接	远程 MCP 服务器 (旧协议)
claude.ai-proxy	通过 claude.ai 代理	claude.ai 提供的官方 MCP
InProcess	同进程直接调用	Chrome MCP、Computer Use

MCP 工具调用流程

当模型调用 MCP 工具时，MCPTool.call() 将请求代理到对应的 MCP 服务器：

核心文件

文件	说明
client.ts	MCP 客户端管理（发现、连接、工具获取、代理调用） ~3600 行
MCPConnectionManager.tsx	连接生命周期管理（React 组件，管理 Hook 驱动的重连）
config.ts	MCP 配置读取（从 settings.json、.mcp.json、CLAUDE.md）
auth.ts	OAuth 认证（远程 MCP 服务器的 token 管理）
channelAllowlist.ts / channelPermissions.ts	Channel 权限控制
elicitationHandler.ts	交互式认证处理（弹出 OAuth 弹窗）
officialRegistry.ts	Anthropic 官方 MCP 服务器注册表
InProcessTransport.ts	进程内传输（用于内嵌 MCP 服务器）

Compact 服务 (services/compact/)

Compact 是 上下文压缩 系统。当对话消息超过模型的上下文窗口时，自动将旧消息摘要成一段简洁的总结。

为什么需要 Compact？

Claude 的上下文窗口有限（如 200k tokens）。一个持续的编程会话很容易超过这个限制。Compact 通过保留信息密度最高的部分、摘要其余部分，让对话可以无限持续。

触发机制

阈值计算: 有效上下文窗口 - 13,000 tokens (缓冲区) = 自动压缩触发点。

防死循环:

• 反应式压缩只尝试一次（hasAttemptedReactiveCompact 标志）
• 连续自动压缩失败 3 次后触发断路器，停止尝试

压缩过程

核心文件

文件	说明
compact.ts	主压缩逻辑 (~1700 行)
autoCompact.ts	自动压缩触发和断路器
microCompact.ts	微压缩（单消息级别，更轻量）
prompt.ts	摘要 prompt 模板
grouping.ts	消息分组（识别 API 轮次边界）
sessionMemoryCompact.ts	会话记忆优先压缩
postCompactCleanup.ts	压缩后清理

LSP 服务 (services/lsp/)

LSP (Language Server Protocol) 提供代码智能能力。Claude Code 启动语言服务器进程，通过 LSP 协议获取诊断信息、符号定义、引用等。

被动反馈: passiveFeedback.ts 监控 LSP 诊断（如 TypeScript 编译错误），在工具执行后自动注入诊断信息，帮助模型及时发现和修复错误。

Analytics 服务 (services/analytics/)

文件	说明
index.ts	logEvent() 主入口 — 所有遥测事件的统一接口
growthbook.ts	GrowthBook Feature Flags — 运行时 A/B 测试和功能开关
datadog.ts	Datadog 集成
firstPartyEventLogger.ts	Anthropic 第一方事件日志
sink.ts / sinkKillswitch.ts	数据汇总通道和紧急开关
config.ts	分析配置（用户可 opt-out）
metadata.ts	事件元数据（OS、版本、模型等）

记忆服务 (services/SessionMemory/, extractMemories/, teamMemorySync/)

服务	说明
SessionMemory/	会话记忆：在自动压缩时提取重要信息，下次会话可恢复
extractMemories/	记忆提取：从对话中识别值得持久化的信息（用户偏好、项目知识）
teamMemorySync/	团队记忆同步：多 Agent 间共享记忆，含 secret scanner 防止敏感信息泄露

其他服务

服务	说明	与其他模块的关系
oauth/	OAuth 认证流程 (authorization code flow)	被登录/MCP 认证使用
plugins/	插件安装/管理	被 /plugin 命令使用
policyLimits/	企业策略限制（如禁止某些工具）	被权限系统使用
remoteManagedSettings/	远程受管设置	企业管理员远程下发配置
settingsSync/	设置同步	多设备设置一致性
PromptSuggestion/	Prompt 建议 + 推测执行	预测用户下一步操作
autoDream/	后台 Dream（idle 时整理知识）	空闲时自动运行
MagicDocs/	自动生成 CLAUDE.md	首次进入新项目时
tips/	使用提示系统	渐进式引导用户
tools/	工具执行服务	见 06-Tool 系统
toolUseSummary/	工具使用摘要（Haiku 生成）	在状态栏显示工具操作摘要
voice.ts	语音转文字	语音模式
preventSleep.ts	防止系统睡眠	长时间任务运行时
notifier.ts	系统通知（iTerm2/Kitty/Bell）	任务完成通知
claudeAiLimits.ts	Claude.ai 配额检查	订阅用户限额管理