wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix: retry macOS robot hotspot scans

Browse Source
This commit is contained in:
brother7
2026-08-17 20:43:24 +08:00
parent 7e8d9e3811
commit 55e61b7d8f
3 changed files with 201 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
.project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md Normal file
View File

@@ -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.