blueprint-figure
为从零开始学 AI 工程课程、README 和手册绘制静态 SVG 图。 使用纸张面板、蓝图强调色、九种图形、固定语义色、八种箭头,并检查可读性与标记。 触发短语:“画一张图”“蓝图风格图”“时序图”“状态机图”“本课图表”“给手册加图”。
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1.3k
- Forks
- 195
01 前言 Front Matter
- name
- blueprint-figure
- tags
- [ "svg", "figures", "diagrams", "accessibility", "documentation" ]
- version
- 1.0.0
- description
- 为从零开始学 AI 工程课程、README 和手册绘制静态 SVG 图。 使用纸张面板、蓝图强调色、九种图形、固定语义色、八种箭头,并检查可读性与标记。 触发短语:“画一张图”“蓝图风格图”“时序图”“状态机图”“本课图表”“给手册加图”。
02 资源文件 4
- 参考文档references/checks.md4.2 KB
- 参考文档references/grammar.md6.7 KB
- 参考文档references/kinds.md4.3 KB
- 脚本templates/figure.mjs8.0 KB
03 SKILL.md 正文
蓝图风格图表
每张静态 SVG 解释真实系统的一个机制,使用系统中的真实 ID、字段、方法、状态码与序号。图表使用浅色纸张面板和少量含义固定的色相,在屏幕和打印的 640 单位宽度下保持清晰。Claude、Cursor、Codex、OpenClaw、Hermes 及所有读取 SKILL.md 的 agent 都可使用。course-style 保存完整课程 token,本技能复制所需值,可独立使用。
适用情况
- 课程、README 或手册需要解释系统部件如何通信、存储数据或改变状态。
- 已有运行记录、日志、规范或源代码,可取得真实名称。
- 断言适合下方九种图形之一。
使用其他方式的情况
- 图表要动或响应滑块:使用
motion-figure。 - 有深度和控件的实体机器讲解:使用
isometric-explainer。 - 多个数据点的数值图:使用绘图工具。
- 没有部件的真实名称:先取得运行记录或源代码。
方法
- 先写图表要证明的一句断言,英文最多 28 词。
- 选一种图形;两种图形都适合时,拆为两张图。
- 从来源收集真实参与方、字段、方法、状态码和序号。
- 绘图前为整组图写好语义色表,见下方颜色规则。
- 在 640 单位网格上安排布局,内容位于 x 20 至 x 620。
- 从
templates/figure.mjs开始,用脚本绘制,不手改 SVG。 - 运行脚本,标签过小、过宽或越界时必须停止。
- 运行
references/checks.md的检查,修复所有发现。 - 渲染为 PNG,分别按原尺寸和 50% 宽度查看。
- 写图注:粗体断言、读图顺序、来源。
九种图形
| 类型 | 用途 |
|---|---|
sequence |
参与方生命线,时间向下,交互编号 |
structure |
一个记录、对象或 schema 的结构 |
flow |
数据流经的阶段,以及谁写谁读 |
comparison |
并排展示同一问题的两种答案 |
timeline |
沿提交序号或时间等数轴的多条轨道 |
tree |
所有权、包含关系、委托 |
state |
状态机与转换 |
decision |
失败位置与各结果含义 |
layers |
分层结构与各层负责的部件 |
各类型的布局尺寸见 references/kinds.md。
图表表达什么
- 使用真实系统和真实名称,不用“组件 A”等泛化方框。
- 不画统计卡、进度条或装饰图标。
- 每图一个断言。
- 对比主题的两种行为,不对比自己项目的旧版本。
- 时序图按运行记录中的发生顺序给交互编号。
颜色
十种色相为 grey、blue、teal、violet、green、amber、plum、olive、indigo、rose。每种都有 ink 和 fill token,同一组图含义一致。
固定四种语义:
| 色相 | 含义 |
|---|---|
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 展示该组使用的每种箭头样式。
边框
- 色相 ink 实线:普通部件或状态。
- 虚线:中断、可选或不存在。
- 双边框:第二个矩形内缩 3 单位,表示终止状态。
- 斜线填充:时间线上的等待时间,不能覆盖文字。
可读性
- 640 单位宽时文字至少 11 单位,屏幕约 11px,打印约 8pt。
- 方框标题 12.5、粗体等宽,副行 11、衬线,箭头标签 11.5,注释 11、衬线。
- 每行衬线字都声明
class="m-serif"和font-family="Source Serif 4, Georgia, serif",使内联、README 图片和手册一致。 - 小标题为 11,英文大写,字距 1.2,颜色 ink-mute。
- 标签不省略,不重叠,不置于斜线填充上,不被连线穿过。
- 放不下时移到外部并加引线,或放进编号索引,不缩字号。
- 箭头标签下垫面板色补底,类为
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)"。衬线行独立声明字体。 - 根直接包含
<title>和至少 40 字符的<desc>。 desc按阅读顺序列出全部部件和交互。- 每个
id以图 ID 开头,例如fig-4-1-head-amber。 - 图 ID 用小写词和数字,以连字符连接,例如
fig-4-1。 - 只用
references/checks.md列出的元素与属性。 - 没有
style、脚本、事件处理器、链接或图片。 transform只能是<g>上的translate()。- 每行一个
<text>。 - 文件不超过 40 KB,绘制元素不超过 450 个。
图注
图注放在页面中 SVG 外部。
- 先用粗体写一句断言,英文最多 28 词,以句号结束。
- 说明读图顺序,例如“从上向下阅读”。
- 说明来源,例如运行记录文件。
手册中使用围栏声明图表。字段与类型保持不变,面向读者的文字译为中文:
```figure
id: fig-4-1
kind: state
title: 任务生命周期
claim: 任务进入四种终止状态之一后,不再离开。
caption: 从左到右阅读。虚线边框表示中断状态。来源为 capture/out/task-states.txt。
```
课程或 README 以内联或图片标签插入 SVG,再在下方添加图注段落。
源与产物一起保存
- 脚本与 SVG 放在邻近目录,例如
figures/src/fig-4-1.js和figures/fig-4-1.svg。 - 每次从脚本生成 SVG,构建后不手改产物。
- 提交前重建,确认提交的 SVG 与脚本输出一致。
完成前检查
- [ ] 断言为一句,英文最多 28 词。
- [ ] 标签都是真实来源中的名称,不用“组件 A”。
- [ ] 使用九种图形之一。
- [ ] 玫红表示失败,灰色表示范围外,琥珀表示生命周期,青色表示持久状态。
- [ ] 箭头使用八种样式之一,并符合语义。
- [ ] viewBox 宽 640,高不超过 760。
- [ ] 包含
role="img"、aria-labelledby、<title>、至少 40 字符的<desc>。 - [ ] 所有 ID 以图 ID 开头。
- [ ] 颜色均为
var(--m-<token>, <light hex>),默认值正确。 - [ ] 字号至少 11,无越界、文字重叠或连线穿字。
- [ ] 标签无省略号。
- [ ] 衬线行有字体属性,根有墨色 fill,不依赖宿主样式表。
- [ ] 无 style、脚本、链接、图片,仅允许 g 上的 translate 变换。
- [ ] 文件最多 40 KB。
- [ ] PNG 在 50% 宽度下清晰。
- [ ] 图注包含粗体断言、读图顺序、来源。
- [ ] 提交的 SVG 等于脚本输出。
文件
references/kinds.md:九种图形布局与图 0.1。references/grammar.md:明暗 token、语义色、箭头、标记、字号、度量、形状、可选节拍。references/checks.md:检查项、允许元素属性、图注规则。templates/figure.mjs:自包含 Node 脚本,含小型图表工具和 sequence 示例。运行node templates/figure.mjs out.svg写文件,不传路径则打印。
仓库中另见 manuals/_shared/figkit.js 完整工具、manuals/_shared/templates/ 各类型模板、scripts/audit_manuals.js 图表检查器。
04 同仓库更多 Skills
write-manual
为一个固定版本的技术主题编写长篇手册,从用途讲到每个请求与响应。 每个示例来自离线运行记录,每个断言追溯到按权威排序的来源,审计必须达到 TOTAL 0。 用于“编写手册”“为某主题写入门手册”“manual.json”“增加手册章节” “构建运行记录工具”“审计手册”“固定规范版本并文档化”。
start-learning
AI Engineering from Scratch 课程的一次性入门流程(523 节课、20 个阶段)。访谈学习者、 运行分级测验,并写入由 learn skill 驱动的持久学习计划 LEARNING.md。触发短语: “开始学习”、“设置课程”、“开始课程”、“带我入门”、“创建学习计划”,或 "start learning", "set up the course", "begin the curriculum", "onboard me", "create my learning plan"
mcpa-certification
AI Engineering from Scratch 中文版中的 MCPA(Model Context Protocol Associate)AI 原生导师与入门流程。学习者需要备考 MCPA、继续认证路线、 交互式学习下一课、运行并验证实践实验、参加诊断或全真模拟、根据薄弱领域 补弱时使用。适用于 Claude Code、Codex、ChatGPT、Cursor 或其他 agent。
lesson-screen
课程导师在终端教学时,在旁边打开浏览器学习屏幕。展示课程已注册的图表、带真实数值的 代码执行过程和可点击的预测题。也可结合课程与宿主已安装的图表技能,为当前课程制作 蓝图、机制图、等距机器或 3D 模型。点击以事件形式返回导师。 触发短语:“打开学习屏幕”、“用图展示”、“用 3D 展示”、“画出架构”、“为这节课制作图表”, 或 "open the lesson screen", "show me this visually", "show this in 3D", "draw the architecture", "visualize this lesson", "build a figure for this lesson", "lesson screen"。
learn
AI Engineering from Scratch 课程的交互式课程 tutor。读取 LEARNING.md,获取下一课, 在终端按章节教学,结尾测验并记录进度。可在克隆仓库中或完全通过 raw.githubusercontent.com 工作—— 无需设置。触发短语:“下一课”、“教我”、“继续课程”、“我们来学习”、“继续学习”,或 "next lesson", "teach me", "continue the course", "let's learn", "resume learning"
learn-reverse-engineering
从零开始学 AI 工程中逆向工程专项路径的交互导师。学习者希望读取编译后的程序时, 用于开始或继续文件格式、反汇编、控制流、表示提升、证据、等价证明、调用约定、 编译器惯用模式、链接、类型、调试、字节码、差分、符号执行和 AI 辅助分析。 每次调用讲授一课,并将证据记录到 REVERSE-ENGINEERING-LEARNING.md。