dsh-md-annotator

面向 DeepSeek Harness Web UI 的 Markdown 批注插件。通过 The Better Sidebar 打开 .md / .markdown 文件后，可进行 Markdown 预览、块级批注、选区批注、源码编辑、保存和批注报告整理。0.9.0 起重新接入 dsh-better-sidebar，由其负责文件路由与面板承载。

功能

• 通过 The Better Sidebar 打开 Markdown 文件，切换「预览」与「源码」模式；源码支持 Cmd/Ctrl+S 保存；
• 解析标题、段落、列表项（逐项）、表格、代码块、引用和水平线；支持常用内联 Markdown；
• 悬停块或列表项后添加批注，也可以在同一段落或列表项内选中文字添加选区批注；批注支持「必须改 / 建议改 / 疑问」类型；
• 批注以右侧卡片显示，按原文位置排列并自动避让；橙色虚线从被批注的文字或段落连接到对应卡片，悬停时加粗；支持原文引用、复制、编辑、删除及单条写入草稿。保留批注高亮、计数和可拖动的批注清单，支持清空和 JSON 导出；
• 批注栏与正文一起滚动，侧栏宽度变化时重新排列；窄侧栏可横向滚动，也可使用官方分栏放大或全屏查看；
• 将全部、所选或单条批注整理为结构化报告，写入该文件所属会话的输入框草稿，不自动发送；
• 独立设置「增强预览」「写入草稿后清空批注」和「报告前缀」；设置保存在本插件自己的版本化 localStorage 空间；
• 文件重新生成后按块内容与邻接上下文重定位批注，失配项标记为「原文已变化」；
• 同一会话和文件的多个视图共享文档草稿、版本和批注；不同会话隔离。

依赖与兼容

• DSH Web profile；
• dsh-better-sidebar >=0.19.1 <0.20.0，以及 DSH 0.1.5-rc.1+；旧 alpha 环境需先升级；
• Node.js ≥ 20，pnpm ≥ 10（仅用于源码构建、测试和打包）；
• 通过 ctx.betterSidebar.registerFileViewer 注册 Markdown 预览器，优先级 20；右侧栏与底部工作台共用；
• Better Sidebar 声明为 optional peer，避免重复实例；客户端通过 inject 等待其服务，未安装或被禁用时不激活预览器。

安装

前置：已安装可正常运行的 DSH Web profile 和上述兼容版本的 The Better Sidebar。

从本地 tgz 安装

仓库当前不提供已发布下载地址。先在项目目录打包，再把生成的 tgz 放入 Web profile 的 vendor 目录：

cd dsh-md-annotator
pnpm run pack
mkdir -p ~/.dsh/profiles/web/vendor
cp dist/dsh-md-annotator-<version>.tgz ~/.dsh/profiles/web/vendor/
dsh plugin --profile web add file:vendor/dsh-md-annotator-<version>.tgz

安装后重启 dsh web，并在浏览器中硬刷新（Cmd/Ctrl+Shift+R）。安装时应使用与实际文件名一致的版本号；本 README 不预设下载链接或校验值。

更新

修改代码后重新执行 pnpm run pack，将新的 tgz 放入 ~/.dsh/profiles/web/vendor/，再次执行 dsh plugin --profile web add file:vendor/dsh-md-annotator-<version>.tgz，然后重启 dsh web 并硬刷新浏览器。

开发、测试与打包

源码位于 lib/src/，由 scripts/bundle.mjs 拼接为 lib/client.js。在插件目录执行：

pnpm install
pnpm build       # 重新生成 lib/client.js
pnpm test        # 运行 smoke、unit、integration、host 测试
pnpm run pack        # prepack 自动构建，产出 dist/dsh-md-annotator-<version>.tgz

也可以分别运行：

node test/smoke.mjs
node test/unit.mjs

测试覆盖模块物化、解析、内联渲染、引用编解码、批注重锚定、报告和有界存储等行为；真实 DSH 浏览器集成仍应在目标版本的独立测试 profile 中验收。

保存、冲突和生命周期限制

• 单文件完整读取上限为 2 MiB。超限文件不会以截断内容进入可保存编辑器；
• 保存使用官方文件版本条件。外部修改导致版本冲突时保留本地源码草稿并提示处理，不自动覆盖；
• 文件草稿、批注和视图状态保存在本次插件运行期内；刷新、重启 DSH 或停用插件前应先保存源码并导出批注 JSON；
• 本插件不提供批注持久化、JSON 导入、富文本编辑、完整 GFM 或自动发送；
• 卸载时撤销 viewer 注册，重新打开文件后由 Better Sidebar 内置预览接管；
• 每 3 秒检查文件版本，保护未保存草稿；未保存标记显示在编辑器内；
• 停用或卸载：

dsh plugin --profile web remove dsh-md-annotator

解析与引用说明

内联解析器为 CommonMark 子集，支持 ATX 标题、段落、列表、表格、代码围栏、引用、水平线，以及 `code`、**粗体**、*斜体*、~~删除线~~ 和 [文本](链接)。不支持 setext 标题、嵌套列表、内联 HTML、列表项内代码围栏或引用、表格单元格转义管道符。

批注引用采用版本化 v1:… 格式，包含内容和邻接上下文签名。文件重新生成后按原文与上下文重锚定，同名块不会静默错挂；无法匹配时保留批注并标记「原文已变化」。