dsh-sidenote 0.3.1 → 0.3.3

package/README.md

@@ -1,64 +1,90 @@
-# dsh-sidenote
+<p align="center">
+  <img src="docs/assets/banner.png" alt="dsh-sidenote —— 侧边开一岔对话，划选留一条注释，主线永不被打断" width="100%">
+</p>
 
-DSH（DeepSeek Harness）web 插件：Codex 风格的**侧边聊天**与**划选注释**。[dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 的薄消费插件（thin consumer），通过 `ctx.betterSidebar` 服务注册侧边栏 Tab。
+<p align="center">
+  DSH（DeepSeek Harness）插件——支线问题不打断主线，结论一键回流。
+</p>
 
-[English](README_EN.md) · 中文
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-sidenote"><img src="https://img.shields.io/npm/v/dsh-sidenote" alt="npm version"></a>
+  <a href="https://github.com/g-yixuan/dsh-sidenote/actions/workflows/ci.yml"><img src="https://github.com/g-yixuan/dsh-sidenote/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/peer-dsh--better--sidebar-informational" alt="requires dsh-better-sidebar">
+</p>
 
-<video src="https://raw.githubusercontent.com/g-yixuan/dsh-sidenote/main/docs/assets/demo.mp4" controls muted loop playsinline width="100%"></video>
+<p align="center">
+  <a href="README_EN.md">English</a> · <b>中文</b>
+</p>
 
-## 功能一览
+![演示：划选注释 → 侧边聊天 → 回流主线](docs/assets/demo.gif)
 
-### 💬 侧边聊天
+## 安装
+
+前置：已装 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)（硬依赖）。
+
+```bash
+dsh plugin --profile web add dsh-sidenote
+```
+
+三步上手：**①** 装依赖 → **②** 装本插件 → **③** 顶栏点「侧边」，或直接划选任意回复文本。
+
+本地开发挂载：`dsh plugin --profile web add link:<本仓库路径>`（client 改动热重载，host 改动需重启 `dsh web`）。
+
+## 侧边聊天——支线问题不打断主线
+
+从当前主会话 **fork**（全量历史快照，不压缩）出独立侧边会话，在右侧栏多轮对话：
+
+- 顶栏「侧边」按钮 / `+` 菜单 / 斜杠命令 `/side` 三个入口，多实例并存；
+- 与主对话**同一套渲染材质**：工具卡、思考预览、任务卡、模型/权限切换、`@` 引用、图片附件；
+- 审批/提问**在面板内直接答复**，不用跳回主视图；跑完有 toast 通知；
+- 继承历史默认折叠成指示卡；折叠态/滚动位置刷新不丢；`Alt+J` 主↔侧切焦点。
 
-从当前主会话 **fork**（全量历史快照）出独立的侧边会话，在右侧栏的「侧边」Tab 里多轮对话——主线思路不打断，支线问题随手开：
+![侧边聊天面板：fork 历史 + 原生级工具卡 + 同能力 composer](docs/assets/04-side-chat-panel.png)
 
-- 顶栏常驻「侧边」按钮、右侧栏 `+` 菜单、斜杠命令 `/side`（中文 `/侧边`）三个入口；
-- fork 时刻带主会话完整上下文，之后两个会话各自独立演进；**继承的历史默认折叠**为「继承自主会话 · 截至 fork 点 · N 条」指示卡（点击展开，密度友好）；
-- 多实例并存（「侧边」「侧边 2」…），各自独立关闭；
-- **原生级消息渲染**：与主对话同一套无缝行材质（无框 DisclosureRow 裸行 + 同源叶子组件六族：终端/差异/读文件/搜索/网页/通用）+ 任务卡（todo_write → 状态点清单）；工具卡标题人话化（`Bash · 列目录` 而非整串命令），思考行折叠态带首行预览；流式跟滚；
-- **composer 与主对话同能力**：模型切换（两级菜单）、权限模式 chip、斜杠命令（`/`）、`@` 引用、图片附件、`Cmd/Ctrl+Enter` 插队；
-- **主线状态可见**：面板顶部常显主会话状态（运行中/待审批/空闲），`Alt+J` 在主↔侧之间切焦点；
-- 状态零丢失：折叠态/滚动位置按会话持久化，刷新恢复；
-- **回流通道**：侧边结论一键「回流到主会话」（问答成对：结论+它回答的问题一起回）或「整段回流」全部问答对——以受控上下文 chip 挂在主输入框上方，随下一条消息发给主线（Cursor 级能力，Codex 没有）；主输入框 `@` 也可直接引用侧边聊天；
-- **生命周期**：「保存为正式会话」把侧聊转正进会话列表（全局 toast 确认去向）；`/side` 弹层可重开最近关闭的侧聊。
+## 划选注释——把「这句有问题」变成模型的上下文
 
-![侧边聊天面板](docs/assets/04-side-chat-panel.png)
+- 划选 assistant 回复 → 浮层 → 注解编辑器，右缘编号角标锚定原文；
+- 注释是受控对象（可预览、可逐条移除），**草稿零污染**——发送瞬间才序列化为模型可读的结构化协议块；
+- 发送后气泡收成「批注 ×N」标签留痕；刷新不丢。
 
-| 折叠态（继承卡 + 操作行 + 芯片组） | 侧边斜杠菜单 |
+| 划选浮层 | 注解编辑器 |
 |---|---|
-| ![折叠态](docs/assets/04a-side-chat-collapsed.png) | ![斜杠菜单](docs/assets/04b-side-slash-menu.png) |
+| ![划选浮层](docs/assets/01-selection-popover.png) | ![注解编辑器](docs/assets/02-annotation-editor.png) |
 
-### 🗒️ 划选注释
+## 回流主线——侧边结论不烂在支线
 
-在 assistant 消息上划选文本，把「引用 + 你的注解」变成发送给模型的上下文：
+- 侧边结论一键「回流到主会话」：**问答成对**（结论 + 它回答的问题）收为受控 chip 挂在主输入框上方，随下一条消息发给主线；`@` 也可直接引用侧边聊天；
+- 「保存为正式会话」转正进会话列表；`/side` 弹层重开最近关闭。
 
-- **添加到对话**：选中文本高亮 + 右缘编号角标 + 注解编辑器（可空注解）；主输入框上方出现「N 条注释」chip（可预览、可逐条移除）；
-- **在侧边聊天中提问**：注解编辑后引用 + 注解直接进入侧边聊天输入框；
-- **草稿零污染**：注释是受控对象，不进输入框文本流；发送瞬间才序列化为结构化 XML 协议块（`<annotation>` 块，模型可读性最佳形态）；
-- **发送后留痕**：已发消息气泡收成「批注 ×N」标签可回看；原文角标转空心只读态；**刷新不丢**（按会话持久化，随点随恢复锚定）。
+![回流 chip：侧边结论挂进主输入框](docs/assets/06-reflow-chip.png)
 
-| 划选浮层 | 注解编辑器 | 角标 + 注释 chip |
-|---|---|---|
-| ![划选浮层](docs/assets/01-selection-popover.png) | ![注解编辑器](docs/assets/02-annotation-editor.png) | ![角标与注释 chip](docs/assets/03-badge-and-chip.png) |
+<details>
+<summary><b>更多截图</b></summary>
 
-| 发送后留痕（气泡收成标签） | 侧边回流 chip |
+| 折叠态（继承卡 + 操作行） | 侧边斜杠菜单 |
 |---|---|
-| ![发送后留痕](docs/assets/05-sent-trace.png) | ![侧边回流 chip](docs/assets/06-reflow-chip.png) |
+| ![折叠态](docs/assets/04a-side-chat-collapsed.png) | ![斜杠菜单](docs/assets/04b-side-slash-menu.png) |
 
-## 安装
+| 角标 + 注释 chip | 发送后留痕 |
+|---|---|
+| ![角标与注释 chip](docs/assets/03-badge-and-chip.png) | ![发送后留痕](docs/assets/05-sent-trace.png) |
 
-前置：已安装 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)（本插件的硬依赖）。
+</details>
 
-```bash
-dsh plugin --profile web add dsh-sidenote
-```
+## 兼容性
 
-本地开发挂载：`dsh plugin --profile web add link:<本仓库路径>`（client 改动热重载，host 改动需重启 `dsh web`）。
+| DSH | dsh-better-sidebar | 状态 |
+|---|---|---|
+| 0.1.1-rc.x | ≥ 0.12.3 | ✅ CI 双档矩阵 |
+| 0.1.2-rc.x | ≥ 0.18.0 | ✅ CI 双档矩阵 |
+
+每周 canary 跟进宿主新版本；宿主面缺席时插件按能力降级（不崩页面）。
 
 ## 设计要点
 
-- **真 fork，不压缩**：侧边会话是真实 DSH 会话（fork 全量历史），拥有与主会话对等的能力（工具调用、继续深挖、再 fork）；不是「压缩成摘要 + 一次性问答」。
-- **列表卫生**：侧边会话归档隐藏，左侧列表永远干净。
+- **真 fork，不压缩**：侧边会话是真实 DSH 会话（全量历史快照），与主会话能力对等；不是「摘要 + 一次性问答」。
+- **列表卫生**：侧边会话归档隐藏，会话列表永远干净。
 - **可累积的标注工作流**：多次划选累积多条注释，编辑、删除、随消息一起发出——不是一次性单引文。
 
 ## 开发
@@ -66,9 +92,11 @@ dsh plugin --profile web add dsh-sidenote
 | 命令 | 说明 |
 |---|---|
 | `pnpm typecheck` | tsc --noEmit |
-| `pnpm test` | vitest 纯函数单测 |
+| `pnpm test` | vitest 单测（136 例） |
 | `pnpm build` | 类型声明 + tsdown（host ESM + client CJS bundle，纯度门） |
-| `pnpm test:mount` | 挂载冒烟：scratch profile + 伪造会话 jsonl + 真实 `dsh web` + Playwright 七条 journey lane（支持 `BS_VERSION` 切换 better-sidebar 版本做前向兼容验证） |
+| `pnpm test:mount` | 挂载冒烟：真实 `dsh web` + 伪造会话日志 + Playwright 十条 journey lane（`BS_VERSION`/`DSH_CMD` 切版本矩阵） |
+
+问题与建议欢迎 [Issue](https://github.com/g-yixuan/dsh-sidenote/issues)。
 
 ## License