dsh-md-overlay

Readme

# dsh-md-overlay

<div align="center">
  <a href="https://www.npmjs.com/package/dsh-md-overlay"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-md-overlay" /></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
  <a href="https://dshfind.com/zh/plugins/2017java/dsh-md-overlay?ref=badge"><img alt="dshfind" src="https://dshfind.com/api/badge/2017java/dsh-md-overlay?lang=zh" /></a><br />
  <b>DSH 里的 Markdown 预览面板：对话里点一下，报告就在可拖拽的右侧面板里渲染（可悬浮，也可 📌 钉住融入布局）。</b>
</div>

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

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

> 与 [dsh-md-viewer](https://www.npmjs.com/package/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 处理：`<img>`→图片、`<!-- 注释 -->` 剥离、实体反转义；纯 React、无 `innerHTML`
- 🔒 安全边界：只读 workspace 内文件，超 1MB 拒绝

## 🚀 安装

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

```sh
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](../PUBLISHING.md)（npm 发布 + dshfind 插件超市收录的完整流程）。

## 📄 License

MIT