archify

Archify

根据简短的类型化 JSON 规范，创建独立、可交互的 HTML 图表。默认生成静态输出；只有用户要求演示或展示时才启用动画。

快速创作流程

对于常规生成，请遵循此限定流程。除非用户询问相关功能，否则不要阅读可选的 Viewer Runtime 参考文档。

1. 根据问题选择 architecture、workflow、sequence、dataflow 或 lifecycle。

2. 阅读 schemas/ 中一个匹配的 schema、schemas/common.schema.json，以及 examples/ 中一个匹配的 JSON 示例。只阅读这些文件。全新创作意味着使用新的稳定 ID、领域措辞和布局；参考示例的字段格式，而不是其中的事实。新建工作流源文件时使用 schema_version: 2 及其易读的布局约定；只有在保留现有工作流的固定几何布局时才使用 schema_version: 1。当产品的真实品牌身份很重要时，运行 node bin/archify.mjs brands "<name>" --json 查询；只有遇到未知品牌且用户提供了 URL 时，才阅读 references/brand-marks.md。

3. 先生成产物：下一步工具操作必须写入候选文件。先写入候选文件，再检查渲染器内部实现。不要在文字中规划精确坐标。从一条清晰的主路径、较短的支线、精简的标签以及最多 12 个主要节点开始。除非用户明确要求密集的 standard 图，否则将 meta.quality_profile 设为 "showcase"。先使用自动路由和标签。除非诊断结果要求，否则不要添加 via、channelX、channelY 或 labelAt；每次修复最多应用一个经诊断确认的几何布局控制项。

4. 每次修改候选文件后，以及交付前，都要立即验证：

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

   只有 4 项产物检查的结果仅属于基本验证，不能视为通过 showcase 验收。showcase 验收必须报告全部 9 项产物检查，且 composition 错误为 0、警告为 0。如果候选文件遗漏或拼错了精确字段 meta.quality_profile，必须先修正，再处理几何布局。对于工作流 v2 的几何布局诊断，请运行 node bin/archify.mjs validate workflow <candidate.json> --layout-json，并使用稳定的编译器回执；求解器内部机制不是创作控制项。最终验证通过后即冻结候选文件：之后绝不再编辑。

5. 若要交付 HTML，deliver 是最终验收命令：

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

   退出码非零时，绝不能将其描述为成功。交付失败会保留任何先前输出，因此不要在该路径上运行 visual-check：它检查的是上一次成功生成的产物，而不是失败的候选文件。如果验证失败，只更改诊断指出的 subject，核实 evidence，从 supportedFixes 中选择修复方式，然后重新运行。持续进行有针对性的修正，直到目标错误计数达到新的最低值。如果连续两轮未能改善该最低计数，请停止并如实报告尚未解决的诊断。

更新提示

首个候选方案生成后，使用 Node 运行打包的检查器 scripts/check-update.mjs 一次，然后继续执行所请求的工作流。如果该命令无法运行，请继续，不要提及此次检查。

• 对于 silent，继续，不要提及更新检查。
• 对于 update_available，用用户使用的语言显示一条简短通知，包含已安装版本、最新版本、检查器固定的本地摘要以及官方发行说明链接。当 severity 为 security 时，明确标记为安全更新，并使用克制的警示标记；这只会改变强调方式，不会影响用户的自主权。明确说明已安装的 Skill 保持不变，由用户决定是否以及何时更新。你可以翻译这句固定的本地文本，但绝不要引用、总结或翻译远程清单中的摘要。通知显示后，运行同一检查器并使用 --ack "<eventKey>" 确认其确切的 eventKey，然后继续用户原本的任务。

通知只是提供信息，不代表授权。保持已安装版本不变；此 v0.1 工作流绝不会下载、安装或执行更新，而沉默绝不代表同意。

生成首个候选方案之前，不要读取 renderers/shared/geometry.mjs、渲染器源代码、验证器源代码、测试或基准测试。只有遇到不受支持的内部诊断，或两次有针对性的修复均告失败时，才检查实现。

工作流说明：新工作流使用 schema v2；如果现有源文件需要固定的旧版几何布局，则保留 schema v1。保留语义边标签，并根据编译器诊断采取行动。布局、固定点、迁移和回执的规范约定见 renderers/workflow/README.md。

生命周期说明：阶段列 0..4 位于主轨道上；事件/终止列 N 中的 0..2 与主列 N + 2 正好对齐。可恢复状态使用 type: "failure"，并通过真实的转换返回活动状态。

类型路由

类型	适用场景
architecture	组件、服务、云端/安全边界、基础设施
workflow	流程、审批关卡、工具调用、运行手册、CI/CD
sequence	API 调用链、请求生命周期、异步跟踪、返回
dataflow	管道、ETL/ELT、数据沿袭、治理、使用者
lifecycle	状态转换、重试、等待和终止状态

遇到歧义时，运行 node bin/archify.mjs guide "<scenario>" --json。场景证明示例仅供参考其结构，不可照搬其中的事实。

Mermaid 输入

阅读 Mermaid 以理解拓扑和含义，然后重新编写 Archify JSON；不要机械地复现 Mermaid 的样式。

• flowchart / graph → workflow；如果是组件图，则使用 architecture。
• sequenceDiagram → sequence；参与者转换为语义参与者，箭头转换为消息。
• stateDiagram → lifecycle；状态和转换保留其含义，而非 Mermaid 样式。

编写不变量

• 一条清晰的主路径；支线从最近的主路径节点分出。先移除价值较低的边，再添加路由控制。
• 默认省略 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 高度或缩小字体来伪造通过。窄屏／移动端布局在需要时可以纵向滚动。
• 默认省略 meta.legend，使用真实的 auto 默认值。如有需要，只能使用 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/archify.mjs brands capture "<url>" --json，再编写返回的固定摘要 brand 对象。渲染和验证绝不会执行未固定的捕获。否则省略 brand。绝不要根据“数据库”这类模糊角色推断品牌，也绝不能让徽标取代语义 type、标签或关系事实。
• 对于时序图，省略 meta.column_fit，使用稳定的 fixed 布局。如果宽 viewBox 会留下未使用的水平空间，或有意义的参与者标签无法放入固定框中，则设为 "spread"；在尝试 "spread" 之前，不要缩短语义标签。
• 组件类型为 frontend、backend、database、cloud、security、messagebus 和 external；变体为 default、emphasis、security 和 dashed。
• 关系标签是语义数据。发生碰撞时，应移动标签、调整路径或间距，然后在保留含义的前提下缩短措辞。只有当措辞已完全由两个端点隐含，且不包含协议、操作、方向、同步／异步行为或跨边界机制时，才可省略。保留所有有意义的标签；删除标签不属于几何修复。如果某个关系起初没有标签，是因为其端点已完全表达其含义，则应说明措辞冗余的原因；这是语义创作选择，不是几何修复。
• 默认省略 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 及字节数。这是确定性产物证据；它不会在浏览器中测试 Viewer。

交付后，在不修改或重新渲染可信 HTML 的前提下，收集有限的桌面端证据：

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

visual-check 会针对确切交付的 HTML 收集自动化浏览器证据，不会修改或重新渲染它。其机器可读测量结果和截图不能证明感知层面的精细度。请遵循 references/delivery-contract.md，了解规范回执字段、覆盖范围、辅助文件、退出行为及补充人工记录要求。

请将以下三项结论分开：deliver 证明确定性产物检查，visual-check 证明真实浏览器中的有限行为，而感知层面的视觉审查需要实际的人类或具备图像能力的审查者。请分别报告浏览器证据和感知审查结果。未经约束地看一眼只能支持感知审查；记录补充人工浏览器操作或处理环境故障时，请遵循规范交付契约。

只有用户希望立即进行本地预览时，才添加 --open。对于正在进行的桌面端创作循环，可使用以下可选命令：

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

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

可选 Viewer 功能

生成的 HTML 已包含主题切换、平移/缩放、搜索、聚焦、关系追踪、语义视图、演示和如实导出功能。这些都是读者功能，不属于额外的创作工作。meta.animation: "trace" 为可选功能；meta.views 也是可选项，最多应包含五个精选章节。

只有用户明确要求 Share Cards、Route/Reach cards、动态效果、引导式故事、深层链接、演示、搜索/聚焦或其他 Viewer Runtime 功能时，才阅读 references/viewer-runtime.md。

设置和回退方案

无需在技能包内安装任何内容。使用以下命令进行验证：

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

无法使用 Shell 时，将架构 SVG 手动放入 assets/template.html，使用 CSS 语义类而非内联颜色，并遵循 references/delivery-contract.md 中的视觉审查契约。

输出

返回已检查的 HTML 路径、图表类型、验证摘要、规范/产物回执、浏览器证据状态，以及如实的视觉审查状态。命令退出码非零时不得声称成功；未实际进行视觉检查时不得声称已检查视觉效果。