用途:生成 Mermaid 流程图,展示代码库中高层组件关系,适合可视化插件/模块关系、入职理解系统结构、为 PR 评审记录架构,以及回答“系统如何组合”。不适用于导入级耦合(用 cartograph:dependency-graph)或运行时调用路径(用 cartograph:call-chain)。
工作流:第一步,派发代码库探索代理分析范围,Agent(cartograph:codebase-explorer),提示探索 [scope] 并返回结构模型,聚焦包、模块及其关系;未提供范围则用项目根目录。第二步,将结构模型转为 Mermaid 流程图:层级系统用 flowchart TD,流水线/流程系统用 flowchart LR;按包将相关模块分组为 subgraph;关系边使用描述性标签;节点最多 15-20 个(聚合小模块);用形状区分组件类型:[Rectangle] 模块/包,([Stadium]) 入口点/命令,[(Database)] 数据存储,{Diamond} 决策点。第三步,通过 MCP 渲染:调用 mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram,传入 prompt、mermaidCode、diagramType 为 flowchart、clientName 为 claude-code;渲染失败则根据错误修复语法并重试,最多 2 次。第四步,向用户展示渲染图,并用 2-3 句话简述其内容。
退出标准:生成的 Mermaid 流程图语法至少包含一个分组相关模块的 subgraph;MCP 渲染调用无错误返回(或首次失败后重试并报告结果);节点数在 3 到 20 之间;渲染输出旁附 2-3 句描述;若 MCP 重试 2 次后仍失败,仍以代码块展示 Mermaid 语法并暴露错误。