48 lines
3.4 KiB
Markdown
48 lines
3.4 KiB
Markdown
# Eddy knowledge catalog v1
|
|
|
|
Reference materials, not executable distribution. All complete categories (source-bug,
|
|
devicesim, app-compat, unknown) are accepted and initially Enabled. Classification is
|
|
diagnostic metadata. It does not select replay behavior or require administrator/model approval.
|
|
The old compat API remains unchanged for old clients; new clients do not execute that feed.
|
|
|
|
Authenticated POST /api/eddy/knowledge accepts {document, files}, where files maps SHA-256
|
|
to base64. Document schema is eddy-knowledge-v1: id, title, category, confidence,
|
|
problem {description, steps, expected, actual, cause, signature?},
|
|
solution {description, kind, validation, rollback, contract?}, observedEnvironment,
|
|
origin {task?, derivedFrom?, legacy?}, attachments [{name, role, mediaType, sha256, bytes}].
|
|
Kinds: frida-js, devicesim-diff, launch-config, advice. JS needs a code attachment;
|
|
DeviceSim diff needs a diff attachment. Screenshots are optional and should contain only relevant evidence.
|
|
24 attachments maximum, 8 MiB each, 32 MiB total; text fields bounded and assets hash-checked.
|
|
An author can revise their record; an SSO administrator can also revise.
|
|
Eddy clients sign in through browser SSO (`eddy auth login`); ordinary employees receive a knowledge-only session without requesting an API key.
|
|
See [client SSO](client-sso.md) for the grant flow, session lifetime and deployment order.
|
|
Repeated content returns its immutable revision receipt; a new revision never undoes Disable.
|
|
|
|
GET /api/eddy/knowledge/feed?cursor=...&limit=50 delivers all enabled materials, independent
|
|
of installed baseline. Stable watermark pagination and serialized change sequence allocation
|
|
prevent skipped concurrent writes. A subsequent incremental pass catches writes after the
|
|
watermark. Disable is a tombstone; clients remove it from default retrieval without deleting
|
|
task edits already created from it. A concurrent disable can make an attachment unavailable;
|
|
clients keep the prior cursor and restart a full visibility scan on 404.
|
|
GET /knowledge/:id/:revision and /knowledge/assets/:hash read content; disabled content
|
|
is restricted to administrators. Baseline identity remains metadata for relevance and
|
|
local execution checks.
|
|
|
|
Administrator APIs under /api/eddy/admin:
|
|
- GET /knowledge: paged full catalog including Disabled, with latest action actor/time.
|
|
- POST /knowledge/:id/state with {enabled: boolean}: audited Enable / Disable.
|
|
- GET /knowledge/:id/export: ZIP containing knowledge.json, receipt.json, problem.md,
|
|
solution.md and every attachment. The extracted package is compatible with Eddy knowledge save.
|
|
|
|
Deployment: apply drizzle/0031_eddy_knowledge_catalog.sql before serving these routes.
|
|
Then explicitly run scripts/migrate-eddy-knowledge.ts against the intended database.
|
|
It preserves old material, author/ID/revision provenance and stopped states, never modifies
|
|
old-client compat states and skips imported revisions on repeat. Invalid/missing payloads
|
|
are reported for follow-up rather than silently discarded or fabricated.
|
|
Unsolved observations remain in the historical audit store; they are not invented solutions.
|
|
Review migration output before switching users to the new knowledge view.
|
|
|
|
Local validation: TEST_DATABASE_URL must point to a dedicated local PostgreSQL database.
|
|
Run bun test control-server/test/eddy_catalog.integration.test.ts and the existing
|
|
eddy_flow.integration.test.ts separately (both close their connection pool).
|