dsh-client-ui-quote 0.11.2 → 0.11.4-lab.10

package/README.md

@@ -4,6 +4,16 @@
 
 选中正文 → 浮层动作 → 引用变成输入框里的行内胶囊（不是纯文本），评论也放在同一颗芯片里；发送之后，引用和评论**合成一颗胶囊**留在消息里，不会摊成一屏 `>` 行。第三项「侧边对话」则把引用写进右侧栏一条**独立的侧边线程的输入框**（一条主会话一条线程，反复点就反复追加），问什么由你写，主会话一点都不动。评论框里**引用正文本身也可编辑**（选多了当场裁）；从**文件预览或终端**划选的引用以**围栏代码块**的线格式发给模型，模型看到的是真正的代码块。
 
+## 界面
+
+| 划词浮层 | 评论：引用与评论各一格，都能改 |
+| --- | --- |
+| ![选中文字后浮出「评论 / 添加到对话 / 侧边对话」，位置贴着选区](docs/screenshots/bar.png) | ![评论框：引用正文与评论分开可编辑，可勾选「让模型逐条回应」](docs/screenshots/comment.png) |
+
+| 发送后的胶囊 + 悬停卡片 | 右侧栏的「引用清单」页 |
+| --- | --- |
+| ![悬停胶囊：引用、评论、跳回原文、改这条引用、复制](docs/screenshots/card.png) | ![引用清单：搜索本会话全部引用、跳回原文、导出 Markdown，底部是侧边线程回流](docs/screenshots/panel.png) |
+
 ## 功能
 
 | 动作 | 行为 |
@@ -12,8 +22,8 @@
 | **添加到对话** | 直接把引用加进输入框，不弹评论框。 |
 | **侧边对话** | 把引用写进一条**独立的侧边对话**（dsh-better-sidebar 的侧边线程）的输入框：线程继承主会话完整上下文、独立运行、不污染主会话，页签自动在右侧栏打开，**什么都不发送**——你写好自己的问题再发。同一条主会话只开一条线程，之后每次点都在同一条线程的草稿后面接着追加。鲸鱼蓝（`#4d6bfe`）的图标是它在浮层里的标识。 |
 | **键盘直达** | `Alt+Q` 引用 / `Alt+C` 评论 / `Alt+B` 侧边对话——同一个浮层的三个动作，不弹浮层直接办。走 DSH 的快捷键服务注册，所以出现在设置里、可改键、与宿主键位冲突会在注册时报错；没有选区时返回 `pass`，按键不会被吞掉。 |
-| **跳回原文** | 悬停卡片底部的 `跳回原文`：把引用当初所在的那条消息**停到视野上方 24px**（和宿主自己跳轮次一样的位置）并闪一下。坐标（消息行锚点 + 轮次）在插入时记下、按引用原文归一化成键存进 `localStorage`，因此跨刷新仍在。只在**引用自己那条会话的面板里**找，不跨会话误跳；被虚拟列表藏起来的行会让位给同轮次的可见行；压根没挂载的行靠滚动搜索一屏一屏地找出来——先往上找（引用总在比它更早的消息里），一路到顶还没找到就从最新处再来一遍；都找不到就明说（`原文不在当前视图里`）。 |
-| **引用清单** | 右侧栏的一个**页面**：本会话发出去的引用与评论的清单。搜索框按引用/评论过滤、点一条跳回原文、`导出 Markdown` 落一个文件、历史没读完时可 `加载更早的消息`。它作为**页面类型**注册进右侧栏（`ctx.sidebarRightTabs.register`），并在指南页留下一个胶囊作入口；`Alt+L` 同样能打开。数据来自会话自己的事件日志（`ctx.sessions.retain` → `session.eventSource`），不依赖屏幕上有没有那条消息。 |
+| **跳回原文** | 悬停卡片底部的 `跳回原文`：把引用当初所在的那条消息**停到视野上方 24px**（和宿主自己跳轮次一样的位置）并闪一下。坐标（消息行锚点 + 轮次 + 同句序号）在插入时**写进消息自己的文本**——一段只在线上存在的 `※ │q1:…` 行（base64url 的 JSON），显示、胶囊、清单导出里都剥掉；它随消息本身走，所以跨刷新、跨窗口、以及清单页里根本没被本插件看着选中的引用都跳得回去。只在**引用自己那条会话的面板里**找，不跨会话误跳；被虚拟列表藏起来的行会让位给同轮次的可见行；压根没挂载的行靠滚动搜索一屏一屏地找出来——先往上找（引用总在比它更早的消息里），一路到顶还没找到就从最新处再来一遍；都找不到就明说（`原文已变`——消息还在、那段文字不在了；或 `原文不在当前视图里`）。 |
+| **引用清单** | 右侧栏的一个**页面**：本会话发出去的引用与评论的清单。搜索框按引用/评论过滤、点一条跳回原文、`导出 Markdown` 落一个文件、历史没读完时可 `加载更早的消息`。它作为**页面类型**注册进右侧栏（`ctx.sidebarRightTabs.register`），并在指南页留下一个胶囊作入口；`Alt+L` 同样能打开。数据来自会话自己的事件日志（`ctx.sessions.retain` → `session.eventSource`），不依赖屏幕上有没有那条消息；每行带着**自己那份坐标**（从消息文本的 `※ │q1:…` 行读出来），所以没被本插件看着选过的引用也能跳。 |
 | **侧边线程回流** | 同一个页面底部是这条会话的**侧边线程**：显示它最后问的那个问题与消息条数，并给两个动作——**`带回主会话`** 把线程最后「问题 + 答案」写成主会话输入框里的草稿（**不发送**，你自己按发送），**`导出 Markdown`** 把整条线程落成一个文件。线程内容同样从它自己的事件日志读；没有线程时这一节只说明「还没有侧边线程」。 |
 | **改这条引用** | 悬停卡片里的 `改这条引用`：把那条引用当初的**引用与评论都原样放回评论框**（引用正文、评论各占一个输入框，都能改），你改完按 `⏎` 就发出一条**新的**引用（DSH 没有编辑已发送消息的 API，这是唯一诚实的做法）。旧胶囊随即挂上 **`已修订`** 标记，卡片里直接显示改后的评论；**连正文一起改过的**，卡片里也把改后的原文亮出来。标记按引用原文记在本机，跨刷新仍在。 |
 | **逐条回应** | 评论框里的一格**勾选项**（默认关）：勾上，这条引用的块尾就多一行**只有模型读得到的指令**——请按出现顺序把引用记为「引用1」「引用2」…并在回复中逐条对应。模型的回复里每个 `「引用N」` 会变成一枚**小徽章**：悬停就是那条引用的完整卡片（含 `跳回原文` 与 `改这条引用`），点了就跳；编号超出这条消息引用数的标签保持纯文本。指令行与围栏一样只是**线上形态**，胶囊、卡片、导出里都不出现。 |
@@ -29,19 +39,23 @@
 
 要求：DSH ≥ 0.2.0-rc.2 的 **web / 桌面** 客户端（`package.json` 里 `engines.dsh` 声明的就是实测版本；插件运行在渲染进程里，headless profile 没有 UI）。
 
-### 方式一：link 安装（推荐）
+### 方式一：npm 包（推荐）
+
+已发布到 npm：`dsh-client-ui-quote`（0.10.0 起上架；稳定版当前 **0.11.3**）。
 
 ```bash
-git clone https://github.com/BangBang-03/dsh-client-ui-quote.git
-dsh plugin --profile desktop add link:<clone-path>
+dsh plugin --profile desktop add dsh-client-ui-quote
 ```
 
-DSH 会把包记进 profile 的依赖并加入组合包列表，装完在侧边栏 **插件** 页能看到「选中引用 (dsh-client-ui-quote)」，可随时开关。
+npmmirror 与 npmjs 一般 10 分钟内同步，DSH 配置了镜像源即可国内直装。Electron 托管的 `desktop` profile 也可以在**应用内市场**里搜索本插件安装（`dsh plugin` 对这类 profile 会拒绝管理，这是 DSH 的限制，不是插件的问题）。
+
+想跟开发线跑：`pnpm install dsh-client-ui-quote@lab`；切回稳定版：`@latest`。
+
+### 方式二：手工注册为 profile 组合包（不用 CLI 时）
 
-### 方式二：手工注册为 profile 组合包
-1. 把本仓库放到任意目录；
+1. 把包装进 profile：`cd <DSH_HOME>/profiles/<profile> && pnpm add dsh-client-ui-quote`；
 2. 编辑 `<DSH_HOME>/profiles/<profile>/package.json`：
-   - `dependencies` 增加 `"dsh-client-ui-quote": "link:<绝对路径>"`（Windows 上用正斜杠，如 `link:C:/path/to/dsh-client-ui-quote`）；
+   - `dependencies` 里应有 `"dsh-client-ui-quote": "^0.11.3"`（安装器会写）；
    - `dsh.profile.bundles` 追加 `"dsh-client-ui-quote"`；
 3. 重启 DSH（profile 打开 `patchReload` 时也会自动重载）。
 
@@ -53,17 +67,26 @@ DSH 会把包记进 profile 的依赖并加入组合包列表，装完在侧边
       name: dsh-client-ui-quote
 ```
 
-### 方式三：npm 包（已上架）
-
-已发布到 npm：`dsh-client-ui-quote`（0.10.0 起上架；每个 `v*` 标签由下面的 workflow 自动发布，本仓库当前 0.11.2）。发布由 GitHub Actions 完成（`.github/workflows/publish.yml`）：推 `v*` 标签或手动 Run `publish` workflow，`prepublishOnly` 的 293 项断言会先在 runner 上跑完，任何一项失败都不会发出去。`npm pack --dry-run` 可核对内容（0.10.0 = 14 个文件 / 97.6 kB）。
-
-装：
+### 方式三：link 本地仓库（只给开发用）
 
 ```bash
-dsh plugin --profile desktop add dsh-client-ui-quote
+git clone https://github.com/BangBang-03/dsh-client-ui-quote.git
+dsh plugin --profile desktop add link:<clone-path>
 ```
 
-npmjs 上架后 npmmirror 一般 10 分钟内同步，DSH 配置了镜像源即可国内直装。
+link 的优点是改完刷新即生效；**日常运行请用方式一**，不要长期挂 link——那样市场/版本号都会绕着走。
+
+### 开发与发布：`link` / `lab` / `stable` 三种运行模式
+
+- **`link`——日常开发（最快）**：profile 里依赖写成 `link:C:/…/dsh-client-ui-quote`，窗口直接加载仓库里的文件。改完 `Ctrl+Shift+R` 硬刷新就生效，不必发版。
+- **`lab`——云端预发布线**：`lab` 分支每 push 一次，CI 就把 `下一个补丁版本-lab.<run_number>`（例如 `0.11.4-lab.37`）发到 npm 的 **`lab`** dist-tag，不碰 `latest`。装它：`pnpm install dsh-client-ui-quote@lab`——用来验证「打包后的产物」，而不是工作区文件。
+- **`stable`——用户装到的版本**：`main` 只接受从 `lab` 合并过来的提交；发版 = 合并到 `main` 后打 `vX.Y.Z` 标签，CI 发到 npm 的 `latest`。
+
+本机切换这三档（这台开发机专用的辅助脚本，不在仓库里）：`node .dsh-quote-work/profile-mode.mjs link|lab|stable|status`。换完在窗口里 `Ctrl+Shift+R` 生效；只有宿主半有改动时才需要重启桌面端。
+
+两条线的断言入口相同：`npm test`（306 项），CI 里 `prepublishOnly` 会先跑完再发。
+
+本机额外限制（只影响这台开发机）：`git push` 到 `github.com:443` 不通，推分支/发版走 GitHub REST API（`.dsh-quote-work/publish-release.mjs`、`push-branch.mjs`），本地对象会按 API 的字节重建，`git status` 保持干净。
 
 **发布运维备忘**（给未来的自己）：
 
@@ -227,7 +250,7 @@ transcript 侧的 `.dshq-cap` 胶囊：一颗胶囊同时装引用与评论，`
 1. **语义而不是机制**：引用与评论是同一颗节点（对齐 Kimi 的 `quote` 节点 `{text, comment}`），一颗芯片 → 一个块 → 一颗胶囊 → 一张卡片 → 一次复制；机制（reference chip、DOM 增强）谁都能抄，这条链子不好抄。
 2. **引用是带坐标的活对象**：`跳回原文` 在自己的会话面板里找行、按宿主的方式对齐到 24px，行被虚拟列表藏起来或没挂载都能找回来；坐标不随引用文本发给模型（不污染 prompt）。
 3. **引用有下落**：清单页（搜索 / 跳转 / 导出 Markdown）+ 侧边线程回流（结论写回主会话草稿 / 导出线程），这两件事在 4471 条里没有对应物。
-4. **工程化**：293 项离线断言（含真跑 `sessions.retain` / `setDraft` / 下载链路）、每个宿主契约都在 README 里写明出处、每个版本都有可回读的 release。同类里多数是一两百行、没有测试的插件。
+4. **工程化**：306 项离线断言（含真跑 `sessions.retain` / `setDraft` / 下载链路）、每个宿主契约都在 README 里写明出处、每个版本都有可回读的 release。同类里多数是一两百行、没有测试的插件。
 
 反过来也要说清楚：**本插件不做的**——不做翻译/解释类选区动作（81 条同类在做）、不做多选合并引用（7 条有）、不做选区折叠/行内 diff 这类渲染花样。它只把「引用」这一件事做穿。
 
@@ -260,7 +283,7 @@ locale/zh.json        插件页卡片文案（中文）
 locale/en.json        插件页卡片文案（英文）
 test/check.mjs        离线自检（清单 + 组件契约）
 test/dom.mjs          给离线自检用的最小 DOM / MutationObserver 垫片
-test/capsule.mjs      离线自检（发送后胶囊 + 悬停卡片 + 跳回原文 + 键位 + 改这条引用 + 代码引用 + 文件路径 + 逐条回应的回复徽章，197 项断言）
+test/capsule.mjs      离线自检（发送后胶囊 + 悬停卡片 + 跳回原文 + 键位 + 改这条引用 + 代码引用 + 文件路径 + 逐条回应的回复徽章 + 浮层不随座位失效，210 项断言）
 test/panel.mjs        离线自检（引用清单：解析 / 搜索 / Markdown / 读取 / 导出 / 页面注册 + 侧边线程回流，96 项断言）
 test/capsule.html     真浏览器里跑同一套胶囊断言（可选）
 ```
@@ -308,7 +331,10 @@ React 重渲染不会出现第二颗、引用变了就地重建、消息被删
 卡片给出 `跳回原文` 与 `改这条引用` 两个动作、点后者把栏切到评论模式并**预填旧评论与旧正文**、
 按确认后 `insertReference` 恰好一次（新芯片的 `ref` 带改后的评论）、旧引用被记为「已修订」并落进 `localStorage`、
 旧胶囊挂上 `已修订` 徽标、它的卡片显示改后的评论（连正文改过的连改后原文一起显示）、空修订不算修订、
-修订不改写引用原文本身、清空引用正文时确认按钮禁用、改后的正文随新芯片发出（共 197 项，含文件路径与逐条回应的线上形态、回复徽章的建立/重建/卸载与悬停卡片复用，以及评论框两个输入区的自适应高度——引用正文那格曾经在被挂进栏之前就量高，读到 0 后被写成 `height:0`，首行因此被裁掉）。
+修订不改写引用原文本身、清空引用正文时确认按钮禁用、改后的正文随新芯片发出；
+**浮层不跟着座位生死**（`conversation.input.overlay` 没挂载也能选中出栏、挂上两个会话座位既不叠加也不丢监听、
+座位不在时用输入框自己的 `actions` 落芯片、无处可插时给 toast 而不是静默返回、effect 卸载/重装后监听恰好一份）；
+（共 210 项，含文件路径与逐条回应的线上形态、回复徽章的建立/重建/卸载与悬停卡片复用，以及评论框两个输入区的自适应高度——引用正文那格曾经在被挂进栏之前就量高，读到 0 后被写成 `height:0`，首行因此被裁掉）。
 `test/capsule.html` 是同一套断言的真浏览器版，用 `file://` 打开即可（页面会把结果写进标题与 `#probe-out`）。
 
 `test/panel.mjs` 单独跑引用清单页与侧边线程回流（96 项）：只认**持久**的 `user/message`（`transient`、助手消息、`data: null` 都跳过）、
@@ -327,7 +353,7 @@ Markdown 的标题/编号/块引用/评论行/时间戳与空列表兜底、超
 `bringThreadBack` 把结论写成**草稿**（原有草稿保留、空行隔开）、外壳没有 `setDraft` 时如实失败、没有线程时不乱写；
 `exportThread` 的文件名与整条线程内容、以及 MIME 是 Markdown。
 
-合计 **293 项**（check.mjs 的契约断言 + capsule 197 + panel 96），`npm test` 全绿。
+合计 **306 项**（check.mjs 的契约断言 + capsule 210 + panel 96），`npm test` 全绿。
 
 ## 已知限制
 
@@ -347,7 +373,7 @@ Markdown 的标题/编号/块引用/评论行/时间戳与空列表兜底、超
 - **引用清单页依赖右侧栏的两个服务**（`sidebarRightTabs` 与 `sidebarRight`，实测 0.2.0-rc.2）；宿主没有它们时页面不注册、`Alt+L` 给一条 toast
   （「引用清单打不开：右侧栏服务不可用」）而不是报错。它的数据来自会话事件日志，**历史是分页的**：只列已加载的消息，更早的要按 `加载更早的消息`；
   如果会话做过原生上下文压缩/裁剪，被裁掉的那些消息里的引用也不会出现在清单里。导出是浏览器下载（宿主没有给客户端插件写盘接口），
-  文件名形如 `quotes-<sessionId>.md`；只有被本插件看着选中过的引用那一行可点击跳转，其余行只是可读文本。
+  文件名形如 `quotes-<sessionId>.md`；一行能不能跳看它自己带不带坐标——本版本发出的引用都带，更早发出的老引用没有坐标，那行只能当文本读。
 - 仅 web / 桌面 profile；选区必须落在会话正文里。
 - 引用在输入框里显示为胶囊，编辑器中复制粘贴出去的是它的模型形态文本。
 - transcript 胶囊是在 DSH 渲染结果之上做的覆盖层：它只隐藏原节点、不搬移 React 的节点，但若 DSH 改了消息的 DOM 结构
@@ -377,7 +403,8 @@ transcript (`quote │ comment`, hover for the full text, click to expand, copy
 the model still receives the full text. The same hover card opens over the composer chip, whose label has to be clipped,
 and it closes with the chip as soon as the message is sent. Each chip resolves its own quote at hover time — React
 reuses a chip node for the next quote, so a card can never show the previous one's text.
-Install with `dsh plugin --profile desktop add link:<clone-path>` (DSH >= 0.2.0-rc.2, web/desktop client).
+Screenshots: [floating bar](docs/screenshots/bar.png) · [comment box](docs/screenshots/comment.png) · [capsule hover card](docs/screenshots/card.png) · [quote list page](docs/screenshots/panel.png).
+Install with `dsh plugin --profile desktop add dsh-client-ui-quote` (published on npm; DSH >= 0.2.0-rc.2, web/desktop client).
 Test with `npm test`. MIT licensed.
 
 Two wire-only extras ride on the same pipeline: a per-quote reply toggle in the comment box (the block carries a