AI教程

使用 live-panel 从 JSON 构建动画架构图

学习如何安装 live-panel、配置画布和主题、从 JSON 创建动画架构图、将其渲染为 MP4 或 HTML，并验证每一帧以发现布局问题，确保播放结果确定一致。

AI我搜编辑部2026年10月4日阅读约 8 分钟

live-panel 的作用

live-panel 将单个 JSON 系统描述转换为动画架构图。布局保持固定，同时数据包沿线路传输、日志滚动、计数器变化、进度条切换状态，侧边触发器依次亮起。

你可以将结果导出为适用于 X 和小红书等平台的 H.264 MP4，也可以将其保留为自包含的实时网页。该仓库还可以通过其中的 SKILL.md 文件作为 Claude Code 风格的技能使用。

随附的 Codex agents 示例复现了 @thedelost 创作的终端风格架构视频片段的外观和动效。该仓库还包含浅色柔和风格的 AI 架构示例和 Airbnb 可视化示例。

主要功能

通过 JSON 定义由配置驱动的架构图。
终端深色和浅色柔和视觉主题。
支持 4:5、3:4 和 1:1 输出的画布预设。
支持动画数据包、路径、日志、计数器、仪表、触发器和状态变化。
完全基于时间进行确定性渲染，不使用墙上时钟计时、Math.random 或 CSS 动画。
导出为 MP4，或保留生成的实时 HTML 页面。
自动检查文本溢出、重叠和跳转一致性。

安装依赖

live-panel 使用 Python 标准库，因此无需安装 pip 软件包。渲染前请安装以下工具：

Python 3.8 或更高版本。
Chrome 或 Chromium。
ffmpeg。

下载仓库后，请确认系统路径中可以找到 python3、Chrome 或 Chromium 以及 ffmpeg。渲染脚本默认会在系统路径中搜索 Chrome 和 ffmpeg。

渲染随附示例

codex

从 Codex agents 配置开始。以下命令会将 JSON 配置渲染为 MP4 文件：

python3 scripts/render.py --config examples/codex-agents/config.json --out out.mp4

示例配置还展示了项目如何将固定位置与动态机器变量结合使用。其他现成示例位于 examples/agent-architecture/ 和 examples/airbnb/。

若要保留生成的网页，而不只是生成视频，请添加 --html-out：

python3 scripts/render.py \
  --config examples/codex-agents/config.json \
  --out out.mp4 \
  --html-out page.html

在兼容的浏览器中打开生成的 HTML 文件即可查看实时动画。你还可以通过 --width、--height、--duration、--fps、--chrome、--ffmpeg、--keep-frames、--audio 和 --crf 等选项控制输出设置。

验证渲染帧

发布架构图前，请运行帧检查器：

python3 scripts/check_frames.py \
  --config examples/codex-agents/config.json \
  --out-dir frames \
  --repeat

检查器会采样约 120 个时间点，测量 DOM 中的文本溢出和元素重叠，并写入具有代表性的 PNG 文件。使用 --repeat 时，它会跳离每个导出帧后再次渲染，以验证结果是否一致。如果检测到问题，该命令将以状态码 1 退出。

创建自己的架构图

agent

复制一个示例配置文件。
编辑其中的文本、数字、颜色、位置和动画设置。
将复制的配置渲染为 MP4 或 HTML。
运行 check_frames.py 并检查生成的 PNG 文件。
调整布局并重复操作，直到检查器不再报告问题。

大多数自定义内容都位于配置文件中。仓库说明，正常创建架构图时无需修改 assets/template.html。

配置画布和主题

配置可以选择画布预设、动画时长、帧率和可选的预渲染时间：

{
  "canvas": {
    "preset": "3:4",
    "duration": 28,
    "fps": 30,
    "preroll": 0
  },
  "theme": {
    "preset": "light-pastel",
    "colors": {
      "pk": "#f0575f"
    }
  }
}

可用的画布预设包括 1200×1500 像素的 4:5、1080×1440 像素的 3:4，以及 1080×1080 像素的 1:1。终端深色预设使用深色窗口、等宽字体和分段式文本框。浅色柔和预设使用白色背景、圆角柔和色块、圆角 SVG 箭头，以及活动项目上的柔和光晕。

画布位置使用绝对像素值。因此，配置是针对单一宽高比编写的。虽然 render.py --width 和 --height 可以通过加黑边缩放输出，但不同宽高比通常需要复制配置并重新定位其中的色块。

描述元素和动效

配置架构支持多种视觉元素类型：

text 用于标签和独立文本。
box 用于容器，包括填充、边框、圆角、虚线样式、逐行项目、条形图和文本运行。
line 和 path 用于线缆和连接。
glyph 和 rule 用于符号和分隔线。
flow 用于沿折线移动的数据包。
tarrow 用于触发箭头。
log 用于滚动或变化的日志内容。

变化值定义在 machines 下。可用的机器类型包括 counter、cycle、gauge、any_low、lane 和 triggers。使用这些变量驱动视觉状态，而不是直接向单个元素添加时间逻辑。

airbnb

方框、路径、流、线条和运行内容可以使用 when 和 then 条件。例如，{"var":"seq.i","in":[0,1,2]} 这样的条件，可以在机器变量匹配所列值之一时突出显示某个项目。多个条件会被视为 AND 表达式。

了解确定性回放

生成的页面会公开 window.seek(t)。每个视觉效果都是时间值 t 的纯函数，伪随机选择使用固定种子的整数哈希。在普通浏览器模式下，动画由 requestAnimationFrame 驱动。渲染期间，导出器使用 seek(i/fps) 跳转到每一帧的时间并捕获结果。

这种设计使导出的帧具有可重复性。它也说明了为什么在更改字体、位置或动画条件后，应使用帧检查器。

改进排版和布局

字体文件不会随附。终端主题会依次回退到 JetBrains Mono、IBM Plex Mono、DejaVu Sans Mono、Noto Sans Mono CJK SC 和通用等宽字体。浅色柔和主题使用 Noto Sans CJK SC、PingFang SC、Microsoft YaHei、Helvetica 或 Arial，大标题使用 Noto Serif CJK SC。

若要更接近示例效果，请安装 JetBrains Mono 和 Noto CJK 字体。表情符号图标还需要 Noto Color Emoji 等彩色表情符号字体。由于不同字体的字形宽度不同，每当更改已安装的字体后，都应再次运行 check_frames.py。

实用渲染技巧

以最接近预期视觉风格的示例作为起点。
使坐标与所选画布比例保持一致。
需要检查用于构建视频的确切图像时，使用 --keep-frames。
不需要音轨时，使用 --audio none。
需要控制编码视频质量时，调整 --crf。
每次进行重要的布局、字体或配置更改后，都运行检查器。
对于 Claude Code，将仓库放在 ~/.claude/skills/live-panel/，或放在代理技能加载器使用的目录中。

致谢与许可

代码以 MIT 许可证发布。Codex agents 示例中重现的视觉设计归 @thedelost 所有，而浅色 AI 架构信息图归原作者、小红书创作者林纾所有。Airbnb 数据来自 Airbnb 领导者在 Latent.Space 访谈中的陈述，动画计数器仅用于示意。

结语

live-panel 提供了一套实用流程，可将结构化系统描述转化为精致且可重复的动态图形。复制示例、编辑 JSON、选择画布和主题、渲染 MP4 或实时页面，并使用确定性帧检查器在发布前发现布局问题。