dsh-code-render

August 14, 2026 · View on GitHub

让 DeepSeek Harness（dsh）网页端像 Claude 一样：模型输出 ```svg、```mermaid 或 ```html 代码块时，对话流中直接渲染出图表/预览，并提示模型用图表代码块代替文字/ASCII 描述架构图、流程图、时序图等。

✨ 功能特性

会话文件面板（Artifacts）：右侧抽屉自动展示本会话生成的文件——长图表代码块自动保存为会话临时文件，模型用 write/edit 写入本地目录的文件也会自动出现；可预览（html/svg 渲染）、复制、下载、删除，点 ✕ 关闭
临时文件不落工作区：长代码保存到 ~/.dsh/session-artifacts/<sessionId>/（跟随会话、重启可恢复、不在工作目录）
三种渲染器，一个框架：svg（消毒后直插 DOM）· mermaid（strict 模式流程图/时序图等）· html（沙箱 iframe 交互预览），共享扫描/流式/折叠/清理机制
Mermaid 离线可用：mermaid 运行时随插件本地分发（vendor/），由 host 半区提供本地路由，不依赖外网；CDN 仅作兜底
行间自动渲染：对话流中的图表代码块，语言栏下方自动出现预览面板（"SVG 渲染"/"Mermaid 渲染"/"HTML 预览"）
默认只看图：代码块默认收起，只展示渲染结果；点击"显示代码"随时展开查看/复制源码
流式实时更新：svg 边生成边渲染；mermaid/html 在消息定型后渲染，中途失败自动保留上一次成功预览
模型优先图表、不落盘：host 半区注入系统提示词段落，引导模型按场景选择 svg/mermaid/html，并默认不把图表保存到工作目录，直接在对话流中渲染
安全分层：svg 消毒后插入；mermaid 以 securityLevel: 'strict' 渲染；html 在 sandbox="allow-scripts"（无 same-origin）iframe 中隔离预览——模型代码无法触碰宿主页面
优雅降级：mermaid 库本地与 CDN 均加载失败，或语法错误时，自动还原为普通代码块，不破坏消息
零依赖、零手动操作：安装后每次启动 dsh web 自动生效，无需 Cordis 审批或 cordis_run

🏗 工作原理

架构图：host 半区注入提示词，client 半区 MutationObserver 扫描代码块并渲染

插件是一个 dsh profile 级 Cordis 插件包，分为两个半区：

半区	文件	职责
host（Node 进程）	`package/lib/index.js`	提示词段落 + `/code-render-vendor/` mermaid 本地路由 + `/code-render-artifacts/` 会话文件 API + 监听 `tools/result` 收录本地写入文件
client（浏览器）	`package/lib/client.js`	代码块渲染器分派（svg/mermaid/html）+ 长代码自动保存 + 右侧会话文件面板（shell.overlay）

注册方式：在 profile 的 cordis.patch.yml 里 insert 一行 code-render，重启后 loader 自动加载；clientModules 扫描到 dsh.client 声明后把 bundle 注入页面 window.__DSH_BOOT__，页面加载即激活——不需要任何审批流程。

📦 目录结构

dsh-code-render/
├── install.sh          # 一键安装脚本
├── uninstall.sh        # 卸载脚本
├── package/            # 插件包本体
│   ├── package.json    # dsh.client 声明（platform: web）
│   ├── lib/
│   │   ├── index.js    # host 半区：提示词段落 + 本地静态路由
│   │   └── client.js   # client 半区：渲染器框架（svg/mermaid/html）
│   └── vendor/         # 本地分发的 mermaid 运行时（mermaid.min.js）
└── assets/             # README 用图

🚀 快速安装

前置要求

已安装 DeepSeek Harness 并用 web profile 启动过（~/.dsh/profiles/web 存在）
macOS / Linux（脚本依赖 bash + python3，两者系统自带）

一键安装

git clone https://github.com/lawrence-jia/Dsh-plugins.git
cd Dsh-plugins
./install.sh                 # 默认安装到 web profile
# 或者安装到其他 profile：
./install.sh --profile my-profile

脚本做两件事：

把 package/ 复制到 ~/.dsh/profiles/node_modules/@deepseek-ai/dsh-client-ui-code-render/
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 注册一行：

- insert:
    - id: code-render
      name: '@deepseek-ai/dsh-client-ui-code-render'

手动安装（不想用脚本）

# 1. 复制插件包
mkdir -p ~/.dsh/profiles/node_modules/@deepseek-ai/dsh-client-ui-code-render
cp -R package/. ~/.dsh/profiles/node_modules/@deepseek-ai/dsh-client-ui-code-render/

# 2. 在 ~/.dsh/profiles/web/cordis.patch.yml 末尾追加（如不存在则创建）：
#    - insert:
#        - id: code-render
#          name: '@deepseek-ai/dsh-client-ui-code-render'

生效

重启 dsh web 进程（退出再启动），打开页面即可使用。安装脚本是幂等的：重复执行不会重复注册。

💡 使用说明

无需任何操作，一切自动发生：

让模型画图或写 demo："画一下这个项目的架构图" / "这个流程怎么走？画个时序图" / "做一个按钮组件的效果演示"
模型会按场景输出 ```svg / ```mermaid / ```html 代码块——不会保存到工作目录（提示词已引导；仅当你明确要求保存时才写盘）
对话流中直接显示渲染结果（SVG 渲染 / Mermaid 渲染 / HTML 预览），代码块默认收起
想看源码：点击 显示代码 展开（复制按钮始终可用）；再点 收起代码 只看结果
历史消息里的图表代码块：刷新页面后也会自动补上渲染

会话文件面板（Artifacts）

长图表代码块（≥6000 字符的 svg/mermaid/html）自动保存为会话临时文件（diagram-1.svg、diagram-2.mmd…），右侧自动弹出面板
模型用 write/edit 写入本地目录的文件也会自动出现在面板中（标记"本地"）
面板操作：点击文件查看内容（html 沙箱预览 / svg 渲染预览 / 其他源码），复制 / 下载 / 删除，点 ✕ 关闭（关闭后不再自动弹出，可再次打开）
文件存于 ~/.dsh/session-artifacts/<sessionId>/：跟随会话、进程重启可恢复、不在工作目录；删除面板中的"本地"文件只移除会话记录，不影响磁盘上的原文件

提示：svg 渲染识别 svg / svg+xml 语言（以及流式期间以 <svg 开头的内容）；mermaid 识别 mermaid；html 识别 html。语言写错（如 ```xml）不会渲染，可以让模型重新输出。

🗑 卸载

./uninstall.sh            # 或 --profile 指定 profile

删除插件包并从 cordis.patch.yml 移除注册行，重启后即恢复原状。

❓ 常见问题

安装后没有渲染效果？

确认已重启 dsh web 进程（组合文件只在启动时加载）
确认代码块语言是 svg（banner 上会显示 svg 字样）
确认页面加载的 bundle 是新的：强制刷新（Cmd+Shift+R）一次
查看启动日志中 loader 对 code-render 行的加载是否成功

会渲染用户消息里的代码块吗？ 会——只要满足语言/内容识别条件都会渲染，不区分消息来源。

Mermaid 不渲染/显示为代码块？ Mermaid 运行时随插件本地分发（package/vendor/mermaid.min.js），由 host 半区通过 /code-render-vendor/ 路由提供，默认完全离线可用；本地加载失败时自动回退 CDN（jsdelivr）。两者都失败或语法错误时降级为普通代码块（浏览器控制台有 warn 日志）。若改动过 vendor/ 文件，需重启 dsh 进程使路由缓存刷新。

HTML 预览安全吗？ 模型 HTML 在 sandbox="allow-scripts" 的 iframe 中运行——脚本可以执行（保证 demo 可用），但没有 same-origin 权限，无法读取/修改宿主页面，也无法访问 dsh 的会话数据。iframe 高度由内部脚本通过 postMessage 自适应报告。

为什么还会出现 .svg 文件？ 提示词默认禁止把图表写盘（"不要用 write 等工具把图表保存为本地文件"），但你明确要求保存文件时模型仍会写盘——这是刻意保留的能力。此时文件会同时出现在右侧面板（"本地"标记）方便查看/复制/下载；历史上已生成的文件需要手动删除。

会话文件存在哪里？ ~/.dsh/session-artifacts/<sessionId>/（每个文件一个 JSON 记录）。不在工作目录、跟随会话、进程重启后自动恢复。卸载插件不会删除这些文件；删除面板中的"本地"类型记录不影响磁盘原文件。

安全性如何？ 三种渲染各有边界：SVG 先经 DOMParser（XML 模式）解析，再剥离 <script>、<foreignObject>、<iframe>、<object>、<embed>、所有 on* 事件属性、javascript: URL、a/use/image 的外部引用后才插入页面；Mermaid 以 securityLevel: 'strict' 渲染（禁用 HTML 注入与点击回调）；HTML 在沙箱 iframe 中隔离。原始代码块内容从不作为 HTML 注入。

版本兼容性：依赖 dsh Web GUI 的 .md-code-block DOM 标记与 --dsw-* 主题变量（ui-primitives 的 CodeBlock）。dsh 大幅改版后若失效，更新本仓库的 client.js 即可。

📤 发布到 GitHub

仓库与推送

本插件托管在 **https://github.com/lawrence-jia/Dsh-plugins**（远端为 ssh://git@ssh.github.com:443/lawrence-jia/Dsh-plugins.git，走 GitHub SSH-over-443 通道）。

cd dsh-code-render
git remote -v        # 应显示 origin -> ssh://git@ssh.github.com:443/lawrence-jia/Dsh-plugins.git
git add -A && git commit -m "..." && git push

发布后维护

修改 package/lib/*.js 后：git add -A && git commit && git push，用户重新 clone 或 git pull 后重跑 ./install.sh
建议开一个 Release：GitHub 仓库页面 → Releases → Create a new release，打 tag（如 v1.0.0），把安装命令贴进 release notes
欢迎提交 Issue/PR：效果反馈、消毒规则补强、多 profile 支持等

（可选）发布到 npm

本插件通过安装脚本分发，不需要 npm 发布。如需走包管理器：

把 package/ 改名为独立包（@deepseek-ai scope 无权发布，请改成你的 scope 或无 scope 名），package.json 增加 version/license/repository 字段
cd package && npm publish
使用者 npm install -g <包名> 后仍需按"手动安装"第 1 步复制到 ~/.dsh/profiles/node_modules/ 并注册 patch 行——安装脚本是更省事的路径

📄 License

MIT