poiuyjie/dsh-md-preview

dsh-md-preview

中文 ｜ English

DeepSeek Harness 的 Markdown 预览插件

点击上方链接切换语言 · Click the links above to switch languages

对话里点开 .md，不再跳 VSCode——右侧并排预览，随手可读。

⚡ 核心体验 —— 与对话并排展示：左边继续你惯常的对话 / 写稿 / 校对工作流，右边在同一窗口内并排、实时渲染你点开的 .md 源稿——所见即所写、无需切换窗口；深色 / 浅色主题自动跟随 shell。

DeepSeek Harness（DSH）插件：在会话头部加一个「MD 预览」入口，自动跟踪本会话读写/打开过的 .md 文件，点击对话中的 md 引用时在右侧栏并排打开预览，而不是跳转到系统编辑器（如 VSCode）。

与 dsh-vision-opencode 协同

本插件与 dsh-vision-opencode 配合使用，效果成倍提升——它也是在这个视觉插件的能力基础上开发完善起来的：

• 视觉驱动的工作流闭环：dsh-vision-opencode 给纯文本主模型补上识图能力（vision_read_image），让模型能"看见"渲染出的文档页面；而本插件让你在右侧栏即时打开并排预览对应的 .md 源文件——先看渲染图，再对照源稿，改稿、验证、记录一气呵成
• 图文对照：左侧对话流里是视觉验证结论（"表格 III 渲染干净、无溢出"），右侧预览栏里就是对应的 Markdown 源稿，边看边改
• 适合文档 / 论文工作流：LaTeX 编译检查、排版 QA、版本修订记录等场景下，视觉确认 + 源稿预览双栏并排，效果大大提高

两个插件搭配安装（推荐用 DSH 原生插件命令，它会从 GitHub 下载源码，并把包登记进 profile 的 dsh.profile.bundles 装配层、自动应用各自 cordis.patch.yml——只手改 package.json（npm pkg set）既不会真正下载，也登记不了装配层，装了也不会生效）：

dsh plugin --profile web add github:poiuyjie/dsh-vision-opencode
dsh plugin --profile web add github:poiuyjie/dsh-md-preview

💡 Windows 下把 dsh 换成 dsh.ps1（或 powershell dsh.ps1），profile 目录为 %USERPROFILE%\.dsh\profiles\web。

功能

• 右侧并排预览：点击对话中的 .md 文件引用（产物芯片 / 行内引用 / 工具卡片路径），在右侧栏打开预览，与对话内容顶部对齐、宽度可拖（支持拖到屏幕中间），布局自动让位、不遮挡对话
• 会话隔离的最近列表：自动收集本会话读写/打开过的 .md 文件（读/写/改/删 + 时间 + 文件 mtime），每个会话只看到自己访问过的文件，互不串扰
• 两类打开方式：
  • 浮动窗口：可拖动、可缩放，位置/大小记忆（localStorage）
  • 右侧停靠：与对话并排，左缘分隔线可拖动调宽
• 修饰键逃生：按住 Ctrl/Cmd/Shift 点击 md 引用，仍走系统默认应用打开（VSCode）
• 手动打开：输入相对工作目录的 .md 路径即可预览
• 完整 Markdown 渲染：标题 / 列表 / 表格 / 代码块 / 引用 / 行内代码 / 公式片段 / 图片链接
• 跟随深浅色主题：面板、列表、渲染区全部基于 DSH shell 的 --dsw-alias-* 设计变量，随 shell 的浅色 / 深色（body[data-ds-dark-theme]）自动切换，无需单独设置
• 「对话/轨迹」栏页签：也提供整页「MD 预览」页签

系统支持

⚠️ 主推 dsh plugin 原生安装（Linux/macOS 用 dsh，Windows 用 dsh.ps1）。手动方式（克隆 + npm install + 改 cordis.patch.yml）在 Ubuntu（DSH 0.1.0-rc.6）与 Windows 上验证过；其他发行版上安装路径、~/.dsh profile 目录、cordis.patch.yml 写法可能不同，请按你的环境调整。

安装

方式零：dsh plugin add（原生，推荐）

仓库已声明 dsh.bundle manifest 并自带 cordis.patch.yml，可以直接用 DSH 原生插件命令安装（会自动把插件加入 profile bundle 层并应用其补丁，无需手动改 cordis.patch.yml）：

dsh plugin --profile web add github:poiuyjie/dsh-md-preview

⚠️ 不要用 npm pkg set "dependencies.xxx=..." 代替：它只改 package.json 的一个字段，既不下载包，也不会把它登记进 dsh.profile.bundles 装配层，装了 dsh web 也扫描不到。dsh plugin add 才会完成「下载 + 登记装配层（自动应用 cordis.patch.yml）」。

方式一：本地克隆（推荐，便于改代码和跟随更新）

从 GitHub 克隆到本地（以 ~/plugins 为例）：

mkdir -p ~/plugins && cd ~/plugins
git clone https://github.com/poiuyjie/dsh-md-preview.git
cd dsh-md-preview

然后在你的 DSH web profile 中引用本地路径（Ubuntu 为 ~/.dsh/profiles/web）：

cd ~/.dsh/profiles/web
npm pkg set "dependencies.dsh-md-preview=file:~/plugins/dsh-md-preview"
npm install

方式二：直接引用 GitHub（不克隆，省事）

cd ~/.dsh/profiles/web
npm pkg set "dependencies.dsh-md-preview=github:poiuyjie/dsh-md-preview"
npm install

手动启用插件（仅方式一 / 方式二需要；方式零 dsh plugin add 会自动完成）

在 profile 的 cordis.patch.yml 中启用：

- insert:
    - id: md-preview
      name: 'dsh-md-preview'

重启 dsh web，刷新页面即可在会话头部看到「MD 预览」按钮。

提示：方式一克隆到本地后，git pull 即可跟随更新；插件本体是纯 JS、无构建步骤，改完代码刷新页面即生效（client 半边支持 HMR）。

卸载

在 profile 目录（Ubuntu 为 ~/.dsh/profiles/web）执行：

cd ~/.dsh/profiles/web
npm pkg delete dependencies.dsh-md-preview
npm install

（方式一本地克隆安装的，依赖会自动解除；想彻底删掉再执行 rm -rf ~/plugins/dsh-md-preview。）

然后从 cordis.patch.yml 中删除对应的 insert 条目：

# 删除这一段：
- insert:
    - id: md-preview
      name: 'dsh-md-preview'

最后重启 dsh web。卸载不会删除你的任何 .md 文件或会话记录，只移除预览面板功能。

使用

1. 点击会话头部的「MD 预览」按钮打开面板；
2. 面板默认显示本会话最近访问的 .md 文件卡片（文件名 / 路径 / 操作历史 / 摘要）；
3. 点击对话消息流中的 .md 引用 → 右侧栏自动打开并加载该文件；
4. 拖动面板左缘分隔线调整宽度；点「浮动」切换为浮动窗口；点「✕」关闭；
5. 按住 Ctrl/Cmd/Shift 点击引用 → 用系统默认编辑器打开。

开发

# 插件本体（Host 半边 + Client 半边均为纯 JS，无构建步骤）
ls index.js client.js

• index.js：Host 半边。监听 fs/observed 记录 md 文件访问（按会话隔离），提供 /md-preview/api/{recent,read,peek} 三个 HTTP 端点
• client.js：Client 半边。面板 UI、点击拦截（document 捕获阶段识别 md 引用按钮）、右侧停靠 + 布局让位

⚠️ pnpm 用户的开发提示：用 pnpm 安装的 profile 会把 file: 本地依赖快照复制到 node_modules/.pnpm/（不是符号链接）。修改 plugins/md-preview 源码后，刷新页面不会生效， 需要在 profile 目录重新执行 pnpm install（或手动把改过的文件同步进 node_modules/.pnpm/dsh-md-preview@file+plugins+md-preview/node_modules/dsh-md-preview/）再刷新页面。

许可

MIT