# 玩具搭档：遥控玩具自扩展前端

这是一个与现有 `apps/web-console` 相互独立的自扩展前端。所有页面、样式、交互和本地 GSCU1B 桥接均位于当前目录，不需要改动主控制台。页面采用不需要纵向滚动的单屏工作台：左侧固定展示六类玩具区域，每类区域可添加并切换多台具体硬件；右侧预留车端设备动作。

## 能力范围

- 建立多个外设硬件档案，预定义为灯光类、声音类、动作类、玩偶类、机械类和其他玩具。
- 每个玩具类型区域均可添加多台同类硬件，并通过区域内的硬件选择框切换；新增硬件不会替换或占用其他类型区域。
- 添加硬件时从对应类型区域进入，再填写具体硬件名称；系统自动创建该类型的 12 个常见待学习动作。
- 每个类型区域一次展示 6 个动作，可在卡片内翻页；点击预设动作即可开始学习，不需要重复输入动作名称。
- 将实体遥控器的任意按键学习到 GSCU1B 的 1–248 号槽位。
- 为按键配置能力名称、自然语言别名、类型、说明和风险等级。
- 完成测试发射并由用户确认物理反应后，将按键注册为可执行能力。
- 由服务端 GPT 根据当前已学能力理解省略硬件名称的表达，例如只有一台灯光类外设时可直接说“打开灯光”。
- 将外设红外动作与 CAN_DEV 的座椅、空调、出风口、遮阳帘、车内灯光、车窗和门锁能力编排成同一份有序计划。
- 导出和导入玩具档案及能力注册；设备凭据不会进入导出文件或浏览器存储。
- 区分“学习器已发射”与“玩具物理执行成功”，后者始终需要独立确认。
- 在动作卡片上删除单项前端登记；使用“开始新一轮测试”调用 GSCU1B 全量 `erase`，同步清空全部已学动作和测试记录。

首次启动会创建一个“灯光测试玩具”，并在固定的灯光类区域显示开启、关闭、红/绿/蓝/白/暖色灯光、快速/慢速闪烁、亮度增减和呼吸灯效 12 个待学习动作。声音类、动作类、玩偶类、机械类和其他玩具区域也会直接展示各自的预设动作；添加具体硬件后即可学习。

## 运行

在当前目录运行：

```powershell
python .\server.py
```

浏览器访问：

```text
http://127.0.0.1:8010
```

默认监听 GSCU1B TCP `4444` 并尝试连接真机。如需纯界面演示，可在启动前设置 `$env:GSCU_TRANSPORT='simulation'`。

## GPT 智能编排

GPT 只在 `server.py` 中调用，API Key 不会进入 HTML、JavaScript、浏览器存储或接口响应。当前兼容服务使用 Responses API 流式结构化输出：

```powershell
$env:OPENAI_BASE_URL='https://api.kendeji.fun/v1'
$env:OPENAI_API_KEY='请在本机安全设置，不要写入仓库'
$env:IR_OPENAI_MODEL='gpt-5.6-sol'
```

前端会把当前已学习的外设能力目录和 CAN_DEV 车端能力目录交给 GPT。GPT 只生成能力级计划：外设步骤只能引用已学习的能力 ID，车端步骤只能生成自然语言请求；原始 CAN 帧仍由 CAN_DEV 的确定性编译与安全校验链路生成。

## CAN_DEV 车端能力

独立终端运行以下脚本，启动 `127.0.0.1:8000` 的车端编排服务：

```powershell
.\run-vehicle-orchestrator.ps1
```

脚本优先使用 `.codex_tmp/can-dev-runtime/Cognitive_Agent` 中的 `project-code/CAN_DEV` 工作树；不存在时使用当前仓库的 Cognitive Agent。当前工作树可这样建立：

```powershell
git remote add project-code https://git.kendeji.fun/dev-team/project-code.git
git fetch project-code CAN_DEV
git worktree add --detach .codex_tmp/can-dev-runtime project-code/CAN_DEV
```

前端桥接地址默认为 `http://127.0.0.1:8000`，可通过 `COGNITIVE_AGENT_API_URL` 修改。默认 `COGNITIVE_AGENT_EXECUTION_MODE=dry_run`，因此会完成 GPT 解析、配置校验、CAN 编译和虚拟执行，但不会发送真实 CAN。真实台架必须沿用 CAN_DEV 的硬件开关、授权令牌、固件身份和回读门禁，不应只修改前端。

## GSCU1B TCP 接入

推荐首次联调使用局域网 TCP。GSCU1B 作为 TCP Client 连接到电脑：

1. 使用 5V/1A Type-C 电源给学习器上电，并将其配置到与电脑相同的 2.4GHz Wi-Fi。
2. 查询电脑的局域网 IPv4 地址。
3. 将设备的自定义 TCP 服务器地址设置为该 IPv4 地址，端口设为 `4444`。
4. 在本目录打开 PowerShell 并运行：

```powershell
$env:GSCU_TRANSPORT='tcp'
$env:GSCU_TCP_LISTEN_HOST='0.0.0.0'
$env:GSCU_TCP_PORT='4444'
python .\server.py --host 0.0.0.0 --port 8010
```

5. 必要时允许 Windows 防火墙入站 TCP `4444`；若 PAD 访问页面，还要允许 `8010`。
6. 重启学习器，打开页面右上角“连接真机”，保存后刷新，直到显示“学习器已连接”。

PAD 或其他电脑通过 `http://<电脑局域网IP>:8010` 访问。真实环境应只在可信局域网使用，或在外部增加认证与 HTTPS 反向代理。设备能力与供电参数以 [GSCU1B 产品说明](https://www.smart-bird.cn/mobile/infrared-controller-WiFi.html) 为准，指令字段以 [官方开发指令](https://www.smart-bird.cn/doc/product/GSCU/device/GSCU1B/command) 和实际固件返回为准。

## GSCU1B MQTT 接入

安装 MQTT 依赖：

```powershell
python -m pip install -r .\requirements.txt
```

配置设备对应的 Broker 和主题后启动：

```powershell
$env:GSCU_TRANSPORT='mqtt'
$env:GSCU_MQTT_HOST='mqtt.geek-smart.cn'
$env:GSCU_MQTT_PORT='1883'
$env:GSCU_MQTT_CLIENT_ID='ir-toy-console-unique-id'
$env:GSCU_MQTT_USERNAME='your-username'
$env:GSCU_MQTT_PASSWORD='your-password'
$env:GSCU_COMMAND_TOPIC='/device/subscribe-topic'
$env:GSCU_RESPONSE_TOPIC='/device/publish-topic'
python .\server.py
```

如果使用 TLS，再设置：

```powershell
$env:GSCU_MQTT_TLS='true'
```

MQTT 密码和主题只存在于服务端环境变量中，不会发送给浏览器。

## 固件协议兼容

本地控制资料使用 `data.no` 传递 `learn` 和 `emit` 的槽位，而部分官方示例使用顶层 `no`。桥接默认采用本地资料的 `data.no` 形式：

```powershell
$env:GSCU_SLOT_FIELD_MODE='data'
```

如果实际固件要求顶层字段：

```powershell
$env:GSCU_SLOT_FIELD_MODE='top_level'
```

切换后重启 `server.py`。

## 文件说明

```text
index.html        独立页面结构
styles.css        响应式视觉样式
app.js            玩具档案、学习状态机、能力库和一句话编排
server.py         静态服务及 GSCU1B HTTP/TCP/MQTT 桥接
run-vehicle-orchestrator.ps1  启动 CAN_DEV 车端编排服务
requirements.txt  MQTT 模式可选依赖
README.md         运行与设备接入说明
```

## 当前边界

- 能力库默认存储在当前浏览器的 `localStorage`，适合自扩展原型和单机测试。
- 同一个 GSCU1B 的红外发射按顺序执行，不声明真正并行；GPT 计划会保留“5 秒后”等相对等待语义，在对应动作执行前倒计时。单步等待上限为 60 秒，整份计划累计等待上限为 5 分钟。
- 车端默认为 CAN_DEV `dry_run` 安全演练；只有 CAN_DEV 自身硬件门禁全部通过时才允许真实下发。
- GSCU1B 资料只提供全量 `erase`，没有单槽位擦除。删除单项能力只删除注册映射；需要硬件完全归零时使用页面顶部“开始新一轮测试”。
- 红外设备通常没有玩具状态回读；页面中的成功代表学习器命令已处理，不代表玩具动作已由传感器确认。