merge: integrate guided hotspot binding v1

This commit is contained in:
2026-08-16 14:55:29 +08:00
11 changed files with 836 additions and 30 deletions

View File

@@ -4,7 +4,7 @@
Accepted
Implementation status: planned; the capability must remain disabled by default until the pilot release gates pass.
Implementation status: implemented; the capability remains disabled by default until all pilot release gates pass.
## Date

View File

@@ -5,7 +5,7 @@
| ID | Decision | Status | Date | Applies To | Detail |
|---|---|---|---|---|---|
| ADR-001 | AI 绘画采用 Workspace / Conversation / Task 分层状态与服务端持久 Conversation Session | Accepted | 2026-08-11 | AI 绘画客户端、Main 适配器、Works Square API | `adr-001-ai-design-conversation-ownership.md` |
| ADR-002 | Robot V1 采用 Main 门控的引导式热点配网并衔接现有六位 Binding | Accepted / planned, default off | 2026-08-16 | Robot Renderer、Host API、Electron Main、现有固件热点入口 | `adr-002-robot-guided-hotspot-binding-v1.md` |
| ADR-002 | Robot V1 采用 Main 门控的引导式热点配网并衔接现有六位 Binding | Accepted / implemented, default off | 2026-08-16 | Robot Renderer、Host API、Electron Main、现有固件热点入口 | `adr-002-robot-guided-hotspot-binding-v1.md` |
## Superseded Decisions

View File

@@ -24,7 +24,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
| Robot Workspace | Account-scoped agent configuration, device activation/binding, assignment, and credential-recovery UI | Renderer receives only safe Works Square projections. Configuration choices come from the USER-scoped safe catalog; unavailable current values remain editable without exposing provider credentials or configuration internals. |
| AI Hardware Main Route | Fixed `/api/works/ai-hardware` Host API to Works Square proxy | Main owns Bearer auth, stable operation IDs, bounded retry, ETag/If-Match, request/response limits, error redaction, and the fixed no-store configuration-catalog proxy. Versioned responses accept only canonical strong or weak numeric ETags that equal the DTO revision; mutations always emit strong `If-Match`. It never forwards Renderer authorization headers. |
| Guided Hotspot Binding V1 | Planned, default-off Renderer journey over the current firmware Hotspot portal and six-digit Binding | System Wi-Fi selection and portal credential entry remain user/firmware-owned. Main exposes only a boolean capability and a fixed system-browser open action; no BLE, automatic claim, or firmware change is part of V1. |
| Guided Hotspot Binding V1 | Implemented, default-off Renderer journey over the current firmware Hotspot portal and six-digit Binding | System Wi-Fi selection and portal credential entry remain user/firmware-owned. Main exposes only a boolean capability and a fixed system-browser open action; no BLE, automatic claim, or firmware change is part of V1. |
## Important Boundaries
@@ -33,7 +33,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
- Robot model, language, and voice choices are dynamically projected from the Xiaozhi USER catalog through Works Square and Electron Main; the catalog is bounded, account-scoped, and `private, no-store` at each public hop.
- One local account maps to one server-side Xiaozhi account binding. Agents and devices are resources beneath that account binding, not separate Xiaozhi users.
- Robot/Canvas/module-selection routes must not initialize AI Programming projects or providers.
- Guided Hotspot Binding is an accepted but not-yet-implemented V1 boundary. Its Main-owned capability remains false by default; disabled/public builds keep the current direct six-digit Binding UI.
- Guided Hotspot Binding is implemented behind a Main-owned capability that remains false by default; disabled/public builds keep the current direct six-digit Binding UI. The guided state is process-local, opener failures expose only the same fixed address for manual copy, and Binding conflicts refresh the safe account overview.
- The fixed portal action may open only `http://192.168.4.1/` in the system browser and must not acquire cloud credentials or call Works Square. Renderer never supplies a portal URL and never handles Wi-Fi credentials.
- A successful Binding means account ownership was established; it is not evidence that the Robot is currently online or protocol-ready.

View File

@@ -4,7 +4,7 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
## Integrated Through
- `14afe4a`: accepted design for a firmware-zero-change, default-off Guided Hotspot Binding V1; implementation is not yet present on `main`.
- `b7a1590` / `14afe4a`: implemented and accepted firmware-zero-change Guided Hotspot Binding V1 with a Main-owned default-off capability, fixed portal action, in-memory Renderer journey, and existing six-digit Binding contract.
- `ea75b06`: Robot configuration reads accept canonical weak numeric response ETags introduced by public response compression only when the numeric revision exactly matches the strictly projected DTO; configuration and assignment writes continue to emit strong `If-Match`.
- `fe55dee`: Robot configuration editing uses the safe Xiaozhi/Works catalog for model, language, and voice selections, with bounded sliders for TTS numeric controls and no-store catalog responses.
- `fd9b5b46a913c515e94e4e26f185d43866c2581f` / `7a811590c4943b7b1b7ea5f3b4d3ce3ce05622a5`: Codex-style persistent AI Programming context-compaction timeline, run-lifecycle separation, polling-idle completion, and cold-hydration hardening.
@@ -34,7 +34,7 @@ Updater 仍由 Electron Main 选择目标 feed、记录原始诊断并保持失
## Recently Completed
- 2026-08-16: Accepted ADR-002 for a default-off Robot onboarding V1 that guides the existing firmware Hotspot portal and then reuses six-digit Binding. This is an architecture decision only: no product behavior or firmware was changed, and the capability must remain off until implementation and pilot gates pass.
- 2026-08-16: Implemented ADR-002's Robot onboarding V1 in Makelore without changing firmware. Main owns a default-off capability and the fixed portal opener; Renderer guides manual hotspot/Wi-Fi handoff and reuses six-digit Binding, clears secrets/retry identity safely, and does not equate Binding with online readiness. Pilot enablement still requires the documented firmware, issuer/validator, gate-on Electron, and physical-device evidence.
- 2026-08-15: Corrected the deployed Robot configuration-read contract after the compressed public Works response was observed with `ETag: W/\"0\"` and matching numeric `config_revision: 0`. Electron Main now accepts only canonical strong or weak numeric response tags, still requires exact DTO revision equality, and always sends strong `If-Match` for mutations. No production client rollout is claimed.
- 2026-08-16: Integrated selection-oriented Robot configuration editing. Enabled model and caller-safe voice metadata now flows from Xiaozhi through Works Square and Electron Main without exposing provider secrets; unavailable current values and `clear_fields` semantics remain intact. Production deployment of the matching service endpoints is still required.
- 2026-08-15:AI 编程上下文压缩改为 Codex 风格的会话内时间线事件;手动与自动压缩原位展示并持久保留,历史回放去重且状态只允许从 running 单调进入 completed,压缩完成不再冒充整个 run idle。
@@ -57,10 +57,9 @@ Updater 仍由 Electron Main 选择目标 feed、记录原始诊断并保持失
## Next Recommended Steps
1. 在独立 feature worktree 实现 ADR-002 的 default-off capability、固定 portal-open Host action、Renderer 引导状态机和聚焦测试,不修改固件。
2. 核对指定固件镜像与六位码发行/消费契约,完成 Electron E2E 和真机 smoke 后再决定是否只为内部试点开启 capability。
3. 成组核对客户端 source+built+contract 上传 → 服务端逐字节校验 → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。
4. 配置真实生产环境,分别执行“小游戏/小程序创建 → 客户端本地构建与同字节预检 → 提交 → 服务端合同/摘要校验与不可变 Release 固化 → 运营批准 → App 播放”。
1. 核对指定固件镜像与六位码发行/消费契约,补齐 capability-on 原生 opener Electron E2E 和真机 smoke 后,再决定是否只为内部试点开启 Guided Hotspot Binding。
2. 成组核对客户端 source+built+contract 上传 → 服务端逐字节校验 → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。
3. 配置真实生产环境,分别执行“小游戏/小程序创建 → 客户端本地构建与同字节预检 → 提交 → 服务端合同/摘要校验与不可变 Release 固化 → 运营批准 → App 播放”。
## Open Questions / Blockers
@@ -87,4 +86,4 @@ Updater 仍由 Electron Main 选择目标 feed、记录原始诊断并保持失
## Last Updated
2026-08-15
2026-08-16

View File

@@ -12,6 +12,7 @@
## Scope
- On 2026-08-16, resume the existing Integration owner to merge reviewed Robot Guided Hotspot Binding implementation commit `b7a1590` into local `main`, reconcile canonical memory from planned to implemented/default-off, and keep firmware edits, capability enablement, and remote push outside this resumption.
- On 2026-08-16, resume the existing Integration owner to accept reviewed Robot Guided Hotspot Binding V1 design commit `14afe4a`, promote only its confirmed minimal-firmware decision into canonical memory, and keep product implementation, firmware changes, and remote push outside this integration step.
- On 2026-08-16, resume the existing Integration owner to merge reviewed Robot configuration-catalog/editor source `fe55dee` into local `main`, promote the accepted dynamic catalog boundary, and keep remote push outside this resumption.
- On 2026-08-15, resume the existing Integration owner to merge reviewed Robot configuration-schema fix `ea75b06` into local `main`, accepting canonical weak numeric response ETags produced by the deployed compression layer while keeping strong `If-Match` writes.
@@ -44,6 +45,7 @@
- The 2026-08-14 user request authorizes the local `main` merge only. It does not expand this resumption into a remote push; the existing authentication blocker remains a separate follow-up.
- The 2026-08-15 context-compaction request likewise authorizes only a local `main` merge. It does not authorize a remote push or changing the existing OpenCode/model compaction threshold.
- The 2026-08-16 Robot onboarding confirmation accepts the current-firmware Hotspot + six-digit Binding V1. It does not authorize firmware edits, claim automatic nearby discovery, enable the pilot capability by default, or revive the unready Security 2/automatic-claim proposal as a V1 contract.
- The reviewed implementation may move canonical truth from planned to present, but release guidance must retain the exact shipped-firmware, issuer/validator, gate-on Electron, and physical-device smoke prerequisites. The source task record remains read-only and must stay on its feature history.
## Project Context Loaded
@@ -125,8 +127,23 @@ Gate result:
- The source changes only Electron Main response-revision parsing and its focused route tests. It still requires DTO/revision equality and emits only strong `If-Match` for writes; no authentication, idempotency, response-bound, or redaction boundary changes.
- Gate result: Passed for the local Robot configuration-schema merge. Remote push remains outside this resumption.
### 2026-08-16 Robot Guided Hotspot Binding Implementation Integration Resume
- Reused the existing Integration owner because it exclusively owns clean local `main` at `54443232dd6a07dc1f3df5b33df00f665540497a`; `task_context.py touch` refreshed the reservation and registry doctor passed.
- Verified source task `20260816-guided-hotspot-binding-7c4d2e` is `ready_for_integration`, source commit `b7a1590ca132c971ffff177cb1e2aa47f96358cf` is a direct descendant of current `main`, its worktree is clean, and independent Sol re-review returned PASS with no P0-P3 findings.
- Read the source task outcome, verification, follow-ups, and promotion candidate against ADR-002 and current canonical Robot memory. The implementation preserves the accepted zero-firmware/default-off boundary; its only promotion candidate remains deferred until release-gate evidence exists.
- No registered peer owns `main` or contradicts this implementation. The prior Security 2/automatic-claim proposal remains a deferred future direction and is not part of this merge.
- Gate result: Passed for the local implementation merge. Firmware changes, capability enablement, physical acceptance, and remote push remain outside this resumption.
## Plan
### 2026-08-16 Robot Guided Hotspot Binding Implementation Integration Plan
1. Merge reviewed source commit `b7a1590` into local `main` with a normal no-ff merge, preserve the source parent, and exclude the source-owned task record from the final main tree.
2. Update only canonical statements that still say the accepted V1 is planned/not implemented; record `b7a1590` under `Integrated Through` while retaining default-off and release-gate wording.
3. Re-run the 90 focused tests, full unit suite, typecheck, scoped lint, production build, Electron Robot navigation smoke, project-document gates, and whitespace/topology checks on the merged tree.
4. Obtain an independent read-only Sol PASS/FAIL integration review, commit the verified no-ff merge, and leave firmware, capability enablement, physical acceptance, and remote push untouched.
### 2026-08-16 Robot Guided Hotspot Binding V1 Decision Integration Plan
1. Verify source commit `14afe4a`, its independent PASS reviews, the existing Robot implementation facts, and explicit human acceptance of the minimal-firmware V1.
@@ -171,6 +188,10 @@ Gate result:
## Outcome
- On 2026-08-16, started a normal `--no-ff --no-commit` merge of reviewed Guided Hotspot Binding source `b7a1590`; Git reported no textual conflicts. The source task record remains reachable on the source commit/feature branch and is excluded from the local `main` result.
- Integrated the default-off Main capability and strict local Host actions, fixed system-browser portal ownership, in-memory Renderer guided/direct Binding journey, safe conflict/retry/secret cleanup, and Bound-without-online semantics. No firmware file, BLE/Wi-Fi discovery, cloud claim route, or capability enablement was added.
- Reconciled canonical current state, system overview, and decision index from planned/not implemented to implemented/default off. Release gates remain exact firmware and issuer/validator verification, gate-on native-opener Electron coverage, and physical-device smoke.
- Final no-ff merge topology is prepared with first parent `54443232dd6a07dc1f3df5b33df00f665540497a` and reviewed source second parent `b7a1590ca132c971ffff177cb1e2aa47f96358cf`. This resumption is complete locally; the long-lived integration task remains blocked only on its separate pre-existing authenticated remote-push scope.
- Accepted source design commit `14afe4a` as ADR-002: V1 guides the user through the current firmware Hotspot portal and then reuses the existing six-digit Binding facade. The former Security 2/automatic-claim design remains deferred rather than silently mixed into V1.
- Promoted a narrow planned interface: Main-owned `guidedHotspotBinding` default false, fixed system-browser portal action for `http://192.168.4.1/`, Renderer-only guidance state, no Wi-Fi credential handling, and no claim that `bound` means online/ready.
- Kept implementation truth explicit: this integration step changes canonical documents only. Product behavior and firmware remain unchanged; pilot enablement is gated on exact shipped-image checks, activation-code contract checks, automated/Electron coverage, and physical-device smoke.
@@ -258,6 +279,13 @@ Gate result:
## Verification
- 2026-08-16 Guided Hotspot source final Sol re-review — `PASS`, no P0-P3 findings after fixed-address copy recovery, conflict/already-bound overview refresh, and complete state-machine/remount coverage were added.
- Staged local-main merge Robot selection — 3 files / 91 tests passed.
- Staged local-main merge `pnpm test` — 156 files / 1755 tests passed.
- Staged local-main merge `pnpm run typecheck`, scoped ESLint, and `pnpm run build:vite` — passed; the production build retains only existing chunk-size and mixed-import warnings.
- Staged local-main merge Electron module-navigation smoke — 2/2 passed, including entry into the Robot route. Gate-on native external-open observation remains an explicit release prerequisite rather than a claimed test.
- Independent staged-merge review initially returned `FAIL` with one P2 and two P3 findings: ADR implementation status remained planned, current-state's update date was stale, and Escape/overlay dismissal during a pending native opener could let an old promise affect a reopened wizard. The documents now state implemented/default-off with the current date; portal-opening sessions reject all close attempts, with an Escape/remount regression test. Focused/full/typecheck/lint/build checks were rerun before re-review.
- Independent staged-merge re-review — `PASS`, no P0-P3 findings. It confirmed all three findings closed, source-task-record exclusion, exact merge parents, default-off/release-gate truth, and no old opener promise can affect a reopened guided session.
- 2026-08-16 ADR-002 integration `check_project_docs.py`, task-aware `check_doc_drift.py`, and `git diff --check` — passed in the Integration owner worktree.
- Independent ADR-002 canonical integration review initially returned `FAIL` on two P2 documentation inaccuracies: a shortened Host wire envelope and an overclaim about deployed firmware. Both were corrected; final re-review returned `PASS` with no P0-P3 findings.
- The final review confirmed only canonical documents and this integration task record changed; no product source, source-task record, or firmware file was modified in this acceptance step.
@@ -328,7 +356,7 @@ Gate result:
## Follow-ups
- Implement ADR-002 from a new feature worktree with the capability still false by default; do not touch `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware`.
- Keep `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING` unset/default false in production; do not touch `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware` for this V1.
- Before any pilot enablement, identify the exact shipped Robot component/firmware image, verify that the deployed issuer produces six ASCII digits with compatible freshness/consumption semantics, and pass a real device smoke through the Host API/Electron flow.
- Deploy matching Xiaozhi and Works Square catalog endpoints before releasing this client; otherwise the editor preserves current values but cannot populate dynamic choices.
- The Robot integration is complete on local `main`. Production still requires matching Works Square/Xiaozhi deployment, feature configuration, credentials, and a real one-time activation-code smoke.
@@ -347,5 +375,6 @@ Gate result:
## Promotion Candidates
- The implementation truth from `b7a1590` was promoted from planned to implemented/default-off in canonical current state, system overview, and ADR index. Its release-enablement procedure/support matrix candidate remains deferred because the mandatory gate-on Electron and physical/firmware evidence does not yet exist.
- The Guided Hotspot Binding V1 candidate from `14afe4a` was promoted into ADR-002, success criteria, system/module/data-flow architecture, business rules, glossary, and current state. No unresolved candidate remains for this design acceptance.
- The context-compaction source candidate was promoted into current state, module map, data flow, evidence, and upgrade commitments. No unresolved candidate remains for this local merge.