yawan
f7fc992f57
4.2 KiB
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/instructionslists/reads creator-owned Markdown rules;POST /instructions/importaccepts UTF-8.md(256 KB, 16k-token rule limit), andPOST /instructions/mountacceptsagent_ids,skill_idsandmode(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.