Watcher 编舞工作台

真机表情预览更新（2026-10-16）

「真机预览」现在同步动作轨道与官方表情轨道：从「官方 → 表情」加入设备已有表情，按时间轴片段开始播放、结束停止。使用 SDK 注入的 animation 通道，不播放表情关联的官方动作或音效。设备未声明的资源会在动作开始前明确报错；请检查 SD 资源和固件，或移除该表情仅预览动作。机器人仍可能因 SD 文件缺失/损坏拒绝播放，程序会报告失败并停止预览。

「我的」中新导入的 GIF 仍只在电脑播放，即使文件名相同，也不会自动绑定设备资源。如果 SD 已有对应官方表情，请从官方库加入对应素材；本次不包含向 SD 上传新 GIF 或自定义作品资源绑定。动画按设备原始速度播放，片段拉伸不代表真机 GIF 变速。网络指令不是硬件级同步。停止/页面失联同时请求停止动作和本次启动的动画，失败保留重试入口。

音频轨道也加入真机预览：在「我的 → 音频」导入 MP3/WAV/OGG（单文件最多4 MiB），点击素材加入音频轨道并对齐起点。电脑预览从电脑出声；真机预览将音频转为24kHz单声道PCM，通过SDK临时播放，不写SD卡，也不在电脑重复出声。要求设备声明 audio.stream 能力；单段PCM最多4 MiB、总计8 MiB，约87秒/174秒。损坏、超限、重叠音频明确拒绝，停止与页面失联清理音频。网络及设备缓冲会产生延迟，本功能不承诺帧级同步；音频不会提交给AI模型。

更新后先保存作品，再重启 Application 并刷新页面；仅刷新页面不会加载新的 Python 服务。

独立 SDK Application：导入 GIF 和可选音效，通过本机 Codex CLI 观察完整帧序列、生成动作，在真实 Watcher 模型上同步预览，导出客户端可导入、可编辑的 action-draft v1 JSON。也提供 Skill 下载、素材导出和外部 AI 提示词。

本地运行

需要 Node.js 22.12+、Python 3.11+、已安装的 watcherobot SDK 0.1.4，以及支持图像输入并已登录的 Codex CLI。当前清单只声明 Windows 支持；其他系统尚未完成运行验收。

在本项目目录执行（PowerShell 和 Shell 命令相同）：

npm ci
npm run build
watcherobot app check .
watcherobot app run .

如果 watcherobot 不在 PATH，请使用安装环境内的可执行文件。app run 会由 SDK 管理运行并打开本机浏览器；日志显示回环地址。端口首次分配后保存在用户目录 .watcher-choreography/web-port，重启复用同一地址，让浏览器里的作品和素材继续可见。地址被占用时明确报错。退出运行命令会关闭应用。不要直接运行 app.py：它要求 Daemon 注入的 Application 环境。

本应用不创建 Daemon、不建立设备连接、不转发 Desktop 业务帧，通过注入的 SDK Device channel 驱动头部。仅在本地回环地址提供网页。GIF 分帧会发送给 Codex 当前配置的模型；没有独立 API 密钥配置；音频用于电脑或真机预览，不发送给模型。

使用

  1. 页面复用客户端创作模式。左侧「我的 → 表情」导入 GIF，再点击素材加入表情轨道；音效按同样方式加入音频轨道。
  2. 打开预览区右上角「AI 观察表情并编舞」，选择 GIF 片段并填写要求，分析 GIF；支持取消，最长等待五分钟。
  3. 检查眼神依据和草稿预览，选择「仅保存到动作库」或「保存并应用到时间轴」。应用时对齐所选 GIF 起点，已有重叠动作会提示先调整。
  4. 「我的 → 动作」的更多菜单选择「编辑与调试」，通过原客户端的曲线编辑器调整关键帧并保存。动作 JSON 保持客户端可导入、可编辑的格式。
  5. 「保存作品」保存在当前浏览器；点击「返回」进入作品列表，可再次打开、导出和导入作品备份。作品文件包含所引用的自定义 GIF、音效和动作轨道。动作 JSON 只包含动作。
  6. 不使用本机 AI 时，选择「用外部 AI 编舞」，下载 Skill、复制提示词并导出 GIF，再导回 AI 生成的 JSON。成功与失败采用顶部居中的绿色/红色浮动通知，不撑高对话框。

素材与动作库保存在当前浏览器，作品需要点击「保存作品」。清除浏览器数据或换浏览器会影响本地内容，请用作品导出保留备份。支持真机动作预览，不自动上传新 GIF/音效到机器人 SD 卡。不同动作片段间的空白保持前一姿态，下一片段先用短过渡到达自身起始姿态，再执行后续关键帧；若片段太短、没有足够过渡时间，会提示对齐前后姿态或延长动作；电脑时间轴预览与真机预览共用同一合成轨道。

坐标 X 中位90、Y中位115；Y减小低头、增大抬头。生成范围 pan ±25、tilt ±15，Y=115-tilt；2–60点，至少120ms间隔。速度约束为保守软件上限，不等同已验收的电机能力。长素材仍按原始帧时序处理，不静默截断。

开发与验证 

npm test
npm run typecheck
python -m unittest discover -s tests
npm run skill:package
node scripts/package-watcher-skill.mjs --check

Python 测试需安装 app.json 所列依赖及 httpx。Skill 的独立发行源为 skill/；打包分发器选择同语义的 PowerShell/Shell 入口，生成 ZIP 与校验清单，修改后应重打包。工作区原 Skill 为历史安装副本，新项目不会自动改写同事的个人安装。

浏览器测试：安装 Playwright Chromium，启动本地测试服务 python -m uvicorn service:create_web_app --factory --host 127.0.0.1 --port 5198，设置 TEST_GIF 指向真实 GIF，运行 node tests/browser.mjs。可通过 WORKBENCH_URL、CHROMIUM_PATH 覆盖测试地址和浏览器。测试不调用收费模型、不操作设备。实际视觉模型输出质量须另行验收。

代码来源与发布

模型、轨道采样和动作格式解析从团队 WatcheRobot_client 的 2df4fd9b 工作树及未提交创作者改动抽离。保留原模型资源，约50MB的 GLB 是主要体积来源；首次加载和弱 GPU 体验仍需优化。没有更改资源授权，发布前沿用团队对原资源的授权要求。

源码仓库不提交 node_modules、web 构建目录或本机配置。交付可安装 Application 时必须先构建，并将 web/ 连同 app.py、app.json、service.py、playback.py、prompt.txt、schema.json、skill/ 一起放入应用制品；仅源码下载不能直接运行。项目目前没有远端仓库、提交或 PR。参见 开发记录。

真机动作预览（本版）

  1. 在项目目录执行 npm start（首次先 npm ci、npm run build）。设置 WATCHER_PYTHON 可指定已安装 SDK 的 Python。PowerShell 与 Shell 入口由 Node 分发器选择，参数和退出码一致；目前实际验收环境仅 Windows。
  2. 电脑和机器人连接同一 Wi-Fi，在机器人上打开 Python SDK。将屏幕六位码填到网页顶部，点击「连接机器人」。成功显示绿色提示，失败显示红色原因并允许重试；已有连接无需重新配对。无需打开桌面客户端，也无需在终端输入配对命令。
  3. 导入 GIF，生成并应用动作，或导入动作 JSON。先电脑预览，再点击真机动作预览。
  4. 机器人先移动到起始姿态，再按时间轴执行头部动作、播放设备已有的官方表情，并通过音频流播放导入的音效；新导入的 GIF 仅在电脑显示。具体设备能力与资源要求见本文开头。真机预览始终从头开始，播放中锁定素材和编辑，停止后保留当前姿态。
  5. 关闭页面或页面失联约2.5秒后，服务停止下发动作并请求停止。断网时无法保证停止命令送达，界面会报告无法确认。

这是网络实时预览，浏览器计时以服务端时间校正，不是硬件级精确同步。实际方向、响应与同步精度须真机验收。离开前保存作品，需要跨电脑时导出作品备份。

发送采用绝对时间轴和两轴关键帧边界，由设备完成段内线性移动，不再每100ms补指令；静止时不重复发送相同目标。回复滞后时跳过过期段，较差网络下细节可能减少。AI生成轨道移除静止内部重复帧，保留停顿起止和总时长。运行中单次指令确认超过1秒会停止并提示，设备断连与页面失联仍停止。更新程序后先导出动作，再重新启动 Application；刷新网页不会重新加载 Python 后端。

完整 Application 交付包

构建后运行 npm run package:app，得到 dist/watcher-choreography.zip。包含已构建页面、模型、Skill 与 Python 服务；解压后执行 watcherobot app check <解压目录> 和 watcherobot app run <解压目录>，无需运行 npm。SDK 安装依赖和托管生命周期；不要直接执行 app.py。源码开发入口为 scripts/application.ps1 / application.sh，均委托 application.py；运行 ZIP 不包含这些开发脚本。

更新这一版后，先保存并导出当前作品，再停止原 Application 并重新启动，最后刷新原网页地址。前后端停止协议一同更新，仅刷新页面不足以加载 Python 修复。停止未得到确认时，页面保留「停止」重试入口；服务会拒绝新的动作播放直到停止确认成功。

源码提交与草稿 PR 流程见 SUBMITTING.md，PR 正文草案见 PR-DRAFT.md。