ADR-003: Robot 配网页内连接 Windows 与 macOS 热点

Status

Accepted

Implementation status: implemented and enabled with Guided Hotspot Binding. Exact environment value NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0 disables the complete guided path and preserves direct six-digit Binding.

Date

2026-08-16

Supersedes

Supersedes only ADR-002's requirement that the user leave Makelore and select the Robot hotspot in the operating-system Wi-Fi panel.
Preserves ADR-002's firmware-zero-change, fixed Portal, Wi-Fi credential isolation, Activation, six-digit Binding, bound semantics, and exact =0 rollback.

Context

ADR-002 delivered a coherent firmware-zero-change journey, but its connect_device_ap step remained manual. The user explicitly requested that Makelore show connectable Robot hotspots and connect the selected hotspot inside the binding dialog on both Windows and macOS.

The current firmware exposes an open Xiaozhi-* provisioning hotspot. Its SSID prefix is only a convenience filter: it does not authenticate Robot identity, ownership, account Binding, or online readiness. Exact shipped-image and physical-device behavior remain release evidence rather than assumptions.

Decision

Electron Main owns a Robot Hotspot Module with platform Adapters:

Windows uses the native WLAN API for open-network scanning, temporary discovery connection, and exact current-SSID verification. It does not parse netsh output or persist a Wi-Fi profile.
macOS uses CoreWLAN for scanning, association, and exact current-SSID verification. Main owns CoreLocation authorization; CoreWLAN work runs in an abortable worker that owns its Objective-C objects.
Unsupported platforms fail safely to the existing system-Wi-Fi/manual fallback.

Renderer accesses only two typed Host operations:

POST /api/works/ai-hardware/provisioning-hotspots/scan accepts exact body {} and returns bounded { candidate_id, ssid, signal_percent, connected } projections.
POST /api/works/ai-hardware/provisioning-hotspots/connect accepts exact body { candidate_id } and succeeds only after the current SSID exactly matches the selected candidate.

Both routes authenticate through the normal loopback Host boundary, check the Main-owned capability, and finish locally before Works credentials or upstream access. Native diagnostics, BSSID, interface names, profiles, and location data never cross into Renderer.

Entering connect_device_ap starts a scan. Makelore displays nearby eligible hotspots and requires the user to choose one explicitly; it never auto-connects the strongest candidate. A verified connection advances to the existing fixed-Portal step. Permission denial, no candidates, timeout, unsupported platform, or connection failure retains a safe retry and manual system-Wi-Fi path.

Candidate And Operation Rules

Only explicitly open, connectable, printable Xiaozhi-* SSIDs no longer than 32 UTF-8 bytes are eligible.
Duplicate SSIDs collapse to the strongest candidate. BSSID never leaves Main.
Candidate IDs are unpredictable and valid only for the latest bounded Main snapshot; rescan, clear, process restart, or the 60-second TTL invalidates them.
Scan and connect are mutually exclusive and bounded. Abort or dialog-session replacement prevents stale permission, worker, or UI continuation.
Discovery and association are unauthenticated convenience signals. They must not be presented as trusted physical identity, automatic claim, or protocol-online proof.

Security And Privacy

Main is the only native-network owner. Renderer cannot submit an arbitrary SSID, BSSID, interface, profile, command, or URL.
Makelore handles no Robot-hotspot password and no home-network credential. Home Wi-Fi SSID/password remain inside the firmware Portal.
Logs and safe errors exclude BSSID, interface/profile details, native diagnostics, Wi-Fi credentials, and location data.
The current open SoftAP/plain-HTTP risk and public-environment warning remain. Default-on does not make the channel authenticated.

Verification And Release Gates

The implementation passed focused Renderer/Main/native tests, the full unit suite, typecheck, lint, production build, Windows Electron/Koffi/WLAN definition loading, a Windows permission-denied native probe, and independent Standards/Spec review.

Before claiming complete two-platform hardware acceptance, release evidence must still include:

A Windows physical Robot scan, selection, connection, exact-SSID verification, Portal, and Binding smoke with location/Wi-Fi access enabled.
Signed packaged macOS x64 and arm64 permission, scan, association, worker/ASAR/Koffi loading, current-SSID, Portal, and Binding smoke.
Electron E2E through the real Host API and native platform seam for success and recovery outcomes.
Exact shipped-firmware hotspot naming/open-network behavior, fixed Portal, and six-digit issuer/validator compatibility.

Consequences

Users can select and connect a Robot provisioning hotspot without first leaving Makelore, while the manual system path remains available.
The firmware, fixed Portal, cloud Binding contract, and credential boundary remain unchanged.
Packaging now includes a native Koffi dependency and macOS location usage descriptions, expanding signing and platform acceptance work.
Trusted discovery, automatic claim, or new firmware provisioning still requires a separate authenticated protocol and accepted ADR.

5.4 KiB Raw Blame History