前言¶
DSH（DeepSeek Harness）采用插件化架构。在会话中预览 Markdown 报告或文档时，若切换到外部编辑器会打断上下文，直接在对话中展示又缺乏良好的排版与交互。dsh-md-overlay 插件通过引入一个可悬浮/可停靠的 Markdown 预览面板，以及一个 md_preview 模型工具，解决了这一痛点，实现了会话内的一键预览。
插件定位¶
这是一个 DSH Web 客户端插件，由 2017java 维护，采用 MIT 许可证。
插件提供两个核心能力：
1. md_preview 模型工具：读取 workspace 内的 .md 文件并触发面板预览。
2. 预览面板：支持浮层/停靠双模式、多标签页管理、宽度拖拽调整，以及代码块语法高亮。
核心功能¶
- md_preview 模型工具：该工具注册为全局工具，所有会话可见。当调用该工具时，插件会读取 workspace 内的 Markdown 文件，并在对话中展示预览卡片，同时打开右侧预览面板。
- 浮层 / 停靠双模式：默认状态下，面板悬浮在内容之上。点击面板头部的 📌 图标可将其停靠，推挤页面布局融入；再次点击可恢复悬浮。
- 多标签与拖拽：支持一次打开多个文档，点击标签切换，逐个关闭。面板宽度可通过左缘拖拽调整，范围在 320px 到 75% 屏宽之间。
- 代码块渲染：支持 JS/TS/Python/Bash/YAML/HTML/CSS 语法高亮，显示行号、语言徽标，并提供一键复制功能。
- 目录与列表：自动收集文档标题生成目录（TOC），点击可平滑滚动至对应章节。支持任务清单（
- [x]）和嵌套列表。 - HTML 处理：自动剥离 HTML 注释，进行实体反转义，确保渲染安全。
- 安全边界：插件仅读取 workspace 内的文件，文件大小超过 1MB 时会被拒绝加载。
安装与启用¶
前置条件：确保 DSH（dsh web）可正常运行。
dsh plugin --profile web add dsh-md-overlay@latest
安装完成后，请硬刷新浏览器（Cmd/Ctrl + Shift + R）以加载新插件。
典型用法¶
- 指令触发：在对话中输入“预览一下 report.md”，Agent 调用
md_preview工具，右侧面板会自动打开并渲染该文档。 - 产物点击：对话中如果出现“产出文件”等 .md 产物，直接点击该文件名，面板会自动打开并展示内容。
注意事项¶
- 相对路径图片：暂不支持解析 Markdown 中的相对路径图片。
- 特殊语法：暂不支持 LaTeX 和 Mermaid（这些是 better-sidebar 的强项，本插件规划中未包含）。
- 触发机制：预览卡片和面板只在
md_preview工具被调用，或者点击 .md 产物后才出现，其他类型文件会交给系统默认应用或侧边栏处理。
总结¶
dsh-md-overlay 适合需要在 DSH 会话中频繁查看 Markdown 文档、代码报告的用户。它通过提供一个悬浮且可嵌入布局的预览窗口，减少了应用切换成本。
