diff --git a/.project-docs/00-brief/success-criteria.md b/.project-docs/00-brief/success-criteria.md index dc8b3ff..acbb95f 100644 --- a/.project-docs/00-brief/success-criteria.md +++ b/.project-docs/00-brief/success-criteria.md @@ -10,13 +10,15 @@ - Electron 双视口预检必须检查与最终 `built_archive` 相同的内存文件字节；预检失败不得上传，预检成功不得被表述为可信审核凭据。 - 上传协议必须同时携带源码归档、构建归档和严格版本化 artifact contract；服务端独立重算摘要、校验合同并固化不可变 Release。 - Renderer 不得获得发布凭据、归档、临时目录、构建 origin 或任意本地路径；旧客户端和旧 sandbox/browser 任务必须提示升级后重新构建提交。 +- Robot Guided Hotspot Binding 实现必须保持固件零改动、Main-owned default-off capability、固定系统浏览器 portal 和现有六位 Binding facade；Makelore 不得接触 Wi-Fi 凭据，也不得把 Binding 成功等同于在线。 ## Quality Checks - 发布安装包前运行 `pnpm verify:publish-runtime`，并对最终 Windows 产物运行 `pnpm verify:artifact:win`；固定 npm 闭包缺失或版本不符时 fail closed。 - 至少覆盖 release builder/静态产物服务/发布路由/Renderer 状态的聚焦测试、typecheck、scoped lint、Vite 构建和真实 Electron 双视口 production-seam E2E。 - 真实生产发布仍需成组验证服务端合同、不可变 Release、运营审核、CDN/App 播放；客户端本地验证不能替代该整链验收。 +- Robot 试点开启前必须通过聚焦 Renderer/Main 测试、真实 Host API Electron E2E、指定固件镜像核对、六位码发行契约核对与真机 smoke；公共/default 配置保持关闭。 ## Last Reviewed -2026-08-12 +2026-08-16 diff --git a/.project-docs/10-decisions/adr-002-robot-guided-hotspot-binding-v1.md b/.project-docs/10-decisions/adr-002-robot-guided-hotspot-binding-v1.md new file mode 100644 index 0000000..22ed329 --- /dev/null +++ b/.project-docs/10-decisions/adr-002-robot-guided-hotspot-binding-v1.md @@ -0,0 +1,74 @@ +# ADR-002: Robot V1 采用引导式热点配网并衔接六位绑定 + +## Status + +Accepted + +Implementation status: planned; the capability must remain disabled by default until the pilot release gates pass. + +## Date + +2026-08-16 + +## Supersedes + +- For V1 delivery only, this decision supersedes the proposed Security 2 / automatic-claim onboarding path in task `20260816-device-provisioning-flow-a4d91c`. +- Authenticated BLE provisioning and automatic claim remain a deferred production-security direction, not a current implementation contract. + +## Related + +- Source proposal commit `14afe4a`: `.project-docs/10-decisions/proposals/20260816-minimal-firmware-onboarding-c3e8b7__guided-hotspot-binding-v1.md` +- Current Robot binding implementation: `src/pages/AiHardware/index.tsx`, `src/lib/ai-hardware.ts`, `electron/api/routes/ai-hardware.ts` +- Firmware audit target: `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware` at audited commit `0449e51` + +## Context + +The audited firmware source enters Hotspot provisioning and serves its configuration portal, but the exact resolved component and shipped device image have not yet been verified. Makelore already provides the cloud Binding operation that accepts a six-digit activation code and an Agent. The firmware source does not expose a trusted nearby-device discovery/correlation protocol, and changing it to authenticated BLE plus automatic claim would require firmware, manufacturing identity, cloud, streaming, recovery, and physical-device contracts that are not ready. + +The immediate product goal is therefore to put provisioning guidance inside the existing Robot binding experience while keeping firmware changes at zero. + +## Decision + +V1 is a Renderer-guided, Main-gated workflow: + +`choose_path -> prepare_robot -> connect_device_ap -> configure_wifi -> reconnect_internet -> enter_activation_code -> binding -> bound` + +- Makelore explains how to place the Robot in provisioning mode and connect the computer to the Robot's existing Wi-Fi hotspot through the operating system. +- Electron Main alone may open the fixed system-browser portal `http://192.168.4.1/`; Renderer never supplies or receives an arbitrary portal URL. +- After Wi-Fi provisioning, Makelore instructs the user to reconnect the computer to the internet and obtain the freshly issued six-digit activation code from the Robot. +- Binding continues to use the existing `bindAiHardwareDevice(activationCode, agentId, { operationId })` cloud contract. +- `bound` means account Binding succeeded. It does not prove the Robot is currently online or protocol-ready. + +The guided path is controlled by a Main-owned `guidedHotspotBinding` capability. It is `false` by default. Public builds with the capability disabled retain the existing direct six-digit Binding flow. + +The planned Host API surface is deliberately small: + +- `GET /api/works/ai-hardware/provisioning-capabilities` has no body/query and succeeds with the standard Host envelope `{ success: true, data: { guided_hotspot_binding: boolean } }`. +- `POST /api/works/ai-hardware/provisioning-portal/open` accepts the exact body `{}`, has no query, and succeeds with `{ success: true, data: { opened: true } }`. +- Portal open must check the Main-owned capability before invoking the opener. Disabled access returns logical `403 / AI_HARDWARE_PROVISIONING_DISABLED`; opener failure returns logical `502 / AI_HARDWARE_PORTAL_OPEN_FAILED`. Like existing handled Host API errors, those logical failures use the standard envelope over outer HTTP 200. +- Both operations are local Main actions and must return before acquiring a Works access token or contacting an upstream service. + +## Security And Recovery Rules + +- The current firmware hotspot and portal are open/plain HTTP. V1 is an internal pilot only; product copy must warn the user not to perform the flow in an untrusted public environment. +- Wi-Fi SSID/password entry stays in the firmware portal. Makelore must not collect, log, persist, or proxy Wi-Fi credentials. +- Cancel, back, and application restart never imply that Wi-Fi changes on the Robot were reverted. The user is guided to reconnect and restart provisioning if needed. +- A same-process ambiguous Binding retry reuses the same operation ID. An invalid/expired/consumed activation code clears both code and retained operation ID; the next freshly issued code gets a new operation ID. +- Main must project `ai_hardware_activation_code_invalid` as non-retryable even if an upstream response incorrectly marks it retryable. +- After application restart, Makelore cannot correlate an earlier code or Binding outcome from the current overview DTO. It must not replay the old code or operation ID; the user obtains a fresh code or stops. + +## Release Gates + +The capability may be enabled only after all of the following are evidenced: + +1. The exact shipped Robot component/image is confirmed to use the audited Hotspot portal flow and fixed portal address. +2. The deployed activation issuer emits exactly six ASCII digits accepted by the existing Works Binding validator, with documented freshness and consumption behavior. +3. Focused Renderer/Main route tests, Electron E2E through the real Host API seam, and a physical-device smoke all pass. +4. The public/default configuration remains disabled until the open SoftAP/plain-HTTP risk is explicitly accepted for the intended pilot population. + +## Consequences + +- The first implementation is desktop-only and requires no firmware, BLE, manufacturing, or cloud-contract change. +- V1 cannot truthfully advertise automatic nearby-device discovery or automatic device claim. +- The UI becomes a single coherent onboarding journey while system Wi-Fi selection and firmware portal entry remain explicit user actions. +- A later authenticated BLE/automatic-claim design requires a new accepted ADR and must not silently widen this V1 interface. diff --git a/.project-docs/10-decisions/decision-index.md b/.project-docs/10-decisions/decision-index.md index c84f5fa..d4d5929 100644 --- a/.project-docs/10-decisions/decision-index.md +++ b/.project-docs/10-decisions/decision-index.md @@ -5,6 +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` | ## Superseded Decisions diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index fef482a..bf0a5a9 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -19,6 +19,7 @@ | 设计消息与确认 | 当前 Conversation | Main ↔ 持久 Agent Gateway Session WebSocket → Conversation 快照 | `command.submit`、Run 与设计事件共用连接；传输失败才以同一幂等 ID 回退 REST；结构化业务错误不重试且未知文本由 Main 脱敏；请求和流式结果同时绑定 Workspace + Conversation | | 设计单图来源选择 | 当前 Workspace 已完成图片 / 本地图片 | 现有 Asset 上传或选择 → `attachmentAssetIds` → 当前 Conversation Turn | 图片 Brief 用作图生图参考图；视频 Brief 用作首帧；只提交一个真实 Workspace Asset ID | | 设计任务同步 | 任一 Conversation 的事件流 / Quote REST 对账 | Renderer Workspace 任务列表 | Task 和 Asset 按 Workspace 归并；任务已落库但 Run 失败时恢复可见性，内部对账失败不覆盖新会话错误，切换 Conversation 后仍同步任务但不回写旧会话 | +| Robot 引导式热点配网 V1（计划、默认关闭） | Robot Binding 页面 | 用户进入固件配网模式 → 操作系统连接 Robot 热点 → Main 在系统浏览器打开固定 portal → 用户在 portal 配置 Wi-Fi → 电脑恢复互联网 → 现有六位 Binding | Makelore 不扫描附近设备、不收集 Wi-Fi 密码、不修改固件；`bound` 不等于 online/ready | ## State Ownership @@ -35,6 +36,7 @@ - AI 编程压缩状态由 transcript 中的 `compactionsById` / `compactionOrder` 单一持有。运行中 hydration 保留 manual pending identity 并用 native Part 合并；completed 不得回退为 running。`session.compacted` 不是 run idle，不能据此释放 queued prompt；失败、中止或 runtime generation 变化只清理对应未完成事件。 - Main Host AI proxy 可为固定 OpenCode 重试契约做窄化的内部状态投影：配额耗尽投影为 `402`，明确上游分组饱和的 `429` 投影为终止 `400`，其他 `429` 原样保留；升级 OpenCode 时必须重新验证该契约。 - Main AppUpdater 持有 feed、原始异常、下载和安装状态；设置页只消费状态投影。一次 electron-updater `error` 事件覆盖的并发检查不会在 Renderer 重复发错，但独立的后续检查仍有自己的报告生命周期。 +- Robot V1 引导状态只在 Renderer 当前进程内保存，不持久化 Wi-Fi 凭据、activation code 或 Binding operation ID。相同进程内的模糊 Binding 重试复用 operation ID；无效码或重启后必须取得新码并使用新 operation ID。 ## External Interfaces @@ -44,7 +46,8 @@ - Main-owned electron-updater IPC 与 Works Square 平台/架构稳定 feed；正式安装产物发布不由 Renderer 控制。 - 服务端安全投影后的公共 `play_url`；只接受同源 HTTPS、精确 App 路径和可信版本状态。 - Works Square Workspace/Conversation API、每个 Conversation 的持久 Agent Gateway Session、单次 WebSocket ticket、双向命令/事件帧与幂等 REST 传输回退。 +- 计划中的本机 Robot provisioning capability 与固定 portal-open Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL。 ## Last Updated -2026-08-15 +2026-08-16 diff --git a/.project-docs/20-architecture/module-map.md b/.project-docs/20-architecture/module-map.md index 6d9fd94..9f838b0 100644 --- a/.project-docs/20-architecture/module-map.md +++ b/.project-docs/20-architecture/module-map.md @@ -29,6 +29,9 @@ | `src/stores/image-workspace.ts` | 当前 Workspace/Conversation、项目任务及流式更新状态 | Quote/task 按 Workspace 无 UI 错误副作用地对账；Conversation 写入按 Workspace-load + Conversation-selection generation/revision 防护 | | `src/pages/ImageCanvas/index.tsx` | Conversation 对话、Quote 确认、统一任务列表、新会话入口与单图来源选择器 | 图片 Brief 选择/上传图生图参考图；视频 Brief 绑定首帧；均提交一个 Workspace Asset ID | | `src/components/layout/ImageWorkspaceSidebar.tsx` | Workspace 与近期 Conversation 切换/创建 | 切换会话不清空项目级任务 | +| `src/pages/AiHardware/index.tsx` | Robot 管理、现有六位 Binding，以及计划中的 default-off 引导式热点配网状态机 | 只编排非敏感步骤；不接收 Wi-Fi 密码，不把 `bound` 展示为在线证明 | +| `src/lib/ai-hardware.ts` | Renderer 侧 Robot Host API 类型、安全错误映射和稳定 Binding facade | 计划新增只读 capability 与无参数固定 portal-open 操作；不添加任意 URL 或 Renderer IPC | +| `electron/api/routes/ai-hardware.ts` | Main-owned Robot 云端代理，以及计划中的本地配网 capability/portal action | 本地操作必须在认证/上游访问前返回；系统浏览器只能打开固定 `http://192.168.4.1/` | ## Dependency Direction @@ -36,6 +39,7 @@ - AI 编程 Renderer → Host API → Main OpenCode routes/runtime；OpenCode provider 请求再经 Main AI proxy 访问模型上游，Renderer 不直接持有上游凭据或本地 runtime URL。 - Project configuration 决定产品分流；Main release builder 生成 source/built/contract，服务端独立重算和校验决定发布安全，本地 `ProjectType` 不是授权结论。 - Built artifact preflight 检查最终上传的同字节快照，但客户端可被绕过且不产生可信 receipt；服务端仍是合同、摘要和不可变 Release 安全权威。 +- Robot Renderer → typed AI hardware API → Main Host route。云端 Binding 仍由 Main 代理；V1 配网只增加 Main-owned capability 与固定系统浏览器 action，Wi-Fi 选择和凭据输入留在操作系统/固件 portal。 ## Risky Or Sensitive Areas @@ -51,7 +55,8 @@ - Gateway 命令的 REST fallback 只处理 WebSocket 发送、断连和 ACK 超时，必须复用 `client_command_id`；业务错误回退会造成重复提交。Quote 任务恢复只更新 Workspace 所有的任务，不能覆盖当前 Conversation。 - `closeEventSessions` 只负责本地流和缓存生命周期；远端 Conversation Session 是服务端持久资源。 - 单图来源选择器当前仍由精确中文 quick reply 触发，并以 Brief medium 判断图生图或视频首帧用途；扩展更多输入用途前应先把消息协议升级为结构化 action/purpose，避免展示文案与行为继续耦合。 +- Guided Hotspot Binding 依赖当前固件的开放热点和明文 HTTP portal，只能作为 default-off 内部试点；未完成指定固件镜像核对、六位码发行契约和真机 smoke 前不得开启。 ## Last Updated -2026-08-15 +2026-08-16 diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index cfb8f2b..54569c8 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -24,6 +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. | ## Important Boundaries @@ -32,6 +33,9 @@ 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. +- 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. - 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。 - 创建者发布唯一调用链是 `ProjectPublishAction → publishWorksProjectSource → Main-owned release build → preflightStaticArtifact → source+built+artifact_contract 上传 → 状态轮询`；客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。 @@ -55,8 +59,8 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展 ## Related Decisions -- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。 +- 当前长期边界记录于 README、ADR-001、ADR-002、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属、Robot 配网/绑定安全边界或重新引入客户端部署协调器，应新增 ADR。 ## Last Updated -2026-08-14 +2026-08-16 diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index 59799e9..98a485c 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -4,6 +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`. - `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. @@ -33,6 +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-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。 @@ -55,9 +57,10 @@ Updater 仍由 Electron Main 选择目标 feed、记录原始诊断并保持失 ## Next Recommended Steps -1. 成组核对客户端 source+built+contract 上传 → 服务端逐字节校验 → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。 -2. 配置真实生产环境，分别执行“小游戏/小程序创建 → 客户端本地构建与同字节预检 → 提交 → 服务端合同/摘要校验与不可变 Release 固化 → 运营批准 → App 播放”。 -3. 核对生产环境的提交状态、构建结果和告警证据。 +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 播放”。 ## Open Questions / Blockers diff --git a/.project-docs/30-worklog/tasks/20260813-sync-push-main-9c2f71.md b/.project-docs/30-worklog/tasks/20260813-sync-push-main-9c2f71.md index 8b0e34f..85e2ef5 100644 --- a/.project-docs/30-worklog/tasks/20260813-sync-push-main-9c2f71.md +++ b/.project-docs/30-worklog/tasks/20260813-sync-push-main-9c2f71.md @@ -12,6 +12,7 @@ ## Scope +- 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. - On 2026-08-15, resume the existing Integration owner to merge reviewed Robot configuration-loading fix `1bcd519` into local `main`, preserving the page error/retry state and Main response-body deadline. @@ -42,6 +43,7 @@ reviewed. Never use `--force`. - 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. ## Project Context Loaded @@ -125,6 +127,13 @@ Gate result: ## Plan +### 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. +2. Create an accepted ADR and promote the planned default-off capability, fixed portal action, Binding retry/restart semantics, release gates, and terminology into canonical project memory without claiming implementation is present. +3. Run project-document structure/drift and whitespace checks, then obtain an independent read-only Sol PASS/FAIL review. +4. Commit the canonical decision locally; start product implementation only from the accepted main baseline and do not modify firmware. + ### 2026-08-16 Robot Configuration Catalog Integration Plan 1. Merge reviewed source commit `fe55dee` into local `main` with a normal no-ff merge while preserving source history. @@ -162,6 +171,9 @@ Gate result: ## Outcome +- 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. - On 2026-08-16, started a normal `--no-ff --no-commit` merge of reviewed Robot catalog/editor source `fe55dee`; Git reported no textual conflicts. The source task record remains reachable on the source commit and feature branch and is excluded from the local `main` result. - Promoted the USER-scoped dynamic model/voice catalog boundary: Renderer receives only bounded display metadata through Electron Main and Works Square, all public catalog outcomes are no-store, and current unavailable values remain editable. - Replaced avoidable configuration text/number inputs with catalog selects and bounded TTS sliders while preserving `clear_fields`, revision conflict, operation identity, and Main-owned credential boundaries. @@ -246,6 +258,9 @@ Gate result: ## Verification +- 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. - 2026-08-16 source and staged-merge Robot catalog regression selection — 5 files / 84 tests passed. - 2026-08-16 Works Square catalog adapter/API suite — 131 tests passed; one existing Starlette/httpx deprecation warning. - 2026-08-16 Makelore typecheck, focused ESLint, and production `build:vite` — passed; only existing chunk-size and mixed-import warnings remain. @@ -313,6 +328,8 @@ 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`. +- 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. - Stable mutation operation IDs are retained across ambiguous retries in the running app but are not persisted across an application restart. @@ -330,4 +347,5 @@ Gate result: ## Promotion Candidates +- 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. diff --git a/.project-docs/40-domain/business-rules.md b/.project-docs/40-domain/business-rules.md index afcb920..739f87e 100644 --- a/.project-docs/40-domain/business-rules.md +++ b/.project-docs/40-domain/business-rules.md @@ -29,6 +29,14 @@ - 图片生成支持无参考图的文生图和单参考图图生图；参考图必须来自当前 Workspace 的已完成图片 Asset，或先通过现有 Workspace 上传接口把本地图片转成 Asset，再随当前 Conversation Turn 提交唯一 Asset ID。 - 视频首帧与图生图参考图复用单图选择器，但用途由当前 Brief medium 决定：只有明确 `image` 使用图生图语义，`video`、null 或缺失值保持视频首帧兼容语义。选择作品或上传成功后应关闭弹窗。 - 当前 quick reply 文案匹配只是兼容契约；新增更多素材输入用途前，应改为结构化 action/purpose，不得继续依赖本地化展示字符串推断行为。 +- Robot V1 把现有固件 Hotspot 配网指导放进现有 Binding 体验，但不宣称自动发现附近设备、自动下发 Wi-Fi、自动认领设备或自动确认在线；这些能力需要另行接受的协议与 ADR。 +- Guided Hotspot Binding capability 由 Electron Main 持有且默认关闭。关闭时保留现有六位码 Binding；Renderer 可以读取 capability，但不能覆盖它。 +- Robot portal 必须由 Main 以系统浏览器打开固定 `http://192.168.4.1/`。Renderer 不得提交任意 URL；该本地动作不得读取 Works 凭据或访问云端。 +- Wi-Fi SSID/密码只在现有固件 portal 内输入。Makelore 不收集、不代理、不日志记录、不持久化 Wi-Fi 凭据。 +- 当前开放 SoftAP 与明文 HTTP portal 只允许 default-off 内部试点。未核对精确固件镜像、六位码发行/消费契约并完成真机 smoke 前，不得面向公共用户开启。 +- Binding 成功仅表示设备与账号/Agent 的云端关系建立，不表示设备在线或业务协议 ready。 +- 同一进程内无法确认结果的 Binding 重试必须复用原 operation ID。无效、过期或已消费 activation code 必须清除 code 与 operation ID；下一个新码使用新 operation ID。Main 必须把 `ai_hardware_activation_code_invalid` 投影为 non-retryable，不信任上游相反标记。 +- 应用重启后，当前 overview DTO 不能证明旧码对应的 Binding 结果；客户端不得重放旧码或旧 operation ID，必须要求新码，无法取得时停止流程。 ## Open Questions @@ -39,7 +47,8 @@ - 图生图随客户端发布前，需确认相匹配的服务端 `image_to_image` Brief/Quote/Task 冻结、私有源图复核与 Bailian edit 执行链已部署，并使用真实 Workspace Asset 完成生产 smoke。 - Updater 生产恢复仍需对齐权威版本、发布正式签名/公证的平台产物，并从旧安装版本执行发现、下载、重启和安装 smoke；源码提示修复本身不构成发布链恢复。 - AI Canvas 双向 Gateway 与 Quote 任务恢复仍需真实账号执行一次生产确认 smoke，核对 WebSocket 不产生 `/runs/{run_id}` 轮询、任务按 Quote 出现在 Workspace 列表，并区分真正的 `agent_runtime_unavailable` worker 故障。 +- Robot Guided Hotspot Binding 试点需确认指定硬件/固件确实提供被审计的 Hotspot portal、部署端签发严格六位 ASCII 数字码且与 Works validator 的时效/消费语义一致，并完成真实设备端到端 smoke。 ## Last Reviewed -2026-08-14 +2026-08-16 diff --git a/.project-docs/40-domain/glossary.md b/.project-docs/40-domain/glossary.md index 38c93f7..23fefdc 100644 --- a/.project-docs/40-domain/glossary.md +++ b/.project-docs/40-domain/glossary.md @@ -16,3 +16,8 @@ | AI Design Workspace | 一个 AI 绘画设计项目 | 持有 Conversation 列表、生成任务和资产；不是单条对话 | | AI Design Conversation | Workspace 内一条独立设计对话 | 持有消息、Brief、Quote、`turnRevision` 和服务端持久 Agent Session 绑定 | | Persistent Conversation Session | 服务端为 Conversation 持久保存的 Agent Gateway Session | 客户端只重连事件流，不在注销或退出时 DELETE | +| Robot Provisioning | 让 Robot 获得目标 Wi-Fi 凭据并尝试联网的阶段 | 与云端 Activation、账号 Binding、协议在线是不同阶段；V1 由现有固件 Hotspot portal 完成 | +| Robot Activation | Robot 联网后向既有服务获取六位激活码的阶段 | 激活码由设备展示/播报给用户；Makelore 不生成该码 | +| Robot Binding | 用户把六位激活码和 Agent 提交到 Works Square，建立账号侧设备关系 | `bound` 不等于设备当前 online 或 protocol-ready | +| Guided Hotspot Binding | Makelore 内计划提供的 default-off 引导流程 | 串联系统热点连接、固定 portal、恢复互联网和现有 Binding；不包含自动发现、Wi-Fi 代填或固件修改 | +| `guidedHotspotBinding` | Electron Main 所有的本地 capability | Renderer 只读；公共默认 false，试点满足 release gates 后才可开启 |