diff --git a/docs/AGENT_TOOLS.md b/docs/AGENT_TOOLS.md new file mode 100644 index 0000000..2e04379 --- /dev/null +++ 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*