62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
# 三省六部 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 分组呈现。
|