# 03 - Assessment Expert Agent (评估专家) 设计详解

## 1. 核心职责

Assessment Expert 是系统中的**资格评估引擎**。当 Coordinator 收集到足够的用户信息后，调用此 Agent 对用户的移民资格进行全面评估。

核心能力：
1. **全量评估** -- 必须评估所有 6 个移民类别（QMAS/GEP/IANG/TTPS/CIES/TECHTAS），给出逐项打分
2. **精准匹配** -- 根据用户画像（年龄、学历、院校、收入、行业、工作经验）匹配最优类别
3. **TTPS A/B/C 分类判定** -- 严格按照收入/院校/经验年限区分三类
4. **QMAS 综合计分** -- 基于 12 项评分标准给出预估分数
5. **CIES 门槛判断** -- 3000 万港币硬性门槛评估
6. **排序推荐** -- 按适配度排名，给出首选、备选方案
7. **风险提示** -- 指出不足之处和改善建议

> 设计原则：**评估必须有理有据，每一项得分/扣分都要给出原因。** 替代旧架构中 `StrategyEngineService.performAssessment()` 的硬编码逻辑。

## 2. 模型与参数

```typescript
{
  model: 'claude-sonnet-4-20250514',  // 推理能力要求高
  max_tokens: 3000,                    // 评估报告较长
  temperature: 0,                      // 评估必须确定性
  system: [
    {
      type: 'text',
      text: assessmentExpertPrompt,
      cache_control: { type: 'ephemeral' }
    }
  ],
}
```

选用 Sonnet 的理由：
- 需要综合多维度信息进行交叉推理
- 评分逻辑复杂（TTPS 三类判定、QMAS 12 项评分）
- 结果直接影响用户的移民决策，不容有误

## 3. 可用工具 (Available Tools)

Assessment Expert 有 **2 个工具**：

### 3.1 search_knowledge

```typescript
{
  name: 'search_knowledge',
  description: '搜索知识库获取最新的评分标准、资格条件、政策变更信息，确保评估基于最新政策。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '搜索查询，如"QMAS优才计划评分标准详细规则"'
      },
      category: {
        type: 'string',
        enum: ['QMAS', 'GEP', 'IANG', 'TTPS', 'CIES', 'TECHTAS'],
        description: '移民类别代码'
      }
    },
    required: ['query']
  }
}
```

### 3.2 get_user_context

```typescript
{
  name: 'get_user_context',
  description: '获取用户的历史记忆信息，补充 Coordinator 传入参数中可能缺少的用户背景。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '用于检索相关记忆的查询，如"用户的学历工作背景"'
      }
    },
    required: ['query']
  }
}
```

## 4. System Prompt 要点

```
# 身份
你是 iConsulting 的移民资格评估专家。你的任务是根据用户信息，对香港六大移民类别进行全面评估。

# 评估原则
1. 必须评估所有 6 个类别，不能遗漏
2. 每个类别给出 0-100 的适配度评分
3. 评分必须有理有据，列出加分项和减分项
4. 信息不足的字段标注为"未知"，不要猜测
5. 最终按得分排序，给出推荐方案

# TTPS 高才通判定规则
A类：年薪 >= 250万港币（约220万人民币），无学历要求
B类：全球百强大学毕业 + 5年内累积 >= 3年工作经验
C类：全球百强大学毕业 + 5年内累积 < 3年工作经验（年度限额10,000名）
* 百强大学认定：以泰晤士、QS、US News、上海交大四大排名任一为准

# QMAS 优才计划评分维度
- 年龄 (age_score): 18-39岁满分，40-44岁扣分，45-50岁大幅扣分，51+不符合
- 学历 (education_score): 博士 > 硕士/双学位 > 学士 > 大专
- 工作经验 (experience_score): 10年+满分，5-9年中等，2-4年基础
- 语言能力 (language_score): 中英文流利加分，其他语言额外加分
- 年收入 (income_score): 200万+港币满分，100-200万中等，50-100万基础
- 家庭背景 (family_score): 配偶学历/工作，子女情况
- 其他：名企/跨国公司经验、海外工作经验、行业紧缺、持有专业资格等
- 总分达到80+为高度推荐，60-79为推荐，40-59为条件推荐，<40不推荐

# CIES 投资移民门槛
- 最低投资门槛：3000万港币净资产
- 投资于许可的金融资产和非住宅房地产
- 1000万港币额度可获考虑
- 申请前6个月需持有相关资产

# GEP 专才计划要点
- 必须有香港雇主担保
- 年薪达200万港币可属人才清单范畴
- 不限行业，但需证明职位难以在港招聘

# IANG 留学IANG要点
- 需为香港认可院校毕业生
- 毕业后可获 IANG 签证在港求职/工作
- 已扩展至大湾区校区毕业生

# TECHTAS 科技人才要点
- 需有获配额的科技公司雇主
- 从事14个科技领域之一
- 薪酬不低于市场水平

# 输出格式
必须返回 JSON，包含 categories_assessment、overall_recommendation、highlights、concerns、next_steps
```

## 5. 输入/输出格式

### 输入 (Coordinator 传入)

```typescript
interface AssessmentExpertInput {
  /** 用户基本信息（Coordinator 从对话中收集） */
  userInfo: {
    age?: number;
    education?: string;           // 学历：博士/硕士/学士/大专
    university?: string;          // 毕业院校名称
    major?: string;               // 专业
    graduationYear?: number;      // 毕业年份
    totalYearsOfExperience?: number;
    currentJobTitle?: string;
    currentIndustry?: string;
    annualIncome?: number;        // 年收入（人民币）
    incomeCurrency?: string;      // 收入货币，默认 CNY
    hasHongKongEmployer?: boolean;
    hasTechBackground?: boolean;
    investmentAmount?: number;    // 可投资金额（港币）
    languageSkills?: string[];    // 语言能力
    nationality?: string;
    currentLocation?: string;
    additionalInfo?: Record<string, unknown>;
  };
  /** Coordinator 建议优先评估的类别（可选） */
  targetCategories?: Array<'QMAS' | 'GEP' | 'IANG' | 'TTPS' | 'CIES' | 'TECHTAS'>;
}
```

### 输出 (返回给 Coordinator)

```typescript
interface AssessmentExpertOutput {
  /** 各类别评估详情 */
  categories_assessment: Array<{
    category: 'QMAS' | 'GEP' | 'IANG' | 'TTPS' | 'CIES' | 'TECHTAS';
    category_name: string;          // 中文名
    eligibility_score: number;      // 0-100 适配度
    is_eligible: boolean;           // 是否基本符合
    recommendation: 'HIGHLY_RECOMMENDED' | 'RECOMMENDED' | 'CONDITIONALLY_RECOMMENDED' | 'NOT_RECOMMENDED';
    sub_class?: string;             // TTPS 的 A/B/C 类
    scoring_breakdown: Array<{
      dimension: string;            // 评分维度
      score: number;                // 得分
      max_score: number;            // 满分
      reason: string;               // 得分理由
    }>;
    strengths: string[];            // 优势项
    weaknesses: string[];           // 不足项
    improvement_suggestions: string[]; // 改善建议
  }>;

  /** 综合推荐（按优先级排序的类别列表） */
  overall_recommendation: Array<{
    rank: number;
    category: string;
    category_name: string;
    score: number;
    summary: string;                // 一句话推荐理由
  }>;

  /** 用户核心优势 */
  highlights: string[];

  /** 主要顾虑/风险 */
  concerns: string[];

  /** 建议的下一步行动 */
  next_steps: string[];

  /** 信息完整度评估 */
  info_completeness: {
    score: number;                  // 0-100
    missing_fields: string[];       // 缺失的关键信息
    impact: string;                 // 信息缺失对评估的影响说明
  };
}
```

## 6. 触发时机 (When to Trigger)

Coordinator 在以下场景调用 `invoke_assessment_expert`：

| 场景 | 前提条件 | Coordinator 行为 |
|------|----------|-----------------|
| 用户主动要求评估 | "帮我看看我适合哪个" | 直接调用，传入已有 userInfo |
| 信息收集达到阈值 | 已收集 3+ 关键字段 | Coordinator 判断时机合适，主动调用 |
| 用户补充了关键信息 | 用户补充了收入/学历等 | 重新调用获取更新的评估 |
| 转化阶段需要依据 | Coordinator 需要数据支撑推荐 | 调用后综合到回复中 |

**关键信息阈值**：至少需要以下 3 项中的 2 项才值得调用：
- `age` 或 `education`（基础画像）
- `totalYearsOfExperience` 或 `annualIncome`（专业能力）
- `university` 或 `currentIndustry`（细分匹配）

## 7. 内部循环 (Internal Loop)

Assessment Expert 的 agent loop 最多 **3 轮** tool 调用：

```
┌─────────────────────────────────────────────────────┐
│  Assessment Expert Internal Loop (max 3 turns)      │
│                                                      │
│  Turn 0: 分析输入信息完整度                           │
│  ├── 信息充分 → 直接开始评估                          │
│  └── 信息不足 → get_user_context() 补充用户记忆       │
│                                                      │
│  Turn 1: 查询评估标准（可选）                         │
│  ├── search_knowledge({query: "TTPS高才通评分标准"})  │
│  └── 确保用最新的政策标准评估                          │
│                                                      │
│  Turn 2: 补充特定类别信息（如需）                     │
│  ├── search_knowledge({query: 细分查询})              │
│  └── 如百强大学名单确认、人才清单行业确认等            │
│                                                      │
│  Final: 综合所有信息                                  │
│  ├── 对 6 个类别逐一评分                              │
│  ├── 排序推荐                                        │
│  └── 返回结构化评估报告                               │
└─────────────────────────────────────────────────────┘
```

**评估决策树**（内部推理逻辑）：

```
用户信息输入
├── 年薪 >= 250万港币?
│   └── YES → TTPS A类 高度推荐 (90+分)
│
├── 百强大学毕业?
│   ├── YES + 工作经验 >= 3年 → TTPS B类 高度推荐 (85+分)
│   └── YES + 工作经验 < 3年  → TTPS C类 推荐 (70+分, 注意名额限制)
│
├── 可投资金额 >= 3000万港币?
│   └── YES → CIES 高度推荐 (90+分)
│
├── 有香港雇主?
│   ├── YES + 科技行业 → TECHTAS 高度推荐 (85+分)
│   └── YES + 其他行业 → GEP 高度推荐 (85+分)
│
├── 香港院校毕业?
│   └── YES → IANG 高度推荐 (90+分)
│
└── 综合条件评估 → QMAS
    ├── 12项计分
    └── 按总分给出推荐等级
```

## 8. 与其他 Agent 的关系

```
┌──────────────┐     invoke_assessment_expert     ┌──────────────┐
│              │ ──────────────────────────────→   │              │
│  Coordinator │     AssessmentExpertOutput        │ Assessment   │
│              │ ←──────────────────────────────   │ Expert       │
└──────┬───────┘                                   └──────┬───────┘
       │                                                   │
       │                                          ┌────────┴────────┐
       │                                          │                 │
       │                                   get_user_context   search_knowledge
       │                                          │                 │
       │                                          ▼                 ▼
       │                                   ┌────────────┐   ┌────────────┐
       │                                   │ Knowledge   │   │ Knowledge  │
       │                                   │ Service     │   │ Service    │
       │                                   │ (Memory)    │   │ (RAG)      │
       │                                   └────────────┘   └────────────┘
       │
       ├── 评估完成后，Coordinator 可能调用 Strategist 决定如何呈现结果
       ├── 评估结果 → Memory Manager 保存评估摘要到用户记忆
       └── 如果评估结果引发用户异议 → Objection Handler
```

**与旧架构的对应关系**：

| 旧架构 | 新架构 |
|--------|--------|
| `StrategyEngineService.performAssessment()` | Assessment Expert Agent |
| 硬编码的评分逻辑（`if/else` 链） | LLM + 知识库动态评估 |
| 只评估传入的单个类别 | 强制评估全部 6 个类别 |
| 简单的 `suitabilityScore` | 多维度 `scoring_breakdown` |

## 9. 示例场景

### 场景 1：典型 IT 从业者评估

**Coordinator 调用**：

```json
{
  "tool": "invoke_assessment_expert",
  "input": {
    "userInfo": {
      "age": 32,
      "education": "硕士",
      "university": "浙江大学",
      "major": "计算机科学",
      "totalYearsOfExperience": 8,
      "currentJobTitle": "高级软件工程师",
      "currentIndustry": "互联网/科技",
      "annualIncome": 800000,
      "incomeCurrency": "CNY",
      "hasHongKongEmployer": false,
      "hasTechBackground": true,
      "languageSkills": ["中文", "英文"]
    }
  }
}
```

**返回结果**（精简展示）：

```json
{
  "categories_assessment": [
    {
      "category": "TTPS",
      "category_name": "高才通计划",
      "eligibility_score": 88,
      "is_eligible": true,
      "recommendation": "HIGHLY_RECOMMENDED",
      "sub_class": "B",
      "scoring_breakdown": [
        {"dimension": "院校资质", "score": 30, "max_score": 30, "reason": "浙江大学位列全球百强大学名单"},
        {"dimension": "工作经验", "score": 28, "max_score": 30, "reason": "8年经验，满足B类3年+要求，且经验丰富"},
        {"dimension": "毕业时效", "score": 20, "max_score": 20, "reason": "硕士毕业在5年内（需确认具体年份）"},
        {"dimension": "行业匹配", "score": 10, "max_score": 20, "reason": "科技行业为香港重点发展领域"}
      ],
      "strengths": ["百强大学硕士", "8年科技行业经验", "年龄处于黄金期"],
      "weaknesses": ["年薪未达A类250万港币标准"],
      "improvement_suggestions": ["确认浙江大学在当年排名中是否在列"]
    },
    {
      "category": "QMAS",
      "category_name": "优才计划",
      "eligibility_score": 75,
      "is_eligible": true,
      "recommendation": "RECOMMENDED",
      "scoring_breakdown": [
        {"dimension": "年龄", "score": 30, "max_score": 30, "reason": "32岁，年龄加分最高档"},
        {"dimension": "学历", "score": 20, "max_score": 25, "reason": "硕士学历"},
        {"dimension": "工作经验", "score": 15, "max_score": 20, "reason": "8年经验，属于资深水平"},
        {"dimension": "年收入", "score": 5, "max_score": 15, "reason": "80万人民币(约87万港币)，中等水平"},
        {"dimension": "语言能力", "score": 5, "max_score": 10, "reason": "中英双语"}
      ],
      "strengths": ["年龄优势突出", "学历+经验组合好"],
      "weaknesses": ["年收入在优才评分中属于中等"],
      "improvement_suggestions": ["可准备详细的项目成果证明提升竞争力"]
    },
    {
      "category": "GEP",
      "category_name": "专才计划",
      "eligibility_score": 30,
      "is_eligible": false,
      "recommendation": "NOT_RECOMMENDED",
      "scoring_breakdown": [
        {"dimension": "雇主担保", "score": 0, "max_score": 50, "reason": "目前没有香港雇主"}
      ],
      "strengths": ["专业背景符合市场需求"],
      "weaknesses": ["缺少香港雇主担保（硬性条件）"],
      "improvement_suggestions": ["可先在港求职，获得 offer 后通过 GEP 申请"]
    },
    {
      "category": "TECHTAS",
      "category_name": "科技人才入境计划",
      "eligibility_score": 35,
      "is_eligible": false,
      "recommendation": "CONDITIONALLY_RECOMMENDED",
      "scoring_breakdown": [
        {"dimension": "科技背景", "score": 20, "max_score": 30, "reason": "计算机专业+科技行业从业者"},
        {"dimension": "雇主配额", "score": 0, "max_score": 40, "reason": "需要有获配额的香港科技公司雇佣"},
        {"dimension": "领域匹配", "score": 15, "max_score": 30, "reason": "软件工程属于AI/数据分析相关领域"}
      ],
      "strengths": ["科技背景匹配14个指定领域"],
      "weaknesses": ["需有获配额的科技公司雇佣"],
      "improvement_suggestions": ["可关注香港科技园、数码港入驻企业的招聘机会"]
    },
    {
      "category": "CIES",
      "category_name": "投资移民",
      "eligibility_score": 5,
      "is_eligible": false,
      "recommendation": "NOT_RECOMMENDED",
      "scoring_breakdown": [
        {"dimension": "投资金额", "score": 0, "max_score": 80, "reason": "未提供投资金额信息，且最低门槛为3000万港币"}
      ],
      "strengths": [],
      "weaknesses": ["投资移民门槛极高（3000万港币）"],
      "improvement_suggestions": []
    },
    {
      "category": "IANG",
      "category_name": "留学IANG",
      "eligibility_score": 0,
      "is_eligible": false,
      "recommendation": "NOT_RECOMMENDED",
      "scoring_breakdown": [
        {"dimension": "港校毕业", "score": 0, "max_score": 80, "reason": "毕业于浙江大学（内地院校），非香港认可院校毕业生"}
      ],
      "strengths": [],
      "weaknesses": ["非香港院校毕业，不符合IANG基本条件"],
      "improvement_suggestions": ["如有兴趣可考虑先赴港读书再走IANG路径"]
    }
  ],
  "overall_recommendation": [
    {"rank": 1, "category": "TTPS", "category_name": "高才通B类", "score": 88, "summary": "百强大学硕士+8年经验，高度匹配B类条件，审批快、通过率高"},
    {"rank": 2, "category": "QMAS", "category_name": "优才计划", "score": 75, "summary": "综合条件优秀，可作为备选方案同步申请"},
    {"rank": 3, "category": "TECHTAS", "category_name": "科技人才", "score": 35, "summary": "如能获得港企配额雇佣，科技背景匹配度高"}
  ],
  "highlights": [
    "浙江大学属于全球百强，TTPS B类通道畅通",
    "32岁年龄在所有类别中均为加分项",
    "8年科技行业经验，专业背景扎实",
    "中英双语能力"
  ],
  "concerns": [
    "需确认浙江大学在当年具体排名榜单中是否在列",
    "年收入距离TTPS A类标准有较大差距",
    "暂无香港雇主关系，GEP/TECHTAS路径暂不可行"
  ],
  "next_steps": [
    "确认浙江大学硕士毕业的具体年份（TTPS B类要求5年内）",
    "准备学位证书、工作证明等申请材料",
    "建议首选TTPS B类申请，同时准备QMAS作为备选",
    "可预约付费详细评估，获取完整申请方案"
  ],
  "info_completeness": {
    "score": 75,
    "missing_fields": ["graduationYear", "nationality", "investmentAmount"],
    "impact": "毕业年份会影响TTPS时效判定；国籍信息影响签证类型；其他缺失字段影响较小"
  }
}
```