让你的AI Agent自动画文本图表:mdxcn SKILL.md安装与使用教程

原创2026-11-19 10:26:2919 阅读

让你的AI Agent自动画文本图表:mdxcn SKILL.md安装与使用教程

mdxcn 是一个免费开源的文本图表组件库,专为 MDX 打造的 callouts、steps、terminal、charts 和 timelines。只需把它的 SKILL.md 放进你的 AI Agent 技能目录,Cursor、Claude Code、Codex 等 Agent 就能在写文档时自动画出带边框的 ASCII 文本图表——时间线、流程图、甘特图、进度条,全部是纯文字,README 和 GitHub 里直接可读。本教程带你在 3 分钟内完成安装并上手使用。

mdxcn 文本图表项目封面

SKILL.md 是什么:让 Agent "会画图"的说明书

普通 AI Agent 写文档时,要么堆砌冗长列表,要么随手画一个歪歪扭扭的 SVG。mdxcn 的 SKILL.md 解决的就是这个问题:

  • 何时画图:Agent 会先判断"这句话是否值得一张图"。一句话能说清就不画;有路径、有时间线、有对比、有数据,才动手。
  • 画哪种图:内置一张"选择器"对照表(chooser),什么场景配哪个组件一目了然。
  • 用什么格式:在 MDX 里写 Markdown 子内容,在 Comark 应用里写 ::graph-* 块,在 Knap 模板里用 graph_* 过滤器,在 README/GitHub/Linear 里粘贴官方围栏 ASCII。

完整技能文件只有两个,都位于 skills/mdxcn/ 目录:

文件 作用
SKILL.md 核心规则:何时画图、选哪个组件、输出什么格式、禁止事项
recipes.md 带真实数据的完整示例(Refactor、Incident、PR 复盘等),Agent 照着抄

Agent 加载 SKILL.md 的方式是"描述匹配":当任务里提到"写一份 README、解释一次重构、复盘一次事故",或涉及 ASCII diagrams、GraphTimeline、Comark、Knap 等关键词时,技能自动生效。

mdxcn 文本图表组件库宣传图

一键安装步骤:把 SKILL.md 放进 Agent 的技能目录

仓库是只读的,安装只是"复制两个文件",不会修改仓库内容。

第 1 步:克隆仓库

git clone https://gitcode.com/gh_mirrors/md/mdxcn

第 2 步:复制到你的 Agent 技能目录

不同 Agent 读取的目录不同,项目内置的安装逻辑(见 lib/docs/skill.ts 与 skill-install.tsx)支持这 4 种:

Agent 项目级目录(随仓库提交,团队共享) 个人级目录(只在你机器上)
Cursor .cursor/skills/mdxcn ~/.cursor/skills/mdxcn
Claude Code .claude/skills/mdxcn ~/.claude/skills/mdxcn
Codex .agents/skills/mdxcn ~/.agents/skills/mdxcn
OpenCode .opencode/skills/mdxcn ~/.config/opencode/skills/mdxcn

以 Cursor 项目级安装为例:

mkdir -p .cursor/skills
cp -R mdxcn/skills/mdxcn .cursor/skills/mdxcn

💡 团队项目推荐项目级安装:提交进仓库后,每位成员的 Agent 都会自动带上这套画图技能。

第 3 步(可选):让图表在你的 React 站点里渲染

SKILL.md 本身不含图表组件。如果你的站点运行 React/MDX,还需要用 shadcn CLI 把组件源码拷进项目(组件落地在 @/registry/default):

pnpm dlx shadcn@latest add https://mdxcn.dev/r/all.json

只装单个组件时,把 all 换成 slug(如 graph-table)。纯 README / 纯 Markdown 场景不需要这一步——Agent 直接输出官方围栏 ASCII。

使用教程:一句话 Prompt 让 Agent 自动配图

安装完成后,正常给 Agent 派活即可,记得点一句"用 mdxcn"。以下是官方示例(来源 lib/docs/skill.ts)中最好用的几条:

场景 1:写重构方案(Flow + Timeline 组合)

We're moving session checks out of route handlers into middleware.
Write a short plan for the team.
Use mdxcn for the before/after request path and the week-by-week
rollout. Prose between the two figures. Don't draw SVG.

场景 2:事故复盘(Timeline + Uptime 组合)

Draft a tight postmortem: p95 crossed 800ms at 14:02, we rolled back
the cache flag at 14:11.
Use mdxcn: a timeline of the night, then the days users felt it.
No SVG.

场景 3:给 README 加发布章节(纯 ASCII,无需 React)

Add a launch section to the README. It's a .md file, no React.
Use mdxcn: a punch list plus a grouped table. Paste the official
fenced ASCII. Don't paste JSX.

Agent 的输出长这样——先 1-3 句结论,再一张图,中间是文字:

+---------------- [ NIGHT ] ----------------+
|                                           |
| ●  14:02  p95 crossed 800ms               |
| │                                         |
| ●  14:11  rolled back the cache flag      |
| │                                         |
| ○  14:40  write the postmortem            |
|                                           |
+-------------------------------------------+

这就是 mdxcn 最妙的地方:图还是文件里的纯文本。Agent 下次改文档时,可以直接读出标签和数值来编辑,而不是对着截图猜。

图表选择速查:Agent 内置的 Chooser 对照表

SKILL.md 里最值钱的就是这张"什么内容配什么图"的对照表(节选自 SKILL.md 的 Chooser 部分):

你要写的内容 Agent 会选的图表
请求路径 / 重构前后 GraphFlow + GraphTimeline
事故复盘 / 事后报告 GraphTimeline + GraphUptime
A vs B 选型对比 GraphCompare(+ 体积相关时加 GraphRank)
PR 改了什么 GraphDiff + GraphSlope
本周并行任务 GraphGantt + GraphStat
迁移进度 GraphMeter + GraphKpi
决策记录 / ADR Decision + GraphScore
嵌套文件 / 组织结构 GraphTree
操作步骤 Steps
注意事项 / 警告 Callout

数据型场景也有对照:少量数字用 GraphSpark,需要 y 轴用 GraphPlot,0 到 1 的进度用 GraphMeter,实际值 vs 目标值用 GraphBullet,占比用 GraphStack(注意:规则里明确禁止饼图)。

⚠️ GitHub / README / Linear 这类不能跑 React 的地方,Agent 只会粘贴有围栏 ASCII 版本的图表;Flow、Plot、Heatmap、Timer 等没有纯文本版的会被自动跳过。

使用规则:4 条铁律保证输出质量

SKILL.md 的"Rules / Do not"部分(SKILL.md)把质量控制写进了技能本身:

  1. 每节最多 2 张图,图与图之间必须有文字,绝不堆"图墙"。
  2. 禁止自造图表:不画 SVG、Mermaid、Recharts、canvas,也不手写 ASCII——只能复制官方围栏图再改标签。
  3. 标题 1-2 个词、大写(渲染为 [ TITLE ]),标签用小写朴素名词(auth middleware 而非 AuthMiddleware Layer)。
  4. 不改边框样式:边框风格通过 frame="corners" | "rule" | "none" 属性切换,不额外加边框或圆角卡片。

相关文件导读:深入 mdxcn 的技能体系

路径 说明
skills/mdxcn/SKILL.md Agent 加载的核心技能文件(选择器 + 规则 + 示例 Prompt)
skills/mdxcn/recipes.md 带真实数据的完整写作配方(JSX 版)
lib/docs/skill.ts 支持的 Agent 列表、选择器数据、官方 Prompt 文案
app/skill.md/route.ts 站点路由:把 SKILL.md 原文作为 Markdown 响应输出
app/llms.txt/route.ts 站点路由:输出选择器 + 所有格式的图表指南
app/agents/page.tsx "for agents" 页面:Agent 写图、读图的完整故事

总结

mdxcn SKILL.md 的安装成本只有两条命令:clone + cp。换来的是 AI Agent 写作能力的显著升级——重构方案自带前后路径图,事故复盘自带时间线和可用性面板,README 里直接嵌入官方围栏 ASCII。图是纯文本,Agent 下次还能读出来改标签。

如果你常用 Cursor 或 Claude Code 写项目文档,这套"免费、开源、Agent 原生"的文本图表技能,值得今天就装进技能目录。

登录后查看全文
mdxcn