内联矢量图 0mao0/dsh-inline-figures

dsh-inline-figures

| name | dsh-inline-figures |
| description | 当 DeepSeek Harness（DSH）的回答需要被读懂，而不是被扫一眼时，就用 dsh-inline-figures。它给模型一个 draw_figure 工具，在回复的段落之间内联渲染干净的矢量图——文字、图、文字——让部件与关系、流程、时序、对比和数量变成一张图，而不是一堵文字墙。图是确定性的 SVG，写进会话工作区，再通过普通的 Markdown 图片通道嵌入：不会塌缩成工具卡片，也不涉及任何客户端代码或新 UI。 |

关键词。 DeepSeek Harness 插件 · DSH 宿主插件 · Cordis bundle · draw_figure · 内联 SVG 图 · 文字–图–文字式回答 · AI 聊天里的矢量图 · ASD-STE100 图标签 · LLM 输出可读性

左边是同一个回答不用插件的样子，右边是用了插件的样子

同样的事实，同样的回答。左边：纯 Markdown。右边：模型画出了结构，并删掉了它所替代的那段文字。

为什么

模型的长回答就是一堵文字墙。有两种公认的解法，这个插件两种都做：

- 写得更朴素。 注入的指引要求行文大致达到 ASD-STE100 的 80%——简化技术英语，也就是飞机维修手册用的受控语言。Andrej Karpathy 推荐用 ASD-STE100 正是为了解决这个问题，并且把图排在文字之上，作为理解模型输出的下一步。这里的图标签是同一风格里最严格的一档：名词短语，最多六个词，一个标签一个概念。
- 把结构画出来。 凡是涉及部件、流程、时序、对比或数量的内容，都变成一张图而不是一段文字，放在它能说明问题的位置。

工作原理

插件如何工作：模型调用 draw_figure，宿主插件校验、渲染、写文件并返回一行 Markdown，回复再把它内联渲染出来

一轮对话，三步。模型判断某个点需要配图，调用 draw_figure；宿主插件校验规格、渲染、写文件，返回一行 Markdown；模型把这行粘进回复，普通的 Markdown 图片就把它按全宽渲染出来。没有新 UI，也没有客户端代码——图和消息里任何其他图片走的是同一条图片通道。

安装

DSH 自带插件管理器，不用手动复制任何东西，也不用对着你的配置档跑包管理器命令。

from npm
dsh plugin --profile <profile> add dsh-inline-figures

or straight from this repository, no registry involved
dsh plugin --profile <profile> add github:0mao0/dsh-inline-figures

Web 侧边栏的 Plugins 页面用表单做同样的事，智能体也可以用 plugin_manager 工具来做（install_bundle，target 填本地克隆的目录）。

然后重启 DSH。宿主侧的插件代码每个进程只加载一次，所以新的 JavaScript 生成需要重启；在那之前，插件列表可能一直显示旧状态。

没有构建步骤。这个插件导入的包由 harness 提供，sharp——可预览图形背后的光栅化器——自带预编译二进制文件。

安装前 harness 会检查什么

package.json 固定了本次发布验证过的 DSH 运行时版本，写在 @deepseek-ai/dsh- 的 peer dependencies 里。插件管理器会先评估这些 peer，运行时版本不同就拒绝安装，报 incompatible-version——干脆地拒绝，而不是装上一个能挂载却行为异常的插件。如果非要在别的运行时上跑，就授予精确版本豁免：

dsh plugin --profile <profile> allow-version dsh-inline-figures@<version> --dsh-version <runtime> --accept-risk

已针对 dsh 0.2.0-rc.2（cordis 4.0.4）验证。如果你需要一台完全连不上 registry 的机器，docs/MAINTAINER-NOTES.md 保留了离线安装器，作为不受支持的兜底方案。

draw_figure 工具

draw_figure({ spec, alt, slug? }) -> { path, markdown, warnings }

预设 spec，帮你排好版——这些永远不要手写坐标：

{ "kind": "compare", "title": "Current vs target",
"rows": [{ "left": { "label": "Manual review" },
"right": { "label": "Automated gate", "tone": "ok" } }] }

返回的那一行，原样粘贴：

Current vs target

| kind | 形状 | 限制 |
| raw_svg | 手写 SVG，用于树、分支流水线、状态机，以及任何自定义图形 | 32 KB spec |
| architecture | 分层方框、P0/P1 徽标、危险分组、反馈边 | 2–6 层 × 1–6 个节点，8 条边 |
| compare | 左右两列，带语义色调（default/danger/ok/muted） | 1–6 行 |
| timeline | 纵向步骤，标记为 done/active/todo | 2–10 步 |
| chart | bar、line 或 pie，带坐标轴刻度和标签自动旋转 | 1–12 个数据点 |

spec 在排版前会先校验，每个错误都会指出出错的字段，所以一次错误的调用返回的是可修复的提示，而不是一张坏图。图形一律用 SVG——绝不用 ASCII art、Unicode 制表符或代码块。
raw_svg 是自由结构的主要路径。清洗器会拒绝 script、doctype、entity 和 iframe，剥掉事件属性、外部引用、<image> 和 <foreignObject>，然后注入主题样式表和箭头 marker，所以手写的图形依然跟随当前配色方案。

写入磁盘的内容

只有会话工作区，任何东西都不离开本机。

<session workspace>/.dsh-figures/<session>/
├── N-slug.svg vector original
├── N-slug.png the raster the reply embeds
└── .gitignore holds , so git status stays clean

- 没有网络请求，没有上传，没有遥测。 渲染在本地完成；一轮对话里唯一的流量就是模型调用本身。
- 按会话隔离。 图形落在绘制它的那个会话的目录里。每个目录保留最新的 200 个；更早的按修改时间清理，SVG 被清理时对应的 PNG 一并删除。
- 图形是引用，不是副本。 删掉文件后，旧回复会显示图片损坏，所以把这个目录当作对话的一部分，而不是临时空间。
- 如果栅格化失败，回复改为嵌入 SVG，插件会在自己旁边写入 raster-diagnostic.txt，让失败对你可见，而不只是对模型可见。

每次回答不会写入其他内容。安装期可能在其他位置留下两样东西：离线回退方案在 ~/.dsh/vendor 下的暂存副本，以及配置档 node_modules 里的 sharp。

脱离 DSH 使用引擎

lib/ 不从 @deepseek-ai/* 或 cordis 导入任何东西，有测试强制保证这一点。./engine 入口是普通模块：

// from a clone: import { ... } from './lib/engine.js'
// from the package: import { ... } from 'dsh-inline-figures/engine'
import { drawFigure, validateSpec, sanitizeSvg, GUIDANCE_TEXT } from './lib/engine.js'

const { svg, warnings } = drawFigure({
kind: 'timeline', title: 'Rollout',
steps: [{ label: 'Design', state: 'done' }, { label: 'Build', state: 'active' }],
})

想在自己的智能体里复用它：注册一个 schema 相同的等效工具，把 GUIDANCE_TEXT 粘贴进你的系统提示词，再通过你的 Markdown 图片通道渲染返回的 SVG（或你自己栅格化后的结果）。

开发

node --test # full suite, no dependencies
$env:UPDATE_GOLDEN='1'; node --test test/architecture.test.js # refresh layout snapshots, then eyeball the diff
node scripts/make-readme-image.mjs # rebuild the before/after images
node scripts/make-readme-diagram.mjs # rebuild the how-it-works diagrams
node scripts/_repro-png-check.mjs # real cordis: mounts the plugin, executes all five kinds, proves unload cleanup
node scripts/_repro-nudge.mjs # real cordis: drives the nudge events
test/compliance.test.js 是官方宿主契约的关卡，契约内容见 Install：宿主包作为 peer、兼容性检查已启用、补丁行与包名匹配、可发布的身份、展示元数据，以及通过 ctx.effect 注册的每一项资源。

在沙箱化的 shell 里，node --test 可能报 spawn EPERM（它会给每个测试文件起一个子进程）。node --test --test-isolation=none 会在单个进程里跑同一套测试。

发布步骤、未修复的缺陷、离线安装的兜底方案，都在 docs/MAINTAINER-NOTES.md。

License

MIT