前言¶
在 DeepSeek Harness（DSH）里让智能体画图，常见结果是 SVG 或 HTML 能渲染，但读者第一眼不知道「该先看哪、结论是什么」。Archify 一类工具把 JSON 规范接到确定性渲染和门禁上；diagram-design 提供版式与无障碍 SVG。二者都不保证页面具备完整的「阅读家具」——结论标题、要点、编号阅读路径、图例与说明，并在发布前被机器校验。
readable-diagrams 把这一层补全：一份 JSON 规范 → 单文件 HTML，且必须通过结构/无障碍门禁与可读性门禁，页面才允许交付。下面介绍它作为 DSH 工作流插件能做什么、如何安装，以及如何按仓库示例复现渲染与检查。
这是什么¶
- 定位：Diagrams a reader understands on first look — one JSON spec to a self-contained HTML page, with a machine-checked comprehension gate。同时可作为 Claude Code / Codex 的 skill 使用。
- 维护者：仓库归属 bingomu/readable-diagrams；npm 包名为
dsh-readable-diagrams，当前插件包版本 1.1.0（以 release 标签安装为准）。 - 许可证：MIT；DSH 要求 >=0.2.0，插件 wrapper 需 Node 20+，渲染与门禁脚本需 Python 3.9+，无 npm 运行时依赖、无构建步骤。
社区目录页：skillhub.cn 插件条目。该目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系；DSH 本身遵循「一切皆插件」的扩展方式。
核心功能¶
规范驱动的图类型与扩展¶
仓库说明中列出的能力包括：
- 九种 spec 驱动类型：architecture、flow、state、sequence、timeline、tree、layer stack、bar、quadrant。
- 手绘式图表族：line、scatter、sankey、radar、heatmap、Gantt、Venn、funnel、journey 等，共用同一套版式与门禁。
- 导入 / 导出：Mermaid、draw.io、Excalidraw 导入；SVG、PNG 导出。
完整字段见仓库内 skills/readable-diagrams/references/spec-schema.md。
两道门禁（均需通过）¶
生成 HTML 后不得手改页面；失败则改 spec、重新渲染、再跑检查。非零退出即失败。
comprehension_check.py title ≤60 · takeaway · caption · numbered reading path ·
legend coverage · ≤2 focal accents · node budget ·
edge-label coverage · type floors · contrast ·
orthogonal connectors · accessible SVG exists
self_check.py role=img · title first · desc · prefixed ids ·
single-file safety · painted content inside viewBox
交互与版式¶
- 悬停高亮、无 JavaScript：悬停节点时其余变暗、关联边高亮；悬停阅读步骤可对应节点；支持错峰入场；
prefers-reduced-motion与打印回退为静态帧。 - 编辑皮肤：明/暗主题，CJK 排版（12px 下限、中文标签 register 切换），4px 网格，无阴影。
- 示例：
skills/readable-diagrams/examples/下八个示例页，均通过两道门禁。
项目在 Archify（Apache-2.0）与 diagram-design（MIT）之上，额外定义「可读性契约」并由 checker 强制执行；设计 token 与连接器语法自 diagram-design 改编并注明出处，见 THIRD_PARTY_NOTICES.md。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前请自行查看仓库源码与 MIT 许可证，确认可接受后再添加。
DeepSeek Harness 官方安装方式（README Install 表）：
dsh plugin --profile desktop add https://github.com/bingomu/readable-diagrams/archive/refs/tags/v1.1.0.tar.gz
也可在 DSH 的 Plugins → Add 页面填入同一 URL。重启应用后，skill 会出现在会话目录中。
其他宿主（非 DSH 正文重点，供对照）：Claude Code 可用 marketplace 或复制 skills/readable-diagrams/；Codex 可复制到 ~/.codex/skills/ 或使用 .codex-plugin/；通用 agent 可读 SKILL.md 并执行 bash install.sh。
典型用法¶
安装或取得仓库内容后，skill 目录为 skills/readable-diagrams。下面步骤与 README Quick start 一致：先渲染示例 spec，再跑两道门禁，最后在浏览器打开输出。
SKILL=skills/readable-diagrams
python3 "$SKILL/scripts/render.py" "$SKILL/examples/architecture.spec.json" -o /tmp/page.html --json
python3 "$SKILL/scripts/self_check.py" /tmp/page.html
python3 "$SKILL/scripts/comprehension_check.py" /tmp/page.html
在本地用浏览器打开 /tmp/page.html 即可查看悬停层效果。
最小 spec 示例（architecture 类型，含 meta 与 reading_path）：
{
"type": "architecture",
"meta": {
"title": "一次下单请求如何穿过网关到达数据库",
"takeaway": "写路径只有一条；风控与通知是旁路。",
"caption": "从左往右是请求方向，实线同步、虚线异步。",
"reading_path": ["client", "gateway", "orders", "pg"]
},
"nodes": [
{"id": "client", "label": "客户端", "kind": "input"},
{"id": "gateway", "label": "API 网关", "kind": "backend"},
{"id": "orders", "label": "订单服务", "kind": "focal"},
{"id": "pg", "label": "订单库", "kind": "store"}
],
"edges": [
{"from": "client", "to": "gateway", "label": "HTTPS", "variant": "accent"},
{"from": "gateway", "to": "orders", "label": "POST /orders", "variant": "accent"},
{"from": "orders", "to": "pg", "label": "写入", "variant": "accent"}
]
}
智能体侧操作说明见 skill 内 SKILL.md；贡献者在 push 前可运行 python3 scripts/check.py（CI 同款：渲染全部 example、跑门禁、解析插件入口）。
适用场景与注意¶
适合：需要在文档、设计评审或 agent 交付物里输出「读者能按路径读完」的架构/流程类图；希望用脚本门禁约束标题、对比度、正交连接器与 accent 预算，而不是事后人工改 HTML。
注意：
- 门禁失败是正常反馈，应改 JSON spec 后重新
render.py，不要 patch 生成页。 - 对比度、节点预算、图例覆盖等规则由
comprehension_check.py与self_check.py具体实现；扩展 spec 前先读references/下说明。 - DSH 插件仅注册 skill 与 bundle（
lib/index.js、cordis.patch.yml）；实际渲染依赖本机 Python 3.9+ 环境。
结尾¶
readable-diagrams 把「人能读懂」写成可检查的契约：一份 JSON、单文件 HTML、两道 Python 门禁。作为 DSH 工作流插件，它让会话里的制图步骤有明确交付标准。
- 目录页：https://www.skillhub.cn/plugins/bingomu/readable-diagrams
- 源码与文档：https://github.com/bingomu/readable-diagrams
