Shots 是 ArchDev 的截图、录屏与评审工具，通过 archdev shots 子命令使用，需 ArchDev 0.53.0 或更新版本；版本较旧时请使用者运行 archdev upgrade。CLI 是权威依据，与文档冲突时以 archdev shots --help 及各子命令的 --help 为准。
用途
Shots 把 UI 工作变成可评审的证据。一次捕获会把 PNG（或海报 PNG 加视频）写入工作树根目录的 .astroshot/<feature>/，并记录到该目录的 manifest.json。评审者在 Astroshots 应用或 archdev shots review 中查看画面，决定与评论写入图片旁的 review.json；代理用 archdev shots status 读回反馈。
开启与检查
Shots 默认关闭，且该设置属于使用者本人。除 doctor 和 --help 外，所有 archdev shots 命令在关闭时都会拒绝执行、退出码 1 并提示 archdev shots is off. Enable it with: archdev settings set shots on。先用只读的 archdev shots doctor 检查：首行显示开启或上述关闭信息，仅开启时退出码为 0；其余行说明各模式所需工具的位置（Chrome、Node 22 及以上与 Node 助手、可选 ffmpeg、ffprobe），缺失的工具只影响需要它的模式。--json 输出同样的 JSON 报告。doctor 不检查 Node 助手的 npm 包。
关闭时请使用者在其本人终端、代理会话之外运行 archdev settings set shots on。不要自行启用：archdev settings set shots … 与 shots-upload … 在代理会话或无交互终端中会拒绝执行，也不得改配置文件或切换 profile 绕过。设置为按 ArchDev profile 存储，若会话使用 ARCHDEV_PROFILE 或 --profile，需在该 profile 下开启。archdev settings set shots-upload auto|manual（默认 manual）是使用者对上传截图到 ArchDev 供网页评审的偏好，同样需人类终端。无人在场的测试 harness 可使用团队审阅并提交的独立 profile 开启后运行。
发布静态截图
archdev shots capture 把已有图片（PNG、JPEG、WebP 或 GIF）或 agent-browser 会话截图发布到 .astroshot/<feature>/ 并打印写入路径。--feature 为 kebab-case，stories 与 friction-logs 保留；--slug 决定编号文件名（如 0001-dialog.png）；--source 与 --from-agent-browser 互斥，后者默认整页截图，可用 --no-full 或 --selector 调整；写入前会校验图片字节与扩展名是否匹配。--title 默认为 slug 的标题格式，--description 说明该画面证明了什么，--url 与 --viewport 是给评审者的上下文，--root 覆盖工作树根。
运行（Run）
manifest.json 一次保存一个运行：run_id、status 与该次捕获的截图。默认 --status running 的捕获追加到当前运行；--status pass/fail/idle 会追加并关闭运行，也可用 --finalize 不带新截图关闭（须带 --status，否则保持 running 并退出 0）。关闭后的下一次捕获会开启新运行。--run-id 可固定运行，多步 harness 应给所有捕获和最终 finalize 传同一 id；不同 --run-id 会无警告替换当前运行，两个 harness 不应共用 feature 名。关闭或开始新运行前先读评审评论，评论按运行隔离。pass 与 fail 只描述你的流程是否运行过，不代表人工评审结果。同一 feature 目录的捕获由 .capture.lock 串行化。
用 fixture 渲染 PNG
当组件或终端状态可脱离整个应用复现时使用 fixture，选最小的边界：固定 props 的 React 组件用 archdev shots react；固定状态的 Ink 组件树用 archdev shots ink；真实终端程序及其键盘流程用 archdev shots pty；路由、登录、实时数据与整个应用外壳用 agent-browser 驱动后配合 capture --from-agent-browser。各命令接受 fixture 路径与 -o/--out（写 PNG 并打印 wrote PATH）或 --feature F --slug S（渲染并一步发布）。fixture 渲染始终以 Git 顶层为根并追加到当前运行；需要 --run-id、--status 或 --root 时用 -o 加 capture。fixture、其导入与 PTY 命令以你的权限运行，临时浏览器或伪终端不是沙箱。
React fixture 默认导出组件和捕获设置（width、height、background、selector、waitFor、settleMs、fullPage、stripOverlay、omitBackground），需 Chrome、Node、助手包以及项目内 react 与 react-dom。可用 react-shot.config.ts 配置 root、alias、styles、postcssConfig、dedupe、stubModules；--root、--config、--width、--height、--headed 可覆盖。批量可用 YAML 清单运行 archdev shots react batch shots.yaml，输出只写到 out 路径，需要进入评审流时再用 capture --source 发布。
Ink fixture 需 Node、助手包及项目内 ink 7 与 react 19，且 package.json 需 "type": "module"。PTY fixture 为 YAML（或 .json），包含 version、command（直接运行、不经 shell）、args、cwd、cols、rows、timeoutMs、actions（waitFor、waitForExit、key、text、pauseMs）与 expectText；非零退出会失败，除非 allowNonZeroExit；不支持鼠标输入、运行中调整尺寸与 Sixel 图形。发布或汇报前应打开每个 PNG 检查裁剪、换行、加载状态、颜色与隐私数据。
录制影片
影片展示一段流程，单个状态仍以静态截图为证据。每次影片会写海报 PNG 和视频到 .astroshot/<feature>/ 并作为一个 shot 加入 manifest，评审状态附于海报。格式默认 WebM，--format mp4 仅对 PTY 和 frames 影片且 PATH 中有 ffmpeg 时生效；以命令 JSON 中 videoPath 的扩展名为准。来源选择：网页或单页应用用 --source browser；终端程序用 --source pty；原生 macOS 窗口用 --source desktop.window；自产 PNG 帧用 movie start / push-frame / stop。不要用抓桌面窗口方式录浏览器或终端。
共享选项：--feature、--slug、--title、--description、--run-id、--root、--size、--fps（最高 60）、--format、--status。browser 支持 --url、--settle-ms、--headed 与 --script（ES 模块默认导出 async (page) => {…}，脚本需助手包）；pty 使用与静态截图相同的 YAML；desktop.window 仅 macOS，用 --bundle-id、--window-id、--title-regex、--owner、--pid 或 --pick 选择窗口，--duration-ms 默认 3000，--cursor 显示指针，近乎空白帧需 --allow-blank，movie list-windows 列出候选窗口，movie check-screen-access 报告屏幕录制权限（拒绝时退出 2，--request 请求，--open-settings 打开系统设置）。属于其他来源的选项会被拒绝。
自产帧流程：movie start 输出含 id 的 JSON 会话；movie push-frame --file 推帧；movie mark 在当前时间加章节；movie stop --status 结束；多个打开会话时用 --session ID 指定。影片运行与静态截图同样方式关闭：archdev shots movie finalize --feature … --run-id … --status pass。
读取评审反馈
archdev shots status 与 archdev shots status --feature … --json 读取评审结果。