dsh-sansheng-liubu/CONTRACT.md

3.6 KiB
Raw Blame History

三省六部 v0.1 内部接口契约

本文件约束 Web 工作台、dsh-go 原生面板与宿主服务之间的数据形状。三端共用 src/shared/roles.js 与 src/shared/schema.js。

十席

  • SEAT_IDS 顺序:lead, zhongshu, shangshu, menxia, libu, hubu, lipu, bingbu, xingbu, gongbu。
  • SEATS[id] = { id, label(两字), duty(短摘要), responsibility(职责全文) }。
  • SEAT_GROUPS = { lead:[lead], sansheng:[zhongshu,shangshu,menxia], liubu:[libu,hubu,lipu,bingbu,xingbu,gongbu] }(工作台布局用)。

宿主 HTTP:POST /api/sansheng

请求体 { endpoint: string, payload?: object };成功回 { ok:true, value },失败回 { ok:false, error:{ code, message } }(HTTP 200)。

endpoint payload value
list — { projects:[{ id, name, status, revision }] }
project { projectId } 项目视图(见下)
open { workspaceId, name?, path? } 项目视图;不存在则按 workspaceId 建项目记录(不创建会话)
enable { projectId } 项目视图;严格创建/恢复十席会话
configure `{ projectId, seatId, model:({provider,model,reasoningEffort?} null), instructions? }`
models — `{ providers:[{ provider, models:[{ model, reasoningEffort?:[...] }] }], default:({provider,model}

错误码:sansheng/invalid、sansheng/not-found、sansheng/conflict、sansheng/unbound(席尚未绑定会话)、sansheng/model-invalid、sansheng/state-corrupt。

项目视图

{
  "revision": 0,
  "project": {
    "id": "ws-1", "name": "项目名", "workspaceId": "ws-1", "path": "D:/x", "status": "pending|provisioning|ready|error",
    "seats": [
      { "id":"lead","label":"丞相","duty":"...","responsibility":"...","status":"pending|creating|bound|failed|missing","sessionId":null,"model":null,"instructions":"","error":null }
    ],
    "groups": { "lead":["lead"], "sansheng":[...], "liubu":[...] }
  }
}

会话/模型规则(两端 UI 必须遵守)

  • 每席一个独立 root Session;切换角色 = 导航到该席 sessionId,不新建、不重建聊天引擎。
  • 模型未选择显示“请选择模型”;选择后显示具体名称。界面不提供“跟随宿主模型”选项。
  • “启用”只建立十个会话,不自动运行模型。
  • 角色补充说明:Web 可编辑;原生面板只读(原生无自由文本控件)。

Web 工作台(src/client/)

纯视图模型函数 buildWorkbenchView(view, ui) 必须可由 node 直接 import 测试(不依赖 React/DOM):

  • view = 项目视图;ui = { selectedSeatId, models, draft }。
  • 返回:{ projectTitle, ready, seats:[{id,name,duty,statusLabel,selected}], groups, selected:{ id,name,responsibility,duty,modelValue,modelLabel,instructions,modelOptions } }。
  • seats 必须正好十项且 name 两字;未选模型时 modelLabel==='请选择模型' 且 modelValue==='';modelOptions 不得含 value==='inherit' 的项。 React 接线用 React.createElement(不用 JSX,便于 esbuild 直接打包)。入口 export const inject=[...] + export function apply(ctx)。

dsh-go 原生面板(src/native/)

纯视图树函数 buildPanelView(input) 必须可由 node 直接 import 测试:

  • input = { project, selectedSeatId, models }。
  • 返回原生 view 节点({ type:'stack'|'row'|'text'|'list'|'callout'|'button'|'accordion'... })。
  • 硬约束:节点数 ≤120、深度 ≤8、单个 options/列表 ≤8 项、无自由文本输入控件;十席按 lead/sansheng/liubu 分组呈现。