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

8.5 KiB
Raw Blame History

三省六部 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。第一版原生样式只能标为概念预览,不能宣称已接线。

已读证据与版本

Web:已验证使用方式,未把未读签名当成公开保证

参考插件使用 export const inject = ["sessions", "uiWorkspace", "uiConversation", "slots", "theme", "layout"] 和 export function apply(ctx) { ... }。以下是已读调用,而非完成核对的宿主类型清单:

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 时随机挑第一个项目。

网络传输最小例(与参考插件同结构):

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 得到的兼容承诺。

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):

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 配置、构建或设备验收。