Archify 使用方案 · 技术图生成 Skill 全玩法实测

组合心得（实测）

• 演示汇报 → signal-flow + trace 动画（流程图有电流感）
• 正式文档 → editorial 静态（配图气质最好）
• 技术评审 → classic / blueprint 静态（不抢内容）
• 动画是显式开启的：{ "meta": { "animation": "trace" } }，不设置就是纯静态图
• 生成后浏览器里按 S 循环切预设、T 切深浅主题，无需重新生成

方式 A · 对话直出（推荐日常用）

直接对 Agent 说，它会走完整校验流程。要点：说清范围（8-12 个组件）、一条主路径、外部依赖、边界，辅助细节让它放说明卡片。

使用 archify 画出登录流程：Browser → Web App → API → JWT 校验 →
Redis Session 查询 → PostgreSQL 回源。缓存未命中作为次要路径。

方式 B · 手写 JSON + CLI（可控性最强）

cd ~/.qoder/skills/archify
node bin/archify.mjs doctor                     # 环境自检
node bin/archify.mjs validate workflow my.json --quality showcase --json   # 每次改完必跑
node bin/archify.mjs deliver workflow my.json out.html --quality showcase  # 通过才交付
node bin/archify.mjs preview workflow my.json out.html --quality showcase  # 实时预览

方式 C · Mermaid 转换

把现有 Mermaid 贴给 Agent：「用 archify 把这个 Mermaid 转成正式图」。映射：flowchart → workflow/architecture；sequenceDiagram → sequence；stateDiagram → lifecycle。

对比两份架构快照，机器精确输出变更

node bin/archify.mjs compare architecture base.json head.json delta.html --json

实测：给工具集架构加了 EdgeOne Pages 发布通道后对比，机器回执：

{ "components": {"added": 1}, "connections": {"added": 1, "changed": 1} }

生成的 delta 页有 Before / Delta / After / Review 四个视图，可逐条点选变更。适合：方案评审前后对比、架构变更留档。

布局与标签

1. 中文标签宽度：CJK 字符比英文宽，节点主标签放短中文（≤5 字），长英文文件名放 sublabel。实测 fetch_credits.py 做主标签直接超框被拦。
2. 同泳道相邻列勿放两个节点（workflow）：会触发 8px 间距 / 28px 最短边校验。解法：主路径在泳道间「交错走位」（zigzag 布局一次通过）。
3. lifecycle 回环布线：把失败态摆到来源决策态的正下方列（垂直 straight 直达），长返回线走底部大外环 via；外环 y 坐标别撞图例（legend-clearance 会拦），via 首点 x 要对齐节点真实出口坐标。
4. 次要连线能删就删：一条斜穿的低价值连线制造了 4 个交叉错误，删掉后一次通过。加 via/labelAt 前先考虑删边。

工程与验证

5. 别整图重写：validate 的 diagnostics 给了准确 subject + supportedFixes，只改被点名的对象。修复超过 2-3 轮无进展就换布局思路。
6. viewBox 加宽不一定解决拥挤：减内容密度比加画布有效。
7. zsh 批量脚本：for + set -- 不分词，写独立 shell 函数脚本更稳。
8. 浏览器验证：成品含动画时截图可能超时，用 evaluate_script 检查 DOM（svg 子元素数、title、控制台）即可完成验证。

四个落地场景

• 调研报告配图：dataflow / architecture 图导出 1200×630 分享卡或 SVG 嵌入报告页（单图约 600KB、Delta 页约 1.7MB）。
• 方案评审：SPEC 实施前后用 Architecture Delta 出对比图，变更留档。
• 交接文档：各模块配一张 architecture 图，比纯文字直观。
• 长期访问：挂 nginx 8080 统一入口（本站即此模式）；临时看图直接 open *.html 即可。