From 55e61b7d8f9caccdad54dc9a42092fc7960fb394 Mon Sep 17 00:00:00 2001 From: brother7 <7brother7@gmail.com> Date: Mon, 17 Aug 2026 20:43:24 +0800 Subject: [PATCH] fix: retry macOS robot hotspot scans --- ...60817-robot-hotspot-scan-missing-4c7e91.md | 103 ++++++++++++++++++ electron/robot-hotspot/macos.ts | 48 ++++++-- tests/unit/robot-hotspot-module.test.ts | 58 +++++++++- 3 files changed, 201 insertions(+), 8 deletions(-) create mode 100644 .project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md diff --git a/.project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md b/.project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md new file mode 100644 index 0000000..e2cb957 --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md @@ -0,0 +1,103 @@ +# Task: Diagnose Robot hotspot missing from in-app scan + +## Identity + +- Task ID: 20260817-robot-hotspot-scan-missing-4c7e91 +- Mode: Feature +- Branch: codex/20260817-robot-hotspot-scan-missing-4c7e91-robot-hotspot-scan-missing +- Worktree: D:\Datas\OthersProjects\makelore-robot-hotspot-scan-missing-4c7e91 +- Base commit: 7e8d9e38114158992c03e589de32535274796d04 +- Owner: codex-root +- Status: Complete — bounded macOS SSID-visibility repair implemented and automated; signed-device smoke remains a release follow-up + +## Scope + +- Reproduce the reported gap where the operating-system Wi-Fi surface lists a Robot provisioning hotspot but Makelore's guided binding scan does not. +- Trace the full local path from the Windows/macOS native adapter through Robot Hotspot Module filtering, Host projection, and Renderer state without exposing SSIDs or native diagnostics to Renderer/logs. +- If a client defect is confirmed, add the narrowest regression test and repair the Makelore scan path while preserving the current firmware, fixed Portal, six-digit Binding, manual system-Wi-Fi fallback, and exact environment rollback. + +## Intent And Constraints + +- Use a tight deterministic feedback loop that can fail for the same native candidate shape before changing production code. +- Do not edit `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware`; the user prefers firmware-zero-change and the current accepted ADR preserves that boundary. +- Do not broaden Makelore into a general Wi-Fi manager or expose BSSID, interface/profile details, location data, credentials, or raw native errors beyond Electron Main. +- Preserve explicit user selection, bounded operations, opaque short-lived candidate IDs, exact-current-SSID verification, and the system Wi-Fi fallback. +- Treat physical adapter behavior and the exact shipped macOS package as unverified until observed; do not infer hardware acceptance from unit tests. The user has now confirmed macOS and a case-correct `Xiaozhi-` hotspot visible in the system Wi-Fi surface. + +## Project Context Loaded + +Task context: +- Task ID: `20260817-robot-hotspot-scan-missing-4c7e91` +- Mode: Feature +- Branch: `codex/20260817-robot-hotspot-scan-missing-4c7e91-robot-hotspot-scan-missing` +- Worktree: `D:\Datas\OthersProjects\makelore-robot-hotspot-scan-missing-4c7e91` +- Base commit: `7e8d9e38114158992c03e589de32535274796d04` +- Other active local tasks: the long-running `main` integration owner and all feature owners remain in separate registered worktrees. Planning-status peer records were read; the only Robot-hotspot implementation task is already integrated/complete, while the active multi-chat, Canvas-error, account-lifecycle, and compaction scopes do not overlap this task. +- Overlap or semantic-conflict assessment: no peer owns this worktree. This task follows ADR-003 and investigates an unverified physical-device release gate rather than changing its product direction. The old integration task still owns `main`, so this feature remains isolated. + +Read: +- `.project-docs/05-agent-entry/read-before-planning.md` +- `.project-docs/05-agent-entry/planning-gate.md` +- `.project-docs/05-agent-entry/memory-index.md` +- this active task record +- `.project-docs/00-brief/project-positioning.md` +- `.project-docs/00-brief/success-criteria.md` +- `.project-docs/30-worklog/current-state.md` +- `.project-docs/10-decisions/decision-index.md` +- `.project-docs/10-decisions/adr-003-robot-in-app-hotspot-connection.md` +- `.project-docs/20-architecture/system-overview.md` +- `.project-docs/20-architecture/module-map.md` +- `.project-docs/20-architecture/data-flow.md` +- `.project-docs/40-domain/business-rules.md` +- `.project-docs/50-evidence/evidence-index.md` +- `.project-docs/60-reflection/reflection-index.md` +- `.project-docs/80-commitments/commitments.md` +- `.project-docs/90-maintenance/stale-items.md` +- relevant peer task records for the `main` integration and Robot hotspot implementation, plus all other planning-status owners + +Relevant understanding: +- Project goal: keep Robot as one cross-platform Electron module whose native/system and cloud boundaries are owned by Main. +- Current integrated focus: Guided Hotspot Binding is default-on and should list nearby eligible open `Xiaozhi-*` hotspots in-page, with system Wi-Fi as fallback. +- Active task scope: reproduce and correct a system-visible but application-missing Robot hotspot without changing firmware or Binding contracts. +- Active constraints: Main-only native access, no Wi-Fi credentials or native identifiers in Renderer, explicit selection, bounded scan/connect, safe fallback, exact `=0` rollback. +- Decisions affecting this task: ADR-003 accepts Windows WLAN/macOS CoreWLAN page-owned scan and requires open/connectable/printable `Xiaozhi-*` candidates; changing that contract requires evidence, not assumption. +- Evidence, reflections, or commitments affecting this task: existing automation passed, but Windows physical Robot, signed macOS, exact shipped firmware, and real Host/native E2E remain pending; this report is physical evidence that the current discovery path may be incomplete. +- Files or modules likely involved: `electron/robot-hotspot/{index,windows,macos,adapter}.ts`, `electron/api/routes/ai-hardware.ts`, `src/lib/ai-hardware.ts`, `src/pages/AiHardware/index.tsx`, and focused Robot hotspot/API/page tests. +- Unknowns, stale docs, or conflicts: the physical CoreWLAN result, installed package signature/Info.plist, macOS version, and current Location authorization state are not directly observable on this Windows host; `project-positioning.md` remains a canonical placeholder; no accepted decision conflicts with diagnosing or repairing this gap. + +Gate result: +- Passed. + +## Outcome + +- Reproduced the reported class of failure on the Windows development machine through the real `wlanapi.dll` Adapter followed by the production Robot Hotspot Module: an Adapter scan returned one open/connectable candidate while the Module projected zero candidates because none matched the exact `Xiaozhi-` filter. The diagnostic emitted aggregate counts only and was removed after use. +- Confirmed Host, Renderer facade, and page do not silently transform a valid non-empty candidate response into an empty list. Empty UI state originates at the native/Module candidate boundary unless a deliberately superseded Renderer session ignores a late result. +- Confirmed current firmware source at `0449e51` configures a visible open `Xiaozhi-XXXX` SoftAP through `WifiBoard` and therefore matches the accepted filter. This source fact does not prove which image is installed on the user's device. +- The user subsequently confirmed the affected computer is macOS and the system-visible hotspot uses the exact case-sensitive `Xiaozhi-` prefix. This rules out the Windows scan path and the known prefix mismatch class for this incident. +- Confirmed the macOS worker currently converts a non-empty CoreWLAN result whose `CWNetwork.ssid` values are all unavailable into a normal empty candidate list. On current macOS releases SSID access is gated by the app's Location privilege, and Apple DTS has documented a first-read-after-authorization case where SSID is initially unavailable but a later read succeeds. The current behavior therefore conflates an authorization/visibility condition with a genuine empty scan. +- Confirmed a second Windows-specific gap remains plausible: `WlanScan` is asynchronous, the implementation waits a fixed four seconds and reads the available-network list once, while Microsoft documents that the driver may flush the prior list and recommends scan-completion notification or timeout. The physical report is consistent with stale/late scan data but does not distinguish it from SSID/security/connectability filtering. +- Applied a narrow macOS-only repair. The CoreWLAN worker now performs exactly one delayed 250 ms rescan when the raw result is empty or every returned network has an unavailable SSID. A recovered open candidate continues through the unchanged Module filter; two genuinely empty scans still return an empty list; and a second non-empty scan with no readable SSIDs returns the existing fixed `permission_denied` result instead of the misleading empty state. +- The fix keeps CoreWLAN/Objective-C work on the existing worker thread and preserves the open-only, printable `Xiaozhi-*`, opaque-candidate, exact-current-SSID, Host DTO, Renderer, manual-fallback, and firmware-zero-change contracts. No SSID or native diagnostic was added to logs or error payloads. + +## Verification + +- `pnpm vitest run tests/unit/robot-hotspot-module.test.ts`: PASS, 1 file / 10 tests. +- Temporary real-Windows aggregate probe through `createWindowsRobotHotspotAdapter()` and `createRobotHotspotModule('windows', adapter)`: PASS as a diagnostic, observing `openConnectableCount=1`, exact/case-insensitive `Xiaozhi-` count `0`, and projected count `0`; no SSID/BSSID/native identifier was printed. The temporary test file was deleted. +- Read-only firmware inspection: HEAD `0449e51`; `WifiBoard` sets `ssid_prefix="Xiaozhi"`, the pinned component source generates `Xiaozhi-` plus four uppercase hex digits and configures `WIFI_AUTH_OPEN`; no repository file was modified. +- Microsoft `WlanScan` and Apple CoreWLAN security semantics were checked against official documentation. macOS `CWSecurity.none` / value `0` correctly means open-system authentication. +- The same focused baseline was rerun after the macOS/prefix clarification and remained PASS, 1 file / 10 tests, before the new regression was introduced. +- TDD RED: the four new macOS projection/retry cases initially failed while the existing 10 cases passed. +- `pnpm exec vitest run tests/unit/robot-hotspot-module.test.ts --reporter=dot`: PASS, 1 file / 14 tests. +- `pnpm run typecheck`: PASS. +- `pnpm exec eslint electron/robot-hotspot/macos.ts tests/unit/robot-hotspot-module.test.ts`: PASS. +- `pnpm run build:vite`: PASS for Renderer, Main, and Preload; only the existing mixed-import and chunk-size warnings remained. The emitted macOS Main chunk retains the worker branch, one 250 ms `Atomics.wait`, bounded retry, and fixed `permission_denied` mapping. +- `git diff --check`: PASS. + +## Follow-ups + +- Validate on a signed macOS package with Location access granted: revoke/regrant Location permission, enter Guided Binding, and confirm the physical `Xiaozhi-*` hotspot is listed and connects. This Windows host cannot execute CoreWLAN or prove physical discovery/association. +- If the signed package still reports `permission_denied`, inspect the actual built app's Info.plist/TCC authorization and signing entitlements on macOS before adding capabilities. The repository already supplies both macOS location usage-description keys; Apple documentation does not establish the iOS-oriented Wi-Fi Information entitlement as a CoreWLAN scan requirement, so this task does not add speculative signing capabilities. + +## Promotion Candidates + +- None. The current result is task-scoped diagnostic evidence; no product behavior, accepted decision, or canonical integrated fact changed. diff --git a/electron/robot-hotspot/macos.ts b/electron/robot-hotspot/macos.ts index 1419cb4..bfa4be6 100644 --- a/electron/robot-hotspot/macos.ts +++ b/electron/robot-hotspot/macos.ts @@ -10,6 +10,7 @@ const LOCATION_AUTHORIZED_ALWAYS = 3; const LOCATION_AUTHORIZED_WHEN_IN_USE = 4; const CORE_WLAN_PERMISSION_DENIED = -3930; const CORE_WLAN_UNSUPPORTED = -3903; +const SCAN_RETRY_DELAY_MS = 250; type StableReason = 'unsupported' | 'permission_denied' | 'scan_failed' | 'connect_failed'; type ObjcId = unknown; @@ -21,6 +22,36 @@ interface WorkerCandidate { open: boolean; } +export interface MacosScanNetwork { + ssid: string | null; + rssi: number; + open: boolean; +} + +export function scanMacosCandidatesWithRetry( + readNetworks: () => MacosScanNetwork[], + currentSsid: string | null, + waitBeforeRetry: () => void, +): WorkerCandidate[] { + let networks = readNetworks(); + if (networks.length === 0 || networks.every((network) => !network.ssid)) { + waitBeforeRetry(); + networks = readNetworks(); + } + if (networks.length > 0 && networks.every((network) => !network.ssid)) { + throw new RobotHotspotAdapterError('permission_denied'); + } + return networks.flatMap((network): WorkerCandidate[] => { + if (!network.open || !network.ssid) return []; + return [{ + ssid: network.ssid, + signalPercent: Math.max(0, Math.min(100, Math.round((network.rssi + 100) * 2))), + connected: currentSsid === network.ssid, + open: true, + }]; + }); +} + type WorkerRequest = { id: number; operation: 'scan' } | { id: number; operation: 'connect'; ssid: string }; type WorkerResponse = { id: number; ok: true; result: WorkerCandidate[] | { ssid: string } } | { id: number; ok: false; reason: StableReason }; @@ -219,13 +250,16 @@ async function runCoreWlanWorker(): Promise { return withPool(() => { const wifi = wifiInterface('scan'); const current = stringValue(sendId(wifi, selectors.ssid)); - return scanNetworks('scan').flatMap((network): WorkerCandidate[] => { - if (!sendSupportsSecurity(network, selectors.supportsSecurity, 0)) return []; - const ssid = stringValue(sendId(network, selectors.ssid)); - if (!ssid) return []; - const rssi = Number(sendLong(network, selectors.rssiValue)); - return [{ ssid, signalPercent: Math.max(0, Math.min(100, Math.round((rssi + 100) * 2))), connected: current === ssid, open: true }]; - }); + const readNetworks = (): MacosScanNetwork[] => scanNetworks('scan').map((network) => ({ + ssid: stringValue(sendId(network, selectors.ssid)), + rssi: Number(sendLong(network, selectors.rssiValue)), + open: sendSupportsSecurity(network, selectors.supportsSecurity, 0), + })); + return scanMacosCandidatesWithRetry( + readNetworks, + current, + () => { Atomics.wait(pollSleep, 0, 0, SCAN_RETRY_DELAY_MS); }, + ); }); } diff --git a/tests/unit/robot-hotspot-module.test.ts b/tests/unit/robot-hotspot-module.test.ts index ce70786..779f4e3 100644 --- a/tests/unit/robot-hotspot-module.test.ts +++ b/tests/unit/robot-hotspot-module.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it, vi } from 'vitest'; import type { RobotHotspotAdapter, RobotHotspotAdapterCandidate } from '@electron/robot-hotspot/adapter'; import { RobotHotspotError, createRobotHotspotModule } from '@electron/robot-hotspot'; -import { MacosWorkerController, requestMacosWorker } from '@electron/robot-hotspot/macos'; +import { MacosWorkerController, requestMacosWorker, scanMacosCandidatesWithRetry } from '@electron/robot-hotspot/macos'; import type { MacosWorkerLike } from '@electron/robot-hotspot/macos'; function candidate(ssid: string, signalPercent: number, overrides: Partial = {}): RobotHotspotAdapterCandidate { @@ -22,6 +22,62 @@ async function expectCode(promise: Promise, code: string): Promise { + it('retries once when the first macOS scan hides every SSID and returns the recovered open hotspot', () => { + const readNetworks = vi.fn() + .mockReturnValueOnce([ + { ssid: null, rssi: -80, open: true }, + { ssid: '', rssi: -60, open: true }, + ]) + .mockReturnValueOnce([ + { ssid: 'Xiaozhi-7A2B', rssi: -58, open: true }, + { ssid: 'Private-Network', rssi: -42, open: false }, + ]); + const waitBeforeRetry = vi.fn(); + + expect(scanMacosCandidatesWithRetry(readNetworks, 'Xiaozhi-7A2B', waitBeforeRetry)).toEqual([ + { ssid: 'Xiaozhi-7A2B', signalPercent: 84, connected: true, open: true }, + ]); + expect(readNetworks).toHaveBeenCalledTimes(2); + expect(waitBeforeRetry).toHaveBeenCalledOnce(); + }); + + it('reports permission denied when both macOS scans find networks but expose no SSIDs', () => { + const readNetworks = vi.fn() + .mockReturnValueOnce([{ ssid: null, rssi: -70, open: true }]) + .mockReturnValueOnce([{ ssid: '', rssi: -65, open: true }]); + + expect(() => scanMacosCandidatesWithRetry(readNetworks, null, vi.fn())).toThrowError( + expect.objectContaining({ reason: 'permission_denied' }), + ); + expect(readNetworks).toHaveBeenCalledTimes(2); + }); + + it('bounds an empty macOS scan retry and keeps an empty result empty', () => { + const readNetworks = vi.fn().mockReturnValue([]); + const waitBeforeRetry = vi.fn(); + + expect(scanMacosCandidatesWithRetry(readNetworks, null, waitBeforeRetry)).toEqual([]); + expect(readNetworks).toHaveBeenCalledTimes(2); + expect(waitBeforeRetry).toHaveBeenCalledOnce(); + }); + + it('does not retry a readable macOS scan and filters secured networks while clamping RSSI', () => { + const readNetworks = vi.fn().mockReturnValue([ + { ssid: 'Xiaozhi-weak', rssi: -120, open: true }, + { ssid: 'Xiaozhi-strong', rssi: -20, open: true }, + { ssid: 'Xiaozhi-secured', rssi: -50, open: false }, + { ssid: null, rssi: -40, open: true }, + ]); + const waitBeforeRetry = vi.fn(); + + expect(scanMacosCandidatesWithRetry(readNetworks, 'Xiaozhi-strong', waitBeforeRetry)).toEqual([ + { ssid: 'Xiaozhi-weak', signalPercent: 0, connected: false, open: true }, + { ssid: 'Xiaozhi-strong', signalPercent: 100, connected: true, open: true }, + ]); + expect(readNetworks).toHaveBeenCalledOnce(); + expect(waitBeforeRetry).not.toHaveBeenCalled(); + }); + it('terminates a hanging macOS native worker when the request is aborted', async () => { const worker = { postMessage: vi.fn(),