diagram

diagram — 用机器准确绘制，不让模型凭空编造图形

核心原则借鉴自 archify，并保留至今，因为它是正确的：模型不绘图。 模型只需填写带有 schema 的表单（有哪些节点、节点 A 如何连接节点 B）。 绘图由确定性代码完成。绘制完成后，机器会自动检查布局；如果失败，就保留之前的 良好版本并明确说明错误所在，绝不输出一张垃圾图。

这也是这个 skill 存在的原因，而不是让模型自行绘制 SVG：一张错误的图看起来仍然 “像那么回事”，因此布局错误是最容易漏检的错误类型。

内容

目的和背景

• 目的： 用确定性代码绘制示意图（关系／流程）和图表（数据）——模型只填写带 schema 的表单，机器负责绘图并自动检查布局；如果失败，就保留之前的良好版本并明确说明错误所在。
• 触发条件（何时使用）： 用户说“画示意图”“画图表”“画流程”“架构图”“处理流程”“flow”“graph”“chart”“可视化”“比较两个流程”“draw a diagram”“sequence diagram”“state machine”“dependency graph”“plot”“dashboard”“convert Mermaid”“diff two flows”（完整列表见 description）。
• 非目标： 不用于 UI／落地页屏幕——那是 hallmark 的用途。不要手动绘制新图形的 SVG 坐标。不要替换自动生成文档中示意图所用的 generator。

心智模型

查看者的问题 → 有数字轴吗？→ 示意图（语法 → archify）或图表（dataviz + 5 条 lieflat 规则）→ HTML 文件 → 质检关卡（frontend-antipattern，可选 visual-receipt）→ 原子交付（新版本通过才替换，失败则保留旧版本）。模型填写逻辑；代码绘图；确定性关卡决定是否通过。

输入和输出约定

	字段	必填？	含义
输入	流程／关系或数据描述	是	查看者需要回答的问题
输入	示意图类型	否	architecture、workflow、sequence、dataflow、lifecycle；留空则由 engine 猜测
输入	现有 Mermaid	否	粘贴进去，由 archify 重新绘制
输入	真实代码锚点	否	sources[] + meta.repository + --repo-root（SHA 必须为 40 个字符）
输出	自包含 HTML 文件	是	示意图或图表，通过质检关卡
输出	关卡判定结果	是	frontend-antipattern.py 的 rc（0 表示干净，1 表示 FAIL，2 表示仅 WARN）；可选的 visual-receipt.py（0 表示通过，1 表示失败，2 表示跳过）+ 4 张图片 + JSON 收据 + 联系表

规则和能力

• RULE-01（必须）：模型不绘图。 模型填写表单；代码负责绘图。如果你发现自己正在手动输入新图形的 SVG 坐标，那就走错路了。
• RULE-02（必须）：不输出垃圾图。 新版本未通过关卡，就保留旧的良好版本并明确说明错误所在。这个仓库的 generator 已经正确实现了这一点（build-overstack-docs.py 中的 _deliver：先渲染到临时文件，在临时文件上运行关卡，通过后才执行 os.replace）。
• RULE-03（必须）：跳过 ≠ 通过。 缺少 Chrome、网络或 engine 时，要说“跳过”，绝不能报告“通过”。一个说谎却显示通过的关卡，比没有关卡更糟。
• RULE-04（必须）：不要把外部 engine 的风格约束搬来当作本地规则。 先测量：archify 要求箭头水平或垂直，但这个仓库的示意图有意采用扇形辐射布局（三张示意图中的 6·4·10 条对角线都有效）——因此吸收时剔除了这条规则，同时采纳了另外三条几何规则。
• RULE-05（必须）：自动生成文档中的示意图要用 generator，不要调用 Agent。 每张通过聊天绘制的示意图都会永久消耗一次 Agent 调用；代码生成 SVG 则消耗 0 次。只有新图或一次性图形才走聊天分支。
• 能力：调用确定性示意图 engine 和图表 engine；在 HTML 文件上运行静态零 token 关卡；可选地运行真实浏览器进行截图并测量请求；通过原子交付写入目标文件。

失败边界

• 不清楚是否有数值轴 → 澄清（询问“我画的东西有数值轴吗？”）。
• 要求是产品界面 → 阻止，转交给 hallmark。
• 图表违反规范（截断坐标轴、在数据标记上使用 glow/3-D、数据过于稀疏）→ 拒绝/降级并说明理由，提供诚实的替代方案。
• deliver 显示红色或关卡 FAIL → 失败，目标文件仍保留旧的良好版本；说明错误所在。
• 缺少 Chrome/网络/引擎 → 跳过，绝不报告“通过”（RULE-03）。
• 代码锚点错误（SHA 不足 40 个字符、origin 不匹配）→ 阻止（失败关闭）。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	判断	要求	选择分支：有数值轴 → 图表；没有 → 示意图；界面 → hallmark	分支	UI → 阻止；含糊 → 澄清
W02	判断	观看者的问题	示意图：选择语法（拓扑、序列、流程、状态、层级、矩阵）；一个问题对应一张图	archify 类型	两个问题 → 两张图
W03	执行	说明	示意图：用自然语言调用 archify，或运行 node ~/.agents/skills/archify/bin/archify.mjs（B01）	HTML 文件	rc 1 → 失败，保留旧版本
W04	执行	数据	图表：在第一行代码之前加载 dataviz + 5 条 lieflat 规则（B02）	HTML 文件	违反规范 → 拒绝/降级
W05	确定性	HTML 文件	本地关卡 python3 fdk/tools/frontend-antipattern.py <file.html>	rc 0	1 → 修改说明，重复 W03/W04
W06	确定性	HTML 文件	可选的浏览器证据 python3 fdk/tools/visual-receipt.py <file.html>（B03）	截图 + 回执	2 → 报告跳过，不报告通过
W07	执行	已通过关卡的文件	原子交付：新版本为绿色时替换目标文件；红色时保留旧的良好版本 + 报告错误所在	目标文件	—

各步骤的详细说明（W01–W07 的真实依据）：

开始前先选择分支

你要呈现什么	分支	引擎
组件之间的关系/流向/顺序（方框 + 箭头）	示意图	archify
数据——比较、分布、趋势、占比	图表	dataviz + 下方的 lieflat 规范
产品界面	不属于此处的工作	hallmark

不确定？问：“我画的东西有数值轴吗？”有 → 图表。没有 → 示意图。

在示意图分支中——选择引擎前先选对语法

先问：观看者需要回答什么问题？——问题决定语法，语法 才决定要画成什么样（从 plannotator/effective-html 融合而来，参见 [[design-foundation]]）：

观看者的问题	语法	archify 类型示例
有什么，彼此如何连接？	拓扑 / 系统示意图	architecture
随时间发生了什么？	序列 / 时间线	sequence
决策/变化如何发生？	流程图	workflow
这个东西如何改变状态？	状态图	lifecycle
什么包含/拥有了什么？	层级 / 包含关系	architecture（嵌套分支）
各方案如何相互比较？	矩阵 / 对齐比较	表格，无需 archify
数量有多少 / 频率多高 / 速度多快？	定量图表	→ 下方的图表分支

不要把两个问题塞进一张图。两者都需要 → 画两张图（或使用可切换图层），不要画一张过载的图。选好语法后，再根据下方对应部分选择引擎（HTML/CSS、SVG、Canvas、WebGL）。

图表分支 — 通过 archify

外部引擎，按 [[adapt-modes]] 的要求从外部拉取：我们不重写，只固定并调用。 安装：npx skills add Rheinmir/archify -g -s archify（实际目标是 ~/.agents/skills/archify）。 这是 tt-a1i/archify 的分支版本：新增第 5 个预设 macos（液态玻璃 + Roboto），并将其设为 默认值——留空 meta.visual_preset 就会使用自家的主题，无需额外步骤。macos-roboto 补丁分支是此分支版本的默认分支，因此无需固定 ref。

两个已经付出代价的陷阱，别再重蹈覆辙：

• 没有 --ref 标志。 而且 owner/repo@branch 无法在安装时固定分支：CLI 会打印 Source: …git @macos-roboto，但仍然安装默认分支，同时把 @ 后面的部分当作 技能名称，因此报错 No matching skills found。这就是为什么要通过默认分支固定版本，而不是用语法。
• -l 不能替代实际安装。 add … -l 会用绿色提示 Found 1 skill，但实际安装命令仍会失败。验证安装路径时，必须真正安装，然后绘制一张图，查看 data-preset 的值。

上游发布新版本时，rebase 此分支，别用 tt-a1i/archify 覆盖安装。

在聊天中用自然语言调用——没有命令前缀：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

明确说明类型，就不用猜了——architecture · workflow · sequence · dataflow · lifecycle。也可以粘贴现有的 Mermaid，让它重新绘制得更美观。

调用前必须了解的三件事，均已通过实际运行验证：

1. Package 设置了 "private": true——不在 npm 上。npx archify 无法运行。所有 shell 命令都必须用 node ~/.agents/skills/archify/bin/archify.mjs …。
2. 退出码不遵循 0/1 惯例：2 既表示用法错误（未知命令、未知标志、未知图表类型），也表示 “visual-check 因没有 Chrome 而跳过”。只有 1 才表示 validate/render/deliver 真正失败。在 CI 中调用时必须明确分支处理。
3. deliver 显示红色失败后，别去检查目标文件——它仍然是旧的正常版本，不是刚刚失败的版本。这是原子交付的直接结果，不是 bug。

lifecycle 特有的三条规则写在代码里，而非 schema 中——于 2026/09/10 测得，已在此分支版本中修复，因此只有新安装版本才包含修复：

• 泳道名称就是约定。 main → 上方带区，terminal → 下方带区（Outcomes），其他所有 ID 都会挤进中间带区。使用其他名称（outcome、recover 等）会落入中间带区并彼此重叠——这是已经耗费 4 轮布局调整的问题。
• 高度有两个不同的下限。 不使用 terminal 带区 → viewBox[1] ≥ 510；使用时 → ≥ 630。修复前两种情况都报告 566，所以在 566 时声明 terminal 会陷入无法解决的 “State exceeds the vertical lifecycle area” 循环。
• 主干线不会自动成为关系。 step 顺序只会绘制线条；若想让 Route Probe / passport / trace 能识别，必须声明真实的 transition（间距狭窄时可省略标签）。点击一个 节点并读取 Semantic Passport：如果看到 No connected relationships，就说明这张图徒有其表，尽管 validate/visual-check 都显示绿色。

要让架构图对应真实代码，需声明 sources[]（路径 + 行号范围）+ meta.repository

• --repo-root。该入口采用失败即关闭策略：revision 必须是完整的 40 位 SHA，--repo-root 必须是带有匹配 origin 的顶层 checkout。锚点不正确时，它会拒绝绘图。

图表分支 — dataviz + lieflat-charts 规范

在编写第一行图表代码之前，先加载 dataviz 技能，适用于所有环境（HTML、 SVG、matplotlib/plotly/d3/Recharts，或将要渲染的 PNG 图片）。再加上从 lieflat-charts 吸收的五条规则，所有规则都优先于美观：

1. 拒绝是正确的行为，不是固执。 截断坐标轴（broken axis）→ 拒绝，并给出三种 诚实的做法。数据标记上使用 Glow / glassmorphism / 3-D → 拒绝。超过六个类别 仍要求用颜色 → 改用单色阶。数据过于稀疏，不适合所选图形（三个节点却要求力导 向图）→ 降级并说明原因。
2. 图形数量 = 独立结论的数量，而非数据列的数量。一个问题 → 一张图；一篇文章 → 四到六张图；每页最多六张图，然后拆分页面。
3. 标题是结论，不是图形类型名称。“四月版本发布后流失率翻倍”，而不是“流失 率柱状图”。
4. 展示选择图形的证据。 作图前至少列出三个候选方案，并说明逐一排除的理由。 只说“我使用柱状图”却没有排除任何候选方案，说明根本没有做出选择。
5. 确定性渲染。 图表中禁止使用 Math.random()——刷新两次必须得到同一张图。 整个文件使用同一套配色；混用两套就得重做。

生成 HTML 文件后——运行本地门禁

外部引擎负责检查它所能检查的布局；下面的门禁负责检查它不了解的内容：本仓库的约定。

python3 fdk/tools/frontend-antipattern.py <file.html>     # 0 sạch · 1 FAIL · 2 chỉ WARN

它会捕获以下问题，结果确定且不消耗 token：

• 几何问题 — 两个矩形部分重叠、矩形位于 viewBox 外、文字溢出其所在矩形。
• 无障碍 + 自包含 — 缺少 role="img"、缺少 <title> 或 <title> 不是第一个子 元素、<title>/<desc> 为空，以及远程 http 引用（自包含页面离线打开时 图片缺失）。
• 证据锚点 — 节点声明了 data-src="path" / data-src="path:line"，但路径无法 解析，或行号超出文件长度。默认拒绝：未声明就不检查，声明了就必须正确。

需要真实浏览器证据（不只是静态分析）：

python3 fdk/tools/visual-receipt.py <file.html>           # 0 pass · 1 fail · 2 BỎ QUA

生成四张图片（1440×900 和 2048×1320，每种尺寸各有浅色 + 深色版本）、一份 JSON 收据，以及一张供人工评审的联系表。它会在真实浏览器中检查正则表达式做不到的 三件事：横向溢出、控制台错误，以及所有发往外部的请求——也就是说，根据实际 行为而非文件中的字符串来衡量自包含性。

分支

ID	类型	条件	行为	跳过 / 失败	汇合点
B01	conditional_required	没有数值轴（关系、流向、顺序）	通过 archify 绘制示意图分支（拉取外部仓库，fork Rheinmir/archify）	未安装 archify → 安装 npx skills add Rheinmir/archify -g -s archify；因缺少 Chrome 而 exit 2 → 跳过，不算通过	W05
B02	conditional_required	有数值轴	通过 dataviz + 5 条 lieflat 规则绘制图表分支	要求违反规则 → 拒绝，并给出三种诚实的做法	W05
B03	capability_optional	需要真实浏览器证据且有 Chrome	visual-receipt.py：4 张图片、JSON 收据、供人工评审的联系表	没有 Chrome → rc 2，跳过	W07
B04	user_optional	架构图必须对应真实代码	声明 sources[] + meta.repository + --repo-root	锚点错误 → 引擎拒绝绘图（默认拒绝）	W03
B05	conditional_required	示意图位于自动生成的文档中	使用仓库的生成器（例如 build-overstack-docs.py），不要调用 agent	新图或一次性使用 → 聊天分支	W05

验证与停止

确定性检查：frontend-antipattern.py 的 rc（几何、无障碍 + 自包含、data-src 锚点） 和 visual-receipt.py 的 rc（横向溢出、控制台错误、外发请求）；对于 archify，rc 1 表示实际失败，rc 2 则表示用法错误或 visual-check 被跳过，因此必须有意选择其他 分支。需要人工检查：visual-receipt 的联系表；对于 lifecycle，点击节点并阅读 Semantic Passport，看到 No connected relationships 就说明内容空洞，即使门禁通过也 一样。门禁通过且目标文件已替换后停止；若未通过，则保留旧版本并报告。

示例

• 正向：“绘制 Browser -> API -> Redis cache -> PostgreSQL fallback 的流程” → 不截断坐标轴 → 选择「图示」，符合拓扑语法 → Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. → frontend-antipattern.py 返回码 0 → 交付 macos 预设的 HTML 文件。
• 边界/失败：“绘制收入图表，截断坐标轴以显示大幅增长” → 选择「图表」分支，拒绝断轴（lieflat 规则 1），提供三种诚实的做法；标题应是结论，而不是“收入柱状图”。
• **边界：**生命周期将泳道设为 outcome → 中间带重叠 → 改为 terminal，并设置 viewBox[1] ≥ 630；如果 deliver 仍显示红色，那么目标文件是之前的正常版本，不要把它当作新版本检查。

来源

• 图示分支：Rheinmir/archify @ macos-roboto（外部拉取——tt-a1i/archify 的 fork； 引擎在外部运行，我们固定其版本并调用）。参见 sources/draft/080926-archify-fork-pin.md。
• 图表规范：larashero3-dotcom/lieflat-charts（吸收——只采纳规则，不采用绘图工具集）。
• 几何检查与原子交付：将 archify 吸收到 fdk/tools/frontend-antipattern.py 和 fdk/tools/build-overstack-docs.py 中，参见 wiki/sources/draft/040926-absorb-round.md。