DSH plugin Web Client 架构:分层、数据通路与重连到底怎么对齐才不混乱
“断网重连后状态乱了”,通常是因为把不同数据当成同一种恢复语义。 DSH plugin 的 Web Client 里,持久 Session 日志、control 流与普通通知各有自己的重连规则。先分清数据属于哪条通路,再谈修法。 DSH插件 的 Web Client 分层很硬,跨层拿状态迟早出问题。
六层所有权:从 Host 到 React
依赖方向单一,反向只走 callback。(来源)
| 层 | 主要 owner | 职责 |
|---|---|---|
| Host 应用 | packages/api/*-controller Host entry | 权威状态、持久化、mutation 顺序、访问策略与 stream 生产 |
| 传输与 API assembly | client/connection、api/gateway、api/remotes | 建立 Client generation,公开生成的 ctx.remote method 与 stream |
| Client model | api/session-controller/client 等 | 不依赖 React 的 Host 状态镜像,处理竞态与 identity |
| UI adapter | client/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 包。
验证建议六步:
- 断开网络 30 秒再恢复,断言持久 Session 的消息没有重复、没有缺页。
- 在断开期间产生一条 control 更新,恢复后断言它以新 baseline 覆盖而不是叠加。
- 触发一条普通通知,恢复后断言它没有被重放。
- 归档一个 Session,断言行仍显示但置灰,且不能直接打开。
- 调取消归档,断言
unarchiveSession被调用且该行恢复可打开。 - 重连后检查组件树,断言没有出现两份 transport state。
如果第 2 步出现重复状态,先确认 Client model 是否把增量应用到了旧 baseline 上,而不是先替换再应用。
客户端模块如何被发现与注入,可以对照Client 模块 wire;Slot 的扩展方式见Slot 的 hooks 与 injection。
一句话收束: 六层单向依赖、lazy CommonJS 启动、Remote 用生成 face、Client model 不依赖 React、重连按数据类型分三类、功能包只共享声明。
常见问题
不能,DSH plugin 明确规定展示组件不接收 Cordis ctx、transport 对象或其他功能插件的实现。DSH plugin 让组件通过推导出的 props 拿 framework hook、owner prop、store action 与显式 injection。
不会,DSH plugin 的普通转发通知不重放。DSH plugin 要求需要可靠恢复的有状态领域自己提供 baseline、cursor 或显式 query。
没有,DSH plugin 明确说架构里没有统一 Client Runtime、events.mux 或通用 resync。DSH plugin 让 Connection 暴露 generation 状态,Gateway 管理 logical stream,各 model 自己定义替换或续传语义。
不能,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 架构
来源
- DeepSeek Harness 官方参考 - Web Client 架构· deepseek-ai
- packages/client/connection/src/rpc.ts· deepseek-ai