用途
markdown-graphs 是一套用于在 Markdown 与文档中嵌入图表的方案，目标是“在文字旁放置图形”。它的核心约束是：先确定宿主环境，再决定粘贴什么格式。图形统一呈现为虚线边框、四角加号、顶部 [ TITLE ] 标题的样式。
主要能力
资料列出了多种图形组件，可按用途选择，例如：路径或重构用 GraphFlow、GraphTimeline；事故复盘用 GraphTimeline、GraphUptime；方案对比用 GraphCompare、GraphRank；PR 变更用 GraphDiff、GraphSlope；本周重叠工作用 GraphGantt、GraphStat；迁移进度用 GraphMeter、GraphKpi；嵌套文件或组织结构用 GraphTree；RFC 或发布清单用 GraphSheet、GraphCheck。数据形态方面：少量数字无坐标轴用 GraphSpark；需要 y 轴的序列用 GraphPlot；0 到 1 的单值填充用 GraphMeter；实际值与目标用 GraphBullet；整体构成用 GraphStack（Waffle 可展示约 100 个单元格）；短排名列表用 GraphRank；小方格网格用 GraphCells；两个小直方图用 GraphBars；单个标题加趋势用 GraphKpi；两到四个无趋势数字用 GraphStat；前后对比用 GraphSlope；计时或距今时长用 GraphTimer；倒计时用 GraphCountdown；每日状态用 GraphUptime；跨月每日计数用 GraphActivity；单月少数标记用 GraphCalendar；带标签的强度网格用 GraphHeatmap；双轴精确数字用 GraphMatrix；累计用 GraphWaterfall；逐步递减用 GraphFunnel；数字行用 GraphTable；分组表格用 GraphSheet；打勾清单用 GraphCheck；发票类用 GraphInvoice；标签值表用 GraphSpec。另有 GraphFrame 仅在组装自定义图形时使用。
使用方式
资料给出的宿主与粘贴格式对应关系如下：React 或可从 @/registry/default 导入的 MDX 使用 JSX，来源为 recipes.md 与文档示例；Comark 应用（普通 .md 由应用渲染）用 ::graph-* 加 YAML，来源为 llms.txt 的 Comark 部分或文档页 Comark 标签；Knap 模板（数据转 Markdown）用 graph_* 过滤器，来源为 llms.txt 的 Knap 部分或文档页 Knap 标签；README、GitHub、Linear、Slack、PR 评论用带围栏的 ASCII，来源为 llms.txt 的 MDX 部分或文档页 MDX 标签。源码通过 shadcn 复制，不是 npm 安装，导入落在 @/registry/default 下。若缺少 registry/default/graph-frame 且宿主为 React、Comark 或 Knap，可执行：pnpm dlx shadcn@latest add https://mdx-graphs.kshv.me/r/all.json。需要动效时，单个组件用其 slug 替换 all（如 graph-flow 等）；Comark 适配器为 graph-comark（已在 all.json 中），Knap 过滤器为 graph-knap（已在 all.json 中），另需 pnpm add knap。导入写法为命名导出与文件夹同名，例如 import { GraphFlow } from "@/registry/default/graph-flow/graph-flow"，不提供 barrel。Comark 接线需将 graphComponents 传入 Comark 的 components prop；Knap 接线需用 createEngine 合并 standardFilters 与 graphFilters；Knap CLI 不会加载这些过滤器。仅复制部分图形时，可用 createGraphComponents 与 createGraphFilters 按需注册。
适用场景
适用于在技术写作、事故复盘、PR 评论、RFC、README 等场景中插入少量图形。资料建议每节最多两个图形，中间要有文字，不做图库；标题 1–2 个词、大写、无标点，渲染为 [ TITLE ]；标签用小写朴素写法。默认调色板为单一强调色 --graph-accent，仅当需要第二或第三序列时才用 palette="duo" 或 "multi"。未使用的行淡化（约 0.4 透明度），数字使用 tabular-nums 并右对齐。动效已内置于组件（transform 与 opacity，约 220ms），不要添加循环、脉冲或 CSS 动画。
限制
资料明确禁止：绘制 SVG、Mermaid、Recharts 或 canvas；自创 ASCII 艺术，必须从 llms.txt 或 MDX 标签复制官方围栏；将 JSX 粘贴到 README、GitHub、Linear 或任何无法导入组件的文件；将 ::graph-* 粘贴到 GitHub、Linear 或 README，这些宿主只能使用带围栏的 ASCII；修改边框样式（不加额外边框、不加圆角卡片、不加新的角标）；在一个回复中堆砌所有图形；使用饼图（应使用 Stack 或 Waffle）；在 Table、Sheet、Invoice、Spec、Stat、Tree 或 Frame 上传入 palette。此外，部分图形（Flow、Plot、Activity、Heatmap、Calendar、Timer、Countdown、Frame）没有带围栏的 ASCII，在 GitHub 上应选择有 ASCII 的图形或跳过；在 Comark 上除 Frame 外仍可用；在 Knap 上除 Frame 外会输出 ::graph-* YAML。若不确定属性，可获取 https://mdx-graphs.kshv.me/llms.txt。其余如具体收费、价格、平台支持范围等，资料暂未提供。