dsh-sansheng-liubu/CONTRACT.md

62 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 三省六部 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? }` | `{ seat }` |
| `models` | — | `{ providers:[{ provider, models:[{ model, reasoningEffort?:[...] }] }], default:({provider,model}|null), failures:[...] }` |
错误码:`sansheng/invalid`、`sansheng/not-found`、`sansheng/conflict`、`sansheng/unbound`(席尚未绑定会话)、`sansheng/model-invalid`、`sansheng/state-corrupt`。
## 项目视图
```jsonc
{
"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 分组呈现。