工作坊 → Miro（顶部模式 vNext）

目标

在 Miro 上生成符合以下标准的工作坊输出：

• 可作为图表阅读（而非“散落的便签”）
• 易于编辑（使用真实的容器）
• 幂等（无重复内容）
• 可修正（支持撤销 / 删除 / 更新）

安全要求（强制）

• 严禁打印 MIRO_ACCESS_TOKEN
• 仅允许通过环境变量使用：MIRO_ACCESS_TOKEN 和 MIRO_BOARD_ID
• 严禁使用浏览器 Cookie 或会话令牌

核心规则：一个容器 = 一个 FRAME（而非任意形状）

当满足以下任一条件时，“工作坊容器”必须为 FRAME：

• 存在一个带明确标题的大矩形/正方形（例如：“Easy vision”、“Milestone”、“VMS”、“Data Hub”、“Vico Insider”）
• 存在一个带标题的泳道/列
• 存在一个明显用于分组多个元素（便签或子框）的框

以下情况不得创建 FRAME：

• 仅为无标题的空白区域
• 仅为无实际分组语义的装饰性边框

硬性要求（严禁违反）

• 若白板中存在分类/区域，你必须创建 frames[] 数组。
• 每个便签（sticky）必须分配一个非空的 frameId（显式标注为“outside notes”的便签除外）。
• 若 frames[] 为空，或超过 10% 的便签的 frameId = null：
  • 禁止执行 push 命令。
  • 重新生成结构（最多尝试 2 次）。

质量门禁 — 容器合理性检查（强制）

若图像中包含 ≥2 个带标题的容器：

• frames.length 必须 ≥2
• 至少 95% 的便签必须具有非空的 frameId
  若不满足该条件：
  • 禁止推送
  • 重新生成结构（最多尝试 2 次）

强制规划步骤（不对外输出）

在生成 JSON 及执行 DIRECT PUSH 之前：

1. 识别候选 FRAME：
   • 任何带标题的大矩形
   • 任何在侧边、或居中位于上方/下方的标注区域
2. 将每个便签分配至某个候选 FRAME。
3. 若某便签归属模糊，添加警告，并将其分配至最邻近/最合理的 FRAME。
4. 仅在此之后，生成最终 JSON。

质量门禁（强制）

在执行 node ... apply 前：

• 至少存在 1 个 FRAME。
• 至少 90% 的便签必须具有非空的 frameId。
• 若图像明显包含多个独立区域，则不得存在“巨型”FRAME。
• 若门禁未通过，禁止推送：重新生成结构（最多尝试 2 次）。

去重 / 幂等性（强制）

• 每次推送都必须为同一图表/主题指定一个稳定的 meta.sessionKey（例如："easy-vision-workshop"）。
• 每次推送都必须包含唯一的 meta.runId（时间戳）。
• 若 sessionKey 相同：
  • 首先自动移除前一次运行结果（自动撤销）
  • 再应用新内容
    此举可防止重复和多次运行。

运行模式

A) 直接推送（DIRECT PUSH，用户未特别说明时默认启用）

1. 生成一份适配 Miro 的 JSON（格式见下文），包含：
   • meta.sessionKey（稳定）
   • meta.runId（唯一）
2. 将 JSON 保存至：
   • ...workshop-miro_outmiro-ready-YYYYMMDD-HHMMSS.json
3. 执行：
   • node ...miro-push.mjs apply
4. 回复内容包括：
   • 创建的 FRAME 数量：N
   • 创建的便签数量：N
   • 创建的连接器数量：N
   • sessionKey + runId
   • 警告信息（如有）

B) 修正操作（CORRECTIONS，用户提出修改需求时）

• 按会话撤销（UNDO）：node ...miro-push.mjs undo
• 若用户表示“请重做 / 分类错误 / 移动内容”：
  • 使用相同的 sessionKey 重新生成已修正的 JSON
  • 再次执行 APPLY（将覆盖前一次运行）

注：细粒度编辑（如删除/更新单个便签）属于后续阶段，前提是脚本已支持该能力。
否则推荐：使用相同 sessionKey 进行完整重建（更干净，通常也更快）。

智能布局规则

• 每个 FRAME 内部布局：
  • 左侧：输入源 / 数据源
  • 中部：处理逻辑 / API / 平台
  • 右侧：输出 / UI / 外部集成
• 间距建议：x += 420，y += 260
• 若图中存在横跨整个图表的长箭头：
  • 若能提升可读性，优先拆分为两条较短连接线，并引入中间节点（例如标题为“API”或“Integration”的便签）

连接器 / 关系规则

当出现以下任一情形时，应创建连接器：

• 白板上存在箭头或连线
• 文字暗示流程关系，例如：“API”、“sensoren”、“data”、“->”、“integration”
• 连接器标签：采用描述该流向的词语（例如：“API”、“Sensoren”、“Data”、“Milestone”）

连接器默认形状为 "elbowed"（对架构图更具可读性）。

防重叠规则（保持连接线清晰）

目标：避免连接器穿过便签/备注。

• 连接器默认形状设为 "elbowed"。
• 始终保留一条自由的“布线路由通道”：
  • 勿将便签紧贴 FRAME 边框放置。
  • FRAME 内部最小边距：160px。
• 若某连接器过长，或需穿越密集元素簇：
  • 在簇外创建一个或多个“路由节点”（灰色便签，内容为 "." 或留空）
  • 将连接拆分为多段：A → R1 → R2 → B
• 跨 FRAME 的连接：
  • 在源 FRAME 右侧边界附近放置一个路由节点
  • 在目标 FRAME 左侧边界附近放置一个路由节点

JSON 输出格式（基于 FRAME）

{ "meta": { "title": "字符串", "source": "photo|notes", "language": "it|de|en", "createdAt": "ISO-8601", "sessionKey": "字符串（稳定）", "runId": "字符串（唯一）" }, "frames": [ { "id": "F1", "title": "字符串", "x": 0, "y": 0, "w": 1400, "h": 900 } ], "stickies": [ { "id": "S1", "frameId": "F1|null", "text": "字符串", "color": "light_yellow|light_blue|light_green|light_pink|gray", "x": 0, "y": 0, "unclear": false } ], "connectors": [ { "from": "S1", "to": "S2", "label": "字符串|null", "shape": "straight|elbowed|curved" } ], "warnings": [ "字符串" ] }

硬性容器识别（强制）

“容器”指一个带有标题、且视觉上包围其他便签的大矩形（例如：“Product A”、“Product B”）。

你必须执行以下操作：

1. 为每个容器矩形创建一个 FRAME（标题即容器标题）。
2. 通过 frameId 将其内部所有便签分配至该 FRAME。
3. 仅当便签明确处于所有容器之外时，才允许其 frameId = null。

容器归属必须严格依据视觉位置判断：

• 若某元素在视觉上位于容器边界内，则它属于该容器。
• 若无法确定，分配至最近的容器，并添加警告。

推送前质量检查清单

• sessionKey 存在且稳定
• 除非照片确实只显示一个巨大的单体框，否则禁止创建巨型 “Workshop” FRAME
• 每个便签均归属正确的 FRAME（分类）
• 同一 FRAME 内不得存在文本完全相同的重复便签
• 连接器仅在逻辑合理处创建（并非每对元素之间都需要）