Agentic Mermaid

为什么选择 Agentic Mermaid

如果你想用通俗语言描述图表，并直接得到无需再进行设计润色即可发布的成品，就可以使用它。

你的需求	Agentic Mermaid 提供
让 Agent 起草图表	Mermaid 源码和经过验证的渲染路径
精美的默认样式	内置 watercolor、blueprint、hand-drawn 和 publication-figure 等外观
符合品牌风格	Style + Palette 叠加组合，以及可保存在代码仓库中的自定义 JSON 调色板
之后安全地编辑	parseRegisteredMermaid → 家族专用窄化器 → mutate → verifyMermaid → serializeMermaid
便于审核的产物	由同一份源码生成的 SVG、PNG、ASCII、Unicode 和 JSON 布局

Agent 工作流是保证图表精致的防护措施：如果有结构化编辑方式，Agent 就不应根据像素猜测、拼接字符串或重新生成整张图表。

亮点

• 通过描述符注册的图表家族 — 内置图表和带命名空间的扩展共用一套发现机制和能力契约。
• SVG、PNG、ASCII、Unicode、JSON — 单次解析请求即可获得明确的图形、终端和定位布局投影。
• 同步、零 DOM 的 SVG 渲染器 — 无需 Puppeteer，也不会出现浏览器闪屏。
• 可组合样式 — { style: ['hand-drawn', 'dracula'] } 可将外观叠加到调色板上；可发现的完整外观涵盖草图、水彩、蓝图、无障碍、印刷、运维、实体媒介、架构和编辑／报告等场景。自定义样式是任何 Agent 都能编写的纯 JSON 记录（docs/style-authoring.md）。seed 会重新生成墨迹效果，不会改变布局。
• 可发现的调色板 + Shiki 兼容性 — 主题就是仅包含调色板的样式：可在运行时发现规范目录、根据两种颜色生成主题，或转换 VS Code 主题。
• 面向 Agent 的编辑 — 为每个已注册的可渲染图表家族提供带类型的变更操作；仅对包含未建模语法的不透明回退内容进行源码级往返处理。
• CLI + MCP + 库 — am、agentic-mermaid-mcp、agentic-mermaid、agentic-mermaid/agent，以及适用于浏览器／workerd 的 agentic-mermaid/agent/core。审计报告和可信的主机资源助手仍属于仓库工具，不作为已发布的运行时入口。

安装

npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
npx --no-install agentic-mermaid --help
npx --no-install agentic-mermaid mcp

开发此仓库时，请从源代码安装并运行 Bun 入口点 （需要 Bun 1.4.0 或更高版本；如果 bun --version 显示的版本较旧，请运行 bun upgrade）：

git clone https://github.com/adewale/agentic-mermaid
cd agentic-mermaid
bun install
bun run build
bun run bin/am.ts --help
bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server

仅支持 ESM。 agentic-mermaid 提供 ES 模块（没有 CommonJS 构建版本）； 使用 require() 的用户应改用动态 import()。需要 Node ≥ 22。

以下 am … 示例使用的是已发布的二进制文件。在项目本地通过 npm 安装后，请在 shell 中运行 npx --no-install agentic-mermaid …（或 在 npm 脚本中运行 am …）。从源代码检出目录运行时，请改用 bun run bin/am.ts …。

输出快速入门

如果你希望通过一个导入路径使用带样式的渲染、输出格式和结构化编辑 API，请使用 agentic-mermaid/agent。

SVG

import { renderMermaidSVG } from 'agentic-mermaid/agent'

const svg = renderMermaidSVG(`flowchart TD
  Start --> Done`, { security: 'strict' })

PNG

import { writeFileSync } from 'node:fs'
import { renderMermaidPNG } from 'agentic-mermaid/agent'

const png = renderMermaidPNG(`flowchart TD
  Start --> Done`, {
  fitTo: { width: 1200 },
  background: '#fff',
})

writeFileSync('diagram.png', png)

CLI 等效命令：

am render diagram.mmd --format png --output diagram.png

ASCII / Unicode

import { renderMermaidASCII } from 'agentic-mermaid/agent'

const unicode = renderMermaidASCII(`flowchart LR
  A --> B`)
const ascii = renderMermaidASCII(`flowchart LR
  A --> B`, { useAscii: true })

Agent 快速入门

如果你的编码 Agent 能读取仓库文件，请让它参考：

• skills/agentic-mermaid-diagram-workflow/SKILL.md，用于编写和编辑图表。
• skills/agentic-mermaid-live-editor/SKILL.md，用于编辑器修改。

如果它只能访问 shell：

am --agent-instructions
am capabilities --json
am preview diagram.mmd --security strict --open
am mutate diagram.mmd --op '{"kind":"add_node","id":"Cache","label":"Cache"}' --json

为编码 Agent 提供的零安装提示词：读取 https://agentic-mermaid.dev/llms.txt，并遵循解析 → 缩小范围 → 修改 → 验证 → 序列化的工作流。若要将 Agentic Mermaid 接入其他仓库，请运行 npx agentic-mermaid init-agent（从源代码检出目录运行时则运行 bun run bin/am.ts init-agent）；它会添加不会覆盖现有内容的 AGENTS.md 章节、根目录下的 skills/ 套件，以及 .mcp.json 示例。

使用严格的 preview 供人工检查，并使用 mutate --op/--ops 执行经验证的单次或批量编辑。

对于多步骤 MCP 编辑，请连接 agentic-mermaid-mcp，并使用 Code Mode execute(code) 及相同的 mermaid.* SDK 名称。默认传输方式为 Stdio；agentic-mermaid-mcp --transport http 会启动 HTTP/SSE，并提供受管理的 PNG 文件/URL 产物。可查看Agent API 使用指南，了解可直接复制粘贴的库、CLI 和 MCP 示例。

MCP 服务

Agentic Mermaid 提供 Model Context Protocol 服务，让支持 MCP 的 Agent 无需调用 shell 命令即可渲染和安全地编辑图表。

• 可自托管（默认）。 agentic-mermaid-mcp 会运行一个 Stdio 服务，提供 execute（Code Mode 沙箱）、describe_sdk（按需查看某个系列的变更架构）、render_png、describe、mutate 和 build。优先使用声明式编辑；自定义逻辑则使用 execute。可通过包运行器执行 npx -y agentic-mermaid mcp；参数 mcp 会将包名二进制文件路由到同一个 Stdio 服务。添加 --transport http 可启用 HTTP/SSE，并提供受管理的 PNG 文件/URL 产物。请参阅 docs/mcp-http-transport.md 和 docs/mcp-code-mode-rationale.md。
• 托管服务。 可通过 https://agentic-mermaid.dev/mcp 访问无状态 Streamable HTTP 端点（工具：execute、describe_sdk、render_svg、render_ascii、render_png、verify、describe、mutate 和 build；输入上限为 64 KB）。编写不熟悉的操作前，可调用 describe_sdk 获取简明签名或精确字段。该端点仅支持 MCP JSON-RPC，并非 REST 渲染 API。托管版 execute 会在无网络连接的 Cloudflare Dynamic Worker 隔离环境中运行相同的 mermaid.* 外观层；托管版 PNG 仅返回 base64。

默认采用本地优先的方式：对于敏感内容、离线使用、超出托管服务上限的内容，或需要本地 PNG 文件/URL 产物的场景，请优先使用库、CLI 或自托管 MCP。托管端点是一个公开、无需身份验证的便捷选项，适用于零安装渲染、验证、查看描述和有界结构化编辑。

目录维护者可使用规范的 MCP 目录条目。托管服务的数据处理方式请参阅 MCP 隐私声明。

结构化编辑示例

import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'

const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
if (!parsed.ok) throw new Error('parse failed')

const flow = asFlowchart(parsed.value)
if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)

const next = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
if (!next.ok) throw new Error(next.error.message)

const verify = verifyMermaid(next.value)
if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))

const source = serializeMermaid(next.value)

规则：

• 修改现有结构化图表前，使用匹配的 as<Family> 窄化器。
• 修改操作使用 kind，而非 type。
• 每个提交点之前都运行 verifyMermaid。
• 不要对不透明的回退正文调用 mutate；对于未建模的语法，窄化器会返回 null。

支持的图表系列

系列支持情况根据 FamilyDescriptor 注册表生成；运行 am capabilities --json 查看实时列表。（不再发布 Section A 能力报告。）语法示例和 兼容性说明请参阅图表系列。

更多文档

• 系统架构 — 从这里开始，了解渲染后的已解析请求、系列描述符、已定位制品和输出安全概览（经过自用验证，可防止偏离）。
• API 参考 — 渲染器、Agent API、选项、CLI/MCP 相关说明。
• 词汇表 — 系列、源对象、Scene 部件、已解析基元和类型化系列窄化。
• Agent API 实用指南 — 面向 Agent 的实用示例。
• 主题 — 双颜色主题、内置主题、Shiki 兼容性。
• 自定义样式实用指南 — JSON 样式文件、截图、模式用法和 CLI 命令。
• 自定义样式中的字体 — 字体选择、SVG 声明、PNG 目录、回退方案和浏览器用法。
• React 集成 — 适用于浏览器、按系列加载的渲染。
• ASCII 输出 — 终端输出、颜色模式、XY 图表。
• Mermaid 配置 — frontmatter、init 指令、运行时配置。
• 功能、质量、安全、分支差异。
• 贡献者请参阅添加图表类型。

在线编辑器和示例

• 示例 — 支持的系列、Style + Palette 组合，以及丰富的共享示例集。
• 在线编辑器 — SVG/PNG 导出和 URL 分享。
• examples/agent-loop.ts
• examples/mcp-vs-cli-complex-diagrams.ts
• examples/agent-improve-auth-flow.ts

致谢

Agentic Mermaid 是由 Luki Labs 开发的 Beautiful Mermaid 的一个分支。ASCII 渲染引擎基于 Alexander Grooff 开发的 mermaid-ascii，并针对 Agentic Mermaid 进行了扩展。

许可证

MIT

Native Event Modeling 和 ZenUML 的创作与渲染已记录在能力和运行时契约中。