摄像头
${CLAUDE_SKILL_DIR}/cam.py：使用标准 Python 库加 ffmpeg，仅限 macOS。每张图像会在 Claude 看到之前进行裁剪和缩小：一张粘贴的手机照片大约消耗 1,600 token 并保留在上下文中，而一张 512 像素的快照仅消耗约 260 token。每个命令会打印保存路径、大小和 token 消耗；仅当你真正需要查看时才 读取 该路径。
首次运行（新用户或新 Mac）
如果 ~/.claude/camera-state/config.json 不存在，或者任何捕获失败，请运行：
python3 ${CLAUDE_SKILL_DIR}/cam.py setup
它会检查 macOS，如果缺失则通过 Homebrew 安装 ffmpeg，构建 ClaudeCam 辅助应用，列出摄像头，拍摄一帧测试图像（这会触发 macOS 摄像头权限提示），并保存配置。它会打印 READY，或带编号的 YOU: 步骤。用简单语言将这些步骤转述给用户，等待，然后重新运行直到显示 READY。 不要在没有说明原因的情况下就退而求其次要求提供照片。
用户需要了解的内容（setup 也会解释）：一部运行 iOS 16+ 的 iPhone XR 或更新机型，使用相同的 Apple ID，开启 Wi-Fi 和蓝牙，并启用连续互通相机；手机锁定、静止并连接充电器；点击“允许”以使“ClaudeCam 想要访问摄像头”。Mac 摄像头可作为备用（--cam mac）。
根据任务选择命令
| 用户想要... | 命令 | 备注 |
|---|---|---|
| 快速查看 | snap [--crop x,y,w,h] [--grid 4x3] | 512 像素。首次查看后裁剪至主体 |
| 对比状态 | sheet --n 4 --every 30s | N 帧平铺成一张图像 |
| 被告知某事发生 | watch --every 30s --until-change | 静默直到变化发生；会命名区域 |
| 随时间推移的进度照片 | timelapse --every 15m --for 6h | 每次构图相同 |
| 监控 3D 打印 | print locate → print use <ids> → print monitor --every 5m --for 3h | 当打印头清晰时拍摄 |
| 记录组装/构建过程 | step "将轴承压入轮毂" --project NAME [--note "..."] | 照片加上 steps.md 中的编号条目 |
| 产品演示视频 | clip --seconds 20 [--fps 60] [--audio] --project NAME | MP4 加关键帧快照表 |
| 从图片生成视频 | compile <文件夹> [--match 'x-*.jpg'] [--fps 8] | 延时摄影、监控或步骤 → MP4 |
| 检查设置 | doctor / setup / devices |
如需为任何定时操作设置间隔菜单：5m · 10m · 15m · 30m · 45m · 60m，或任意 90s / 2h / 48h（纯数字表示秒）。提供一个合理的默认值：打印用 5m，固化、胶合或干燥用 15–30m，持续数天的缓慢过程用 60m。
长时间运行的任务（timelapse，watch，print monitor）：使用 run_in_background 运行，命令为 python3 -u ... | tee <out>/run.log。它们每帧打印一行，并在某帧失败后继续运行。不要读取每张图像：在日志中搜索 failed / WARNING，当某行看起来异常时查看，并在结束时查看。
项目。 --project NAME 会在当前目录或父目录中查找 projects/NAME/。如果在项目文件夹内运行，则无需该标志即可工作。输出会存入 projects/NAME/media/{cam,steps,clips}/。如果没有项目，输出会存入 ~/Pictures/claude-cam/<date>/，而 --out DIR 会覆盖两者。在完成一系列 step 或演示 clip 后，可主动提议在项目的日志（如果存在）中添加一行，链接到生成的媒体文件。
设计与原型制作中的使用范例
工业设计、产品设计和创客工作流程，映射到上述命令。当存在项目文件夹时，务必添加 --project NAME，以便媒体文件随项目一起存储。
| 流程中的时刻 | 操作 |
|---|---|
| 草图捕捉（纸质草图、马克笔） | snap --cam desk --width 1600 --label sketch-<主题>。桌面视图可以俯视看到桌面上的纸张。每个概念使用一个标签，以便迭代结果按顺序排列 |
| 草图或模型迭代墙 | 在 --match 'sketch-*' 集合上以 1–2 fps 运行 compile，或使用 sheet，并排比较变体 |
| 泡沫、粘土或纸板模型迭代 | step "v3：握把收窄 4 毫米" --note "手感更好，拇指托位置偏低"，每次迭代一个步骤。steps.md 成为设计依据的记录 |
| CMF 色样（颜色、材质、表面处理） | 桌面视图，均匀的自然光，画面中包含白色或灰色卡纸；snap --width 1280 --label cmf-<名称>。每次光照条件相同，否则无法比较颜色 |
| 配合与公差检查 | snap --crop ... --width 1024，画面中包含尺子或卡尺。将数值写入项目的公差记录中，而不仅仅是照片 |
| 人机工程学：手持和使用中照片 | 用户改变握持姿势时，sheet --n 6 --every 3s：一张图像包含所有姿势 |
| 转盘产品拍摄 | 手机固定在支架上，产品放在懒人转盘上；用户每听到一次提示音旋转 45°，运行 sheet --n 8 --every 4s。如需视频片段：clip --seconds 20 --fps 60，缓慢旋转一圈 |
| 机械或演示视频 | clip --seconds 15 --fps 60 [--audio]；检查关键帧快照表；如果构图不佳则重新拍摄。使用 MP4 进行 Remotion 或其他编辑 |
| 组装或构建指南 | 按顺序对每个操作执行 step（--cam desk）；steps.md 就是指南；compile --fps 1 生成幻灯片 |
| 胶合、固化、干燥、降解 | timelapse --every 15m --for 24h（后台运行）；结束时运行 compile |
| 打印件 | 下方的 3D 打印模式 |
| 用户测试或协同设计会议 | clip --audio 仅在获得参与者明确同意的情况下，并说明录制内容和保存位置。优先拍摄手部和产品而非面部。将录制内容保存在项目文件夹内，切勿放在共享或公共位置 |
首先设置好拍摄场景
在第一次真正拍摄前，针对此任务具体告诉用户如何放置手机：使用哪个摄像头、手机放在哪里、距离多远、画面中必须包含什么，以及一个比例参考。
- 桌面视图（
--cam desk）：手机夹在 Mac 屏幕顶部，后置摄像头朝向用户。这提供了桌面的俯视图，非常适合记录桌面上的零件step。 - 主摄像头（
--cam phone）：使用任何支架或三脚架对准主体。对于打印机，放置得更高更远，约 45° 角，这样打印头就不会遮挡零件。 - 均匀的光线，画面中不要有窗户（自动曝光漂移会被视为变化）。每次都使用相同的位置（贴胶带标记），并在尺寸重要时在画面中放入尺子或已知物体，因为未缩放的图像无法提供毫米级信息。
- 通过连续互通相机没有光学变焦：“变焦”意味着在 1920×1440 的原始帧上使用
--crop配合更大的--width。要获取真正的细节，需要将手机移近。
然后拍摄一张完整快照，找到主体，并在本次会话的其余部分保留该 --crop。如果某个数字（如打印机 API 读数、测量值）已经回答了问题，则跳过图像。对于重复检查，将查看任务委托给子代理（“读取 <路径>；用一句话回答 <问题>”）：它的图像永远不会进入主上下文。
文档与视频（cam_studio.py）
- step：1280 像素照片（文档质量，如果读取则约 1,600 token；不要仅仅为了检查而读取它们）。编号为
NN-简称.jpg的文件加上包含标题、图像和注释的steps.md，构成一份可随时分享的组装指南。对于桌面上的零件，使用--cam desk。将配合问题、故障和公差放在--note中。 - clip：使用 H.264（CRF 20）录制，并可选地从同一手机的麦克风录制 AAC。它会跳过手机大约 5 秒的预热时间。iPhone 模式：1920×1080 或 1920×1440，30 或 60 fps。之后，仅读取关键帧快照表（6 帧，约 600 token）以判断构图和动作。MP4 文件可用于 Remotion 或其他编辑。
- compile：以
--fps指定的帧率通过拼接解复用器生成幻灯片；不同大小的帧会以白色信箱模式显示。8 fps 适合延时摄影；1–2 fps 适合步骤幻灯片。
3D 打印模式（cam_print.py）
print locate录制约 40 秒，并构建一张第 25 百分位合成图像（逐像素取最暗的四分之一时刻），这样即使打印头超过一半时间遮挡了打印件，打印件仍然可见。中位数不行：打印头在其正在打印的零件上方停留时间过长。它会框选出暗色背景上的候选区域，并根据周围床身的明亮程度进行排序。标注后的 640×480 图像消耗约 410 token。print use 1,2,4：由你决定哪些框是打印件。 Logo 字母、皮带、导轨夹和光杆阴影都能通过像素测试，而且排序有时会先把光杆阴影排在前面。如果模棱两可，拍摄一张带网格的snap并匹配单元格。如果没有任何区域是打印件，请用户重新对准。选区会按照--grow（默认 0.15；当光杆阴影触及零件时使用 0.08）扩大，以捕获微弱的相邻零件。print shot/print monitor以 2 fps 流式传输，并根据当前可见的打印像素份额为每帧评分。它们会跳过模糊帧并保存原生分辨率裁剪。打印过程中，打印头可能永远不会完全离开（60–75% 可见是正常的）；要获得清晰的底板图像，请在打印结束后拍摄。假设深色打印件位于浅色底板上；尚未实现浅色在深色背景上的检测。
它能够自动适应移动过的手机。 每轮会将其前 3 秒与保存的视图进行对齐。轻微位移（最佳匹配误差 ≤ 22）会被自动跟踪（视图偏移 +dx,+dy px）。重新对准（误差 > 22）会显示 摄像头移动：monitor 会重新运行 locate，并以 需要确认 退出，任务结束时通知你；读取定位图像，运行 print use，然后重新启动。录制文件的校准结果：未移动 15.8，轻微位移后对齐 15.9，不同场景 28.9（仅打印头移动就会增加约 15）。
可靠性注意事项（已验证 2026-10-15）
- macOS 权限授予给 ClaudeCam。 Claude Code 作为其自有辅助包运行，该包声明不调用摄像头，因此 macOS 会静默拒绝将其启动的任何子进程（ffmpeg 直接挂起）访问摄像头，并且永远不会在“隐私与安全性”>“摄像头”下列出。
cam.py通过~/Applications/ClaudeCam.app（由setup/install-helper构建）启动 ffmpeg 进程，使用open -W -g -n -a；macOS 会向 ClaudeCam 询问一次权限。 - 之前工作正常现在却显示“无帧” 是连续互通流卡住了，不是权限问题。解锁手机一次，然后锁上，将其静止放在充电器上，并确保没有其他应用正在使用它。即使
devices仍然列出 iPhone，也不意味着帧在流动。 - 手机需要大约 5 秒来连接和曝光（1.5 秒会导致全黑且无错误），因此它会跳过 150 帧；Mac 摄像机会跳过 45 帧。设备索引在调用之间会变化，因此设备通过名称选择。ffmpeg 默认的 29.97 fps 被拒绝，因此强制使用 30/60 fps，nv12 格式。
- 卡死：如果一轮中 25 秒没有帧，则放弃并重试一次。卡死的 ffmpeg 会忽略 SIGTERM（有一次它占用了摄像头 9 分钟），因此
ff_stop会升级到 SIGKILL，并且每轮监控会首先运行pkill -9 -f cam-shot-。终止open进程永远不会停止 ClaudeCam 内部的 ffmpeg。 - 模糊与冻结：自动对焦搜寻曾产生过完全模糊的“最佳”帧。拍摄过程会跳过质量低于本轮最清晰帧 60% 的帧，并打印
警告：模糊/警告：流冻结。 - 需要锁定/休眠（连续互通相机仅从锁定的手机传输流）。在电池供电或低电量模式下，从空闲状态唤醒手机速度较慢，因此请要求连接充电器。手机被移动是真正的风险：要求用户通过
snap查看画面，而不是拿起手机。 open -W始终返回 0，因此成功意味着输出文件存在。Homebrew 版本的 ffmpeg 没有drawtext，因此时间戳和网格标签以文本形式打印。使用--input <图像|视频>回放录制文件进行测试，无需摄像头（状态存储在camera-state/file/下）。- Figma：使用带有
nodeIds的upload_assets放入占位矩形，其大小根据图像的宽高比调整，适用于将摄像头图像放入画框中。