# 261011 dsh 0.2 兼容性修复总结

## 背景

本机 DSH 于 2026-10-10 升级到 `0.2.0-rc.2`（客户端包族做过一次重组：`dsh-client-runtime`
退役，session 快照与 chat 数据分离）。dsh-zen 1.0.1 是按 0.1.x 客户端契约写的，需要核对
兼容性并修复断点。本机 live `web` profile 未启用本插件，因此在一次性 `dsh-e2e` 实例
（dsh-base + dsh-web-app + 本插件）上做实测。

## 断点与修复

| # | 断点（0.1.x → 0.2.0-rc.2） | 影响 | 修复 |
| --- | --- | --- | --- |
| 1 | `sessions.list.getSnapshot().current` 已移除（列表快照只剩 `ids`/`byId`/`phase`/`projectionsBySession`） | 自动进出禅永不触发 | 按 `uiSession.publishMain` 的同一推导取「主视图保留」的会话：`byId` 中 `retainedBy.mainView > 0` 的行 |
| 2 | Session 快照不再携带 `chat` / `runningCalls`（迁到 Conversation 视图快照存储） | Zen 视图读不到用户消息、AI 回复、运行中工具 | 经 `ctx.uiConversation.binding(sessionId).target("chat")` 订阅 Chat 目标快照（订阅即激活目标，避免 Zen 为当前视图时 chat 目标未激活）；`runningCalls` 取 `chat.legacy.runningCalls` |
| 3 | `dsh.client.inject` 里仍列已退役的 `@deepseek-ai/dsh-client-runtime` | 无功能影响（该字段是信息性依赖声明，不参与模块解析），但元数据失真 | 改为实际依赖的客户端包：`dsh-api-session-controller`、`dsh-client-locale`、`dsh-client-ui-conversation`、`dsh-client-ui-settings`；`dsh-client-ui-primitives` 属平台种子模块表，无需 `external` |
| 4 | ChatHideToggle 的 CSS 命中宿主 CSS-module 哈希类名（`Sxvs8a_body`、`gdEzaW_contextRow`） | 换构建即静默失效（空行折叠、隐藏思考后 body 的 gap 归零） | 改为与哈希无关的选择器：`[class*="_body"]` / `[class*="_contextRow"]` / `:has(> [data-variant="think"])` |

核对后**无需改动**的部分：slot 名与 `register` 选项（`order`/`label`/`locale`/`inject`）、
`ctx.locale.register/bind`、`MarkdownText`（平台的静态种子模块表）、`useSession` 选择器
（`running`/`blank`/`openState`）、header 动作里用于切视图的 `actions.setView` 桥。

## 验证

`e2e/zen-view.mjs`（`npm run e2e:zen`）在 `dsh-e2e` 一次性实例上跑真实 GUI，全部通过：

- Zen 视图标签注册并渲染；视图标签列表 `["Chat","Zen","Trajectory"]`
- Zen 视图显示实时用户消息与 **AI 回复**（走新的 Chat 目标快照通路）
- header 的「隐藏中间过程」按钮注册，点击后 `body[data-chat-hide="on"]`
- `Alt+Z` 双向切换 Chat / Zen
- 设置页出现 Zen Settings 分区
- 自动进出禅：开启后 agent 运行中自动进入 Zen，轮次结束后自动回到 Chat
- 无插件相关 JS 报错（唯一 404 来自内置 `dsh-client-ui-open-in-app` 的资源）

部署层核验：`dsh --profile web --dump-config` 出现 `# == @johnnren/dsh-zen` 命名层与
解析后的 `- id: zen` 行。

截图：`docs/screenshots/e2e-zen-view.png`、`e2e-zen-reply.png`、`e2e-zen-after-altz.png`、
`e2e-zen-settings.png`、`e2e-zen-auto.png`。

## 遗留 / 注意

- 断点 1、2 属 0.2 时代契约，后续升级需对照目标版本源码重新核验（已写入 README 与项目
  AGENTS.md 的兼容性契约小节）。
- ChatHideToggle 依赖宿主稳定 data 属性（`data-chat-flow-kind`、`data-variant`）；0.2 新增
  `turn-process` 行不在隐藏清单内 —— 见 `261011-dsh-02-compat.validation.md` 的用户验证项。
- 本机 live `web` profile 仍未启用本插件；是否上架 live 由用户决定。