dsh-sansheng-liubu/CONTRACT.md

67 lines
4.5 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 }` | 项目视图;严格创建/恢复十席会话 |
| `enableSeat` | `{ projectId, seatId }` | 项目视图;只开启一个部门(手动/派工按需) |
| `openSeat` | `{ projectId, seatId }` | 项目视图 + `sessionId`;只核实并进入已绑定原会话,绝不创建 |
| `rebuildSeat` | `{ projectId, seatId, expectedSessionId? }` | 项目视图 + `sessionId`;仅 missing 时重建一次,旧历史保留 |
| `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/session-missing`(绑定会话已不存在,需用户确认重建)、`sansheng/session-check-failed`(暂无法确认会话,禁止自动重建)、`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`,不新建、不重建聊天引擎。
- 已有绑定必须先核实原会话:存在就进入原 session;被删除才标记 `missing`,由用户点“重建会话”确认后只创建一次。
- 部门会话标题固定为两字角色名(丞相、中书、门下、尚书、吏部、户部、礼部、兵部、刑部、工部);新建/恢复/重建都通过宿主 `rename` 钉住标题,停止自动标题。
- 模型未选择显示“请选择模型”;选择后显示具体名称。界面不提供“跟随宿主模型”选项。
- “启用”只建立十个会话,不自动运行模型。
- 角色补充说明: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 分组呈现。