# 三省六部 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) => void): () => void; }): () => void; on(id: string, handler: (scope: NativeScope, event: NativeEvent) => NativeEffect[] | Promise): () => 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 配置、构建或设备验收。