WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Native workbench implementation contract
+
+Brand: 私域Agent. Base API: `/api/v1/workbench`. All routes use the existing
+WeKnora auth middleware and tenant RBAC; no FastAPI calls or shared admin JWT.
+
+## HTTP
+
+- `GET /modules`: enabled module metadata.
+- `GET /resources/:kind`: `{success:true,data:Resource[],total:number}`; page/page_size/q.
+- `POST /resources/:kind`: `{name,data}` -> Resource.
+- `GET /resources/:kind/:id`: Resource.
+- `PUT /resources/:kind/:id`: `{name,data,version}` -> Resource; optimistic locking.
+- `DELETE /resources/:kind/:id?detach=true`: delete owned resource, optional explicit detach.
+- `POST /resources/:kind/:id/actions/:action`: `{version, advice?, day?, segment_id?, agent_id?}`
+  -> `{success:true,data:Job}` for asynchronous AI work, Resource for synchronous work.
+- `GET /jobs/:id`: Job including progress, stage, error and generation usage metadata.
+- `GET /notifications`, `POST /notifications/read-all`.
+
+Resource: `{id,tenant_id,owner_id,owner_name,kind,name,status,version,data,created_at,updated_at}`.
+Kinds in this package: `training-maps`, `content-tasks`, `flows`.
+Digital humans are implemented separately as typed `/api/v1/digital-humans` routes;
+skills and memories reuse native modules and receive extensions separately.
+IDs are UUIDs, owner/tenant derived from auth. Defaults private. Admin can inspect all
+resources in the active tenant, while mutations, deletion, queued AI actions and
+bindings remain owner-only. Data is versioned JSON with per-kind validation.
+
+Job: `{id,resource_id,kind,action,status,progress,stage,error,generation,created_at,updated_at}`.
+Status queued/running/succeeded/failed/cancelled. Progress measures completed stages;
+the UI must not display invented countdowns. Concurrent writes use resource version.
+
+## Payloads
+
+- training-maps: `{topic,days_count,agent_id,knowledge_base_ids:[],knowledge_ids:[],days:[{day,title,prerequisite,hook,nodes:[{id,label,children:[]}],framework,confirmed}],advice}`.
+  Actions generate/revise (optional day)/generate-day (day)/confirm-day (day)/confirm.
+- flows: `{nodes:[{id,agent_id,label}],edges:[{source,target}],description}`.
+- content-tasks: `{map_id,day,flow_id,agent_id,knowledge_base_ids:[],segments:[{id,title,agent_id,status,content,review,source_ids:[]}],review,composed}`.
+  Actions decompose/generate (segment_id)/accept/skip/revise (segment_id + advice)/review/compose.
+- digital-humans: `{description,source_text,agent_id,model_id,profile,versions:[]}`.
+  Actions distill (advice optional)/approve. Linked native CustomAgent created automatically.
+- instruction skills: `/api/v1/skills/instructions` lists/reads creator-owned Markdown rules;
+  `POST /instructions/import` accepts UTF-8 `.md` (256 KB, 16k-token rule limit), and
+  `POST /instructions/mount` accepts `agent_ids`, `skill_ids` and `mode` (`add`, `remove`,
+  `replace`). Rules are creator-private, never executed as code, and are injected into
+  native chat and workbench generation after access checks. Executable sandbox skills
+  remain governed by the native catalog and are separate from these rules.
+- memories: `{agent_id,content,source}`.
+
+## Go package contract
+
+Package `internal/workbench`. Root owns `service.go`, `models.go`, `handler.go`,
+`jobs.go`, `generation.go`, content/map operations, router/container wiring.
+Resources have `Data JSON` (`map[string]any` implementing SQL Scanner/Valuer).
+Service fields: `db *gorm.DB`, `models interfaces.ModelService`,
+`agents interfaces.CustomAgentService`, `sessions interfaces.SessionService`.
+Helpers: `s.get(ctx,kind,id) (*Resource,error)`, `s.save(ctx,*Resource,expectedVersion) error`,
+`s.complete(ctx,agentID,system,prompt string) (string,error)`,
+`s.progress(ctx,jobID string,percent int,stage string) error`.
+Digital humans use separate types/interfaces/repository/service/handler and migration
+000091. Their default Agent is private and created transactionally; review syncs its
+persona, and deletion cleans its default Agent, bindings and IM channels. Workbench
+generation resolves mounted instruction skills through an injected resolver.
+
+Implementation status must be recorded honestly. Persisted CRUD alone is not a
+complete port of a legacy workflow. Keep original data until verified ETL and parity.