# WorkBuddy 语音问答助手 · 部署说明

> 给部署人员（工作人员 / 家属）的完整指南。
> 目标：让一台新电脑在 **10 分钟内**跑起这套"语音问答助手"，且**不需要任何配置**。

---

## 一、这套系统是什么

```
┌─────────────┐   语音    ┌──────────────┐  HTTP   ┌─────────────┐
│ 盲人使用者   │ ───────▶ │  网页界面     │ ──────▶ │ 桥接代理     │
│ （对着电脑） │  TTS朗读 │ （打开即用）  │         │ (gateway-   │
└─────────────┘ ◀─────── └──────────────┘ ◀────── │  bridge.js) │
                                                  └──────┬──────┘
                                                         │ 自动发现端口/密码
                                                  ┌──────▼──────┐
                                                  │ WorkBuddy   │
                                                  │ (运行/gateway)│
                                                  └─────────────┘
```

- **网页界面**：语音输入 / 大字显示 / 自动朗读 / 进度提示，为盲人优化
- **桥接代理**：自动找到 WorkBuddy 网关的**端口**和**密码**，使用者完全不用管
- **WorkBuddy**：真正回答问题的大脑（需要先运行 `/gateway` 开启远程控制）

**最重要的设计：使用者零配置。** 端口、密码全部自动发现。

---

## 二、部署包内容

把整个 `智能助手调用` 文件夹复制到新电脑（建议放桌面），里面有：

| 文件 | 作用 | 必须？ |
|---|---|---|
| `workbuddy-accessible-workstation.html` | 语音问答网页 | ✅ |
| `gateway-bridge.js` | 桥接代理（同时托管网页） | ✅ |
| `node.exe` | 免安装的 Node.js 运行环境（87MB） | ✅（新电脑没装 Node 时必须） |
| `start-assistant.bat` | 一键启动脚本（双击即可） | ✅ |
| `部署说明.md` | 本文档 | 可选 |

> `node.exe` 是免安装的，**新电脑不需要单独安装 Node.js**。

---

## 三、新电脑部署步骤（2 步，任何电脑通用）

### 第 0 步：确保新电脑已安装 WorkBuddy

如果没有，先安装 WorkBuddy 桌面版并登录账号（**必须登录，网关依赖登录态**）。

### 第 1 步：复制部署包

把 `智能助手调用` 整个文件夹复制到新电脑（比如桌面）。

### 第 2 步：双击启动（全自动）

双击 `start-assistant.bat`，它会自动完成**所有事情**：

1. 自动打开 WorkBuddy（如果没运行）
2. **自动启动网关**（用 WorkBuddy 自带的官方命令行 `codebuddy --serve --port 7890`——这是官方通用方式，任何电脑都有效，**不需要输入任何命令**）
3. 自动启动桥接代理
4. 自动打开网页 `http://localhost:6800`

> 在 WorkBuddy 输入框输入 `/gateway` 是无效的（会被 AI 当聊天）——**不用管它**，本方案完全自动。

### 第 3 步：验证

网页顶部的连接状态应显示绿色"**已连接**"。
如果显示红色，等 10 秒自动重试即可。

---

## 四、日常使用（给使用者）

### 一键使用（推荐）

- **开机**：电脑开机后全部自动运行（WorkBuddy → 网关 → 代理 → 网页自动打开）
- **直接说话**：网页没弹出就双击桌面 **「语音问答助手-启动.bat」**
- 已设置开机自启（`autostart.vbs` 在系统启动文件夹），无需手动配置

> 桌面入口：
> - **语音问答助手-启动.bat** —— 完整启动（网关+代理+网页）
> - **语音问答助手.url** —— 只打开网页

### 操作方式

| 操作 | 方法 |
|---|---|
| 开始说话 | 点击大按钮「点击开始说话」，或按 `Ctrl+M` |
| 结束说话 | 再点一次按钮 / 再按 `Ctrl+M` |
| 提交问题 | 按 `Enter`（或点击「提交问题」） |
| 开始新问题 | 点击「开始新问题」（清空所有内容） |
| 终止任务 | 按 `Esc` |
| 重新朗读回答 | 点击「重新朗读」 |

- 回答生成后**会自动朗读**，无需任何操作
- 处理中会显示进度并语音提示"正在思考，请稍候"，不会干等

---

## 五、常见问题

| 现象 | 原因 | 解决 |
|---|---|---|
| 网页显示红色"未连接" | 桥接代理还没探测到网关（10 秒重试）；或 WorkBuddy 没运行 | 打开 WorkBuddy 并登录（网关自动启动）；**网页每 10 秒自动检测，连上自动播报"已连接"，无需任何操作** |
| 在 WorkBuddy 输入 `/gateway` 提示"不是当前可用的命令" | `/gateway` **不是 WorkBuddy 命令**，是另一个概念 | **不要输入 /gateway**！WorkBuddy 网关是应用启动时自动运行的，**什么都不用做** |
| 重启 WorkBuddy / 电脑后短暂连不上 | 网关重启，端口/密码变化 | **无需任何操作** —— 代理会自动重新发现（约 1 分钟内自动恢复） |
| 显示"已连接"但提交后报错 | 旧版代理还在用失效的连接信息（假连接 bug） | 已修复：新版代理**实测验证**连接，连不上会正确显示"未连接"；请确保使用最新版 gateway-bridge.js 并重启代理 |
| 点麦克风没反应 | 浏览器权限未授权 | 允许浏览器使用麦克风（地址栏锁图标 → 麦克风 → 允许） |
| 打开网页是英文/乱码的 bat 窗口 | 无 | 不影响使用，忽略即可 |
| 说话没识别出来 | 环境嘈杂 / 没对准麦克风 | 靠近麦克风重新说；或手动在输入框打字 |
| 代理窗口一闪而过 | 端口 6800 被占用 | 关闭占用 6800 的程序后重试 |

---

## 六、工作原理（可选了解）

- **网关启动（官方通用方式）**：本方案用 WorkBuddy 自带的官方命令行 `codebuddy --serve --port 7890` 启动网关（serve 模式）——这是 CodeBuddy/WorkBuddy 官方支持的 Web UI/API 服务方式，**任何电脑、任何账号都有效**，不依赖任何特殊权限
- 网关启动后生成随机密码（终端显示），**密码与端口全部自动发现**：
  - 端口：固定 7890（我们指定的），代理候选列表直接覆盖
  - 密码：日志提取（`CODEBUDDY_GATEWAY_PASSWORD=xxx` 格式）+ 实测验证
- 所以**使用者永远不需要输入任何命令、不需要配置端口和密码**；双击 `start-assistant.bat` 全自动完成一切

---

## 七、版本记录

- v2.6.1（当前，修复版）：① 修复开机自启脚本硬编码路径问题（autostart.vbs 改为动态定位脚本所在目录，换电脑/换目录不再失效）；② 修复网关 CLI 启动方式（codebuddy 是无扩展名的 Node 脚本，现用 node 运行，避免 Windows 无法直接执行）；③ 修复桥接代理重试逻辑（401/502 时缓冲响应后重试，消除"假已连接"与崩溃）；④ 移除配置文件中的明文密码（密码改由日志自动发现）；⑤ 桥接代理支持远程网关（gateway-config.json 配置 host 即可连接公网 WorkBuddy 网关）；⑥ 网页新增会话历史、多会话切换、积分领取等增强功能
- v2.6：无障碍优化——① 默认关闭网页自身朗读，配合争渡读屏使用，消除"两个声音"冲突（需网页朗读时用 ?voice=1 打开）；② 新增开屏快捷键说明层，操作界面不再显示文字说明；③ Tab 焦点只保留【语音输入】【新对话】，删除"朗读"按钮，"已连接"不再占焦点；④ 语音识别开始时自动停止朗读，防止麦克风识别到朗读内容；⑤ 新增每日积分领取说明（客户端左下角头像→领取今日礼包）
- v2.5：整合官方 `codebuddy --serve` 启动网关，任何电脑双击一个 bat 全自动（WorkBuddy → 网关 → 代理 → 网页）
- v2.4：一键启动 + 开机自启 + 修复代理自连 bug
- v2.3：删除"运行 /gateway"步骤（误解更正）；代理自动提取动态密码 + 动态端口扫描
- v2.2：代理自动发现网关端口；代理直接托管网页（免 Python）；一键启动脚本；免安装 Node.js
- v2.1：修复自动朗读；新增"开始新问题"按钮；修复语音识别历史累积
- v2.0：超大界面 + 阶段化进度提示
- v1.0：精简版无障碍工作台
