dsh-ui-tools

DSH Web 插件：七个 UI 工具合并成一个包，只动对应控件，不改 DSH 任何一行源码。

功能一：模型选择双按钮（原 dsh-model-select-style）

把输入框官方的「模型选择」控件替换为两个独立按钮，两级联动：

1. 「供应商」按钮 —— 点击弹出供应商列表（如 DeepSeek / SiliconFlow / OpenRouter）；
2. 选中某供应商后，「模型」按钮亮起；
3. 「模型」按钮 —— 点击只列出当前所选供应商的模型，点选即切换；
4. 模型支持推理时，模型按钮显示 模型名 · 推理等级（如 deepseek-chat · 高），面板内带「推理等级」区可调节思考强度。

选择逻辑完全复用官方组件（同一份模型目录、同一套选择提交、错误 Toast），只是把入口从单个按钮拆成两个。

功能二：侧边栏工作区折叠/展开（原 dsh-workspace-collapse）

在侧边栏工作区列表下方渲染「折叠全部 / 展开全部」工具条，一键折叠/展开所有工作区分组（纯 slot 渲染 + CSS 对齐，不搬动 DOM）。

功能三：会话标题旁工作区徽章（v0.3.0 新增）

在会话页头部标题右侧显示一个圆角徽章，标出当前会话所属工作区名（与侧边栏分组标题同名），一眼看出当前对话跑在哪个工作区：

• 数据：标准 kit 自带 useWorkspaces，从 workspaces.items 按 sessionIds 反查当前会话所属工作区，取 title；
• 未归入任何工作区（未分组 / 空白会话）时徽章不渲染，不占位；
• 徽章显示工作区显示名（改名后同步），title/aria-label 带可读文案。

实现原理：本功能注册进官方纯增量 list 槽 conversation.session.header.actions（session 作用域）——它是头部标题 cluster 内的动作行，位于面包屑标题右侧，正好是「标题旁」。list 槽是加性的（绝不替换标题、无占用冲突，当前该槽无其他插件占用），我们用负数 order: -100 让徽章排在其它交互动作之前、紧贴标题。纯 slot 渲染，不搬 DOM、不改源码。

功能四：插件设置页「DSH UI 工具」（v0.4.0 新增；v0.4.1 移除快捷命令条）

在官方设置中心新增一个「DSH UI 工具」页面，集中控制本包功能的偏好：

• 布局偏好：工作区徽章开关、启动时默认折叠所有工作区分组、显示输出速度计（tok/s）（v0.4.29 起该速度计为可拖动胶囊悬浮窗，位置自由、双击复位）；
• 偏好经 localStorage 持久化（dsh-ui-tools:prefs:v1），刷新/重启后保持；
• 能力感知（v0.4.2）：速度计依赖的内核服务不可用时（0.1.1-rc.x），那一行开关灰显并在标签下提示「需内核 0.1.2-alpha.1+」，不会出现一个点了没用的开关。可用性由 alphaFeatures 子 fiber 实际激活来置位（比在 apply 期一次性探测更可靠：官方 provider 可能比本插件晚激活）。

> 存储说明：官方 settings 命名空间需要 host 侧 ctx.settings.register(ns, schema) 声明 schema 才能持久化（参考 ui-theme/src/index.ts）；本插件刻意保持纯浏览器（lib/index.js 空入口、不引入 host 依赖与 schema 校验风险），故沿用浏览器插件社区惯例（同款 dsh-better-sidebar）的 localStorage。偏好仅当前浏览器生效；如需跨端/跨浏览器同步，可后续增加 host 半部迁移到 settings 文档。

实现原理：注册进官方 settings.section（root 作用域 list 槽），id: "dsh-ui-tools"、order: 100、label 走双语文案，设置导航自动出现该页。页面组件订阅同一个 localStorage 偏好仓库（useSyncExternalStore），所有开关写入即落盘；既有功能在 apply() 里注入同一偏好仓库：徽章/速度计组件渲染时读开关，侧边栏折叠条在插件加载时按「默认折叠」偏好执行一次。

功能五：输出速度计 tok/s（v0.4.6 新增；v0.4.25 迁到输入框下方统计行；v0.4.27 修结算后消失；v0.4.29 改为可拖动胶囊悬浮窗）

在可随意拖动的胶囊悬浮窗里显示输出速度读数（v0.4.29 起；此前 v0.4.25–v0.4.28 是输入框下方统计行里的固定 pill）：

• 回合结束后（精确值）：显示 ⚡42 tok/s —— 最近一回合的输出速度，无需点开「本轮用时和速度」弹窗即可看到；
• 生成中（估算值）：显示 ⚡≈ 25 tok/s · 生成中估算，随流式增量刷新。

> 与官方底部统计的关系：官方统计行里的 TPS 是全会话口径（全程 decodeTokens ÷ decodeMs），本胶囊是本回合 / 最近一回合口径 —— 两者互补。胶囊是新增控件（注册 id: "ui-tools-token-speed"、order: 2，排在官方 activity(0) / usage(1) 之后，不替换、不覆盖官方任何控件），但 v0.4.29 起它的显示位置由用户自己拖动决定（position:fixed 浮层，挂在 document.body 上，默认右下角），不再绑死在统计行右侧。
>
> 拖动与位置记忆：在胶囊上按住拖动即可移动到任意位置；位置写入 localStorage（dsh-ui-tools:token-speed:pos:v1），刷新/重启后保持；拖出视口会自动夹回可视区（留边距）；双击复位回默认右下角位置。

数值口径（精确值）与内核「本轮用时和速度」弹窗里的 TPS 同源：先定位回合（生成中以外取最大回合，tspLastTurnSpeed；按 messageId 的 tspTurnSpeed 仍保留以兼容既有断言），再折叠该回合全部已固化 assistant 节点。折叠是两级口径（v0.4.27 起）：

1. 解码口径（首选，与内核 deriveTurnMetrics / assistantStepReading 完全一致）：只累计同时带 timing.firstTokenTime 与 usage.outputTokens 的 step，按 ΣoutputTokens ÷ Σ(completedTime − firstTokenTime) 求值；只要该回合存在这类 step，就只用这批算，不让墙钟 step 污染分母。
2. 整步墙钟口径（回退）：真机实测发现内核 legacy 快照里的 assistant 节点 timing.firstTokenTime 恒为 null（连刚流式生成完的回合也是 —— 内核只在 durable log / sessionStats projection 里保留首字时间，客户端窗口的 settled 节点拿不到；官方 ActivityPill 因此走 useProjection("sessionStats") 而非 deriveStats(nodes)）。故所有 step 都缺 firstTokenTime 时，回退到 ΣoutputTokens ÷ Σ(completedTime − stepStartTime)（含首字延迟，数值略低于纯解码速度，tooltip 已注明）。这是历史 / 已固化回合唯一能算的速度，保证结算后读数不消失。

两种口径都算不出（无合法 step、时长为 0）时不显示，绝不猜一个假值。

为什么生成中只能给估算值：内核在流式期间不上报 token 数 —— assistant/live-chunk 里的 usage chunk 被 publication: "none" 抑制，不推给客户端。所以生成中改为读 chat 快照里的 legacy.partial（内核在 assistant-step 运行期持续发布的 {turn, step, blocks}），按已输出字符折算（CJK 1 字符 ≈ 1 token，其余 4 字符 ≈ 1 token；tspBlocksEffort 统计 text / reasoning 正文与 tool-call 的 name+argsRaw），分母只计相邻增量之间的真实出字时间（间隔超过 TSP_LIVE_GAP_CAP_MS=1000ms 的停顿视为等工具/等请求、不计入），并始终带「≈」与「生成中估算」标注，与精确值明确区分；回合一旦结束（partial 消失）即让位给精确值，不重复显示。有效出字时间 < 250ms 或折算 token 为 0 时不显示估算，避免爆表读数。

实现原理（单一通道，不改源码）：注册进官方 list 槽 conversation.composer.dock（session 作用域）—— 保留这个注册点是因为它是拿到 session 作用域标准 props（useChat）的唯一可靠通道（内核槽框架会把 sessionId 连同 useChat 等作为标准 props 注入该槽组件；官方 ActivityPill 就是用 useChat(s => s.legacy.nodes)）。组件 TokenSpeedDockPill 因此直接读标准 props 的 useChat 拿 chat 快照（legacy.nodes 算精确值、legacy.partial 算生成中估算），再用 require("react-dom").createPortal 把 [data-tsp-capsule] 渲染到 document.body 的 position:fixed 浮层里 —— 不再占用统计行的版面，而是可自由拖动的悬浮胶囊。为什么必须 portal 到 body：slot 祖先链常带 overflow:hidden / transform，会裁剪浮层，只有挂到 body 才能真自由。⚠️ 不能写成 inject: (sessionId) => … —— 槽的 inject 回调不接收 sessionId（v0.4.25 踩过此坑：拿到 undefined → 空快照 → 永远不渲染），只能返回 { prefs } 这类注入面。react-dom 属插件模块表允许的依赖（本机已装插件普遍 require("react-dom")），拿不到时组件退化为内联 fixed 元素（仍可拖动）。

> v0.4.29 迁移说明：v0.4.25–v0.4.28 的形态是「统计行里与官方 activity / usage 同行的固定 pill」，位置由内核布局决定、用户改不了。v0.4.29 改为可拖动胶囊悬浮窗（[data-tsp-capsule] 外壳 + [data-tsp-pill] 读数，createPortal 到 document.body），新增 tspReadPos / tspWritePos / tspClearPos / tspClampPos / tspDefaultPos 几何工具与 onPointerDown/Move/Up + onDoubleClick 拖动交互；compat-check 相应补「portal 到 body」「fixed 浮层」「拖动写 localStorage」「夹取/默认位/坏数据回退」断言，并把 require 桩放行 "react-dom"；live-smoke 2c 从「与统计行同行且在右侧」改为「脱离统计行、body 下的 fixed 浮层、真实鼠标拖拽后坐标变化并落盘」。

> v0.4.25 迁移说明：此前（v0.4.6–v0.4.24）精确 pill 挂在 conversation.chat.assistant-actions（order: -10，紧贴「用时」左侧），生成中估算条走 Definition 通道自建 token-speed-live chat 节点 + conversation.chat.node 渲染器。后者因内核「已物化节点被撤回即抛错、整条 chat 快照链停更」（v0.4.7 事故）而成为长期风险面，且 Definition 节点不进 legacy 快照、dock 组件本就读不到。v0.4.25 把两处合并为 dock 里的单条 pill：删除 Definition 通道、conversation.chat.node 渲染器与旧 assistant-actions 注册，生成中改由 legacy.partial 折算 —— 风险面归零、位置也正落在用户要的「几轮几步旁边」。compat-check 相应新增「源码不得再出现 tspLiveDefinition / token-speed-live / tspChunkEffort / data-tsp-live」四条反向钉。

开关：设置页「显示输出速度计（tok/s）——可拖动的胶囊悬浮窗，双击复位」，默认开；偏好字段 tokenSpeedEnabled（同一个 localStorage key）。旧内核上该开关灰显。

> 历史回合的读数口径（v0.4.27 修正）：早期版本认为「firstTokenTime 不进持久化日志、重载后历史回合没有读数」。真机实测否定了这一假设：legacy 快照里的 firstTokenTime 在真机上恒为 null（与是否重载无关），所以只靠解码口径会让每个回合结算后都失去读数（生成中能看到、一结束就消失）。v0.4.27 起改为「解码优先、墙钟回退」两级口径：历史回合显示的是整步墙钟速度（含首字延迟，通常略低于纯解码速度），而不是不显示。

功能六：会话 / 工作区列表右键菜单（v0.4.13 新增）

在侧边栏的会话行与工作区行上按右键，弹出上下文操作菜单。实现参考社区插件 @baihejiangnan/dsh-session-context-menu 的能力面，但代码完全自写——不 import、不 require、不引用对方的包名与全局注册表，也不依赖对方的事件名（已由断言钉死）。

会话行右键（7 项，v0.4.20 新增「删除会话…」）：

工作区行右键（5 项）：新建会话（uiWorkspace.startSession(id)）、复制工作区路径（workspace.path → 剪贴板）、归档工作区全部会话（逐个 archiveSession）、删除工作区全部会话（二次确认后真删磁盘，见下节）、刷新页面。

> ⚠ 服务契约（v0.4.13 首发踩过的坑）：新建会话 只能走官方 uiWorkspace.startSession(id) —— sessions 上没有 startSession；切会话同理只能走 uiWorkspace.openSession(id)，sessions 上那个 open 不收会话 id。首发版误写成 workspaces.startSession / sessions.open，异常被 ctxToast 吞掉，用户看到的就是「点了没反应」。现在由 tools/check-context-menu.mjs 第 14 节的真实方法表逐条钉死。

选中文本时右键（2 项）：复制所选文本、发送所选文本到输入框（填入输入框，不自动发送）。

删除会话（v0.4.20 新增；v0.4.21 改走 connection.fetch）

「归档会话」只是把 id 记进 archivedSessionIds，磁盘上的日志一个字节都不动；要真正腾空间、把会话从磁盘上抹掉，需要「删除会话」。

内核没有删除会话的 RPC。 逐个核过 session/*（20 个方法）与 workspace/*（12 个方法），既无 delete/remove，也没有任何渲染进程可用的文件操作通道；workspace/delete 的描述是「移除一个工作区登记，保留文件与会话」。社区插件 dsh-plugin-session-delete 的 README 结论相同："Core has no deleteSession RPC, so this plugin adds a small host-side HTTP route that performs the durable deletion"。

本插件的做法：宿主半边 + 客户端半边，走内核 connection 服务提供的 Fetch 路由。

几个必须说清的设计取舍：

• 不用裸 webServer.register() 路由。 社区插件那条 POST /api/session-delete 完全不鉴权（webServer 的 exact 路由在分发时直接命中 handler，不经过 frontend-static 也不经过 authorizeIndex），任意网页都能对它发一条跨站表单请求把用户磁盘上的会话删掉。本插件改走 connection.fetch.register()：请求先经过 connection 的 /api 共享处理器 —— Host/Origin 栅栏（403）→ 浏览器 cookie 鉴权（401）→ 得到 principal.kind === "owner" 的 peer，handler 里再显式核一遍 peer.principal.kind。安全边界在内核里，不在插件里。
• connection 只加在宿主半边的子 fiber，客户端仍走 ctx.get() 可选获取。 入口 inject 一个字节没改（仍是 slots / modelDirectories / sessions / locale / workspaces），所以旧内核上功能六照常可用，只是「删除会话」会给出明确原因「当前内核未提供插件通道（connection），无法删除会话；请升级内核，或改用『归档会话』」——不做功能级静默隐藏，也不拖垮整条 fiber（R3）。
• sessionPersistence / sessionQuery / agents / workspaceRegistry 全是可选服务，逐个 ctx.get() + 能力探测；缺席时只让这条端点报错，不影响插件启动。
• 删完不调 workspaces.archiveSession()。 archiveSession 第一步是 await this.sessionKnown(id)，文件已删 → 查不到 → 抛 WorkspaceUnknownSessionError。删完之后的收尾是三步：workspaces.stopSessionActivity(id)（停宿主侧活动）、若是当前会话则 uiWorkspace.clearMain()（释放主视图引用）、sessions.refresh()（重拉列表基线，行才会消失）。
• 二次确认是硬门槛。 菜单项点下去不会立刻发请求，而是弹出一个与客户端同款的 Modal 弹窗（v0.4.24 起：遮罩 + 居中卡片 + 右下角横排按钮，见下节），点名要删哪个会话、写明不可撤销，危险按钮在最右、默认焦点落在「取消」，「取消」/ Esc / 关闭键 / 点遮罩都能取消。断言钉死「确认前发出的删除请求数 = 0」。
• 失败不装作成功。 服务端拒绝（not found / forbidden / 落盘定位失败）时把真实原因显示给用户，且不摘掉列表行——避免「看起来删了其实还在」。通道缺席时同样给可读提示，不泄漏内部 TypeError。
• 宿主路由不存在时说「请重启 DSH」，不说 HTTP 状态码。 宿主进程只在启动时装配一次 profile（dsh-desktop-host 的 main() 里跑一遍 runProfile），没有热重载。装完插件不重启，/api/ui-tools/sessionDelete 这条路由根本不存在：/api 前缀路由在、精确子路由不在，于是内核回 404（若整条 /api 都没挂则掉进 frontend-static 兜底的 405）。所以客户端把这两种非业务状态码统一识别成 no-host，提示「插件宿主半边未加载（宿主进程只在启动时装配插件）……请重启 DSH 后重试」。否则用户看到的是一句没头没脑的 删除失败：405 method not allowed，根本不知道该去重启。

> ⚠ 已知边界：正在生成中的会话被删后，宿主 agent 可能在收尾时重建日志（插件已尽力先 cancel，但这是尽力而为）；工作区里残留的 id 由内核下次对账时自愈（groupByWorkspace 对 list.byId[id] === undefined 直接跳过，不会渲染死账）。
>
> ✅ v0.4.23 起会级联删除子会话分支（见下节「子会话级联」），并且删除过程有逐条进度。
>
> ⚠ 装完必须重启 DSH（不是刷新页面）。宿主半边是新写进 lib/index.js 的，只同步文件不重启，菜单会出现但点了只会提示「宿主半边未加载」。

删除工作区全部会话（v0.4.22 新增）

右键工作区行 → 「删除工作区全部会话…」。它是「归档工作区全部会话」的彻底版：归档只记账，这里真删磁盘。

• 一次请求删一批，不循环调单删端点。 宿主新增精确路由 /api/ui-tools/sessionsDelete，与单会话端点共用同一个 registerDeleteRoute(path) 工厂（一次删一个 = 只含一项的批量，两条路径的行为不可能分家）。之所以不在客户端 for 循环调单删端点：几十个会话就是几十个 HTTP 往返，而且中途失败时说不清「停在哪一个」，用户只能看到列表莫名其妙少了一半。
• 串行删，不并发。 每个会话的删除都要先停 agent、再动工作区记账、最后递归删目录，并发会互相踩；串行才能给出可解释的逐条结果。
• 失败不吞。 返回 {ok:false, error:{code:"partial", details:{deleted, failed}}}，客户端拼成「已删除 N 个，M 个失败：<真实原因>」；全失败时则直接透出第一条失败的业务码与原因。绝不因为「一条失败」就把整批显示成「删除失败」而让人以为一个都没删掉。
• 载荷同时兼容两种形态。 新的批量端点和旧的单会话端点都调 readDeleteBatchPayload()：先看 sessions 数组，没有才退回顶层 {sessionId, cwd}。这样只重启了一半（包更新了但进程还是旧的）也不会打通了一个、坏了一个。条目上限 200 条，超了直接 400 而不是让宿主跑十分钟。
• 确认弹窗点名数量。 「删除「项目一」的全部 5 个会话？」+ 「这些会话记录会从磁盘上永久删除，无法撤销。工作目录里的文件不受影响。」——明确区分「删会话记录」与「删工作目录文件」，避免用户以为会把代码目录一起端掉。id 列表为空时点下去只给一句提示，不弹确认弹窗。

> ⚠ 与单会话删除同一条已知边界：正在生成中的会话、以及会话分支的子会话不会被级联处理。

子会话级联删除（v0.4.23 新增）

「创建会话分支」建出来的子会话，单独删父会话会留下孤儿分支——它们仍在列表里、仍占磁盘，但已经失去了上游上下文。v0.4.23 起删父会话时会连整棵子树一起删。

• 血缘链完全在客户端就能算出来，不需要新 RPC。 逐行核过内核：dsh-session:2017 fork 时写入 header.parentSession → dsh-api-session-controller:2129 投影成条目字段 parentSessionId → 客户端 service.js:512 再投影成摘要的 parentId。也就是说 sessions.list.getSnapshot().items 里每条摘要本来就带 parentId，拼成 parentId → [childId] 就能 BFS 出整棵子树。新增的纯函数 ctxDescendantSessionIds(sessions, parentIds) 就干这件事：多根、多兄弟、血缘成环（脏数据）不死循环、快照读不到时返回 []（级联是附加能力，绝不能因为它而弄坏删除本身）。
• 确认弹窗必须说清楚要多删几个。 有子会话时正文换成「该会话下还有 N 个子会话分支，会一并删除。」——在用户点『永久删除』之前就把级联的代价摊开，而不是删完再告诉人家。没有子会话时逐字沿用旧文案，不吓唬人。
• 有子会话就走批量/流式端点，没有就走单会话端点。 单会话端点一次只能删一个，级联必须多次往返；所以有子树时改调 /api/ui-tools/sessionsDeleteStream。没有子树时载荷逐字不变（仍只发 {sessionId, cwd}），v0.4.20 的老契约一个字没改。
• 工作区批量删除也会顺手把「跨工作区的子会话」带上。 一个从 w1 的会话 fork 出来、后来被归到 w2 的子会话，在 w1 的 sessionIds 里是看不到的——只按 sessionIds 删就会漏。所以工作区删除同样先做一次级联展开再取并集，确认弹窗上的数字是展开后的真实条数。
• origin 字段不参与判据。 内核 dsh-session:1053 里 origin 只允许 "subagent"，但用户手动 fork 出来的分支 origin 是空的；只认 origin 会漏掉手动分支，故判据只用 parentId。

批量删除进度（v0.4.23 新增）

删 20 个会话在真机上要好几秒（每个都要先停 agent、再动工作区记账、最后递归删目录）。这期间如果界面只有一句「正在删除…」，用户会以为卡死并反复点击。

• 宿主逐条推进度，客户端逐条刷提示。 新路由 /api/ui-tools/sessionsDeleteStream 返回 NDJSON（application/x-ndjson，一行一个 JSON），deleteSessions() 每删完一个就 onProgress({done, total, sessionId, ok, code?, message?})，宿主随即写出 {"type":"progress", …}；全部结束后写 {"type":"done", …}（内容是和非流式端点完全一致的 deleteEnvelope()）。
• 为什么是 NDJSON 而不是 SSE。 EventSource 只能发 GET、带不了请求体，而这条端点必须收 sessions 数组；所以用 fetch + ReadableStream 手切行。响应头带 x-accel-buffering: no，防止中间层把流攒起来一次性吐出（那样进度就成了假的）。
• 进度是真的数出来的，不是按时间估的。 断言直接钉住「3 个会话 → 恰好 3 次进度回调」且 done 逐次为 1,2,3，并附带静态钉「宿主 deleteSessions 里必须有 onProgress({done: 调用」+ 文本变异负向对照。
• 老宿主自动降级。 如果这个进程还是 v0.4.22 的旧半边（没有流式路由，返回 404/405），客户端会立刻退回去打一次性批量端点，删除照常成功、只是没有进度。断言把这条降级路径单独跑了一遍。
• 客户端断开不等于删除要停。 流写到一半用户关标签页，controller.enqueue 会抛错；宿主把它吞掉并继续把剩余的删完——中止到一半留下的半删状态比多删几秒更难收拾。

删除确认弹窗（v0.4.24 重做）

v0.4.20 ~ v0.4.23 的二次确认是「菜单原地换成一条确认条」——样式复用右键菜单、按钮竖排成菜单项。真机用下来两个问题：

1. 观感一眼外挂。 内核自己的确认框（「停止并归档此会话？」「删除工作区」）用的是同一个 Modal primitive：遮罩 + 居中卡片 + 标题 + 正文 + 右下角横排按钮。插件的确认条长得像菜单，跟它并排看就是两套东西。
2. 位置偏右。 旧代码把 window.innerWidth / 2 当成左上角传给 ctxPositionMenu(root, x, y)，而那个函数收的正是左上角坐标（left = max(6, min(x, innerWidth - width - 6))）——于是整个框从屏幕正中开始往右铺，再被视口右边夹住，看起来就是贴着右半边。

重做后的做法：

• 位置完全交给 CSS。 根节点 position: fixed; inset: 0 + display: flex; align-items: center; justify-content: center，卡片 width: min(380px, 100%)。ctxConfirmDialog 里再也没有 ctxPositionMenu / innerWidth —— 这两条都有静态钉 + 文本变异负向对照（把坐标计算塞回去必须报红）。
• 结构、尺寸、间距照官方 Modal 抄。 类名 .dsh-ctx-confirm__mask / __dialog / __header / __title / __close / __content / __body / __footer，头部 padding: 22px 14px 12px 24px、标题 16px/24px 中等字重、正文 padding: 0 24px + 14px/22px、页脚右对齐 gap: 8px、圆角 --dsw-radius-panel、阴影 --dsw-elevation-prominent、底色 --dsw-alias-bg-layer-2 —— 全部取自 dsh-web-frontend 里那组 _root_ / _mask_ / _dialog_ / _header_ / _title_ / _content_ / _description_ / _footer_ 规则，所以深浅主题都跟客户端自洽。
• 颜色一律走 --dsw-* token，缺了才掉回兜底色。 危险按钮用 --dsw-alias-state-error-primary —— 与官方删除确认里的 deleteAction 是同一个 token。
• 按钮照官方 Button 的 md + outline 规格。 36px 高、0.5px solid var(--dsw-alias-border-l3) 描边、14px/22px 字、圆角 --dsw-radius-md；顺序与官方 footer 一致：取消在左、危险动作在最右。
• 三种关窗方式都算取消，且一个请求都不发：点「取消」、按 Esc、点右上角关闭键、点遮罩空白处。点卡片正文不会误关（事件挂在遮罩上而不是根节点上，卡片不是遮罩的子节点）——否则用户想选文字复制都会把弹窗点没。
• 断言从 196 条加到 228 条：新增 §16 整节，含弹窗语义（role="alertdialog" 在卡片上而非根上）、遮罩存在、不再复用 dsh-ctx-menu、按钮顺序（取消在左 + 危险在最右）、关闭键/遮罩/卡片正文三种点击行为、以及「弹窗里用到的每个类名都必须在 CTX_CSS 里有定义」（防止改了 JS 忘了改 CSS 导致掉回无样式观感）。负向对照 2 条：抽掉 justify-content: center 后居中钉必红；把坐标计算塞回 ctxConfirmDialog 后「不再算坐标」两条钉必红。

⚠ 为什么用 connection.fetch 而不是 connection.rpc

v0.4.20 首发用的是 connection.rpc.handle("/ui-tools", handler) + 客户端 connection.rpc.call(...)。真机上必然失败，报：

register-failed: cannot get property "webServer" without inject
at Fiber. (…/dsh-client-connection/lib/index.js:871:35)
at Object.handle (…/dsh-client-connection/lib/index.js:727:39)

原因在 dsh-client-connection 自己身上：

// :724  rpc getter —— owner 取的是 Connection 服务自己的 ctx
get rpc() { const owner = this.ctx; return { handle: (channel, handler) => this.register(owner, channel, handler) }; }
// :871  register 的最后一行 —— 拿 owner.webServer 去挂路由
return owner.effect(() => owner.webServer.register(route), `client-connection: ${channel} rpc channel`);
// :1013 而该插件自己的入口 inject 里没有 webServer
const inject = ["credentials"];

于是任何第三方插件调 rpc.handle 都会在 owner.webServer 上抛「without inject」，rpc 通道这条路对插件彻底关闭。（宿主侧 webServer 和这完全是两回事：ctx.inject(["webServer"], …) 在自己的子 fiber 里拿是拿得到的，但那条路由不经过鉴权，见上一节。）

connection.fetch.register(route) 走的是另一条链（registerFetchRoute，:840-854）：它只往内部的 fetchRoutes Map 里塞一条精确路径，完全不碰 webServer，返回 disposer，天然满足 R3/拆卸纪律。约束有三条：

1. 路径必须以 /api/ 开头（assertFetchRoute → endpointFromPath("/api", path)），且挂在 /api 那条 prefix 路由上按 pathname 精确匹配；
2. methods 非空不重复；
3. 处理函数是标准 (request: Request, peer) => Response，body 由内核按 requestBody: "buffered" 缓冲好。

> ⚠ peer 根本不会传进来。 createSharedFetchHandler（dsh-client-connection:820-839）在鉴权通过后写的是 return route.fetch(request) —— 只传 request（:831），形参声明成 (request, peer) 的那个 peer 恒为 undefined。v0.4.20/0.4.21 第一版就在这里翻车：handler 开头写了「peer.principal.kind !== "owner" 就回 403」当作纵深防御，结果每一次删除都被自己拦成 403，而且报错文案还是「只有本机会话可以删除会话」，看上去像鉴权在起作用，实际是插件把自己关死了。现在断言钉死：宿主 async fetch( 的形参个数必须为 1，且源码里不许出现 peer.principal（附负向对照：把签名改回 (request, peer) 后该断言必须变红）。鉴权已由内核完成且更严——传输层 admit() 做 Host/Origin 栅栏与 cookie 鉴权，授权层 :830 对非 owner Peer 直接 403。

已由断言钉死：宿主必须出现 connection.fetch.register(，且不许出现 rpc.handle(；客户端必须 fetch(ctxDeleteUrl(), …) 且 SESSION_DELETE_PATH 全文件只出现一处；宿主导出 DELETE_ROUTE_PATH = "/api/ui-tools/sessionDelete" 与客户端常量逐字一致；运行时逐项核对 URL（同源绝对地址）/ method / credentials: "same-origin" / content-type / body.sessionId / body.cwd。

为什么客户端拼同源绝对地址而不是相对路径：相对路径把「同源」交给运行环境解释，Node 测试沙箱里 fetch("/api/…") 直接 TypeError: Failed to parse URL —— 断言只能看到同一句无意义报错，等于测了个寂寞。ctxDeleteUrl() 先取 window.location.origin 拼绝对地址，取不到才退回相对路径。

目标识别：为什么不能用 aria-label

判据是官方渲染时写死的 data-row-key 前缀 —— session: / workspace:，不看 aria-label、不看界面语言。这一条来自参考插件注释里指出的坑：官方 row-actions 按钮在空白会话与已归档会话上根本不渲染，若靠「这一行有没有『会话操作』按钮」判定，这类行会被判成非会话行，菜单直接退化、拿不到 session。（同一结论、自写实现。）

解析：三级降级 + 唯一性保护

ctxResolveSession(sessions, row, workspace) 依次尝试：

1. DOM 行 id —— data-row-key 命中，最可靠；
2. 当前选中行 —— aria-selected="true" 时取 store 的 current；
3. 标题兜底 —— 按 aria-label / title 在库中匹配，只在唯一命中时采用。

任一级无法唯一确定就返回 null，调用方据此保留浏览器原生菜单 —— 绝不猜。 尤其第 3 级：标题命中多个会话时同样返回 null，宁可不管，也不操作错会话。

实现原理（纯 DOM，不注册 slot）

• 只挂 document 级 三个监听：contextmenu、pointerdown、keydown；菜单节点 appendChild 到 body；
• 不注册任何 slot，因此旧内核上也照常可用（无 alpha 依赖，不进 alphaFeatures 子 fiber）；用到的 sessions / workspaces 本就在入口 inject 里，官方 uiWorkspace 走可选获取（ctx.get("uiWorkspace")，缺席时返回 undefined 并降级）—— 绝不把可选服务写进入口 inject（见下方说明，守 R3）；
• R2 合规：不搬动、不包裹 slot 渲染出来的任何节点，无 MutationObserver、无轮询定时器 —— 菜单节点是本插件新建的，不是搬运既有节点；
• 全部监听由 installContextMenu() 返回的拆卸函数解除，插件卸载后不留补丁（断言逐项核对 contextmenu / pointerdown / keydown 三类监听是否解绑干净）；
• 动作抛错被捕获并转成提示，不冒泡成未捕获异常；事件已被 preventDefault() 时不再接管，与其他右键类插件共存不打架。

⚠ 为什么 uiWorkspace 必须走可选获取，不能写进 inject

这是 v0.4.13 首发后真实发生的一次事故，代价是六个功能全部消失：

uiWorkspace 由官方 dsh-client-ui-workspace 提供，在精简 bundle / 旧内核里可能不存在。cordis 的 inject 数组语义是「必须等到这些服务就绪才开始」，任何一个等不到，整条 fiber 就停在 PENDING —— 所以把 "uiWorkspace" 加进入口 inject 的后果不是「右键菜单少一个功能」，而是：

dsh-ui-tools: pending (waiting for services: uiWorkspace)

即插件整体不激活：五个既有功能一起消失 + 顶部加载横幅，boot 审计报 1 entry did not activate。用户看到的现象是「右键菜单里的项都没效果」——极易误诊成菜单自身的事件 bug，实际菜单根本没装上。（这与 v0.4.2 在 uiConversation 上踩的是同一个坑。）

正解 —— 在子作用域里可选获取，配能力探测干净降级：

ctx.inject(["sessions", "workspaces"], (scope) => {
const uiWorkspace = ctx.get("uiWorkspace");   // 缺席时是 undefined，不抛错
// 每个调用点都探测：typeof uiWorkspace?.startSession === "function"
});

ctx.get(name) 在服务缺席时返回 undefined 而不抛错（cordis 内部 const impl = key && this.store[key]; if (!impl) return;），因此这条路径是干净的降级而不是崩溃。

已由断言钉死：把 "uiWorkspace" 塞回入口 inject，compat-check 从 101/101 掉到 50/85，并精确报出 pending (waiting for services: uiWorkspace)。

交互与无障碍

role="menu" / role="menuitem"、tabindex="-1" + roving tabindex（打开即聚焦首项）；支持 Esc 关闭、↑/↓ 移动、Home/End 跳转、点击菜单外部关闭；归档等危险项走独立样式类 dsh-ctx-item--danger；空菜单被拒绝，不会弹出一个空白方块。

开关：设置页「会话 / 工作区列表右键菜单」，默认开；偏好字段 ctxMenuEnabled。关掉时一根监听都不挂，浏览器原生右键菜单原样保留；门控显式订阅偏好仓库，因此改开关即时生效、无需刷新页面，卸载时订阅与监听一并清理。

功能七：待办进度面板（v0.4.30 重构，取代 v0.4.28 的「待办清扫」）

v0.4.28 的初版把功能七做成了「回合结束后隐藏仍在转圈的待办面板」。用户实测后指出理解错了：
真正的问题是「待办列表不按进度更新状态」——模型写完一次 todo_write 之后就不再维护，列表永远停在
「进行中」；同时官方面板折叠时只显示一行汇总，不展开就看不到每项的状态。v0.4.30 按这两条重做。

根因：todos 投影的 host 端 reducer 只处理两个事件——todo/write 覆盖、turn/start 清空；
回合结束 / 停止 / 出错都不对账，模型不重写就冻结在最后一份快照。而官方 TodoPanel 里
!collapsed && —— 折叠时每项状态点根本不进 DOM。插件改不了 reducer（todo_write 在 tool / host 侧，
client 侧无写入通道），只能做展示层推断 + 恒展开渲染。

做法

在同一个 conversation.input.dock 槽位挂一个镜像进度面板 TodoProgressDock（id="ui-tools-todo-progress"，
order 30，不同 id 不替换官方 todo 的 order:0）：

1. 组件从标准 props 读 useProjection("todos")（待办清单）与 useProjection("sessionStats").steps（助手步数）；
2. 用 tswSignature 认出「同一份列表」，记下它首次出现时的步数基线，之后按
   tswAdvanceFromSteps(stepsSince, TSW_STEPS_PER_ITEM=2) 每 2 步推进一项（回合收尾至少 +1）；
3. tswDeriveStatuses(todos, advance, running) 把推断结果叠加到内核状态上，三条硬约束：
   内核已判 completed 的项绝不降级、运行中不把最后一项也判完成、空闲时不新造 in_progress；
4. 面板始终展开，每项渲染 [data-status] + 状态点 + 文案，折叠态看不到的问题从根上消失；
   头部给「N 已完成 · N 进行中 · N 待处理」汇总，推断生效时带「按步数推断」小徽标；
5. 渲染时给 ` 打data-ui-tools-todo-mirror="on"，共享样式标签的TSW_CSS单条规则html[data-ui-tools-todo-mirror] [data-testid="todo-panel"]{display:none !important}` 隐藏官方本体，避免双层；
6. 卸载 / 关开关时 useEffect cleanup 摘掉属性，官方待办面板原样恢复；
7. 宽度与输入框卡片严格对齐（v0.4.31）：镜像面板在 conversation.input.dock 里是独立块级元素，
   width: calc(100% - 16px) 会按整列宽铺开、比输入框宽出一大截，所以改用内核自己的 composer 变量
   width: calc(100% - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-side-clearance,16px))
   再配 max-width: var(--dsh-composer-card-max-width,952px)——与输入框卡片同宽同左右边；
   变量缺失（旧内核）时回退 16px/952px，仍是同级合理宽度。

设计取舍

• 只做展示层：不写回任何投影、不拦内核请求、不轮询清理；推断只影响这一份镜像的渲染；
• fail-open：useProjection 缺席或 todos 非数组时不渲染镜像、不打属性（官方面板照常）；
• 不搬 DOM、无 MutationObserver、无轮询定时器（R2 铁律）：副作用只有 `` 属性 + 一条 CSS 规则；
• 不用 :has() / 内核哈希类名：选择器只含 [data-testid="todo-panel"]（官方自家测试锚点）与自有属性。

开关：设置页「会话待办 → 显示待办进度面板（始终展开每一项，按进度推进状态）」，默认开；偏好字段 todoSweepEnabled。
断言：compat-check 场景 B4（注册位/默认值/推断口径/不降级/副作用矩阵/fail-open/卸载清理/反向钉）+ live-smoke 2d（CSS 契约与属性自洽）。

实现原理

• 官方模型组件照常注册在 conversation.input.model（数据/提交逻辑原样保留），用 CSS 隐藏官方触发按钮；
• 本插件通过 modelDirectories 服务读取同一份模型目录（groups = 供应商分组），注册到 conversation.input.right（list slot）追加双按钮；v0.4.4：该子作用域必须同时声明 remote 和 remote.session——内核对 directoryFor() 的实现会在调用方上下文里读 this.ctx.remote.session（cordis 的 Service tracker 会把 service 的 this.ctx 重绑到调用者），而 remote.session 是嵌套追踪服务，只声明 remote 仍会抛 cannot get property "remote.session" without inject；
• 选择模型/推理等级时调用官方 directory.select(...)，官方 store 同步更新，输入框状态与原生一致；
• 折叠条注册到 sidebar.footer.action——官方渲染位置就是 footer 顶部、紧贴工作区列表正下方，用 CSS（对齐 --dsh-session-list-edge-inset 内边距）贴合列表即可，不搬动 DOM。搬动 slot 渲染出来的节点会与框架重渲染互相触发，导致渲染进程 100% CPU 卡死（v0.1.0 全局观察器、v0.1.2 收窄观察器均因此卡死；v0.1.3 起彻底不搬）。

• 跨内核分层（v0.4.2；v0.4.9 收窄）：uiConversation 是 0.1.2-alpha.1 才引入的 client target 体系服务，旧内核 store 里没有它的提供方。因此这个硬依赖不写在 loader entry 的 inject 上（写了会让整个 entry 停在 PENDING，被 boot 末尾只遍历 ctx.loader.entries() 的审计判为失败 → web boot: 1 entry did not activate + Failed to load plugins 横幅，其余功能一起丢），而是收进 ctx.plugin(alphaFeatures) 子 fiber：入口层只声明五个跨内核服务，功能五（速度计）整段注册（chat target 取数、conversation.composer.dock 注册、TSP 文案）放在子 fiber 内，alphaFeatures.inject = ["uiConversation"]。旧内核上该子 fiber 停在 PENDING——cordis 不执行其函数体、不注册其 effect、也不计入审计，服务（哪怕延后出现）就绪时自动激活，并随 entry dispose 一并释放。渲染方式完全不变（纯 slot，无观察器/定时器）。

• 工作区徽章注册进 conversation.session.header.actions（见功能三）。

• 设置页注册进 settings.section（见功能四）；所有偏好走 apply 期创建的一次性 localStorage 偏好仓库，组件经 useSyncExternalStore 订阅。
• 待办进度面板注册进 conversation.input.dock（见功能七）：镜像面板（每项状态始终可见 + 按步数推断推进）+ ` 属性 +TSW_CSS` 隐藏官方本体，无 Observer、无定时器。

七个功能各自独立命名空间（locale / slot id / data-* 前缀），互不干扰。

> v0.4.9 移除「修改的文件」选项卡：它原本注册进官方 conversation.view 槽（v0.2.0 引入、v0.4.9 整体删除）。移除原因：其取数是同一份 chat target 快照的又一遍解析，与速度计重复；维护成本集中在 run_code 内嵌路径提取这类易碎逻辑上（模板串、变量拼接、shell 级写操作都解析不了）。随之下线的还有 uiSession.provide 暴露的 useModifiedFiles hook、workspaces.openPath 打开链路、mfsCompact 偏好与 conversation.view 槽注册——alphaFeatures 子 fiber 的 inject 因此收窄为 ["uiConversation"]，跨内核降级机制本身完全未变。

内核兼容矩阵

> ¹ 「更新」指 同属 0.1.2-alpha.1 之后的发布线（0.1.2-alpha.1 / 0.1.2-* / 0.1.3-* / 0.1.5-* / 0.1.6-* 及更高）。DSH 的预发布版按 semver 只与同一 x.y.z 元组比较，所以字面区间 >=0.1.2-alpha.1 在真实 semver 下并不匹配 0.1.5-rc.2——本包因此按发布线逐条声明，而不是写一个连续区间，详见下节。

机器可读的内核约束（engines.dsh）

package.json 同时声明两处（生态两种写法都在用，值必须一致）：

"engines":      { "dsh": "^0.1.1-0 || ^0.1.2-0 || ^0.1.3-0 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0 || >=0.3.0-0" },
"dsh": { "engines": { "dsh": "^0.1.1-0 || ^0.1.2-0 || ^0.1.3-0 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0 || >=0.3.0-0" } }

• 谁在读：dshmarket 的 manifestFacts() 读顶层 engines.dsh，缺失时回落到 dsh.engines.dsh；市场会据此在 Discover 页展示宿主兼容性，并在安装/更新前直接拒绝判定为不兼容的版本（deriveHostCompatibility → incompatible → 400）。
• 生效范围（请如实理解）：市场是按 npm 包名向 registry 取这份事实的。本包目前以 github:qgx1992/dsh-ui-tools 分发，而该更新路径对 git 源不查 registry（usesNpmUpdateTarget = !restore && !isGit）；且 dsh-ui-tools 这个 npm 名字属于他人（另一作者的插件，无此声明）。所以这条声明当下的作用是统一生态惯例、并为将来可能的 npm 发布备好，不构成本机 github 安装路径的运行时保险——本包的旧内核自动降级是靠 alphaFeatures 子 fiber 实现的（见上），与这条声明无关。
• 为什么是逐条发布线而不是 >=0.1.1-rc.1：semver 的预发布规则要求预发布版本只匹配同 x.y.z 的区间，因此 >=0.1.1-rc.1 会漏掉 0.1.2-*、0.1.5-* 等线；^0.1.N-0 每项覆盖一条线，末项 >=0.3.0-0 兜住此后所有新线，且不硬顶未来内核（把未来内核误判为不兼容会让市场拒绝合法升级）。
• -0 后缀的作用：^0.1.1-0 的下界取该线最早的预发布，否则区间会被预发布规则排除。
• 该区间已对 npm 上全部 29 个已发布内核版本 + 3 个未来哨兵逐项断言，并保证普通 semver 语义与市场侧 includePrerelease 语义判决一致（见下「自检」）。
• v0.4.8 修正：此前区间写作 … || >=0.1.6-0，其末项在普通语义下不覆盖任何 0.1.7-* / 0.2.0-* 预发布版（只在 includePrerelease 下才成立），实测有 6 条分流（0.1.7-alpha.1/2、0.1.7-rc.1/2、0.2.0-rc.1/2）。原因同上一节：预发布版只与同 x.y.z 的元组比较，而 >=0.1.6-0 的下界落在 0.1.6 线。更隐蔽的是——当时 0b 的版本表只列了 21 个，恰好漏掉整条 0.1.7/0.2.0 线，于是「两种语义判决一致」那条断言假绿。现改为逐条发布线 ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0 || >=0.3.0-0 并全量列表，令同类裂缝无处可藏。

> 验证口径：node tools/compat-check.mjs 跑在本机已装内核副本的真实 cordis 上（v0.4.32 实测 127/127 全绿；断言计数随内核枚举动态变化，门槛是零 FAIL 而非某个具体数字，因此别把它当固定指标读。另注意它需要 DSH_CORDIS_ENTRY / DSH_SEMVER_ENTRY 指向可用的 cordis 与 semver——本机可指向仓库内 .scratch/kernel/...），场景断言七个功能的槽位注册、子 fiber 状态与 boot 审计口径；B3 自 v0.4.25 起改为「Definition 通道已移除」的源码反向钉（不再逐内核驱动装配器）；B4 自 v0.4.30 起覆盖功能七待办进度面板（注册位/纯函数推断口径/不降级/副作用矩阵/fail-open）。真机（浏览器）行为另由 tools/live-smoke.mjs 覆盖（含 2c 功能五胶囊浮窗契约与 2d 功能七待办进度面板 CSS 契约），需自备 URL+token。

> profile 安装漂移：tools/check-profile-drift.mjs 会比对 ~/.dsh/profiles/*/ 三处口径——package.json 的声明、pnpm-lock.yaml 的 specifier 与 resolved 版本、node_modules 里实际安装的版本。三者不一致时必须先修 profile，否则「改了代码、刷新页面、毫无变化」——因为真实 GUI 跑的是 profile 里的安装副本，而 compat-check.mjs 读的永远是仓库 lib/client.js，两者是两份文件。

自检

node --check lib/client.js       # 语法
node tools/check-hooks-order.mjs  # Hook 顺序钉：条件 return 不得夹在 Hook 之间（防 React 卸载期抛错）
node tools/check-model-seat-hug.mjs  # 功能一「座位紧贴听写按钮」的选择器回归钉（手写 DOM 骨架 + 求值真实 CSS）
node tools/check-context-menu.mjs    # 功能六右键菜单钉：判据/三级降级/菜单组装/事件分发/键盘/拆卸/开关门控（手写 DOM 测试台）
node tools/check-profile-drift.mjs   # profile 安装漂移钉：声明 / lock / 实装三者须一致
node tools/compat-check.mjs      # 内核自适应回归（真实 cordis，场景 0/0b/A/B/B2/B4/B3/C/D + 速度计组件/口径断言）
node tools/live-smoke.mjs    # 真机冒烟（可选；自动探测本机 Chrome/Edge）
# 或一次跑完：npm run check

tools/check-hooks-order.mjs 专治一类只在特定状态切换时才炸的崩溃：React 靠「Hook 调用顺序 + 数组下标」识别 Hook，而它从不清空 hook 数组，只按 hookIndex++ 覆盖——于是 if (!cond) return null; 夹在两个 Hook 之间时，cond 为假的那次渲染里后续 Hook 槽位残留上一次的值（若上次该槽是 undefined，卸载时 React 执行 destroy() 直接抛 undefined is not a function）。脚本用纯词法扫描（不引入 babel/typescript，守 R6）切出每个函数组件的函数体、跟踪最外层 return 与 useXxx( 调用的相对位置，命中即 FAIL；并自带双向负向对照（违规样例必红 + 合规写法不误报），确保断言本身不会退化成同义反复。

tools/check-context-menu.mjs 用手写 DOM 测试台（零依赖，不引 jsdom）跑功能六的 228 条断言：从 lib/client.js 里按花括号配平取出真实函数注入沙箱执行，并把 CTX_ZH 词典求值出来做文案核对（断言看的是用户真正会看到的字，不是 stub 返回的键名）。覆盖判据识别（含「工作区行不被误判成会话行」）、三级降级与标题歧义必须返回 null、菜单组装与空菜单拒绝、三类目标的右键分发、键盘与外部点击、卸载后三类监听全部解绑且补丁摘干净、动作真的调到官方服务而非空壳、动作抛错不冒泡、不引用参考插件包名、CSS 并入共享标签、开关门控语义，以及 v0.4.20 的删除会话全链路（二次确认不可跳过、载荷字段逐字正确、宿主半边路由常量与客户端一致、connection.fetch.register 而非裸路由也非不可用的 rpc.handle、可选服务确实没进 inject、删完不调 archiveSession 而调 stopSessionActivity + clearMain + refresh、失败不摘行、通道缺席给可读原因）。v0.4.21 起沙箱额外注入 location 与 fetch 两个形参（Node 无全局 location；不注入 fetch 时相对 URL 会直接 TypeError: Failed to parse URL，断言只能看到同一句无意义报错），并用可编程的 fetchRoutes 路由表模拟宿主行为 —— 未注册路径回 405 就是「宿主没重启」的真实形状。calls.deleted 与 fetchCalls 是同一个数组，且它全局共享：负向对照必须先 const since = fetchCalls.length 再 slice(since) 取新记录，否则读到的是上一个用例的正常 URL，对照会假绿（踩过）。负向对照必须真的变红：判据改坏的方式是把源码文本改掉后重新编译沙箱（给 env.ctxSessionRowId 重新赋值是无效的——闭包内的调用走词法绑定，改不到；这一点本身就是踩过的坑）。另外，凡是「代码里不许出现 X」的断言都先剥离注释再比对，否则文件顶部写明「参考插件：@baihejiangnan/…」「无 MutationObserver」会把注释当代码判红。

> ⚠ 测试台的一个时间陷阱（v0.4.20 踩到）：沙箱把 setTimeout 注入成 (fn) => realSetTimeout(fn, 0)，即立刻执行。而 ctxToast 用 window.setTimeout(..., 1800) 清理旧提示——真实浏览器里 1800ms 远大于微任务，但沙箱里那个清理回调会和新提示挤在同一批微任务里、并且后执行，于是一次 .dsh-ctx-toast 全扫会把刚落地的「已删除…」也删掉（断言看到的是空）。规程：凡断言「提示文案」的地方，让出宏任务（await new Promise((r) => setImmediate(r))）而不是若干次 await Promise.resolve()。

tools/check-profile-drift.mjs 专治一类排查成本极高的假象：profile 的 package.json 写着 #v0.4.11，而 pnpm-lock.yaml 仍钉在旧 commit——下次 pnpm install 会把插件无声回退；更常见的是「改了仓库代码、刷新页面毫无变化」，因为真实 GUI 加载的是 profile 里的安装副本。脚本只读不写，逐 profile 比对声明 / lock specifier / lock resolved 版本 / node_modules 实装版本，找不到 ~/.dsh/profiles 时优雅 SKIP。

tools/check-model-seat-hug.mjs 专治一类静态阅读看不出来的样式 bug：它把手写 DOM 骨架建成内核 InputBar 右侧动作区的真实层次（座位在 div.standardControls 内、听写按钮嵌在兄弟容器 div.activity 的 span.triggerAnchor 里），求值 MSS_CSS 模板串（而不是只读源码文本）后用自写选择器匹配器逐条核对：座位父容器被推到最右、横缝收到 0、中英两套 aria-label 都命中、无座位/听写缺席时不误伤、CSS 里不出现内核哈希类名、官方模型按钮仍被隐藏。它也守住「模板串被反引号提前闭合」这类事故——那种情况下求值会失败或留下未展开的 ${...}。本仓库零依赖，不引入 jsdom。

tools/compat-check.mjs 不开浏览器也不重启服务：它从本机已装内核副本里加载 cordis，搭一个最小宿主把 lib/client.js 的 entry 挂上去，在「旧内核 / 新内核 / 服务后到 / 内核不提供 remote」四种主场景（外加声明层 0/0b、速度计 B2、待办进度面板 B4、Definition 通道已移除的反向钉 B3）下复刻 boot 的审计口径（只看 loader entry fiber 是否停在 PENDING），断言入口激活、子 fiber 状态、各槽位注册、功能一目录冷解析、设置页能力位（含三条「conversation.view / uiSession.provide / workspaces.openPath 永不被调用」的逆向钉），以及功能五的数值口径（tspTurnSpeed/tspFoldTurn/tspLastTurnSpeed/tspBlocksEffort）与 dock 组件的 DOM/开关门控（后两项直接截取 bundle 源码段执行，测的就是被测 bundle）。

另含声明层断言（场景 0b）：用内核自带的真实 semver 校验 engines.dsh 覆盖全部已发布内核版本、不误伤未来内核，并保证普通语义与市场侧 includePrerelease 语义判决一致——手搓匹配器会把「被测语义」偷换成「我以为的语义」，故不用。可用 DSH_SEMVER_ENTRY=<...>/semver/index.js 指定匹配器。

tools/live-smoke.mjs 用 puppeteer-core 驱动本机 Chromium 内核浏览器（按 DSH_SMOKE_CHROME → ms-playwright 缓存 → 系统 Chrome/Edge → 常见类 Unix 路径依次探测），打开正在运行的 DSH Web 断言无加载横幅、各功能 DOM 标记在位、并截图。拿不到 URL/token 或找不到浏览器时 SKIP（exit 0）。

变更记录

• v0.4.32（本次）：插件简介改回一句话（用户：「把插件的简介弄简短一点啊，现在点开插件一大篇」）。
• 根因：真机定位到 DSH「插件」页点开某插件后的详情面板，是把该包 package.json 的 description 字段原样全文渲染的；
  而本项目此前惯例是「每版在 description 末尾追加一条变更说明」，v0.4.2 一路累积到 v0.4.31，description 涨到 16376 字，
  所以点开就是一大篇。（列表页的卡片是单行 -webkit-line-clamp: 1 截断，本来不丑——丑的只有点开之后。）
• 修法：description 固定为一句话简介（约 90 字，覆盖七个功能 + 「只改界面，不改内核源码」定位），
  16376 → 93 字；版本变更说明只进本文件「变更记录」与 git tag / GitHub Release，不再往 description 里堆。
• 验证：description 仅此一处被替换，name/version/engines/dsh/files/exports 等字段逐字节未动（脚本化 splice + 逐字段比对断言）；
  全仓库无任何断言依赖 description（grep tools/*.mjs 零命中），故不影响回归。

• 文档与版本：package.json 0.4.31 → 0.4.32；本条替代此前「description 追加本条」的惯例。

• v0.4.31：修功能七镜像面板过宽（用户：「你是有毒吗，把待办拉那么宽干什么？把宽度跟输入框对齐」）。

• 根因：[data-todo-mirror] 用的是 width: calc(100% - 16px)。它在 conversation.input.dock 里是独立块级元素，
  100% 取的是整个 composer 列宽（比输入框卡片宽出一大截），减 16px 仍远宽于输入框，于是面板左右各溢出一截。
• 修法：改用内核自己的 composer 变量——width: calc(100% - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-side-clearance,16px))
  配 max-width: var(--dsh-composer-card-max-width,952px)，得到与输入框卡片同宽、同左右边的结果；
  变量缺失（旧内核）时回退 16px / 952px，仍是同级合理宽度，且不引入任何写死像素的绝对定位。
• 断言：compat-check B1 新增「镜像面板宽度与输入框对齐（width 用 side-clearance + max-width 用 card-max-width）」的数值级样式哨兵
  （只扫选择器会被旧实现假绿，故必须查两个变量名与 width/max-width 同现），126 → 127/127；live-smoke 2d 增加真机宽度实测
  （镜像面板与输入框卡片的 getBoundingClientRect 宽度差 ≤ 2px、左右边缘差 ≤ 2px）。

• 文档与版本：package.json 0.4.30 → 0.4.31、description 追加本条；README 功能七「做法」补第 7 条与本节、验证口径（127/127）同步；AGENT.md §4/§6.3 口径同步。

• v0.4.30：重构功能七——用户指出 v0.4.28 理解错了需求。