SuperAPI AI 工具集

pr-lens-diagrams

编程与开发

查看项目

更新于 10-20 12:25

技能介绍

PR Lens Diagrams 用于制作动画架构图与数据流图。底层工具为 PR Lens(MIT,https://prlens.dev),它把一份 JSON 图文档渲染成自包含的动画 SVG,动画通过 SMIL 的 <animateMotion> 实现,不依赖脚本。模型密钥只在 analyze 模式下需要(从 git diff 生成图);绘制任意示意图时,由智能体直接手写 JSON。

用途与输出

该技能面向“把系统结构或数据流画成动画图”的场景:先手写 graph.json,经校验后渲染为动画 SVG,并录制帧编码为 GIF 与 MP4。渲染默认深色主题,也可选择浅色或双主题输出。

快速开始

依赖:Node >= 20.11、npm、ffmpeg;Chromium 由 setup 脚本安装。

bash scripts/pr-lens-setup.sh # 安装到 $PR_LENS_HOME(默认 ~/.cache/pr-lens-diagrams) bash scripts/pr-lens-build.sh my.graph.json out/ # 输出 out/architecture.{svg,gif,mp4} 与 out/data-flow.{svg,gif,mp4}

可从 examples/bots.graph.json 起步(4 条泳道、12 个节点、12 条边、1 个 flow)。build 脚本会执行校验、渲染(默认深色;第 3 个参数可选 light 或 both)、用 Playwright 以 deviceScaleFactor: 2 录帧,并编码非抖动 GIF 与 MP4(crf 18)。

环境变量:PR_LENS_HOME、FPS(20)、MIN_WIDTH(1600)、PR_LENS_CLI_VERSION、PLAYWRIGHT_VERSION。

注意:npx skills add coldteadotai/pr-lens 在 Node 20 上会崩溃(fs/promises 没有 glob),并非必需。与版本匹配的文档可在 $PR_LENS_HOME 内通过 npx pr-lens skill / npx pr-lens skill references 查看。

未经用户明确同意不要发布:pr-lens canvas push 会把图放到 prlens.dev,任何持有查看链接的人都能打开。

文档结构(schemaVersion 0.2.0)

必填:schemaVersion、kind: "graph"、title、lenses、provenance、lanes、nodes;另有 edges 与 flows。

provenance 即使没有仓库也必须提供(可用占位 owner/name 与 40 个零的 sha)。

lanes 是按顺序从左到右的列,没有“顶部”概念,最左侧泳道即起点。

节点类型:service|app|module|function|route|job|queue|datastore|cache|external|ui|config|test|package|other。边类型:call|http|rpc|event|queue|data|dependency|render|other;emphasis:normal|hero|muted;animated: true。

普通示意图在所有节点使用 delta: "unchanged"。layout: { direction, laneOrder, rank } 只是提示,不是坐标。

动画机制

架构图:带动画的边携带一个圆点(1.6 秒);hero 边携带 3 点列车(2.1 秒,间隔 0.7 秒)并带光晕。无缝循环周期为 LCM(1.6, 0.7) = 11.2 秒。

数据流图:在 lenses 中加入 "data-flow" 并编写 flows[](participants 为节点 id;消息类型 sync|async|return|self)。步骤按数组顺序依次点亮;循环长度取 SVG 中的 dur(7 步 → 9.8 秒,最长 16 秒)。

walkthrough 与 payload 仅在 prlens.dev 画布上播放。

resvg、cairosvg、rsvg 等光栅化工具会忽略 SMIL;应在浏览器中用 pauseAnimations() + setCurrentTime(t) 捕获(scripts/record.mjs)。

美观与质量要点

节点不超过 10–12 个,边约 12 条。相似对象合并为组节点,成员列在 subtitle 中;用聚合节点或其 subtitle 表达“所有节点 → X”。

使用 3–4 条泳道,流向从左到右(输入 → 编排器 → 工作节点 → 输出),避免空泳道或过载泳道。

每行一张卡片:同一泳道中同 rank 的节点会并排、变窄并截断,因此同泳道每个节点应各给一个 layout.rank。Rank 是下限(≥ 前驱 + 1),用 0,1,2,3… 的阶梯;行在各泳道间共享,相连邻居应取相同 rank 以获得直线边。

标签要短:窄卡片 subtitle 约 20 字符,宽卡片约 45 字符。

hero 只用于 1–2 条关键路径;次要边用 muted;显而易见的边不加标签。

数据流宽度约每参与者 320 px,参与者不超过 6–7 个。

主题选择:第 3 个参数为 dark(默认,在聊天中阅读效果最好)、light 或 both(输出 <lens>-dark.* 与 <lens>-light.*)。目标页面会切换主题时(如 GitHub <picture>、nopaste、文档站)选 both;只能放一张图时匹配读者主题。

调色板:PALETTE=github(默认渲染器颜色,深色底 #0d1117,浅色底 #ffffff)或 PALETTE=nopaste(paste.goldfinches.ru 配色:深色 #212427/强调色 #8ab4f8,浅色 #e6ddd2/强调色 #176b62)。差异色(added/modified/removed)永不改变。

以 DPR 2、CSS 宽度 ≥ viewBox 宽度且 ≥ 1600 px、20 fps 录制。

GIF 使用 palettegen=max_colors=128:stats_mode=diff 与 paletteuse=dither=none:diff_mode=rectangle,用 lanczos 缩放到 CSS 宽度(约 11 秒约 1 MB);MP4 保持完整 2x。

Telegram 与多数聊天不播放动画 SVG,应发送 GIF/MP4;GitHub PR 评论可显示动画 SVG。

交付前按 1:1 裁剪 GIF 帧检查,缩小预览会掩盖模糊。

渲染输出文件名带哈希;build 会复制为稳定的 <lens>.svg。

智能体工作流

列出实体并归并为 10–12 个节点,确定 1–2 条主路径(hero)。

复制 examples/bots.graph.json 并修改:泳道、带 layout.rank 阶梯的节点、边,必要时加 flows。

运行 bash scripts/pr-lens-build.sh graph.json out/;若 validate 指出字段错误,修正后重跑。

检查录出的帧:无截断标签、无成对卡片、无交叉;按需调整 rank 与标签。

把 GIF 或 MP4、graph.json 源文件与 SVG 交付给用户。

限制

动画 SVG 在多数聊天客户端中无法播放,需转 GIF/MP4;SMIL 不被常见光栅化工具支持,需浏览器捕获。发布到 prlens.dev 需用户明确同意。graph.json 结构错误会被校验拦下。