Agentic Mermaid 是一个与具体智能体无关的 Mermaid 图表工作流技能，核心是提供类型化的编辑界面，并配合结构化校验、类型化变更、往返序列化和图形化输出。
用途
该技能用于编写和编辑 Mermaid 图表。新图表可以直接以 Mermaid 源码编写，然后进行验证和渲染。已有建模图表可以解析为 ValidDiagram，使用类型化操作进行变更，进行结构化验证（而非主观视觉评分），再序列化回规范源码。
主要能力
- 输出 SVG、PNG、ASCII、Unicode 和 JSON 布局。
- 布局是确定性的，经过跨进程验证，不使用布局种子。
- 样式外观（style render option: name | spec | stack，例如 ['hand-drawn', 'dracula']）接受 ink seed，可重新生成抖动效果而不移动布局；详见 docs/style-authoring.md。
- 支持结构化验证，返回 ok / warnings / layout 等字段。
- 支持按图表族区分的类型化变更操作，操作使用 kind 字段作为判别器。
- 支持往返序列化，解析器不会静默丢弃任何内容。
- 对于未建模的构造，回退为不透明主体，仍可解析、渲染、验证并无损往返，但不提供结构化变更。
使用方式
选择使用通道：
- agentic-mermaid-mcp 已连接时使用 Code Mode（references/code-mode.md），可在一次往返中完成多步编辑。
- 可运行带导入的 JS/TS 时使用库（agentic-mermaid/agent），与 SDK 相同。
- 仅 Shell 时使用 CLI（references/cli.md）。
- 无本地安装、仅网络时使用托管 MCP：https://agentic-mermaid.dev/mcp（无状态 Streamable HTTP JSON-RPC；提供 execute、describe_sdk、render_svg、render_ascii、render_png、verify、describe、mutate 和 build 工具，输入上限 64 KB）。使用托管请求前请阅读 references/hosted-mcp.md。
托管 MCP 工具选择：
- 需要结构有效性、图表族、警告、布局计数时使用 verify，参数 { source }。
- 需要文字说明、AX 树或语义事实清单时使用 describe，参数 { source, format?: 'text' | 'json' | 'facts' }。
- 需要以已知操作编辑现有图表时使用 mutate，参数 { source, ops: [{ kind, ...fields }] }。
- 需要以已知操作编写新的建模图表时使用 build，参数 { family, ops: [{ kind, ...fields }] }。
- 需要发现某个图表族的精确操作字段时使用 describe_sdk，参数 { family, detail: 'fields' }。
- 需要自定义同步控制流时使用 execute，参数 { code, timeoutMs? }。
请求输出时使用 render_svg、render_ascii 或 render_png；不要将一次性渲染、验证、描述、变更或构建通过 execute 路由。
变更词汇表按图表族区分，不可互换。例如状态图使用 add_state 和 add_transition，不要复用仅适用于流程图的 add_node 或 add_edge。若不确定精确的族操作，应调用 describe_sdk，而不是从其他族借用操作名。状态图的 add_state 接受 id、可选 label、parent 和 region，没有 terminal 字段。类关联使用 { kind: 'add_relation', from, to, relKind: 'association' }，没有 add_relationship 操作或 relation 字段。
托管请求信封中的 tool 始终是上述裸托管名称之一，不要编造带提供者前缀的名称或特定图表工具名。
能力发现
在选择图表族或变更前，运行 am capabilities --json（或调用等效 SDK 能力 API）。其注册表派生的族条目暴露当前 narrower、操作 schema、编辑策略、输出支持和最小源码示例；生成的 Section A 矩阵提供显式的 native、source-preserved、diagnosed 和 absent 状态。本技能有意不维护第二份族或操作表。
在托管 MCP 上，检查已连接服务器的 tools/list 以了解工具面，并调用 describe_sdk({ family, detail: 'fields' }) 获取变更字段。托管端没有名为 capabilities 的工具。
选择图表族
根据读者的任务选择图表族；图表族是该决策的结果，而非起点。完整任务路由及各族反模式和验证码见 docs/choosing-a-diagram.md。常见路由：
- 步骤和决策走向结果：flowchart。系统响应事件在模式间移动：state。
- 参与者之间的有序消息：sequence。流程图箭头表示因果，而非时间。
- 带持续时间和依赖的日期工作：gantt。无日期时代：timeline。一个人对过程的有评分体验：journey。
- 必须跨阶段平衡的数量：sankey。某一时刻整体的部分：pie。跨类别或时间的测量序列：xychart。
可渲染性和编辑策略仍来自 am capabilities --json，而非此路由。
工作流
新图表：直接编写 Mermaid 源码，然后 parseRegisteredMermaid / verifyMermaid / render。
已有建模图表：
- parseRegisteredMermaid(source) → ValidDiagram。
- 在变更前使用族条目公布的 narrower（例如 asFlowchart(d) 或 asState(d)）。
- mutate(d, op)（按族类型化）。
- verifyMermaid(d) — 结构化警告；检查 ok / warnings / layout。
- 若 !ok，回退到上一个 ValidDiagram，尝试另一个操作。
- 仅在检查验证通过后 serializeMermaid(d)。
当存在类型化操作时，不要通过重新生成或拼接源码来编辑已有结构化图表。直接源码编写适用于新图表。变更操作使用判别器字段 kind（不是 type）。边删除使用 id，例如 { kind: 'remove_edge', id: 'API->DB' }；序列化前先验证。
对于 mutate 或 build，将返回信封视为提交边界：仅当顶层 ok 和 verify.ok 均为 true 时接受 source，并检查 verify.warnings。若操作失败，使用其 opIndex 和 error，调用 describe_sdk 并传 detail: 'fields'，然后仅用返回的 kind 和 fields 重试。不要猜测托管操作名或回退到源码拼接。
当用户询问哪些嵌入式验证字段必须通过时，准确命名响应路径：要求顶层 ok、确认顶层 family、要求 verify.ok、检查 verify.warnings。不要用转述替代这些字段路径。
在托管 mutate 请求中，source 是编辑前的精确输入；不要自行将请求的更改应用到该字符串。所有更改仅通过 ops 表达，不要包含 describe_sdk 未公布的便利字段。对于文件支持的输入，检查字节而非依赖终端显示：保留行尾以及文件是否有最终换行。若文件以 LF 结尾，JSON source 字符串在最后可见行后必须以 \n 结尾。不要修剪或规范化源码；在发出请求前将 JSON 解码后的 source 字节与附件比较。
若请求如“让它更好”没有具体质量目标，在变更前询问受众、输出媒介和预期改进。只读的 verify、describe 或 render 检查可以安全提供，但不要编造编辑目标。
适用场景
- 需要以结构化、可验证方式创建或修改 Mermaid 图表。
- 需要确定性布局和多种输出格式（SVG、PNG、ASCII、Unicode、JSON）。
- 需要通过 MCP、库或 CLI 在智能体工作流中集成图表编辑。
- 需要无损往返序列化，确保解析不丢失内容。
限制
- 变更词汇表按图表族区分，不可互换；不确定时应调用 describe_sdk。
- 未建模的构造回退为不透明主体，不提供结构化变更。
- 托管 MCP 输入上限 64 KB。
- 托管端没有 capabilities 工具。
- references/upstream/ 中的 Mermaid 语法仅作编写参考，可渲染族以 am capabilities --json 为准。
- 具体收费、价格、平台支持等事实暂未提供。