mobile-demo-record 是 superset-sh/superset 仓库中的移动端演示录制技能，用于在 iOS 模拟器上运行 apps/mobile 并连接本地服务栈，再用 Maestro 驱动操作，最终获得干净的屏幕录像。该技能特别说明：移动端没有 CDP，因此使用无界面启动的 iOS 模拟器、Maestro 和 simctl 录制，整个过程中不会在用户显示器上打开窗口。
用途与原则 技能面向“录制或拍摄移动应用演示”的场景。规则要求只录制真实应用状态，包括真实会话、真实拉取请求和真实页面，禁止使用模拟稿或仿 DOM 造假；需要预置故事所需数据，录制后删除。画面中不得出现真实数据：使用开发账号 admin@local.test 与带演示项目的演示组织，分享前逐帧检查联系人表里的姓名、邮箱、仓库名和令牌。每个故事只拍一次；对已连接过的主机或已读页面，需要在每次拍摄前重置或重新播种状态。录制后应报告 worktree、API 端口、模拟器 UDID 和应用构建日期。
服务栈准备 每个服务在独立的 Superset 终端启动，命令通过 superset terminals create --local --workspace $SUPERSET_WORKSPACE_ID --command "..." 执行，缺少 --local 会静默返回空。端口取自 .superset/ports.json 与根目录 .env。API 用 cd apps/api && bun run dev；若出现 500“password authentication failed”，说明该 worktree 的 Neon 分支被清理，需要重建并改写 .env 中的“# Workspace Database”行。Relay 用 wrangler dev 循环启动，因为客户端中断请求会让 wrangler dev 以空错误退出。Metro 用 cd apps/mobile && CI=1 bunx expo start --dev-client --port 8081，CI=1 会禁用文件监听，改代码后需重启；还需先用 curl -H 'expo-platform: ios' localhost:8081 预热首个 bundle。apps/mobile/app.config.ts 以 override: true 加载仓库根 .env，因此本地 bundle 总指向当前工作区的 API。
模拟器与驱动 通过 xcrun simctl 查找并启动 iPhone 17 Pro，设置浅色外观、覆盖状态栏时间与电量，写入跳过开发菜单引导的偏好，并用 openurl 打开开发客户端；simctl boot 不会启动 Simulator.app。状态栏覆盖在关机后失效，每次启动后需重设。若无开发客户端或原生依赖变更后崩溃，需执行 expo prebuild、xcodebuild（约 10 分钟）后 simctl install，并设置 SENTRY_DISABLE_AUTO_UPLOAD=true，且不得设置 CODE_SIGNING_ALLOWED=NO。Maestro 需要设置 JAVA_HOME，流程放在 apps/mobile/.maestro/flows/，通过 dev-sign-in-button 登录，每个故事写一个流程，优先按可见文本点击，文本有歧义时加 testID；inputText 逐字符输入，看起来像人在打字。Maestro 启动需 7 到 25 秒，应在开始录制前启动，并用 waitForAnimationToEnd 或 extendedWaitUntil 让开头停在稳定画面。开发会话 plan 为 null，首页会显示付费墙，需要临时在 Neon 分支插入 plan pro 的订阅行并在结束后删除。
录制与后处理 在临时目录中执行：mkdir -p raw shots cfr，用 xcrun simctl io $U recordVideo --codec h264 --force 录制，同时运行 maestro test 流程，之后仅用 SIGINT 停止录制，否则文件不可播放。recordVideo 只在画面变化时写帧，文件为可变帧率，需先用 ffmpeg -vf fps=30 转为恒定帧率再选剪辑点；亚秒级闪烁无法用截图捕捉，应先录制再抽帧。技能还列明页面功能需要额外的对象存储、Worker 密钥和传输安全设置，以及 tRPC 脚本调用所需的授权头；截屏和录像保留在临时目录，除非用户要求放入仓库。
限制与清理 页面在本地需自建 S3 替身、复制对象到本地 R2、配置 USERCONTENT_TOKEN_SECRET，并在模拟器已安装副本上修改 Info.plist 允许本地网络，结束后恢复。Maestro 按完整无障碍标签匹配，可用正则和 hierarchy 排查。录制后只删除本次创建的数据行与对象，恢复被改动的组织或用户名，停止所有启动的服务，恢复模拟器原外观、字号和 AppleLanguages（原本未设置则移除），还原传输安全修改，清除状态栏覆盖并关机。