AGENT SKILL

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

03 SKILL.md 正文

蓝图风格图表

每张静态 SVG 解释真实系统的一个机制,使用系统中的真实 ID、字段、方法、状态码与序号。图表使用浅色纸张面板和少量含义固定的色相,在屏幕和打印的 640 单位宽度下保持清晰。Claude、Cursor、Codex、OpenClaw、Hermes 及所有读取 SKILL.md 的 agent 都可使用。course-style 保存完整课程 token,本技能复制所需值,可独立使用。

适用情况

  • 课程、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. 渲染为 PNG,分别按原尺寸和 50% 宽度查看。
  10. 写图注:粗体断言、读图顺序、来源。

九种图形

类型 用途
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 外部。

  1. 先用粗体写一句断言,英文最多 28 词,以句号结束。
  2. 说明读图顺序,例如“从上向下阅读”。
  3. 说明来源,例如运行记录文件。

手册中使用围栏声明图表。字段与类型保持不变,面向读者的文字译为中文:

```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

fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

write-manual

为一个固定版本的技术主题编写长篇手册,从用途讲到每个请求与响应。 每个示例来自离线运行记录,每个断言追溯到按权威排序的来源,审计必须达到 TOTAL 0。 用于“编写手册”“为某主题写入门手册”“manual.json”“增加手册章节” “构建运行记录工具”“审计手册”“固定规范版本并文档化”。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

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"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

mcpa-certification

AI Engineering from Scratch 中文版中的 MCPA(Model Context Protocol Associate)AI 原生导师与入门流程。学习者需要备考 MCPA、继续认证路线、 交互式学习下一课、运行并验证实践实验、参加诊断或全真模拟、根据薄弱领域 补弱时使用。适用于 Claude Code、Codex、ChatGPT、Cursor 或其他 agent。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

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"。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn

AI Engineering from Scratch 课程的交互式课程 tutor。读取 LEARNING.md,获取下一课, 在终端按章节教学,结尾测验并记录进度。可在克隆仓库中或完全通过 raw.githubusercontent.com 工作—— 无需设置。触发短语:“下一课”、“教我”、“继续课程”、“我们来学习”、“继续学习”,或 "next lesson", "teach me", "continue the course", "let's learn", "resume learning"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn-reverse-engineering

从零开始学 AI 工程中逆向工程专项路径的交互导师。学习者希望读取编译后的程序时, 用于开始或继续文件格式、反汇编、控制流、表示提升、证据、等价证明、调用约定、 编译器惯用模式、链接、类型、调试、字节码、差分、符号执行和 AI 辅助分析。 每次调用讲授一课,并将证据记录到 REVERSE-ENGINEERING-LEARNING.md。

★ 1.3k