# 02 · 工具清单与官方链接 > **想先搞懂「为什么选这些工具、怎么用」？** 请读专题文档：[06-工具选型与使用说明.md](./06-工具选型与使用说明.md) > 本文侧重：**官方原链接、请求参数、返回格式**等技术细节。 本文列出本项目**实际调用**的所有外部能力：大模型接口、四个业务工具、以及它们对应的**官方文档与原链接**。 --- ## 总览表 | 类别 | 名称 | 是否需 API Key | 代码位置 | |------|------|----------------|----------| | 大模型 | DashScope `qwen-plus` | 是 | `src/lib/dashscope.ts` | | 工具 1 | `get_current_datetime` | 否 | `src/lib/tools.ts` | | 工具 2 | `calculate` | 否 | `src/lib/tools.ts` | | 工具 3 | `get_weather` | 否 | `src/lib/tools.ts` | | 工具 4 | `get_exchange_rate` | 否 | `src/lib/tools.ts` | --- ## 一、大模型：阿里云 DashScope ### 用途 - 理解用户问题 - 决定是否调用工具（Function Calling） - 根据工具结果生成最终回答 ### 本项目使用的接口 | 项目 | 值 | |------|-----| | 模型 | `qwen-plus` | | 调用方式 | OpenAI 兼容模式 Chat Completions | | 开发环境请求路径 | `/api/dashscope/compatible-mode/v1/chat/completions` | | 实际转发目标 | `https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions` | ### 官方链接 | 说明 | 链接 | |------|------| | 百炼控制台（获取 API Key） | https://bailian.console.aliyun.com/ | | DashScope API 参考（中文） | https://help.aliyun.com/zh/model-studio/qwen-api-via-dashscope | | Function Calling 文档（中文） | https://help.aliyun.com/zh/model-studio/qwen-function-calling | | OpenAI 兼容模式说明 | https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope | ### 请求示例（简化） ```http POST /compatible-mode/v1/chat/completions Authorization: Bearer sk-xxxxxxxx Content-Type: application/json { "model": "qwen-plus", "messages": [...], "tools": [...], "tool_choice": "auto" } ``` ### 代理配置 开发时由 Vite 把浏览器请求转发到 DashScope，避免 CORS 问题。见 `vite.config.ts`： ```ts proxy: { '/api/dashscope': { target: 'https://dashscope.aliyuncs.com', changeOrigin: true, rewrite: (path) => path.replace(/^\/api\/dashscope/, ''), }, } ``` --- ## 二、工具 1：`get_current_datetime` ### 用途 回答「现在几点」「今天星期几」等需要**当前时刻**的问题。 ### 数据来源 - **不调用外部 HTTP API** - 使用浏览器 / Node 运行环境的 `Date` 对象 + `toLocaleString` - 按 IANA 时区格式化（默认 `Asia/Shanghai`） ### 参数 | 参数 | 类型 | 说明 | 示例 | |------|------|------|------| | `timezone` | string | IANA 时区名 | `Asia/Shanghai` | ### 参考链接 | 说明 | 链接 | |------|------| | IANA 时区数据库 | https://www.iana.org/time-zones | | MDN：Date.prototype.toLocaleString | https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString | ### 返回示例 ```text 时区 Asia/Shanghai 的当前时间：2026/06/09 星期二 14:30:25 ``` --- ## 三、工具 2：`calculate` ### 用途 精确数学计算，避免大模型心算错误（如 `12345 × 6789`）。 ### 数据来源 - **本地计算**，不访问网络 - 在 `tools.ts` 的 `safeCalculate()` 中执行 - 仅允许数字和 `+ - * / ^ % ( )`，防止注入 ### 参数 | 参数 | 类型 | 说明 | 示例 | |------|------|------|------| | `expression` | string | 数学表达式 | `12345 * 6789` | ### 返回示例 ```text 12345 * 6789 = 83810205 ``` --- ## 四、工具 3：`get_weather` ### 用途 查询指定城市的**实时天气**（温度、湿度、风速、天气状况）。 ### 数据来源 调用 **Open-Meteo** 免费公开 API，分两步： #### 步骤 A：城市 → 经纬度（地理编码） | 项目 | 值 | |------|-----| | 原链接模板 | `https://geocoding-api.open-meteo.com/v1/search?name={城市}&count=1&language=zh&format=json` | | 示例 | https://geocoding-api.open-meteo.com/v1/search?name=深圳&count=1&language=zh&format=json | #### 步骤 B：经纬度 → 实时天气 | 项目 | 值 | |------|-----| | 原链接模板 | `https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}¤t=temperature_2m,weather_code,relative_humidity_2m,wind_speed_10m&timezone=auto` | ### 官方链接 | 说明 | 链接 | |------|------| | Open-Meteo 首页 | https://open-meteo.com/ | | 天气预报 API 文档 | https://open-meteo.com/en/docs | | 地理编码 API 文档 | https://open-meteo.com/en/docs/geocoding-api | ### 参数 | 参数 | 类型 | 说明 | 示例 | |------|------|------|------| | `city` | string | 城市名称 | `深圳` | ### 返回示例 ```text 深圳（中国）当前天气：多云 温度：25.2°C 湿度：78% 风速：12.5 km/h ``` --- ## 五、工具 4：`get_exchange_rate` ### 用途 查询两种货币之间的**实时汇率**并换算金额。 ### 数据来源 调用 **Frankfurter** 免费公开 API（欧洲央行参考汇率）。 | 项目 | 值 | |------|-----| | 原链接模板 | `https://api.frankfurter.app/latest?from={FROM}&to={TO}` | | 示例 | https://api.frankfurter.app/latest?from=USD&to=CNY | ### 官方链接 | 说明 | 链接 | |------|------| | Frankfurter 首页 | https://www.frankfurter.app/ | | API 文档 | https://www.frankfurter.app/docs/ | | GitHub 开源仓库 | https://github.com/lineofflight/frankfurter | ### 参数 | 参数 | 类型 | 必填 | 说明 | 示例 | |------|------|------|------|------| | `from_currency` | string | 是 | 源货币代码 | `USD` | | `to_currency` | string | 是 | 目标货币代码 | `CNY` | | `amount` | string | 否 | 换算金额，默认 1 | `100` | ### 返回示例 ```text 汇率日期：2026-06-08 1 USD = 6.7819 CNY 100 USD = 678.1900 CNY ``` --- ## 六、示例问题与推荐工具对照 | 示例问题 | 预期调用的工具 | |----------|----------------| | 深圳现在的天气怎么样？ | `get_weather` | | 请计算 12345 × 6789 等于多少？ | `calculate` | | 现在北京时间是几点？星期几？ | `get_current_datetime` | | 100 美元现在能换多少人民币？ | `get_exchange_rate` | | 用一句话解释什么是 ReAct？ | 无（纯知识回答） | 预设问题定义在 `src/data/questions.ts`。 --- ## 七、命令行自测脚本 不打开浏览器也可验证工具是否正常： ```bash # 测试四个业务工具（无需 DashScope Key） node scripts/test-tools.mjs # 测试完整 ReAct + 普通模式（需环境变量 DASHSCOPE_API_KEY） node scripts/test-react.mjs ``` --- ## 八、随堂检查 1. 哪个工具需要 DashScope API Key？ 2. `get_weather` 实际访问了哪两个 Open-Meteo 接口？ 3. `calculate` 为什么要在本地算，而不是让模型直接算？
参考答案 1. 只有大模型接口（qwen-plus）需要 Key；四个业务工具中的天气/汇率 API 免费无需 Key。 2. 地理编码 `geocoding-api.open-meteo.com` + 天气预报 `api.open-meteo.com`。 3. 大数运算模型容易出错，本地计算结果确定、可验证。
--- 下一篇：[03-开发思路与项目架构.md](./03-开发思路与项目架构.md)