Newshot

为 AI 编程代理提供在 Markdown 中创建图表的能力

Translation(model translation, not the source's own text)

仓库文件导航

题图
题图

docu.md skills

面向 docu.md Markdown 流水线的 Agent 技能。一个技能包,按读者的需求组织,背后的渲染引擎作为实现参考。

242 个经过验证的示例 · 183 个场景 · 31 个目标领域 · 5 个引擎,每个图形都从 styles/ 中定义的九种主题之一取色,并由源表生成,由 scripts/check-all.mjs 把关(主题漂移 · 对比度 · 块渲染 · 块覆盖率 · 主题使用 · 结构),再加上用于完整渲染流程的 scripts/verify-examples.mjs。

技能遵循 Agent Skills 格式。

🧭 快速导航

🚀 安装 • 🧩 技能包 • ⚙️ 引擎 • �️ documd CLI • �🔀 迁移的技能 • 🔗 链接

🚀 安装

快速安装(推荐)


        npx skills add markdown-viewer/skills
      

此方法适用于多种 AI 编程 Agent(Claude Code、Codex、Cursor 等),并能发现 documd-visuals 包。

手动安装

面向 Claude Code(手动)


        cp -r skills/documd-visuals ~/.claude/skills/
      

面向 claude.ai

将该包添加到项目知识中,或将 SKILL.md 的内容粘贴到对话中。

面向 GitHub Copilot / VS Code

将包放入 .github/skills/ 目录后会自动被检测到。

🧩 技能包


        skills/
├── documd-visuals/        ← 技能包 —— 这里唯一的技能,也是唯一被安装的内容
│   ├── SKILL.md           ← 路由:铁律、31 个目标、能力边界
│   ├── converting.md      ← documd CLI:安装、格式、标志、导出后保留的内容
│   ├── catalog/           ← 每个场景:领域、引擎、层级、示例文件
│   ├── goals/             ← 每个目标领域一份指南
│   ├── engines/           ← 每个引擎的参考 + coverage/ 台账(先单元,再按目标列示例)
│   ├── examples/          ← 242 个经过验证的示例,按目标领域分组
│   └── styles/            ← palette.md(契约)+ themes/<theme>.md(取值 + 每个引擎一个块)
├── research/              ← 引擎档案:覆盖率台账 + 验证说明(仅仓库内,从不随包发布)
└── scripts/               ← 仓库级把关脚本(不随包发布)
      

该包是自包含的:它从不引用 research/ 或 scripts/,一旦引用,把关脚本就会让构建失败。如果你安装了该包,它所引用的一切都在包内——而包内的每个文件都能从 SKILL.md 到达,validate-skills.mjs 会对此强制执行。唯一的例外是 LICENSE.md:法律附件不属于路由内容,因此它随包发布,但不由路由文件链接。

research/ 和 scripts/ 不会被当作技能发现:CLI 通过定位 SKILL.md 来查找技能,而这两个目录都不包含 SKILL.md。已验证——npx skills add ./skills --list 报告恰好只有一个技能:documd-visuals。

请求如何被路由

  • SKILL.md 将读者的意图匹配到 31 个目标领域之一,这些领域归入四个元集群:数据与指标 · 流程与系统 · 基础设施与治理 · 知识与表达。
  • goals/<domain>.md 列出该领域的场景,以及实现这些场景的示例文件。
  • engines/<engine>.md 涵盖所选引擎的限制和反模式。

目标领域

Meta 集群领域
A — 数据与指标service-reliability · ops-monitoring · delivery-throughput · goal-and-status-reporting · product-metrics · business-reporting · go-to-market · cost-and-budget · data-exploration
B — 流程与系统engineering-operations · incident-management · process-and-workflow · software-design · software-behaviour · dependencies-and-relations · system-architecture
C — 基础设施与治理cloud-architecture · data-platform · network-topology · security-and-compliance · enterprise-architecture · organization-and-roles · people-and-hiring
D — 知识与表达knowledge-and-outline · planning-and-roadmap · migration-and-rollout · comparison-and-selection · internal-documents · catalogues-and-inventories · customer-and-partner-comms

⚙️ 引擎

推荐 — 使用以下引擎编写新内容

围栏引擎用途
plantuml / pumldraw-uml 1.5.2 → drawio2svgUML、ArchiMate、BPMN、流程、云/网络/安全架构、依赖图、9,514 个模具图标
vega / vega-litevega 6.4.0 / vega-lite 6.4.3需要数据变换、分面、统计的图表
echartsecharts 6.1.0报告级图表、仪表盘、仪表、注释
infographic@antv/infographic 0.2.20模板驱动的信息图:路线图、序列、对比
(bare HTML)内置系统架构图、卡片、备忘录和页面级布局

其他引擎均不推荐。该包未记录其他引擎,新内容使用以上五种;被排除的名称唯一出现的地方是 SKILL.md 的描述,这样当用户要求某个引擎时,agent 能识别它们并予以拒绝。

🛠️ documd CLI

该包将图形作为 Markdown 中的文本绘制,由查看器实时渲染——作者无需预先渲染任何内容。documd CLI 是可选的导出部分:它将整个 Markdown 文档渲染为成品文件,并将图表源渲染为图像。它记录在包内——documd-visuals/converting.md,由 SKILL.md 链接——因此安装该技能的 agent 知道导出路径存在。

安装该技能不会安装 CLI,安装器也无法被设置为安装它。npx skills add 会将文件复制或符号链接到 agent 的技能目录中;Agent Skills 格式没有安装钩子字段,CLI 在 add 期间也不运行任何自己的脚本。技能包在任何时刻都无法触发 npm install。请将 CLI 视为技能所指向的独立工具。

使用它无需安装任何东西:


        npx @markdown-viewer/documd report.md report.docx                 # also .pdf .epub .html
npx @markdown-viewer/documd architecture.puml architecture.svg    # also .png
      

如果同一命令反复运行,请安装一次——这会提供 documd 二进制文件:


        npm install -g @markdown-viewer/documd
      
⚠️ 使用作用域。npm 上的裸名称 documd 是一个无关的包(“markdown object notation”)。npx documd 获取的是那个包,而不是此 CLI。请始终写 @markdown-viewer/documd。

npm 发布版与扩展版本号相同,因此 npx 运行的就是此处记录的构建。

🔀 迁移的技能

此仓库过去发布 14 个以引擎和领域命名的技能。它们现在是一个包,其内容是重写的,而非复制的:

旧技能新位置
umlengines/plantuml.md , engines/plantuml-stencils/ , examples/software-design/ , examples/software-behaviour/
cloud · network · security · iot · data-analyticsexamples/cloud-architecture/ , network-topology/ , security-and-compliance/ , data-platform/
archimate · bpmn · mindmapexamples/enterprise-architecture/ , process-and-workflow/ , knowledge-and-outline/
vega · graphviz · infographicengines/vega.md , engines/infographic.md — graph 示例已改写为 plantuml 矩形
architecture · infocardengines/html-css.md(规则、七种架构形状、页面骨架、连接线);布局集已恢复至 examples/system-architecture/ ,卡片原型则移至 examples/internal-documents/ 、catalogues-and-inventories/ 、customer-and-partner-comms/ ;90 文件设计库的其余部分已被筛除

没有兼容性占位目录:CLI 通过定位 SKILL.md 来发现技能,因此占位目录会被忽略而不会被安装——并且只会给仓库增加一个无用的目录。请重新安装以获取新包。

📖 包开发

检查


        node scripts/check-all.mjs                                           # 一次性运行所有主题检查
node scripts/validate-skills.mjs                                     # 布局、预算、目录、围栏、语言、主题可达性
node scripts/build-themes.mjs --check                                 # 主题文件与源表一致
node scripts/build-catalog.mjs --check                               # 目录 ↔ 文件系统一致性
node scripts/build-goals.mjs --check                                  # 目标文档与目录一致
node scripts/sync-engine-indexes.mjs --check                          # 随附模板索引与已安装引擎一致
node scripts/build-coverage.mjs --check                               # 覆盖台账与目录一致
node scripts/verify-examples.mjs --dir documd-visuals/examples --all  # 渲染每个示例
      

check-all.mjs 运行主题检查——漂移(build-themes.mjs --check)、对比度(check-palette-contrast.mjs,按主题)、块渲染(verify-blocks.mjs)、块覆盖(apply-block.mjs --all --check)、非主题字面量(check-palette-usage.mjs --strict)——以及 validate-skills.mjs,后者还强制要求 styles/palette.md 和每个 styles/themes/.md 从 SKILL.md、目标文档和引擎引用中保持可达;添加 --with-examples 可执行完整渲染。所有命令都必须以 0 退出。build-themes.mjs 从 scripts/themes.json 重新生成 documd-visuals/styles/themes/.md——请编辑 JSON,而不是生成的主题文件。build-catalog.mjs 和 build-goals.mjs 从 documd-visuals/catalog/scenarios.tsv 重新生成 documd-visuals/catalog/scenarios.{json,md} 和 documd-visuals/goals/*.md——请编辑 TSV,而不是生成的文件。

预算

文件预算
documd-visuals/SKILL.md300 行 / 12 KB 正文(frontmatter description:1024 个字符——Agent Skills 限制)
goals/*.md200 行
engines/*.md300 行(生成的 plantuml-stencils/ 除外)
examples/**/*.md目标 120 行,硬限制 200 行(冗长的 Vega 规范)
engines/coverage/*.md330 行(生成:精选单元表 + 按目标分组的每个示例)

添加示例

  • 按标准结构编写 documd-visuals/examples/<domain>/<scenario>.md:Best for / Avoid when / Answers → 围栏代码块 → Data Shape / Key Options / Pitfalls / Alternatives → 一行 <!-- source: … -->。
  • 向 catalog/scenarios.tsv 添加一行:domain <TAB> scenario <TAB> engine <TAB> file。
  • node scripts/build-catalog.mjs --apply && node scripts/build-goals.mjs。
  • node scripts/verify-examples.mjs --dir documd-visuals/examples --all。

代码围栏参考

引擎代码围栏输出
PlantUML (draw-uml)``plantuml / ``pumlSVG
Vega-Lite / Vega``vega-lite / ``vegaPNG
ECharts```echartsPNG
Infographic```infographicPNG
HTML/CSS(无围栏,原生 HTML)HTML

🔗 链接

  • Markdown Viewer Extension - 这些技能背后的渲染引擎
  • Agent Skills Format - AI agent 技能的标准格式
  • Chrome Extension - 在 Chrome 和 Chromium 浏览器中安装
  • Edge Extension - 从 Microsoft Edge 加载项安装
  • Firefox Add-on - 在 Firefox 中安装
  • Obsidian Plugin - 从 Obsidian 社区目录安装
  • VS Code Extension - 在 VS Code 中安装

🤝 贡献

请为单一包做贡献,而不是新增以引擎命名的技能:

  • 在 documd-visuals/catalog/scenarios.tsv 中找到你的示例所属的目标领域(或打开 SKILL.md 查看路由)。如果没有合适的领域,请提出一个——每个领域容纳 3–8 个场景。
  • 编写示例并在 TSV 中注册它(参见上文 Adding an example)。
  • 运行全部四道关卡;渲染失败或目录过期都会阻止变更。
  • 保持表述可溯源:每个示例都以 <!-- source: … --> 结尾,指向引擎文档。

📄 许可证

技能包(documd-visuals/)采用 CC-BY-4.0 许可——你可以使用、复制、改编和再分发它,包括商业用途,也包括其中的示例,但需署名。同样的文本以 documd-visuals/LICENSE.md 随包分发,因此已安装的副本自带其条款。该授权覆盖整个仓库,包括 scripts/ 中仅存在于仓库的工具以及 research/ 中的档案——这两个目录都不会随包分发,也不会作为技能被发现。

documd CLI 和渲染引擎是依据 GPL-3.0-only 单独授权的独立作品。@markdown-viewer/documd、@markdown-viewer/draw-uml 和 @markdown-viewer/drawio2svg 不属于本包,也不在上文 CC-BY-4.0 授权的覆盖范围内;安装该技能并不会为它们授予许可。

实践中的署名。CC-BY-4.0 要求你在分享该包时署名,且仅在那时要求。将其纳入你的项目并在旁边保留 LICENSE.md,或者在你的项目声明中写一行致谢——两者都满足要求。使用该技能撰写文档,以及在组织内部留存的文档,完全不需要任何署名。绝不要为每张图单独署名。完整细节:documd-visuals/LICENSE.md。

本包中通篇使用的第三方名称——PlantUML、AWS、Azure、Cisco、ArchiMate、ECharts、Vega、AntV 等——是各自所有者的商标,仅用于描述本包所记录的语法和图标集。不授予任何商标权利。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗