mcpField
B
baguette

baguette

github.com/tddworks测试与质量2.3k69 次安装1 天前更新
代码仓库

关于 baguette

baguette 是通过 Apple 的 SimulatorHID 控制 iOS 模拟器的 macOS 命令行技能，适用于 Agent 和开发者执行交互、查看屏幕并验证应用行为；不支持控制实体设备。

主要功能

  1. 01启动并列出模拟器
  2. 02执行触摸、滑动和文本输入
  3. 03截取屏幕并查看界面信息
  4. 04设置应用运行环境
  5. 05通过 JSON 连续发送手势

适用场景

  1. 01测试修改后的 SwiftUI 界面
  2. 02自动执行模拟器交互
  3. 03检查手势后的应用行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tddworks/baguette --skill baguette

安装后在 Claude Code 中输入/baguette确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
apps.md
commands.md
devices.md
environment.md
interact.md
observe.md
wire.md

详细介绍

baguette — 以编程方式控制 iOS 模拟器

baguette 是一款 macOS 命令行工具，通过 Apple 的私有 SimulatorHID（Xcode 内部使用的路径）驱动 iOS 模拟器：对于输入操作，它比 idb / AXe / simctl io 更快、更可靠。Agent 使用命令行工具；想要观看或一起操作的用户，应使用 baguette serve 和 http://localhost:8421/simulators/<udid>。

操作循环

几乎所有任务都是：获取设备、操作、查看、重复。

baguette list --json                                    # 1. a booted UDID
baguette boot --udid <UDID>                             #    (if none is running)
baguette describe-ui --udid <UDID> | jq .screen        # 2. its size in points
baguette tap --udid <UDID> --x 219 --y 478 --width 438 --height 954   # 3. act
baguette screenshot --udid <UDID> --output /tmp/frame.jpg             # 4. look

然后读取 /tmp/frame.jpg。如果轻点返回 {"ok":true}，但没有任何反应，请运行 baguette heal --udid <UDID>（Xcode 27 的 Device Hub 接管了输入界面；请参阅 references/devices.md）。

坐标单位是设备点（请务必阅读）

每个 x / y / startX / endX / x1 / cx … 都以设备点为单位， 与传入的 width / height 使用相同单位。438×954 屏幕的中心是 x:219, y:478：不是 0.5, 0.5（归一化坐标），也不是 1206, 2622（像素）。从每台设备的 describe-ui 外层 screen 获取 width / height，旋转或折叠后重新读取；返回的帧也使用相同单位，因此元素中心坐标可以直接用于轻点。不要使用 chrome layout：它的 screen 是边框图片的尺寸，不是设备点坐标。

你需要做什么？

只阅读当前任务所需的参考文档。

你想要……阅读命令
启动设备、调整尺寸、旋转、折叠；修复输入无处生效的问题references/devices.mdlist boot shutdown heal orientation hinge
像用户一样操作：触摸、拖动、按按钮、输入文字、粘贴references/interact.mdtap double-tap swipe pinch pan input press type key paste clipboard
检查发生了什么：查看画面、查找元素、读取日志、录制references/observe.mdscreenshot describe-ui logs record stream render-3d
设置应用运行时的条件references/environment.mdlocation motion network interface status-bar notify shake，相机（仅限 WebSocket）
安装应用及其数据并启动应用references/apps.mdinstall add-media openurl schemes defaults，simctl launch

还有两个文档，由 make docs 从二进制文件生成（不要在此处编辑）。 references/commands.md 包含所有子命令、标志和退出代码；文件很长， 因此只阅读某个命令对应的章节，而不是整个文件： grep -A25 '^## baguette swipe' references/commands.md（子命令使用 ### baguette location set 的格式）。references/wire.md 包含 input 和 WebSocket 的所有 JSON 手势。

单次调用或流式输入

只需少量步骤时，每个手势使用一条命令即可；每条命令都要支付 HID 初始化开销（约 50–100 毫秒）。如果要拖动、编排操作或执行许多步骤，请打开 baguette input --udid <UDID> 一次，并逐行写入 JSON 手势（references/interact.md）。无论哪种方式，ok:true 都只表示已发送，并不代表屏幕已响应：请用屏幕截图确认。

应明确说明的限制，而不是等到发现后再说

  • type / key 使用美国英语 ASCII 击键。其他内容（重音符号、CJK、表情符号） 应通过 baguette paste --text "…" 输入。
  • press --button siri 会被拒绝：所有已知路径都会导致 backboardd 崩溃。
  • motion、network 和相机仅对启用后启动的应用生效；请重新启动应用一次（之后执行 network set 或 clear 则不需要）。
  • 闲置屏幕可能不会产生任何帧，因此 screenshot 会超时；先轻点一下唤醒屏幕。
  • 仅支持模拟器：尚未接入实体设备控制。

冒烟测试

#!/usr/bin/env bash
set -euo pipefail
UDID="$1"
read W H < <(baguette describe-ui --udid "$UDID" | jq -r '.screen | "\(.width) \(.height)"')

baguette press --udid "$UDID" --button home
sleep 0.4
baguette tap --udid "$UDID" --x $((W * 75 / 100)) --y $((H * 55 / 100)) --width "$W" --height "$H"
sleep 0.5
baguette screenshot --udid "$UDID" --output /tmp/settings.jpg

确定一次尺寸，并将其传给每个手势。与其猜测位置，不如使用 baguette describe-ui 查找元素，然后轻点其中心。

与 Claude Code 配合

编辑 SwiftUI 应用时：构建并运行 → press --button home，然后轻点进入更改后的屏幕 → screenshot 并 Read 截图 → 确认像素效果符合预期。为便于用户跟进，启动 baguette serve，并将 http://localhost:8421/simulators/<udid> 提供给他们；它还支持键盘输入、拖放安装和功能卡片。baguette plugin 和 baguette bakery 可扩展该页面（参见 commands.md）。

各功能指南：https://github.com/tddworks/baguette/blob/main/docs/features/<feature>/README.md。

安装（仅在缺少时）

brew install baguette
baguette --version

需要在 Apple Silicon 上运行 Xcode 26 或更高版本。如果 baguette 已能正常运行，请跳过此步骤；不要每次调用都重新安装。

评论

支持 Markdown