# 07 — API 密钥获取与配置指南

> ⭐ **使用本教程前，请先支持一下这个开源项目：**
>
> 1. **Star ⭐** — 点击 GitHub 仓库右上角 ⭐ Star，收藏本项目，方便以后找到
> 2. **Fork 🍴** — 点击 Fork，把项目复制到你的 GitHub 账号下，可以自由修改
> 3. **Download 📥** — 点击绿色 **Code** 按钮 → **Download ZIP**，下载到本地开始复刻
>
> 📸 **操作示意图：**
>
> ![Star-Fork-Download](../Picture/demo.jpg)

---

MindPaw 使用了两个云端 API 和一个离线语音模块，都需要申请或配置才能使用。本文一步步教你完成所有配置。

---

## 目录

- [1. 心知天气 API（天气查询）](#1-心知天气-api天气查询)
- [2. 火山引擎方舟 API（AI 对话）](#2-火山引擎方舟-aiai-对话)
- [3. HLK-V20 语音模块配置](#3-hlk-v20-语音模块配置)
- [4. 在机器狗上配置](#4-在机器狗上配置)

---

## 1. 心知天气 API（天气查询）

### 1.1 注册账号

1. 打开 [心知天气官网](https://www.seniverse.com/)
2. 点击右上角 **注册**
3. 可用邮箱或 GitHub 账号注册
4. 注册后登录

### 1.2 获取 API Key

1. 登录后进入控制台，点击左侧 **产品管理**
2. 找到 **天气数据 API**，点击 **免费版**
3. 免费版每天可调用 1000 次，对个人机器人完全够用
4. 创建成功后，你会在页面上看到类似这样的密钥：

```
你的API密钥: S_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

5. 点击 **复制**，保存到记事本备用

### 1.3 在代码中的位置

获取的 API Key 不需要写死在代码里，通过网页配置即可（见第四节）。

```cpp
// main.cpp 第 65 行 — API Key 默认为空，通过网页填写
String weatherapi = ""; // 启动后通过网页填写
```

---

## 2. 火山引擎方舟 API（AI 对话）

MindPaw 通过火山引擎的方舟平台调用**豆包大模型**，接口完全兼容 OpenAI 格式。

### 2.1 注册账号

1. 访问 [火山引擎官网](https://www.volcengine.com/)
2. 点击右上角 **注册**（支持手机号 / 邮箱）
3. 注册后完成实名认证（AI 服务需要）
4. 登录控制台

### 2.2 创建推理接入点

1. 在控制台顶部搜索框输入 **方舟**，进入 **方舟平台**
2. 左侧菜单选择 **推理接入点**
3. 点击 **创建接入点**，填写：

| 字段 | 填写内容 |
|------|---------|
| **名称** | 随意，如 `MindPaw` |
| **模型选择** | 推荐 **Doubao-pro-32k**（性价比高）或 **Doubao-lite-32k**（更快更便宜） |
| **计费方式** | 按量计费（新用户有免费额度） |

4. 创建完成后，你会得到一个 **接入点 ID（Endpoint）**，格式如：

```
ep-2025xxxx-xxxxx-xxxxx-xxxx
```

5. **复制这个 ID**，保存备用

### 2.3 获取 API Key

1. 在方舟平台左侧菜单，点击 **API Key 管理**
2. 点击 **创建 API Key**
3. 填写名称后创建，你会得到：

```
AK:  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

4. **点击显示完整 Key** 并复制（关闭页面后不再显示完整内容）
5. 将 API Key 和 Endpoint ID 保存到记事本

### 2.4 （可选）充值

新用户通常有 **几十万 Token 免费额度**，够用很久。如果后续需要充值：

1. 方舟平台 → **费用中心**
2. 充值 ¥10 可以用非常久（Doubao-pro 约 0.8元/百万token）

### 2.5 在代码中的位置

```cpp
// doubao_config.h 第 10 行 — API 端点（已填好无需修改）
#define DOUBAO_BASE_URL   "https://ark.cn-beijing.volces.com"
#define DOUBAO_API_PATH   "/api/v3/chat/completions"
```

API Key 和 Endpoint ID 通过网页配置，不写死在代码里。

---

## 3. HLK-V20 语音模块配置

HLK-V20（也叫 SU-03T）是离线语音识别模块，无需联网即可识别语音命令。

### 3.1 下载配置工具

1. 百度搜索 **"SU-03T 配置工具"** 或 **"HLK-V20 上位机"**
2. 也可以在海凌科官方淘宝店页面找到下载链接
3. 工具是 Windows 软件，约 200MB

### 3.2 连接模块到电脑

使用 **USB-TTL 模块** 连接：

| USB-TTL | HLK-V20 |
|---------|---------|
| TX | RX |
| RX | TX |
| GND | GND |
| 3.3V | VCC |

**注意：**
- 不要接 5V，HLK-V20 是 3.3V 供电
- RX/TX 要**交叉连接**（TX→RX, RX→TX）

### 3.3 配置语音命令

打开配置工具，按以下步骤操作：

**第一步：设置基本参数**

| 参数 | 推荐值 |
|------|--------|
| **波特率** | 9600 |
| **唤醒方式** | 按键触发 / 唤醒词触发（推荐唤醒词） |
| **唤醒词** | 如 "小狗小狗"（3-5 个字） |

**第二步：添加命令**

点击 **添加命令**，每一条命令包含：
- **识别词**：用户说的内容（如 "前进"）
- **输出**：模块识别后通过串口发送的字符串（如 `CMD1`）

按以下表格创建 22 条命令：

| # | 识别词 | 输出 | 作用 |
|---|--------|------|------|
| 1 | 前进 | `CMD1` | 前进 |
| 2 | 后退 | `CMD2` | 后退 |
| 3 | 左转 | `CMD3` | 左转 |
| 4 | 右转 | `CMD4` | 右转 |
| 5 | 停下 | `CMD5` | 停止 |
| 6 | 坐下 | `CMD6` | 坐下 |
| 7 | 趴下 | `CMD7` | 趴下 |
| 8 | 开心 | `CMD8` | 开心表情 |
| 9 | 生气 | `CMD9` | 生气表情 |
| 10 | 难受 | `CMD10` | 难过表情 |
| 11 | 好奇 | `CMD11` | 好奇表情 |
| 12 | 喜欢 | `CMD12` | 喜爱表情 |
| 13 | 睡觉 | `CMD13` | 睡觉姿势 |
| 14 | 自由模式 | `CMD14` | 开关自由模式 |
| 15 | 抬左手 | `CMD15` | 抬左手 |
| 16 | 抬右手 | `CMD16` | 抬右手 |
| 17 | 现在时间 | `CMD17` | 显示时间 |
| 18 | 今天天气 | `CMD18` | 显示天气 |
| 19 | 显示标志 | `CMD19` | 显示 Logo |
| 20 | 你好 | `CMD20` | 打招呼 |
| 21 | 再见 | `CMD21` | 告别 |
| 22 | （不配置） | `CMD22` | 保留 |

**第三步：烧录到模块**

1. 点击 **烧录** 或 **生成固件并下载**
2. 等待烧录完成（约 10-30 秒）
3. 烧录完成后断开 USB-TTL

### 3.4 验证

烧录后，用 USB-TTL 连接模块：
1. 打开串口助手（波特率 9600）
2. 对着模块说话，串口应输出对应的 `CMD1`、`CMD2`... 等字符串
3. 如果没反应，检查麦克风是否正常、识别词是否清晰

---

## 4. 在机器狗上配置

### 4.1 连接 WiFi

1. 给机器狗上电
2. 手机/电脑搜索 WiFi 热点 **MindPaw**
3. 输入密码 `mindpaw1234`
4. 连接成功后，浏览器打开 `http://192.168.4.1`

### 4.2 配置天气 API

1. 在控制台页面，点击 **在线功能 → 设置**
2. 找到 **天气 API 密钥** 输入框
3. 粘贴从心知天气复制的 API Key
4. 输入城市名（如 `Shanghai`、`Beijing`）
5. 点击 **保存并连接**
6. 返回 **在线功能** 页面，点击 **天气** 应能正常显示

### 4.3 配置 AI Agent

1. 浏览器打开 `http://192.168.4.1/aiconfig.html`
2. 在 **API Key** 输入框粘贴火山引擎的 API Key
3. 在 **推理端点 ID** 输入框粘贴 Endpoint ID
4. 点击 **保存配置**
5. 提示保存成功后，打开 `http://192.168.4.1/aichat.html`
6. 输入消息测试，机器狗应通过动作+表情+旋律回复

### 4.4 验证 HLK-V20

HLK-V20 接好后不需要额外配置，上电即用：

1. 对着模块说唤醒词（如 "小狗小狗"）
2. 听到模块发出提示音后，说出命令（如 "前进"）
3. 观察机器狗是否执行相应动作
4. 如果没反应，检查接线（见 [05_Assembly_Guide.md](05_Assembly_Guide.md)）

---

## 常见问题

### 天气 API 显示 "Need NET"

- 机器狗连接 WiFi 了吗？（OLED 显示的是 AP 模式，需要连接外部 WiFi）
- 在 **设置页面** 重新填写 WiFi 信息并保存

### AI 聊天提示 "AI未配置"

- 检查 aiconfig.html 是否保存成功
- 检查 API Key 和 Endpoint ID 是否复制完整（没有多余空格）
- 火山引擎账号是否完成了实名认证？

### HLK-V20 没反应

- 接线正确吗？RX/TX 是否交叉？
- 波特率是否设为 9600？
- 模块里的固件烧录成功了吗？（用 USB-TTL 单独测试输出）
- 对着模块说话时距离不要太远（推荐 0.5-1 米）

### 语音命令和实际执行不一致

- HLK-V20 的识别词和输出字符串对应关系是否正确？
- 检查 `hlkv20.cpp` 中的 `DEFAULT_MAPPING` 表是否与你的输出字符串一致

### 密钥泄露了怎么办？

- **心知天气**：登录控制台 → 产品管理 → 重置密钥
- **火山引擎**：登录方舟平台 → API Key 管理 → 删除旧 Key → 创建新 Key
- **WiFi 密码**：修改 `main.cpp` 中的 `password`，重新编译烧录