diagram

图表

使命

生成易于阅读、符合 ToDiagram 自定义架构且便于快速理解的 .todiagram JSON。

模式路由

1. schema-build：用户要求创建或修复 .todiagram 结构，或将笔记转换为有效的节点/边。
2. system-architecture：用户要求绘制平台/服务/组件拓扑。
3. flow-diagram：用户要求绘制工作流、用户旅程、运行手册或决策流程。
4. detail-calibration：用户要求简化、丰富或拆分内容密集的图表。

如果请求涉及多个模式，请按以下顺序执行：

1. schema-build
2. system-architecture 或 flow-diagram
3. detail-calibration
4. 最终架构验证

全局输出约定

• 默认优先输出文件，以确保稳定性： 创建 .todiagram 文件并返回其路径。
• 只有用户明确要求内联输出时，才返回内联 JSON。
• 使用规范的原始 .todiagram 键：nodes、edges、direction、id、label、from、to、imageUrl、iconUrl、custom_theme、fields。
• 将节点显示数据放在 fields 对象中。架构已弃用节点上的直接属性。
• 同一节点上绝不能同时使用 imageUrl 和 fields——imageUrl 会替代行渲染。
• 仅在使用 imageUrl 和 iconUrl 时才包含这些键；否则完全省略。
• 仅对具有实际子节点的真实容器使用节点级 nodes。
• direction 仅限 RIGHT、LEFT、UP 或 DOWN（使用 UP，不要使用 TOP）。
• 保持 ID 全局唯一；确保每个边的端点都能对应到现有 ID。
• 图标优先使用 Iconify 规格（logos:*、fa7-solid:*、fa:gear 等简写）；只有用户明确要求时才使用外部 URL 图标。
• 不确定准确的 Iconify slug 时，通过 curl -fsSL 'https://api.iconify.design/search?query=<term>&limit=10' 查询（可选添加 &prefix=logos），并从返回的 icons 数组中选取 slug。若可用，请使用 ToDiagram MCP 图标搜索工具。
• 使用 custom_theme（NODE、EDGE、TEXT 分组）为每个节点设置主题——完整键列表请参阅架构约定。

文件输出策略

• 如果用户提供了目标路径/名称，请写入该位置。
• 如果用户未提供，请根据图表主题或内容生成简短的 kebab-case 文件名 （例如，“系统架构” → system-architecture.todiagram，“用户引导流程” → user-onboarding-flow.todiagram，“AWS 基础设施” → aws-infrastructure.todiagram）。 写入当前工作目录。
• 输出多个图表时，请使用稳定且描述明确的名称： overview.todiagram、domain-<name>.todiagram、flow-<name>.todiagram。
• 写入后，运行： python scripts/validate_todiagram_schema.py <file>.todiagram

核心工作流

1. 确定受众和决策意图。
2. 选择模式和细节层级（概览、工作级、深入分析）。
3. 先起草容器层级，再添加叶节点，最后添加边。
4. 添加简洁标签和少量高价值元数据。
5. 使用 references/authoring-checklist.md 验证，并运行： python scripts/validate_todiagram_schema.py <file>.todiagram
6. 如果内容过于密集，请使用 references/split-strategies.md 拆分，同时保留共享 ID/名称。

模式操作手册

1) 架构构建

请先阅读 references/schema-contract.md。

除非用户提供了不同的封装结构，否则使用此脚手架：

{
  "direction": "RIGHT",
  "nodes": [],
  "edges": []
}

规则：

• 仅当键映射偏离默认值时才添加 configuration。
• 将载荷规范化为规范键（children → nodes，source/target → from/to）。
• 将已弃用的节点直接属性移入 fields 对象。
• 如果节点同时具有 imageUrl 和 fields，请删除其中一个——两者不能共存。

2) 系统架构

阅读：

• references/grouping-playbook.md
• references/architecture-patterns.md

规则：

• 优先采用 2-3 个层级。
• 大多数容器的子项数量控制在 3-8 个。
• 默认通过叶节点之间的连接表示交互。
• 概览图尽量减少元数据。

3) 流程图

阅读：

• references/flow-patterns.md
• references/labeling-guide.md

规则：

• 先构建理想路径，再添加分支、失败和重试。
• 每张图保持一个主导方向。
• 边标签简短（1-3 个词）且有意义。

4) 细节校准

阅读：

• references/complexity-budgets.md
• references/split-strategies.md

规则：

• 生成前先选择细节层级。
• 如果超出预算，按领域、生命周期、环境或受众拆分。
• 确保不同图之间的命名和共享 ID 保持一致。

示例意图

• “在 ToDiagram 中创建高层 SaaS 架构。” -> system-architecture + 概览层级。
• “修复这个无效的 ToDiagram JSON。” -> schema-build。
• “将这份事故处理手册转换成清晰的流程图。” -> flow-diagram（内容密集时再加 detail-calibration）。

故障排除

• 载荷结构无效：先规范化键并展开包装层。
• 图表过于杂乱：移除低价值元数据，并拆分为聚焦的视图。
• 图表过于抽象：为关键叶节点添加 1-2 个重要元数据属性。
• 关系不清晰：添加简洁的协议、操作或结果边标签。
• 架构验证依赖项错误：通过 python3 -m pip install --user jsonschema 安装 jsonschema。

参考资料

• 架构契约：references/schema-contract.md
• 编写检查清单：references/authoring-checklist.md
• 架构模式：references/architecture-patterns.md
• 分组指南：references/grouping-playbook.md
• 流程模式：references/flow-patterns.md
• 标签指南：references/labeling-guide.md
• 复杂度预算：references/complexity-budgets.md
• 拆分策略：references/split-strategies.md

脚本

• 规范格式与架构验证器： scripts/validate_todiagram_schema.py