仓库文件导航
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 / puml | draw-uml 1.5.2 → drawio2svg | UML、ArchiMate、BPMN、流程、云/网络/安全架构、依赖图、9,514 个模具图标 |
| vega / vega-lite | vega 6.4.0 / vega-lite 6.4.3 | 需要数据变换、分面、统计的图表 |
| echarts | echarts 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 个以引擎和领域命名的技能。它们现在是一个包,其内容是重写的,而非复制的:
| 旧技能 | 新位置 |
|---|---|
| uml | engines/plantuml.md , engines/plantuml-stencils/ , examples/software-design/ , examples/software-behaviour/ |
| cloud · network · security · iot · data-analytics | examples/cloud-architecture/ , network-topology/ , security-and-compliance/ , data-platform/ |
| archimate · bpmn · mindmap | examples/enterprise-architecture/ , process-and-workflow/ , knowledge-and-outline/ |
| vega · graphviz · infographic | engines/vega.md , engines/infographic.md — graph 示例已改写为 plantuml 矩形 |
| architecture · infocard | engines/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.md | 300 行 / 12 KB 正文(frontmatter description:1024 个字符——Agent Skills 限制) |
| goals/*.md | 200 行 |
| engines/*.md | 300 行(生成的 plantuml-stencils/ 除外) |
| examples/**/*.md | 目标 120 行,硬限制 200 行(冗长的 Vega 规范) |
| engines/coverage/*.md | 330 行(生成:精选单元表 + 按目标分组的每个示例) |
添加示例
- 按标准结构编写 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 / ``puml | SVG |
| Vega-Lite / Vega | ``vega-lite / ``vega | PNG |
| ECharts | ```echarts | PNG |
| Infographic | ```infographic | PNG |
| 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 等——是各自所有者的商标,仅用于描述本包所记录的语法和图标集。不授予任何商标权利。