fix: recover Robot configuration loading

.project-docs/30-worklog/tasks/20260815-robot-config-loading-4f8c2d.md

@@ -0,0 +1,94 @@
+# Task: Fix Robot agent configuration loading
+
+## Identity
+
+- Task ID: 20260815-robot-config-loading-4f8c2d
+- Mode: Feature
+- Branch: codex/20260815-robot-config-loading-4f8c2d-robot-config-loading
+- Worktree: D:\Datas\OthersProjects\makelore-robot-config-loading-4f8c2d
+- Base commit: a4050f0a6567e8203630bf5d16b57f00c45caab8
+- Owner: codex
+- Status: Ready for review
+
+## Scope
+
+- Reproduce the Robot page state where a selected agent remains indefinitely in configuration loading and the edit action stays disabled after device binding.
+- Trace the Renderer typed API, page effects, and Main-owned Works Square route without weakening authentication, ETag, idempotency, or response validation.
+- Fix the smallest confirmed client-side cause and add a regression test at the user-visible page seam.
+
+## Intent And Constraints
+
+- The edit button may be enabled only after a real, versioned agent configuration has loaded; do not bypass the loading/error state.
+- Preserve Main ownership of Works Square credentials and upstream headers, and retain strict numeric revision plus ETag equality checks.
+- Keep activation codes and upstream response details out of Renderer state, logs, task records, and test output.
+- Work only in the isolated linked worktree; do not alter or release the existing `main` integration owner.
+
+## Project Context Loaded
+
+Task context:
+- Task ID: `20260815-robot-config-loading-4f8c2d`
+- Mode: `feature`
+- Branch: `codex/20260815-robot-config-loading-4f8c2d-robot-config-loading`
+- Worktree: `D:\Datas\OthersProjects\makelore-robot-config-loading-4f8c2d`
+- Base commit: `a4050f0a6567e8203630bf5d16b57f00c45caab8`
+- Other active local tasks: the existing `main` integration owner, completed Robot source task, and isolated release, AI Design, AI Programming, updater, and packaging tasks returned by the registry.
+- Overlap or semantic-conflict assessment: the completed Robot task establishes the relevant trust and state boundaries; no active peer owns the Robot page or typed hardware API. The same-base AI Design points task is confined to AI Design. Placeholder peer records have unrelated titles and isolated worktrees, so no semantic conflict blocks this diagnosis.
+
+Read:
+- `.project-docs/05-agent-entry/read-before-planning.md`
+- `.project-docs/05-agent-entry/memory-index.md`
+- `.project-docs/05-agent-entry/planning-gate.md`
+- this 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/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`
+- evidence, reflection, commitment, and stale-item indexes
+- every peer task record returned by `task_context.py status --json`
+
+Relevant understanding:
+- Project goal: provide a non-technical desktop workflow while keeping credentials and sensitive network behavior in Electron Main.
+- Current integrated focus: Robot is the single enabled hardware module and its typed Renderer → Host API → Main → Works Square chain is integrated.
+- Active task scope: restore the configuration-loading terminal state so the user can edit the selected agent after binding a device.
+- Active constraints: do not expose credentials/raw upstream errors, do not bypass revisions, and do not initialize Programming state on Robot routes.
+- Decisions affecting this task: one local account maps to one Xiaozhi binding; agents/devices are resources beneath it; Main owns auth/idempotency/ETags.
+- Evidence, reflections, or commitments affecting this task: the screenshot proves overview and device binding render successfully while the configuration pane remains loading; real production Robot smoke remains the decisive deployment check.
+- Files or modules likely involved: `src/pages/AiHardware/index.tsx`, `src/lib/ai-hardware.ts`, `electron/api/routes/ai-hardware.ts`, and their focused tests.
+- Unknowns, stale docs, or conflicts: the screenshot alone does not distinguish a never-settling promise from a rejected response followed by stale loading state; a red-capable page test is required before selecting a fix.
+
+Gate result:
+- Passed.
+
+## Outcome
+
+- Reproduced the user-visible failure with a deterministic page test: after the configuration request rejected, the card still rendered `正在读取配置`, exposed no retry action, and kept editing disabled.
+- Split configuration loading from its terminal failure state. A failed read now renders a safe local error state with `重试读取配置`; a successful retry restores the prompt and enables editing only after a real configuration and revision have loaded.
+- Clear loading/error state when no agent is selected, preventing an abandoned request from leaving a stale spinner.
+- Extended the Main-owned upstream deadline through bounded response-body reading and JSON parsing. A response that returns headers and an initial chunk but never completes now terminates as the safe retryable `504 / AI_HARDWARE_TIMEOUT` envelope instead of leaving Renderer pending forever.
+- Preserved strict response schemas, ETag/revision equality, Main-owned authentication, idempotency, response-size limits, and upstream error redaction.
+- Cross-repository inspection found no current source-contract mismatch for agent configuration fields, revision numbers, or ETags. Production still needs to be checked for the current Xiaozhi image and Liquibase migrations if a retry reports a server error.
+
+## Verification
+
+- Red page test on the pre-fix implementation: `pnpm exec vitest run tests/unit/ai-hardware-page.test.tsx -t "stops loading and lets the user retry after configuration loading fails"` — 1 failed, proving the stale loading state.
+- Red Main route test on the pre-fix implementation: stalled configuration response body exceeded the 100 ms test deadline without returning an envelope.
+- `corepack pnpm exec vitest run tests/unit/ai-hardware-page.test.tsx` — 25 passed.
+- `corepack pnpm exec vitest run tests/unit/ai-hardware-routes.test.ts` — 18 passed.
+- Focused Robot/Main regression suite across page, route, typed API, Host proxy, module navigation, layout gate, and provider gate — 7 files / 74 tests passed.
+- `corepack pnpm run typecheck` — passed.
+- ESLint on the four changed TypeScript/TSX files — passed.
+- `git diff --check` — passed; only Git line-ending conversion warnings were emitted.
+- Independent final Sol review — PASS; the reviewer reproduced the 7-file / 74-test result and found no code or documentation blocker.
+
+## Follow-ups
+
+- After deployment, verify the Xiaozhi manager image includes numeric External API revision serialization and that Liquibase changesets `202608131500` and `202608131501` are applied if configuration reads still fail.
+- Perform a signed-in staging smoke: bind a device, load the selected agent configuration, edit `systemPrompt`, save with the returned revision, and confirm the updated prompt after refresh.
+
+## Promotion Candidates
+
+- None recorded.