dsh-md-studio 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+本项目所有显著变更都记录在此文件中。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本遵循语义化版本。
+
+## [1.2.0] - 2026-10-13
+
+### 新增
+
+- **对话内 Mermaid 渲染**：聊天消息里的 ` ```mermaid ` 块就地渲染为图表卡片，与右侧文档预览共用同一渲染管线（语法自动修复、图形/源码切换、全屏、下载 SVG、深浅主题重绘）。
+- **流式稳定检测**：AI 正在输出的图表块静默 400ms 后才渲染；输出完成后若内容被重写，自动重建图表。消息卸载（含虚拟列表回收）时自动清理。
+- **与 dsh-mermaid 插件共存安全**：监听器互认对方的渲染产物，不双渲染。
+
+### 说明
+
+- 右侧文件预览行为与 1.1.1 完全一致；本次只是把同一渲染能力扩展到对话消息。
+
+## [1.1.1] - 2026-10-09
+
+### 新增
+
+- **Mermaid 语法自动修复**：首次渲染失败时，对 flowchart/graph 源做一次保守修复重试——为含英文括号的节点标签与边标签自动加引号（如 `W2[Codex / Claude Code (ACP)]`），成功后徽章显示"已自动修复"；图形/圆柱等特殊形状括号不受影响。真实世界文档（如含 `(ACP)`、`(IM/Web)` 的架构图）无需改动原文即可渲染。
+- 渲染失败提示补充常见错误说明；错误信息移到卡片工具栏下方，长源码时更易发现。
+
+### 修复
+
+- 测试脚本跨平台浏览器探测（Windows/macOS/Linux 系统浏览器与 Playwright 缓存），CI 可用。
+
+## [1.1.0] - 2026-10-09
+
+### 重写
+
+- **接入方式重构**：不再创建独立预览面板或接管对话产物卡片，改为直接接管 DSH **原生右侧文件预览**的 Markdown 渲染器（`sidebar.right.tab.document` 插槽，官方 key，`priority: -100`）。文件读取、权限校验、分页累积、刷新、标签页生命周期全部保留 DSH 原生行为。
+- **完全离线**：Mermaid 11.17、markdown-it、DOMPurify、highlight.js、KaTeX 与公式字体全部随包内置，渲染过程零网络请求。
+
+### 新增
+
+- KaTeX 行内 `$...$` 与块级 `$$...$$` 数学公式。
+- 脚注（markdown-it-footnote）、任务列表、GFM 表格、标题锚点与文内跳转。
+- Mermaid 图表卡片：图形/源码切换、全屏（缩放/拖拽）、下载 SVG、语法错误保留源码并给出原因。
+- 代码高亮（highlight.js common 语言集）。
+- 深浅主题跟随 DSH 主题自动重绘图表。
+- 相对路径图片按文档目录解析，经 DSH 原生鉴权文件接口（`api/file`）读取。
+- 文档级“查看源码”切换。
+
+### 安全
+
+- HTML 经 DOMPurify 净化：禁执行 `<script>`/`<iframe>` 等标签与事件属性；Mermaid 输出单独净化；`securityLevel: 'strict'`。
+- 本地图片仅接受绝对路径或文档同目录相对路径，拒绝协议相对与控制字符。
+
+### 修复（相对 1.0.0）
+
+- 修复流程图节点文字被 SVG 净化误删的问题（`htmlLabels: false`）。
+- 修复深色主题下表格文字对比度不足。
+- 修复快速连续打开文件时的陈旧渲染竞态（渲染中止 + 卸载清理）。
+
+### 测试
+
+- 新增真实浏览器自动化测试（`node test/browser.mjs`）：加载与发布一致的 bundle，验证 14 项能力，断言零外部网络请求、零页面异常。
+- 新增截图脚本（`node test/screenshots.mjs`）。
+
+### 兼容性
+
+- 适配 DSH `0.2.0-rc.2` 客户端插槽 API；`engines.dsh` 声明 `>=0.2.0-rc.2 <0.3.0-0`。旧版 0.1.x 未验证。
+
+## [1.0.0] - 2026-10-08
+
+首个内部版本：独立分屏预览面板 + 对话内 Mermaid 增强 + 产物卡片行（整合 dsh-mermaid 与 dsh-artifact-preview 思路）。已被 1.1.0 的原生接入方案取代，不再维护。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioAIEvolu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+# 📄 Markdown Studio for DeepSeek Harness
+
+**Mermaid diagrams, math formulas and syntax highlighting rendered right inside DSH's native right-sidebar file preview — and in chat messages.**
+
+The rendering engine ships with the plugin — **fully offline** · no document changes needed · disable to restore the stock renderer
+
+[![CI](https://github.com/BioAIEvolu/dsh-md-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/BioAIEvolu/dsh-md-studio/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-md-studio)](https://www.npmjs.com/package/dsh-md-studio)
+[![GitHub release](https://img.shields.io/github/v/release/BioAIEvolu/dsh-md-studio)](https://github.com/BioAIEvolu/dsh-md-studio/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness)
+[![中文文档](https://img.shields.io/badge/docs-中文-green)](README.md)
+
+[The same Mermaid block: stock preview vs Markdown Studio](docs/images/before-after.png)
+
+</div>
+
+---
+
+## Why
+
+DeepSeek Harness's right-sidebar preview is great — except ` ```mermaid ` blocks show up as raw code. Existing workarounds open a separate panel or fetch rendering engines from a CDN.
+
+**Markdown Studio takes over the native preview's Markdown renderer**: file reads, permission checks, reload and tab lifecycle all stay native — only the drawing is upgraded. Mermaid, markdown-it, KaTeX, highlight.js and DOMPurify ship **inside the bundle**, so diagrams work offline.
+
+| Stock preview | Markdown Studio |
+|---|---|
+| `​```mermaid` shown as code | Rendered in place as SVG + toolbar |
+
+## ✨ Features
+
+- **📈 Mermaid diagrams, chat + documents** — the same pipeline renders ` ```mermaid ` blocks in chat messages and in opened documents: flowcharts, sequence, gantt, pie and the full Mermaid 11 family; per-diagram toolbar with **diagram/source toggle · fullscreen (zoom & pan) · SVG download**; automatic re-render on theme change
+- **🩹 Syntax auto-repair** — the most common real-world breaker, ASCII parentheses inside node labels (`W2[Codex / Claude Code (ACP)]`), is repaired and rendered with an "auto-repaired" badge. No need to edit your documents
+- **📐 KaTeX math** — inline `$...$` and display `$$...$$`
+- **📝 Full GFM** — tables, task lists, footnotes, heading anchors
+- **🎨 Syntax highlighting** — highlight.js common languages
+- **🖼️ Local images** — relative paths resolve beside the document through DSH's authenticated file route
+- **📴 Fully offline** — zero rendering network requests (asserted by automated tests); remote images authored in the document still load from their URLs
+- **🛡️ Secure** — DOMPurify sanitization for both document HTML and diagram SVG; scripts never execute; Mermaid runs in `strict` mode
+
+## 📸 Screenshots
+
+| Dark | Light |
+|---|---|
+| ![Dark](docs/images/demo-dark.png) | ![Light](docs/images/demo-light.png) |
+
+## 🚀 Install
+
+> Requires DeepSeek Harness `0.2.0-rc.2+` (client slot API, see [Compatibility](#️-compatibility))
+
+**Option 1 · In-app plugin market (dshmarket)** — search `dsh-md-studio`.
+
+**Option 2 · CLI from GitHub**
+```sh
+dsh plugin --profile desktop add github:BioAIEvolu/dsh-md-studio
+```
+
+**Option 3 · CLI from npm (once published)**
+```sh
+dsh plugin --profile desktop add dsh-md-studio
+```
+
+Restart DSH Desktop, then open any `.md` file in the right sidebar.
+
+## 📖 Usage
+
+- A **Markdown Studio** marker and a **source toggle** appear above the document
+- Every Mermaid diagram gets its own toolbar: **diagram / source / fullscreen / download SVG**
+- Fullscreen supports wheel zoom, drag pan and fit
+- A broken diagram keeps its source plus the reason — other diagrams still render
+- Disable the plugin anytime to restore the stock renderer
+
+Try [docs/demo.md](docs/demo.md) — a document covering every feature.
+
+## 🧠 How it works
+
+No DOM scanning, no floating panel: the plugin registers on DSH's **official document-preview slot** and takes over the official Markdown key with higher priority.
+
+```mermaid
+flowchart LR
+    A[Open .md file] --> B[DSH native preview]
+    B --> C{document slot}
+    C -->|Markdown Studio| D[This renderer]
+    C -->|other types stay native| E[PDF / image / Excel / code]
+    D --> F[markdown-it + GFM]
+    D --> G[Mermaid]
+    D --> H[KaTeX]
+    F --> I[DOMPurify]
+    G --> I
+    I --> O[Right sidebar tab]
+```
+
+File reading, paging, reload and lifecycle remain DSH's job — the plugin only draws. Slot takeover is verified live via DSH Inspect: this plugin `active: true`, the official Markdown occupant yields.
+
+## ✅ Quality
+
+`node test/browser.mjs` loads the exact shipped bundle in a real Chromium with networking blocked (asserts **zero network requests, zero page errors**): 4 diagram types with visible labels, auto-repair, GFM, math, highlighting, toggles, fullscreen, SVG download, theme re-render, broken-diagram isolation, XSS sanitization, rapid file switching and disposal. Full list in the [Chinese README](README.md#-质量保障).
+
+## ⚠️ Compatibility
+
+- Built for **DSH `0.2.0-rc.2`** (`engines.dsh: >=0.2.0-rc.2 <0.3.0-0`); other versions unverified — open an issue if the slot API changes
+- Limits: 2M chars per document, 50k chars / 2000 lines / 2000 edges per diagram
+- Sanitized Mermaid output: diagram interactions and external references are disabled
+
+## 🛠️ Build from source
+
+```sh
+pnpm install --ignore-scripts
+node scripts/build.mjs        # lib/ incl. fonts and license notices
+node test/browser.mjs
+node test/screenshots.mjs     # regenerate docs images
+pnpm pack
+```
+
+`lib/client.js` is shipped in DSH ModuleLoader factory format; only React is required from the host.
+
+## 🙏 Credits
+
+- [dsh-mermaid](https://github.com/MrmoLabs/dsh-mermaid) and [dsh-artifact-preview](https://github.com/nirvanaslash/dsh-artifact-preview) — inspiration for the interaction design
+- Libraries: [Mermaid](https://mermaid.js.org/) · [markdown-it](https://github.com/markdown-it/markdown-it) · [DOMPurify](https://github.com/cure53/DOMPurify) · [highlight.js](https://highlightjs.org/) · [KaTeX](https://katex.org/) — full notices in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)
+
+## ⭐ Support
+
+If this plugin saves you time, please star the repo. Issues and PRs welcome — [中文文档](README.md).
+
+## License
+
+[MIT](LICENSE) © BioAIEvolu

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 📄 Markdown Studio for DeepSeek Harness
+
+**在 DSH 原生右侧文件预览中，把 Markdown 里的 Mermaid 图表、数学公式、代码高亮一次看全。**
+
+渲染引擎随插件内置，**完全离线可用** · 无需改动你的文档 · 停用即恢复官方渲染器
+
+[![CI](https://github.com/BioAIEvolu/dsh-md-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/BioAIEvolu/dsh-md-studio/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-md-studio)](https://www.npmjs.com/package/dsh-md-studio)
+[![GitHub release](https://img.shields.io/github/v/release/BioAIEvolu/dsh-md-studio)](https://github.com/BioAIEvolu/dsh-md-studio/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness)
+[![English](https://img.shields.io/badge/docs-English-green)](README.en.md)
+
+[同一份 Mermaid 代码块：官方预览 vs Markdown Studio](docs/images/before-after.png)
+
+</div>
+
+---
+
+## 为什么需要它
+
+DeepSeek Harness 的右侧文件预览很好用，但 **Mermaid 代码块只会显示为一堆源码**——架构图、时序图、流程图全都要靠想象。外部方案要么需要开独立面板、要么依赖 CDN 联网。
+
+**Markdown Studio 直接接管原生预览的 Markdown 渲染器**：文件读取、权限校验、刷新、标签页这些全部保留 DSH 原生行为，只有"画"的部分被增强。渲染引擎（Mermaid / markdown-it / KaTeX / highlight.js / DOMPurify）**随插件打包**，断网也能看图。
+
+| 官方预览 | Markdown Studio |
+|---|---|
+| `​```mermaid` 显示为代码块 | 就地渲染为 SVG 图 + 工具栏 |
+| 长文档来回滚动 | 图文混排，所见即所得 |
+
+## ✨ 特性
+
+- **📈 对话内 + 文档预览双渲染**：聊天消息里的 Mermaid 块与右侧打开的 Markdown 文档，用同一套管线就地渲染成 SVG 图
+- **📈 Mermaid 图表**：流程图、时序图、甘特图、饼图等 Mermaid 11 全系图型；每张图带 **图形/源码切换 · 全屏（缩放/拖拽）· 下载 SVG** 工具栏；深浅主题自动重绘
+- **🩹 语法自动修复**：真实文档里最常见的 `W2[Codex / Claude Code (ACP)]` 这类"标签含英文括号"语法错误，**自动修复后照常渲染**，并在徽章标注"已自动修复"——不用改你的文档
+- **📐 KaTeX 数学公式**：行内 `$...$` 与块级 `$$...$$`（文档预览）
+- **📝 完整 GFM**：表格、任务列表、脚注、删除线、标题锚点跳转
+- **🎨 代码高亮**：highlight.js 常用语言集
+- **🖼️ 本地图片**：相对路径按文档目录解析，经 DSH 原生鉴权接口读取
+- **📴 完全离线**：渲染零网络请求（有自动化测试断言兜底）；作者写在文档里的远程图片仍按原 URL 加载
+- **🛡️ 安全**：DOMPurify 双重净化（文档 HTML + 图表 SVG），禁执行脚本；Mermaid `strict` 模式
+
+## 📸 截图
+
+| 深色主题 | |
+|---|---|
+| ![深色主题完整渲染](docs/images/demo-dark.png) | ![浅色主题完整渲染](docs/images/demo-light.png) |
+| 深色 | 浅色 |
+
+## 🚀 安装
+
+> 需要 DeepSeek Harness `0.2.0-rc.2+`（客户端插槽 API 依赖，见 [兼容性](#️-兼容性)）
+
+**方式一 · 可视化插件市场（dshmarket）**
+在 DSH 设置 → 插件 → 市场中搜索 `dsh-md-studio`。
+
+**方式二 · 命令行（GitHub）**
+```sh
+dsh plugin --profile desktop add github:BioAIEvolu/dsh-md-studio
+```
+
+**方式三 · 命令行（npm，发布后可用）**
+```sh
+dsh plugin --profile desktop add dsh-md-studio
+```
+
+安装后重启 DSH Desktop，在右侧打开任意 `.md` 文件即可。
+
+## 📖 使用
+
+打开 Markdown 文件后：
+
+- 文档顶部出现 **Markdown Studio** 标识与 **查看源码** 按钮（整篇源码/渲染视图切换）
+- 每个 Mermaid 图表自带工具栏：**图形 / 源码 / 全屏 / 下载 SVG**
+- 全屏模式支持滚轮缩放、拖拽平移、一键适应
+- 语法错误的图表保留源码并给出原因，**不影响文档里其他图表**
+- 不想用了？在插件管理中停用，官方渲染器原样恢复
+
+试试仓库里的 [docs/demo.md](docs/demo.md)——一份覆盖全部特性的验证文档。
+
+## 🧠 工作原理
+
+不扫描页面 DOM、不开独立窗口，而是注册 DSH 文档预览的**官方扩展插槽**，以更高优先级接管官方 Markdown 渲染键：
+
+```mermaid
+flowchart LR
+    A[打开 .md 文件] --> B[DSH 原生文件预览]
+    B --> C{document slot}
+    C -->|Markdown Studio 接管| D[本插件渲染器]
+    C -->|其他类型保持官方| E[PDF / 图片 / Excel / 代码]
+    D --> F[markdown-it + GFM]
+    D --> G[Mermaid 图表]
+    D --> H[KaTeX 公式]
+    F --> I[DOMPurify 净化]
+    G --> I
+    I --> O[右侧标签页渲染]
+```
+
+- 文件读取、分页、刷新、生命周期仍由 DSH 管理——插件只负责"画"
+- 通过实时 Inspect 验证插槽注册：本插件 `active: true`，官方 Markdown 渲染器自动让位
+
+## ✅ 质量保障
+
+`node test/browser.mjs` 加载与发布完全一致的 bundle，在真实 Chromium 中断网验证（**零网络请求、零页面异常** 断言）：
+
+| 验证项 | |
+|---|---|
+| Mermaid 四类图渲染 + 节点文字可见 | ✅ |
+| 含括号标签自动修复 | ✅ |
+| GFM 表格 / 任务列表 / 脚注 | ✅ |
+| 行内 + 块级 KaTeX | ✅ |
+| 代码高亮 | ✅ |
+| 图形/源码切换、全屏、SVG 下载 | ✅ |
+| 深浅主题重绘 | ✅ |
+| 非法图表隔离（一图坏不拖累整页） | ✅ |
+| XSS 净化（脚本不执行） | ✅ |
+| 快速切换文件无陈旧渲染 | ✅ |
+| 卸载清理 | ✅ |
+
+## ⚠️ 兼容性
+
+- 适配 **DSH `0.2.0-rc.2`**（`engines.dsh: >=0.2.0-rc.2 <0.3.0-0`）；其他版本未验证，升级 DSH 后如插槽 API 变更请提 issue
+- 文档上限 200 万字符；单图 5 万字符 / 2000 行 / 2000 边
+- Mermaid 输出经净化：图表内的交互点击、外部图片引用会被禁用
+
+## 🛠️ 从源码构建
+
+```sh
+pnpm install --ignore-scripts
+node scripts/build.mjs        # 产出 lib/（含字体与三方授权清单）
+node test/browser.mjs         # 真实浏览器测试
+node test/screenshots.mjs     # 重新生成文档截图
+pnpm pack                     # 打包 dsh-md-studio-x.y.z.tgz
+```
+
+构建产物 `lib/client.js` 为 DSH ModuleLoader 工厂格式，仅依赖宿主 React，其余依赖全部打包。
+
+## 🗺️ Roadmap
+
+- [x] 对话内 Mermaid 渲染（v1.2 已实现；与 [dsh-mermaid](https://github.com/MrmoLabs/dsh-mermaid) 插件共存安全，互不双渲染）
+- [ ] 图表导出 PNG
+- [ ] 目录（TOC）侧栏
+- [ ] 设置页（字号、图表方向）
+
+## 🙏 致谢
+
+- [dsh-mermaid](https://github.com/MrmoLabs/dsh-mermaid)（MrmoLabs）与 [dsh-artifact-preview](https://github.com/nirvanaslash/dsh-artifact-preview)（nirvanaslash）——1.0 版的整合来源，1.1 的交互设计参考
+- 渲染库：[Mermaid](https://mermaid.js.org/) · [markdown-it](https://github.com/markdown-it/markdown-it) · [DOMPurify](https://github.com/cure53/DOMPurify) · [highlight.js](https://highlightjs.org/) · [KaTeX](https://katex.org/)，完整授权见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)
+
+## ⭐ 支持项目
+
+如果这个插件帮你省掉了"改文档语法"和"切窗口看图"的时间，欢迎点个 Star；问题与需求请提 [Issue](https://github.com/BioAIEvolu/dsh-md-studio/issues)，PR 欢迎。
+
+English documentation: [README.en.md](README.en.md)
+
+## License
+
+[MIT](LICENSE) © BioAIEvolu