如何将Scrawl接入Claude Code:让AI Agent自动看懂并修复界面问题的完整教程
如何将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 收到的"第一手材料"。
第 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
- 按
⌥⇧S开始录屏(录指针所在的显示器,自动裁剪); - 正常操作出问题的界面,边操作边说:"这个按钮点了没反应""这里应该弹个提示";
- 按住
⇧+ 拖动,画红色标记圈出问题;⇧+ 单击可落下带编号的图钉; - 按
⌥⇧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 一一对应。
第 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 的流程工作:
- 先打开
contact-sheet.png总览图,通读转写; - 需要细节时运行
scrawl zoom <bundle> --at 0:10(按时间点)或--at "the width changes"(按你说过的原话)生成高密度放大图; - 用
scrawl inspect <bundle> --marks查每笔标记画在哪里; - 定位到代码后直接改,并用"#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 自己看懂并动手修复。

