跳至正文
Skills — live-panel:把一份 JSON 渲染成动态架构图的 Agent Skill

live-panel:JSON 到动态架构图

项目仓库(MIT,2026-10-03 建仓)

AI 参与说明(Agent:OpenBot):本题的仓库调研与渲染实测由一次 OpenBot 任务完成,正文由另一次 OpenBot 任务依据其材料重写并排版。模型 deepseek-flash(提供方 deepseek,reasoning effort high),执行入口 OpenBot。事实来源为仓库克隆 HEAD d5aa86d、README.md、SKILL.md、references/ 规则文档与 GitHub API,核验日期 2026-11-18。文中的帧率、耗时、体积与检查结果均出自那次实测;上游默认编码参数下的体积没有复现,见「实测」一节。

静态架构图证明不了系统在跑。想看数据在流、日志在滚、计数器在涨,通常只有两条路:录屏,不精确也不可复现;或写动画代码,Remotion、Manim 一类,一套图配一套程序。

live-panel 走的是第三条:版面固定不动,只让状态动。一份 JSON 描述盒子、连线、日志文案与计数器,渲染器把它变成 H.264 视频,或一个自己循环播放的网页。

它有两个地方值得单独看。一是 skill:SKILL.md 是写给 Claude Code、Codex 这类 agent 的操作说明,agent 自己写配置、自己渲染、自己逐帧检查。二是验收:结果不靠肉眼确认,而是用 DOM 测量查文字溢出与重叠,再验证重放是否逐像素一致。这两点把它跟「又一个图表工具」区分开。

仓库实况:小、纯、没有 CI

项实测来源
提交数41GET /repos/.../commits?per_page=1 的 Link: rel="last" = page 41
贡献者ythx-101 36 次、cursoragent 2 次、cursor[bot] 2 次、ABCLDZ 1 次GET /contributors
CI无仓库根目录没有 .github/(ls -a)
Release / tag无GET /releases、GET /tags 均返回空数组
包分发无 npm / pip 包没有 package.json、setup.py、requirements.txt
Python 代码1954 行(scripts/*.py + tests/*.py)wc -l
前端代码2949 行(assets/template.html 448 行 + assets/views/*.js)wc -l
文档908 行(README.md、SKILL.md、references/ 6 篇)wc
工作树体积43 MB,大头是 examples/ 里 6 个 mp4 与若干 WebP 预览du -sh

两点与使用判断有关。41 次提交里作者 36 次,cursoragent 与 cursor[bot] 各 2 次:一个给 agent 用的工具,自己也用 agent 写。另外它没有 CI、没有 release、没有版本号可锁(CITATION.cff 只有 date-released: 2026-10-03)。因此凡是「它能保证 X」的说法,实际强度是作者本机跑过、你也能自己跑,而不是流水线持续验证。

两部分,不是一个应用

skill 部分是 SKILL.md(11 KB) 加 references/ 里三篇规则:config-schema.md 是字段表,motion-grammar.md 是动效语法,view-rules.md 是 19 条硬规则。接进 agent 的方式很土:把目录放进 agent 加载 skill 的位置,Claude Code 是 ~/.claude/skills/live-panel/。没有 MCP server,没有插件协议,没有后台进程,agent 读文档、写 JSON、执行命令行脚本。

SKILL.md 里有一条自我约束,可以抄进任何长输出任务的 prompt:

Never type a whole config into a single message or tool call: a 20-40 KB JSON in one write is the most common way an agent run dies before anything is saved.

它把「agent 会在长输出中途死掉」当成设计前提,要求先用 scaffold.py 出骨架,再小步改,每改 1–3 个盒子跑一次检查。这种工程妥协比功能列表更能说明项目的成熟度。

renderer 部分是三个脚本加一个模板:

  • scripts/livepanel.py(218 行):把模板与配置合成一个自包含 HTML,用 --remote-debugging-pipe 直接驱动无头 Chrome。纯标准库,走 fd 3/4,不用 websocket,不装 puppeteer。
  • scripts/render.py(69 行):逐帧 seek(i/fps)、Page.captureScreenshot,PNG 字节流管道进 ffmpeg。
  • scripts/check_frames.py(83 行):采样约 120 个时间点,调页面里的 window.__check() 做几何检查,导出 PNG,加 --repeat 再验重放一致性。

依赖只有三样:Python 3.8+(仅标准库)、本机 Chrome 或 Chromium、ffmpeg。不需要 API key,不联网。

配置:坐标是绝对的,动画是时间的函数

顶层键在 references/config-schema.md 里列全了:meta、canvas、theme、clock、titlebar、credit、machines、elements。这是 examples/minimal/config.json 的删节版:

json
{
  "canvas": {"preset": "1:1", "duration": 12, "fps": 30, "preroll": 4},
  "theme": {"preset": "terminal-dark"},
  "clock": {"start": "09:00:00", "rate": 1},
  "titlebar": {"text": "~/minimal - live-panel"},
  "credit": {"text": "minimal example - all numbers are illustrative", "y": 1060},
  "machines": {
    "reqs": {"type": "counter", "start": 1200, "rate": 7, "format": "comma"},
    "agent": {"type": "lane", "period": 6, "run": 4, "busy": "working", "done": ["done"],
              "log": {"who": "agent", "c": "gr", "msgs": [["task finished", "ok"]]}}
  },
  "elements": [
    {"type": "box", "x": 390, "y": 140, "w": 300, "h": 110, "color": "cy",
     "lines": [{"t": "user", "b": 1}, {"runs": ["requests ", {"v": "reqs"}]}]},
    {"type": "flow", "path": [[540, 250], [540, 330]], "period": 1.5, "offsets": [0, 0.7], "color": "cy"}
  ]
}

两个决定划出了它的上限和下限。

坐标是画布像素,不是相对布局。README 写得很直白:Positions in a config are absolute canvas pixels, so a config is authored for one canvas。换画幅不是改一个参数,而是另写一份配置重排盒子。这既是「任何一帧都是完整图」的前提,也是它无法像 Mermaid 那样自适应容器宽度的原因。

会动的东西都是时间的纯函数。machines 一共 7 种:counter、cycle、gauge、any_low、lane、triggers,加上文本里的 {packets} 与 {clock}。它们不发事件给 DOM,而是在渲染时按 t 求值。日志行也由同一批状态机生成,所以日志里的数字与条上的数字是构造出来的,不是事后对齐的。

除了手写 JSON,还有一条导入路线:excalidraw_import.py(296 行)把 .excalidraw 文件转成配置,矩形、椭圆、菱形变成节点,箭头保留 binding(两端连到形状就成 edge),虚线保持流动,帧、图片与手绘笔迹跳过。两条路都落在同一个 {"type":"view","kind":"excalidraw"} 渲染器上。

渲染链路:seek、截图、x264

flowchart TD
    A["config.json 或 .excalidraw"] --> B["build_page:内联 assets/views/*.js 与字体"]
    B --> C["自包含 page.html"]
    C --> D["headless Chrome --remote-debugging-pipe(fd 3/4)"]
    D --> E["seek(i/fps):按 t 求值状态"]
    E --> F["Page.captureScreenshot"]
    F --> G["PNG 字节流 → ffmpeg stdin"]
    G --> H["libx264 -preset medium -crf 16 + 静音 AAC"]
    H --> I["mp4"]
    C --> J["--html-out:同一页面循环播放"]

每一步都能指到代码:

  1. build_page() 读模板,把配置塞进 <script id="live-config">,并把 assets/views/*.js 和用到的字体以 base64 data URL 内联,产出一个完全自包含的 HTML(livepanel.py:build_page)。
  2. 启动 Chrome:--headless=new --remote-debugging-pipe,用 sh -c 'exec "$@" 3<&"$LP_R" 4>&"$LP_W"' 把两个管道接到 fd 3/4(livepanel.py:Chrome.__init__)。这是它只依赖标准库的关键,也是 Windows 不能原生跑的原因:POSIX 文件描述符传不过去,官方建议在 WSL 里跑。
  3. 打开 page.html?manual,轮询 window.__ready,等 document.fonts.ready 之后再开始。
  4. 循环 seek(i/fps) → Page.captureScreenshot → 写进 ffmpeg 的 stdin:-f image2pipe -c:v png 进,libx264 -preset medium -crf 16 -pix_fmt yuv420p 出,默认再挂一条 anullsrc 静音 AAC 轨。README 给的理由很实用:某些聊天软件会把没有音轨的 mp4 当 GIF 处理。
  5. --html-out 另存那份自包含页面,浏览器打开即循环播放;去掉 ?manual 后由 requestAnimationFrame 驱动同一个 seek。

验收:DOM 几何与逐像素重放

确定性靠三条禁令:没有 wall clock,没有 Math.random,没有 CSS animation 或 transition。少数需要「随机」的取值用固定种子整数哈希。

window.__check()(template.html:376)查五类问题:文字越出画布、文字越出所属盒子、文字互相压、文字压在别的盒子上、盒子互相压。container:true 的容器盒与 inside:true 的图标文字被豁免,避免嵌套布局误报。

check_frames.py --repeat 的做法是截图、seek 到别处再回来、再截图,然后在页面内用 canvas 逐像素比对,容差 50 个像素,用来吸收抗锯齿噪声。

视图自己还有一轮 lint:references/view-rules.md 共 19 条,其中 R1–R7 与 R17 由 verify_view.py 强制执行。规则本身是经验值,比如 CJK 标签宽约拉丁的两倍、每个 label 都要过 ctx.fit;任何高亮持续不少于 0.8 s;数字在 0.4 s 内不得超过一次变化,且宽度不能抖。

这套检查的价值在于它不依赖眼睛。check_frames.py 退出码为 0 才算完成,比「看起来还行」可执行得多。

两种风格:同一套布局,换主题

terminal-dark 与 light-pastel 不是两套布局,是同一套布局引擎的两个主题预设。template.html:407 起是两张表:

terminal-darklight-pastel
字体JetBrains Mono → IBM Plex Mono → DejaVu Sans Mono → Noto Sans Mono CJKNoto Sans CJK SC → PingFang SC → Helvetica/Arial
字号 / 行高21 / 3017 / 24
盒子画法boxMode: "segmented",上下实线、两侧分段,模仿终端文本框boxMode: "solid",圆角 9、描边 1.5
装饰无辉光、数据包小glow: true、线宽 2.2、数据包 10px、状态箭头带两个包
色表深色 8 基色 + acc1..acc6浅色 pastel 基色 + acc1..acc6

boxMode 只在两处被读(template.html:222 的盒子绘制与每盒的 sides 覆盖),所以换主题不改布局逻辑。

真正要改的是注意力分配。SKILL.md 的 Light theme notes 要求浅色版用 container:true、inside:true 与共享 cycle 机器逐行点亮,让屏幕上只有一件事在发生。这是推断而非实测结论:深色版靠数据包密度撑起「在跑」,浅色版靠高亮和辉光撑起「在读」,同一份内容换主题后通常要调文字长度。

实测:0.11–0.20 秒一帧

环境:macOS 27.2.1 / Apple M1 Max、Python 3.14.0(pyenv)、Chrome 157 headless、PATH 上没有 ffmpeg。

用例配置来源分辨率 / 帧数耗时检查结果
minimal仓库自带1080×1080 / 360 帧44 scheck_frames 124 点 0 问题,重放逐像素一致
loop-poteto(loop 视图,中文)仓库自带1200×1500 / 540 帧110 s同上,124 点 0 问题
自写(中文 light-pastel,3:4)scaffold.py 从 20 行 spec 生成 7 KB 配置1080×1440 / 900 帧99 s124 点 0 问题,重放一致

换算下来是 0.11–0.20 秒每帧:一条 30 秒 30 fps 的片子约 1.5–3 分钟,瓶颈在逐帧截图而不是编码。另外三项也跑通了:python3 -m unittest tests.test_offline(3 项,0.26 s,不需要浏览器)、verify_view.py --config examples/ring/config.json(7 组画幅×主题 7/7 PASS,27.3 s)、scaffold.py 的 --example | --spec | --out 往返。

两处踩到的都是环境问题,不是代码问题。

ffmpeg 需要 libx264。 本机 PATH 上没有 ffmpeg。Playwright 缓存的 ffmpeg-mac 是 --disable-everything 构建,只有 libvpx 与 png,render.py 直接报 Unrecognized option 'preset'。另一个 app 包内自带的 ffmpeg 只有 h264_videotoolbox。实测时把 render.py 复制成 render_vt.py、把编码器换成 h264_videotoolbox -b:v 8M 才跑通。这是测试侧的改动,不是上游行为:画面内容不受影响,但码率与体积跟上游默认的 -crf 16 不可比(12 秒 1080×1080 出 2.1 MB,18 秒 1200×1500 出 17.5 MB)。要按上游参数出片,得装一个带 libx264 的 ffmpeg。

等宽字体大概率没装,但不会崩。 fc-list | grep -ic 'jetbrains|dejavu|noto sans mono' 返回 0,说明 terminal-dark 的字体链本机全部缺失,实际落到系统 monospace(macOS 是 Menlo)。实测 21 px 下 M 宽 12.64 px,即 0.602 em,与 schema 声明的拉丁 0.6 em 几乎一致,布局计算仍然成立。CJK 在 monospace 下是 1 em,而 schema 假设 CJK 占两格即 1.2 em,实际比预期窄,方向上是安全的。仓库自带得意黑(1.15 MB,titleFont: "smiley" 时内联)与 Excalifont 拉丁子集(25 KB);中文手写体小赖约 22 MB 不在仓库里,要跑 scripts/fetch_fonts.sh 自己下。

限制

限制具体表现来源
版面不自适应换画幅要重排坐标;--width/--height 只是缩放加黑边README
平台Linux / macOS 原生,Windows 只能在 WSL 里跑livepanel.py 用 POSIX fd 传管道
外部依赖必须本机有 Chrome 或 Chromium 加 ffmpeg,缺 libx264 就出不来本次实测
渲染耗时0.11–0.20 秒每帧,长片线性增长本次实测
视图覆盖ring / funnel / loop / excalidraw 标 ready;sketchboard 只有示例且字体不随仓库提供;nebula / timeline / tree / kpi 仍标 plannedREADME Views 表、SKILL.md
无版本、无 CI没有 tag 或 release,回归靠本地 unittest 加两个脚本GitHub API、ls -a
数字合规没给来源的跳数必须在画面标 illustrative 或示意;复刻他人图必须在 credit 写 handle 与完整链接references/motion-grammar.md §4
许可分层代码是 MIT,但 examples/codex-agents/ 与 examples/agent-architecture/ 的设计不在 MIT 授权内;字体是 OFL,rough.js 是 MITNOTICE、LICENSE
不适合需要交互或真实遥测的图、要讲一步步来的教学动画、任意形状的复杂矢量插画SKILL.md 的 Not for

有一点需要单独提醒:它的「动」是模拟,不是数据绑定。想让图跟着真实 Prometheus 指标跳,得自己写脚本定时把值写进配置再重渲,项目本身不做这件事。这是推断,但它与无 CI、无版本号放在一起看,更像有意的范围划分,而不是没做完。

什么时候用它

  • 要发 X 或小红书,需要一张看起来在运行的架构图,且愿意手摆坐标:用。
  • 已经有 .excalidraw 白板图想让它动起来:走导入路线最省事。
  • 只是给 README 画一张架构图:用 Mermaid,别开 Chrome。
  • 要任意运动或精确到帧的编排:Remotion、Manim 更合适,这个工具的表达力是刻意收窄的。
  • 要给 agent 一个自己会出图、自己会验收的技能:它是少见的、把验收写进 skill 的样本。

视觉语法本身并不新,据 SKILL.md 记录学自 @thedelost 的一条录屏。它多做的一步是把这套套路形式化成 19 条可 lint 的规则,并把「agent 出图要自我验收」写成流程。

验证范围

  • 上游默认 libx264 -crf 16 的输出体积与画质没有对照,本机无 libx264 构建。
  • Windows + WSL 路径未实测。
  • 中文手写体小赖未下载,excalidraw 视图的中文效果只在仓库自带的 WebP 预览里见过。
  • 「所有例子都能过检查」目前是作者声明加三次抽样,无 CI 持续验证。

关联阅读

博客助手

正在打开博客助手…