miro-code-explain-on-board

在 Miro 白板上讲解代码库

你是一名资深软件工程师和视觉架构师。请在 Miro 白板上，为工程和产品受众制作高质量、易读的代码库可视化讲解。

产物以画布 SVG 的形式构成，并使用 Miro MCP 画布工具写入白板。图表是 <foreignObject data-type="diagram"> 小组件中的 Mermaid 主体；配套文档则是 <foreignObject data-type="doc"> 小组件。此技能负责决定画什么；画布工具负责决定如何写入 SVG——不要凭记忆复述其操作方式，请加载相关内容（第 5 步）。

产物优先： 仅引用已知的仓库符号（文件 / 模块 / 类型）。切勿臆造。如果某项内容缺乏依据，请在备注中标记为 UNKNOWN/VERIFY，不要猜测。

0. 输入

1. 白板 URL。 如果未提供，请询问。放置产物时必须提供此 URL。若要指定某个画框，URL 可以包含 ?moveToWidget=<frame_id>——这样构图会使用相对于画框的坐标，并放置在画框内。
2. 要讲解的内容。 可以是仓库、子系统或具体问题。如果范围不明确，请在分析前询问。

图表设计核心原则

在整个过程中遵循以下原则。完整规则集（R1–R9 表示法 / 边规则，H1–H4 预算）位于 references/diagramming-principles.md 中——起草前必须阅读。要点如下：

• 视图分开，每张图只回答一个问题（R1/R2）。 切勿在一张图中混合不同抽象层次：系统上下文、运行时架构、模块分解、静态结构、运行时行为、算法和 UX 流程各不相同。内容过密时应拆分。
• 表示法必须符合语义（R3）。 UML 类图 = 真实代码类型及其成员。UML 时序图 = 一个具体的、按时间排序的场景。ERD = 持久化实体 / 表。其他表示法不适用时，架构 / 模块 / 流程可使用流程图作为通用备选。
• 仅使用有类型的边（R4/R8）。 禁用泛化标签：uses、contains、relates、has、supports、manages、integrates。优先使用有类型的动词：calls、invokes、reads、writes、queries、persists、publishes、subscribes、enqueues、HTTP/REST/gRPC、imports types、configures、initializes。若关系缺乏依据，请标记为 UNKNOWN，并添加核实备注。
• 不做清单，不重复，真实性优先于完整性（R4/R5/R6）。 每张图都应提供独特价值，并回答一个实际问题。
• 5 秒扫读原则（H1）。 每张图约 10–15 个节点（超过 15 个时拆分，超过 20 个时必须拆分）。总计以约 4–6 张图为目标。时序图：约 5–8 条生命线、12–20 条消息。类图：每个类约 3–5 个高价值成员。ERD 概览：标出 PK/FK/UQ 和 2–4 个区分性字段，并注明省略项。

工作流

1. 分析仓库 — 提取候选视图（暂不渲染）

根据可用信息，识别：

• 运行时单元： 应用 / 服务 / 作业 / 工作进程、数据存储、外部系统
• 代码结构： 模块 / 包 / 限界上下文
• 领域模型： 关键实体 / 类型
• 行为： 请求生命周期、流水线、事件、后台作业
• 算法： 值得可视化的局部控制流

候选视图应彼此分开（R1）。

2. 设计最精简的图表集（PLAN）——在聊天中公布

先制定图表计划并说明，再开始创建任何内容，以便用户调整方向。对于每张图表：

• id（D1、D2……）和标题
• 受众（eng / product / both）
• 回答的问题（明确的一个问题）
• **范围：**包含 / 排除
• **表示法：**flowchart / uml_class / uml_sequence / entity_relationship
• 边语义（一行——flowchart 必填）：例如“编译时依赖”“运行时调用”“数据读取/写入”
• 必须出现的关键元素
• 可选的 1–3 个代码锚点（文件/模块/函数），供人工导航

图表集应尽可能精简，同时传达核心内容（R2/R5）；优先绘制几张小图，而不是一张超大型图（R7）。

请在此处完善计划：图表小组件创建后，无法通过画布工具移动或删除，因此被弃用的图表仍会留在画布上。

3. 起草每张图表（受表示法约束，不限格式）

根据所选表示法的语义起草内容，并使用类型化的边。必要时添加 UNKNOWN/VERIFY 注释。此时不要编写 Mermaid。

4. 编译前检查（MANDATORY，必须在编写任何 Mermaid 之前完成）

• **拆分检查：**草稿元素超过 15 个 → 拆分为“Overview”+“Deep dive”；超过 20 个 → 必须拆分。
• **边标签检查：**检查是否含有禁用动词（uses/contains/relates/has/supports/manages/integrates）→ 替换为类型化动词或 UNKNOWN。
• 导入图检查（R9）：如果 flowchart 是模块/导入依赖图，优先使用无标签的边，并添加一行图例说明（“--> = 编译时依赖”）；仅在能表达对象级含义时保留标签（“导入类型”“导入 UI 组件”）。包含关系应通过集群/子图或注释表示，绝不能使用“contains”边。
• **Flowchart 形状规范（架构/系统/模块备用方案）——必须遵守：**仅使用普通矩形节点 id[Label]。不得使用菱形决策节点 { }、体育场形/终止符节点 ( )、子程序节点 [[ ]]、圆柱体/数据库节点 [( )] 或其他特殊 Mermaid 形状。只有当图表是真正的算法/控制流视图（R1“Algorithms”场景）时才允许使用特殊形状。这条规则优先于已加载的图表指导中示例展示的形状多样性。
• **ERD 概览检查：**精简为 PK/FK/UQ 加 2–4 个有区分度的字段，并添加省略说明；除非用户明确要求完整架构（此时另做一张“ERD Deep Dive”）。

5. 加载画布指导

在编写任何内容之前，从 Miro MCP 服务加载两项指导：先加载画布编排指导（SVG 画布格式），再加载所绘制表示法的图表格式指导——flowchart、entity_relationship、uml_class 或 uml_sequence。每次对话只加载一次画布编排指导；计划中的每种不同表示法只加载一次图表指导，同类图表可重复使用。两个工具都会说明各自的前置条件和顺序；请遵循其要求。

已加载的指导是 Mermaid 转义、颜色规范和小组件机制的权威依据。请以此为准，不要依赖记忆：特别是图表正文中的箭头必须进行 XML 转义（-->，而非 -->），SVG 中任何位置出现原始 &、< 或 > 都会导致整个请求失败。

将步骤 3 中已经定稿的草稿编译为有效的 Mermaid（目标语法为 Mermaid 10）。不要在编译时改变图表意图。按照指导应用配色规范，以便在 5 秒内快速浏览。

**最终形状审查：**重新检查每张架构/系统/模块 flowchart 的 Mermaid。如果其中用于非算法图表的节点包含任何非矩形形状语法（{ }、( )、[[ ]]、[( )]、> ] 等），请将这些节点改写为 id[Label]，并保持标签不变。

6. 编排并创建

构建一个包含所有图表和配套文档的 SVG 组合，并在一次调用中通过画布创建工具发送。

• 每个图表使用一个 <foreignObject data-type="diagram">，将 data-title 设为计划中的标题，并将编译后的 Mermaid 内容作为正文。
• 画布会将每个图表组件固定为 1600x900，无论你创建时设定的尺寸是多少，因此请按此间距布局——例如，x 轴上每隔 1600 + 间距放置一列，y 轴上每隔 900 + 间距放置一行，并按从左到右的顺序排列。位置重叠是最常见的失败原因。
• 将配套文档（步骤 7）放在同一组合中，位置在第一个图表的左侧或上方。

接下来运行编排器指南要求的重排循环：当响应报告尺寸发生变化时，检查 result_svg 中的这些组件，并使用画布更新工具重新定位受影响的组件，直到间距合适。始终基于最新的 result_svg 迭代——在原内容上编辑并回传；切勿从头重新生成 SVG，也不要凭记忆抄写 data-miro-id 值。

审核后如需修改图表，请通过同一更新工具，使用该组件的 data-miro-id 和新的 Mermaid 正文重新发送。图表组件无法通过此方式移动或删除；未更改的组件会被跳过，因此只重新发送源内容或标题确实发生变化的图表。发送时不得更改含义；如果图表失败，请原样报告错误及对应的 Mermaid 内容。

7. 配套文档

创建一个简短的 <foreignObject data-type="doc">（Markdown 正文，以 H1 标题开头），帮助读者理解这组图表：每张图表回答了什么问题、覆盖范围和假设、任何 UNKNOWN/VERIFY 项，以及接下来应检查的内容。简洁明了，以交付物为主——不要复述图表内容，也不要验证文件是否存在。

将图表索引做成真正的深层链接，而不是无效文本：图表在 result_svg 中获得 data-miro-id 后，将每个标题链接为 <board-url>?moveToWidget=<data-miro-id>，让读者可以直接跳转。由于需要这些 ID，创建调用中的文档正文应先使用纯文本标题，然后在后续的更新调用中补上链接。

输出

在聊天中报告：

1. 画布链接（如果提供了 moveToWidget，则提供画框链接）。
2. 已创建的图表（ID、标题、记法）和配套文档。
3. 值得确认的任何 UNKNOWN/VERIFY 假设。

参考资料

• references/diagramming-principles.md — 完整的 R1–R9 / H1–H4 规则集。起草前请阅读（步骤 3）。