docs/services/overview.md

后端服务

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 长连接机器人。

详见 飞书集成文档。

功能速览

• 应用注册（支持 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: 支持并发工具执行，进度实时推送