blueprint-figure

蓝图图示

此技能用于绘制一张静态 SVG 图示，说明真实系统中的一种机制。图示使用系统中的真实名称：ID、字段名、方法名、状态码和序列号。图示置于浅色纸面面板上，并使用一组含义固定的少量色调。在屏幕上和印刷品中，即使宽度仅为 640 个单位，也能清晰阅读。Claude、Cursor、Codex、OpenClaw、Hermes 或任何可读取 SKILL.md 的 Agent 都可以使用此技能。配套技能 course-style 包含完整的课程设计令牌。此技能会复制所需令牌，因此可以独立使用。

适用场景

• 课程、README 或手册需要一张图，说明系统各部分如何通信、存储数据或改变状态。
• 你有一份记录、日志、规范或源代码，其中包含真实名称。
• 主题符合下列九种类型之一。

不适用场景

• 图示需要动起来或响应滑块。请使用配套技能 motion-figure。
• 主题是需要展示纵深和控件的实体机器说明图。请使用配套技能 isometric-explainer。
• 数据是包含许多数据点的数值图表。请使用图表工具。
• 你没有各部分的真实名称。请先获取记录或源代码。

方法

1. 先写出论点。用一句不超过 28 个词的句子，说明图示要证明什么。
2. 从下表中选择一种类型。如果两种类型都适用，就画两张图。
3. 从来源中收集真实名称：参与方、字段、方法、代码、序列号。
4. 绘制前先为整组图示编写色调表（参见“颜色”）。
5. 在 640 单位网格上勾勒布局。内容应保持在 x 20 到 x 620 之间。
6. 使用脚本绘制图示。从 templates/figure.mjs 开始。不要手动编辑 SVG。
7. 运行脚本。如果标签过小、过宽或超出图示范围，脚本会停止。
8. 运行 references/checks.md 中的检查。修复所有问题。
9. 将 SVG 渲染为 PNG，并分别以 100% 和 50% 宽度查看。
10. 编写图注：先写加粗的论点，再说明如何阅读图示，最后注明来源。

九种类型

类型	用途
sequence	参与方位于生命线上，时间向下流逝，并为交互编号
structure	展示一条记录、对象或架构的组成
flow	展示数据经过的阶段，以及谁写入、谁读取
comparison	并排展示同一问题的两种答案
timeline	展示沿编号轴排列的轨迹，例如提交序列或时间
tree	展示所有权、包含关系或委派关系
state	展示状态机及其转换
decision	展示故障位置以及每种结果的含义
layers	展示分层堆栈及各层负责的部分

每种类型的布局数值见 references/kinds.md。

图示内容

• 使用真实名称展示真实系统。绝不要绘制“组件 A”之类的通用方框。
• 绝不要绘制统计卡片、进度条或装饰性图标。
• 每张图只表达一个论点。
• 比较主题的两种行为。绝不要拿它与自己项目的早期版本比较。
• 按照记录中实际发生的顺序，为序列中的交互编号。

颜色

十种色调：grey、blue、teal、violet、green、amber、plum、olive、indigo、rose。每种色调都有一个墨色令牌和一个填充令牌。同一组图示中的每种色调都表示相同的含义。

四种含义固定：

色调	固定含义
rose	故障：错误、崩溃、中止、工作丢失
grey	主题之外：宿主、操作者、不在范围内的内容
amber	生命周期：任务、阶段、状态机
teal	持久状态：存储和已提交记录

每组图示只为其余六种色调各分配一种含义，并将表格写在页面或手册前置部分。

每种颜色都写作 var(--m-<token>, <light hex>)，例如 var(--m-rose-ink, #b0344d)。宿主页面提供深色值。README 显示浅色十六进制值。所有浅色和深色值均见 references/grammar.md。

箭头

样式	含义
实线墨色	调用或请求
虚线墨色	回复
实线青绿色	持久写入
虚线琥珀色	状态变化
实线李子色	模型调用或计算
虚线橄榄色	系统外部的影响
点线靛蓝色	流或事件
虚线玫瑰色	失败

• 线宽为 1.2。虚线样式为 5 4。点线样式为 1.5 3.5，端点为圆形。
• 每种色调使用一个箭头标记，id 为 <figure-id>-head-<hue>。
• 箭头末端与目标边框相距 1 个单位。
• 图组中的第一张图（图 0.1）展示该图组使用的每种箭头样式。

边框

• 色调墨色实线边框：普通部分或状态。
• 虚线边框：中断、可选或不存在。
• 双线边框（第二个矩形内缩 3 个单位）：终止状态。
• 斜线填充：时间线条上的等待时间。上面不得放置文字。

易读性规则

• 在 640 单位宽度下，文字至少为 11 个单位。这相当于屏幕上的 11 像素，印刷时约为 8 磅。
• 方框标题为 12.5 号粗体等宽字体。副行使用 11 号衬线字体。箭头标签为 11.5 号。注释使用 11 号衬线字体。
• 每个衬线字体行都要单独指定字体：class="m-serif" 和 font-family="Source Serif 4, Georgia, serif"。这样图在任何页面内嵌显示、作为 README 图片显示或出现在手册中时，外观都一致。
• 眉题为 11 号大写字母，字间距为 1.2，使用墨色弱化色。
• 标签中不得使用省略号。文字不得相互重叠。斜线填充上不得放置文字。线条不得穿过文字。
• 标签放不下时，应将其放在外部并用引导线连接，或放入编号图例。不得缩小字号。
• 每个箭头标签都放在面板颜色的遮挡底块上，并添加 class="m-knock"。
• 遮挡底块应在线条之后、标签之前绘制。
• 遮挡底块会遮住线条，但不算作标签必须放入的方框。
• 放置文字前先测量：等宽字体的宽度为 字符数 × 字号 × 0.6，衬线字体的宽度为 字符数 × 字号 × 0.54。

技术规则

• 根元素：viewBox="0 0 640 H"，H 不得超过 760；设置 role="img" 和 aria-labelledby="<id>-title <id>-desc"。
• 根元素字体和墨色：font-family="JetBrains Mono, ui-monospace, monospace" 和 fill="var(--m-ink, #1a1a1a)"。衬线字体行按上述要求设置自己的 font-family。
• 根元素的直接子元素中必须包含 <title> 和 <desc>，且两者至少为 40 个字符。
• desc 按阅读顺序描述每个部分和每次交互。
• 每个 id 都以图的 id 开头，例如 fig-4-1-head-amber。
• 图的 id 由小写单词和数字组成，并以连字符连接，例如 fig-4-1。
• 只能使用 references/checks.md 中列出的元素和属性。
• 不得使用 style、脚本、事件处理程序、链接或图片。
• transform 只能在 <g> 上使用 translate()。
• 每行文字使用一个 <text> 元素。
• 文件大小不得超过 40 KB，绘制元素不得超过 450 个。

图注

将图注放在 SVG 外的页面中。不得将图注放在 SVG 内。

1. 以粗体写出主张：一个句子，最多 28 个单词，以句号结尾。
2. 说明如何阅读这张图，例如“从上到下阅读。”
3. 注明来源，例如捕获文件。

在手册中，使用围栏代码块声明该图：

```figure
id: fig-4-1
kind: state
title: the task lifecycle
claim: A task ends in one of four terminal states and never leaves one.
caption: Read left to right. Dashed borders are interrupted states. From capture/out/task-states.txt.
```

在课程或 README 中，将 SVG 放入图片标签或内嵌显示，然后在其下方用段落写图注。

将源文件与输出文件放在一起

• 将图形脚本保存在 SVG 旁边，例如 figures/src/fig-4-1.js 和 figures/fig-4-1.svg。
• 每次都从脚本构建 SVG。构建后不得手动编辑 SVG。
• 提交前再次构建，并确认提交的 SVG 与脚本输出一致。

完成前请检查

• 声明是一个句子，且不超过 28 个词。
• 每个标签都是真实的源名称。不能使用“组件 A”。
• 图形使用九种类型之一。
• 玫瑰色表示失败，灰色表示范围外，琥珀色表示生命周期，青绿色表示持久状态。
• 每条箭头都使用八种样式之一，且含义与表格一致。
• viewBox 的宽度为 640，高度不超过 760。
• 包含 role="img"、aria-labelledby、<title> 和至少 40 个字符的 <desc>。
• 每个 id 都以图形 ID 开头。
• 每种颜色都是 var(--m-<token>, <light hex>)，且十六进制值正确。
• 文本字号不低于 11 单位，不在 viewBox 外，不与其他文本重叠，也不被线条穿过。
• 标签中不得有省略号。
• 每条衬线字体文本都具有 font-family 属性，根元素具有墨色 fill，因此图形无需宿主样式表。
• 不得使用 style、脚本、链接、图像，也不得使用 <g> 上 translate() 以外的变换。
• 文件不超过 40 KB。
• PNG 渲染图在 50% 宽度下清晰可读。
• 图注包含加粗声明、阅读顺序和来源。
• 已提交的 SVG 与脚本输出一致。

文件

• references/kinds.md：九种类型各自的布局数值，以及图形 0.1。
• references/grammar.md：浅色和深色令牌、色相含义、箭头笔画、标记、文本大小和度量、形状、可选节拍。
• references/checks.md：每项检查及其测试、允许的元素和属性，以及图注规则。
• templates/figure.mjs：自包含的 Node 脚本，包含一个小型图形工具包和一个 sequence 图形。运行 node templates/figure.mjs out.svg 可写入 SVG；省略路径则会将其打印出来。

在 AI Engineering from Scratch 仓库中，还可查看 manuals/_shared/figkit.js（完整工具包）、manuals/_shared/templates/（每种类型对应一个脚本）和 scripts/audit_manuals.js（图形检查器）。