画廊 · 布局 · 风格 · 快速开始 · 功能特性 · 配置 · 校验

archscribe 是一个 Codex / Claude 技能 + 本地渲染器,用于生成高级感的深色画布技术图:手绘字体、可编辑的 Excalidraw 源文件、静态 PNG 预览,以及真正会动的 GIF。

它适合用来做文章讲解、系统架构图、流程图,以及 DailyDoseOfDS 风格的深色背景技术草图。

画廊

默认视觉系统:深色画布、沿箭头流动的高亮、图标微动效、模块呼吸脉冲、细微颗粒、暗角,以及右上角的手绘签名。

动画 GIF

静态 PNG

布局模板

三套模板覆盖绝大多数讲解场景。在配置里用 "layout" 字段选择;内容数量弹性适配,画布高度自动计算。

布局	适合的内容	预览
panorama(默认)	完整系统全景:输入源 → 核心管线 → 存储/产出面板
pipeline	线性流程:CI/CD、审批流、数据管道、生命周期
layers	分层结构:技术栈、N 层架构、协议栈

弹性说明:panorama 支持 2-6 个输入、2-4 张核心卡片,三个底部面板均可省略(全部省略时画布收窄为上半区);pipeline 支持 2-6 个阶段 + 可选判定菱形 / 产出卡 / 阶段备注 / 重试回路;layers 支持 2-5 层、每层 0-5 个条目。

风格

Archscribe 内置 4 套风格。图的布局、动画、图标完全一致,只有配色(以及浅色风格的收尾处理)不同。通过命令行 --style 或配置文件里的 "style" 字段选择。

风格	观感	预览
default	纯黑底深色手绘霓虹(品牌默认)
blueprint	深海军蓝单色,技术蓝图感
terminal	近黑画布 + 磷光绿 CRT 终端色调
candy	浅色纸张底,清新可爱的马卡龙色

在命令行选择风格(优先级高于配置文件):

python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename my-diagram \
  --style candy

或写进配置 JSON,让该图始终用这套风格渲染:

{
  "style": "blueprint",
  "canvas": { "width": 1210, "height": 1138, "fps": 20, "frames": 41 }
}

两者同时存在时,--style 优先;都不设置时使用 default。

功能特性

• 3 套布局模板(配置 layout 字段):panorama(弹性全景:2-6 输入 / 2-4 核心卡 / 面板可省)、pipeline(2-6 阶段,可选判定 + 重试回路 + 备注)、layers(2-5 层堆叠)
• 浏览器主渲染器(默认):无头 Chromium 内用 rough.js 手绘每个形状 + 内置 Excalifont / 思源黑体 webfont——真正的 Excalidraw 观感,任何系统渲染结果一致
• 3 套动画预设(--animation):flow(缓动能量光束 + 到站涟漪 + 波次呼吸)、draw(白板手绘生长)、relay(压暗画布上的接力点亮),三种布局全部支持,外加随风格自动切换的氛围层
• 一份 JSON 配置生成 .excalidraw、.png、.gif、.mp4、独立 .svg 和交互 .html(--formats 选择)
• 交互 HTML:点击模块高亮它的连接,勾选「整条链路」看 BFS 全链传播,悬停显示提示,支持键盘;单文件可直接分享
• MP4 体积远小于 GIF,X / 微信公众号原生支持;GIF 使用全局共享调色板,体积小
• 内置 4 套可选风格(default、blueprint、terminal、candy),用 --style 或配置 style 字段切换
• 渲染前配置预检(--validate-only 或渲染时自动执行):字段级 path / message / fix 报错,方便 agent 自动修正
• 品牌定制:任意条目用 icon_file 指向本地 SVG/PNG 当彩色图标 / 产品 logo(保留原色);left_panel.badge_file 在面板头放品牌标;input_style: "plain" 输出参考图同款无框彩色输入图标;down_label / up_label / yes_label 改写内置箭头标签;超长签名(如域名)自动左移 + 下划线拉伸,不再裁剪
• .excalidraw 源文件保持可编辑、纯文本
• 内置字体(OFL)与 Tabler SVG 图标子集(MIT),完全离线渲染;flow 预设下图标还有波次弹跳微动效
• --check 校验完整输出契约(尺寸、帧数、真实动效、MP4 流参数、SVG 字体内嵌、HTML 热区、Excalidraw 不变量);--verify 打印帧差报告
• 经典 Pillow 管线保留为 --renderer pillow 兜底

输出产物

默认渲染(--renderer browser)生成:

<basename>.excalidraw
<basename>.png
<basename>.gif
<basename>.mp4

可选:<basename>.svg(内嵌字体,可独立打开)、<basename>.html(点击探索的交互页面)。画布宽 1210,高度由布局按内容计算(经典 panorama 为 1210 x 1138)@ 20 fps;flow 41 帧(约 2 秒循环),draw 至少 72 帧,relay 至少 88 帧。

快速开始

git clone https://github.com/lazypay/Archscribe.git
cd Archscribe
python3 -m pip install -r requirements.txt
python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename sample \
  --verify

安装

把本文件夹放进你的 Codex 技能目录:

~/.codex/skills/archscribe

常见的本地安装路径:

${CODEX_HOME:-$HOME/.codex}/skills/archscribe

安装运行依赖:

python3 -m pip install -r requirements.txt

在 Codex 中使用

按技能名直接调用:

用 $archscribe 把这篇文章做成高级感手绘动态架构 GIF。

中文提示词示例:

用 $archscribe 把这篇文章整理成手绘动态架构图（岚叔 / DailyDoseOfDS 风格），输出 GIF、PNG 和 Excalidraw。

用 $archscribe 画一个 CI/CD 发布流程图（pipeline 布局），带失败重试回路，再给我一个能点击探索的 HTML。

关于浏览器图标引擎:browser 引擎是脚本通过 Playwright 自己拉起的无头 Chromium,与 "Codex 内置浏览器" 无关,无需手动启动。只要装好 requirements-browser.txt 与 python -m playwright install chromium,后续会自动启用;未安装时会静默回退到 pillow 引擎。

命令行用法

从内置模板开始:

cp assets/default-spec.json work/my-diagram-spec.json

渲染:

python3 scripts/render_animated_diagram.py \
  --spec work/my-diagram-spec.json \
  --outdir outputs \
  --basename my-diagram \
  --style default \
  --animation flow \
  --verify \
  --check

关键参数:

• --renderer auto|browser|pillow — browser(可用时的默认)在无头 Chromium 里用 rough.js 重放布局;pillow 为经典栅格兜底。
• --animation flow|draw|relay — 动画预设(浏览器渲染器),优先级高于配置文件的 animation 字段。
• --formats gif,mp4,png,svg,html,excalidraw — 选择产物;浏览器渲染器默认 gif,mp4,png,excalidraw。
• --style default|blueprint|terminal|candy — 配色,详见 风格。
• --validate-only — 只做配置预检并退出(JSON 格式的字段级报错/警告,有错误时退出码 2);正常渲染前也会自动预检。
• --verify — 打印抽样帧间差异(变化像素非零 = 真动画)。
• --check — 校验完整输出契约(PNG/GIF 尺寸、帧数、FPS、动效、MP4 流参数、SVG 字体内嵌、HTML 热区、Excalidraw 不变量),不通过则以非零码退出。
• --icon-engine — 仅影响 pillow 兜底管线的图标质量。

调试排版时先用 --formats png 快速出静态图(几秒),布局确认后再跑完整渲染。

配置结构

从示例配置起步:assets/default-spec.json(panorama)、assets/examples/pipeline-spec.json、assets/examples/layers-spec.json。

所有布局共享的字段:

layout         (可选: panorama | pipeline | layers, 默认 panorama)
style          (可选: default | blueprint | terminal | candy)
animation      (可选: flow | draw | relay)
signature
title.prefix
title.highlight
title.subtitle

panorama 专属:inputs(2-6)、core.cards(2-4)、decision、output、left_panel / center_panel / right_panel(均可省略)。

pipeline 专属:stages(2-6,每个含 title / body / 可选 icon / 可选 note)、可选 decision(含 loop_label 重试回路)、可选 output。

layers 专属:layers(2-5,每层含 name / 可选 desc / items(0-5 个,每个含 label / 可选 icon))、可选 edge_labels。

自定义图标 / logo:任何带 icon 的条目都可以改用 icon_file(本地 .svg / .png,相对路径以配置文件所在目录为基准),浏览器渲染器按原色嵌入,适合品牌 logo;left_panel.badge_file 则把面板头的文字徽标换成 logo 图片。

支持的图标键:

folder  file    scan    shield  db      hash
package message event   api     clock   brain
gear    eye     terminal globe  video   snapshot
server  lock    check   clipboard

详细说明见 references/spec-format.md。

校验

校验技能结构:

python3 ${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py \
  ${CODEX_HOME:-$HOME/.codex}/skills/archscribe

校验 GIF 媒体参数:

ffprobe -v error -select_streams v:0 -count_frames \
  -show_entries stream=width,height,r_frame_rate,avg_frame_rate,nb_read_frames \
  -show_entries format=duration \
  -of default=noprint_wrappers=1 outputs/my-diagram.gif

校验动画:

python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename sample \
  --verify \
  --check

依赖

必需:

• Python 3.9+
• Pillow 10.0.0+
• svg.path 7.0+

安装 Python 包:

python3 -m pip install -r requirements.txt

推荐(浏览器主渲染器——手绘形状、动画预设、SVG 输出):

python3 -m pip install -r requirements-browser.txt
python3 -m playwright install chromium

可选工具:

• ffmpeg:MP4 输出(缺失时自动跳过);ffprobe:检查媒体参数
• Excalidraw 网页版或编辑器插件:手动编辑生成的 .excalidraw 文件

内置资产(渲染时零下载):

• assets/fonts/ — Excalifont + 思源黑体子集(OFL-1.1),见 assets/fonts/README.md
• assets/vendor/rough.js — rough.js 4.6.6(MIT)
• assets/icons/tabler/ — Tabler 图标子集(MIT)

项目结构

archscribe/
├── SKILL.md
├── README.md            # 中文说明（本文件，默认）
├── README.en.md         # English
├── LICENSE
├── requirements.txt
├── requirements-browser.txt
├── agents/
│   └── openai.yaml
├── assets/
│   ├── default-spec.json          # panorama 示例
│   ├── examples/
│   │   ├── pipeline-spec.json     # pipeline 示例
│   │   └── layers-spec.json       # layers 示例
│   ├── fonts/                     # 内置 Excalifont + 思源黑体（OFL）
│   ├── vendor/                    # rough.js（MIT）
│   ├── icons/
│   │   └── tabler/
│   └── previews/
│       ├── memory-pack.gif        # 默认风格，动画主图
│       ├── memory-pack.png
│       ├── layout-pipeline.png
│       ├── layout-layers.png
│       ├── style-blueprint.png
│       ├── style-terminal.png
│       └── style-candy.png
├── docs/
│   └── interactive-output-design.md   # 2.0 路线图
├── references/
│   └── spec-format.md
├── scripts/
│   ├── render_animated_diagram.py     # CLI + 配置预检 + pillow 管线 + op 录制
│   ├── svg_renderer.py                # rough.js 浏览器渲染器 + 动画引擎 + 交互 HTML
│   ├── graph_model.py                 # 布局规划器（三种布局的几何 + 图拓扑）
│   ├── prepare_fonts.py               # 一次性字体资产构建
│   └── icon_browser.py                # 旧图标引擎（pillow 管线用）
└── tests/
    ├── test_render_output_checks.py
    ├── test_text_fitting.py
    ├── test_graph_model.py
    ├── test_bundled_fonts.py
    └── test_ops_and_browser.py

设计理念

本项目刻意把视觉系统收得很窄:

• 深色画布、手绘标题、右上角签名——三种布局共用同一套视觉语言
• 三套布局模板覆盖"系统全景 / 线性流程 / 分层堆叠"三类讲解场景,数量弹性但坐标全部由布局规划器计算,不接受任意自由布局
• 所有几何出自 graph_model.py 单一来源:Pillow、浏览器渲染器、动画路径、交互热区共享同一份 plan,不存在双渲染漂移
• 静态图保持克制,动效只加在 GIF/MP4 叠层(主要是路径光点 + 小幅图标聚焦扫描 / 微光)

这种约束保证不同架构主题下的输出都一致、精致。

致谢

这套深色手绘动态视觉风格,灵感来自 岚叔 的动态架构图,以及 DailyDoseOfDS 风格的深色背景技术草图。Archscribe 是对该观感的独立、开源再实现;原创美学的全部功劳归属于这些创作者。

许可证

MIT

assets/icons/tabler 中内置的图标来自 Tabler Icons,采用 MIT 许可,详见 assets/icons/tabler/LICENSE。