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

fix: accept compressed Robot revision ETags

Browse Source
This commit is contained in:
brother7
2026-08-15 20:48:54 +08:00
parent a26a53a7f4
commit ea75b0618a
3 changed files with 154 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
.project-docs/30-worklog/tasks/20260815-robot-config-schema-8e2c41.md Normal file
View File

@@ -0,0 +1,99 @@
# Task: Fix Robot configuration response validation
## Identity
- Task ID: 20260815-robot-config-schema-8e2c41
- Mode: Feature
- Branch: codex/20260815-robot-config-schema-8e2c41-robot-config-schema
- Worktree: D:\Datas\OthersProjects\makelore-robot-config-schema-8e2c41
- Base commit: a26a53a7f4b1326be3084955029a65ef1f79929a
- Owner: codex
- Status: Ready for Integration
## Scope
- Reproduce the production Robot configuration read failure with the exact safe response shape and field lengths reported by Works Square logs.
- Identify the precise Main or Renderer validation rule that rejects a successful versioned configuration response.
- Align the client contract with the already deployed Xiaozhi/Works Square public schema without weakening exact-key validation, bounds, ETag/revision equality, authentication, or error redaction.
- Add regression coverage at the rejecting seam and the user-visible typed API/page path.
## Intent And Constraints
- Treat the upstream `200 application/json`, numeric revision, and Works `200` as confirmed evidence that the failure is downstream client validation, not device binding or authentication. The canonical strong ETag is confirmed only on the Xiaozhi-to-Works hop; the deployed compressed Works response was independently observed as canonical weak `W/"0"`.
- Use only safe field names, types, and lengths from the supplied logs; do not capture tokens, raw prompts, agent/device identifiers, or raw response bodies in tests or task records.
- Preserve strict DTO projection and bounded field validation. Change only rules proven inconsistent with the server contract.
- Keep Renderer free of credentials/raw upstream responses and preserve Main ownership of Works Square access and ETag handling.
- 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-schema-8e2c41`
- Mode: `feature`
- Branch: `codex/20260815-robot-config-schema-8e2c41-robot-config-schema`
- Worktree: `D:\Datas\OthersProjects\makelore-robot-config-schema-8e2c41`
- Base commit: `a26a53a7f4b1326be3084955029a65ef1f79929a`
- Other active local tasks: the existing `main` integration owner plus isolated release, packaging, AI Design, AI Programming, and completed Robot tasks returned by the registry.
- Overlap or semantic-conflict assessment: the immediately preceding Robot loading task is completed and integrated, and establishes the relevant error/retry and timeout behavior. No active peer owns the Robot response-schema validators. Packaging tasks are read/build-only snapshots; AI Design and AI Programming scopes do not overlap this contract fix.
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`
- 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 registered peer task record's Scope, Intent And Constraints, and Promotion Candidates sections
Relevant understanding:
- Project goal: keep a non-technical desktop workflow while Electron Main owns credentials, upstream network access, revisions, and safe response projection.
- Current integrated focus: Robot is the single hardware module; the previous fix now exposes a terminal configuration error instead of an endless spinner.
- Active task scope: correct the strict client response contract that rejects a server-successful agent configuration.
- Active constraints: do not bypass validation or enable editing without a real configuration plus revision; do not expose raw prompt/response data.
- Decisions affecting this task: one account maps to one Xiaozhi binding; agents/devices are subordinate resources; Main owns auth, idempotency, and ETag conversion.
- Evidence, reflections, or commitments affecting this task: production logs prove both upstream and Works endpoints return 200, numeric revision, and a complete field inventory. A local Electron diagnostic using the existing OS-encrypted session fetched the deployed Works endpoint without printing secrets or configuration values and confirmed `content-encoding`, `ETag: W/"0"`, `config_revision: 0`, `chat_history_conf: 0`, and the exact expected snake_case key set. Real deployment smoke remains necessary after the client fix.
- Files or modules likely involved: `electron/api/routes/ai-hardware.ts`, `src/lib/ai-hardware.ts`, and their focused tests.
- Unknowns, stale docs, or conflicts: the exact edge component that weakens the origin's strong ETag while compressing the response is not represented in this repository. The client can safely recover the numeric application revision from a strictly canonical weak tag only when it matches the typed DTO revision; no canonical memory conflict was found.
Gate result:
- Passed.
## Outcome
- Confirmed the deployed Works Square response was not the same as the origin-hop log: the JSON DTO and numeric revision were valid, while response compression changed the version validator to canonical weak `ETag: W/"0"`.
- Updated the Electron Main AI hardware route to accept either canonical strong `"n"` or canonical weak `W/"n"` revision tags. Noncanonical values, negative/decimal values, leading zeroes, non-numeric values, and unsafe integers remain rejected.
- Preserved optimistic concurrency: the parsed ETag revision must equal the strictly projected DTO revision, and PATCH/PUT continue to send a strong `If-Match: "n"` header.
- Added regression coverage across configuration GET/PATCH and assignment GET/PUT, including weak-tag mismatch and invalid-tag rejection.
## Verification
- TDD red: the new deployed-shape cases failed before the implementation with `AI_HARDWARE_INVALID_ETAG` (`2 failed, 23 passed`).
- TDD green: `tests/unit/ai-hardware-routes.test.ts` passed `25/25`.
- Integrated focused suite passed `7 files / 78 tests`:
- `tests/unit/ai-hardware-routes.test.ts`
- `tests/unit/ai-hardware-api.test.ts`
- `tests/unit/ai-hardware-page.test.tsx`
- `tests/unit/host-api-proxy.test.ts`
- `tests/unit/ai-hardware-server-registration.test.ts`
- `tests/unit/module-navigation.test.tsx`
- `tests/unit/main-layout-module-gate.test.tsx`
- `corepack pnpm run typecheck` passed.
- ESLint passed for both changed TypeScript files.
- `git diff --check` passed; Git emitted only line-ending conversion warnings.
- Final read-only Sol reviewer returned `PASS` after independently checking the diff and rerunning the 7-file/78-test suite, typecheck, ESLint, doc drift, and registry doctor.
## Follow-ups
- Rebuild/redeploy Makelore and repeat the real signed-in Robot configuration read/edit flow through the compressed public Works Square endpoint.
- The exact edge component responsible for the strong-to-weak ETag transformation is outside this repository; retaining this strict compatibility prevents future compression changes from breaking the semantic revision flow.
## Promotion Candidates
- Target: AI hardware client contract documentation. Proposal: record that versioned Works responses may arrive with canonical weak numeric ETags after content transformation; Electron Main normalizes only the numeric application revision, requires DTO equality, and always emits strong `If-Match` for mutations. Evidence: deployed response `ETag: W/"0"` with `content-encoding` and matching `config_revision: 0`. Future impact: preserves Robot read/edit behavior across compression gateways without weakening optimistic concurrency. Semantic conflicts: original strict strong-response assumption. Human confirmation required: no; this is an observed transport compatibility fact.