live-panel-skill是一个把 JSON 配置变成动态架构图的开源渲染器：终端监控面板风格的 agent 架构动图、会动的浅色信息图，输出 H.264 mp4 视频或可在浏览器里循环播放的网页。更关键的是，它自带一份 SKILL.md，可以直接接入 Claude Code、Codex 等 AI 编程助手——你只需用自然语言描述系统，AI 就会替你写配置、渲染视频、逐帧自查，全程不用手写任何动画代码。

live-panel-skill 是什么：一个 JSON 生成会动的架构图 🎬

传统架构图（Mermaid、Excalidraw）画出来就是一张"死"的静态图。live-panel-skill 的思路完全不同：把图当作一个"正在运行的系统"的监控面板——版面永远固定不动，但连线上的数据包在流动、日志在滚动、计数器在跳动、进度条会翻转状态、侧栏触发点依次点亮。随便截其中一帧，都是一张完整可读的架构图。

它的输入输出非常克制：

• 输入：只有一个 JSON 文件（方框、连线、数据包路径、日志文案、计数器），HTML 模板 assets/template.html 永远不需要动；
• 输出：H.264 mp4 视频（30 fps），和/或一个自包含的 HTML 页面（--html-out参数）；
• 两套主题：terminal-dark（终端暗色监控面板）和light-pastel（白底粉彩信息图，适合小红书）；
• 画幅预设：4:5（1200x1500，适配 X）、3:4（1080x1440，适配小红书）、1:1（1080x1080）。

下面是最小示例的动画预览：user → agent → tools三级面板，数据包沿连线流动，底部日志滚动，数字全部标注"示意"。

SKILL.md：让 Claude Code 和 Codex 学会"画图技能" 🧠

SKILL.md是 Agent Skill 的标准约定：任何会加载技能的 AI 助手（Claude Code、Codex 等）读到它，就掌握了一项新能力。这份文件的开头是标准的 frontmatter 元信息，name: live-panel加上description（用中英文写清了"什么时候该用这个技能"）：

当用户要做"活的"架构图、agent 树或系统监控面板风格的动画（mp4 视频或循环网页）时使用——固定布局、线上流动的数据包、滚动日志、翻转的计数器和状态条。

正文部分则给 AI 定了一套固定工作流，让它不会"自由发挥"翻车：

1. 收集内容并标注每个数字的来源——没有真实来源的数字必须标注"示意 / illustrative"，绝不伪造；
2. 用脚手架生成配置，再小步迭代——AI 不手写 20~40 KB 的大 JSON，而是先写一份几行的简短 spec，用 scripts/scaffold.py 自动完成像素布局、连线、数据包、日志列和文字换行，之后每次只改 1~3 个方框；
3. 渲染——用 scripts/render.py 出 mp4；
4. 按帧检查，不靠感觉——用 scripts/check_frames.py 采样约 120 个时间点，从 DOM 里测量文字溢出与元素重叠，导出 PNG 让你肉眼确认，并验证"回放确定性"（同一配置每次渲染逐帧一致）。

这套流程的核心参考还包括 references/motion-grammar.md（"快、中、慢"三档节奏的运动语法）和 references/config-schema.md（每个 JSON 字段的完整说明）。AI 照着执行，新手照着看也能明白它是怎么工作的。

快速上手：三步完成 SKILL.md 技能安装 📦

第一步：克隆仓库

git clone https://gitcode.com/gh_mirrors/li/live-panel-skill

第二步：放到 AI 助手加载技能的目录

以 Claude Code 为例，把整个文件夹放到（或软链到）~/.claude/skills/live-panel/；Codex 等其他读取 SKILL.md 的 agent 同理，放进它们的 skills 目录即可。

第三步：确认本地环境

不需要 API Key，不需要联网，Windows 用户可在 WSL 里原样运行。环境就绪后，对 AI 说一句话就行。

实战：一句话让 AI 生成 agent 架构动图 ✍️

在 Claude Code 里直接描述你想要的画面，例如：

画一个我们多 agent 系统的动态架构图：主 agent 下面有 worker、explorer、researcher 三个子 agent，左侧放三个 on-call 触发器，要有滚动日志和 token 计数器，暗色主题，4:5 画幅发 X。

AI 按 SKILL.md 的流程执行，背后的实际动作是这几条命令（了解即可，通常不用你敲）：

# 1. 简短 spec 生成完整配置（布局、连线、日志列自动完成） python3 scripts/scaffold.py --spec spec.json --out out/config.json # 2. 渲染 mp4（--html-out 额外保留可循环网页版） python3 scripts/render.py --config out/config.json --out out.mp4 --html-out out.html # 3. 逐帧自查：溢出、重叠、回放确定性，退出码 0 才算过 python3 scripts/check_frames.py --config out/config.json --out-dir frames --repeat

如果 AI 没按套路走，你也可以直接给它指条路："先抄 examples/codex-agents/config.json 改，不要从零写"——仓库里的每个示例都是一份"标准答案"，AI 从最接近的示例出发迭代，成功率远高于从头规划坐标。

输出效果：动态架构图与动图预览 🌟

以下是仓库自带的示例（每个示例目录下都有完整 mp4 和 config.json，可对照学习）：

① Codex agent 树（terminal-dark，4:5）——子 agent 分发、侧栏触发器逐个点亮、session log 滚动、calls / tokens read计数累加，是最经典的"监控面板"观感，配置见 examples/codex-agents/：

② AI Agent 完整架构（light-pastel，3:4）——同一套运动语法套在浅色信息图上：步骤列表逐行点亮、工具与 MCP 面板同步高亮、箭头变色并携带数据包，专为小红书 3:4 画幅设计：

③ ring 视图：循环流程——"规划→执行→验证→反思"这类循环结构不用手摆坐标，一个{"type":"view","kind":"ring"}元素自动环形排布，中心计数器记录迭代轮次：

④ loop 视图：带分支回环的工作流——判定菱形、虚线回环、人工闸门分组框，适合表达"发现不了就回工单"这类嵌套循环：

更多示例（funnel 漏斗图、中文内容的 Airbnb 面板、手绘风 excalidraw 视图等）都在 examples/ 目录，每个文件夹都附 config.json、mp4 与动画预览。

新手常见问题：需要 API Key 吗？能出 GIF 吗？❓

为什么同一配置每次渲染结果都一样？页面上每个视觉元素都是时间t的纯函数：不读系统时钟、不用Math.random()、不用 CSS 动画，"随机"选择用固定种子哈希。渲染器对每一帧调用window.seek(i/fps)截图，check_frames.py --repeat还会跳走再跳回来比对字节，保证确定性。

输出可以当 GIF 用吗？推荐先用 mp4（聊天软件和 X 对 mp4 更友好）。要 GIF 用 ffmpeg 一转即可：

ffmpeg -i my.mp4 -vf "fps=15,scale=600:-1:flags=lanczos" my.gif

放 README 的话，动画 WebP 体积约为 GIF 的 1/4 且发光效果更平滑，仓库里的预览图就是这么做的。

支持哪些图型？除了自由摆放方框连线，还有自动排版的"视图"元素：ring（循环）、funnel（漏斗转化）、loop（嵌套工作流+决策回环）、excalidraw（手绘风），契约见 references/views.md，验收命令是 scripts/verify_view.py（3 种画幅 × 2 种主题共 7 组组合全 PASS 才算完成）。nebula、tree、kpi等已在规划中。

画面上的数字是真的吗？只有你给了来源的才算真的——来源写在配置顶层的credit行；所有只因动画而跳动的计数器，画面上一律标注 "(illustrative)"。复刻别人的图时，credit和发帖文案里都要写原作者，这是 SKILL.md 的硬性署名规则。

小结：把"会动的架构图"变成一句话的事 🚀

live-panel-skill 把"画一张会动的架构图"拆成了三件事：描述系统 → 生成 JSON → 渲染自查，而 SKILL.md 让 Claude Code、Codex 这些 AI 助手完整接管了后两步。你只需要提供系统描述和数字来源，剩下的布局、运动节奏、逐帧检查都由技能流程保证。

• 技能入口：SKILL.md
• 完整文档与 FAQ：README.md
• 配置文件字段全集：references/config-schema.md
• 运动语法（快中慢三档节奏）：references/motion-grammar.md
• 示例配置库：examples/

把仓库放进你的 skills 目录，然后试着对 AI 说："帮我把我的系统画成一张会动的架构图"——剩下的，交给 live-panel-skill。