wangxuming/makelore
1
0 Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity
Files
c1326a298026a697181c822cdd3062cc96c3aa2d
makelore/.project-docs/30-worklog/tasks/20260816-robot-hotspot-connect-5e7a91.md
T

11 KiB
Raw Blame History

Task: Implement in-app Robot hotspot scan and connection on Windows and macOS

Identity

  • Task ID: 20260816-robot-hotspot-connect-5e7a91
  • Mode: Feature
  • Branch: codex/20260816-robot-hotspot-connect-5e7a91-robot-hotspot-connect
  • Worktree: D:\Datas\OthersProjects\makelore-robot-hotspot-connect-5e7a91
  • Base commit: abecd5f344
  • Owner: codex-root
  • Status: Complete

Scope

  • Replace the manual connect_device_ap step with in-dialog discovery, explicit selection, connection, and verification of nearby open Xiaozhi-* Robot hotspots on both Windows and macOS.
  • Add one Main-owned Robot hotspot Module with Windows and macOS Adapters, a strict typed Host interface, safe Renderer projection, permission/error fallbacks, and focused tests.
  • Keep the current firmware, fixed portal, Wi-Fi credential entry, Activation, six-digit Binding, and exact NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0 rollback unchanged.
  • Add task-scoped decision/evidence records and promotion candidates; do not write accepted ADRs or canonical shared memory from feature mode.

Intent And Constraints

  • The user explicitly confirmed simultaneous Windows and macOS delivery, superseding only ADR-002's manual operating-system hotspot-selection step.
  • Renderer uses the existing typed Host seam and never invokes native networking, arbitrary IPC, shell commands, interface names, SSIDs, BSSIDs, profiles, or URLs directly.
  • Renderer receives bounded Xiaozhi-* candidate projections with short-lived opaque candidate IDs. Dialog reset immediately drops all Renderer references; Main invalidates the snapshot on a later scan/explicit clear, after the 60-second TTL, or on process restart.
  • Only open Robot hotspots may be connected. Makelore does not accept or retain hotspot/home-network passwords and does not become a general Wi-Fi manager.
  • Discovery and connection are convenience signals, not authenticated Robot identity, account claim, Binding, or online readiness.
  • Native operations are bounded, non-overlapping, locally handled before Works credentials/upstream access, and fail safely to the existing system-settings/manual path.
  • Windows and macOS use separate platform Adapters behind the same deep Module interface; tests replace those Adapters rather than exposing platform details through the Renderer contract.

Project Context Loaded

Task context:

  • Task ID: 20260816-robot-hotspot-connect-5e7a91
  • Mode: Feature
  • Branch: codex/20260816-robot-hotspot-connect-5e7a91-robot-hotspot-connect
  • Worktree: D:\Datas\OthersProjects\makelore-robot-hotspot-connect-5e7a91
  • Base commit: abecd5f34485ab467e5f032c618083d88e34b74d
  • Other active local tasks: all owners returned by task_context.py status --json were checked through their task-record Scope, Intent And Constraints, and Promotion Candidates only.
  • Overlap or semantic-conflict assessment: completed Robot onboarding/default-on tasks overlap semantically but do not own this worktree or an in-app Wi-Fi Module. ADR-002 conflicts with automatic discovery, but the user has explicitly confirmed the superseding Windows+macOS product decision. No unresolved peer decision blocks implementation.

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
  • .project-docs/30-worklog/tasks/20260816-robot-hotspot-connect-5e7a91.md
  • .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-002-robot-guided-hotspot-binding-v1.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/40-domain/glossary.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 understanding:

  • Project goal: cross-platform Electron product with Robot as the single hardware module and Main ownership of native/system integration.
  • Current integrated focus: Guided Hotspot Binding is default-on, firmware-zero-change, manual at the OS hotspot step, then fixed portal and six-digit Binding.
  • Active task scope: move only Robot hotspot discovery/selection/connection into the dialog for Windows and macOS.
  • Active constraints: no firmware or cloud-contract change; no Wi-Fi credentials; no arbitrary native input; preserve safe fallback and exact rollback.
  • Decisions affecting this task: ADR-002 is accepted and must be superseded only at connect_device_ap; a new decision proposal is required because public workflow and architecture change.
  • Evidence, reflections, or commitments affecting this task: exact shipped firmware, physical-device flow, native opener, and full end-to-end evidence remain release gates; local tests cannot claim physical compatibility.
  • Files or modules likely involved: electron/services/robot-hotspot-*, electron/api/routes/ai-hardware.ts, src/lib/ai-hardware.ts, src/pages/AiHardware/index.tsx, focused Robot tests, packaging/native assets, task-scoped proposal/evidence.
  • Unknowns, stale docs, or conflicts: project-positioning remains a placeholder; Windows and macOS physical permission/association behavior cannot be fully verified from the Windows development host; accepted canonical docs still describe manual OS selection until Integration Gate.

Gate result:

  • Passed. User confirmation resolves the decision change; implementation remains isolated and preserves all unaffected ADR-002 rules.

Outcome

  • Decision proposal created at .project-docs/10-decisions/proposals/20260816-robot-hotspot-connect-5e7a91__cross-platform-robot-hotspot-connection.md.
  • Added a Main-owned Robot Hotspot Module with bounded opaque candidate snapshots, stable safe errors, exclusive native operations, open Xiaozhi-* filtering, strongest-SSID deduplication, and exact current-SSID verification.
  • Added real Windows wlanapi.dll and macOS CoreWLAN/CoreLocation Adapters through lazily loaded Koffi 2.16.3; neither Adapter uses a shell, CLI, persistent Windows Wi-Fi profile, arbitrary Renderer SSID, or firmware change.
  • macOS CoreWLAN scan, association, and exact-SSID verification run in a dedicated abortable worker that owns all Objective-C objects. Foreground CoreLocation authorization remains in Main; an 8/12-second Module deadline can terminate a hung worker without freezing Electron Main. A deduplicated termination barrier prevents a replacement operation from creating or messaging another worker until the previous worker has fully exited.
  • Added strict local Host scan/connect routes and typed Renderer projections. Both routes remain behind Host authentication and the existing guidedHotspotBinding capability, and finish before Works token/upstream access.
  • Replaced the manual-only hotspot step with automatic in-dialog scan, explicit selection/connection, signal and connected-state display, safe recovery messages, rescan, async-session guards, and a retained system-Wi-Fi/manual fallback.
  • Added macOS location usage descriptions and synchronized README.md with the Windows/macOS product behavior.
  • Integration runtime smoke found and fixed CommonJS dynamic-import interop: Electron exposes Koffi through the default export. The corrected adapters now load under Electron 40.10.6.

Verification

  • pnpm vitest run tests/unit/robot-hotspot-module.test.ts tests/unit/ai-hardware-routes.test.ts tests/unit/ai-hardware-api.test.ts tests/unit/ai-hardware-page.test.tsx: PASS, 4 files / 132 tests.
  • pnpm test: PASS on the latest tree, 157 files / 1796 tests.
  • pnpm run typecheck: PASS.
  • pnpm run lint:check: PASS with 6 pre-existing warnings and no errors.
  • pnpm run build:vite: PASS for Renderer, Electron Main, and Preload; existing chunk-size warnings only.
  • Electron 40.10.6 runtime probe: Koffi 2.16.3 loaded, wlanapi.dll loaded, and the WLAN function definition resolved.
  • Windows native scan probe: WlanOpenHandle and interface enumeration succeeded; this machine's Windows location setting denied WlanScan with native code 5, which the public Module correctly projected as permission_denied. No SSIDs were printed or retained by the probe.
  • Firmware repository D:\Datas\HardwareProjects\xiaozhi-esp32-firmware remains clean at 0449e51dec7e0fad3d4567a7bcfcd354efbe1a87.
  • git diff --check: PASS; line-ending notices only.
  • Final read-only Sol review: PASS on both Standards and Spec axes with no P0-P3 findings.

Follow-ups

  • Run signed packaged macOS x64 and arm64 smoke for location authorization, CoreWLAN scan, open-hotspot association, current SSID verification, and Koffi load. This cannot be proven from the Windows development host.
  • Run a Windows physical Robot smoke with location/Wi-Fi access enabled, including multiple Robot candidates and verified connection to the fixed Portal flow.
  • Confirm on signed packaged macOS that the bundled Worker(__filename) dynamic Main chunk loads from ASAR and Koffi is worker-thread compatible on both x64 and arm64; the build preserves the worker self-entry, but the Windows host cannot execute it.
  • Windows waits a bounded four seconds for scan refresh rather than registering WLAN notifications; revisit notification-based completion only if physical evidence shows stale/slow scan results.

Promotion Candidates

  • Target canonical documents: 10-decisions/decision-index.md, a new accepted ADR following ADR-002, 20-architecture/system-overview.md, 20-architecture/module-map.md, 20-architecture/data-flow.md, 30-worklog/current-state.md, 40-domain/business-rules.md, 40-domain/glossary.md, and 50-evidence/evidence-index.md after platform evidence exists.
  • Proposal: promote .project-docs/10-decisions/proposals/20260816-robot-hotspot-connect-5e7a91__cross-platform-robot-hotspot-connection.md; it supersedes only ADR-002's manual OS hotspot-selection step and preserves the rest of ADR-002.
  • Evidence: implementation/test/build results in this task record; Windows Electron/Koffi/WLAN permission-path smoke; macOS and physical Robot evidence remain outstanding and must not be inferred.
  • Future impact: support, security copy, packaging, notarization, and hardware acceptance must distinguish unauthenticated hotspot convenience from Robot identity/Binding/online readiness.
  • Semantic conflict: accepted ADR-002 still states OS-level manual hotspot selection and must be updated/superseded during Integration Gate. No other accepted decision is intentionally reversed.
  • Human confirmation: not required for this product-direction promotion because the user explicitly confirmed in this task that both Windows and macOS should connect from the page. Human or release-owner confirmation is still required before treating incomplete macOS/physical smoke as accepted release evidence.
Reference in new issue View Git Blame Copy Permalink