feat: add child motion picture book stage tooling

.hermes/shared-memory/pitfalls.md

@@ -43,14 +43,22 @@
 - 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
 - 关联：`.hermes/README.md`。
 
-## 儿童动作 Demo 挥手阶段不推进先查 mocap 消费链路
+## 儿童动作 Demo 卡在摄像头不可用或挥手不推进先查 mocap 消费链路
 
-- 现象：`/child-motion-demo` 能打开摄像头画面，但到“打个招呼”或左右手挥动阶段时，真实硬件动作无法检测通过，只能用鼠标拖拽或键盘调试继续。
-- 原因：摄像头视频流只是舞台背景；如果热身关没有消费 `useMocapInput` 的动作名和手部坐标，就不会把硬件动作转换成热身状态机完成事件。
-- 处理：确认 `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 在 `step.kind === 'gesture'` 时启用 `useMocapInput`；确认 `src/services/useMocapInput.ts` 能解析 `/stream` 包里的 `actions/action/gesture/gestures/event/name/type`、`hands[]`、`leftHand/rightHand`、`left_hand/right_hand`、左右手标记和 `open_palm/grab` 状态。热身关应由 mocap 推进，键鼠只作为本地调试兜底。
-- 验证：运行 `npx vitest run src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx`，并在本地硬件服务启动后进入 `/child-motion-demo` 实测招手、左右手挥动和跳跃阶段。
+- 现象：`/child-motion-demo` 打开后即使 `http://127.0.0.1:8876/` 已启动，页面仍提示“摄像头暂不可用”，或到“打个招呼”、左右手挥动、站位步骤时真实硬件动作无法检测通过，只能用鼠标拖拽或键盘调试继续。
+- 原因：浏览器摄像头视频流只是舞台背景；如果热身关把 `getUserMedia` 状态当成主动作数据源，或只在 gesture 阶段消费 `useMocapInput`，就会错过 mocap 的身体中心、动作名和手部坐标。
+- 处理：确认 `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 全热身流程启用 `useMocapInput`，页面主提示展示 mocap 动作数据源状态而不是浏览器摄像头状态；确认 `src/services/useMocapInput.ts` 能解析 `/stream` 包里的 `general.body.center_norm`、`actions/action/gesture/gestures/event/name/type`、`hands[]`、`leftHand/rightHand`、`left_hand/right_hand`、左右手标记和 `open_palm/grab` 状态。`/stream` 是 WebSocket，普通 HTTP 访问返回 404 不能当成服务不可用。
+- 验证：运行 `npx vitest run src\services\useMocapInput.test.ts src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx`，并在本地硬件服务启动后进入 `/child-motion-demo` 实测站位、招手、左右手挥动和跳跃阶段。
 - 关联：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
 
+## 儿童动作 Demo 真实绘本背景图未生成先查 VectorEngine 配置
+
+- 现象：`/child-motion-demo` 已经呈现绘本草地风格，但 `public/child-motion-demo/picture-book-grass-stage.webp` 不存在，Network 里该图返回 404，或运行 `npm run assets:child-motion-demo -- --live` 返回缺少 VectorEngine 配置。
+- 原因：儿童动作 Demo 的真实背景图使用 VectorEngine `gpt-image-2-all` 生成，脚本只读取 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和可选 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；仓库内不能提交真实 key，缺配置时页面只能使用 CSS 草地绘本兜底。
+- 处理：在本地私密环境补齐 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai` 与 `VECTOR_ENGINE_API_KEY`，不要把 key 写入 Git；先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt，再运行 `npm run assets:child-motion-demo -- --live` 生成默认背景图。
+- 验证：生成后确认 `public/child-motion-demo/picture-book-grass-stage.webp` 存在，重新打开 `/child-motion-demo` 可看到真实绘本草地背景；`npm run check:encoding` 仍通过。
+- 关联：`scripts/generate-child-motion-demo-assets.mjs`、`src/index.css`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
+
 ## GPT-image-2 不再读 APIMart 图片配置
 
 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。