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

feat(robot): connect provisioning hotspots in app

Browse Source
This commit is contained in:
brother7
2026-08-16 20:18:28 +08:00
parent abecd5f344
commit c1326a2980
17 changed files with 1950 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
.project-docs/30-worklog/tasks/20260816-robot-hotspot-connect-5e7a91.md Normal file
View File

@@ -0,0 +1,112 @@
# 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: abecd5f34485ab467e5f032c618083d88e34b74d
- 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.