# 后端服务

Codev 提供一系列后台服务，涵盖 MCP 集成、上下文压缩、自主记忆整合、即时通讯集成、OAuth 认证、分析监控及工具执行引擎。

---

## MCP (Model Context Protocol)

**目录**: `src/services/mcp/`

MCP 客户端实现，基于 `@modelcontextprotocol/sdk`，支持多种传输层协议和 OAuth 认证。

### 核心文件

| 文件 | 描述 |
|------|------|
| `client.ts` | MCP 客户端 — 支持 Stdio、SSE、Streamable HTTP 三种传输协议；管理工具/资源/命令的发现与调用 |
| `auth.ts` | MCP OAuth 认证 — 基于 Authorization Server Metadata 发现流程，支持 PKCE、令牌刷新、本地 HTTP 服务器捕获授权码 |
| `config.ts` | MCP Server 配置解析 |
| `types.ts` | MCP 相关类型定义 |
| `InProcessTransport.ts` | 同进程传输层实现 |
| `SdkControlTransport.ts` | SDK Control 传输层 |
| `normalization.ts` | MCP 结果规范化 |
| `envExpansion.ts` | 环境变量展开 |
| `headersHelper.ts` | HTTP 头部辅助 |
| `elicitationHandler.ts` | MCP Elicit 请求处理 |
| `mcpStringUtils.ts` | MCP 字符串工具 |
| `claudeai.ts` | Claude AI 集成 |
| `officialRegistry.ts` | 官方 MCP 注册表 |
| `useManageMCPConnections.ts` | MCP 连接管理 Hook |
| `vscodeSdkMcp.ts` | VSCode SDK 兼容层 |
| `channelAllowlist.ts` / `channelPermissions.ts` / `channelNotification.ts` | 频道权限与通知 |
| `MCPConnectionManager.tsx` | MCP 连接管理器 UI 组件 |
| `xaa.ts` / `xaaIdpLogin.ts` | XAA 身份提供方登录 |
| `oauthPort.ts` | OAuth 回调端口管理 |

### 支持的传输协议

1. **StdioClientTransport** — 子进程标准输入/输出
2. **SSEClientTransport** — Server-Sent Events
3. **StreamableHTTPClientTransport** — 可流式 HTTP

### 发现能力

工具（Tools）、资源（Resources）、提示（Prompts）的自动发现与调用。

---

## 上下文压缩

**目录**: `src/services/compact/`

上下文压缩引擎，在对话历史超出上下文窗口时自动触发压缩，将冗长的历史会话压缩为精炼的摘要。

### 核心文件

| 文件 | 大小 | 描述 |
|------|------|------|
| `compact.ts` | 61 KB | **核心压缩引擎** — 将对话历史压缩为摘要，包含完整的压缩策略与边界消息管理 |
| `autoCompact.ts` | — | **自动压缩** — 当上下文窗口使用量超过阈值时自动触发压缩，管理 maxTokens、重试逻辑、token 估算 |
| `microCompact.ts` | — | **微压缩** — 细粒度工具结果压缩，仅压缩特定工具（FileRead、FileEdit、FileWrite、Glob、Grep、WebFetch、WebSearch 等）的输出 |
| `sessionMemoryCompact.ts` | — | **会话记忆压缩** — 实验性功能，将会话记忆压缩整合到会话恢复流程中 |
| `cachedMicrocompact.ts` | — | 缓存式微压缩，提升重复压缩效率 |
| `cachedMCConfig.ts` | — | 缓存微压缩配置 |
| `snipCompact.ts` / `snipProjection.ts` | — | 截断式压缩与投影 |
| `grouping.ts` | — | 消息分组策略 |
| `reactiveCompact.ts` | — | 响应式压缩 |
| `timeBasedMCConfig.ts` | — | 基于时间的微压缩配置 |
| `postCompactCleanup.ts` | — | 压缩后清理 |
| `prompt.ts` | — | 压缩提示词模板 |
| `apiMicrocompact.ts` | — | API 微压缩接口 |
| `compactWarningHook.ts` / `compactWarningState.ts` | — | 压缩警告 UI 状态管理 |

### 压缩流程

1. `autoCompact` 监控上下文窗口使用率
2. 当超过阈值时，调用 `compactConversation()`（在 `compact.ts` 中）
3. 压缩引擎提取历史消息，调用 AI 生成摘要
4. 摘要替换原始历史消息，压缩边界消息标记范围
5. `sessionMemoryCompact` 可选地将会话记忆额外压缩
6. `microCompact` 对工具结果进行细粒度压缩以进一步节省 token
7. `postCompactCleanup` 执行压缩后清理

---

## Auto Dream (自主记忆整合)

**目录**: `src/services/autoDream/`

Auto Dream 是一个后台记忆整合系统，在对话间期自动运行，将学习到的信息整理为持久化的记忆文件。

### 核心文件

| 文件 | 描述 |
|------|------|
| `autoDream.ts` | 主模块 — 后台记忆中整合，使用 `runForkedAgent` 执行 `/dream` 提示词。使用三道门控（Gate）按成本递增顺序判断是否执行：时间（距上次整合 >= minHours）、会话数（新会话 >= minSessions）、锁（无其他进程正在整合） |
| `config.ts` | 配置 — 是否启用 Auto Dream |
| `consolidationLock.ts` | 整合锁 — 基于 PID 和 mtime 的文件锁，防止多个进程同时整合。锁文件位于记忆目录，mtime 作为 `lastConsolidatedAt` 时间戳 |
| `consolidationPrompt.ts` | 整合提示词 — 构建 `/dream` 的系统提示词，指导 AI 反思记忆文件并整理为持久化知识 |

### 门控顺序

1. **时间门控**: 距上次整合 >= 最小小时数（一个 stat 调用，最便宜）
2. **会话门控**: 新产生的会话记录数 >= 最小会话数
3. **锁门控**: 无其他进程正在进行整合（最昂贵）

### 整合内容

- 回顾记忆目录中的 `.md` 文件
- 分析近期会话记录（transcript）
- 合成新的记忆，整理现有知识
- 确保记忆文件对后续会话具有良好可读性

---

## 飞书集成

**目录**: `src/services/feishu/`

飞书（Feishu/Lark）机器人集成，基于 `@larksuite/channel` SDK 的 WebSocket 长连接机器人。

详见 [飞书集成文档](feishu.md)。

### 功能速览

- 应用注册（支持 QR 码一键创建）
- DM 私聊 / Group 群聊模式
- 访问控制（白名单 / 管理员 / 拥有者）
- 引用上下文回复
- Markdown 格式化输出
- 语音回复（Edge TTS / VoxCPM 语音克隆）
- Keepalive 自动保活

---

## Telegram 集成

**文件**: `src/services/telegram/TelegramService.ts`

Telegram 机器人服务，基于 Telegram Bot API 实现消息收发、指令处理、行内键盘等功能。

### 功能

- `getMe` — 获取机器人信息
- `sendMessage` — 发送消息（支持 Markdown / HTML 格式）
- `editMessageText` — 编辑已发送消息
- `answerCallbackQuery` — 响应回调查询
- `sendChatAction` — 发送聊天动作指示器
- `setMyCommands` — 设置机器人命令列表
- `getUpdates` — 轮询获取更新

配置管理: `telegramConfig.ts` / `telegramTypes.ts`

---

## OAuth

**目录**: `src/services/oauth/`

通用 OAuth 2.0 认证服务，支持授权码流程（Authorization Code Flow with PKCE）。

### 核心文件

| 文件 | 描述 |
|------|------|
| `index.ts` | `OAuthService` — 主类，管理完整 OAuth 流程：生成 code_verifier、启动本地 HTTP 服务器监听回调、令牌交换 |
| `auth-code-listener.ts` | 授权码监听器 — 启动本地 HTTP 服务器捕获回调中的授权码 |
| `client.ts` | OAuth 客户端 HTTP 请求封装 |
| `crypto.ts` | PKCE 加密工具 — code_verifier / code_challenge 生成 |
| `getOauthProfile.ts` | 获取 OAuth 用户档案 |
| `types.ts` | OAuth 类型定义（令牌、速率限制、订阅类型等） |

### 流程

1. 生成 PKCE code_verifier 和 code_challenge
2. 构建授权 URL 并打开浏览器
3. 本地 HTTP 服务器监听回调 / 用户手动粘贴授权码
4. 用授权码换取令牌（access_token + refresh_token）
5. 支持令牌刷新和持久化

---

## 分析 (Analytics)

**目录**: `src/services/analytics/`

### 核心组件

| 文件 | 描述 |
|------|------|
| `index.ts` | 分析日志入口 — 标准化事件日志接口 |
| `growthbook.ts` | GrowthBook 特性标记集成 — 远程配置和 A/B 测试功能开关 |
| `config.ts` | Analytics 配置 |
| `metadata.ts` | 分析元数据提取 — 工具名称脱敏、MCP 工具详情、文件扩展名 |
| `datadog.ts` | Datadog 集成 |
| `firstPartyEventLogger.ts` / `firstPartyEventLoggingExporter.ts` | 第一方事件日志与导出 |
| `sink.ts` / `sinkKillswitch.ts` | 事件接收器与终止开关 |

### 功能

- 工具使用统计与耗时追踪
- 模型调用分析
- GrowthBook 远程特性配置
- Datadog APM 集成

---

## 工具执行引擎

**目录**: `src/services/tools/`

### 核心文件

| 文件 | 大小 | 描述 |
|------|------|------|
| `toolExecution.ts` | 60 KB | **工具执行引擎** — 核心工具运行逻辑，管理工具调用生命周期、权限检查、进度报告、结果处理 |
| `toolHooks.ts` | — | **工具钩子系统** — 执行 Pre-Tool 和 Post-Tool 挂钩，支持基于规则和基于审批的权限决策 |
| `StreamingToolExecutor.ts` | — | **流式工具执行器** — 管理并发工具执行队列，支持工具状态追踪（queued / executing / completed / yielded），支持进度消息即时推流 |
| `toolOrchestration.ts` | — | **工具编排** — 高级工具调度与编排逻辑 |

### 工具执行流程

1. **Pre-Tool Hooks**: 权限检查、规则匹配、审批流程
2. **工具调用**: 查找工具定义 -> 执行 -> 收集结果
3. **Post-Tool Hooks**: 结果处理、日志记录、统计更新
4. **Streaming**: 支持并发工具执行，进度实时推送