pma-draw

ReactFlow 图表创建器

生成 .rfd.json 文件，用形状、位置和连接关系表达含义，供基于 ReactFlow 的查看器（pma-viewer）使用；该查看器包含预定义的自定义节点类型目录。

保持此入口文件精简。仅加载当前图表所需的参考资料。

始终遵循的规则

1. 优先保证同构性：节点布局和边的拓扑结构必须映射概念的结构。移除所有标签后仍能传达其含义，设计才算正确。
2. 仅使用预定义的节点类型。从 references/node-types.md 中选取每个节点的 type。除非用户要求且查看器支持，否则绝不自行创建新类型。
3. 仅使用预定义的边类型。从 references/edges.md 中选取每条边的 type。除非没有合适的预设，否则避免使用原始的 default。
4. 颜色取自 references/colors.md。节点样式由预设决定；仅在语义需要时覆盖。
5. 通过父子关系分组，而不是绘制容器矩形。对子节点使用 parentNode + extent: "parent"，并将 group 类型作为父节点。
6. 每种关系都需要一条边。仅靠邻近位置不构成连接。
7. 不在本地渲染：该技能仅生成 .rfd.json。渲染和导出由 pma-viewer（SPA）完成。必须在 JSON 层面保证质量，详见 references/validation.md。
8. 按章节逐步构建大型图表。每次编辑时追加节点/边，并按章节前缀为 ID 命名空间（ingest__、process__、deliver__），以便清晰地引用跨章节内容。

核心工作流

第 1 步：评估深度

• 简单 / 概念性 — 使用抽象节点类型（process、start、end）和通用边。适用于心智模型和理念。
• 全面 / 技术性 — 使用语义化节点类型（backend、database、queue、ai）、包含真实代码/JSON 的 evidence 节点，以及带类型的边（stream、callback）。适用于真实系统、协议和教程。

技术图表需要先进行调研：在编写 JSON 之前，查阅实际规格、端点、事件名称和数据格式。

第 2 步：概念到模式的映射

为每个主要概念选择能映射其行为的视觉模式——发散、汇聚、树、时间线、循环、流水线、并列、间隙、云。不同的主要概念不应共用同一种模式。详见 references/design.md。

第 3 步：规划布局

从 references/layouts.md 中选择布局模板（vertical-flow、horizontal-pipeline、hub-and-spoke、swimlanes、timeline、matrix）。生成节点之前，先计算 position 值的网格。ReactFlow 使用绝对像素位置——布局一致性来自共用网格，而非自动布局过程。

第 4 步：选择节点和边类型

• 每个已发现的组件 → 从目录中选择一个节点 type。
• 每种关系 → 选择与其语义（流、数据流、回调、依赖、比较）相符的边 type。
• 对于技术图表，为真实代码片段或数据载荷添加 evidence 节点。

第 5 步：生成 JSON

编写包装对象 + nodes[] + edges[] + viewport。以 references/templates.md 中的预定义模板为起点。使用描述性 ID（api-server、edge__api-to-db）。

第 6 步：验证并交接

运行 references/validation.md 中的交付前检查清单（ID 唯一、边引用的节点存在、parentNode 引用有效、sourceHandle/targetHandle 符合节点约定、位置没有冲突）。然后告知用户在 pma-viewer 中打开文件（详见 references/render.md）。Agent 无法查看渲染结果，因此必须严格遵守 JSON 层面的规范。

按章节绘制大型图表

1. 编写外层结构（schema、type、viewport、metadata）以及第 1 节的 nodes + edges。
2. 每次编辑追加一个章节。按章节为 ID 添加前缀（ingest__source、ingest__queue），让后续跨章节边易于阅读。
3. 当新章节中的边指向较早的节点时，引用前一章节中该节点的准确 ID。
4. 按章节划分位置：为每个章节预留列（x）或行（y），避免后续编辑与已有内容重叠。
5. 所有章节完成后，通读整个文件一次，检查边引用和位置重叠，再交付。

不要在单次响应中生成完整的大型图表，不要手写生成器脚本，也不要将 JSON 输出委托给编码子 Agent——逐章节编辑以外的这些方式都会产生更差的结果。

输出

• 文件：默认保存至 docs/architecture/<name>.rfd.json，也可使用用户指定的路径。扩展名 .rfd.json 表示 ReactFlow Diagram 架构，同时兼容纯 JSON 工具。
• 查看：在 pma-viewer（基于 ReactFlow 的 SPA）中打开。PNG / SVG 导出和编辑都在其中进行——交接方式见 references/render.md。
• 嵌入：references/integration.md 中介绍了四种方式：
  • React / MDX 站点 → <PmaViewer src="..." /> 组件
  • 纯 HTML → pma-viewer UMD <script> + PmaViewer.mount(...)
  • 交互式链接 → 使用 ?src=<url> 查询参数的托管查看器
  • 静态图片（GitHub README、电子邮件、PDF）→ 服务器渲染的 SVG 端点 GET /render.svg?src=<url>

参考资料包

• references/design.md 可视化模式库、证据材料、多级缩放架构、概念到模式的映射。
• references/json-schema.md 文件外层结构、nodes / edges / viewport 结构、parentNode 分组规则、连接点。
• references/node-types.md 预设自定义节点目录，包含各类型的数据架构。涵盖语义、结构和实用类别。
• references/edges.md 预设边目录：流、数据流、回调、依赖、比较、注释。连接点位置、动画、标签。
• references/colors.md 语义色彩方案（默认 / AWS / Azure / GCP / K8s）和文本层级。节点类型参考中的样式预设会引用此文件。
• references/layouts.md 布局模板（垂直流、水平管线、中心辐射、泳道、时间线、矩阵）及网格计算。
• references/templates.md 可复制粘贴的节点 / 边 JSON 和完整的入门图表（三级架构、微服务、事件驱动、数据管线、CI/CD）。
• references/validation.md 交付前检查算法、清单、常见问题处理方案。
• references/render.md pma-viewer SPA 契约、交接格式、查看器内导出、故障排查。
• references/integration.md 下游使用方如何嵌入图表：MDX / React 组件、浏览器 <script> SDK、通过托管查看器加载 URL 中的 JSON，以及服务器渲染的 SVG 端点（用于 GitHub README、电子邮件、PDF）。

快速指引

• 从头开始设计：加载 references/design.md，然后加载 references/layouts.md。
• 选择节点 / 边类型：加载 references/node-types.md + references/edges.md。
• 编写 JSON：加载 references/json-schema.md + references/templates.md。
• 从代码库提取架构：加载 references/node-types.md + references/layouts.md。
• 交付前验证：加载 references/validation.md。
• 告知用户如何在 pma-viewer 中打开或导出：加载 references/render.md。
• 在文档中嵌入图表（MDX / HTML / README / SVG）：加载 references/integration.md。

如果项目还使用 /pma 控制工作流，请先加载 /pma，只有在需要图表时再加载 /pma-draw。