如何将Scrawl接入Claude Code:让AI Agent自动看懂并修复界面问题的完整教程

原创2026-10-31 20:56:411,693 阅读

如何将Scrawl接入Claude Code:让AI Agent自动看懂并修复界面问题的完整教程

Scrawl 是一个"把问题直接展示给 Agent"的录屏标注工具:按一下 ⌥⇧S 开始录屏,边说边用红笔圈画问题,再按一次结束,它就会把屏幕、语音、点击和标记打包成一个 .scrawl 捕获包。本教程教你把 Scrawl 接入 Claude Code,让 AI Agent 像读 Bug 报告一样读你的录屏,自动定位并修复界面问题,无需再费力打字描述"这里有点怪"。

Scrawl 是什么?

传统报 Bug 的方式是:文字描述 + 截图 + "大概就是这个位置"。AI Agent 拿到这种描述只能猜。

Scrawl 的思路完全不同——录屏即 Bug 报告。它会自动完成三件费人工的事:

  • 智能关键帧:只在点击、绘制、场景变化等真实事件处截取帧(见 src/keyframes.rs),静止画面说话再久也不会截一堆废帧;
  • 语音转写对齐:本机语音识别(Apple Speech / Hex / 自定义命令)把每句话对齐到对应关键帧(见 src/transcribe.rs);
  • 自动裁剪:根据你的手势位置把每张关键帧裁剪到活动区域,让 Agent 的"注意力"花在有信号的地方(见 src/autocrop.rs)。

下面这张图就是 Scrawl 的工作方式:红色圈线标出按钮排错位,箭头指向证据,旁边还有语音备注——这就是 Agent 收到的"第一手材料"。

Scrawl 录屏标注界面:红笔圈出部署活动列表中的问题并配语音说明

第 1 步:安装 Scrawl

Scrawl 需要 Apple 芯片的 Mac(macOS 15+)或 Windows 10 2004+(预览版)。Mac 上用 Homebrew 一条命令搞定:

brew install --cask kitlangton/tap/scrawl

首次启动会进入欢迎引导,依次授予屏幕录制、麦克风、辅助功能三项权限即可(详见 README.md 的 Welcome and permissions 一节)。

第 2 步:给 Claude Code 装上 scrawl 技能

这一步是让 Agent"认识"Scrawl 的关键。Scrawl 自带一份 Agent 技能文档 skills/scrawl/SKILL.md,教 Agent 如何解读捕获包、如何调用 CLI 放大细节。一条命令安装:

bunx skills add kitlangton/scrawl

该技能同样支持 OpenCode、Codex 等其他 Agent。你也可以直接运行 scrawl skill 查看技能全文,或到 Scrawl 的 Settings › Agents 面板里一键复制安装命令(逻辑在 src/settings.rs 中定义)。

第 3 步:安装 scrawl 命令行工具

技能里会教 Agent 使用 scrawl 命令去放大时间片段、提取帧。这个命令是 Scrawl.app 自带的二进制,需要链接到 PATH:

  • Homebrew 用户:cask 安装时已自动链接;
  • 其他用户:在 Settings › Agents › Command-line tool 旁边点 Install,它会链接到 /opt/homebrew/bin、/usr/local/bin 或 ~/.local/bin(实现见 src/command_line.rs)。

验证一下:

scrawl --help

第 4 步:像开发者一样录一个 Bug

  1. 按 ⌥⇧S 开始录屏(录指针所在的显示器,自动裁剪);
  2. 正常操作出问题的界面,边操作边说:"这个按钮点了没反应""这里应该弹个提示";
  3. 按住 ⇧ + 拖动,画红色标记圈出问题;⇧ + 单击可落下带编号的图钉;
  4. 按 ⌥⇧S 再次结束。

结束后,捕获包生成在 ~/Library/Application Support/scrawl/captures/,核心文件包括:

文件 内容
contact-sheet.png 所有关键帧拼成的总览图(带编号)
frames/frame-XX.png 全分辨率关键帧
summary.md 时间对齐的转写 + 操作时间线
scrawl.json 完整结构化清单(标记、事件、词级时间戳)
recording.mp4 / audio.wav 原始音视频

下面这张 contact sheet 就是 Agent 首先看到的"案情总览":左侧是操作前的界面,右侧用红圈标出了你指出的输入框问题,编号与 summary.md 一一对应。

Scrawl 生成的 contact sheet 关键帧总览,红圈标注了界面上被指出的输入框问题

第 5 步:粘贴给 Claude Code,让它修复

录完按 ⌥⇧V,Scrawl 会把 contact sheet 图片和 summary.md 文本一起贴进前台应用。切到 Claude Code 的输入框(或任意终端),⌘V 粘贴后你会看到形如这样的内容:

[scrawl 0:33 · OpenCode "Settings" · /Users/me/Library/…/scrawl-1792432139176.scrawl]
Open contact-sheet.png and frames/ in that folder before changing anything…
- #1 (0:04) [clicked "New tab"] "Command T makes a new session, but here it should make a tab."
- #3 (0:10) ⚑ "It says command shift B makes a new tab."

然后直接对 Claude Code 说:"看看这个 Scrawl 捕获,修掉里面的问题"。

装了技能的 Agent 会按 skills/scrawl/SKILL.md 的流程工作:

  1. 先打开 contact-sheet.png 总览图,通读转写;
  2. 需要细节时运行 scrawl zoom <bundle> --at 0:10(按时间点)或 --at "the width changes"(按你说过的原话)生成高密度放大图;
  3. 用 scrawl inspect <bundle> --marks 查每笔标记画在哪里;
  4. 定位到代码后直接改,并用"#3 (0:10)"这样的编号回应你,方便你在总览图上对照。

💡 小技巧:说不清"哪里"的时候,录屏 + 画圈 + 一句"这里不对"就够了——这正 Scrawl 的设计初衷:Show an agent a problem instead of describing it.

常用 scrawl 命令速查

命令 作用
scrawl zoom <bundle> --at 0:21 放大某个时刻前后 2 秒的帧(可用你说过的短语定位)
scrawl zoom <bundle> --mark 2 聚焦 ✎② 那笔标记画出的瞬间
scrawl frames <bundle> --from 0:04 --to 0:06 提取一段区间的普通 PNG 帧
scrawl inspect <bundle> 打印 summary.md 文本
scrawl export latest --zoom 导出带自动镜头、烧录标记音画的 .mp4 分享给别人
scrawl skill 打印当前安装的 Agent 技能全文

更多用法见 README.md 的 Usage 一节,路由与投递机制详见 docs/iphone-and-routing.md。

常见问题

  • Agent 说找不到 scrawl 命令? 回到 Settings › Agents 点 Install,或临时用完整路径 /Applications/Scrawl.app/Contents/MacOS/scrawl。
  • 语音识别错词? 正常现象。技能会提醒 Agent "文字与画面冲突时以画面为准",转写只作线索。
  • 视频被清理后还能放大吗? 7 天后 recording.mp4 会被移入废纸篓(可在 Settings › Storage 改为永久保留),但 contact sheet、关键帧和 scrawl.json 仍然可用,粘贴给 Agent 完全不受影响。
  • Windows 用户? 快捷键为 Alt+Shift+S / Alt+Shift+V,命令行工具在 Settings › Agents 中安装为 scrawl.cmd。

总结

接入流程回顾:装 Scrawl → 一条命令装 Agent 技能 → 链接 scrawl 命令 → 录屏 + 标注 + 口述 → ⌥⇧V 粘贴给 Claude Code。从此"界面哪里坏了"不再靠嘴描述,而是圈出来、说出来,让 AI Agent 自己看懂并动手修复。

登录后查看全文
scrawl