docs(robot): accept guided hotspot binding v1
This commit is contained in:
brother7 committed
1 parent
bfcb88cfef
commit
54443232dd
10 files changed
+133
-9
No files matched your search
@@ -19,6 +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 | Makelore 不扫描附近设备、不收集 Wi-Fi 密码、不修改固件；`bound` 不等于 online/ready |
|
||||
|
||||
## State Ownership
|
||||
|
||||
@@ -35,6 +36,7 @@
|
||||
- AI 编程压缩状态由 transcript 中的 `compactionsById` / `compactionOrder` 单一持有。运行中 hydration 保留 manual pending identity 并用 native Part 合并；completed 不得回退为 running。`session.compacted` 不是 run idle，不能据此释放 queued prompt；失败、中止或 runtime generation 变化只清理对应未完成事件。
|
||||
- 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。
|
||||
|
||||
## External Interfaces
|
||||
|
||||
@@ -44,7 +46,8 @@
|
||||
- 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。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-15
|
||||
2026-08-16
|
||||
@@ -29,6 +29,9 @@
|
||||
| `src/stores/image-workspace.ts` | 当前 Workspace/Conversation、项目任务及流式更新状态 | Quote/task 按 Workspace 无 UI 错误副作用地对账；Conversation 写入按 Workspace-load + Conversation-selection generation/revision 防护 |
|
||||
| `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-off 引导式热点配网状态机 | 只编排非敏感步骤；不接收 Wi-Fi 密码，不把 `bound` 展示为在线证明 |
|
||||
| `src/lib/ai-hardware.ts` | Renderer 侧 Robot Host API 类型、安全错误映射和稳定 Binding facade | 计划新增只读 capability 与无参数固定 portal-open 操作；不添加任意 URL 或 Renderer IPC |
|
||||
| `electron/api/routes/ai-hardware.ts` | Main-owned Robot 云端代理，以及计划中的本地配网 capability/portal action | 本地操作必须在认证/上游访问前返回；系统浏览器只能打开固定 `http://192.168.4.1/` |
|
||||
|
||||
## Dependency Direction
|
||||
|
||||
@@ -36,6 +39,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。
|
||||
|
||||
## Risky Or Sensitive Areas
|
||||
|
||||
@@ -51,7 +55,8 @@
|
||||
- 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，只能作为 default-off 内部试点；未完成指定固件镜像核对、六位码发行契约和真机 smoke 前不得开启。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-15
|
||||
2026-08-16
|
||||
@@ -24,6 +24,7 @@ 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 | Planned, default-off Renderer journey over the current firmware Hotspot portal and six-digit Binding | System Wi-Fi selection and portal credential entry remain user/firmware-owned. Main exposes only a boolean capability and a fixed system-browser open action; no BLE, automatic claim, or firmware change is part of V1. |
|
||||
|
||||
## Important Boundaries
|
||||
|
||||
@@ -32,6 +33,9 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
- Robot model, language, and voice choices are dynamically projected from the Xiaozhi USER catalog through Works Square and Electron Main; the catalog is bounded, account-scoped, and `private, no-store` at each public hop.
|
||||
- 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 an accepted but not-yet-implemented V1 boundary. Its Main-owned capability remains false by default; disabled/public builds keep the current direct six-digit Binding UI.
|
||||
- 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.
|
||||
|
||||
- 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。
|
||||
- 创建者发布唯一调用链是 `ProjectPublishAction → publishWorksProjectSource → Main-owned release build → preflightStaticArtifact → source+built+artifact_contract 上传 → 状态轮询`；客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。
|
||||
@@ -55,8 +59,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
|
||||
## Related Decisions
|
||||
|
||||
- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。
|
||||
- 当前长期边界记录于 README、ADR-001、ADR-002、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属、Robot 配网/绑定安全边界或重新引入客户端部署协调器，应新增 ADR。
|
||||
|
||||
## Last Updated
|
||||
|
||||
2026-08-14
|
||||
2026-08-16
|
||||
Reference in new issue
Block a user