wangxuming/makelore
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
55e61b7d8f9caccdad54dc9a42092fc7960fb394
makelore/.project-docs/30-worklog/tasks/20260817-robot-hotspot-scan-missing-4c7e91.md
T

11 KiB
Raw Blame History

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: 7e8d9e3811
  • 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.
Reference in new issue View Git Blame Copy Permalink