iconsulting/docs/architecture/02-policy-expert-agent.md

02 - Policy Expert Agent (政策专家) 设计详解

1. 核心职责

Policy Expert 是系统中的移民政策百科全书。当用户提出与政策、条件、流程、时间线相关的问题时，Coordinator 会调用此 Agent 获取准确的政策信息。

核心能力：

1. 精准检索政策 -- 通过 knowledge-service RAG 搜索最相关的政策条文
2. 结构化解读 -- 将复杂政策拆解为用户能理解的要点（条件、流程、时间、费用）
3. 引用出处 -- 每条关键信息附带来源（文章标题、官方条文编号）
4. 类别对比 -- 当用户问及多个类别时，能并列对比差异
5. 时效性标注 -- 标注政策的生效日期与是否有变更风险

设计原则：宁可多查一次知识库，也不要凭 LLM 记忆编造政策细节。

2. 模型与参数

{
  model: 'claude-sonnet-4-20250514',  // 准确性要求高，不能用 Haiku
  max_tokens: 2048,
  temperature: 0,                      // 政策回答必须确定性，不需要创造力
  system: [
    {
      type: 'text',
      text: policyExpertPrompt,
      cache_control: { type: 'ephemeral' }
    }
  ],
}

选用 Sonnet 的理由：

• 政策解读需要高准确性，hallucination 会导致用户做出错误决策
• 需要综合多条 RAG 结果进行推理整合
• Haiku 在长文本归纳和交叉引用方面表现不足

3. 可用工具 (Available Tools)

Policy Expert 只有 1 个工具，最大限度减少复杂度：

3.1 search_knowledge

{
  name: 'search_knowledge',
  description: '搜索香港移民知识库，获取政策条文、申请条件、流程指南、费用标准等信息。每次搜索尽量用精确的关键词。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '搜索查询内容，建议包含具体类别名称和关键词，如"TTPS高才通B类申请条件"'
      },
      category: {
        type: 'string',
        enum: ['QMAS', 'GEP', 'IANG', 'TTPS', 'CIES', 'TECHTAS'],
        description: '移民类别代码，用于缩小搜索范围'
      }
    },
    required: ['query']
  }
}

底层实现：调用 knowledge-service 的 POST /api/v1/knowledge/retrieve

// HTTP 请求
const response = await axios.post('http://knowledge-service:3003/api/v1/knowledge/retrieve', {
  query: input.query,
  category: input.category,
  userId: context.userId,
  limit: 5,
  similarityThreshold: 0.7,
});

4. System Prompt 要点

# 身份
你是 iConsulting 的政策研究专家，专注于香港六大移民类别的政策解读。

# 核心原则
1. 一切回答必须基于知识库检索结果，不要凭记忆回答
2. 如果知识库没有相关信息，明确说明"未找到相关政策信息"
3. 每个关键论点必须标注来源
4. 区分"官方政策"和"实务经验"
5. 政策有变更风险的，加注提醒

# 搜索策略
- 第一次搜索：用用户原始问题的关键词
- 如果结果不够精准：用更具体的类别+条件进行二次搜索
- 如果涉及多个类别：分别搜索每个类别
- 最多进行 3 轮搜索

# 六大移民类别代码
- QMAS: 优才计划 (Quality Migrant Admission Scheme)
- GEP: 专才计划 (General Employment Policy)
- IANG: 留学IANG (Immigration Arrangements for Non-local Graduates)
- TTPS: 高才通计划 (Top Talent Pass Scheme)
- CIES: 投资移民 (Capital Investment Entrant Scheme)
- TECHTAS: 科技人才入境计划 (Technology Talent Admission Scheme)

# 输出格式
必须返回结构化 JSON，包含 policy_summary、requirements、process_steps、important_notes、sources

5. 输入/输出格式

输入 (Coordinator 传入)

interface PolicyExpertInput {
  /** 用户的政策相关问题 */
  query: string;
  /** 指定的移民类别（可选，Coordinator 可能已判断出类别） */
  category?: 'QMAS' | 'GEP' | 'IANG' | 'TTPS' | 'CIES' | 'TECHTAS';
}

输出 (返回给 Coordinator)

interface PolicyExpertOutput {
  /** 政策摘要：一段话概括核心结论 */
  policy_summary: string;

  /** 具体条件/要求列表 */
  requirements: Array<{
    item: string;        // 条件项，如"年龄要求"
    detail: string;      // 具体说明
    mandatory: boolean;  // 是否为必要条件
  }>;

  /** 申请流程步骤 */
  process_steps: Array<{
    step: number;
    title: string;
    description: string;
    estimated_time?: string;  // 预计耗时
  }>;

  /** 重要提醒 */
  important_notes: string[];

  /** 引用来源 */
  sources: Array<{
    title: string;
    article_id?: string;
    relevance: number;  // 0-1
  }>;

  /** 政策有效时间（如果知识库中有标注） */
  effective_date?: string;

  /** 是否有近期变更风险 */
  change_risk?: 'low' | 'medium' | 'high';
}

6. 触发时机 (When to Trigger)

Coordinator 在以下场景调用 invoke_policy_expert：

场景	示例用户消息	Coordinator 传入的参数
询问某类别条件	"优才计划需要什么条件？"	{query: "优才计划申请条件", category: "QMAS"}
询问申请流程	"高才通怎么申请？"	{query: "高才通申请流程步骤", category: "TTPS"}
询问费用	"投资移民要多少钱？"	{query: "投资移民资金门槛", category: "CIES"}
询问时间线	"IANG多久能批下来？"	{query: "IANG审批时间", category: "IANG"}
类别对比	"优才和高才通有什么区别？"	{query: "优才计划vs高才通区别对比"}
政策变更	"最近移民政策有变化吗？"	{query: "香港移民政策最新变化"}
续签规则	"签证到期后怎么续签？"	{query: "签证续签条件流程", category: "TTPS"}

不应触发的场景：

• 用户只是闲聊（"你好"）
• 用户在讨论付费服务
• 用户的问题是关于个人资格评估（应该调 Assessment Expert）

7. 内部循环 (Internal Loop)

Policy Expert 有自己独立的 agent loop，最多 3 轮 tool 调用：

┌─────────────────────────────────────────────────┐
│  Policy Expert Internal Loop (max 3 turns)      │
│                                                  │
│  Turn 1: 初始搜索                                │
│  ├── search_knowledge({query: 用户原问题})       │
│  ├── 分析结果：信息是否足够？                      │
│  │   ├── YES → 生成结构化输出，结束               │
│  │   └── NO  → 继续 Turn 2                       │
│  │                                               │
│  Turn 2: 补充搜索                                │
│  ├── search_knowledge({query: 更精确的关键词})    │
│  ├── 综合 Turn 1 + Turn 2 结果                   │
│  │   ├── 足够 → 生成输出，结束                    │
│  │   └── 不够 → 继续 Turn 3                      │
│  │                                               │
│  Turn 3: 最终搜索                                │
│  ├── search_knowledge({query: 不同角度的查询})    │
│  ├── 综合所有结果，生成最终输出                    │
│  └── 无论是否完整，必须结束并返回                  │
└─────────────────────────────────────────────────┘

内部循环伪代码：

async function policyExpertLoop(input: PolicyExpertInput): Promise<PolicyExpertOutput> {
  const messages: Message[] = [
    { role: 'user', content: JSON.stringify(input) }
  ];

  for (let turn = 0; turn < 3; turn++) {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      system: policyExpertSystemPrompt,
      messages,
      tools: [searchKnowledgeTool],
      max_tokens: 2048,
      temperature: 0,
    });

    // 收集响应
    const toolUses = response.content.filter(b => b.type === 'tool_use');

    if (toolUses.length === 0) {
      // LLM 认为信息足够，提取结构化输出
      return extractPolicyOutput(response);
    }

    // 执行 search_knowledge
    const results = await executeTools(toolUses);

    // 将结果喂回
    messages.push({ role: 'assistant', content: response.content });
    messages.push({
      role: 'user',
      content: results.map(r => ({
        type: 'tool_result',
        tool_use_id: r.id,
        content: r.output,
      }))
    });
  }

  // 达到最大轮次，强制生成输出
  return forceGenerateOutput(messages);
}

8. 与其他 Agent 的关系

┌──────────────┐        invoke_policy_expert         ┌──────────────┐
│              │ ──────────────────────────────────→  │              │
│  Coordinator │         PolicyExpertOutput           │ Policy       │
│              │ ←──────────────────────────────────  │ Expert       │
└──────────────┘                                      └──────┬───────┘
       │                                                      │
       │  Coordinator 综合政策信息后                             │ search_knowledge
       │  回复用户                                              ↓
       │                                              ┌──────────────┐
       │                                              │ Knowledge    │
       │                                              │ Service      │
       │                                              │ (Port 3003)  │
       │                                              └──────────────┘
       │
       ├── 可能同时调用 Assessment Expert（用户问完条件想知道自己是否符合）
       ├── 可能同时调用 Case Analyst（用政策+案例一起说服用户）
       └── Policy Expert 的结果可能触发 Coordinator 后续调用 Objection Handler

关键关系：

• Coordinator → Policy Expert：单向调用，Coordinator 传入问题，Policy Expert 返回结构化政策信息
• Policy Expert → Knowledge Service：通过 HTTP API 检索知识库
• Policy Expert 不直接与其他 Agent 交互：所有 Agent 间通信都通过 Coordinator 中转
• 与 Assessment Expert 互补：Policy Expert 回答"政策是什么"，Assessment Expert 回答"你是否符合"

9. 示例场景

场景 1：询问高才通B类条件

Coordinator 调用：

{
  "tool": "invoke_policy_expert",
  "input": {
    "query": "高才通B类的申请条件是什么？需要什么学历和工作经验？",
    "category": "TTPS"
  }
}

Policy Expert 内部执行：

Turn 1: search_knowledge({query: "高才通B类申请条件学历工作经验", category: "TTPS"})
  → 知识库返回 3 条结果，包含 TTPS B类详细条件
  → 信息充足，直接生成输出

返回结果：

{
  "policy_summary": "高才通计划B类面向全球百强大学毕业生，要求在紧接申请日期前五年内获得全球百强大学颁授的学士或以上学位，且在紧接申请日期前五年内累积至少三年的工作经验。不设名额限制。",
  "requirements": [
    {
      "item": "学历要求",
      "detail": "持有全球百强大学颁授的学士学位或以上学历（以泰晤士高等教育世界大学排名、QS世界大学排名、US News全球最佳大学排名、上海交通大学世界大学学术排名中任一排名为准）",
      "mandatory": true
    },
    {
      "item": "毕业时间",
      "detail": "在紧接申请日期前五年内取得学位",
      "mandatory": true
    },
    {
      "item": "工作经验",
      "detail": "在紧接申请日期前五年内累积至少三年工作经验",
      "mandatory": true
    },
    {
      "item": "良好品格",
      "detail": "无犯罪记录、无不良入境记录",
      "mandatory": true
    }
  ],
  "process_steps": [
    {
      "step": 1,
      "title": "准备材料",
      "description": "学位证书、成绩单、工作证明（雇主推荐信/劳动合同/社保记录）、身份证明文件",
      "estimated_time": "1-2周"
    },
    {
      "step": 2,
      "title": "在线申请",
      "description": "通过入境事务处网站提交电子申请表格",
      "estimated_time": "1天"
    },
    {
      "step": 3,
      "title": "审批等待",
      "description": "入境事务处审核申请",
      "estimated_time": "4-6周"
    },
    {
      "step": 4,
      "title": "获批签注",
      "description": "获批后前往中国签证申请服务中心办理签注手续",
      "estimated_time": "1-2周"
    }
  ],
  "important_notes": [
    "全球百强大学名单每年更新，以申请时公布的名单为准",
    "工作经验不限行业和地域，但需提供有效证明文件",
    "B类无年度名额限制，获批后可获2年签证",
    "首次入境后无需立即找到工作，可在港自由求职"
  ],
  "sources": [
    {
      "title": "高端人才通行证计划申请指南 - 入境事务处",
      "article_id": "ttps-guide-001",
      "relevance": 0.95
    },
    {
      "title": "全球百强大学综合名单（2024/25年度）",
      "article_id": "ttps-univ-list-001",
      "relevance": 0.88
    }
  ],
  "effective_date": "2022-12-28起实施",
  "change_risk": "low"
}

场景 2：多类别对比查询

Coordinator 调用：

{
  "tool": "invoke_policy_expert",
  "input": {
    "query": "优才计划和高才通有什么区别？哪个更容易？"
  }
}

Policy Expert 内部执行：

Turn 1: search_knowledge({query: "优才计划vs高才通区别对比"})
  → 返回 2 条结果，但对比信息不够全面
Turn 2: search_knowledge({query: "QMAS优才计划申请条件评分标准", category: "QMAS"})
  → 补充优才计划详情
Turn 3: search_knowledge({query: "TTPS高才通三类ABC分类", category: "TTPS"})
  → 补充高才通详情
  → 综合三轮结果生成对比输出

返回结果：

{
  "policy_summary": "优才计划(QMAS)采用综合计分制，对年龄、学历、工作经验、语言能力等12项指标打分，择优录取；高才通(TTPS)条件更明确，分ABC三类，满足条件即可获批。总体而言，如果你是百强大学毕业或高薪人士，高才通更直接快速；如果你条件综合但不满足高才通硬性标准，优才计划是更灵活的选择。",
  "requirements": [
    {
      "item": "优才计划 - 计分制",
      "detail": "12项评分标准（年龄、学历、工作年限、年收入、语言能力等），满足6项为基本门槛，总分越高越有竞争力",
      "mandatory": true
    },
    {
      "item": "高才通A类",
      "detail": "年薪达250万港币（约220万人民币），无学历要求",
      "mandatory": true
    },
    {
      "item": "高才通B类",
      "detail": "全球百强大学毕业 + 5年内有3年以上工作经验",
      "mandatory": true
    },
    {
      "item": "高才通C类",
      "detail": "全球百强大学毕业 + 5年内少于3年工作经验，年度限额10,000名",
      "mandatory": true
    }
  ],
  "process_steps": [],
  "important_notes": [
    "审批速度：高才通 4-6 周，优才计划 9-12 个月",
    "高才通条件明确、审批快、通过率高；优才计划竞争性强、周期长但灵活性更大",
    "两者可同时申请，不冲突",
    "优才获批后需有在港计划，高才通可自由求职"
  ],
  "sources": [
    {
      "title": "香港六大人才引进计划对比分析",
      "article_id": "compare-001",
      "relevance": 0.92
    }
  ]
}