# 08 - 动态上下文注入系统 (Context Injection System)

## 1. 设计哲学

借鉴 Claude Code 的 attachment 系统：在每次 Claude API 调用之前，**动态组装最相关的上下文**注入到 messages 中。

核心原则：
- **按需注入**：不是所有上下文每次都注入，根据对话阶段和用户消息动态选择
- **优先级驱动**：当 context window 接近上限时，按优先级淘汰低优先级上下文
- **缓存友好**：高频不变的上下文利用 Prompt Caching 降低成本
- **格式统一**：所有上下文以统一的 XML-like 标签注入，方便 LLM 识别

## 2. 上下文类型总览

| 序号 | 类型标识 | 名称 | 数据源 | 优先级 | Cache TTL | 预估 Tokens |
|------|----------|------|--------|--------|-----------|-------------|
| 1 | `user_memory` | 用户历史记忆 | knowledge-service `/api/v1/memory/user/{id}/top` | P0 (最高) | 60s | 200-500 |
| 2 | `collected_info` | 已收集的用户信息 | 本地 ConsultingState.collectedInfo | P0 | 0 (实时) | 100-300 |
| 3 | `conversation_stats` | 对话统计 | 本地计算 (messages + timestamps) | P1 | 0 (实时) | 50-80 |
| 4 | `assessment_result` | 评估结果 | 本地 ConsultingState.assessmentResult | P0 | 0 (实时) | 200-400 |
| 5 | `relevant_knowledge` | 相关知识预检索 | knowledge-service `/api/v1/knowledge/retrieve/prompt` | P1 | 30s | 300-800 |
| 6 | `similar_experiences` | 系统经验 | knowledge-service `/api/v1/memory/experience/search` | P2 | 120s | 150-400 |
| 7 | `device_context` | 设备/地区信息 | ConversationGateway 传入的 deviceInfo | P2 | 对话生命周期 | 30-60 |
| 8 | `active_agents_history` | 最近 Agent 调用记录 | 本地 agentLoop 内存 | P1 | 0 (实时) | 100-300 |

**优先级说明**：
- **P0 (Critical)**：绝不丢弃，即使 context window 紧张也必须保留
- **P1 (Important)**：正常保留，极端情况下可压缩
- **P2 (Nice-to-have)**：context window 紧张时首先丢弃

## 3. TypeScript 类型定义

```typescript
// context.types.ts

/**
 * 上下文类型枚举
 */
export enum ContextType {
  USER_MEMORY = 'user_memory',
  COLLECTED_INFO = 'collected_info',
  CONVERSATION_STATS = 'conversation_stats',
  ASSESSMENT_RESULT = 'assessment_result',
  RELEVANT_KNOWLEDGE = 'relevant_knowledge',
  SIMILAR_EXPERIENCES = 'similar_experiences',
  DEVICE_CONTEXT = 'device_context',
  ACTIVE_AGENTS_HISTORY = 'active_agents_history',
}

/**
 * 上下文优先级
 */
export enum ContextPriority {
  CRITICAL = 0,   // P0: 绝不丢弃
  IMPORTANT = 1,  // P1: 正常保留
  NICE_TO_HAVE = 2, // P2: 可丢弃
}

/**
 * 单条上下文块
 */
export interface ContextBlock {
  type: ContextType;
  priority: ContextPriority;
  content: string;           // 格式化后的文本内容
  estimatedTokens: number;   // 预估 token 数
  timestamp: number;         // 生成时间（用于缓存判断）
  cacheTTL: number;          // 缓存有效期 (ms), 0 = 不缓存
  isEmpty: boolean;          // 是否为空（空的不注入）
}

/**
 * 上下文注入请求
 */
export interface ContextInjectionRequest {
  userId: string;
  conversationId: string;
  messages: Anthropic.MessageParam[];        // 当前对话历史
  currentUserMessage: string;                // 最新用户消息
  consultingState?: ConsultingState;         // 当前咨询状态
  deviceInfo?: DeviceInfo;                   // 设备信息
  agentHistory?: AgentExecutionRecord[];     // 最近 Agent 调用记录
  maxContextTokens?: number;                 // 上下文 token 上限 (default: 180000)
}

/**
 * 上下文注入结果
 */
export interface ContextInjectionResult {
  messages: Anthropic.MessageParam[];        // 注入上下文后的 messages
  injectedContexts: ContextType[];           // 实际注入了哪些上下文
  droppedContexts: ContextType[];            // 被丢弃的上下文（因 token 限制）
  totalContextTokens: number;                // 注入的上下文总 token 数
  compacted: boolean;                        // 是否触发了压缩
}

/**
 * Agent 执行记录（用于 active_agents_history）
 */
export interface AgentExecutionRecord {
  agentName: string;
  invokedAt: number;         // timestamp
  durationMs: number;
  inputSummary: string;      // 调用参数摘要
  outputSummary: string;     // 返回结果摘要（截断到 200 字符）
  tokensUsed: number;
}

/**
 * 上下文缓存条目
 */
interface ContextCacheEntry {
  block: ContextBlock;
  createdAt: number;
  expiresAt: number;         // createdAt + cacheTTL
}
```

## 4. 每种上下文的详细设计

### 4.1 user_memory — 用户历史记忆

**数据源**：knowledge-service 的 Memory API

```typescript
// API 调用
const memories = await knowledgeClient.getUserTopMemories(userId, 10);
// 返回: UserMemory[] — 按 importance 排序的用户记忆

// 备选：语义搜索（与当前消息相关的记忆）
const relevantMemories = await knowledgeClient.searchUserMemories({
  userId,
  query: currentUserMessage,
  limit: 5,
});
```

**注入格式**：

```xml
<user_memory>
以下是该用户的历史记录摘要（来自之前的对话）：
- [FACT] 用户35岁，本科学历，毕业于浙江大学 (重要度: 90)
- [FACT] 在互联网行业工作8年，目前年薪60万 (重要度: 85)
- [INTENT] 用户对高才通B类感兴趣 (重要度: 80)
- [PREFERENCE] 用户偏好文字交流，回复较简短 (重要度: 60)
- [FACT] 已婚，有一个3岁的孩子 (重要度: 70)
</user_memory>
```

**Freshness Policy**：
- Cache TTL: 60s（用户记忆在一次对话中变化不频繁）
- 首次调用时强制刷新
- 当 Memory Manager Agent 保存了新记忆后，立即 invalidate 缓存

**逻辑**：
```typescript
async function buildUserMemoryContext(
  userId: string,
  currentMessage: string,
  cache: Map<string, ContextCacheEntry>,
): Promise<ContextBlock> {
  const cacheKey = `user_memory:${userId}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() < cached.expiresAt) {
    return cached.block;
  }

  // 并行获取：Top 记忆 + 语义相关记忆
  const [topMemories, relevantMemories] = await Promise.all([
    knowledgeClient.getUserTopMemories(userId, 5),
    knowledgeClient.searchUserMemories({ userId, query: currentMessage, limit: 3 }),
  ]);

  // 合并去重
  const allMemories = deduplicateMemories([...topMemories, ...relevantMemories]);

  if (allMemories.length === 0) {
    return { type: ContextType.USER_MEMORY, priority: ContextPriority.CRITICAL, content: '', estimatedTokens: 0, timestamp: Date.now(), cacheTTL: 60000, isEmpty: true };
  }

  const content = formatMemoryBlock(allMemories);
  const block: ContextBlock = {
    type: ContextType.USER_MEMORY,
    priority: ContextPriority.CRITICAL,
    content,
    estimatedTokens: estimateTokens(content),
    timestamp: Date.now(),
    cacheTTL: 60000,
    isEmpty: false,
  };

  cache.set(cacheKey, { block, createdAt: Date.now(), expiresAt: Date.now() + 60000 });
  return block;
}
```

### 4.2 collected_info — 已收集的用户信息

**数据源**：本地 `ConsultingState.collectedInfo`（存储在 Conversation 实体中）

```typescript
// 直接从 state 读取，无需 API 调用
const collectedInfo = consultingState?.collectedInfo || {};
```

**注入格式**：

```xml
<collected_info>
本次对话已收集的用户信息：
- 年龄: 35
- 学历: 本科
- 毕业院校: 浙江大学
- 工作年限: 8年
- 行业: 互联网/IT
- 年收入: 约60万人民币
- 婚姻状况: 已婚
尚未收集: 语言能力、是否有香港联系、资产情况
</collected_info>
```

**Freshness Policy**：
- Cache TTL: 0（实时，每次从 state 读取）
- 零开销：纯本地数据，无 API 调用

**逻辑**：
```typescript
function buildCollectedInfoContext(consultingState?: ConsultingState): ContextBlock {
  const info = consultingState?.collectedInfo || {};
  const entries = Object.entries(info);

  if (entries.length === 0) {
    return emptyBlock(ContextType.COLLECTED_INFO, ContextPriority.CRITICAL);
  }

  // 映射 key 到中文标签
  const labelMap: Record<string, string> = {
    age: '年龄', education: '学历', university: '毕业院校',
    workYears: '工作年限', industry: '行业', annualIncome: '年收入',
    maritalStatus: '婚姻状况', children: '子女', languageAbility: '语言能力',
    hasHKConnection: '香港联系', assets: '资产情况', nationality: '国籍',
  };

  const collected = entries
    .map(([key, value]) => `- ${labelMap[key] || key}: ${value}`)
    .join('\n');

  // 计算未收集的核心字段
  const coreKeys = ['age', 'education', 'workYears', 'annualIncome', 'languageAbility', 'hasHKConnection'];
  const uncollected = coreKeys
    .filter(key => info[key] === undefined)
    .map(key => labelMap[key] || key)
    .join('、');

  const content = `<collected_info>\n本次对话已收集的用户信息：\n${collected}\n${uncollected ? `尚未收集: ${uncollected}` : '核心信息已收集完毕'}\n</collected_info>`;

  return {
    type: ContextType.COLLECTED_INFO,
    priority: ContextPriority.CRITICAL,
    content,
    estimatedTokens: estimateTokens(content),
    timestamp: Date.now(),
    cacheTTL: 0,
    isEmpty: false,
  };
}
```

### 4.3 conversation_stats — 对话统计

**数据源**：本地计算

```typescript
// 从 messages 数组和 conversation 实体计算
const stats = {
  totalTurns: messages.filter(m => m.role === 'user').length,
  duration: Date.now() - conversation.createdAt,
  currentStage: consultingState?.currentStageId,
  stageHistory: consultingState?.stageHistory,
  messagesInCurrentStage: consultingState?.stageTurnCount,
};
```

**注入格式**：

```xml
<conversation_stats>
对话统计：
- 总轮次: 8轮 (用户发言8次)
- 对话时长: 12分钟
- 当前阶段: 信息收集 (第3轮)
- 阶段历程: 开场破冰(2轮) → 需求了解(3轮) → 信息收集(进行中)
- 用户回复特点: 平均每次30字，回复较简短
</conversation_stats>
```

**Freshness Policy**：
- Cache TTL: 0（实时计算，无 API 开销）

**逻辑**：
```typescript
function buildConversationStatsContext(
  messages: Anthropic.MessageParam[],
  consultingState?: ConsultingState,
  conversationCreatedAt?: Date,
): ContextBlock {
  const userMessages = messages.filter(m => m.role === 'user');
  const totalTurns = userMessages.length;

  // 计算对话时长
  const durationMs = conversationCreatedAt
    ? Date.now() - conversationCreatedAt.getTime()
    : 0;
  const durationMinutes = Math.round(durationMs / 60000);

  // 分析用户回复特点
  const avgUserMsgLength = userMessages.reduce((sum, m) => {
    const text = typeof m.content === 'string' ? m.content : '';
    return sum + text.length;
  }, 0) / Math.max(userMessages.length, 1);

  const replyStyle = avgUserMsgLength < 20 ? '极简短，可能在移动设备'
    : avgUserMsgLength < 50 ? '较简短，需引导展开'
    : avgUserMsgLength < 150 ? '中等长度，表达较充分'
    : '详细表达，用户积极参与';

  // 构建阶段历程
  const stageNames: Record<string, string> = {
    greeting: '开场破冰', needs_discovery: '需求了解', info_collection: '信息收集',
    assessment: '评估', recommendation: '推荐', objection_handling: '异议处理',
    conversion: '转化促成', handoff: '专家对接',
  };

  let stageHistoryStr = '无';
  if (consultingState?.stageHistory) {
    stageHistoryStr = consultingState.stageHistory
      .map(h => `${stageNames[h.stageId] || h.stageId}(${h.turnsInStage}轮)`)
      .join(' → ');
  }

  const parts = [
    '<conversation_stats>',
    '对话统计：',
    `- 总轮次: ${totalTurns}轮`,
    `- 对话时长: ${durationMinutes}分钟`,
    `- 当前阶段: ${stageNames[consultingState?.currentStageId || ''] || '未知'} (第${(consultingState?.stageTurnCount || 0) + 1}轮)`,
    `- 阶段历程: ${stageHistoryStr}`,
    `- 用户回复特点: 平均每次${Math.round(avgUserMsgLength)}字，${replyStyle}`,
    '</conversation_stats>',
  ];

  const content = parts.join('\n');
  return {
    type: ContextType.CONVERSATION_STATS,
    priority: ContextPriority.IMPORTANT,
    content,
    estimatedTokens: estimateTokens(content),
    timestamp: Date.now(),
    cacheTTL: 0,
    isEmpty: false,
  };
}
```

### 4.4 assessment_result — 评估结果

**数据源**：本地 `ConsultingState.assessmentResult`

**注入格式**：

```xml
<assessment_result>
用户移民资格初步评估结果：
推荐方案: 高才通B类、优才计划
匹配度: 75分/100分
优势:
  - 名校毕业+工作经验充足
  - 工作经验丰富（8年）
  - 年龄优势明显（35岁）
注意事项:
  - 年薪未达高才通A类标准
  - 建议准备详细的工作业绩证明
提示: 这是基于初步信息的预评估。付费详细评估(¥99)将提供完整的评分报告和申请建议。
</assessment_result>
```

**Freshness Policy**：
- Cache TTL: 0（实时，一旦生成不会变化直到重新评估）
- 仅当 `consultingState.assessmentResult` 存在时注入

**逻辑**：
```typescript
function buildAssessmentResultContext(consultingState?: ConsultingState): ContextBlock {
  const result = consultingState?.assessmentResult;

  if (!result) {
    return emptyBlock(ContextType.ASSESSMENT_RESULT, ContextPriority.CRITICAL);
  }

  const parts = [
    '<assessment_result>',
    '用户移民资格初步评估结果：',
    `推荐方案: ${result.recommendedPrograms.join('、')}`,
    `匹配度: ${result.suitabilityScore}分/100分`,
  ];

  if (result.highlights.length > 0) {
    parts.push('优势:');
    result.highlights.forEach(h => parts.push(`  - ${h}`));
  }

  if (result.concerns.length > 0) {
    parts.push('注意事项:');
    result.concerns.forEach(c => parts.push(`  - ${c}`));
  }

  parts.push('提示: 这是基于初步信息的预评估。付费详细评估(¥99)将提供完整的评分报告和申请建议。');
  parts.push('</assessment_result>');

  const content = parts.join('\n');
  return {
    type: ContextType.ASSESSMENT_RESULT,
    priority: ContextPriority.CRITICAL,
    content,
    estimatedTokens: estimateTokens(content),
    timestamp: Date.now(),
    cacheTTL: 0,
    isEmpty: false,
  };
}
```

### 4.5 relevant_knowledge — 相关知识预检索

**数据源**：knowledge-service RAG API

```typescript
// 基于用户最新消息做语义检索
const knowledge = await knowledgeClient.retrieveForPrompt({
  query: currentUserMessage,
  userId,
  category: detectCategory(currentUserMessage), // 可选的类别过滤
});
```

**注入格式**：

```xml
<relevant_knowledge>
以下是与用户最新问题相关的知识库内容（仅供参考，请结合实际情况回答）：

来源：高才通计划申请指南 (相似度: 0.92)
> 高才通计划（TTPS）B类要求：申请人须持有全球百强大学颁授的学士学位，
> 并在申请前五年内累积至少三年工作经验。百强大学名单以最新公布的
> QS/Times/USNEWS/SJTU 四大排名综合为准...

来源：优才计划评分标准 (相似度: 0.85)
> 综合计分制下，学历最高可得45分（博士/双硕士），年龄18-39岁可得30分...
</relevant_knowledge>
```

**Freshness Policy**：
- Cache TTL: 30s（同一用户短时间内的消息通常主题相近）
- Cache Key: `relevant_knowledge:${userId}:${hashOf(currentMessage)}`
- 仅当用户消息涉及具体政策/条件/流程时注入

**条件注入逻辑**：
```typescript
async function buildRelevantKnowledgeContext(
  userId: string,
  currentMessage: string,
  cache: Map<string, ContextCacheEntry>,
): Promise<ContextBlock> {
  // 简单的关键词检测，判断是否需要知识检索
  const needsKnowledge = shouldRetrieveKnowledge(currentMessage);
  if (!needsKnowledge) {
    return emptyBlock(ContextType.RELEVANT_KNOWLEDGE, ContextPriority.IMPORTANT);
  }

  const cacheKey = `relevant_knowledge:${userId}:${simpleHash(currentMessage)}`;
  const cached = cache.get(cacheKey);
  if (cached && Date.now() < cached.expiresAt) {
    return cached.block;
  }

  const knowledge = await knowledgeClient.retrieveForPrompt({
    query: currentMessage,
    userId,
  });

  if (!knowledge) {
    return emptyBlock(ContextType.RELEVANT_KNOWLEDGE, ContextPriority.IMPORTANT);
  }

  const content = `<relevant_knowledge>\n以下是与用户最新问题相关的知识库内容（仅供参考，请结合实际情况回答）：\n\n${knowledge}\n</relevant_knowledge>`;

  const block: ContextBlock = {
    type: ContextType.RELEVANT_KNOWLEDGE,
    priority: ContextPriority.IMPORTANT,
    content,
    estimatedTokens: estimateTokens(content),
    timestamp: Date.now(),
    cacheTTL: 30000,
    isEmpty: false,
  };

  cache.set(cacheKey, { block, createdAt: Date.now(), expiresAt: Date.now() + 30000 });
  return block;
}

/**
 * 判断是否需要知识检索
 * 简单的关键词 + 模式匹配，避免每次都调 RAG API
 */
function shouldRetrieveKnowledge(message: string): boolean {
  const policyKeywords = [
    '高才通', 'TTPS', '优才', 'QMAS', '专才', 'GEP', '留学', 'IANG',
    '投资', 'CIES', '科技', 'TECHTAS', '条件', '要求', '资格', '申请',
    '流程', '材料', '费用', '时间', '打分', '评分', '签证', '续签',
    '永居', '居留', '配偶', '受养人', '政策', '最新',
  ];

  const lowerMessage = message.toLowerCase();
  return policyKeywords.some(kw => lowerMessage.includes(kw.toLowerCase()));
}
```

### 4.6 similar_experiences — 系统经验

**数据源**：knowledge-service Experience API（来自 evolution-service 的经验积累）

```typescript
const experiences = await knowledgeClient.searchExperiences({
  query: currentUserMessage,
  activeOnly: true,
  limit: 3,
});
```

**注入格式**：

```xml
<similar_experiences>
系统积累的相关经验（可参考但不必逐字照搬）：
1. [对话策略] 当用户表示"我还在考虑"时，不要急于推销，先询问具体顾虑点，
   再针对性解答。成功率比直接推进高40%。
2. [案例参考] 类似背景的用户（35岁+互联网+本科）通过优才计划成功的案例较多，
   建议重点介绍优才综合计分制的优势。
3. [异议处理] 对于"费用太贵"的异议，可以从投资回报角度切入：
   香港税收优势每年可节省X万...
</similar_experiences>
```

**Freshness Policy**：
- Cache TTL: 120s（系统经验更新频率低）
- 仅在信息收集、评估推荐、异议处理阶段注入

### 4.7 device_context — 设备/地区信息

**数据源**：ConversationGateway 在 WebSocket 连接时传入的 deviceInfo

```typescript
// 从 conversation 实体的 deviceInfo 字段获取
const deviceInfo = conversation.deviceInfo;
```

**注入格式**：

```xml
<device_context>
用户环境信息：
- 设备类型: 移动设备 (iPhone)
- 时区: UTC+8 (中国标准时间)
- 地区: 上海 (根据IP推断)
- 当前时间: 2025-01-15 周三 下午2:30
提示: 用户在手机上咨询，回复可适当简短。下午时段用户可能在工作间隙咨询。
</device_context>
```

**Freshness Policy**：
- Cache TTL: 整个对话生命周期（连接后设备信息不变）
- 仅在首次消息或每5轮注入一次（避免浪费 token）

### 4.8 active_agents_history — 最近 Agent 调用记录

**数据源**：agentLoop 内存中维护的 `AgentExecutionRecord[]`

**注入格式**：

```xml
<active_agents_history>
最近调用的专家 Agent（本次对话中）：
1. [2分钟前] Policy Expert - 查询高才通B类条件
   → 返回了详细的学历和工作经验要求
2. [1分钟前] Memory Manager - 保存用户信息（年龄35，浙大本科）
   → 已成功保存
注意: 避免重复调用相同 Agent 查询相同信息。如需进一步了解，可直接使用已获取的信息。
</active_agents_history>
```

**Freshness Policy**：
- Cache TTL: 0（实时，每次 API 调用都从内存读取最新记录）
- 仅保留最近 5 条记录
- 每条记录包含 agent 名称、时间、输入/输出摘要

## 5. ContextInjector 服务实现

```typescript
// context-injector.service.ts

import { Injectable } from '@nestjs/common';
import { KnowledgeClientService } from '../knowledge/knowledge-client.service';
import {
  ContextType, ContextPriority, ContextBlock,
  ContextInjectionRequest, ContextInjectionResult,
  ContextCacheEntry,
} from './context.types';
import Anthropic from '@anthropic-ai/sdk';

/**
 * Token 估算常量
 * 中文约 1.5-2 tokens/字符，英文约 0.25 tokens/word
 * 保守取 2 tokens/字符
 */
const TOKENS_PER_CHAR = 2;

/**
 * Claude Sonnet 的 context window 上限
 */
const MAX_CONTEXT_WINDOW = 200000;

/**
 * 为 output 预留的 tokens
 */
const RESERVED_OUTPUT_TOKENS = 4096;

/**
 * 为 system prompt 预留的 tokens（coordinator prompt 约 8000 tokens）
 */
const RESERVED_SYSTEM_TOKENS = 10000;

/**
 * 上下文注入触发的压缩阈值（占 context window 的百分比）
 */
const COMPACTION_THRESHOLD = 0.80;

@Injectable()
export class ContextInjectorService {
  /**
   * 内存缓存 — 按 conversationId 隔离
   * Map<conversationId, Map<cacheKey, ContextCacheEntry>>
   */
  private cacheStore = new Map<string, Map<string, ContextCacheEntry>>();

  constructor(
    private knowledgeClient: KnowledgeClientService,
  ) {}

  /**
   * 主入口：注入上下文
   *
   * 流程：
   * 1. 并行获取所有上下文块
   * 2. 过滤空块
   * 3. 按优先级排序
   * 4. 检查 token 预算，必要时丢弃低优先级块
   * 5. 组装成 context message 注入到 messages 数组
   * 6. 如果总 token 仍超限，触发 auto-compaction
   */
  async inject(request: ContextInjectionRequest): Promise<ContextInjectionResult> {
    const cache = this.getOrCreateCache(request.conversationId);
    const maxTokens = request.maxContextTokens || MAX_CONTEXT_WINDOW;
    const availableForContext = maxTokens - RESERVED_OUTPUT_TOKENS - RESERVED_SYSTEM_TOKENS;

    // ======== Step 1: 并行获取所有上下文 ========
    const contextBlocks = await this.fetchAllContexts(request, cache);

    // ======== Step 2: 过滤空块 ========
    const nonEmptyBlocks = contextBlocks.filter(b => !b.isEmpty);

    // ======== Step 3: 按优先级排序（P0 → P1 → P2）========
    nonEmptyBlocks.sort((a, b) => a.priority - b.priority);

    // ======== Step 4: Token 预算裁剪 ========
    const existingMessageTokens = this.estimateMessagesTokens(request.messages);
    let remainingTokenBudget = availableForContext - existingMessageTokens;

    const injected: ContextBlock[] = [];
    const dropped: ContextType[] = [];

    for (const block of nonEmptyBlocks) {
      if (block.estimatedTokens <= remainingTokenBudget) {
        injected.push(block);
        remainingTokenBudget -= block.estimatedTokens;
      } else if (block.priority === ContextPriority.CRITICAL) {
        // P0 级别：即使超限也要注入，但触发压缩
        injected.push(block);
        remainingTokenBudget -= block.estimatedTokens;
      } else {
        dropped.push(block.type);
      }
    }

    // ======== Step 5: 组装 context message ========
    const contextMessage = this.buildContextMessage(injected);
    const enrichedMessages = this.injectContextMessage(request.messages, contextMessage);

    // ======== Step 6: Auto-compaction ========
    const totalTokens = existingMessageTokens + injected.reduce((sum, b) => sum + b.estimatedTokens, 0);
    const utilizationRatio = totalTokens / availableForContext;
    let compacted = false;
    let finalMessages = enrichedMessages;

    if (utilizationRatio > COMPACTION_THRESHOLD) {
      finalMessages = await this.autoCompact(enrichedMessages, availableForContext);
      compacted = true;
    }

    return {
      messages: finalMessages,
      injectedContexts: injected.map(b => b.type),
      droppedContexts: dropped,
      totalContextTokens: injected.reduce((sum, b) => sum + b.estimatedTokens, 0),
      compacted,
    };
  }

  /**
   * 并行获取所有上下文块
   */
  private async fetchAllContexts(
    request: ContextInjectionRequest,
    cache: Map<string, ContextCacheEntry>,
  ): Promise<ContextBlock[]> {
    // 所有获取操作并行执行，互不依赖
    const [
      userMemory,
      collectedInfo,
      conversationStats,
      assessmentResult,
      relevantKnowledge,
      similarExperiences,
      deviceContext,
      agentsHistory,
    ] = await Promise.all([
      this.buildUserMemoryContext(request.userId, request.currentUserMessage, cache),
      this.buildCollectedInfoContext(request.consultingState),
      this.buildConversationStatsContext(request.messages, request.consultingState),
      this.buildAssessmentResultContext(request.consultingState),
      this.buildRelevantKnowledgeContext(request.userId, request.currentUserMessage, cache),
      this.buildSimilarExperiencesContext(request.currentUserMessage, request.consultingState, cache),
      this.buildDeviceContext(request.deviceInfo, request.messages.length),
      this.buildAgentsHistoryContext(request.agentHistory),
    ]);

    return [
      userMemory,
      collectedInfo,
      conversationStats,
      assessmentResult,
      relevantKnowledge,
      similarExperiences,
      deviceContext,
      agentsHistory,
    ];
  }

  /**
   * 将上下文块组装成一条 context message
   *
   * 设计选择：将所有上下文放在一条 system-level 的 user message 中，
   * 放在对话历史的最前面（在 previousMessages 之前）。
   *
   * 这样做的好处：
   * 1. 不污染 system prompt（system prompt 走 cache_control）
   * 2. 上下文随每次调用动态变化，不影响缓存命中率
   * 3. LLM 能清晰区分 "上下文信息" 和 "用户对话"
   */
  private buildContextMessage(blocks: ContextBlock[]): string {
    if (blocks.length === 0) return '';

    const parts = [
      '=== 动态上下文信息（系统自动注入，非用户输入） ===',
      '',
    ];

    for (const block of blocks) {
      parts.push(block.content);
      parts.push('');
    }

    parts.push('=== 以上为系统上下文，以下为用户对话 ===');
    return parts.join('\n');
  }

  /**
   * 将 context message 注入到 messages 数组
   *
   * 注入位置：作为第一条 user message，紧接着一条空的 assistant 确认
   * 这样不会打断后续的 user/assistant 交替模式
   */
  private injectContextMessage(
    messages: Anthropic.MessageParam[],
    contextMessage: string,
  ): Anthropic.MessageParam[] {
    if (!contextMessage) return messages;

    // 方案 A：注入为 messages 数组的前置消息对
    // 必须保持 user → assistant 交替
    return [
      { role: 'user', content: contextMessage },
      { role: 'assistant', content: '我已了解以上上下文信息，将在回复中参考使用。' },
      ...messages,
    ];
  }

  // ========== 各类上下文构建方法（详见 4.1-4.8）==========
  // 这里省略具体实现，见上方各小节

  private async buildUserMemoryContext(userId: string, currentMessage: string, cache: Map<string, ContextCacheEntry>): Promise<ContextBlock> { /* ... */ }
  private buildCollectedInfoContext(state?: any): ContextBlock { /* ... */ }
  private buildConversationStatsContext(messages: any[], state?: any): ContextBlock { /* ... */ }
  private buildAssessmentResultContext(state?: any): ContextBlock { /* ... */ }
  private async buildRelevantKnowledgeContext(userId: string, message: string, cache: Map<string, ContextCacheEntry>): Promise<ContextBlock> { /* ... */ }
  private async buildSimilarExperiencesContext(message: string, state: any, cache: Map<string, ContextCacheEntry>): Promise<ContextBlock> { /* ... */ }
  private buildDeviceContext(deviceInfo?: any, messageCount?: number): ContextBlock { /* ... */ }
  private buildAgentsHistoryContext(history?: any[]): ContextBlock { /* ... */ }

  // ========== 工具方法 ==========

  /**
   * 估算 messages 数组的 token 数
   */
  private estimateMessagesTokens(messages: Anthropic.MessageParam[]): number {
    let total = 0;
    for (const msg of messages) {
      if (typeof msg.content === 'string') {
        total += msg.content.length * TOKENS_PER_CHAR;
      } else if (Array.isArray(msg.content)) {
        for (const block of msg.content) {
          if (block.type === 'text') {
            total += (block as any).text.length * TOKENS_PER_CHAR;
          } else if (block.type === 'image') {
            total += 1000; // 图片约 1000 tokens
          }
        }
      }
    }
    return total;
  }

  private getOrCreateCache(conversationId: string): Map<string, ContextCacheEntry> {
    if (!this.cacheStore.has(conversationId)) {
      this.cacheStore.set(conversationId, new Map());
    }
    return this.cacheStore.get(conversationId)!;
  }

  /**
   * 清理对话缓存（对话结束时调用）
   */
  clearCache(conversationId: string): void {
    this.cacheStore.delete(conversationId);
  }

  /**
   * 使特定上下文类型的缓存失效
   * 例如 Memory Manager 保存了新记忆后，invalidate user_memory 缓存
   */
  invalidateContext(conversationId: string, contextType: ContextType): void {
    const cache = this.cacheStore.get(conversationId);
    if (!cache) return;

    // 删除该类型的所有缓存条目
    for (const [key, entry] of cache.entries()) {
      if (key.startsWith(contextType)) {
        cache.delete(key);
      }
    }
  }
}
```

## 6. Auto-Compaction 策略

当消息总 token 数接近 context window 上限时（超过 80%），自动触发压缩。

### 6.1 压缩算法

```typescript
/**
 * Auto-compaction: 自动压缩对话历史
 *
 * 策略（按优先级执行，每步检查是否降到阈值以下）：
 * 1. 移除 tool_result 中的详细内容，保留摘要
 * 2. 压缩早期对话为摘要（保留最近 10 轮完整）
 * 3. 截断过长的单条消息（超过 2000 字符的）
 * 4. 移除 P2 上下文块
 * 5. 压缩 P1 上下文块
 */
async autoCompact(
  messages: Anthropic.MessageParam[],
  tokenBudget: number,
): Promise<Anthropic.MessageParam[]> {
  let currentTokens = this.estimateMessagesTokens(messages);
  let compactedMessages = [...messages];

  // ---- 策略 1: 压缩 tool_result 内容 ----
  if (currentTokens > tokenBudget * COMPACTION_THRESHOLD) {
    compactedMessages = this.compactToolResults(compactedMessages);
    currentTokens = this.estimateMessagesTokens(compactedMessages);
  }

  // ---- 策略 2: 早期对话摘要化 ----
  if (currentTokens > tokenBudget * COMPACTION_THRESHOLD) {
    compactedMessages = await this.summarizeEarlyMessages(compactedMessages, 10);
    currentTokens = this.estimateMessagesTokens(compactedMessages);
  }

  // ---- 策略 3: 截断过长消息 ----
  if (currentTokens > tokenBudget * COMPACTION_THRESHOLD) {
    compactedMessages = this.truncateLongMessages(compactedMessages, 2000);
    currentTokens = this.estimateMessagesTokens(compactedMessages);
  }

  return compactedMessages;
}

/**
 * 压缩 tool_result：将详细的 JSON 结果替换为一行摘要
 */
private compactToolResults(messages: Anthropic.MessageParam[]): Anthropic.MessageParam[] {
  return messages.map(msg => {
    if (msg.role !== 'user' || !Array.isArray(msg.content)) return msg;

    const compactedContent = (msg.content as any[]).map(block => {
      if (block.type === 'tool_result') {
        const originalContent = typeof block.content === 'string'
          ? block.content
          : JSON.stringify(block.content);

        // 如果 tool_result 超过 500 字符，压缩为摘要
        if (originalContent.length > 500) {
          return {
            ...block,
            content: `[已压缩] ${originalContent.slice(0, 200)}... (原始长度: ${originalContent.length}字符)`,
          };
        }
      }
      return block;
    });

    return { ...msg, content: compactedContent };
  });
}

/**
 * 将早期对话（保留最近 N 轮完整）压缩为摘要
 * 使用 Haiku 模型做快速摘要，成本极低
 */
private async summarizeEarlyMessages(
  messages: Anthropic.MessageParam[],
  keepRecentTurns: number,
): Promise<Anthropic.MessageParam[]> {
  // 找到上下文注入消息对（前2条）和对话消息
  const contextPair = messages.slice(0, 2);  // context injection pair
  const dialogMessages = messages.slice(2);

  // 计算需要保留的最近消息数（每轮 = 1 user + 1 assistant = 2条）
  const keepCount = keepRecentTurns * 2;

  if (dialogMessages.length <= keepCount) {
    return messages; // 没有足够的早期消息需要压缩
  }

  const earlyMessages = dialogMessages.slice(0, -keepCount);
  const recentMessages = dialogMessages.slice(-keepCount);

  // 用 Haiku 快速摘要早期对话
  const earlyText = earlyMessages
    .map(m => `${m.role}: ${typeof m.content === 'string' ? m.content : '[complex content]'}`)
    .join('\n');

  const summaryResponse = await this.anthropic.messages.create({
    model: 'claude-haiku-4-20250514',
    max_tokens: 500,
    messages: [{
      role: 'user',
      content: `请用200字以内概括以下对话的要点（保留关键信息如用户背景、已讨论的移民方案等）：\n\n${earlyText}`,
    }],
  });

  const summary = summaryResponse.content[0].type === 'text'
    ? summaryResponse.content[0].text
    : '';

  // 组装：上下文 + 摘要 + 最近消息
  return [
    ...contextPair,
    { role: 'user', content: `[以下是之前对话的摘要]\n${summary}\n[摘要结束，以下是最近的对话]` },
    { role: 'assistant', content: '好的，我了解了之前的讨论内容，我们继续。' },
    ...recentMessages,
  ];
}
```

### 6.2 Compaction 触发时机

```
消息 token 数 / 可用 token 预算:

0%  ──────── 50% ──────── 80% ──────── 95% ──── 100%
│          正常区域          │  压缩区域   │ 危险区域  │
│                           │             │           │
│   不做任何处理             │ 触发策略1-3  │ 触发策略4-5│
│                           │ 压缩日志     │ 强制压缩   │
│                           │ 通知前端     │ 可能截断   │
```

## 7. 完整数据流

```
用户发送消息
      │
      ▼
ConversationService.sendMessage()
      │
      ▼
CoordinatorAgentService.sendMessage()
      │
      ▼
  ┌───────────────────────────┐
  │   ContextInjector.inject() │
  │                            │
  │  ┌─────────────────────┐  │
  │  │  Promise.all([       │  │
  │  │    fetchUserMemory,  │──┼──→ knowledge-service (HTTP)
  │  │    fetchKnowledge,   │──┼──→ knowledge-service (HTTP)
  │  │    fetchExperiences, │──┼──→ knowledge-service (HTTP)
  │  │    buildLocalCtx...  │  │    (本地计算，无 I/O)
  │  │  ])                  │  │
  │  └──────────┬──────────┘  │
  │             │              │
  │  ┌──────────▼──────────┐  │
  │  │  Token Budget Check  │  │
  │  │  排序 → 裁剪 → 注入  │  │
  │  └──────────┬──────────┘  │
  │             │              │
  │  ┌──────────▼──────────┐  │
  │  │  Auto-Compaction     │  │
  │  │  (如果 > 80%)        │  │
  │  └──────────┬──────────┘  │
  │             │              │
  │  Return: enrichedMessages │
  └─────────────┬─────────────┘
                │
                ▼
        Claude API 调用
   (system prompt + enrichedMessages + tools)
```

## 8. 缓存失效策略

| 事件 | 失效的缓存 | 方式 |
|------|-----------|------|
| Memory Manager 保存了新记忆 | `user_memory:${userId}` | `invalidateContext()` 主动失效 |
| 评估完成 | `assessment_result` | 直接更新 state，无需缓存 |
| 对话结束 | 该对话的所有缓存 | `clearCache(conversationId)` |
| 用户长时间不活跃 (>5min) | 所有外部数据缓存 | TTL 自动过期 |
| 知识库更新 | `relevant_knowledge` | TTL 自动过期（30s）|

## 9. 性能指标

| 指标 | 目标 | 备注 |
|------|------|------|
| 上下文注入耗时 | < 200ms | 并行获取 + 缓存命中时 < 10ms |
| 缓存命中率 | > 70% | 同一对话中连续消息通常命中 |
| Auto-compaction 耗时 | < 2s | 使用 Haiku 做摘要时 |
| 上下文 token 占比 | 5-15% | 占总 context window 的比例 |
| API 调用次数 | 0-3 per injection | 缓存命中时为 0 |

## 10. 与旧架构的对比

| 方面 | 旧架构 (ClaudeAgentServiceV2) | 新架构 (ContextInjector) |
|------|-------------------------------|--------------------------|
| 上下文来源 | `buildSystemPrompt()` 固定拼接 | 8 种动态上下文，按需注入 |
| 缓存 | 无 | 多级缓存，TTL 策略 |
| Token 管理 | `calculateMaxTokens()` 限制输出 | 完整的输入+输出 token 预算管理 |
| 压缩 | 固定取 last 20 messages | 自动压缩，摘要化早期对话 |
| 用户记忆 | `context.userMemory` 字符串数组 | 结构化 UserMemory，语义搜索 |
| 知识注入 | 工具调用时才检索 | 预检索，主动注入相关知识 |
| 经验利用 | `getAccumulatedExperience()` 简单拼接 | 语义匹配，按场景注入 |
| 设备适配 | `buildDeviceContext()` 仅首次 | 持续参考，影响回复风格 |