docs: add comprehensive agent tools documentation

Document all 10 tools available to the immigration consulting agent: - 6 knowledge & memory tools (search, off-topic check, assessment, payment, memory, context) - 4 real-time tools (datetime, web search, exchange rate, news) Includes input parameters, return formats, implementation details, and configuration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-23 00:49:10 -08:00 · 2026-01-23 00:49:10 -08:00 · 36ce824db8
parent 4c125f3276
commit 36ce824db8
1 changed files with 552 additions and 0 deletions
--- a/docs/AGENT_TOOLS.md
+++ b/docs/AGENT_TOOLS.md
@ -0,0 +1,552 @@
+# 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*