iconsulting/docs/architecture/06-case-analyst-agent.md

06 - Case Analyst Agent (案例分析师) 设计详解

1. 核心职责

Case Analyst 是系统中的案例匹配引擎。当 Coordinator 需要用真实案例来增强说服力时（评估后展示、异议处理、犹豫用户激励），调用此 Agent 从知识库中查找并呈现最相关的成功案例。

核心能力：

1. 案例检索 -- 从知识库中搜索与用户画像最匹配的成功案例
2. 相似度评估 -- 计算用户条件与案例主角的匹配程度
3. 关键因素提取 -- 分析案例成功的关键因素，映射到当前用户的优劣势
4. 时间线参考 -- 提供案例从准备到获批的时间线供用户参考
5. 差异化呈现 -- 在多个案例之间做差异化展示，覆盖不同角度

设计原则：案例必须来自知识库，不可捏造。 如果没有匹配的案例，诚实说明而不是编故事。

2. 模型与参数

{
  model: 'claude-haiku-3-5-20241022',  // 主要是搜索+格式化，不需要 Sonnet
  max_tokens: 1500,
  temperature: 0,                       // 案例呈现需要准确性
  system: [
    {
      type: 'text',
      text: caseAnalystPrompt,
      cache_control: { type: 'ephemeral' }
    }
  ],
}

选用 Haiku 的理由：

• 核心工作是搜索知识库 + 结构化整理，不涉及复杂推理
• 需要快速返回结果（用户在等待中）
• 成本敏感 -- 案例查找可能频繁触发，Haiku 成本仅为 Sonnet 的 1/10
• 输入/输出格式固定，Haiku 足以胜任

3. 可用工具 (Available Tools)

Case Analyst 有 2 个工具：

3.1 search_knowledge

{
  name: 'search_knowledge',
  description: '搜索知识库中的成功案例、客户故事、申请经验。搜索时应包含用户的核心特征（行业、学历、年龄段）作为关键词。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '案例搜索查询，如"IT行业硕士30岁高才通成功案例"'
      },
      category: {
        type: 'string',
        enum: ['QMAS', 'GEP', 'IANG', 'TTPS', 'CIES', 'TECHTAS'],
        description: '移民类别，用于缩小案例搜索范围'
      }
    },
    required: ['query']
  }
}

3.2 get_user_context

{
  name: 'get_user_context',
  description: '获取用户的详细背景信息，用于更精准地匹配案例。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '检索用户背景，如"用户的学历工作行业信息"'
      }
    },
    required: ['query']
  }
}

4. System Prompt 要点

# 身份
你是 iConsulting 的案例分析师。你的任务是从知识库中查找与当前用户最匹配的成功案例。

# 核心原则
1. 所有案例必须来自知识库搜索结果，绝不能编造
2. 如果没有高度匹配的案例，诚实说明并提供最接近的参考
3. 案例呈现要突出与用户的相似点，让用户产生共鸣
4. 同时指出案例与用户的差异，保持客观
5. 优先展示最近的案例（时效性更强）

# 搜索策略
- 第一轮搜索：用用户的核心特征组合（行业+学历+类别）
- 如果结果不足：放宽条件，搜索同行业或同类别的案例
- 最多搜索 2 轮

# 相似度评分标准（0-100）
- 同行业 +25
- 同学历层次 +20
- 年龄差在5岁内 +15
- 同移民类别 +20
- 同地区/城市 +10
- 工作年限差在3年内 +10

# 输出格式
必须返回 JSON，包含 matched_cases[]、similarity_analysis、timeline_reference

5. 输入/输出格式

输入 (Coordinator 传入)

interface CaseAnalystInput {
  /** 用户的核心画像 */
  userProfile: {
    age?: number;
    education?: string;
    university?: string;
    industry?: string;
    yearsOfExperience?: number;
    annualIncome?: number;
    targetCategory?: string;
  };
  /** 目标移民类别 */
  targetCategory: 'QMAS' | 'GEP' | 'IANG' | 'TTPS' | 'CIES' | 'TECHTAS';
  /** 案例搜索的侧重点（可选） */
  focus?: 'success_story' | 'timeline' | 'similar_background' | 'overcoming_weakness';
}

输出 (返回给 Coordinator)

interface CaseAnalystOutput {
  /** 匹配到的案例列表（按相似度排序） */
  matched_cases: Array<{
    /** 案例标题/代号 */
    case_title: string;
    /** 案例主角的背景摘要 */
    profile_summary: string;
    /** 申请的移民类别 */
    category: string;
    /** 与当前用户的相似度（0-100） */
    similarity_score: number;
    /** 相似点列表 */
    similarities: string[];
    /** 差异点列表 */
    differences: string[];
    /** 成功的关键因素 */
    key_success_factors: string[];
    /** 案例时间线 */
    timeline?: {
      preparation: string;    // 准备期
      application: string;    // 申请期
      approval: string;       // 审批期
      total: string;          // 总耗时
    };
    /** 来源引用 */
    source?: {
      title: string;
      article_id?: string;
    };
  }>;

  /** 综合相似度分析 */
  similarity_analysis: {
    best_match_score: number;         // 最高匹配分数
    average_score: number;            // 平均匹配分数
    match_quality: 'high' | 'medium' | 'low' | 'none';
    summary: string;                  // 一句话总结匹配情况
  };

  /** 时间线参考（综合多个案例） */
  timeline_reference: {
    estimated_preparation: string;    // 预计准备时间
    estimated_processing: string;     // 预计审批时间
    estimated_total: string;          // 预计总时间
    factors_affecting_timeline: string[];  // 影响时间的因素
  };

  /** 如果无匹配案例 */
  no_match_reason?: string;
}

6. 触发时机 (When to Trigger)

Coordinator 在以下场景调用 invoke_case_analyst：

场景	目的	触发条件
评估结果呈现后	用案例增强推荐说服力	评估完成，需要展示同类成功案例
用户犹豫不决	用案例激励用户	Strategist 建议 build_rapport
异议处理中	用案例回应"能成功吗"的顾虑	Objection Handler 建议 provide_more_data
用户主动要求	"有没有类似的案例？"	用户直接询问案例
时间线问题	用案例提供时间参考	用户问"要多久"

不应触发的场景：

• 对话初期，用户信息不足（无法做有效匹配）
• 用户在问纯政策问题（调 Policy Expert）
• 已经展示过案例且用户没有追问

7. 内部循环 (Internal Loop)

Case Analyst 的 agent loop 最多 2 轮 tool 调用，设计为快进快出：

┌─────────────────────────────────────────────────────┐
│  Case Analyst Internal Loop (max 2 turns)           │
│                                                      │
│  Turn 0: 主搜索                                      │
│  ├── 构建搜索查询：                                  │
│  │   "{industry} {education} {age}岁                 │
│  │    {targetCategory} 成功案例"                      │
│  ├── search_knowledge({query, category})             │
│  │                                                   │
│  ├── 结果分析：                                       │
│  │   ├── 找到 2+ 相关案例 → 直接生成输出，结束       │
│  │   ├── 找到 0-1 条 → 放宽条件进入 Turn 1           │
│  │   └── 找到 0 条 → 返回 no_match_reason           │
│  │                                                   │
│  Turn 1: 补充搜索（放宽条件）                         │
│  ├── 放宽策略：                                       │
│  │   ├── 去掉年龄限制                                │
│  │   ├── 只保留行业 + 类别                           │
│  │   └── 或搜索同类别的通用成功案例                   │
│  ├── search_knowledge({query: 放宽后的查询})          │
│  │                                                   │
│  └── 综合两轮结果生成输出                             │
└─────────────────────────────────────────────────────┘

搜索查询构建逻辑：

function buildCaseSearchQuery(input: CaseAnalystInput): string {
  const parts: string[] = [];

  // 核心维度
  if (input.userProfile.industry) parts.push(input.userProfile.industry);
  if (input.userProfile.education) parts.push(input.userProfile.education);
  if (input.userProfile.age) {
    const ageRange = input.userProfile.age < 30 ? '20多岁' :
                     input.userProfile.age < 40 ? '30多岁' : '40多岁';
    parts.push(ageRange);
  }

  // 类别
  const categoryNames: Record<string, string> = {
    QMAS: '优才计划', GEP: '专才计划', IANG: 'IANG',
    TTPS: '高才通', CIES: '投资移民', TECHTAS: '科技人才'
  };
  parts.push(categoryNames[input.targetCategory] || input.targetCategory);
  parts.push('成功案例');

  return parts.join(' ');
}

8. 与其他 Agent 的关系

┌──────────────┐     invoke_case_analyst       ┌──────────────┐
│              │ ─────────────────────────────→ │              │
│  Coordinator │     CaseAnalystOutput         │ Case         │
│              │ ←───────────────────────────── │ Analyst      │
└──────┬───────┘                                └──────┬───────┘
       │                                               │
       │  常见协作模式：                                 ├── search_knowledge
       │                                               └── get_user_context
       │  模式 A：评估 + 案例（增强说服）
       │  ├── invoke_assessment_expert (并行)
       │  └── invoke_case_analyst     (并行)
       │      → Coordinator 综合评估结果和案例一起呈现
       │
       │  模式 B：异议 + 案例（回应质疑）
       │  ├── invoke_objection_handler
       │  └── invoke_case_analyst
       │      → Coordinator 用案例数据支撑异议回应
       │
       │  模式 C：单独使用（用户主动问案例）
       │  └── invoke_case_analyst
       │      → Coordinator 直接转述案例

并行调用优化： Case Analyst 和 Assessment Expert 可以并行调用，因为两者互不依赖：

// Coordinator 同时发起两个 Agent 调用
const [assessmentResult, caseResult] = await Promise.all([
  invokeAssessmentExpert({ userInfo }),
  invokeCaseAnalyst({ userProfile, targetCategory: 'TTPS' }),
]);
// 综合两者结果生成回复

9. 示例场景

场景 1：IT 从业者查找高才通案例

Coordinator 调用：

{
  "tool": "invoke_case_analyst",
  "input": {
    "userProfile": {
      "age": 32,
      "education": "硕士",
      "university": "浙江大学",
      "industry": "IT/科技",
      "yearsOfExperience": 8,
      "targetCategory": "TTPS"
    },
    "targetCategory": "TTPS",
    "focus": "success_story"
  }
}

内部执行：

Turn 0: search_knowledge({
  query: "IT科技 硕士 30多岁 高才通 成功案例",
  category: "TTPS"
})
→ 找到 2 条相关案例
→ 信息充足，直接生成输出

返回结果：

{
  "matched_cases": [
    {
      "case_title": "资深前端工程师 高才通B类获批",
      "profile_summary": "33岁，华中科技大学硕士，前端开发9年经验，曾就职于腾讯、字节跳动",
      "category": "TTPS B类",
      "similarity_score": 82,
      "similarities": [
        "同为IT/科技行业",
        "硕士学历",
        "年龄接近（33 vs 32）",
        "工作经验相近（9年 vs 8年）",
        "均为百强大学毕业"
      ],
      "differences": [
        "案例为华中科技大学（用户为浙江大学）",
        "案例有大厂经历（腾讯、字节）"
      ],
      "key_success_factors": [
        "百强大学硕士满足B类学历要求",
        "9年经验远超B类最低3年要求",
        "IT行业为香港重点发展领域",
        "准备了详细的项目经验证明"
      ],
      "timeline": {
        "preparation": "约2周（材料准备）",
        "application": "1天（在线提交）",
        "approval": "5周",
        "total": "约7周"
      },
      "source": {
        "title": "IT行业高才通成功案例集",
        "article_id": "case-ttps-it-001"
      }
    },
    {
      "case_title": "AI算法工程师 高才通B类获批",
      "profile_summary": "29岁，北京大学学士+硕士，AI/机器学习方向5年经验，年薪50万",
      "category": "TTPS B类",
      "similarity_score": 68,
      "similarities": [
        "IT/科技行业",
        "百强大学",
        "高才通B类路径"
      ],
      "differences": [
        "年龄较轻（29 vs 32）",
        "工作经验较少（5年 vs 8年）",
        "北大 vs 浙大"
      ],
      "key_success_factors": [
        "AI领域高度匹配香港科技发展战略",
        "虽然经验年限不长但项目含金量高",
        "准备了发表论文和专利清单"
      ],
      "timeline": {
        "preparation": "约1周",
        "application": "1天",
        "approval": "4周",
        "total": "约5周"
      },
      "source": {
        "title": "AI领域人才高才通案例",
        "article_id": "case-ttps-ai-001"
      }
    }
  ],
  "similarity_analysis": {
    "best_match_score": 82,
    "average_score": 75,
    "match_quality": "high",
    "summary": "找到2个高度匹配的IT行业高才通B类成功案例，您的条件（浙大硕士+8年经验）与案例主角非常接近，匹配度较高。"
  },
  "timeline_reference": {
    "estimated_preparation": "1-2周",
    "estimated_processing": "4-6周",
    "estimated_total": "5-8周",
    "factors_affecting_timeline": [
      "材料准备的完整度直接影响审批速度",
      "申请高峰期可能延长1-2周",
      "百强大学认证通常不需要额外时间"
    ]
  }
}

场景 2：无高匹配案例时的处理

Coordinator 调用：

{
  "tool": "invoke_case_analyst",
  "input": {
    "userProfile": {
      "age": 45,
      "education": "大专",
      "industry": "传统制造业",
      "yearsOfExperience": 20
    },
    "targetCategory": "QMAS",
    "focus": "overcoming_weakness"
  }
}

内部执行：

Turn 0: search_knowledge({query: "传统制造业 大专 40多岁 优才计划 成功案例", category: "QMAS"})
→ 0 条直接匹配
Turn 1: search_knowledge({query: "大专学历 优才计划 成功案例 经验丰富"})
→ 1 条弱相关案例
→ 如实返回低匹配结果

返回结果：

{
  "matched_cases": [
    {
      "case_title": "制造业高管 优才计划获批",
      "profile_summary": "42岁，本科学历，制造业20年经验，担任工厂副总经理，年薪80万",
      "category": "QMAS",
      "similarity_score": 45,
      "similarities": [
        "同为制造业从业者",
        "工作年限相近（20年）",
        "年龄接近（42 vs 45）"
      ],
      "differences": [
        "案例为本科（用户为大专）",
        "案例有高管头衔",
        "案例年薪较高"
      ],
      "key_success_factors": [
        "20年行业深耕，强调管理经验和行业贡献",
        "持有多项行业专利和资质证书",
        "在申请材料中突出了企业经营业绩"
      ],
      "timeline": {
        "preparation": "约4周（需额外准备补充材料）",
        "application": "1天",
        "approval": "约10周",
        "total": "约15周"
      },
      "source": {
        "title": "制造业人才优才申请经验分享",
        "article_id": "case-qmas-mfg-001"
      }
    }
  ],
  "similarity_analysis": {
    "best_match_score": 45,
    "average_score": 45,
    "match_quality": "low",
    "summary": "知识库中与您条件高度匹配的案例较少。找到1个同行业案例作为参考，但该案例的学历和职位层级与您有差异。建议通过详细评估确认最优路径。"
  },
  "timeline_reference": {
    "estimated_preparation": "4-6周（可能需要额外补充材料）",
    "estimated_processing": "9-12周",
    "estimated_total": "3-4个月",
    "factors_affecting_timeline": [
      "大专学历可能需要额外的经验证明材料",
      "需要突出工作成果和行业贡献弥补学历短板",
      "建议准备推荐信增加申请说服力"
    ]
  }
}