xinmi/WORKBENCH_CONTRACT.md

# 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.