# 智能助手 · 语音问答助手 —— 连接说明

> 本文件写给「下载本安装包的客户 / 工作人员」。
> 核心一件事：**把本 zip 发送给你电脑上的 WorkBuddy，让 WorkBuddy 的账号连接到语音问答网页。**

---

## 一、这套系统是什么（30 秒了解）

```
你（说话）→ 语音问答网页 → 桥接代理 → WorkBuddy（你的账号）→ 回答并自动朗读
```

- **语音问答网页**：语音输入 / 大字显示 / 自动朗读，为视障使用者优化
- **桥接代理**：自动找到 WorkBuddy 网关的端口和密码，全程零配置
- **WorkBuddy**：真正回答问题的大脑 —— **谁登录 WorkBuddy，网页就用谁的账号**

---

## 二、推荐方式：把 zip 发送给本机 WorkBuddy（自动连接账号）

> 前提：本电脑已安装 **WorkBuddy 桌面版** 并登录你自己的账号。
> （如未安装：去 WorkBuddy 官网下载安装，打开后用微信扫码登录）

**只需 3 步：**

1. **打开 WorkBuddy** 桌面版，确认左下角头像显示已登录（**用你自己的账号**）
2. **把本 zip 文件直接拖进 WorkBuddy 对话框**（或点输入框旁的附件按钮，选择本 zip 文件发送）
3. 对 WorkBuddy 说一句：
   > **"请解压这个包，按里面的说明部署语音问答助手，并打开网页"**

WorkBuddy 会自动：
- 解压本包、读取本说明与部署说明
- 启动网关（`codebuddy --serve --port 7890`）
- 启动桥接代理
- 打开语音问答网页 `http://localhost:6800`

**网页顶部显示绿色「已连接」即可使用 —— 此时网页连接的就是你登录账号的 WorkBuddy。**

> 如果 WorkBuddy 没有自动执行，只给出了文字指引，就按它说的做，或使用下面「手动方式」。

---

## 三、账号是怎么"连"到网页的（原理，了解即可）

- 语音问答网页**不保存任何账号**，也没有登录框
- 网页通过桥接代理，自动发现**本机** WorkBuddy 的网关（端口 7890，密码自动从 WorkBuddy 日志提取）
- **网关身份 = 当前登录 WorkBuddy 的账号**
- 所以：**只要 WorkBuddy 登录的是你的账号，网页上的问答就全部由你的账号完成**

一句话：**WorkBuddy 登录谁，网页就是谁。**

---

## 四、手动方式（备用，不依赖 WorkBuddy 自动执行）

### Windows
1. 把本 zip 解压，得到一个文件夹（如 `智能助手调用-v2.6.1-修复版`），放到桌面
2. 双击 `start-assistant.bat`
3. 网页自动打开，顶部变绿「已连接」即可说话

### Mac
1. 解压 zip，得到文件夹（如 `智能助手调用-v2.6.1-Mac版`）
2. 双击 `启动语音问答助手.command`（首次若被拦截：右键 → 打开）
3. 需已安装 Node.js（终端执行 `brew install node`）

---

## 五、一键启动失败排查

| 现象 | 原因 | 解决 |
|---|---|---|
| 网页显示红色「未连接」 | WorkBuddy 未运行 / 未登录 / 网关未启动 | 打开 WorkBuddy 并登录自己的账号；网页每 10 秒自动重连 |
| 提示「未找到 codebuddy / CLI」 | WorkBuddy 安装路径不同或未安装 | 重新安装 WorkBuddy 并登录；或直接在 WorkBuddy 里发送本 zip 让它处理 |
| 提示「Node.js not found」（Windows） | node.exe 缺失 | 确认 zip 完整解压，`node.exe` 与 bat 在同一文件夹 |
| 提示「未找到 Node.js」（Mac） | Mac 需自行安装 | 终端执行 `brew install node` |
| 双击 bat 一闪而过 | 端口 6800 被占用 | 先关闭旧窗口，或重启电脑后重试 |
| 点麦克风没反应 | 浏览器麦克风权限未授权 | 地址栏锁图标 → 麦克风 → 允许 |
| 端口 6800 / 7890 被其他程序占用 | 冲突 | 关闭占用程序（如 TRAE、Live Server）后重试 |

---

## 六、常见问题

**Q：网页必须和 WorkBuddy 在同一台电脑吗？**
A：本安装包默认是本机模式 —— 网页、桥接、WorkBuddy 在同一台电脑上即可。跨电脑远程连接需要手动修改 `gateway-config.json`，属进阶用法。

**Q：为什么网页没有登录框？**
A：这是刻意设计。账号跟随 WorkBuddy 客户端，网页无需（也不该）保存账号，使用者零操作。

**Q：换一个账号怎么办？**
A：在 WorkBuddy 里退出并登录新账号，重启一次桥接代理（Windows 双击 `start-assistant.bat`，Mac 双击 `.command`），网页自动切换到新账号。

**Q：「一键领取积分」按钮怎么用？**
A：点击后会自动在 WorkBuddy 客户端定位并点击「领取今日礼包」（每日签到，前 6 天每天 100 分、第 7 天 1000 分）；如自动点击失败，会唤起 WorkBuddy 并语音引导手动领取。

---

## 七、安装包内容

| 文件 | 作用 |
|---|---|
| `workbuddy-accessible-workstation.html` | 语音问答网页 |
| `gateway-bridge.js` | 桥接代理（托管网页 + 自动发现网关） |
| `gateway-config.json` | 连接配置（默认本机 7890） |
| `start-assistant.bat`（Windows） | 一键启动脚本 |
| `node.exe`（Windows） | 免安装 Node.js 运行环境 |
| `启动语音问答助手.command`（Mac） | Mac 一键启动脚本 |
| `claim-points.ps1` / `click-claim-points.applescript` | 「一键领积分」自动点击脚本 |
| `部署说明.md` / 本文件 | 说明文档 |

> 需要帮助：把 WorkBuddy 的回复或报错截图发给工作人员即可。
