Back to Details

diagram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

diagram — vẽ đúng bằng máy, không để model bịa hình

diagram — 用机器准确绘制，禁止模型自行编造图形

Nguyên tắc trung tâm, mượn của 
archify
và giữ nguyên vì nó đúng: model KHÔNG vẽ. Model chỉ điền logic vào một tờ khai có schema (có những khối nào, khối A nối khối B ra sao). Việc dựng hình là của code tất định. Vẽ xong, máy tự soi lại bố cục; hỏng thì giữ nguyên bản tốt trước đó và nói rõ chỗ sai, tuyệt đối không nhả ra một hình rác.
Đó cũng là lý do skill này tồn tại thay vì để model tự vẽ SVG: một cái hình sai trông vẫn "có vẻ được", nên lỗi bố cục là loại lỗi đi lọt xa nhất.
核心原则借鉴自
archify
，因其合理性予以保留：model 不负责绘图。 Model 仅需向带有 schema 的表单中填入逻辑（包含哪些模块、模块A与模块B的连接方式等）。 图形生成由确定性代码完成。绘制完成后，机器会自动检查布局；若生成失败，则保留上一个可用版本并明确说明错误位置，绝对不输出劣质图形。
这也是该技能存在的意义，而非让 model 自行绘制 SVG：错误的图形往往看起来“还不错”，因此布局错误是最容易漏过的问题类型。

Chọn nhánh trước khi làm bất cứ gì

开始任何操作前先选择分支

Bạn đang thể hiện cái gìNhánhEngine
Quan hệ / luồng / trình tự giữa các thành phần (hộp + mũi tên)Sơ đồ
archify
Số liệu — so sánh, phân bố, xu hướng, tỉ trọngBiểu đồ
dataviz
+ kỷ luật lieflat dưới đây
Một màn hình sản phẩmkhông phải việc ở đây
hallmark
Không chắc? Hỏi: "cái tôi vẽ có TRỤC SỐ không?" Có → biểu đồ. Không → sơ đồ.
你要展示的内容分支引擎
组件间的关系/流程/时序（方框+箭头）示意图
archify
数据——对比、分布、趋势、占比图表
dataviz
+ 下文的 lieflat 规范
产品界面不属于此处范畴
hallmark
不确定？问问自己：“我要画的东西有数值轴吗？” 有 → 图表。没有 → 示意图。

Nhánh SƠ ĐỒ — qua 
archify

示意图分支 — 通过 
archify
实现

Engine ngoài, KÉO NGOÀI theo 
[[adapt-modes]]
: ta không viết lại, chỉ ghim + gọi. Cài: 
npx skills add Rheinmir/archify -g -s archify
(đích thật là 
~/.agents/skills/archify
). Đây là fork của 
tt-a1i/archify
: thêm preset thứ 5 
macos
(liquid glass + Roboto) và đặt làm mặc định — bỏ trống 
meta.visual_preset
là ra đúng theme của nhà, không phải áp thêm bước nào. Nhánh vá 
macos-roboto
là nhánh MẶC ĐỊNH của fork, nên không cần ghim ref.
Hai cái bẫy đã trả giá, đừng lặp lại:
  • Không có cờ 
    --ref
    .     Và 
    owner/repo@nhánh
    KHÔNG ghim được nhánh lúc cài: CLI in ra 
    Source: …git @macos-roboto
    nhưng vẫn cài nhánh mặc định, đồng thời hiểu phần sau 
    @
    là TÊN SKILL nên báo 
    No matching skills found
    . Đó là lý do pin bằng default-branch, không bằng cú pháp.
  • -l
    không thay được cài thật.     
    add … -l
    báo 
    Found 1 skill
    xanh trong khi lệnh cài thật vẫn hỏng. Kiểm đường cài phải cài thật rồi vẽ một sơ đồ, xem 
    data-preset
    ra gì.
Upstream ra bản mới thì rebase nhánh, đừng cài đè bằng 
tt-a1i/archify
.
Gọi bằng ngôn ngữ tự nhiên trong chat — không có prefix lệnh:
text
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.
Nói rõ LOẠI thì khỏi phải đoán — 
architecture
· 
workflow
· 
sequence
· 
dataflow
· 
lifecycle
. Dán Mermaid có sẵn vào cũng được, nó vẽ lại cho đẹp.
Ba điều phải biết trước khi gọi, đã kiểm chứng bằng cách chạy thật:
  1. Package đặt 
    "private": true
    — không có trên npm. 
    npx archify
    không chạy. Mọi lệnh shell đều là 
    node ~/.agents/skills/archify/bin/archify.mjs …
    .
  2. Mã thoát không theo quy ước 0/1: 
    2
    vừa là lỗi cách dùng (lệnh lạ, cờ lạ, kiểu sơ đồ lạ) vừa là "visual-check bỏ qua vì không có Chrome". 
    1
    mới là thất bại thật của validate/render/deliver. Gọi trong CI phải rẽ nhánh có chủ đích.
  3. Sau một 
    deliver
    ĐỎ, đừng đi soi file đích — nó vẫn là bản tốt CŨ, không phải bản vừa hỏng. Đây là hệ quả trực tiếp của giao-nguyên-tử, không phải lỗi.
Riêng 
lifecycle
, ba luật nằm trong code chứ không nằm trong schema — đo 10/09/2026, đã vá ở fork nên bản cài mới mới có:
  • Tên lane là hợp đồng. 
    main
    → dải trên, 
    terminal
     → dải dưới (Outcomes), mọi id khác dồn chung dải giữa. Đặt tên khác (
    outcome
    , 
    recover
    , …) là rơi vào dải giữa và đè lên nhau — đây là chỗ đã đốt 4 vòng bố cục.
  • Hai sàn chiều cao khác nhau. Không dùng dải terminal → 
    viewBox[1] ≥ 510
    ; có dùng → 
    ≥ 630
    . Trước bản vá cả hai đều báo 566, nên khai 
    terminal
    ở 566 là rơi vào vòng lặp "State exceeds the vertical lifecycle area" không lối ra.
  • Rail chính KHÔNG tự thành quan hệ. Thứ tự 
    step
    chỉ vẽ đường; muốn Route Probe / passport / trace thấy được thì phải khai transition thật (bỏ nhãn nếu khe hẹp). Bấm một node rồi đọc Semantic Passport: thấy 
    No connected relationships
    là sơ đồ rỗng ruột dù validate/visual-check đều xanh.
Sơ đồ kiến trúc cần bám mã thật thì khai 
sources[]
(path + khoảng dòng) + 
meta.repository
  • --repo-root
    . Cổng đó fail-closed: revision phải là SHA đủ 40 ký tự, 
    --repo-root
    phải là top-level checkout có 
    origin
    khớp. Neo sai thì nó từ chối vẽ.
外部引擎，按照
[[adapt-modes]]
的规则外部引入：我们不重写代码，仅固定版本并调用。 安装命令：
npx skills add Rheinmir/archify -g -s archify
（实际路径为
~/.agents/skills/archify
）。 这是
tt-a1i/archify
的fork版本：新增了第5个预设
macos
（液态玻璃效果 + Roboto字体），并设为默认值——留空
meta.visual_preset
即可使用默认主题，无需额外步骤。
macos-roboto
修复分支是该fork的默认分支，因此无需固定ref。
两个已经踩过的坑，请勿重复：
  • 没有
    --ref
    参数。     并且
    owner/repo@分支
    的格式无法在安装时固定分支：CLI会输出
    Source: …git @macos-roboto
    ，但实际仍安装默认分支，同时会将
    @
    后的内容识别为技能名称，因此报错
    No matching skills found
    。这就是为什么要通过默认分支来固定版本，而非通过语法格式。
  • -l
    参数无法验证实际安装结果。     
    add … -l
    会显示绿色的
    Found 1 skill
    ，但实际安装命令可能仍然失败。要验证安装路径，必须实际安装后绘制一张示意图，查看
    data-preset
    的输出值。
上游发布新版本时，对分支进行rebase即可，不要用
tt-a1i/archify
覆盖安装。
在聊天中使用自然语言调用——无需命令前缀：
text
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.
明确说明类型就无需猜测——
architecture
（架构图）· 
workflow
（流程图）· 
sequence
（时序图）· 
dataflow
（数据流图）· 
lifecycle
（生命周期图）。直接粘贴已有的Mermaid代码也可以，它会重新绘制得更美观。
调用前必须了解的三件事，已通过实际运行验证：
  1. 包设置了
    "private": true
    ——npm上没有。
    npx archify
    无法运行。所有shell命令都需使用
    node ~/.agents/skills/archify/bin/archify.mjs …
    的格式。
  2. 退出码不遵循0/1惯例：
    2
    既表示使用错误（命令未知、参数未知、示意图类型未知），也表示“因无Chrome而跳过视觉检查”。
    1
    才是验证/渲染/交付的真正失败。在CI中调用时必须主动进行分支判断。
  3. 当
    deliver
    失败（红色状态）后，不要去查看目标文件——它仍然是之前的可用版本，而非刚生成的失败版本。这是原子提交原则的直接结果，并非bug。
关于
lifecycle
类型，有三条规则写在代码里而非schema中——截至2026年9月10日，已在fork版本中修复，因此仅新安装的版本包含：
  • 泳道名称是约定好的。 
    main
    → 上方泳道，
    terminal
     → 下方泳道（结果层），其他所有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
    ，说明示意图虽然验证/视觉检查都通过，但实际没有定义关系。
如果架构图需要关联真实代码，需声明
sources[]
（路径 + 行号范围）+ 
meta.repository
+ 
--repo-root
。该接口fail-closed：版本号必须是完整的40位SHA，
--repo-root
必须是带有匹配
origin
的顶层检出目录。锚点错误时会拒绝绘制。

Nhánh BIỂU ĐỒ — 
dataviz
+ kỷ luật lieflat-charts

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

Nạp skill 
dataviz
trước khi viết dòng code biểu đồ đầu tiên, ở mọi môi trường (HTML, SVG, matplotlib/plotly/d3/Recharts, hay ảnh PNG sẽ render). Cộng năm luật hấp thụ từ 
lieflat-charts
, tất cả đứng trên thẩm mỹ:
  1. Từ chối là hành vi ĐÚNG, không phải bướng. Cắt trục (broken axis) → từ chối, đưa ba cách trung thực. Glow / glassmorphism / 3-D trên data mark → từ chối. Hơn sáu category mà vẫn đòi màu → lùi về thang mono. Dữ liệu quá mỏng cho hình đã chọn (ba node mà đòi force graph) → hạ cấp và nói vì sao.
  2. Số hình = số KẾT LUẬN độc lập, không phải số cột dữ liệu. Một câu hỏi → một hình; cả một bài viết → bốn tới sáu; trần sáu hình một trang rồi tách trang.
  3. Tiêu đề là KẾT LUẬN, không phải tên kiểu hình. "Churn tăng gấp đôi sau bản tháng Tư", không phải "Biểu đồ cột churn".
  4. Trưng bằng chứng chọn hình. Nêu ít nhất ba ứng viên và lý do loại từng cái TRƯỚC khi vẽ. "Tôi dùng biểu đồ cột" mà không có ứng viên nào bị loại nghĩa là chưa hề chọn.
  5. Render tất định. Cấm 
    Math.random()
    trong biểu đồ — refresh hai lần phải ra đúng một hình. Cả file một hệ màu; trộn hai hệ là làm lại.
在任何环境（HTML、SVG、matplotlib/plotly/d3/Recharts，或是要渲染的PNG图片）中，在编写第一行图表代码之前，先加载
dataviz
技能。另外还有从
lieflat-charts
吸收的五条规则，全部基于审美原则：
  1. 拒绝是正确的行为，而非固执。 截断坐标轴（broken axis）→ 拒绝，并提供三种诚实的替代方案。数据标记上使用发光/玻璃拟态/3D效果 → 拒绝。超过六个分类仍要求使用不同颜色 → 退化为单色阶。所选图表类型对应的数据量过少（比如只有三个节点却要求用力导向图）→ 降级使用更简单的类型并说明原因。
  2. 图表数量 = 独立结论的数量，而非数据列的数量。一个问题 → 一张图；一篇文章 → 四到六张；每页最多六张图，超出则分页。
  3. 标题即结论，而非图表类型名称。比如“Churn在4月版本发布后翻倍”，而非“用户流失率柱状图”。
  4. 图表选择要有依据。 绘制前至少列出三个候选类型，并说明排除每个类型的原因。只说“我用柱状图”却没有排除任何候选，说明根本没有经过选择。
  5. 渲染必须是确定性的。 图表中禁止使用
    Math.random()
    ——刷新两次必须得到完全相同的图形。整个文件使用同一套配色体系；混用两套体系必须重做。

Sau khi có file HTML — chạy cổng của NHÀ

得到HTML文件后 — 运行内部校验工具

Engine ngoài gác bố cục của nó; cổng dưới đây gác thứ nó không biết: quy ước của repo này.
bash
python3 fdk/tools/frontend-antipattern.py <file.html>     # 0 sạch · 1 FAIL · 2 chỉ WARN
Nó bắt, tất định và 0 token:
  • Hình học — hai ô đè nhau một phần, ô nằm ngoài 
    viewBox
    , chữ tràn ra ngoài ô chứa nó.
  • Accessibility + tự chứa — thiếu 
    role="img"
    , thiếu 
    <title>
    hoặc 
    <title>
    không phải con đầu, 
    <title>
    /
    <desc>
    rỗng, và tham chiếu remote 
    http
     (trang tự-chứa mà mở offline lại khuyết hình).
  • Neo bằng chứng — node khai 
    data-src="path"
    / 
    data-src="path:line"
    mà đường dẫn không resolve, hoặc số dòng vượt độ dài file. Fail-closed: không khai thì không bị hỏi, đã khai thì phải đúng.
Cần bằng chứng trình duyệt thật (không phải chỉ phân tích tĩnh):
bash
python3 fdk/tools/visual-receipt.py <file.html>           # 0 pass · 1 fail · 2 BỎ QUA
Ra bốn ảnh (1440×900 và 2048×1320, mỗi cỡ sáng + tối), một biên lai JSON, và một contact sheet để người chấm. Nó kiểm trong trình duyệt thật ba thứ regex không làm được: tràn ngang, lỗi console, và mọi request thoát ra ngoài — tức tính tự-chứa đo bằng hành vi chứ không bằng chuỗi trong file.
外部引擎负责自身的布局校验；以下工具负责校验引擎无法识别的内容：本仓库的规范。
bash
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"
    ，但路径无法解析，或行号超出文件长度。fail-closed：未声明不会被检查，一旦声明就必须正确。
需要真实浏览器验证（而非仅静态分析）：
bash
python3 fdk/tools/visual-receipt.py <file.html>           # 0 pass · 1 fail · 2 BỎ QUA
会输出四张图片（1440×900和2048×1320两种分辨率，每种分辨率各有亮/暗模式）、一份JSON格式的回执，以及一张contact sheet供人工审核。它会在真实浏览器中检查三件正则表达式无法做到的事：横向溢出、控制台错误，以及所有对外请求——即自包含性通过行为而非文件内的字符串来衡量。

Rules

规则

  • Model không vẽ. Model điền tờ khai; code dựng hình. Thấy mình đang gõ toạ độ SVG bằng tay cho một hình mới là đã đi sai nhánh.
  • Không nhả hình rác. Bản mới không qua cổng thì giữ bản tốt cũ, báo rõ chỗ sai. Generator của repo này đã làm đúng vậy (
    _deliver
    trong 
    build-overstack-docs.py
    : render ra file tạm, chạy cổng trên file tạm, xanh mới 
    os.replace
    ).
  • BỎ QUA ≠ SẠCH. Thiếu Chrome, thiếu mạng, thiếu engine → nói "bỏ qua", tuyệt đối không báo "đạt". Một cổng nói dối mà vẫn xanh tệ hơn không có cổng.
  • Đừng bê ràng buộc phong cách của engine ngoài về làm luật nhà. Đo trước: archify đòi mũi tên thẳng ngang/dọc, nhưng sơ đồ của repo này cố ý toả nan quạt (6·4·10 đường chéo hợp lệ ở ba sơ đồ) — nên luật đó bị loại khi hấp thụ, còn ba luật hình học kia thì nhận.
  • Sơ đồ trong tài liệu tự sinh thì dùng generator, đừng gọi agent. Mỗi sơ đồ vẽ qua chat tốn một lượt agent, mãi mãi; code sinh SVG tốn 0. Chỉ dùng nhánh chat cho hình mới hoặc hình dùng một lần.
  • Model 不绘图。 Model 填写表单；代码生成图形。如果你发现自己正在手动为新图形输入SVG坐标，说明你走错了分支。
  • 不输出劣质图形。 新版本未通过校验则保留旧的可用版本，并明确说明错误位置。本仓库的生成器就是这样做的（
    build-overstack-docs.py
    中的
    _deliver
    函数：渲染到临时文件，对临时文件运行校验，通过后才执行
    os.replace
    ）。
  • 跳过 ≠ 合格。 缺少Chrome、缺少网络、缺少引擎 → 说明“跳过”，绝对不要报告“通过”。一个会撒谎却仍显示通过的校验工具，比没有校验工具更糟糕。
  • 不要把外部引擎的风格约束当作内部规则。 比如：archify要求箭头只能水平/垂直，但本仓库的示意图特意使用扇形发散布局（三张示意图中共有6·4·10条合法斜线）——因此这条规则在吸收时被剔除，而另外三条几何规则被保留。
  • 自动生成的文档中的示意图使用生成器，不要调用agent。 每张通过聊天绘制的示意图都会永久消耗一次agent调用额度；代码生成SVG的成本为0。仅对新图形或一次性图形使用聊天分支。

Origin

来源

  • Nhánh sơ đồ: 
    Rheinmir/archify
    @ 
    macos-roboto
    (KÉO NGOÀI — fork của 
    tt-a1i/archify
    ; engine sống ngoài, ta ghim + gọi). Xem 
    sources/draft/080926-archify-fork-pin.md
    .
  • Kỷ luật biểu đồ: 
    larashero3-dotcom/lieflat-charts
    (HÒA TAN — chỉ lấy luật, không lấy bộ vẽ).
  • Cổng hình học + giao nguyên tử: hấp thụ từ archify vào 
    fdk/tools/frontend-antipattern.py
    và 
    fdk/tools/build-overstack-docs.py
    , xem 
    wiki/sources/draft/040926-absorb-round.md
    .
  • 示意图分支：
    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
    。