merge: add in-app robot hotspot connection
This commit is contained in:
@@ -19,7 +19,7 @@
|
||||
| 设计消息与确认 | 当前 Conversation | Main ↔ 持久 Agent Gateway Session WebSocket → Conversation 快照 | `command.submit`、Run 与设计事件共用连接；传输失败才以同一幂等 ID 回退 REST；结构化业务错误不重试且未知文本由 Main 脱敏；请求和流式结果同时绑定 Workspace + Conversation |
|
||||
| 设计单图来源选择 | 当前 Workspace 已完成图片 / 本地图片 | 现有 Asset 上传或选择 → `attachmentAssetIds` → 当前 Conversation Turn | 图片 Brief 用作图生图参考图；视频 Brief 用作首帧；只提交一个真实 Workspace Asset ID |
|
||||
| 设计任务同步 | 任一 Conversation 的事件流 / Quote REST 对账 | Renderer Workspace 任务列表 | Task 和 Asset 按 Workspace 归并；任务已落库但 Run 失败时恢复可见性，内部对账失败不覆盖新会话错误，切换 Conversation 后仍同步任务但不回写旧会话 |
|
||||
| Robot 引导式热点配网 V1（已实现、默认开启） | Robot Binding 页面 | 用户选择引导配网 → 进入固件配网模式 → 操作系统连接 Robot 热点 → Main 在系统浏览器打开固定 portal → 用户在 portal 配置 Wi-Fi → 电脑恢复互联网 → 现有六位 Binding | 精确环境值 `0` 或 capability 读取失败回退直接六位码；Makelore 不扫描设备、不收集 Wi-Fi 密码、不修改固件，`bound` 不等于 online/ready |
|
||||
| Robot 引导式热点配网 V1（已实现、默认开启） | Robot Binding 页面 | 用户选择引导配网 → 进入固件配网模式 → Renderer 经 Host API 请求 Main 扫描 → 用户选择短效候选 → Windows/macOS Adapter 连接并核验当前 SSID → Main 打开固定 Portal → 用户在 Portal 配置 Wi-Fi → 电脑恢复互联网 → 现有六位 Binding | 精确环境值 `0` 或 capability 读取失败回退直接六位码；系统 Wi-Fi 保留兜底，Makelore 不收集 Wi-Fi 密码、不修改固件，热点发现/`bound` 都不等于可信身份或 online/ready |
|
||||
|
||||
## State Ownership
|
||||
|
||||
@@ -37,6 +37,7 @@
|
||||
- Main Host AI proxy 可为固定 OpenCode 重试契约做窄化的内部状态投影：配额耗尽投影为 `402`，明确上游分组饱和的 `429` 投影为终止 `400`，其他 `429` 原样保留；升级 OpenCode 时必须重新验证该契约。
|
||||
- Main AppUpdater 持有 feed、原始异常、下载和安装状态；设置页只消费状态投影。一次 electron-updater `error` 事件覆盖的并发检查不会在 Renderer 重复发错，但独立的后续检查仍有自己的报告生命周期。
|
||||
- Robot V1 引导状态只在 Renderer 当前进程内保存，不持久化 Wi-Fi 凭据、activation code 或 Binding operation ID。相同进程内的模糊 Binding 重试复用 operation ID；无效码或重启后必须取得新码并使用新 operation ID。
|
||||
- Robot Hotspot Module 只在 Main 内保存最近一次扫描的短效、不透明候选快照。新的扫描、clear、60 秒过期或进程重启使旧 candidate ID 失效；Renderer 关闭/重开向导以 generation 防止旧扫描/连接结果回写。
|
||||
|
||||
## External Interfaces
|
||||
|
||||
@@ -46,7 +47,7 @@
|
||||
- Main-owned electron-updater IPC 与 Works Square 平台/架构稳定 feed；正式安装产物发布不由 Renderer 控制。
|
||||
- 服务端安全投影后的公共 `play_url`；只接受同源 HTTPS、精确 App 路径和可信版本状态。
|
||||
- Works Square Workspace/Conversation API、每个 Conversation 的持久 Agent Gateway Session、单次 WebSocket ticket、双向命令/事件帧与幂等 REST 传输回退。
|
||||
- 已实现的本机 Robot provisioning capability 与固定 portal-open Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL。
|
||||
- 已实现的本机 Robot provisioning capability、固定 portal-open 与 hotspot scan/connect Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL/SSID/BSSID/interface/profile。
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
@@ -30,8 +30,12 @@
|
||||
| `src/pages/ImageCanvas/index.tsx` | Conversation 对话、Quote 确认、统一任务列表、新会话入口与单图来源选择器 | 图片 Brief 选择/上传图生图参考图；视频 Brief 绑定首帧；均提交一个 Workspace Asset ID |
|
||||
| `src/components/layout/ImageWorkspaceSidebar.tsx` | Workspace 与近期 Conversation 切换/创建 | 切换会话不清空项目级任务 |
|
||||
| `src/pages/AiHardware/index.tsx` | Robot 管理、现有六位 Binding，以及已实现的 default-on 引导式热点配网状态机 | 只编排非敏感步骤；不接收 Wi-Fi 密码，不把 `bound` 展示为在线证明 |
|
||||
| `src/lib/ai-hardware.ts` | Renderer 侧 Robot Host API 类型、安全错误映射和稳定 Binding facade | 读取 Main-owned capability 并调用无参数固定 portal-open；不添加任意 URL 或 Renderer IPC |
|
||||
| `electron/api/routes/ai-hardware.ts` | Main-owned Robot 云端代理，以及已实现的本地配网 capability/portal action | 默认开启、精确环境值 `0` 回滚；本地操作必须在 Works token/上游访问前返回，系统浏览器只能打开固定 `http://192.168.4.1/` |
|
||||
| `src/lib/ai-hardware.ts` | Renderer 侧 Robot Host API 类型、安全错误映射和稳定 Binding/hotspot facade | 读取 Main-owned capability，调用固定 portal-open，并只传递短效 hotspot candidate ID；不添加任意 URL、SSID 或 Renderer IPC |
|
||||
| `electron/api/routes/ai-hardware.ts` | Main-owned Robot 云端代理，以及本地 capability/portal/hotspot actions | 默认开启、精确环境值 `0` 回滚；所有本地操作必须在 Works token/上游访问前返回，且只投影稳定安全错误 |
|
||||
| `electron/robot-hotspot/index.ts` | Robot hotspot 深模块：候选过滤/去重/TTL、操作互斥、超时和精确 SSID 核验 | 只接受 Adapter 输出与不透明 candidate ID；Renderer 不能选择任意 SSID |
|
||||
| `electron/robot-hotspot/windows.ts` | Windows 原生 WLAN 扫描、临时开放网络连接和当前 SSID 查询 | 懒加载 `wlanapi.dll`；不使用 `netsh`、不保存 profile、不主动断开 |
|
||||
| `electron/robot-hotspot/macos.ts` | macOS CoreLocation 授权与 worker-owned CoreWLAN 扫描/关联/核验 | Objective-C 对象不跨线程；取消/超时终止 worker，旧终止屏障阻止迟到权限/native continuation |
|
||||
| `electron/robot-hotspot/adapter.ts` | 平台 Adapter 的最小内部契约与稳定错误分类 | 平台细节不进入 Host/Renderer 公共 DTO |
|
||||
|
||||
## Dependency Direction
|
||||
|
||||
@@ -39,7 +43,7 @@
|
||||
- AI 编程 Renderer → Host API → Main OpenCode routes/runtime；OpenCode provider 请求再经 Main AI proxy 访问模型上游，Renderer 不直接持有上游凭据或本地 runtime URL。
|
||||
- Project configuration 决定产品分流；Main release builder 生成 source/built/contract，服务端独立重算和校验决定发布安全，本地 `ProjectType` 不是授权结论。
|
||||
- Built artifact preflight 检查最终上传的同字节快照，但客户端可被绕过且不产生可信 receipt；服务端仍是合同、摘要和不可变 Release 安全权威。
|
||||
- Robot Renderer → typed AI hardware API → Main Host route。云端 Binding 仍由 Main 代理；V1 配网只增加 Main-owned capability 与固定系统浏览器 action，Wi-Fi 选择和凭据输入留在操作系统/固件 portal。
|
||||
- Robot Renderer → typed AI hardware API → Main Host route → Robot Hotspot Module → Windows/macOS Adapter。云端 Binding 仍由 Main 代理；热点选择/连接移入页面，但家庭 Wi-Fi 凭据输入仍只留在固件 Portal，系统 Wi-Fi 保留为兜底。
|
||||
|
||||
## Risky Or Sensitive Areas
|
||||
|
||||
@@ -55,7 +59,7 @@
|
||||
- Gateway 命令的 REST fallback 只处理 WebSocket 发送、断连和 ACK 超时，必须复用 `client_command_id`；业务错误回退会造成重复提交。Quote 任务恢复只更新 Workspace 所有的任务，不能覆盖当前 Conversation。
|
||||
- `closeEventSessions` 只负责本地流和缓存生命周期；远端 Conversation Session 是服务端持久资源。
|
||||
- 单图来源选择器当前仍由精确中文 quick reply 触发，并以 Brief medium 判断图生图或视频首帧用途；扩展更多输入用途前应先把消息协议升级为结构化 action/purpose，避免展示文案与行为继续耦合。
|
||||
- Guided Hotspot Binding 已由产品决策默认开启，但仍依赖当前固件的开放热点和明文 HTTP portal。未完成指定固件镜像核对、六位码发行契约、原生 opener E2E 和真机 smoke 前不得宣称完整兼容；现场异常使用精确环境值 `0` 回滚。
|
||||
- Guided Hotspot Binding 已由产品决策默认开启，并通过 native dependency 执行未经认证的热点扫描/连接。未完成指定固件镜像核对、六位码发行契约、签名 macOS x64/arm64 worker/ASAR/Koffi 验证、Windows 真机和完整 Electron/Robot smoke 前不得宣称完整兼容；现场异常使用精确环境值 `0` 回滚。
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
@@ -24,7 +24,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
|
||||
| Robot Workspace | Account-scoped agent configuration, device activation/binding, assignment, and credential-recovery UI | Renderer receives only safe Works Square projections. Configuration choices come from the USER-scoped safe catalog; unavailable current values remain editable without exposing provider credentials or configuration internals. |
|
||||
| AI Hardware Main Route | Fixed `/api/works/ai-hardware` Host API to Works Square proxy | Main owns Bearer auth, stable operation IDs, bounded retry, ETag/If-Match, request/response limits, error redaction, and the fixed no-store configuration-catalog proxy. Versioned responses accept only canonical strong or weak numeric ETags that equal the DTO revision; mutations always emit strong `If-Match`. It never forwards Renderer authorization headers. |
|
||||
| Guided Hotspot Binding V1 | Implemented, default-on Renderer journey over the current firmware Hotspot portal and six-digit Binding | Exact environment value `0` disables the journey. System Wi-Fi selection and portal credential entry remain user/firmware-owned; no BLE, automatic claim, or firmware change is part of V1. |
|
||||
| Robot Hotspot Module | Main-owned bounded scan/connect/verify interface with Windows WLAN and macOS CoreWLAN/CoreLocation adapters | Accepts only short-lived opaque candidates from the latest scan, exposes no BSSID/interface/profile/native diagnostic, and retains the system-Wi-Fi fallback. |
|
||||
| Guided Hotspot Binding V1 | Implemented, default-on Renderer journey over in-page hotspot selection, the current firmware Portal, and six-digit Binding | Exact environment value `0` disables the journey. Hotspot discovery is unauthenticated convenience; Portal credential entry remains firmware-owned, and no BLE, automatic claim, or firmware change is part of V1. |
|
||||
|
||||
## Important Boundaries
|
||||
|
||||
@@ -34,6 +35,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
- One local account maps to one server-side Xiaozhi account binding. Agents and devices are resources beneath that account binding, not separate Xiaozhi users.
|
||||
- Robot/Canvas/module-selection routes must not initialize AI Programming projects or providers.
|
||||
- Guided Hotspot Binding is implemented behind a Main-owned capability that is true by default; exact `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0` disables it, while capability-read failure falls back to direct six-digit Binding. The guided state is process-local, opener failures expose only the same fixed address for manual copy, and Binding conflicts refresh the safe account overview.
|
||||
- Robot hotspot scanning and connection are local Main operations that return before Works credentials/upstream access. Renderer may submit only an opaque candidate ID from the latest bounded scan; Main alone filters open printable `Xiaozhi-*` SSIDs, performs platform association, and verifies the exact current SSID.
|
||||
- Hotspot discovery and connection do not authenticate a Robot. BSSID, interface/profile details, native diagnostics, location data, and Wi-Fi credentials never cross the Main boundary; permission or platform failure keeps the system-settings/manual path available.
|
||||
- The fixed portal action may open only `http://192.168.4.1/` in the system browser and must not acquire cloud credentials or call Works Square. Renderer never supplies a portal URL and never handles Wi-Fi credentials.
|
||||
- A successful Binding means account ownership was established; it is not evidence that the Robot is currently online or protocol-ready.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user