# 语音控制增强 - 安装指南

> 版本：V1.0  
> 创建时间：2026-03-08 09:15  
> 预计耗时：10 分钟

---

## 🎯 功能简介

**语音控制增强 Skill** 让你可以通过酷狗 K8 耳机语音输入，执行各种复杂任务：

- ✅ "生成周报" → 自动调用周报 Skill
- ✅ "当前优先级" → 显示优先级提醒
- ✅ "保存会话" → 归档豆包会话
- ✅ "专家点评" → 生成 HTML 专家点评
- ✅ 20+ 预置语音命令

**核心价值：** 解放双手，语音执行复杂任务，效率提升 3-5 倍！

---

## 📦 安装内容

本次安装包含：

1. ✅ **Skill 文件** - `skills/voice-control-enhanced/SKILL.md`
2. ✅ **原子动作** - `atomic-actions/04-analysis/ATOM-VOICE-001-语音命令识别.md`
3. ✅ **命令词库** - `voice-commands.json`（20 个预置命令）
4. ✅ **配置脚本** - `setup-voice-control.ps1`
5. ✅ **测试脚本** - `test-voice-command.ps1`

---

## 🔧 安装步骤

### 步骤 1：检查硬件

**需要设备：**
- ✅ 酷狗 K8 蓝牙耳机（已配对）
- ✅ 麦克风权限已开启
- ✅ 网络连接正常

**检查命令：**
```powershell
# 检查蓝牙设备
Get-PnpDevice -Class Bluetooth | Where-Object { $_.FriendlyName -like "*K8*" }

# 检查录音设备
Get-AudioDevice -List
```

---

### 步骤 2：配置阿里云语音识别

**获取 API Key：**
1. 访问：https://dashscope.console.aliyun.com/
2. 登录阿里云账号
3. 开通"智能语音交互"服务
4. 创建 API Key（sk-开头）

**配置到 OpenClaw：**
```powershell
# 方式 1：写入配置文件
openclaw configure --set tts.aliyun_api_key="sk-你的 Key"

# 方式 2：设置环境变量
[Environment]::SetEnvironmentVariable("ALIYUN_API_KEY", "sk-你的 Key", "User")
```

**测试连接：**
```powershell
# 运行测试脚本
.\test-aliyun-tts.ps1
```

---

### 步骤 3：运行安装脚本

```powershell
# 进入工作目录
cd C:\Users\Xiabi\.openclaw\workspace

# 运行安装脚本
.\setup-voice-control.ps1
```

**安装脚本会：**
1. ✅ 检查文件完整性
2. ✅ 验证命令词库
3. ✅ 测试阿里云 API
4. ✅ 注册语音命令
5. ✅ 创建快捷方式

---

### 步骤 4：配置酷狗 K8 耳机

**酷狗音乐 App 设置：**
1. 打开酷狗音乐 App
2. 进入"设置" → "耳机设置"
3. 开启"语音唤醒"
4. 设置唤醒词为"嗨阿福"
5. 测试语音输入

**Windows 系统设置：**
1. 右键喇叭图标 → "声音设置"
2. 选择"Kugou K8"为默认输入设备
3. 测试麦克风音量

---

### 步骤 5：测试语音命令

**测试命令：**
```powershell
# 运行测试脚本
.\test-voice-command.ps1 -Command "生成周报"

# 或手动测试
# 1. 说"嗨阿福"唤醒
# 2. 说"生成周报"
# 3. 检查是否触发周报 Skill
```

**预期结果：**
- ✅ 语音识别准确
- ✅ 命令匹配成功
- ✅ 周报 Skill 被调用
- ✅ 文字 + 语音双重反馈

---

## 🎤 预置命令清单（20 个）

### 查询类（6 个）
| 语音命令 | 同义词 | 功能 |
|---------|--------|------|
| 当前优先级 | 优先级/优先任务/现在做啥 | 显示优先级提醒 |
| 今天天气 | 天气/天气预报 | 查询天气预报 |
| 我的工作 | 工作日志/worklog | 显示 worklog.txt |
| 项目进度 | 项目状态/进度 | 显示项目卡片 |
| 技能列表 | 有哪些技能/你能干啥 | 显示所有 Skills |
| 帮助 | 咋用/怎么用 | 显示帮助信息 |

### 执行类（9 个）
| 语音命令 | 同义词 | 功能 |
|---------|--------|------|
| 生成周报 | 周报/写周报 | 调用周报 Skill |
| 保存会话 | 保存豆包/归档会话 | 调用豆包归档 Skill |
| 打开 Chrome | 开浏览器/启动 Chrome | 启动 Chrome |
| 发送飞书 | 发飞书/通知 | 调用飞书消息 Skill |
| 播放语音 | 播放/放语音 | 播放最新 TTS |
| 专家点评 | 生成点评/HTML 点评 | 生成专家点评 HTML |
| 知识库索引 | 更新索引/刷新知识库 | 运行索引更新脚本 |
| OAuth 配置 | 飞书 OAuth/授权配置 | 飞书 OAuth 配置 |
| 晚安 | 睡觉/休息 | 晚安记忆同步 |

### 创建类（2 个）
| 语音命令 | 同义词 | 功能 |
|---------|--------|------|
| 新建待办 | 添加待办/创建任务 | 创建新任务 |
| 记录想法 | 记一下/记录 | 写入 memory 文件 |

### 删除类（2 个）
| 语音命令 | 同义词 | 功能 |
|---------|--------|------|
| 删除提醒 | 删除任务/取消提醒 | 删除 Cron 任务 |
| 清空缓存 | 清理缓存/清理 Temp | 清理 Temp 文件夹 |

### 查询类（1 个）
| 语音命令 | 同义词 | 功能 |
|---------|--------|------|
| 查看文件 | 打开文件/看文件 | 查看指定文件 |

---

## 🎯 自定义命令

**添加新命令：**
编辑 `voice-commands.json`，添加新条目：

```json
{
  "name": "你的命令",
  "action": "对应的 action 名称",
  "synonyms": ["同义词 1", "同义词 2"],
  "category": "查询类/执行类/创建类/删除类",
  "description": "命令描述"
}
```

**示例：添加"打开文档"命令**
```json
{
  "name": "打开文档",
  "action": "open-document",
  "synonyms": ["开文档", "看文档"],
  "category": "执行类",
  "description": "打开最近编辑的文档"
}
```

---

## ⚠️ 常见问题

### Q1: 语音识别不准确

**原因：** 环境噪音大 / 麦克风距离远 / 方言口音

**解决：**
- 在安静环境使用
- 靠近麦克风（≤10cm）
- 说普通话（支持轻微方言）

---

### Q2: 命令未匹配

**原因：** 不在词库中 / 发音不清

**解决：**
- 使用预置命令或同义词
- 添加自定义命令到词库
- 清晰发音

---

### Q3: API Key 无效

**原因：** Key 过期 / 配置错误

**解决：**
```powershell
# 重新配置
openclaw configure --set tts.aliyun_api_key="sk-新 Key"

# 测试连接
.\test-aliyun-tts.ps1
```

---

### Q4: 耳机未连接

**原因：** 蓝牙未配对 / 电量不足

**解决：**
- Windows 设置 → 蓝牙 → 重新配对
- 充电后重试

---

## 📚 参考文档

- Skill 文件：`skills/voice-control-enhanced/SKILL.md`
- 原子动作：`atomic-actions/04-analysis/ATOM-VOICE-001-语音命令识别.md`
- 命令词库：`voice-commands.json`
- 阿里云文档：https://help.aliyun.com/product/30487.html

---

## 🎉 安装完成！

**下一步：**
1. ✅ 测试语音命令（说"嗨阿福，生成周报"）
2. ✅ 熟悉 20 个预置命令
3. ✅ 根据需要添加自定义命令
4. ✅ 享受语音控制的便利！

**有问题？** 随时问我！ 😄🐾

---

_语音控制增强 | 酷狗 K8 集成 | 解放双手 | 2026-03-08_
