ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Web Client 架构:分层、数据通路与重连到底怎么对齐才不混乱

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessWeb Client分层重连
页面能开,但断网重连后状态错乱,或分不清哪层该持有会话状态。本文讲六层所有权与依赖方向、lazy CommonJS 启动、生成式 Remote、Client model 的职责,以及按数据类型区分的重连语义。

“断网重连后状态乱了”,通常是因为把不同数据当成同一种恢复语义。 DSH plugin 的 Web Client 里,持久 Session 日志、control 流与普通通知各有自己的重连规则。先分清数据属于哪条通路,再谈修法。 DSH插件 的 Web Client 分层很硬,跨层拿状态迟早出问题。

六层所有权:从 Host 到 React

依赖方向单一,反向只走 callback。(来源)

层主要 owner职责
Host 应用packages/api/*-controller Host entry权威状态、持久化、mutation 顺序、访问策略与 stream 生产
传输与 API assemblyclient/connection、api/gateway、api/remotes建立 Client generation,公开生成的 ctx.remote method 与 stream
Client modelapi/session-controller/client 等不依赖 React 的 Host 状态镜像,处理竞态与 identity
UI adapterclient/ui-session、client/ui-workspace把 model observable 转成 Slot source,拥有视图级导航
Conversation 数据client/ui-conversation、ui-chat 等组装 target snapshot,拥有 shell 与输入流程
组合与渲染client/ui-slots、ui-renderer、UI 功能包声明扩展位置、推导 props、绑定 hook、挂载组件树

依赖方向是:Host 状态 → Remote 传输 → Client model → UI adapter → Conversation 或 presentation → Slots → React。

用户操作通过 callback 反向进入注入的 Client service 或生成的 Remote namespace。Presentation component 绝不接收 Cordis ctx、transport 对象或其他功能插件的实现——这条约束让 UI 层无法绕过 model 直接改状态。

浏览器启动:lazy CommonJS 表

加载 bundle 只注册 factory,materialize 时才真正执行。(来源)

Host 把组合后的 WebBootGraph 写入 window.__DSH_BOOT__,并在 parser-preloaded script 执行前安装浏览器 module-loader facade。模块系统是一张 lazy CommonJS 表:加载 bundle 只注册 factory;materialize entry 时才以同步 require 运行 factory,并解析 platform module 与已声明的动态依赖。

Web boot kernel 创建模块系统、预取 immediately entry、挂载 vendored Cordis Loader,再创建图中的每个 entry。激活顺序由 Cordis service injection 决定;module graph 顺序只决定同步 import 能否被 materialize。

启动审计有明确判定:完整 roster 到达 settled 状态且启动审计通过——浏览器必需名单中的 entry 未激活会拒绝启动,其他未激活 entry 只输出一条控制台警告。最后 ui-renderer hydrate 不依赖框架的 boot DOM,并调用唯一一次 context 级 renderSlot('root')。

Remote 通信:用生成的 face,不依赖实现

功能包依赖生成的 service face,而不是 Gateway 实现或 Host 运行时 entry。(来源)

Host 业务 service 使用 Typert Remote decorator 标记可调用 method。Host generation 产出严格 descriptor、runtime codec、declaration merge 与 source map。Client 侧 api-remotes assembly 选择这些生成贡献,并把具体 method 挂到 ctx.remote.<namespace> 与 Session scope 的 agentCtx.remote.<namespace>。

职责划分要记清:Connection 拥有请求 URL 解析、request correlation、/api carrier、trust check、精确 Fetch 路由与 connection generation;API Gateway 拥有 Remote dispatch、取消、logical stream 与选定 Host event 的转发。

Controller 操作应进入生成的 Remote method 或显式 Remote stream;功能自有的下载则注册精确 Fetch 路由。内部 $events logical stream 是 Connection generation source,它的 opening ready frame 携带用于路径显示的 Host home,并在 Host listener 已挂载、任何 controller 开始 baseline read 之前建立 generation。

ctx.remote.$on() 把 allowlist 内的普通 event 交付给 root Client Context,把 scoped waterfall event 交付给已解析的 Session Context;waterfall listener 可以返回结果、调用 next() 或拒绝。

Client models:不依赖 React 的状态镜像

Host 决定真相,Client 只维护最新可用的本地投影。(来源)

每个 API controller 包都拥有配对的 Host face 与 Client face。Client 侧基于相同的生成 wire type 维护 identity 稳定、与 React 无关的 model,并公开 observable snapshot 与 command。UI 包消费这些 Client service,不在 component store 中复制 transport state。

Sessions 侧分三层:ClientSessions 提供 ctx.sessions,拥有 reference、source count、Session scope 与稳定的 SessionBinding 对象,并投影不含全局 current Session 选择的 catalog state;SessionManager 拥有 list baseline、实时 list/control update、惰性 Session instance、projection store、subagent catalog,以及 pull 与后到 update 之间的冲突顺序;每个 Session 拥有一段由 SessionEventLikeEntry 表示的连续逻辑事件窗口、分页、follow、prompt/control state 与供 adapter 消费的快照。

持久 event 路径的关键在首帧:follow() 的第一帧包含当前 header、tail page、cursor 与完整 projection baseline。history record 带显式 event 或 chunks 判别字段和字段对齐的内部 event;journal 先校验每条 record 的逻辑 seq 闭区间,Client 再直接保留为 SessionEventLikeEntry,无需逐 record 转换。每个物理 generation 都根据该 snapshot 原子替换保留窗口,随后按 seq append 标准实时 event。page() 只用于更早历史与 gap repair。

Workspace model 与竞态合并

重连时用新 baseline 整体替换,不做增量猜测。(来源)

api/workspace-controller 把 Workspace 变更策略与权威 follow feed 留在 Host。ClientWorkspaceModel 拥有浏览器行、Workspace 顺序、归档与置顶 Session id 数组、命令回显,以及流与一元调用的竞态合并。

每代 stream 先给出完整 baseline,再给出 upsert、remove、order、archived 与 pinned increment;重连时以新 baseline 替换 model。WorkspaceController 把该 model 作为 ctx.workspaces 公开,ui-workspace 则提供 useWorkspaces 与导航回调。

几条产品语义:侧边栏的 ArchivedFilter 控制列表与搜索中的默认隐藏、显示已归档或仅显示已归档;归档行保留排序位置、置灰展示,必须先通过行菜单或搜索结果的取消归档操作恢复后才能打开;恢复调用 workspace.unarchiveSession。Session 显示顺序保存在浏览器本地并包含隐藏归档项;置顶在该完整顺序内移动 Session,取消置顶不恢复先前位置。

Conversation、Slots 与重连

持久日志与 control 流的恢复方式不同,普通通知根本不重放。(来源)

ui-session 安装 Session scope adapter,并在 remote-access Client 服务之上提供 useSessions、useSessionStatus、useSession、useProjection 等 hook。SessionProvider 可以继承外围 binding,也可以绑定显式 SessionReference,因此并存子树可以指向不同 Session。

ui-conversation 对每个 SessionBinding.eventSource 只绑定一次。event registry 把持久 Session event 与 Client-only assistant/live-chunk update 关联成稳定的业务 Context,view registry 则 materialize target snapshot。Chat Assistant、Trajectory Assistant 与 Turn Tail 同时解释 live chunk 和持久 settlement 中嵌入的紧凑 stream,因此重连与分页历史无需持久 token 行即可复现相同 Assistant 状态。

ui-slots 提供类型化 registry 与 lifecycle ledger;ui-renderer 是唯一通过 useSyncExternalStore 绑定裸 observable、拥有 React context 并渲染 root tree 的包。

重连语义分三类:持久 Session journal 校验逻辑 seq range,并按每个 generation 的 opening snapshot 替换窗口,page() 补更早历史与修复后续 gap;Session control 与 Workspace stream 在断开期间保留最后一次发布的值,再用新的 opening baseline 原子替换;普通 forwarded notification 不会 replay,需要可靠恢复的有状态领域必须自己提供 baseline、cursor 或显式 query。

架构中没有统一的 Client Runtime、events.mux、events.host 或通用 resync() API。物理恢复与逻辑恢复彼此独立:Gateway mux 恢复物理 WebSocket;Connection 发布可用 generation 后,每个 RemoteStream 分别重开自己的 logical source。carrier failure 可以重试;business error、非法 opening item 或 protocol violation 会令所属 logical stream 终止。

包边界与验证

功能包之间只共享声明,不共享运行时值。(来源)

功能插件包可以通过 import type 共享声明;不得运行时导入或转发另一个功能插件的值。跨包行为用注入的 Cordis service,跨包 UI 用 Slots。特定 target 的 Conversation Definition、projection helper 与最终 view data 留在所属 target 包中,即使 Chat 与 Trajectory 有意实现平行逻辑。共享运行时值需要一个职责收窄、没有功能生命周期的静态 owner,例如 client/store、ui-primitives 或浏览器安全的 util 包。

验证建议六步:

  1. 断开网络 30 秒再恢复,断言持久 Session 的消息没有重复、没有缺页。
  2. 在断开期间产生一条 control 更新,恢复后断言它以新 baseline 覆盖而不是叠加。
  3. 触发一条普通通知,恢复后断言它没有被重放。
  4. 归档一个 Session,断言行仍显示但置灰,且不能直接打开。
  5. 调取消归档,断言 unarchiveSession 被调用且该行恢复可打开。
  6. 重连后检查组件树,断言没有出现两份 transport state。

如果第 2 步出现重复状态,先确认 Client model 是否把增量应用到了旧 baseline 上,而不是先替换再应用。

客户端模块如何被发现与注入,可以对照Client 模块 wire;Slot 的扩展方式见Slot 的 hooks 与 injection。

一句话收束: 六层单向依赖、lazy CommonJS 启动、Remote 用生成 face、Client model 不依赖 React、重连按数据类型分三类、功能包只共享声明。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 Presentation 组件能拿到 Cordis ctx 吗?

不能,DSH plugin 明确规定展示组件不接收 Cordis ctx、transport 对象或其他功能插件的实现。DSH plugin 让组件通过推导出的 props 拿 framework hook、owner prop、store action 与显式 injection。

DSH plugin 的普通转发通知,在断线重连之后会被重放吗?

不会,DSH plugin 的普通转发通知不重放。DSH plugin 要求需要可靠恢复的有状态领域自己提供 baseline、cursor 或显式 query。

DSH plugin 有统一的 resync API 吗,各层各自恢复吗?

没有,DSH plugin 明确说架构里没有统一 Client Runtime、events.mux 或通用 resync。DSH plugin 让 Connection 暴露 generation 状态,Gateway 管理 logical stream,各 model 自己定义替换或续传语义。

DSH plugin 的已归档会话能直接打开吗,打开之前要先做什么?

不能,DSH plugin 的归档行保留位置但置灰。DSH plugin 要求先通过行菜单或搜索结果的取消归档操作恢复,恢复后再打开。

相关术语

WebBootGraph
WebBootGraph 是 Host 写入 window.__DSH_BOOT__ 的组合启动图,描述浏览器侧每个 entry 与依赖。— DeepSeek Harness 官方参考 - Web Client 架构
SessionBinding
SessionBinding 是 ClientSessions 拥有的稳定绑定对象,承载 Session scope 与 eventSource 等引用。— DeepSeek Harness 官方参考 - Web Client 架构
SessionEventLikeEntry
SessionEventLikeEntry 是 Client 保留的连续逻辑事件窗口条目,来自打包后的 Remote 历史记录,无需逐条转换。— DeepSeek Harness 官方参考 - Web Client 架构
ClientWorkspaceModel
ClientWorkspaceModel 是浏览器侧 Workspace 模型,拥有行、顺序、归档与置顶数组及流与一元调用的竞态合并。— DeepSeek Harness 官方参考 - Web Client 架构

来源