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:… 格式,包含内容和邻接上下文签名。文件重新生成后按原文与上下文重锚定,同名块不会静默错挂;无法匹配时保留批注并标记「原文已变化」。