# dsh-select-quote 实现说明(维护者向) 面向用户的介绍与安装在 [README](../README.md)。这里只记**现存**的协议、槽位与机制——改代码前先读这份。历史调查记录(含已失效的中间结论)在 [`archive/`](archive/),只供溯源。 ## 开发命令 ```bash pnpm run typecheck # tsc --noEmit,应无输出 pnpm run test # Vitest 纯逻辑用例(角标/定位/配置/快捷键矩阵) pnpm run build # 产出 lib/index.js 与 lib/client.js pnpm run watch # 增量重建 pnpm run sync:desktop # 把 lib/ 推给桌面客户端已安装的副本(热更新) pnpm run sync:desktop -- --watch pnpm run sync:web # 同上,目标换成 web profile(= sync-desktop.mjs --profile web) pnpm run dev:desktop # 上面两个一起开:增量重建 + 推送(scripts/dev-desktop.mjs 拉起两个子进程) pnpm run verify # 无头执行 lib/client.js:全部贡献都注册上,八语言词典键与占位符齐备,外加包展示元信息(locale + icon)按宿主规则解析、打包 pnpm run check # typecheck + test + build + verify(提交前跑这个;CI 同款) pnpm run release # check → 追加 CHANGELOG.md → 提升版本号并打 tag ``` **为什么有 `verify`**:`tsdown` 不做类型检查,一个语法坏掉的 bundle 也能构建"成功",而这是唯一能在浏览器之外发现这类错误的手段——它把 `lib/client.js` 放进假的 `window.__ModuleLoader__` 里跑一遍,用 mock ctx 调 `apply()`,逐项核对注册结果。改动 `src/client/index.tsx` 的注册项时,记得同步 `scripts/verify-bundle.mjs` 里的 `EXPECTED`。(最初的事故现场见 [`archive/investigations.md`](archive/investigations.md)。) **本地跑起来**:把 `dev.patch.example.yml` 复制成 `dev.patch.yml`(后者已 gitignore),插件路径必须是**绝对路径**(checkout 不在 profile 的 `node_modules` 里,Loader 没有包名可解析)。换机器/换目录时改那一行;本地 patch 不进仓库、不随 npm 包发布,发布版走 `cordis.patch.yml`(按包名)。 **桌面客户端的热更新(`sync:desktop`)**:宿主把 `@deepseek-ai/dsh-client-hmr` 挂在 web 组合包里(`dsh-web-app/cordis.patch.yml` 注明 always mounted,没有产物变化时静默)。它的 node 半每 500ms `statSync` 每个 roster 行 client 产物的 `mtimeMs/ctimeMs/size`,签名一变就调 `clientModules.rebuilt(id)` 重算 revision,并经 SSE `/plugins/events` 广播 `{type:"rebuilt",id,rev}`;浏览器半收到即 `ctx.modules.entries.reload(id, rev)`,只重载这一个插件模块。产物按 `?rev=` 取,新 revision 天然绕过 immutable 缓存。因此 `scripts/sync-desktop.mjs` 要做的只有一件事:**让被监听的那个文件内容变化**——它按 `$DSH_HOME`(默认 `~/.dsh`)+ profile(`--profile` / `$DSH_PROFILE`,默认 `desktop`)定位已安装副本,只在字节不同的时候写,避免空重载。换 package 版本(`pnpm add` / 市场更新)仍然必须重启客户端,热路径只覆盖产物字节。 ## 数据契约 ### 现行:批注 JSON 块 待发批注在发送瞬间被折成一段带指令头的 JSON 块,跟在用户正文前面(`composeAnnotatedMessage`): ``` # Response annotations: Each item contains text selected from an earlier message ... [{"text":"…","annotation":"…","source":{…}}] 用户自己输入的问题 ``` - 读取:`scanAnnotatedMessage()` 剥掉整块,气泡只剩用户正文。展示层只认完整的开闭标记对:JSON 非法或不是数组时不产出批注,但块照样剥掉,协议原文永不出现在对话里; - 回填:`readComposedDraft()` 是 `composeAnnotatedMessage()` 的逆。dsh-rewind 撤回时把它读到的持久文本原样写回输入框(`messageTextAt` → `setComposerText`),协议块也会跟着进编辑器;`AnnotationPanel` 检测到完整块后把批注重新挂回待发摘要、草稿还原成用户正文(见关键机制 1)。回填比展示保守:只认完整、JSON 合法且非空数组的块,被截断或手改过的块不碰; - 回指:协议头要求模型对它处理过的每条批注内联 `:dsh-annotation{index="N"}`,客户端 `decorateAnnotationDirectives.ts` 把这些指令渲染成 chip。chip 的 hover / focus / click 都打开预览浮层(触屏点按同样只开预览),原文和评论由 `transcript/quote-registry.ts` 按用户消息 flow key 暂存,chip 通过前一条 mark 的 flow key 取回;跳转由浮层标题栏右侧的箭头图标按钮触发(仅图标、带本地化名称,和编辑/前往/删除同一组样式),点 chip 本身不再直接跳。取不到 registry 时退回 mark 文本并隐藏评论区。浮层在 `dom/chipPreview.ts`,body 级 fixed(消息表面的 contain: layout 会劫持 fixed 定位),复用 `placePopover` 做翻转/钳位(默认在上方),内容层用和批注卡列表相同的 `dsq-rise-in`(只动 transform),退场用反向的 `dsq-rise-out`、120ms 后才摘节点;滚动和缩放时重排,chip 被流式重渲染替换时自动关闭;mark 不可见或已被移除时按「批注摘要卡 → 批注所属用户消息 → quote.messageId 来源消息」逐级回退并闪烁,全都没有才保留预览并提示;正文 mark 复用同一浮层:最后一个片段(带角标)有 `role=button` / `tabIndex=0` 和本地化 aria-label,点击或 Enter/Space 打开预览,待发批注按 store id 取原文/评论,历史批注按 `dqsm_` id 走 quote-registry,预览里不出现「原文」按钮;**待发批注的预览标题栏带编辑/删除**:编辑把正文换成评论输入框(取消/保存;Enter / ⌘/Ctrl+Enter 保存,Shift+Enter 换行,手势复用 `popoverEnter`,与评论泡一致),保存写回 store 后回到阅读态,编辑期间浮层像摘要列表一样钉住、外部点击不关闭;删除走全插件统一的内联两步确认(第一次点击长成「图标 + 确认移除」,再点才删),正文角标与输入框摘要同步消失。历史批注属于已发送消息的引用,没有这两个按钮;绑定用 document 级委托,宿主重渲染替换 mark 不会泄漏监听; - **改格式要一起改**:`composeAnnotatedMessage()`(写)、`scanAnnotatedMessage()`(读)、`readComposedDraft()`(撤回回填)、`ANNOTATION_DIRECTIVE_RE`(chip)、`scripts/verify-bundle.mjs`。 **「打开链接」为什么用 `window.open`**:宿主自己的外链处理(`dsh-client-ui-chat` 的 `openExternalLink`)在用户把「链接打开方式」设成侧边栏时,会把 http(s) 链接塞进应用内的浏览器标签——那里加载任意 URL 就是客户端被搞崩的路径。工具条的「打开链接」因此直接 `window.open(url, '_blank', 'noopener,noreferrer')`:桌面主进程的 `setWindowOpenHandler` 只认 http/https,命中就转交 `shell.openExternal`(真·系统默认浏览器),其余协议一律 deny。所以按钮**只对 http(s) 亮起**(`selection-url.ts`),`chrome-extension://` 这类点了也不会有反应——要让它们也进系统浏览器,得宿主改那个白名单,是上游的事。检测逻辑无 DOM 依赖,`verify-bundle` 直接 import 跑用例(含全角括号/尾随标点/大小写/非 http scheme)。 **chip 必须接住 characterData**:流式回复是**原地改文本节点**(`nodeValue` / `insertData`),这类 MutationRecord 的 `addedNodes` 是空的。观察者若只遍历 `addedNodes`,流式期间就永远不装饰——原文一直挂在那儿,直到消息 DOM 被重建(切会话、重挂载)才补上,表现就是"切个会话就好了"。所以回调里必须先分流 `record.type === 'characterData'` 并装饰 `record.target`。`verify-bundle` 有一条静态闸守这件事(`checkDirectiveObserver`)。 **镜像切分:宿主的文本节点绝不离开文档**:宿主(0.2.2-rc.2)流式尾块经 React 用 `nodeValue` 原地重写,整段行内文字是**同一个 Text 节点**。装饰器若 split + `replaceChild`,React 手里还是旧节点,之后每个 chunk 都写进已脱离文档的节点——批注指令后面的内容(含还没到的 chunk)从页面上消失,直到回复结束、DOM 被重建才回来([issue #13](https://github.com/latte03/dsh-select-quote/issues/13))。现在改成**镜像**:宿主节点留在原处、只保留第一条指令之前的前缀,chip 与其后的正文放进紧随其后的 ``,每次 React 重写就重新规划一次。这条路成立是因为宿主的正文段落渲染成 `jsx("p", { children: [...] })`,`children` **恒为数组**(哪怕只有一项),React 因此建 HostText fiber 走 `nodeValue`;它的 `setTextContent` 只在 children 是 string/number(或 textarea/noscript/dangerouslySetInnerHTML)时才用,段落永远走不到,所以我们插进去的兄弟节点不会被 React 清掉。MutationObserver 回调是微任务、在绘制前跑完,因此不会闪出原文。六条不变量必须一起守住:①**先摆镜像再截断宿主节点**——中途抛错时是文字重复而不是文字消失,React 下一个 chunk 能修重复、永远补不回空洞;②**截断写入要守卫,且只能用一次性 `selfWrite` 标记、不能靠比值**——不守卫则自己的 characterData 记录把自己再叫起来,微任务队列排不空、连 DevTools 都跑不动;但 Blink 对「`nodeValue` 写成它已经持有的字符串」**照样发 characterData 记录**,所以宿主把节点重写成恰好等于旧前缀时(行内标记正好在指令前闭合、消息被重新生成),比值闸会把它当成自己的写入而跳过,旧镜像就永久留在页面上(流式已结束,没有下一个 chunk 来自愈)。标记在写之前置位、被那条记录消费一次;③**React 按 index reconcile**,段落里冒出新的行内节点时它只删旧 Text fiber,必须从 `record.removedNodes` 认领并撤掉镜像,否则段落里留一份重复正文。**撤销不能加 `box.previousSibling === node` 这类邻接条件**:走到这条路径时宿主节点已被 React 摘出文档,条件永远不成立,孤儿盒会一路累积(实测把守卫加上,95 条断言红 60 条);④**chip 按 index 复用、未变化的 run 不做任何 DOM 操作**——重建节点会丢 `activeChip` 归属,摘掉聚焦中的 chip 还会触发 blur 关掉用户正在读的预览卡;⑤**React 会把新行内节点 append 到镜像盒后面**(它不知道盒存在,`getHostSibling` 只走 fiber),顺序靠「旧节点失去指令就撤盒 + 新节点自己建盒」收敛,不要试图去猜 React 的插入位置;⑥**同一回调里的多条 characterData 记录只按节点的最终值规划一次**,`data-streaming` 摘除后的装饰也推迟到本回调末尾——一个任务里连做几次提交(流式突发)时,每条记录描述的都是被后一次覆盖掉的旧值,而本回调刚写的截断记录只会在下一个回调送达;若让过期记录按序消费 `selfWrite`,随后的截断记录就会被误读成「宿主写回前缀」,镜像被撤、尾部消失(正好是最后一帧就不会自愈)。`scripts/mirror-harness/` 的 S17 断言这条。宿主会在文档不动的情况下重新求值客户端模块(WeakMap 清空),所以镜像容器带 `data-dsq-ann-mirror`,靠 `nextElementSibling` 认领回来而不是再叠一份。 **为什么「新节点误认领旧镜像盒」在当前宿主下不可达**:inline 子节点是 `Kn = e.map((r, i) => Zp(r, i, ctx))`,**key 就是索引**,而 `case "text"` 直接返回裸字符串(隐式索引 key)——Text fiber 没有可复用的显式 key,换位置只能是删了重建,不可能被「移动」。React 又先提交删除再提交插入,MutationObserver 按时间顺序交付记录,所以删除记录一定先到。真要防这件事,正确的形状是给盒记一个反向 owner(`WeakMap`),认领时转移归属、撤销时只撤自己仍拥有的盒;邻接判断不是它的近似。宿主若哪天改成显式 key 或把文本包进元素,这条要重验。 **这些不变量由 `pnpm run verify:mirror` 逐条断言**(`scripts/mirror-harness/`,真实 React 18 + headless Chrome,已并入 `check`):流式逐 chunk 的节点身份与全文、行内标记在指令前/后/中间出现时的阅读顺序、孤儿回收、`` 形态的延迟与替换、宿主模块热重载认领,以及「写成同值也发记录」这条 Blink 行为。`verify-bundle` 的静态闸只守形状,时序只有这套能验——上面两个真缺陷(比值闸留旧镜像、邻接守卫漏孤儿)都是它抓到的,改装饰器时新分支要写成断言。 **`` 形态是硬约束例外**:inlineCode 渲染成 `jsx("code", { children: 字符串 })`,正好命中 `setTextContent`;它的快路径要求「元素只有一个 Text 子节点」,一旦在里面插镜像,每个 chunk 都退化成 `code.textContent = 新值`,把 chip 整个抹掉,而且报的是 **childList 不是 characterData**。所以 code 形态仍等 `data-streaming` 摘掉再处理(观察者监听该属性就是为它)。处理时也**不能 `replaceWith`**:React 之后 `removeChild` 那个已脱离的 `` 会抛 `NotFoundError`(真实 React 18.3.1 复现)。改成元素留在文档里、文本清空、加 `.dsq_annCodeHost` 隐藏,chip 放它旁边,用 WeakMap + `removedNodes` 跟着回收。 **流式尾块只有最后两个块**:宿主的流式渲染器把已完成的块冻结,缓存其 React element 并**按引用复用**,React 直接 bailout、DOM 不再变动;只有最后 `cW = 2` 个块留在 tail 每 chunk 重渲染。所以镜像的风险窗口只有 tail 那一小段,冻结块天然稳定;反过来「等整条回复结束才出 chip」是过度保守——批注所在段落往往早就冻结了。`[data-streaming]` 挂在整条消息上,粒度比块粗得多,不能拿它判断某个段落是否还在被重写。 ### 遗留:`> [选中文本]` 引用块 旧版把引用写成 Markdown 引用块。现在**不再写入**,只在 `quote-protocol.ts` 里保留读取与剥离能力(`parseQuoteMessage()` / `displayTextWithoutQuote()`),用于渲染历史消息。新消息一律走上面的 JSON 块。 ## 客户端贡献 | 位置 | 类型 | 说明 | |---|---|---| | `shell.overlay` | list slot | `select-quote-toolbar`(order 100):划词工具条 + 评论气泡。挂 root 级,切会话/看历史都不会失去观察 | | `conversation.input.overlay` | list slot | `select-quote-card`(order 20):输入框内的批注摘要;`select-quote-session-bridge`(order 1):只负责把 `sessionId` 发布给 root 工具条 | | `conversation.chat.user.before` | chain slot | `select-quote-user-before`:批注摘要块挂在宿主自己的 user 行上(`select` 只要 `kind === "user"`);**不覆写任何 Chat 节点** | | `conversation.chat.text-interaction` | keyed slot | key `quote`(`priority: -1`):**遮蔽**宿主 `message-quotes` 的引用按钮条目,在宿主自己的划词浮层里画「引用文本」+ 我们的动作行(`mergeHostSurface` 打开时)。见机制 19 | | `plugins.bundle.config` | keyed slot | 按包名 `dsh-select-quote`:插件页**外层**(描述与行列表之间)直接渲染的分段控件、快捷键开关,以及开关下方从宿主 catalog 读取的当前键位;注册包在 `ctx.configForms.whileServed(['select-quote'], …)` 里,表单控制器经 slot `inject` 以 `configForm` prop 传入 | | `ctx.uiConversation.userText` | 规则 | `select-quote.annotations`(order 10100):气泡文本由宿主工厂生成时剥掉协议块,不再重写 `data.content` | | `ctx.shortcuts` | 命令 | `select-quote.openMenu` / `select-quote.addToTask`:`shortcut` 开启时一起注册;无选区返回 `blocked`,评论步骤未完成时也返回 `blocked`,命中时经 `runtime.selection` 打开菜单 / 保存批注并开评论框;设置区订阅 `ctx.shortcuts.catalog` 显示当前键位;缺该服务时插件照常工作(见机制 15) | | `ctx.sessions` | 客户端服务 | 读会话摘要的 `origin` / `blank` / `cwd` / `updatedAt`;跨会话批注读标题与工作区并用 `create()` 静默新建空白会话(见机制 18);侧边提问用 `fork()` / `retain()` 和子会话自身的 `prompt()` 驱动(见机制 16)。已知的侧栏 fork id 不接管主会话绑定 | | `ctx.workspaces` / `ctx.uiWorkspace` | 客户端服务(可选) | 读工作区分组与 `archivedSessionIds`,用 `openSession()` 在会话间跳转;三者(含 `sessions.create`)缺任一项时隐藏「放入会话」入口,插件照常激活(见机制 18) | | `ctx.modelDirectories` | 客户端服务(可选) | 读主会话的模型目录快照,给侧边提问的模型 chip 提供分组、搜索与推理等级;侧边提问在**子会话**目录上调用 `select()`,主会话路由不变(见机制 16) | | `ctx.resources` / `ctx.sidebarRightTabs` / `ctx.sidebarRight` | 客户端服务 | 侧边提问的 fork 标签:注册 `select-quote-side` 资源与标签类型,`openResource('dsh-resource://select-quote-side/session/', { kind: 'select-quote-side' })`(见机制 16) | | `ctx.contextMenus` | 客户端服务(可选) | 给标签右键菜单加「保留到列表」;只在 `tab.kind === 'select-quote-side'` 且尚未保留时返回动作。缺服务时标签标题里的保留图标仍可用(见机制 16) | | `remote.selectQuoteTranslate` | Typert Remote | Host 服务 `SelectQuoteTranslate` 经 `exports["./typert"]` 清单自动注册;`exports["./remote"]` 导出同一份可挂载贡献,客户端一次 `ctx.remote.$mount` 得到 `translate(agentId, { text, target, prompt })`,它是 `mode: 'stream'` 的可取消流,逐帧产出 thinking / text / done(机制 17) | | `remote.selectQuoteSideForkRetention` | Typert Remote | Host 服务 `SelectQuoteSideForkRetention` 的单次 `prune({ sessionIds, cutoffMs })`:客户端只提交本地台账里已归档、未保留、超过周期的 fork id;宿主再校验归档状态、非活动、seeded fork 与日志 mtime,通过后删除整个会话目录。持久化契约没有删除 API,这里是唯一的 unlink 点(见机制 16) | | `ctx.locale` | 语言服务 | 宿主缺 `ja/es/fr/de/ru/pt` 时先 `addLanguage`,再 `register('select-quote', {zh,en})` + 六种语言包各一次三参 `register` + `bind('select-quote')`,见下面第 10 节 | 不再注册 `select-quote` Chat 节点,也不再注册 Conversation Definition——摘要块内联在 `user` 节点里,原因见下面第 4 节。 ## 关键机制 **1. 批注不进草稿,只在发送瞬间注入** 摘要块不是草稿的"可视化",而是唯一的表示。草稿始终保持用户真正输入的内容,JSON 块在**发送动作的捕获阶段**才折进去:`document` 上的 `keydown`(宿主会提交的 Enter 手势:Enter / Ctrl+Enter / Cmd+Enter;Shift+Enter 换行,Alt、AltGraph 与 IME 合成不提交,判定见 `composer-host.ts` 的 `isSubmitKey`)或 `click`(composer 卡片内 DOM 顺序上的最后一个 `button`,且不是停止按钮——停止按钮渲染的是 `svg rect`)。捕获阶段早于 composer 自己的处理器,因此它读到的草稿已经包含批注块。见 `src/client/composer/useSendIntercept.ts`。 反向路径只有一个入口:**检测到完整协议块**。dsh-rewind 撤回时直接读持久消息的 `data.content` 并把文本写回 composer(不经过本插件),协议块也会跟着进编辑器。`AnnotationPanel` 的 layout effect 用 `readComposedDraft()` 把块拆回批注与正文:批注带 `source` 定位重新挂回待发摘要(`restoreAnnotations()`,同 text+comment 去重),编辑器里只留用户自己写的字。触发条件是**完整且 JSON 合法**的块;发送手势刚折进去的那份由 `foldingRef` 排除,普通地提到 `` 的草稿不会被改写,IME 合成期间也一律跳过。展示层(`scanAnnotatedMessage()` 与回显剥离)的分工不同:只要开闭标记完整就剥掉,不要求 JSON 可读。写入时 JSON 里的 `<` 会转义成 `\u003c`(选中文本或评论自带闭合标记也不会提前截断);读旧消息时按候选闭合位置逐个试解析,兼容没有转义的历史块。 **2. 不可见字符 U+200B 让发送按钮保持可用** 草稿为空时 composer 会把发送按钮置灰(`empty = draft.trim() === "" && attachments.length === 0`),而 U+200B 不是 JS 的 WhiteSpace,`trim()` 不会去掉它,于是"只有批注、没打字"也能直接发送。对账只有一处:`useDraftMarker.ts` 的 `reconcileDraftMarker(draft, pending)`——有批注且草稿只剩空白就补标记,批注清空就剥掉,有真实文字就一个字节都不写;返回 `null` 表示当前草稿已经对了,写入只由 `AnnotationPanel` 那一个 effect 做。发送前由 `composeSubmission()` 里的 `stripDraftMarker()` 剔除,绝不进消息;附带产生的空气泡由 `annotations.ts` 的 `[data-message-bubble]:has(…)` 规则藏掉。 > **补写标记必须走原地动词**:`setDraft()` 是 `root.clear()` + 逐行重建 + 光标移到末尾,早年"草稿一变就补写"因此造成「删除失效」和「输入法被打断」(事故现场见 [`archive/investigations.md`](archive/investigations.md))。现在这条写入统一走 `composer/draft-write.ts` 的 `writeDraft()`:`captureInsertion()` 的跨度覆盖整篇时才用 `insertText()` 原地插入(空草稿恒满足),否则退回 `setDraft()`。IME 合成期间一律不写(`composing` 守卫)。标记本身是删不掉的——Backspace 会把它原地补回,这是设计不是 bug。 **3. 输入框摘要布局** `conversation.input.overlay` 的锚点是 `height: 0; position: absolute`,摘要容器本身也是绝对定位,因此**不会挤开下面的编辑器**,默认会盖住附件栏。做法是给 `[data-composer-card]` 加一个 `.dsq_cardPad` 类,用 `ResizeObserver` 实测摘要高度写进 `--dsq-quote-pad`: ```css .dsq_cardPad { padding-top: var(--dsq-quote-pad, 88px) !important; } ``` 绝对定位子元素相对**padding box** 定位,所以摘要仍在顶部,而附件栏与编辑器一起被推到它下方——这也顺带修掉了"传图时图片被摘要盖住"。 **4. 对话记录:装饰席位挂摘要块,文本由宿主工厂剥离** - 摘要块注册在 **`conversation.chat.user.before`**——宿主 0.2.2 起为消息来源装饰提供的官方 chain 席位。它渲染在宿主 `user` 行**内部**(气泡上方),所以气泡、附件、时间/复制行、以及所有往动作行 portal 的插件(dsh-rewind 的 ↶)都仍归宿主,插件一行都不用碰。**绝不要覆写 `conversation.chat.node`**:0.2.2 的注册表只返回「胜出者」,覆写 `user` 会让宿主的 `UserMessageNodeView` 直接离开 entries,既拿不回来、也再也枚举不到([issue #8](https://github.com/latte03/dsh-select-quote/issues/8))。 - 席位只拿到 `{ source, kind }`,没有正文。取正文两条路:①`source.rpcId` → `userMessageTextOf()` 在 Chat 快照里按 `data.source.rpcId` 命中;②没有 rpcId 时(侧边提问的激活提示就是 `source: { kind: "user" }`)退回按所在行的 `data-chat-flow-key` 查 `nodes.byKey`(`chatNodeTextOf`)。两条都拿不到就不渲染。 - 协议块从气泡里消失靠 **`uiConversation.userText` 规则**(`transcript/protocol-rule.ts`,id `select-quote.annotations`,order 10100),不是改写 `data.content`。规则只认完整块,JSON 非法也照剥,其它文本原样返回。 - 摘要块(``)是这条路径上唯一新增的 DOM:**一条消息只有一个块**,块上只显示条数,悬停列表里逐条展示选中文本 + 评论,点条目滚回正文对应 mark。不要退回「一条批注一张卡」。 - **fork 的继承卡片要分开处理**:子代理复制父会话历史时,那些行带着父会话的 rpcId,卡片会二次渲染,所以 `runtime.isSubagentSession()` 为真时跳过带 rpcId 的继承行,只装饰它自己的那条提问;侧栏 fork 也复制历史,但它的首问是新 rpcId,所以 `runtime.isSidebarForkSession()` 只把卡片当 embedded(机器人徽章),不跳过继承行,复制的上下文与自己的引用卡都可见。 **5. 正文 Mark:虚线下划线 + 末尾序号角标** 划中的文本在**原消息正文**里留下 `.dsq_annMark`:高亮色**虚线**下划线(`--dsw-static-blue-500`)+ 淡蓝底 + 圆形序号徽章。徽章是**真实元素**(`i.dsq_annBadge`),挂在划词**末尾**(多片段选区只挂在最后一个片段),不挡阅读。**不要用伪元素**:`::after` 既没法在 DevTools 里选中/截图,也定位不准——跨行 mark 是一个横跨多行的 inline 盒,`left:100%` 解析出来的宽度和文字实际结束位置无关(实测 678px 两行 mark 解析成 `left:0`,91px 单行 mark 解析成 `90.88px`)。现在 `placeBadge()` 先对 mark 文本取 Range、拿**最后一个 client rect**,再**实测徽章在 `left:0` 时的真实原点**(inline 包含块原点同样不等于 mark 左边:实测 mark 在 325、徽章 `left:0` 却画在 653),把差值写成 `transform`。徽章绝对定位、不占行内宽度,加批注不会改变段落换行。角标用 `z-index: 2` 压在原生选区高亮和后续 mark 的底色之上:选区贴到角标、或相邻批注的底色盖过来时,数字仍完整可见。**多个批注结尾重合或靠得很近**时,`dom/badge-layout.ts` 的 `placeBadges()` 做纯几何贪心避让:每个角标先试原位,再向右错开两格(每格 28px),还冲突就向上叠(每格 18px),同时受滚动容器右/上边界约束;偏移直接叠加到徽章自身的 `transform` 上(基准偏移 + 避让偏移),仍不参与文本排版;装饰后延迟一帧重测一次,resize 与 `document.fonts.ready` 也会重新测量。 **角标自己吃点击、但不进选区**:`i.dsq_annBadge` 是 `pointer-events: auto` + `cursor: pointer` + `user-select: none`——角标是打开预览的**唯一**鼠标目标(`role=button` + `aria-label` 仍挂在 mark 上),`user-select: none` 避免 Ctrl+A 或拖动跨过句子时把字形一起选中、被原生高亮涂上一块底色。**不能把它设成 `pointer-events: none`**:pill 绝对定位画在 `last.right + BADGE_MARGIN`,落在 mark 的**行盒之外**,穿透的点击落到段落元素上,`event.target.closest('[data-dsq-ann-mark]')` 拿到 null,预览就再也打不开——角标从伪元素改成真实元素时踩过这个坑。因为角标是带文字的子元素,`mark.textContent` 会变成「正文+序号」,`findAnnotationMark()` 的文本比对必须走 `markTextOf()`(只拼文本节点、跳过角标),否则永远匹配不上、退回同序号的第一条;标记本身不能设 `pointer-events: none`——那会把正文的鼠标划选一并掐掉。点击收尾时 `chipPreview.ts` 用**角标元素自己的 `getBoundingClientRect()`**(`badgeElementBox()`,四边各 3px 容差)做命中判定——mark 自己的矩形是所有行片段的并集,跨行时按它反推角标位置会漂几百像素,闸门会把命中角标的点击一并丢掉;只有角标元素缺席时才退回旧的 `badgeHitBox()`(绘制位置 + 避让偏移,宽度按位数估)。落在正文上的 click 直接忽略;键盘/辅助技术的激活事件不带可用坐标,走最后一个片段的 Tab 焦点与 Enter。定位靠 `message-text.ts`:选区落在哪条消息(`[data-chat-flow-key]`)、起止字符偏移多少——偏移在"跳过插件自身装饰节点"的纯净文本上计算,mark 本身透明(不计入偏移),所以装饰前后偏移稳定。比较时忽略空白(选区文本在段落间有换行、DOM 拼接没有)。定位随 `source` 写进 wire JSON,刷新页面后由 durable 消息重新解析、重新装饰。 **重渲染只扫受影响的消息**:`annotate-text.ts` 的 MutationObserver 按 mutation record 收集 flow item(target 所属的消息;新增节点可能是若干条新消息的包装层,取子树;删除的节点已断开,不必处理),合并到下一帧后调 `applyAnnotationMarks(root, only)`。该路径只对 `messageId` 命中的 job 重新定位/包裹;无定位的 job 也只在这些消息里搜索。嵌套在消息里的推理面板等 block 也有自己的 flow key,所以被改动的 block 会按**自身与所有祖先 key**归属,消息级 job 仍能命中。角标避让按消息 block 分组测量,向上叠不会爬进上一条消息,也不再每帧遍历整个对话。只有 job 注册表变化(upsert / 删除)与 resize 走全量扫描;`requestAnimationFrame` 在页面隐藏时会暂停,回到可见时再补这一帧。 **6. 悬停摘要面板** 面板 **portal 到 `document.body`**:消息内容里有带 `contain: layout` 的表面、滚动容器带 `container-type`,它们都会成为 `position: fixed` 的包含块,面板写在子树里会整体跑出屏幕。面板与摘要之间留 12px 透明"悬停桥",指针离开集群只有 40ms 宽限(够跨桥,退场动画随即开始);resize / 滚动时面板重新定位而非失效。**默认优先放摘要上方**(`placePopover(anchor, panel, 'top', 0)`),只有上方确实放不下、且下方更宽裕时才翻到下方;gap 传 0,视觉间距与悬停桥都靠外层只在朝向摘要一侧留的 12px padding(左右不留,面板卡面因此与摘要左缘对齐)。面板退场时保留节点 120ms 播 `dsq-rise-out` 再卸载,期间 `pointer-events: none`。条目序号与"选中的文本"同行,点击滚动到对应正文 mark。编辑批注**不另弹层**:点铅笔后该项在列表面板内原地展开编辑(完整原文 + 评论框 + 取消/保存);编辑期间指针离开、点击面板外导致失焦都不关闭面板,退出编辑后才恢复关闭;编辑目标按批注 `id` 记录,删除其他条目不会串到旁边的批注。划词工具条等**拖拽结束**(pointerup)才出现,评论弹窗居中于工具条。 - **只有一条批注时,卡片就是那条批注**:标题换成引文、提示行换成用户评论,没写评论就整行不画(卡片只剩一行,而不是画一行空提示)。两条起才回到「N 条批注 + 悬停/点按查看」——序号徽章本来就在左边显示数字,一条时再说一遍「1 条批注」是重复。「有没有评论」直接问 `ui/comment-block.ts`,规则不在这里复述;引文与评论都投影成单行(`ui/summary-heading.ts` 折叠空白,`.dsq_summaryTitle/.dsq_summaryHint` 已有 `nowrap + ellipsis` 负责截断)。**必须两个槽一起切**:`count` 与 `items` 对不上、或引文为空时整体退回计数写法,只换标题不换提示会得到一个没有名字的按钮。 - **浮层宽度跟内容走,不写死**:`.dsq_summaryHover` 与 `.dsq_chipPreview` 共用一条规则,只给 `min-width: 160px` 与 `max-width: min(320px, calc(100vw - 16px))`,**不写 `width`**——fixed 盒没有宽度就是 shrink-to-fit,正好是「和内容一样宽,到上限为止」;一写 `width` 两条限制就只剩钳位作用,卡片又变成永远最大。宽度都在设置 `left` **之前**量(`mountPreview` 先读 `offsetWidth` 再 `placePopover`,悬停面板读的是 inner),所以量到的就是最终画出来的宽度;`placePopover` 的水平钳位沿用 8px 边距,配合 `calc(100vw - 16px)` 不会把卡片推出视口。`pnpm run verify` 的 CASCADE 闸成对断言:两条限制必须落在共享规则上,且这条规则里不许再出现 `width`。 - **徽章只在数字变化时动,方向就是消息**:`.dsq_summaryIcon` 里的数字是计数、不是装饰——悬停、展开、挂载一律静止(用户正在读的数据不该晃),只有 `count` 真的变了才播一次 180ms 的入场:加一条从下方升起、删一条从上方落下,方向由 `ui/summary-count.ts` 的 `countDirection` 决定(纯函数、可单测);同一拍里图块补一层 0.18 的 `--dsq-link` 淡出,**只在上方那一条**,删掉不庆祝。图块 `overflow: hidden`,数字从块外滚进来,不会越到标题上。**重播靠 `key={count}` 重建整个图块**:同一个方向连着来两次(2→3 → 3→4)时 `animation-name` 不变,只有重建才能重新起跑;方向必须在**渲染期**算(`if (seen !== count) setSeen(…)`),放进 effect 会先提交一帧没有方向的新数字,看着像卡顿。`prefers-reduced-motion` 换成 `dsq-count-fade`:保留「变了」的节拍,去掉位移与补光。 - **三档计数动画(`countAnimation`,在「按钮」tab)**:`subtle` 是上面那套上浮 + 补光;`dots` 用 `ui/pixel-count.ts` 的 5×7 点阵把数字画成一个 ``(一行内连续像素合并成矩形,一位数 8 条指令,不是 35 个 `rect`),网格自动缩放塞进图块里 22×18 的盒子;`none` **不挂 `data-dir`**,动画由 CSS 属性选择器驱动,所以"不动"是缺一个属性,不是另一条更慢的动画。点阵的墨水是 `currentColor`(跟着图块的 `--dsq-link` 走),这块网格也是后面鲸鱼的底座。配置项落在**单独一个「彩蛋」tab**:这是唯一允许放纯装饰的 tab,别再往行为 tab 里塞。新增字段仍然要重启宿主(schema 在宿主侧)。 - **跑到哪只鲸鱼、什么时候跑**:`dots` 档下,**当前这一轮在回答**的那张卡会在图块里放一只 20×13 的鲸鱼(`ui/whale.ts`,同一套点阵网格、同一条 `path` 构建器)。运行态不靠嗅 DOM:`useChat` 取 `location.turn.status === 'open'`(宿主自己就是用它决定运行指示器的),拿不到再退到根 hook `useSessionStatus` 的 `running`,两者都没有就**当没在跑**——一只游不停的鲸鱼比没有鲸鱼更糟。三个阶段:`swim`(0.28 不透明度穿过图块,5.6s 一轮,两端停一拍)、`dive`(回合结束那一下:0.6s 变实、抬 6px、下潜出图块,期间数字降到 0.2,一个 32px 方块里两个实心东西只会糊成一团)、然后消失。**只有亲眼看它游过的那张卡才有 `dive`**:`whalePhaseOf(running, wasRunning)` 里 `wasRunning` 决定这一下要不要放,挂载进一个已经结束的会话时不放。`prefers-reduced-motion` 直接 `display: none`——定格在角落的鲸鱼只会是一块解释不清的污渍。CASCADE 闸对 swim / dive(0.6s) / reduce 隐藏各断言一次。 - **键盘**:摘要卡可聚焦;Enter 展开并把焦点移到面板第一个控件,↓ 在已展开时进入面板;Tab / Shift+Tab 在面板内循环,Esc 关闭并把焦点还给摘要卡。面板是 React portal 子节点,keydown 会按 React 树冒泡回摘要卡,所以面板处理过的键要 `stopPropagation()`,否则摘要卡的 Tab 会抢回第一个控件。 - **触屏**:`(hover: none), (pointer: coarse)` 下提示从「悬停查看批注」切成「点按查看批注」;`pointerup` 的 `pointerType === 'touch'` 时点按摘要展开,`pointerleave` 不触发自动关闭(触屏抬手也会发 pointerleave),点外部关闭。操作按钮在 coarse 指针下为 44px;角落关闭按钮保留视觉尺寸,用 `::after` 扩展命中区。 - **触屏的划词 chrome**:coarse pointer 下工具条和评论泡改走 `document.body` 级 fixed,不再挂滚动容器。操作条贴 visual viewport 底部(`visualViewport` 算软键盘 inset,再加 `env(safe-area-inset-bottom)`),评论是底部抽屉:带上选中原文预览、输入框 16px 防 iOS 聚焦缩放、按钮 44px,`maxHeight` 跟 visual viewport 走。抽屉打开时不自动聚焦评论框,关闭后也不把焦点抢回 composer,避免软键盘第二次弹出。细指针(鼠标)仍走内容坐标 + 滚动容器裁剪。 **7. 划词只在对话正文和右侧文件预览生效** 工具条的唯一入口是 `readSelectionSnapshot()`(`SelectionToolbar.tsx` 的 refresh 调它):选区的 anchor 与 focus 必须落在**同一类**可选区——对话消息的 `[data-chat-flow-key]`,或右侧栏文档预览的内容盒 `[data-textpreview-content]`(`dom/selection-surface.ts` 的 `selectionSurfaceOf()` 返回 `transcript` / `sidebarFile`)。文件树 `aside[data-files-navigator]`、预览头、设置、模型选择等仍是应用 chrome:它们要么不在内容盒里,要么被导航区排除。宿主侧确认:`ui-sidebar-documentpreview` 的 `PreviewFrame` 给内容盒写 `data-textpreview-content`,文件树是内容盒里的 `aside[data-files-navigator]`;markdown / code / 纯文本 / PDF 文本层都在内容盒内。两侧落在不同 surface(跨对话与侧栏)的选区不算引用。右键接管和快捷键桥复用同一个准入:工具条读不到的选区也打不开菜单(见机制 15)。 侧栏文件选区没有消息定位(`source` 为空),批注与放入会话按纯文本记录;**动作清单不出现「在侧边提问」**——`selectionActions()` 按 `snapshot.surface === 'sidebarFile'` 跳过该项,浮条与右键菜单共用这一份清单,不会一边有一边没有。浮层宿主也从选区向上找滚动祖先(`floatingLayerFor()` 不再只从 flow item 起步),因此工具条随预览内容滚动、被预览面板裁剪,且不会被主对话 composer 的底边夹住。 **8. 样式与主题** 摘要块、工具条和评论泡都复用宿主的材质/阴影 token(见下),不再有独立的文件卡片几何。 - 深色模式用产品自己的 `body[data-ds-dark-theme]`(由 `dsh-client-ui-layout` 挂在 body 上),**不是** `prefers-color-scheme`; - **字体必须显式给,不能 `inherit`**:浮层挂在被选中的内容旁边(右侧文件预览尤其如此),继承下去会跟着文档变——代码文档把字族设成宋体时,工具条也会变宋体。所以 token 层加 `--dsq-font: var(--dsw-font-family, )`,所有浮层选择器(工具条/评论泡/右键菜单/目标面板/预览卡/模型与语言菜单/宿主 pill)统一 `font-family: var(--dsq-font)`;按钮的 `font: inherit` 于是继承到的是宿主 UI 栈而不是文档字体; - 颜色一律走产品 token,但**不直接写 token 名**:`src/client/styles/` 的分层是(`styles.ts` 只按序拼接与导出) 1. **token 层**:产品 token 各包一次成 `--dsq-*` 别名(`--dsq-label`、`--dsq-line`、`--dsq-shadow`…),兜底值只在这里出现一遍;别名块挂在 `body` 而不是 `:root`,因为产品在 `body[data-ds-dark-theme]` 上翻转调色板,挂在根元素会把亮色值冻结后继承进深色页; 2. **原子层**:`.dsq_a_*`(`row` / `col` / `col-end` / `grid-mid` / `ell` / `plain` / `keep` / `grow` / `box` / `inline-row`),由 `ATOMS` 表同时生成 CSS 规则和 `A` 常量,两边不可能对不上;**只放形状,不放数字和颜色**; 3. **组件层**:带数字的取值都留在这里,注入顺序在原子之后,所以组件规则总能盖住原子; 4. **宿主层**:`@keyframes`、深色覆写、以及伸进产品 DOM 的那两条规则(`.dsq_cardPad` 给 composer 让位)。 JSX 里用 `cx(styles.summary, A.row)` 组合;`A.x` 和 `styles.x` 都是字面量类型,写错名字过不了 `pnpm run typecheck`; - 输入框与对话记录复用同一套摘要组件与样式(`.dsq_summary` / `.dsq_summaryHover`);历史侧只多一层 `.dsq_tSummary` 负责右对齐与宽度上限,不再有“一条批注一张卡”的独立几何; - **浮层的磨砂材质用官方 material 图层同款 token**:工具条、评论气泡、悬停面板、右键菜单以及触屏/预览浮层的底色与模糊都画在一个 `z-index:-1` 的 `::before` 图层上(`background: var(--dsq-menu)` + `backdrop-filter: var(--dsq-menu-backdrop)`,即宿主的 `--dsw-menu-surface-fill` / `--dsw-menu-backdrop-filter`,后者恒为 `blur(40px) saturate(150%)`,亮暗自动翻)。**必须画在独立图层上**:`backdrop-filter` 直接写在容器上会连容器自己的子树一起糊,而负 z 图层只取身后的页面。悬停面板为此把 `overflow-y: auto` 从面板挪到内层 `.dsq_summaryList`——绝对定位的图层留在会滚动的容器里会跟着内容跑掉,滚到底部时面板顶部就露空。**列表条目必须 `flex: none`**:条目自身的 `overflow: hidden` 会把 flex 子项的自动最小高度归零,条目一多就被压进 `max-height`、各自裁掉半行字,列表反而永远不溢出(0.4.9 真机确认,批注一多预览面板整片挤在一起)。**滚动期间绝不再重排面板**:`AnnotationSummary` 的 document 滚动监听忽略 `event.target` 落在悬停面板内的滚动——列表自己滚动移不动锚点,以前每个滚轮 tick 都跑一次 `place()`,往磨砂面板里写样式会让整块材质重新栅格化,看起来就是刚开始滚动时闪一下。别试图用 `will-change: transform` 给列表预提升合成层:真机上滚轮会完全滚不动(拖滚动条仍可用)。老浏览器没有 `backdrop-filter` 时(`@supports not`)图层退成 `--dsq-bg-raised` 不透明底,避免半透明直接糊在文字上; - **阴影统一用 `--dsw-elevation-prominent` 一档**(别名 `--dsq-shadow`):和宿主自己的菜单/弹层同档,且它自带 `0 0 0 .5px` 的描边环(`--dsw-elevation-stroke`)——浮层因此不画 border 也有轮廓。以前工具条用 soft、两个气泡用 prominent 两档,现在合成一个别名;兜底值按真 token 的组成补齐那一圈描边。所有浮层都把描边覆写成更淡的 `--dsw-alias-border-l1`(磨砂边缘自带分界,不需要再勾一道)——**覆写和 `--dsq-shadow` 的声明都必须写在浮层选择器上**:自定义属性在声明处展开,`--dsq-shadow` 留在 body 上时浮层上的覆写够不着; - **磨砂的视觉验证只能在真实客户端里做**:本机 headless Chrome(CLI 与 MCP 两通道)不渲染 `backdrop-filter`,最小页面可复现——别把"没模糊"当代码缺陷,也别用那里的帧率数字下结论(2026-10-19 的教训,见 [`archive/investigations.md`](archive/investigations.md)); - **入场动画绝不带 opacity**:规范实锤祖先 `opacity<1` 会成为 backdrop root,`::before` 采样不到身后的页面,磨砂在整段淡入里消失、结束才糊上。transform 不在禁止列(用户已在真实客户端验证 scale 无恙),现行入场是 `translate(-50%,-100%) translateY(4px) scale(0.96) → 归位`;工具条默认在首行上方,配置改成「下方」或内容顶部没地方放时翻到首行下方(`data-anchor="below"`),换成 `dsq-toolbar-in-below` 关键帧; - 样式通过 `ensureToolbarStyles()` 注入一个 `