dsh-md-annotator

在 dsh-better-sidebar 的 Markdown 预览中逐项批注，并把全部批注一键整理成结构化修改指令写入聊天对话框，以便对产出内容进行精准修改。

功能

在侧边栏直接切换「预览」与「源码编辑」模式；源码编辑支持 Cmd/Ctrl+S 或宿主保存按钮写回原 Markdown 文件，并与现有批注预览、better-sidebar 合并工具栏兼容；
打开任意 .md 文件（侧边栏预览）时，把文档解析为块：标题、段落、列表项（逐项）、表格、代码块、引用、水平线；
悬停任意块 / 列表项 → 「＋批注」→ 内联填写修改意见（支持增/改/删，一处可多条），并可给批注打类型标签（必须改 / 建议改 / 疑问）；
选中任意文字批注：在预览里拖选不限字数的文字（需在同一个段落/列表项内）→ 浮出「＋批注选区」→ 填写意见；被选中的文字会持续高亮（CSS Custom Highlight API），批注引用精确到选中的字句而非整块；
已批注块显示琥珀色左边框 + 计数角标；底部固定栏显示总数（可点手柄 ﹀ 收起 / ︿ 展开），并可展开「批注清单」悬浮面板（可拖动位置（可拖出侧边栏到页面任意位置）、可调整大小、单条移除、一键清空），点击跳转定位；
点「全部发送」→ 当前会话输入框草稿写入结构化指令（按类型分组：文件路径 + 行号 + 原文引用 + 批注），回车即可发送给模型；清单内可逐条发送或勾选后批量发送；
设置页集成：侧边栏「设置 → 侧边卡片」中可整体开关本预览器，并可配置「发送后自动清空批注」（默认开启）与「发送内容前缀」；
文件被重新生成时，按「块序号 + 原文」重匹配批注，失配项标注「原文已变化」，仍可按引文定位发送。

依赖

DSH web profile；
已挂载 dsh-better-sidebar（本插件通过其 ctx.betterSidebar 服务注册 viewer）。未挂载时本插件行将一直等待服务而不会激活。

安装

前置：Node ≥ 20、pnpm ≥ 10，dsh web 可正常运行。

安装发布版（推荐）

▼
sh
复制代码
curl -L -o dsh-md-annotator-0.6.0.tgz \
  https://github.com/3361805598-gif/dsh-md-annotator/releases/download/v0.6.0/dsh-md-annotator-0.6.0.tgz
shasum -a 256 dsh-md-annotator-0.6.0.tgz

mkdir -p ~/.dsh/profiles/web/vendor
cp dsh-md-annotator-0.6.0.tgz ~/.dsh/profiles/web/vendor/
dsh plugin --profile web add file:vendor/dsh-md-annotator-0.6.0.tgz

v0.6.0 安装包的 SHA-256 应为：

▼
text
复制代码
7e389c52e9ec65f6864b766fe39e586c67d5df80fa94fdd26cf7cfc18c9fff08

安装后重启 dsh web，再硬刷新浏览器（Cmd/Ctrl+Shift+R）。

从源码打包

▼
sh
复制代码
# 1. 打包（在包目录内；prepack 会自动重新拼接 lib/client.js，产物落到 dist/）
pnpm pack         # 产出 dist/dsh-md-annotator-<version>.tgz

# 2. 放入 profile 的 vendor 目录
cp dist/dsh-md-annotator-<version>.tgz ~/.dsh/profiles/web/vendor/

# 3. 安装并自动挂载（官方 CLI 会协调 dsh.profile.bundles）
dsh plugin --profile web add file:vendor/dsh-md-annotator-<version>.tgz

# 4. 重启 dsh web，然后硬刷新浏览器（Cmd/Ctrl+Shift+R）

更新

改完代码后：pnpm pack → 覆盖 ~/.dsh/profiles/web/vendor/ 下的 tgz（或放新版本号）→ 重新执行 dsh plugin --profile web add file:vendor/... → 重启 dsh web + 硬刷新。

开发与测试

源码按职责拆在 lib/src/（styles / store / parser / selection / panel / viewer / entry），由零依赖拼接脚本 scripts/bundle.mjs 合并为单文件 lib/client.js（仍为无打包器、直发的 __ModuleLoader__ factory 形式）。修改源码后需重新拼接：

▼
sh
复制代码
node scripts/bundle.mjs   # 重新生成 lib/client.js（pnpm pack 会经 prepack 自动执行）
node test/smoke.mjs       # 工厂物化 + 块解析冒烟
node test/unit.mjs        # 纯函数单测（解析器 / 内联渲染 / ref 编解码 / 重锚定 / 报告 / 存储有界）
npm test                  # 依次跑上面两个测试

卸载 / 停用

临时停用：侧边栏「设置页 → 侧边卡片」中关闭 md-annotator 条目，内置 Markdown 预览立即恢复；
完全卸载：dsh plugin --profile web remove dsh-md-annotator（bundle 协调会自动移除层栈条目）→ 重启 dsh web。

说明与限制

批注保存在浏览器内存中：切换 Tab / 会话不丢失，但重启 DSH 或停用插件后清空；清单面板与底部栏提供「导出」按钮，可把当前文件全部批注下载为 JSON 备份（localStorage 持久化与拖拽排序为后续演进方向）；
插件运行期间会接管 .md 文件的侧边栏预览（内置预览的编辑模式不可用），停用后自动恢复；
UI 为全中文，无 i18n 层（个人插件定位）；
内联 Markdown 解析器为 CommonMark 子集：支持 ATX 标题、段落、列表（逐项）、表格、代码围栏、引用、水平线，以及 `code` / **粗体** / *斜体* / ~~删除线~~ / [文本](https://github.com/3361805598-gif/dsh-md-annotator/blob/HEAD/链接) 内联语法；不支持 setext 标题、嵌套列表（缩进子项按续行拍平）、内联 HTML、列表项内代码围栏/引用、表格单元格转义管道符；
批注引用为版本化 + 内容/邻接上下文签名的 v1:… 格式，文件重生成后按「原文 + 上下文签名」重锚定，同名块不会静默错挂；失配项标注「原文已变化」；
无构建链：lib/client.js 为 scripts/bundle.mjs 从 lib/src/*.js 拼接出的 __ModuleLoader__.load factory 格式，由 /plugins/dsh-md-annotator/client.js 直接下发；lib/index.js 为 no-op 宿主半（功能纯客户端）。

功能

在侧边栏直接切换「预览」与「源码编辑」模式；源码编辑支持 Cmd/Ctrl+S 或宿主保存按钮写回原 Markdown 文件，并与现有批注预览、better-sidebar 合并工具栏兼容；

打开任意 .md 文件（侧边栏预览）时，把文档解析为块：标题、段落、列表项（逐项）、表格、代码块、引用、水平线；

悬停任意块 / 列表项 → 「＋批注」→ 内联填写修改意见（支持增/改/删，一处可多条），并可给批注打类型标签（必须改 / 建议改 / 疑问）；

选中任意文字批注：在预览里拖选不限字数的文字（需在同一个段落/列表项内）→ 浮出「＋批注选区」→ 填写意见；被选中的文字会持续高亮（CSS Custom Highlight API），批注引用精确到选中的字句而非整块；

已批注块显示琥珀色左边框 + 计数角标；底部固定栏显示总数（可点手柄 ﹀ 收起 / ︿ 展开），并可展开「批注清单」悬浮面板（可拖动位置（可拖出侧边栏到页面任意位置）、可调整大小、单条移除、一键清空），点击跳转定位；

点「全部发送」→ 当前会话输入框草稿写入结构化指令（按类型分组：文件路径 + 行号 + 原文引用 + 批注），回车即可发送给模型；清单内可逐条发送或勾选后批量发送；

设置页集成：侧边栏「设置 → 侧边卡片」中可整体开关本预览器，并可配置「发送后自动清空批注」（默认开启）与「发送内容前缀」；

文件被重新生成时，按「块序号 + 原文」重匹配批注，失配项标注「原文已变化」，仍可按引文定位发送。

安装

前置：Node ≥ 20、pnpm ≥ 10，dsh web 可正常运行。

安装发布版（推荐）

▼
sh
复制代码

curl -L -o dsh-md-annotator-0.6.0.tgz \ https://github.com/3361805598-gif/dsh-md-annotator/releases/download/v0.6.0/dsh-md-annotator-0.6.0.tgz shasum -a 256 dsh-md-annotator-0.6.0.tgz mkdir -p ~/.dsh/profiles/web/vendor cp dsh-md-annotator-0.6.0.tgz ~/.dsh/profiles/web/vendor/ dsh plugin --profile web add file:vendor/dsh-md-annotator-0.6.0.tgz

v0.6.0 安装包的 SHA-256 应为：

▼
text
复制代码

7e389c52e9ec65f6864b766fe39e586c67d5df80fa94fdd26cf7cfc18c9fff08

安装后重启 dsh web，再硬刷新浏览器（Cmd/Ctrl+Shift+R）。

从源码打包

▼
sh
复制代码

# 1. 打包（在包目录内；prepack 会自动重新拼接 lib/client.js，产物落到 dist/） pnpm pack # 产出 dist/dsh-md-annotator-<version>.tgz # 2. 放入 profile 的 vendor 目录 cp dist/dsh-md-annotator-<version>.tgz ~/.dsh/profiles/web/vendor/ # 3. 安装并自动挂载（官方 CLI 会协调 dsh.profile.bundles） dsh plugin --profile web add file:vendor/dsh-md-annotator-<version>.tgz # 4. 重启 dsh web，然后硬刷新浏览器（Cmd/Ctrl+Shift+R）

开发与测试

▼
sh
复制代码

node scripts/bundle.mjs # 重新生成 lib/client.js（pnpm pack 会经 prepack 自动执行） node test/smoke.mjs # 工厂物化 + 块解析冒烟 node test/unit.mjs # 纯函数单测（解析器 / 内联渲染 / ref 编解码 / 重锚定 / 报告 / 存储有界） npm test # 依次跑上面两个测试

说明与限制

批注保存在浏览器内存中：切换 Tab / 会话不丢失，但重启 DSH 或停用插件后清空；清单面板与底部栏提供「导出」按钮，可把当前文件全部批注下载为 JSON 备份（localStorage 持久化与拖拽排序为后续演进方向）；

插件运行期间会接管 .md 文件的侧边栏预览（内置预览的编辑模式不可用），停用后自动恢复；

UI 为全中文，无 i18n 层（个人插件定位）；

内联 Markdown 解析器为 CommonMark 子集：支持 ATX 标题、段落、列表（逐项）、表格、代码围栏、引用、水平线，以及 `code` / **粗体** / *斜体* / ~~删除线~~ / [文本](https://github.com/3361805598-gif/dsh-md-annotator/blob/HEAD/链接) 内联语法；不支持 setext 标题、嵌套列表（缩进子项按续行拍平）、内联 HTML、列表项内代码围栏/引用、表格单元格转义管道符；

批注引用为版本化 + 内容/邻接上下文签名的 v1:… 格式，文件重生成后按「原文 + 上下文签名」重锚定，同名块不会静默错挂；失配项标注「原文已变化」；

无构建链：lib/client.js 为 scripts/bundle.mjs 从 lib/src/*.js 拼接出的 __ModuleLoader__.load factory 格式，由 /plugins/dsh-md-annotator/client.js 直接下发；lib/index.js 为 no-op 宿主半（功能纯客户端）。