Community编程与开发github.com

antijank

捕捉截图无法捕获的单帧UI卡顿。记录真实浏览器中每次交互每一帧每个元素的位置和不透明度,并以几行文本报告哪些元素发生了跳跃、闪烁、无淡入弹出、推动相邻元素、反转、闪烁、突然滚动或对点击响应缓慢。可在您已有的浏览器(Chrome DevTools MCP、Playwright MCP)中运行,无需安装任何东西,也可通过其运行器无头运行。

antijank 是什么?

antijank 是一个 AI 智能体技能,用于检测 UI 动画和交互中的微卡顿和视觉缺陷。它通过在页面中注入一个探针,在每次绘制的帧后读取每个被监视元素的边界框、有效不透明度和滚动位置,精确报告如“一帧内向下移动 44px”等事实。该技能支持两种运行模式:A) 直接加载到您已有的浏览器工具中(如 Chrome DevTools MCP、Playwright MCP),无需额外安装;B) 使用 Node 22+ 和 Playwright 的运行器,适合 CI 场景,可一次性完成页面加载和矩阵测试。antijank 能识别超过 20 种异常类型,包括闪烁、跳动、弹出、闪退、慢帧和慢响应等,并提供期望断言(expectations)功能,将“看起来不错”转化为明确的通过/失败结果,有助于防止回归。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imomadjid/antijank/tree/main/skills/antijank

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

antijank 是做什么的?

量化测量运动,而非肉眼观察。探针在页面中运行,每次绘制帧后读取每个被监视元素的边界框、有效不透明度和滚动位置,仅报告异常。每次交互只需几行文本,无需逐帧检查。

它报告事实(例如“一帧内向下移动 44px”),而非主观判断。判断持续时间或缓动函数是否合适属于另一项审查。缺陷(闪烁、跳跃、抖动、推动相邻元素)优先报告;单纯缺乏过渡的变化(弹出、替换)被单独列出,因为“瞬间”往往是正确的选择。

选择运行方式

<skill-dir> 表示此技能的文件夹(即本文件所在目录)。

A. 您已有的浏览器:无需安装。 如果您已有浏览器工具(Chrome DevTools MCP、Playwright MCP,或可执行 JavaScript 的浏览器面板/扩展),将探针加载到您正在测试的页面中。它会保留该浏览器的登录状态,无需向项目添加任何内容。

您的工具加载探针
Chrome DevTools MCP使用 evaluate_script,参数为 sourcePath: "<skill-dir>/scripts/probe.js" 和 format: "script"
Playwright MCP使用 browser_run_code(某些版本为 browser_run_code_unsafe):async (page) => { await page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' }) }
您自己脚本中的 Playwright pageawait page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' })
仅支持评估 JavaScript 文本的工具评估下面的 CDN 加载器。如果被阻止,则直接评估 scripts/probe.min.js 的内容(42KB)

CDN 加载器获取此精确版本,完整性哈希使浏览器拒绝任何其他文件:

await new Promise((ok, fail) => {
  const s = document.createElement('script');
  s.src = 'https://cdn.jsdelivr.net/npm/[email protected]/skills/antijank/scripts/probe.min.js';
  s.integrity = 'sha384-gbt1FS2nRYbhwU3zqdkxuKbH6++BQeLIjkpVPLNNOwbu361o2lV0U6li+N879FDf';
  s.crossOrigin = 'anonymous';
  s.onload = ok;
  s.onerror = () => fail(new Error('antijank: CDN script blocked (Content-Security-Policy or offline)'));
  document.head.append(s);
});
  • 在同一页面上重复加载是安全的,但每次导航后都需要重新加载。
  • 严格的内容安全策略(Content-Security-Policy)会阻止脚本标签,因此 CDN 加载器和 addScriptTag 在这些页面上会失败。通过 DevTools(使用 sourcePath 的 evaluate_script,或粘贴 probe.min.js)评估文件内容不会被阻止。
  • 标签页必须可见。浏览器会暂停隐藏标签页和面板中的帧,探针随后会拒绝记录(status: hidden)。
  • 使用同一工具降低 CPU 速度并开启减少动效。在 DevTools MCP 中,先调用 emulate 参数 cpuThrottlingRate: 4,然后调用 prefersReducedMotion: "reduce";每次调用替换上一次,空调用重置。在 Playwright MCP 中,使用 browser_emulate_media 参数 reducedMotion: "reduce",对于 CPU,运行 const s = await page.context().newCDPSession(page); await s.send('Emulation.setCPUThrottlingRate', { rate: 4 })。
  • 要记录页面加载,探针必须在页面自身脚本之前运行。使用 Playwright,添加两个初始化脚本,然后加载页面并等待结果:
    await page.addInitScript({ path: '<skill-dir>/scripts/probe.js' });
    await page.addInitScript(() => antijank.start({ root: 'main' }));
    await page.goto(url);
    const result = await page.evaluate(() => antijank.wait());
    
    其他工具:使用运行器(B),它会默认记录加载过程。

B. 运行器:用于 CI、页面加载和单条命令完成完整矩阵。 它需要 shell、Node 22+ 和项目中的 Playwright,并以无头模式运行自己的 Chromium,因此可重复。

node <skill-dir>/scripts/run.mjs http://localhost:3000/inbox --click "button[aria-label='Compose']" --root main
node <skill-dir>/scripts/run.mjs http://localhost:3000 --steps steps.json --matrix
node <skill-dir>/scripts/run.mjs http://localhost:3000/settings            # records the page load

运行器仅支持 Chromium,并在 Node 上运行,与项目使用的任何技术无关。如果项目没有 Playwright,运行器会告知。使用项目已有的包管理器(查看 lockfile)添加,然后下载 Chromium:

锁文件添加 Playwright下载 Chromium
pnpm-lock.yamlpnpm add -D playwrightpnpm exec playwright install chromium
yarn.lockyarn add -D playwrightyarn playwright install chromium
bun.lock / bun.lockbbun add -d playwrightbunx playwright install chromium
deno.lockdeno add npm:playwright(在 deno.json 中设置 "nodeModulesDir": "auto",以便 Node 能找到它)deno run -A npm:playwright install chromium
package-lock.json 或无npm i -D playwrightnpx playwright install chromium

在向他人项目添加依赖前请先询问;选项 A 无需任何依赖。运行 node <skill-dir>/scripts/run.mjs --help 查看所有选项。运行器会为自己的浏览器关闭内容安全策略。

记录

当操作可以在页面内部运行时:

const result = await antijank.record(() => document.querySelector('#open').click(), { root: 'main' });
antijank.report(); // the text report

record 会等待操作的 Promise 完成后才让记录稳定,因此具有多个步骤的异步操作会被完整记录。

当您从页面外部驱动操作时(通过工具进行真实的点击和输入),保持记录开启直到完成:

antijank.start({ root: 'main', hold: true }); // 1. evaluate
// 2. click, type, wait: as many steps as the interaction needs
await antijank.release(); // 3. evaluate: settles after the last step, resolves with the result
antijank.report();

在点击元素前先悬停(DevTools MCP 的 hover,Playwright MCP 的 browser_hover),就像用户操作一样,并在第一次输入前至少一秒开始记录。直接跳转到元素上的点击会随按压开始其悬停效果,而自行更新的事物(时钟、实时计数器)需要那一秒被识别为已在变化;否则两者都可能被误认为是点击的响应。运行器在每次点击前都会悬停。

不使用 hold 时,记录会在没有任何移动约 330ms 后稳定,这可能会落在您的两个步骤之间。从未释放的 hold 会在 holdTimeout(默认 60s)后以错误结束。antijank.wait() 会在记录结束后解析结果;antijank.stop() 会立即结束它。

工作流程

  1. 决定要记录什么。 每次记录一个交互:触发器、应反应的页面部分(root)以及“完成”的含义。如果变化等待网络请求,传入 waitFor 参数,使用一个在内容到达后才会存在的选择器,否则记录可能在事件发生前就稳定了。
  2. 尽可能使用生产构建。 开发构建会重放效应(React StrictMode),热重载会引入停滞,因此动效可能与发布版本不同。如果必须使用开发版本,请在报告时说明。
  3. 记录并阅读报告。 严重性是一个起点:HIGH 几乎总是可见,LOW 通常可以接受。
  4. 决定哪些发现是有意为之。 未动画的变化与缺陷分开列出。对于标签页、菜单、工具提示以及任何频繁或键盘驱动的元素,瞬间变化是有效的选择,不要为了清除发现而添加动画。使用期望(expectation)固定预期行为,或将元素标记为 data-antijank-ignore。
  5. 为预期行为编写期望(如下所示)并重新运行。这将“看起来不错”转换为通过/失败,并且相同的规范可以在以后防止回归。
  6. 修复缺陷,然后重新运行。 最终检查时,分别在正常速度、CPU 减速 4 倍和减少动效条件下记录(运行器使用 --matrix,或选项 A 中的模拟调用),因为时序错误(慢速第一帧吞掉动画、延迟变换)通常只在 CPU 慢时出现。
  7. 使用数字报告, 例如“composer 在 170ms 内从 245 移动到 562px,其他元素均未移动超过 1px,三种条件下均无发现”。

发现及其通常原因

发现含义通常原因和修复
blip在错误位置停留了 1–3 帧,然后弹回FLIP 变换延迟一帧应用(在绘制之后)。在同一帧内测量并设置逆变换作为布局变化:使用 layout effect,而非 effect 或 rAF
jump (start)第一步很大,然后平滑移动动画从错误原点开始,或第一帧在起始值设置之前绘制
jump (end) / snap平滑移动,然后在结尾处突然跳跃错误的目标(过时的测量),或在布局匹配之前清除了变换
jump (mid)某一帧远大于其相邻帧动画中途布局发生变化(内容到达),或两个动画交接
shift静止元素在一帧内移动其上方有元素被插入、移除或调整大小且没有动画。[cause: …] 指定插入、移除或移动;[same frame: …] 指定同一帧内的调整大小,是可能的原因而非确证。对大小进行动画处理、预留空间或使用叠加
pop-in / pop-out以完全不透明度出现或消失(无动画)如果是有意的瞬间变化则正常。否则没有进入或退出动画,或进入过渡从未触发,因为起始样式从未渲染(在同一帧中添加了 class 又移除)
flash仅可见 1–2 帧占位符或陈旧状态渲染一帧;条件渲染反复切换
flicker不透明度下降后又恢复重新挂载(key 变化)、状态重置或退出动画重新开始
swap一个元素被另一个元素原位替换,无交叉淡入(无动画)对于标签页和即时视图正常。否则缺少共享元素或英雄过渡
reversal在移动过程中部分转向两个动画驱动同一个值,或重新定位到旧位置
oscillation方向逐帧翻转两个脚本冲突(滚动锚定对抗跟踪、ResizeObserver 循环)
resettle稳定后又再次移动延迟测量(字体、图片、异步内容)后的修正
overshoot远远超过目标弹簧回弹高于预期。如果是有意的弹跳则忽略它
stretch文本不均匀缩放对包含文本的盒子进行缩放动画;对其子元素应用反向缩放或动画化大小
scroll-jump / scroll-fight滚动位置跳跃或改变方向无平滑滚动的编程式滚动、滚动锚定或两个跟随者
slow-frame一帧耗时 50ms 或更多动画期间的主线程工作(已命名脚本)。“Forced layout” 表示脚本在更改样式后立即读取布局(offsetHeight、getBoundingClientRect),通常在一个循环中:先全部读取,再全部写入
slow-response点击、回车、空格或 Escape 在 100ms 或更多时间内无反应在工作或请求运行时没有按下或等待状态。立即显示一个。[cause: main thread busy …] 表示慢速处理程序阻止了响应的绘制
layout-anim对 width、height、top、margin 等进行动画每帧触发布局。对于小手风琴可以接受;对于大型或频繁的动效,优先使用变换

动效发现会命名在那一帧正在移动元素的动画,或其祖先的动画:[animation: transition transform 300ms ease-out]、[animation: animation slide-in 400ms ease on div.panel] 或 [animation: Web Animation of opacity, transform 200ms linear]。首先转到该规则或调用。如果没有命名动画,通常意味着动效由脚本驱动(requestAnimationFrame、弹簧库)或根本没有动画。

期望

传入 expect(选项或 --expect)以获取通过/失败行,并在失败时退出码为 1:

{
  "moves": { "[data-composer]": { "dy": 317, "tolerance": 2 } },
  "still": "others",
  "maxShift": 1,
  "fadesIn": [".toast"],
  "fadesOut": ["[role=dialog]"],
  "noFindings": "medium"
}
  • moves:从第一帧到最后一帧的净位移,以 px 为单位。如果元素被重新挂载,它会跟踪屏幕上的任意副本。
  • still:必须不能移动超过 maxShift 的元素。使用 "others" 表示全程存在且未在其他地方指定的所有元素。匹配不到任何元素的选择器会导致失败。
  • fadesIn:元素在其第一个可见帧时透明度必须低于 50%,结束时为 90% 或更高。fadesOut:在其最后一个可见帧时透明度低于 50%。
  • noFindings:没有达到或高于该严重程度的发现,包括未动画的发现。
  • 运行器的 --fail-on <severity> 在出现达到或高于该严重程度的缺陷时退出码为 1。未动画的变化不计入;应使用 fadesIn 或 fadesOut 要求淡入淡出。
  • 任何匹配不到元素的选择器都会导致其期望失败,因此拼写错误不会静默通过。

保持报告有用

  • 使用 root 限定到应反应的区域。这样更快且更安静。仍然会监视在其外部添加的叠加层:直接添加到 <body> 的元素、固定定位元素,以及对话框、菜单、弹出窗口、工具提示和 toast(通过 role、aria-modal、popover 或 <dialog> 查找)。
  • 一个尚不存在的 root 会被等待。当它出现时其中包含的内容即为基线,因此要判断面板如何出现,请使用在其出现之前就已存在的 root(或省略)。
  • 一次性插入(或移入,如流式 HTML)的子树会作为一个发现报告,包含子树名称及其包含的元素数量。
  • 只有绘制某些内容(文本、背景、边框、阴影、背景滤镜、::before/::after 内容、图片、表单控件)的元素才能产生发现。透明包装器保持静默,因此它们绘制的子元素会进行报告。
  • 无限 CSS 和 Web 动画(旋转器、闪烁)会被自动忽略。永不停歇的 JavaScript 循环会...

…(已截断用于翻译)

相关技能