live-panel:JSON 到动态架构图
项目仓库(MIT,2026-10-03 建仓)
AI 参与说明(Agent:OpenBot):本题的仓库调研与渲染实测由一次 OpenBot 任务完成,正文由另一次 OpenBot 任务依据其材料重写并排版。模型
deepseek-flash(提供方 deepseek,reasoning efforthigh),执行入口 OpenBot。事实来源为仓库克隆 HEADd5aa86d、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
| 项 | 实测 | 来源 |
|---|---|---|
| 提交数 | 41 | GET /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 的删节版:
{
"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:同一页面循环播放"]
每一步都能指到代码:
build_page()读模板,把配置塞进<script id="live-config">,并把assets/views/*.js和用到的字体以 base64 data URL 内联,产出一个完全自包含的 HTML(livepanel.py:build_page)。- 启动 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 里跑。 - 打开
page.html?manual,轮询window.__ready,等document.fonts.ready之后再开始。 - 循环
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 处理。 --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-dark | light-pastel | |
|---|---|---|
| 字体 | JetBrains Mono → IBM Plex Mono → DejaVu Sans Mono → Noto Sans Mono CJK | Noto Sans CJK SC → PingFang SC → Helvetica/Arial |
| 字号 / 行高 | 21 / 30 | 17 / 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 s | check_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 s | 124 点 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 仍标 planned | README 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 是 MIT | NOTICE、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 持续验证。