ADR-002: Robot V1 采用引导式热点配网并衔接六位绑定

Status

Accepted

Implementation status: implemented and enabled by default. Exact environment value NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0 disables the guided path as an operational rollback.

Date

2026-08-16

Supersedes

For V1 delivery only, this decision supersedes the proposed Security 2 / automatic-claim onboarding path in task 20260816-device-provisioning-flow-a4d91c.
Authenticated BLE provisioning and automatic claim remain a deferred production-security direction, not a current implementation contract.
ADR-003 supersedes only this decision's manual operating-system hotspot-selection step; all other firmware, Portal, credential, Binding, rollback, and readiness boundaries remain active.

Source proposal commit 14afe4a: .project-docs/10-decisions/proposals/20260816-minimal-firmware-onboarding-c3e8b7__guided-hotspot-binding-v1.md
Cross-platform page-owned hotspot connection: ADR-003, adr-003-robot-in-app-hotspot-connection.md
Current Robot binding implementation: src/pages/AiHardware/index.tsx, src/lib/ai-hardware.ts, electron/api/routes/ai-hardware.ts
Firmware audit target: D:\Datas\HardwareProjects\xiaozhi-esp32-firmware at audited commit 0449e51

Context

The audited firmware source enters Hotspot provisioning and serves its configuration portal, but the exact resolved component and shipped device image have not yet been verified. Makelore already provides the cloud Binding operation that accepts a six-digit activation code and an Agent. The firmware source does not expose a trusted nearby-device discovery/correlation protocol, and changing it to authenticated BLE plus automatic claim would require firmware, manufacturing identity, cloud, streaming, recovery, and physical-device contracts that are not ready.

The immediate product goal is therefore to put provisioning guidance inside the existing Robot binding experience while keeping firmware changes at zero.

Decision

V1 is a Renderer-guided, Main-gated workflow:

choose_path -> prepare_robot -> connect_device_ap -> configure_wifi -> reconnect_internet -> enter_activation_code -> binding -> bound

Makelore explains how to place the Robot in provisioning mode, scans eligible open Xiaozhi-* hotspots through the Main-owned ADR-003 Module, and connects only the candidate the user explicitly selects. System Wi-Fi remains the recovery fallback.
Electron Main alone may open the fixed system-browser portal http://192.168.4.1/; Renderer never supplies or receives an arbitrary portal URL.
After Wi-Fi provisioning, Makelore instructs the user to reconnect the computer to the internet and obtain the freshly issued six-digit activation code from the Robot.
Binding continues to use the existing bindAiHardwareDevice(activationCode, agentId, { operationId }) cloud contract.
bound means account Binding succeeded. It does not prove the Robot is currently online or protocol-ready.

The guided path is controlled by a Main-owned guidedHotspotBinding capability and is true by default. Electron Main derives the packaged default from NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING !== '0'; an exact 0 disables the path without changing the binary. Disabled builds and Renderer capability-read failures retain the existing direct six-digit Binding flow.

The implemented Host API surface is deliberately small:

GET /api/works/ai-hardware/provisioning-capabilities has no body/query and succeeds with the standard Host envelope { success: true, data: { guided_hotspot_binding: boolean } }.
POST /api/works/ai-hardware/provisioning-portal/open accepts the exact body {}, has no query, and succeeds with { success: true, data: { opened: true } }.
Portal open must check the Main-owned capability before invoking the opener. Disabled access returns logical 403 / AI_HARDWARE_PROVISIONING_DISABLED; opener failure returns logical 502 / AI_HARDWARE_PORTAL_OPEN_FAILED. Like existing handled Host API errors, those logical failures use the standard envelope over outer HTTP 200.
Both operations are local Main actions and must return before acquiring a Works access token or contacting an upstream service.

Security And Recovery Rules

The current firmware hotspot and portal are open/plain HTTP. Default-on accepts that compatibility risk but does not make the channel authenticated; product copy must warn the user not to perform the flow in an untrusted public environment.
Wi-Fi SSID/password entry stays in the firmware portal. Makelore must not collect, log, persist, or proxy Wi-Fi credentials.
Cancel, back, and application restart never imply that Wi-Fi changes on the Robot were reverted. The user is guided to reconnect and restart provisioning if needed.
A same-process ambiguous Binding retry reuses the same operation ID. An invalid/expired/consumed activation code clears both code and retained operation ID; the next freshly issued code gets a new operation ID.
Main must project ai_hardware_activation_code_invalid as non-retryable even if an upstream response incorrectly marks it retryable.
After application restart, Makelore cannot correlate an earlier code or Binding outcome from the current overview DTO. It must not replay the old code or operation ID; the user obtains a fresh code or stops.

Default-On Acceptance And Remaining Verification

The user explicitly chose default-on on 2026-08-16 while retaining the current firmware behavior. The open SoftAP/plain-HTTP channel remains a known residual risk; choosing the product default is not evidence that the physical flow or its security has passed. Before claiming complete hardware compatibility or end-to-end provisioning acceptance, all of the following still require evidence:

The exact shipped Robot component/image uses the audited Hotspot portal flow and fixed portal address.
The deployed activation issuer emits exactly six ASCII digits accepted by the existing Works Binding validator, with documented freshness and consumption behavior.
Electron E2E through the real Host API/native opener and native hotspot seams plus Windows/macOS physical-device smoke pass; focused Renderer/Main/native tests already cover default-on, exact 0 rollback, fixed portal ownership, candidate constraints, local-before-cloud behavior, cancellation, and error redaction.
Release/support instructions retain the exact =0 rollback and do not describe V1 as authenticated discovery, automatic Wi-Fi delivery, automatic claim, or proof of online readiness.

Consequences

The first implementation is desktop-only and requires no firmware, BLE, manufacturing, or cloud-contract change.
V1 may advertise nearby provisioning-hotspot discovery and explicit user-selected connection as an unauthenticated convenience, but not trusted device discovery or automatic device claim.
The UI becomes a single coherent onboarding journey while system Wi-Fi remains a recovery path and firmware Portal entry remains an explicit user action.
A later authenticated BLE/automatic-claim design requires a new accepted ADR and must not silently widen this V1 interface.

7.1 KiB Raw Permalink Blame History