65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
|
# 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.
|