dsh-sansheng-liubu/docs/client-contract-research.md

107 lines
8.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.0.1 客户端契约调研
日期:2026-11-14。只读调研;唯一新增文件为本笔记。后续任务曾短暂授权客户端实现,随后根任务改为“第一版方案 + dsh-go 样式预览”;未新增或修改客户端实现。
## 结论
Web 与 dsh-go 必须分开设计。Web 保留项目树与原生 session chat,仅追加入口及右面板;DS Bot 整套前端不可搬用,因为其显式替换 sidebar.workspaces 与多个 conversation 槽。dsh-go 是具有原生组件协议与 engine bridge 的 App;参考文档明确涉及 Android 验收,不能把响应式手机 Web 当作 dsh-go。当前已读原生桥不证明可注册桌面右 sidebar、不证明支持打开另一 session,也不提供 workspaceId。第一版原生样式只能标为概念预览,不能宣称已接线。
## 已读证据与版本
- [DS Bot manifest](../ds-bot/ds-bot/package.json):0.3.6;exports `.` → `./index.js`、`./client` → `./client.js`;`dsh.client.platform = "web"`。
- [DS Bot 测试宿主版本](../ds-bot/ds-bot/dev/harness/package.json):`@deepseek-ai/dsh = 0.2.2-rc.1`。这是参考仓库锁定版本,不是当前宿主运行版本证明。
- [DS Bot 客户端入口](../ds-bot/ds-bot/src/client/index.js):61–63 行 export inject/apply;104–108 行通过 workspaces.list 查询 session 所属 workspace;916–933 行 sidebarRight.openTab;982–985 行 slots 注册;1088 行 sidebar.workspaces 替换。
- [DS Bot transport](../ds-bot/ds-bot/src/client/api.js):8–41 行。
- 原生参考包 `@changfenhuang/dsh-genui` 0.16.0,已读其 [manifest](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/package.json)、[dsh-go 文档](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/docs/dsh-go.md)、[桥接类型](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/src/plugin/dsh-go-types.ts)、[面板实现](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/src/plugin/dsh-go-native.ts)、[只读工具卡投影](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/src/plugin/dsh-go-view.ts)、[原生组件编译器](C:/Users/qyh15/.dsh/profiles/desktop/node_modules/@changfenhuang/dsh-genui/src/plugin/dsh-go-compiler.ts)。仅读取 node_modules 下的包代码和文档,未读取用户配置、凭据。
## Web:已验证使用方式,未把未读签名当成公开保证
参考插件使用 `export const inject = ["sessions", "uiWorkspace", "uiConversation", "slots", "theme", "layout"]` 和 `export function apply(ctx) { ... }`。以下是已读调用,而非完成核对的宿主类型清单:
```js
ctx.slots.inject(name, () => ctx.slots.register({ name, id, order, inject }, Component));
ctx.get("sidebarRight")?.openTab("terminal");
ctx.get("sidebarRightTabs")?.get("terminal");
ctx.sessions.list.getSnapshot();
ctx.sessions.binding(sessionId);
const items = ctx.get("workspaces")?.list?.getSnapshot()?.items ?? [];
const owner = items.find(item => item.sessionIds?.includes(sessionId))?.workspaceId;
```
`sidebar.footer.action` 是参考插件已有的追加型入口用法;`sidebar.workspaces` 是其项目树替换方式,本需求禁止照搬。`sidebarRightTabs.register`、navigation 精确签名、当前 workspace 的 authoritative selection、打开 native chat 的 exact API 尚未由本轮宿主导出类型核实,不能据此写假接口。通过 sessionIds 查所属 workspace 也不能用于无 session 时随机挑第一个项目。
网络传输最小例(与参考插件同结构):
```js
async function request(endpoint, payload, signal) {
const res = await fetch("api/sansheng", {
method: "POST", credentials: "same-origin",
headers: { "content-type": "application/json" },
body: JSON.stringify({ endpoint, payload: payload ?? null }), signal,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const result = await res.json();
if (!result.ok) throw new Error(result.error?.message ?? "请求失败");
return result.value;
}
```
建议后端成功 `{ok:true,value:view}`,失败 `{ok:false,error:{code,message}}`。根 Agent 已收到此建议。请求必须捕获 projectId + generation/revision,结果到达后核对当前项目;项目变化时 abort/丢弃旧响应。此处是设计约束,未声称已实现。
## dsh-go:真实桥接签名与最小原生示例
GenUI 的类型文件对 Cordis Context 声明 `dshGo: NativeBridge`,但该文件没有独立 package export。不要 import 其内部源码。实际宿主桥是否存在应延迟注入探测:`ctx.inject(["dshGo", "sessions"], native => ...)`。这份接口是已安装公开插件的真实使用证据,不是本轮读取宿主 dshGo SDK 得到的兼容承诺。
```ts
type NativeScope = { sessionId?: string; messageId?: string; callId?: string };
type NativeEvent = { action?: string; value?: unknown; locale: string };
type NativeCaps = { locale: string; components: string[] };
type NativeEffect =
| { type: "refresh"; id?: string }
| { type: "copy" | "toast" | "insert"; text: string }
| { type: "link"; url: string };
interface NativeBridge {
panel(id: string, definition: {
view(scope: NativeScope, caps: NativeCaps): NativeView;
data?(scope: NativeScope, emit: (data: Record<string, unknown>) => void): () => void;
}): () => void;
on(id: string, handler: (scope: NativeScope, event: NativeEvent) =>
NativeEffect[] | Promise<NativeEffect[]>): () => void;
refresh(id: string, scope?: NativeScope): void;
}
```
最小形状示例(仅说明已读 view 节点,不代表完整插件可安装 manifest):
```js
ctx.inject(["dshGo"], native => {
native.effect(() => native.dshGo.panel("sansheng", {
view: (scope, caps) => ({
type: "stack", children: [
{ type: "text", text: "三省六部" },
{ type: "callout", tone: "info", text: scope.sessionId
? "当前对话的十席概览" : "请先从已加载的对话打开" },
{ type: "list", items: [{ title: "尚书省", subtitle: "统筹执行 · 待连接" }] },
],
}),
}));
});
```
实际模块通过 `@deepseek-ai/dsh-session` 的 `appendPluginRecord` / `pluginRecordOf` 持久化状态;这两项缺失时展示要求 DSH 0.2.1-rc.2 或更新版本的提示。这个版本门槛针对该持久原生面板方案,不是所有 dsh-go 功能的最低版本。GenUI 文档说明 manifest 提供 composer shortcut 和 session/chat panel;本轮没有读到对应 manifest 注册定义,不能给出编造的入口注册格式。
## dsh-go 样式预览边界
真实编译器以 `stack/children` 与 `row/children` 布局,文字用 `text` 字段(不是 Web GenUI 的 content);列表 `list.items` 使用 title/subtitle/action;度量 `metric`,键值 `keyValue`,提示 `callout` tone 为 info/good/warn/bad。Web card 在转换中变成 stack,并非独立原生 CSS 卡片。
原生面板可用按钮、单选列表、多选组、switch、tabs、accordion、复制与确认 HTTPS 链接。单个 options 最多 8 项且标签唯一、≤80 字符、不得换行;十席不能塞一个十项 options,应按三省/六部分组或使用 list。模型可做已有选项选择;当前桥不提供自由文本/密码字段,因此不能把备注编辑或自填模型 ID 画成已经可用的原生输入框。
容量:tool card 8 KiB / 40 nodes / depth 6,只读;model fence 整体 JSON 16 KiB;native panel 32 KiB / 120 nodes / depth 8。自由文本、slider、ECharts、SVG/Mermaid、3D、音视频不能保持原交互。SVG 树连线不应当成原生支持;十席层次可由标题、分组 list、stack 体现。
原生 panel scope 无 workspaceId,effect 无 session-navigation。三栏布局、右 sidebar 扩展、当前项目读取及角色点击打开另一原生 session 均需要另外核实宿主/App契约。独立 dsh-go 预览应明确“原生组件概念布局”,不能宣称与 Web 三栏完全一致。局部 bridge 存在也不等于当前客户端就是 dsh-go。
## 调研覆盖限制
给定 `resources/app.asar/dsh` 在普通文件搜索工具中不可作为目录读取;`.dsh/dsh-runtimes` 查到的仅 runtime manifest 与 dependencies。公开 Github main tree 请求为 404,npm 包页面重定向到登录,dsh.so/docs fetch 失败,均未作为接口证据。历史 `832e265` workbench/panel 源输出被截断,因此只将其当历史参考,未把未完整读取部分认定为官方契约。没有运行或安装插件、修改宿主、读取用户 profile 配置、构建或设备验收。