generate-diagrams

生成图表（媒体渲染器）

使用一条打包命令，将已批准的 DIAGRAM_SPEC.md 渲染为项目 images/ 文件夹中的 SVG 文件。该命令负责提取 D2、验证、标志、主题样式、输出检查和临时文件清理；此 Skill 负责范围、布局选择、交互式审阅、结果报告和阶段状态。

输出语气

对范围问题、审阅提示和结果报告进行轻量润色，使语气自然。传递用户提供的 Media Intent 和 D2 源代码时，保持原样；文件名、路径、命令和状态值也必须准确无误。在批准图表标签或说明文字之前，必须调用独立的 unslop Skill，使用 DISCOVERY.json.editorialPreferences 完成完整的编辑审校；保留 D2 语法和语义标签。

流程：确定媒体范围，默认采用批处理（用户要求时采用交互式）；审阅并报告结果；仅更新自有的媒体阶段，取消或失败时将其保留为待处理状态；保留无关的阶段记录。D2 设置仍在本地进行。

启动

1. 从 DISCOVERY.json 确定项目文件夹（使用 paths.diagramSpec；若无则回退到 DIAGRAM_SPEC.md），如有歧义则询问。

2. 必须存在 DIAGRAM_SPEC.md。如果缺失：

   ❌ 未找到 DIAGRAM_SPEC.md。请先创建并批准图表规范，再渲染图表。 中止。

3. 运行 which node。如果未找到，则中止：❌ 未安装 node — 图表渲染命令需要 Node.js。

4. 运行 which d2。如果未找到，说明需要 D2 并提供以下选项：

   ❌ D2 is not installed. It is required to render SVG diagrams.
   
     1  Install D2 now       — I’ll use a suitable installation method after your confirmation
     2  I’ll install it      — install D2 yourself, then tell me when it is ready
     3  Cancel
   

   • 1：确认操作系统和包管理器，并在安装前征求确认。在使用 Homebrew 的 macOS 上优先采用 brew install d2；在 Linux 上使用 D2 的官方安装程序或发行版包管理器；在 Windows 上使用受支持的包管理器或官方安装程序。
   • 2：提供官方 D2 安装指南链接，并等待用户确认已安装。
   • 3：停止，不修改项目。
   • 选择 1 或 2 后，再次运行 which d2；仅当命令能找到 D2 时才继续，否则再次提供相同选项。

5. 确定当前调用的 SKILL.md 所在目录的绝对路径。渲染命令为 <skill-directory>/scripts/render-diagrams.mjs；必须确认文件存在，并在每次调用时引用其绝对路径。绝不可根据 cwd 推断该路径。

流程

步骤 1：确定媒体范围

读取 DIAGRAM_SPEC.md 中每个条目的 **Filename:**，并检查对应文件是否存在。

• 已明确指定： 请求或用户刚刚回答的决策提示明确对应某些条目：幻灯片编号、文件名、“all”、“missing”，或恰好匹配一个条目的描述（“标题图表”）。无需提问。对范围内已存在的每个文件打印一行 Overwriting images/foo.svg (Slide N)，然后进入步骤 2。如果指定的幻灯片或文件名没有对应条目，则不渲染任何内容：说明情况并使用下方菜单。

• 未明确指定且没有文件存在： 范围为所有条目。无需提问；进入步骤 2。

• 未明确指定且至少有一个文件存在： 显示：

  ⚠️  images/ — existing files detected (N of M diagrams already present)
  
    Already present:    • images/foo.svg  (Slide 1 — Title)  [...]
    Not yet generated:  • images/bar.svg  (Slide 3 — Title)  [...]
  
    A  Generate missing only   — skip the N that already exist
    B  Regenerate everything   — overwrite all M diagrams
    C  Choose slides           — e.g. "C 1 3"
    D  Cancel
  

  等待用户选择。选择 C 时，从同一条回复中获取幻灯片编号；只有用户单独回复 C 时才询问“哪些幻灯片编号？（例如 1 3 5）”。选择 D 则停止，不做任何更改。

步骤 2：渲染

除非用户要求逐个查看图表，否则使用 Batch 渲染。

Batch — 一次调用处理整个范围：

node "<absolute skill directory>/scripts/render-diagrams.mjs" "<DIAGRAM_SPEC.md path>" [--force] [--slides=N,M,...]

• 所有条目，或仅处理缺失项 → 不加标志（命令会跳过已有文件）。
• 重新生成全部内容 → --force。
• 指定幻灯片 → --slides=N,M,...，并加上 --force 以覆盖已有文件。

Interactive — 仅在用户要求时使用。对范围内的每张幻灯片，调用：

node "<absolute skill directory>/scripts/render-diagrams.mjs" "<DIAGRAM_SPEC.md path>" --slide=N --force

每次调用后，显示：

✅ Saved: images/foo.svg  (Slide N — Title)
   Open to review, then choose:

     N  Next  — accept and continue to the next diagram
     R  Redo  — render again (after you edit DIAGRAM_SPEC.md)
     S  Stop  — exit and keep what has been rendered so far

R 重复同一调用。S 结束循环；此阶段仍保持待处理状态。

该命令就是完整的渲染步骤：它会解析条目、运行 d2 validate、通过 Diagram Roles 应用锁定的 Presentation Theme、检查每个 SVG 的结构和 20 px 有效文本大小，并进行清理。只能通过该命令运行 D2。

步骤 3：仅提供适用的布局

本 Skill 是唯一提供图表布局选项的地方。每当必须更改图表布局时（有效文本大小检查失败后或用户提出要求时），将每个候选方案的 D2 写入操作系统临时目录中的文件，并在不编辑 DIAGRAM_SPEC.md 的情况下检查：

node "<absolute skill directory>/scripts/render-diagrams.mjs" "<DIAGRAM_SPEC.md path>" --check --slide=N --candidate="<temp file>"

仅在 Decision Prompt 中提供退出码为 0 的候选方案，并说明检查输出中的媒体框：例如，“图表区域为 1152×347，约为 3.3:1，因此纵向布局无法达到 20 px。”如果没有候选方案通过，请说明情况，并提供剩余方案：拆分图表、缩短标签，或在 Theme Package 中增大角色字体。由用户选择；然后编辑 DIAGRAM_SPEC.md 并重新渲染幻灯片。--check 不会向 Project Folder 写入任何内容；全部通过时退出码为 0，任一失败时为 1，用法或前置条件错误时为 2。

步骤 4：报告并更新状态

转达命令摘要。其消息会注明幻灯片、问题和修复方法。

退出码	含义	操作
0	所有选定图表均已渲染或已存在	在 Batch 模式下，或最后一次 Interactive N 之后，将 PROJECT.json 中的 phases.diagrams.status 设为 "done"，并更新其完成时间戳
1	至少一个条目失败；已渲染的图表会保留	报告每个失败项；如果有效文本大小检查失败，转到步骤 3；保持此阶段为待处理状态
2	用法或前置条件错误	报告该消息并遵循其指示（例如，在 generate-slides 中刷新主题）；保持此阶段为待处理状态
130	已中断	保持此阶段为待处理状态

该命令不会写入 PROJECT.json；只有本 Skill 会更改状态。只有完整范围的退出码为 0 时，才将此阶段标记为完成，并保留所有其他阶段记录。