Mirofy

# Mirofy

从一个结构化的 JSON 规范创建一个自包含、可交互的 HTML 图表。默认输出静态版本；仅当用户要求演示或演示文稿时才启用动画。

## 扫描优先：从真实仓库推导图表

当图表必须描述现有代码时，请勿凭记忆创作。请推导它：

```bash
npm run scan      # 仓库 -> 证据图（事实与差距）
npm run model     # 证据 + 文档 -> 一个系统模型
npm run compile   # 模型 -> 具有意图的限定视图

每一步都会报告它无法确定的内容。scan 会记录其无法分析的每个文件的差距，compile 会记录其省略的每个对象及其原因。将这些信息传递给用户；一个静默省略一半系统的图表比一个标明遗漏内容的图表更糟糕。

当用户描述尚未存在的事物或没有可用的仓库时，请使用下面的快速路径。

快速创作路径

对常规生成使用此有限路径。除非用户询问这些功能，否则不要阅读可选的 Viewer Runtime 参考。

1. 从问题中选择 architecture、workflow、sequence、dataflow 或 lifecycle。

2. 阅读 schemas/ 中的一个匹配模式、schemas/common.schema.json 以及 examples/ 中的一个匹配 JSON 示例。仅读取这些文件。全新的创作意味着新的稳定 ID、领域措辞和布局；使用示例来了解字段形状，而非事实。当涉及真实产品身份时，运行 node bin/mirofy.mjs brands "<name>" --json；仅当用户提供了未知品牌的 URL 时，才读取 references/brand-marks.md。

3. 先制作工件：下一个工具操作必须写入候选文件。在检查渲染器内部之前写入候选文件。不要用散文规划精确坐标。从一个清晰的主路径、短分支、稀疏标签和最多 12 个主要节点开始。将 meta.quality_profile 设置为 "showcase"，除非用户明确要求密集的 standard 地图。从自动路由和标签开始。在诊断需要之前，不要添加 via、channelX、channelY 或 labelAt；每次修复最多应用一个被诊断的几何控制。

4. 每次编辑候选文件后以及移交给用户前立即进行验证：

   node bin/mirofy.mjs validate <type> <candidate.json> --quality showcase --json
   

   仅通过 4 项工件检查的回执是基本验证，绝不是展示验收。展示通过必须报告所有 9 项工件检查，且组合错误和警告均为 0。如果候选文件省略或拼错了确切的 meta.quality_profile 字段，请在处理几何之前修复它。最终验证通过后，候选文件即被冻结：之后切勿编辑它。

5. 对于交付的 HTML，deliver 是最终的验收命令：

   node bin/mirofy.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   非零退出码永远不能描述为成功。如果验证失败，仅更改被诊断的 subject，验证 evidence，从 supportedFixes 中选择，然后重新运行。在目标错误计数达到新最小值之前，持续进行针对性修正。如果连续两轮未改善该最佳计数，请停止并如实报告未解决的诊断信息。

在第一个候选文件之前，不要读取 renderers/shared/geometry.mjs、渲染器源代码、验证器源代码、测试或基准测试。仅在出现不支持的内部诊断或两次针对性修复失败后，才检查实现。

类型路由

类型	用途
architecture	组件、服务、云端/安全边界、基础设施
workflow	流程、审批门禁、工具调用、运行手册、CI/CD
sequence	API 调用链、请求生命周期、异步跟踪、返回值
dataflow	管道、ETL/ELT、血缘、治理、消费者
lifecycle	状态/状态转换、重试、等待和终止状态

当有歧义时，运行 node bin/mirofy.mjs guide "<scenario>" --json。场景证明示例是结构参考，而非要复制的事实。

Mermaid 输入

node bin/mirofy.mjs import mermaid <input.mmd> [output.json] [--json]

flowchart/graph → architecture，sequenceDiagram → sequence，stateDiagram(-v2) → lifecycle。

导入器从不猜测：它无法读取的任何行都会成为带有行号的差距，因此要报告未被传递的内容，而不是称结果为完整。它也不分配任何位置——转换后的架构使用 layout.mode: "grid"，并且扇出可能使边穿过节点，这会导致始终处于开启状态的 clean-flow 门禁失败。导入后务必进行验证。 也要阅读源文件以了解含义：导入器传递拓扑结构，而非领域判断，因此标签和类型通常需要重写。

修复几何

当验证报告重叠组件时，不要手动逐个编辑坐标：

node bin/mirofy.mjs repair <type> <input.json> [output.json] --safe

--safe 是必需的，因为它会重写已创作的坐标。修复仅移动涉及重叠的组件，每个组件以清除验证器 8px 间隙所需的最小修正量移动，打印每次微移的回执，并且仅触碰几何，绝不触碰标签、类型、连接或 ID。它会重新验证并命名位移无法修复的问题（如路由、标签放置），而不是将其留给下一次运行重新发现。

创作不变量

• 一条明显的主路径；侧分支离开最近的主路径节点。在添加路由控制之前，移除低价值的边。
• 默认省略 meta.visual_preset，以便每个图表都以 classic 样式打开，无论其解析的颜色模式是浅色还是深色。颜色模式和视觉预设是独立的：切换浅色/深色必须保留当前预设。仅当用户明确请求该视觉风格时，才设置 signal-flow、blueprint 或 editorial。
• 默认省略 meta.subtitle。切勿发明重复标题、节点或卡片内容的副标题；仅当用户明确要求时，才包含一行简短的辅助内容。
• 默认将独立的桌面查看器视为全屏工件，而非浅窄的条纹。生成一个适用于笔记本电脑和外接显示器的响应式工件——切勿生成特定于设备的 HTML 或替代拓扑。查看器可能仅根据实时视口高度调整外部阅读宽度；它必须保留创作的 SVG/viewBox、比例、语义几何和正常文档流。在宽或高的桌面上，使用足够的创作垂直节奏，使图表面板及其必要的结论卡片作为平衡的整体占据屏幕；运行时缩放无法修复过度压缩的 Y 布局或过小的显式 meta.viewBox。在移交前，在 1440×900、1600×1000 和 1920×1080 分辨率下打开真实的 HTML；此外，当构图为大型桌面显示器设计时，还要检查 2048×1320。要求在每种检查尺寸下，document.documentElement.scrollWidth <= window.innerWidth 且 scrollHeight <= window.innerHeight，同时视觉上检查图表在最大检查视口下是否仍然舒适可读且垂直平衡。通过仅移除确实多余的内容或紧凑间距来修复溢出，然后再缩小节点、标签或主面板。如果最大视口在查看器宽度上限处仍有一个明显的空白下带，则重新分配创作的 Y 位置并成比例增加 viewBox 高度；不要添加填充内容或装饰性卡片。切勿通过 overflow: hidden、裁剪内容、内部图表滚动器、拉伸的 SVG 高度或更小的字体来伪造通过。窄/移动端布局在必要时可以垂直滚动。
• 默认真实的 auto 时省略 meta.legend。当需要时，仅使用 mode: auto|all|hidden 以及渲染器支持的 entries.<kind>.label|visible；标签从不改变语义。
• 根据用户明确选择选择一种主要创作语言；否则遵循请求或对话的主导语言。meta.locale 仅控制渲染器拥有的查看器 UI：使用 "en" 或 "zh-CN" 以对应支持的主要语言。对于所有其他语言，省略 meta.locale 并明确披露固定的查看器 UI 和 <html lang> 将回退到英语。渲染器从不翻译创作内容。详见 references/authoring-contract.md。
• 保留精确的产品名称、代码标识符、命令、协议、API 路径和环境名称。在本地化文案中它们可以保留为英语，但切勿以此为理由将周围的解释性散文保留为另一种语言。
• 品牌身份是可选的且是显式的。当节点命名真实产品时，在 brand 中放置规范的内置 ID。如果没有预置匹配且用户提供了官方 HTTP(S) URL，首先运行 node bin/mirofy.mjs brands capture "<url>" --json，然后创作返回的、带有摘要锁定的 brand 对象。渲染和验证从不执行未锁定的捕获。否则省略 brand。切勿从诸如 "database" 的模糊角色推断品牌，也绝不要让徽章取代语义 type、标签或关系事实。
• 对于时序图，对于稳定的 fixed 布局省略 meta.column_fit。当宽 viewBox 会留下未使用的水平空间，或有意义的参与者标签无法适应固定框时，将其设置为 "spread"；在尝试 spread 之前不要缩短语义标签。
• 组件类型为 frontend、backend、database、cloud、security、messagebus 和 external；变体为 default、emphasis、security 和 dashed。
• 关系标签是语义数据。当发生碰撞时，移动标签、调整路由或间距，然后在保留含义的同时缩短措辞。仅当两个端点完全暗示关系且标签不包含协议、动作、方向、同步/异步行为或跨边界机制时，才删除标签；并解释为什么删除的标签是多余的。切勿仅仅为了通过 showcase 而删除有意义的标签。
• 默认省略 meta.engineering_profile。区域、集群和安全边界措辞本身并不启用它。仅当用户明确要求生产部署拓扑、所有权交接或故障关闭部署审查，且源事实已知时，才启用 deployment-ownership。一旦启用，绝不能仅仅为了通过验证而删除工程概况；应修复事实或如实报告诊断信息。
• 间距意味着清晰的间隙，而非中心距离。对于关系标签，清晰间隙必须超过其测量的遮罩宽度；在考虑删除之前，使用保留标签的修复顺序。
• 自动路由拥有其端点侧。侧是一个方向契约：第一个和最后一个线段必须垂直于该侧进出。
• 自动端口分布是架构图、工作流图、数据流图和生命周期图的默认渲染器行为。它会跳过单一关系和显式的 via、channelX、channelY、labelAt 或非 auto 路由。接近的平行端口使用外部桥接，以便自动路由不会创建小于 8px 的线段或小于 16px 的内部转弯。架构图额外保持无遮挡的面对自动端口（left/right 或 top/bottom）在其偏移小于 16px 且两个端口均保留角间距时位于一个共享轴上。如果恰好一个端点被分布，则只有未共享的端点可以移动到该轴上；如果两个端点都被分布，则保持外部桥接，以便竞争端口保持区分。
• 绝不允许边穿过不相关的非透明节点、模糊的共享通道，或关系标签遮蔽另一条路由。

仅当需要字段枚举、间距计算、自动端口放置、几何修复规则、仓库证据或特定模式的放置时，才读取 references/authoring-contract.md。

交付

在修复期间使用 validate，并最终使用 deliver 进行验收。交付将确切的规范字节冻结到一个私有的同目录快照中，渲染并检查该快照，原子地提交 HTML，并报告规范与工件的 SHA-256 和字节计数。

交付后，在不修改或重新渲染受信任的 HTML 的情况下收集桌面证据：

node bin/mirofy.mjs visual-check <output.html> --json

visual-check 在 1440×900、1600×1000、1920×1080 和 2048×1320 下测量包含性；在最小和最大尺寸下捕获浅色/深色截图；并在工件旁边写入相对路径的联系表以及 JSON sidecar 文件。其自动回执始终报告 visualReview: "pending"：截图是用于检查的证据，而非自动的完美声明。退出码 0 表示包含性和捕获通过，1 表示溢出或捕获失败，2 表示 Chrome/Chromium 不可用且回执为 skipped。该命令不会更改已交付的 HTML。仅当用户想要立即本地预览时才添加 --open。对于活跃的桌面创作循环，可选命令是：

node bin/mirofy.mjs preview <type> <input>.json <output>.html --quality showcase

默认不启动预览。当使用预览、仓库证据、导出回执、视觉审查或提交后打开时，请阅读 references/delivery-contract.md。

可选的查看器功能

生成的 HTML 已包含主题切换、平移/缩放、搜索、聚焦、关系追踪、语义视图、演示和真实的导出。这些是读者的功能，而非额外的创作工作。meta.animation: "trace" 是选择加入的；meta.views 是可选的，最多应包含五个精选章节。仅当用户明确询问分享卡片、路由/到达卡片、动画、引导式故事、深层链接、演示、搜索/聚焦或其他 Viewer Runtime 功能时，才读取 references/viewer-runtime.md。

设置与回退

安装技能是可选的。

...

[内容已截断以供翻译]