iconsulting/docs/AGENT_TOOLS.md

# iConsulting Agent 工具文档

本文档详细描述了 iConsulting 移民咨询 Agent 可使用的所有工具。

## 工具概览

| 工具名称 | 类别 | 描述 |
|---------|------|------|
| search_knowledge | 知识与记忆 | 搜索移民知识库 |
| check_off_topic | 知识与记忆 | 检测离题问题 |
| collect_assessment_info | 知识与记忆 | 收集评估信息 |
| generate_payment | 知识与记忆 | 生成支付二维码 |
| save_user_memory | 知识与记忆 | 保存用户记忆 |
| get_user_context | 知识与记忆 | 获取用户上下文 |
| get_current_datetime | 实时查询 | 获取当前时间 |
| web_search | 实时查询 | 网络搜索 |
| get_exchange_rate | 实时查询 | 汇率查询 |
| fetch_immigration_news | 实时查询 | 获取移民新闻 |

---

## 知识与记忆工具

### 1. search_knowledge

搜索香港移民相关知识库，获取最新的政策信息和常见问题解答。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| query | string | ✅ | 搜索查询内容 |
| category | string | ❌ | 移民类别代码 |

**category 可选值**:
- `QMAS` - 优才计划
- `GEP` - 专才计划
- `IANG` - 留学IANG
- `TTPS` - 高才通计划
- `CIES` - 投资移民
- `TECHTAS` - 科技人才入境计划

**返回格式**:

```json
{
  "success": true,
  "content": "检索到的知识内容",
  "sources": [
    {
      "articleId": "xxx",
      "title": "文章标题",
      "similarity": 0.85
    }
  ],
  "userContext": ["用户相关记忆"],
  "relatedExperiences": ["相关系统经验"],
  "message": "找到 3 条相关知识"
}
```

**实现说明**:
- 调用 knowledge-service 的 `/api/v1/knowledge/retrieve` API
- 支持向量相似度搜索
- 自动关联用户记忆和系统经验
- 如 API 不可用，返回 `success: false` 并建议基于内置知识回答

---

### 2. check_off_topic

检查用户的问题是否与香港移民相关，用于判断是否需要拒绝回答。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| question | string | ✅ | 用户的问题 |

**返回格式**:

```json
{
  "isOffTopic": true,
  "confidence": 0.92,
  "suggestion": "这个问题似乎与香港移民无关。作为移民咨询顾问，我专注于香港各类移民政策的咨询。请问您有香港移民相关的问题吗？"
}
```

**实现说明**:
- 调用 knowledge-service 的 `/api/v1/knowledge/check-off-topic` API
- 使用向量相似度判断问题是否属于移民领域
- confidence 表示判断置信度 (0-1)
- 如 API 不可用，默认返回 `isOffTopic: false`

---

### 3. collect_assessment_info

收集用户的个人信息用于移民资格评估。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| category | string | ✅ | 用户感兴趣的移民类别 |
| age | number | ❌ | 用户年龄 |
| education | string | ❌ | 最高学历 |
| university | string | ❌ | 毕业院校 |
| yearsOfExperience | number | ❌ | 工作年限 |
| currentJobTitle | string | ❌ | 当前职位 |
| industry | string | ❌ | 所属行业 |
| annualIncome | number | ❌ | 年收入（人民币） |
| hasHKEmployer | boolean | ❌ | 是否有香港雇主 |

**返回格式**:

```json
{
  "success": true,
  "collectedInfo": {
    "category": "QMAS",
    "age": 35,
    "education": "硕士",
    "yearsOfExperience": 10
  },
  "message": "已记录您的信息。如需完整评估，请选择付费评估服务。",
  "nextStep": "payment"
}
```

**实现说明**:
- 收集的信息自动保存到用户记忆 (importance: 80)
- 用于后续付费评估服务
- 信息以 `FACT` 类型存储

---

### 4. generate_payment

为付费评估服务生成支付二维码。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| serviceType | string | ✅ | 服务类型，目前仅支持 `ASSESSMENT` |
| category | string | ✅ | 移民类别 |
| paymentMethod | string | ✅ | 支付方式 |

**paymentMethod 可选值**:
- `ALIPAY` - 支付宝
- `WECHAT` - 微信支付
- `CREDIT_CARD` - 信用卡

**各类别价格**:

| 类别 | 价格 (CNY) |
|------|-----------|
| QMAS | 99 |
| GEP | 99 |
| IANG | 79 |
| TTPS | 99 |
| CIES | 199 |
| TECHTAS | 99 |

**返回格式**:

```json
{
  "success": true,
  "orderId": "ORD_1706012345678",
  "amount": 99,
  "currency": "CNY",
  "paymentMethod": "ALIPAY",
  "qrCodeUrl": "https://...",
  "expiresAt": "2024-01-23T12:30:00.000Z",
  "message": "请扫描二维码支付 ¥99 完成QMAS类别的移民资格评估服务"
}
```

**实现说明**:
- 用户付费意向自动保存到记忆 (INTENT 类型, importance: 90)
- 二维码有效期 30 分钟
- TODO: 对接实际支付服务

---

### 5. save_user_memory

保存用户的重要信息到长期记忆，以便后续对话中记住用户情况。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| memoryType | string | ✅ | 记忆类型 |
| content | string | ✅ | 要记住的内容 |
| category | string | ❌ | 相关的移民类别 |

**memoryType 可选值**:
- `FACT` - 用户陈述的事实（如：年龄、学历、工作经验）
- `PREFERENCE` - 用户偏好（如：偏好的移民方式）
- `INTENT` - 用户意图（如：计划移民的时间）

**importance 自动设置**:
- FACT: 70
- INTENT: 80
- PREFERENCE: 60

**返回格式**:

```json
{
  "success": true,
  "memoryId": "mem_xxx",
  "message": "已记住您的信息，下次对话时我会记得"
}
```

**实现说明**:
- 调用 knowledge-service 的 `/api/v1/memory/user` API
- 数据存储到 PostgreSQL + Neo4j
- 支持跨会话记忆

---

### 6. get_user_context

获取用户的历史背景信息和之前的对话记忆，帮助提供更个性化的建议。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| query | string | ✅ | 当前问题，用于检索相关记忆 |

**返回格式**:

```json
{
  "success": true,
  "memories": [
    {
      "type": "FACT",
      "content": "用户35岁，硕士学历，10年工作经验",
      "importance": 80
    },
    {
      "type": "INTENT",
      "content": "用户对QMAS优才计划感兴趣",
      "importance": 75
    }
  ],
  "message": "找到 2 条用户背景信息"
}
```

**实现说明**:
- 并行获取相关记忆和重要记忆
- 相关记忆：基于 query 向量搜索 (limit: 3)
- 重要记忆：按 importance 排序 (limit: 5)
- 自动去重合并

---

## 实时查询工具

### 7. get_current_datetime

获取当前的日期和时间，用于回答与时间相关的问题。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| timezone | string | ❌ | 时区 | Asia/Hong_Kong |
| format | string | ❌ | 返回格式 | full |

**format 可选值**:
- `full` - 完整日期时间
- `date` - 仅日期
- `time` - 仅时间

**返回格式**:

```json
{
  "success": true,
  "datetime": "2024年1月23日星期二 14:30:00",
  "timezone": "Asia/Hong_Kong",
  "timestamp": "2024-01-23T06:30:00.000Z",
  "message": "当前Asia/Hong_Kong时间: 2024年1月23日星期二 14:30:00"
}
```

**实现说明**:
- 使用 JavaScript Intl.DateTimeFormat
- 支持任意 IANA 时区
- 默认使用香港时区

---

### 8. web_search

搜索互联网获取最新信息，用于查询移民政策变更、新闻动态等实时内容。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| query | string | ✅ | 搜索关键词 | - |
| site | string | ❌ | 限定搜索网站 | - |
| language | string | ❌ | 搜索语言 | zh-CN |

**language 可选值**:
- `zh-CN` - 简体中文
- `zh-TW` - 繁体中文
- `en` - 英文

**常用 site 值**:
- `immd.gov.hk` - 香港入境事务处
- `talentservicewindow.gov.hk` - 香港人才服务窗口

**返回格式**:

成功时:
```json
{
  "success": true,
  "query": "香港优才计划最新政策",
  "results": [
    {
      "title": "优秀人才入境计划 - 入境事务处",
      "url": "https://www.immd.gov.hk/...",
      "snippet": "优秀人才入境计划是一项设有配额的移民吸纳计划..."
    }
  ],
  "resultCount": 5,
  "message": "找到 5 条相关结果"
}
```

降级时:
```json
{
  "success": false,
  "query": "香港优才计划最新政策",
  "results": [],
  "message": "搜索服务暂时不可用。建议您访问以下官方网站获取最新信息：",
  "suggestedSites": [
    { "name": "香港入境事务处", "url": "https://www.immd.gov.hk" },
    { "name": "香港人才服务窗口", "url": "https://www.talentservicewindow.gov.hk" },
    { "name": "投资推广署", "url": "https://www.investhk.gov.hk" }
  ]
}
```

**环境变量**:
- `GOOGLE_SEARCH_API_KEY` - Google Custom Search API Key
- `GOOGLE_CSE_ID` - Google Custom Search Engine ID

**实现说明**:
- 优先使用 Google Custom Search API
- 如未配置 API Key，返回官方网站建议
- 每次请求返回最多 5 条结果

---

### 9. get_exchange_rate

查询实时货币汇率，用于投资移民金额换算等场景。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| from | string | ✅ | 源货币代码 |
| to | string | ✅ | 目标货币代码 |
| amount | number | ❌ | 要转换的金额 |

**常用货币代码**:
- `CNY` - 人民币
- `HKD` - 港币
- `USD` - 美元

**返回格式**:

实时汇率:
```json
{
  "success": true,
  "from": "CNY",
  "to": "HKD",
  "rate": 1.0823,
  "amount": 3000000,
  "convertedAmount": 3246900,
  "lastUpdate": "2024-01-23T00:00:00Z",
  "message": "3000000 CNY = 3246900.00 HKD (汇率: 1.0823)"
}
```

降级汇率:
```json
{
  "success": true,
  "from": "CNY",
  "to": "HKD",
  "rate": 1.08,
  "amount": 3000000,
  "convertedAmount": 3240000,
  "isEstimate": true,
  "message": "参考汇率 (可能有偏差): 1 CNY ≈ 1.08 HKD，3000000 CNY ≈ 3240000.00 HKD"
}
```

**环境变量**:
- `EXCHANGE_RATE_API_KEY` - Exchange Rate API Key (可选)

**降级汇率表**:

| From | To | Rate |
|------|-----|------|
| CNY | HKD | 1.08 |
| CNY | USD | 0.14 |
| USD | HKD | 7.78 |
| USD | CNY | 7.24 |
| HKD | CNY | 0.93 |
| HKD | USD | 0.13 |

**实现说明**:
- 优先使用 Exchange Rate API (v6 或 v4)
- v4 API 免费，无需 API Key
- 如 API 不可用，使用内置降级汇率
- 降级汇率会标记 `isEstimate: true`

---

### 10. fetch_immigration_news

获取香港移民相关的最新新闻和政策公告。

**输入参数**:

| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| category | string | ❌ | 移民类别 | ALL |
| limit | number | ❌ | 返回条数 | 5 |

**category 可选值**:
- `QMAS` - 优才计划
- `GEP` - 专才计划
- `IANG` - 留学IANG
- `TTPS` - 高才通计划
- `CIES` - 投资移民
- `TECHTAS` - 科技人才入境计划
- `ALL` - 所有类别

**返回格式**:

动态新闻:
```json
{
  "success": true,
  "category": "QMAS",
  "news": [...],
  "message": "获取到 3 条QMAS相关移民新闻"
}
```

静态参考:
```json
{
  "success": true,
  "category": "QMAS",
  "news": [
    {
      "title": "优才计划持续接受申请",
      "summary": "香港优才计划无配额限制，全年接受申请。申请人需符合基本资格要求，并通过计分制评核。",
      "date": "2024-01",
      "source": "香港入境事务处"
    }
  ],
  "isStatic": true,
  "message": "以下是QMAS类别的参考信息。如需最新资讯，请访问香港入境事务处官网。",
  "officialSources": [
    { "name": "香港入境事务处", "url": "https://www.immd.gov.hk/hks/services/visas/admission_talents.html" },
    { "name": "香港人才服务窗口", "url": "https://www.talentservicewindow.gov.hk" }
  ]
}
```

**实现说明**:
- 优先从 knowledge-service 获取新闻
- 调用 `/api/v1/news/immigration` API
- 如服务不可用，返回静态参考信息
- 静态信息会标记 `isStatic: true`

---

## 工具调用流程

```
用户消息 → ClaudeAgentService.sendMessage()
    ↓
构建系统提示词 (含工具列表)
    ↓
调用 Claude API (带 tools 参数)
    ↓
Claude 决定是否调用工具
    ↓
如需调用 → ImmigrationToolsService.executeTool()
    ↓
工具执行返回结果
    ↓
结果注入对话上下文
    ↓
Claude 继续生成回复
    ↓
循环直到无需更多工具调用
    ↓
返回最终回复给用户
```

---

## 配置环境变量

```env
# Knowledge Service
KNOWLEDGE_SERVICE_URL=http://knowledge-service:3003

# Google Search (可选)
GOOGLE_SEARCH_API_KEY=your_api_key
GOOGLE_CSE_ID=your_cse_id

# Exchange Rate (可选)
EXCHANGE_RATE_API_KEY=your_api_key
```

---

## 相关文件

- [immigration-tools.service.ts](../packages/services/conversation-service/src/infrastructure/claude/tools/immigration-tools.service.ts) - 工具定义与实现
- [system-prompt.ts](../packages/services/conversation-service/src/infrastructure/claude/prompts/system-prompt.ts) - 系统提示词
- [claude-agent.service.ts](../packages/services/conversation-service/src/infrastructure/claude/claude-agent.service.ts) - Agent 核心服务
- [knowledge-client.service.ts](../packages/services/conversation-service/src/infrastructure/knowledge/knowledge-client.service.ts) - Knowledge Service 客户端

---

*文档更新时间: 2026-01-23*