2017java/dsh-md-overlay

dsh-md-overlay

DSH 里的 Markdown 预览面板：对话里点一下，报告就在可拖拽的右侧面板里渲染（可悬浮，也可 📌 钉住融入布局）。

给 DSH 一个可悬浮 / 可停靠、可拖拽调宽、多标签的 Markdown 预览面板，外加一个 md_preview 模型工具：

- 你在对话里说"预览一下 report.md"，agent 调用 md_preview → 对话出现带简短预览的卡片 + 右侧面板打开渲染好的预览；
- 📌 钉住：点面板头部 📌，把悬浮面板钉进布局（推挤会话列，VSCode 侧边栏式），再点恢复悬浮；不依赖 better-sidebar；
- 浮层支持同时打开多个文档、标签切换、宽度拖拽（320px~75% 屏宽）；
- 渲染质量：代码语法高亮 + 行号 + 一键复制、目录 TOC、任务清单、嵌套列表、表格、剥离 HTML 注释，无需打开本地应用。

与 dsh-md-viewer（融合进 dsh-better-sidebar 侧边栏）互补：需要"融入布局、不遮挡"用 md-viewer；需要"随时弹出的阅读区/停靠面板"用 md-overlay。

✨ 功能

- 🖥️ md_preview 模型工具：读取 workspace 内 .md 并触发面板预览（Host 全局注册，所有会话可见，同一页面内标签跨对话累积）
- 📇 预览卡片：对话里不是小 chip，而是文件名 + 状态 + 简短渲染预览 + 目录节数 + 打开按钮
- 📌 浮层 / 停靠双模式：默认悬浮盖在内容上；点 📌 停靠 → 推挤页面布局融入（与 better-sidebar 的推挤 calc() 叠加共存，装不装它都能用）
- 📑 多标签：一次打开多个文档，点击切换，逐个关闭
- 📏 可拖拽宽度：左缘拖动 320px~75% 屏宽
- 🌈 代码块：语法高亮（js/ts/py/bash/json/yaml/html/css）、行号、语言徽标、一键复制
- 🧭 目录 TOC：自动收集标题层级，点条目平滑滚动到对应章节
- ✅ 任务清单（- [x] 复选框）与 嵌套列表（缩进层级）
- 🛡️ HTML 处理：→图片、 剥离、实体反转义；纯 React、无 innerHTML
- 🔒 安全边界：只读 workspace 内文件，超 1MB 拒绝

🚀 安装

前置：DSH（dsh web 可运行）。

dsh plugin --profile web add dsh-md-overlay@latest

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）。之后在对话里让 agent 预览某个 md 文档（或你提到某个报告文件），卡片与面板即会自动打开。

🔌 机制

- Host 半（lib/index.js）：用 ctx.tools.register(defineTool(...)) 注册 md_preview 工具，经 fs 读取文件（workspace 守卫 + 1MB 上限）；文件内容通过 output.presentationMeta 随 tool/result 事件带给客户端卡片。另注册读取路由 POST /dsh-md-overlay/read（自包含，供客户端"点产物"取内容）。
- Client 半（lib/client.js）：tool.call.toolview 渲染预览卡片（解析 block.meta 拿到内容并写入标签页）；shell.overlay 渲染多标签面板；📌 停靠通过 #root margin-right 推挤实现（html #root + calc() 与 better-sidebar 叠加）。
- 点"产出文件".md 进本面板：客户端 wrap workspaces.openPath（延迟到所有插件 apply 后安装 + 轮询保底最外层，HMR-safe）——.md/.markdown 走 /dsh-md-overlay/read 读内容并打开我们面板；非 md 放行（有 better-sidebar 时给它的侧边栏，否则给系统默认应用）。

🆕 v0.3 更新

- 点"产出文件" .md 直接进本面板（不再被 better-sidebar 侧边栏截走；未装 better-sidebar 时也不再跳系统外部应用）——真正打通"AI 产出 → 会话里点一下 → 我们面板预览"。

🆕 v0.2 更新

- 融合 dock：浮层 / 停靠（📌）双模式，dsh-md-dock 已并入本包；
- 卡片从 chip 升级为带简短预览的卡片；
- 渲染 v2：代码行号、任务清单、嵌套列表；含已有高亮 / TOC / 复制。

⚠️ 已知限制

- markdown 相对路径图片不解析；暂不支持 LaTeX / Mermaid（better-sidebar 的强项，规划中）；
- 卡片 / 面板只在 md_preview 工具被调用或点击 .md 产物后出现；.md 产物点击进本面板，其他类型文件交给 better-sidebar / 系统默认应用。

📦 发布

见 PUBLISHING.md（npm 发布 + dshfind 插件超市收录的完整流程）。
📄 许可证

MIT