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

Status

Accepted

Implementation status: implemented; the capability remains disabled by default until all pilot release gates pass.

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.

Source proposal commit 14afe4a: .project-docs/10-decisions/proposals/20260816-minimal-firmware-onboarding-c3e8b7__guided-hotspot-binding-v1.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 and connect the computer to the Robot's existing Wi-Fi hotspot through the operating system.
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. It is false by default. Public builds with the capability disabled retain the existing direct six-digit Binding flow.

The planned 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. V1 is an internal pilot only; 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.

Release Gates

The capability may be enabled only after all of the following are evidenced:

The exact shipped Robot component/image is confirmed to use 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.
Focused Renderer/Main route tests, Electron E2E through the real Host API seam, and a physical-device smoke all pass.
The public/default configuration remains disabled until the open SoftAP/plain-HTTP risk is explicitly accepted for the intended pilot population.

Consequences

The first implementation is desktop-only and requires no firmware, BLE, manufacturing, or cloud-contract change.
V1 cannot truthfully advertise automatic nearby-device discovery or automatic device claim.
The UI becomes a single coherent onboarding journey while system Wi-Fi selection and firmware portal entry remain explicit user actions.
A later authenticated BLE/automatic-claim design requires a new accepted ADR and must not silently widen this V1 interface.

5.7 KiB Raw Blame History