documd-visuals

documd 可视化

为本文档流水线可渲染的每个图表、卡片和版式进行路由。

图表即文本，直接写在原处。 Markdown 中的围栏（plantuml · vega · echarts · infographic）或裸 HTML 本身就是图表：查看器会即时绘制，代码块仍可编辑，无需预先渲染、构建或导出。documd 是可选的——仅用于导出和验证。

铁律

1. 允许的围栏——plantuml / puml · vega · vega-lite · echarts · infographic， 以及裸 HTML——系统架构图、卡片和页面版式均通过它绘制。
2. 列表以外的内容一律不允许。 列表未列出的围栏就是错误，而不是次优选项—— 不存在第二梯队的引擎。
3. 每个围栏只放一个图表。 不要在一个代码块中放入两个引擎，也不要嵌套围栏。
4. HTML 必须裸写，绝不能使用 ```html——围栏代码块会变成图像。应从真实文件入手， 而不是凭空创建：系统架构图参考 layered-with-wings.md，卡片参考 executive-brief-summary.md。
5. 数据内嵌。 vega / vega-lite / echarts 必须包含自己的 values / series 数据； 在导出流程中，外部 URL 并不可靠。
6. 在正文中说明图表要表达的内容。 每个图表都要回答一个问题——将问题写在正文或代码块的 title 中。
7. 先选主题，再从中取色。 颜色必须来自 styles/palette.md 中列出的某个主题；复制该主题中适用于相应引擎的代码块，并从中选取所有 值——手动挑选十六进制颜色，或在一个图表中混用两个主题，都是错误的。图表按顺序使用 分类色阶；卡片使用一种强调色搭配中性色。

按目标选择

找到读者的目标，打开对应的目标指南，再选择示例。引擎仅供参考；目标指南和 示例才是权威依据。

A — 数据与指标

目标	触发关键词	引擎	阅读
service-reliability	延迟 · p95/p99 · SLO · SLA · 错误预算 · 消耗速率 · 可用性 · 正常运行时间 · 可靠性	echarts vega infographic	goals/service-reliability.md
ops-monitoring	事故负载 · 告警量 · 异常值 · 异常 · 服务计分卡 · 支持请求量	echarts vega infographic	goals/ops-monitoring.md
delivery-throughput	吞吐量 · 周期时间 · 前置时间 · 速度 · 容量 · 人员配置 · 待办事项 · WIP · 排名变化	echarts vega infographic	goals/delivery-throughput.md
goal-and-status-reporting	OKR · KPI · 目标与实际 · 目标达成情况 · 状态看板 · 仪表板 · 计分卡	echarts vega infographic html-css	goals/goal-and-status-reporting.md
product-metrics	转化 · 漏斗 · 采用率 · 留存率 · 流失率 · 激活 · 注册 · 群组 · 实验	echarts infographic	goals/product-metrics.md
business-reporting	季度业绩 · 收入 · ARR · 收入构成 · 利润率 · 定期业绩 · 预测	infographic vega echarts	goals/business-reporting.md
go-to-market	销售管道 · 渠道 · 合作伙伴 · 合作伙伴等级 · 市场进入 · 销售漏斗 · SWOT · 营销活动	echarts infographic	goals/go-to-market.md
cost-and-budget	成本 · 支出 · 预算 · 云账单 · 节省 · 降本 · 资本支出 · 单位经济效益	echarts infographic vega	goals/cost-and-budget.md
data-exploration	相关性 · 分布 · 回归 · 异常值检测 · 缺失数据 · 小多图 · 密度	vega echarts	goals/data-exploration.md

B — 流程与系统

目标	触发关键词	引擎	阅读
engineering-operations	站会 · 冲刺仪式 · 团队节奏 · 值班 · 覆盖范围 · 轮班交接 · 部署节奏 · 检查清单	infographic vega echarts	goals/engineering-operations.md
incident-management	事件 · 事后复盘 · 升级处理 · 分诊 · 运维手册 · 变更请求 · 发布就绪 · 评审	infographic echarts html-css	goals/incident-management.md
process-and-workflow	审批 · 工作流 · 泳道图 · SOP · 流程图 · BPMN · 关卡 · 采购	plantuml infographic	goals/process-and-workflow.md
software-design	类 · 领域模型 · 组件 · 包 · 分层 · 用例 · 对象 · C4 容器 · SysML	plantuml	goals/software-design.md
software-behaviour	状态机 · 生命周期 · 序列 · 交互 · 消息传递 · 事件流 · EIP · 部署	plantuml	goals/software-behaviour.md
dependencies-and-relations	依赖 · 调用图 · 影响分析 · 耦合 · 归属 · 因果关系 · 鱼骨图	plantuml vega echarts infographic	goals/dependencies-and-relations.md
system-architecture	系统架构 · 分层堆栈 · 区域 · 流水线阶段 · 服务目录 · 请求路径 · 连接器	html-css	goals/system-architecture.md

C — 基础设施与治理

目标	触发关键词	引擎	阅读
cloud-architecture	AWS · Azure · Kubernetes · 容器 · 无服务器 · IoT · 边缘 · VPC · 可观测性	plantuml infographic	goals/cloud-architecture.md
data-platform	ETL · 湖仓一体 · 数据仓库 · CDC · 流式处理 · 数据摄取 · 目录 · ML 流水线 · ER 模型	plantuml	goals/data-platform.md
network-topology	网络 · 拓扑 · DMZ · 无线 · 防火墙 · 交换机 · 数据包 · 路由 · 流量	plantuml echarts	goals/network-topology.md
security-and-compliance	零信任 · IAM · 加密 · 威胁模型 · 信任边界 · 控制措施 · 证据 · 审计 · 合规 · 风险	plantuml infographic html-css	goals/security-and-compliance.md
enterprise-architecture	ArchiMate · 能力地图 · 价值流 · 利益相关者地图 · 业务架构	plantuml infographic	goals/enterprise-architecture.md
organization-and-roles	组织架构图 · 汇报关系 · 员工队伍 · 能力覆盖 · 能力成熟度 · 交接 · 职责	infographic vega echarts html-css	goals/organization-and-roles.md
people-and-hiring	招聘 · 人员编制计划 · 面试流程 · 入职引导 · 职业阶梯 · 认证 · 职业发展	infographic	goals/people-and-hiring.md

D — 知识与表达

目标	触发关键词	引擎	阅读
knowledge-and-outline	思维导图 · 大纲 · 知识图谱 · 概念图 · 主题 · 词云	plantuml infographic vega echarts	goals/knowledge-and-outline.md
planning-and-roadmap	路线图 · 里程碑 · 时间线 · 甘特图 · 季度计划 · 发布计划 · 战略重点	infographic vega plantuml html-css	goals/planning-and-roadmap.md
migration-and-rollout	迁移 · 切换 · 分阶段推出 · 分阶段交付 · 计划 · 工作分解	plantuml infographic	goals/migration-and-rollout.md
comparison-and-selection	比较 · 对比 · 自建还是采购 · 决策记录 · 象限图 · 供应商选择 · 权衡 · 优先级	infographic html-css	goals/comparison-and-selection.md
internal-documents	备忘录 · 简报 · 章程 · 摘要 · 政策 · 引言 · 原则	html-css infographic	goals/internal-documents.md
catalogues-and-inventories	目录 · 清单 · 权益 · 服务项目 · 标准工具 · 支持等级	infographic	goals/catalogues-and-inventories.md
customer-and-partner-comms	客户故事 · 案例研究 · 销售简报 · 公告 · 通知 · 合作伙伴简报 · 教育模块	html-css	goals/customer-and-partner-comms.md
theme-and-tone	打印 · 复印 · 讲义 · 低视力 · 大字版 · 色盲 · 幻灯片 · 投影 · 长篇内容	infographic echarts plantuml	goals/theme-and-tone.md

引擎速查表

引擎	适用场景	不适用场景
plantuml	UML/ArchiMate/BPMN 语义、品牌和设备图标（9,514 个模板），或需要自动布局的关系图	图表
vega / vega-lite	需要先处理数据——连接、窗口、折叠、回归、密度、分面、小多图	需要大量样式设计的精致图表（echarts）
echarts	报告级图表或 KPI 仪表板：坐标轴、系列、阈值、注释、仪表盘	必须先转换数据
infographic	设计感强的版面：路线图、时间线、清单、比较、象限图、知识图谱	坐标轴、多个系列或统计形状（echarts）
HTML/CSS	卡片、备忘录、概览、页面级布局	其他引擎已能渲染该图表

详情、限制和注意事项：plantuml · echarts · vega · infographic · html-css。

功能边界

以下无法实现；请改用备用方案，不要反复尝试。

需求	备用方案
3D / 地球仪 / WebGL 图表（没有 echarts-gl）	2D echarts；用 scatter/graph 表现形状
地理地图（没有随附地图数据，也无法离线使用 GeoJSON）	示意矩形布局，或 HTML/CSS 区域图
ECharts 中的 dataset.transform（在 6.1.0 中会抛出 RangeError）	先在上游排序并派生数据，再使用 dataset.source
echarts 选项中的函数（会被解析为 JSON）	模板字符串（"{c}%"）、逐项标签对象
外部数据或图像（data.url、远程 URL）	内联 values、数据 URL
PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / math（可解析，但无法绘制有用内容）	@startmindmap、带框矩形树、HTML/CSS 样稿或代码围栏
交互式图表（工具提示、缩放、刷选）	直接添加标注：标签、阈值、引线注释
vega / echarts 中的图标	plantuml 模板
infographic 中的自由定位	使用 HTML/CSS 控制像素级布局

阅读文档

要在浏览器或 VS Code 中阅读文档，请安装 docu.md Markdown Viewer： https://docu.md。

导出与验证 — 可选

编写内容不需要这些操作。documd CLI 可将文档或图表源文件转换为文件、提取图表作为图片，并验证代码块是否能正确渲染——适用于输出为文件的情况。无需安装：npx @markdown-viewer/documd in.md out.docx。标志、格式和 npm 作用域警告： converting.md。

代码块无法渲染时

1. 是否使用了允许列表中的代码围栏？每个图表是否恰好对应一个代码块？
2. 是否属于该引擎参考文档中的反模式（参见 引擎速查表）——或者是否存在严格语法要求（echarts/vega 使用 JSON，裸 HTML 中不能有空行）？
3. 然后切换到目标指南中列出的替代引擎；大多数场景都有两个选项。
4. 或通过渲染进行验证：npx @markdown-viewer/documd file.md --assets /tmp/figs。

内容索引

catalog/scenarios.md 按领域、引擎、等级和示例路径索引所有场景——从这里开始；然后查看 goals/<domain>.md、engines/<engine>.md、examples/<domain>/<file>.md。