wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
ea75b0618a793928878edad736f0837ac9e4adc1
makelore/.project-docs/30-worklog/tasks/20260815-robot-config-schema-8e2c41.md

7.9 KiB
Raw Blame History

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: a26a53a7f4
  • 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.