dsh-motion 0.3.0 → 0.4.1

package/README.md

@@ -14,7 +14,7 @@
 |---|---|
 | `motion_frames` | **极简模式（默认）**：直接从场景出帧，不生成视频、不用 HF；几秒拿到 storyboard PNG 与 layout 问题 |
 | `motion_doctor` | 环境自检（Node / FFmpeg / Python venv / manimgx / sympy / Chrome / HyperFrames） |
-| `motion_render` | 渲染 Manim / manimgx 场景，可加运动模糊、颗粒、暗角、调色 |
+| `motion_render` | 渲染 Manim / manimgx 场景；未通过 `APPROVALS.json` 确认门的项目会拒绝渲染 |
 | `motion_probe` | 成片抽帧拼 contact sheet，报告全黑 / 过曝的空镜 |
 | `formula_check` | 用 SymPy 判断两个表达式是否恒等 |
 
@@ -48,6 +48,10 @@
 
 路由是显式的：`node scripts/route-style.mjs "<题材>"`（点名优先 → registry 打分 → 默认 `swiss-motion`；分数并列/为 0 时要求确认）。规则在 [styles/registry.json](styles/registry.json)。
 
+迭代预算（首帧 ≤60s、输出 ≤30k、上下文 ≤100k、读图 ≤10）见 [docs/performance-budget.md](docs/performance-budget.md)。
+
+开工前先过需求卡点：`npm run plan -- "竖屏抖音，讲导数，要旁白"`，会推断画幅、交付、风格的候选项，再交给 `ask_user_question`；能推断的不问。
+
 项目 `DESIGN.md` 头部写 `style: <slug>` + `style_version: 1.0.0`。风格来源、HF 集成、抽帧能力与 Lemo 调研见 [docs/ai-native-motion.md](docs/ai-native-motion.md)。
 
 ## 演示
@@ -62,6 +66,30 @@
 
 汇总见 [showcase/README.md](showcase/README.md)。
 
+## 开工前确认
+
+顺序是硬性的：
+
+1. 需求卡点（画幅 / 交付 / 风格 / 受众 / 旁白）
+2. 脚本 / 文案（逐句旁白、上屏文字、公式）
+3. 分镜（镜头、秒数、画面、运动、字幕）
+4. `DESIGN.md` + 3 张风格帧（只出帧，不渲染）
+5. 交付清单（尺寸 / fps / 时长 / 文件 / 音频 / 字幕）
+6. **用户明确说“可以开始 / 开始做 / 按这个执行”**
+
+`motion_render` 会读项目里的 `APPROVALS.json`；没有，或 `delivery` / `start` 等阶段未全部 approved，直接报错，不会偷偷渲染。
+
+没听到第 6 步的明确指令，不写完整场景、不出全片。清单模板见
+[skills/animation-router/references/confirmation.md](skills/animation-router/references/confirmation.md)。
+
+按体量分档：`light`（≤15 s 无旁白：脚本+分镜合并）、`standard`（15–60 s 或旁白）、`full`（>60 s 或多段，加 animatic）。确认状态落在项目里的 `APPROVALS.json`：
+
+```bash
+npm run approvals -- init <project> --mode light
+npm run approvals -- set <project> start approved --note "用户说可以开始"
+npm run approvals -- check <project>
+```
+
 ## 安装
 
 ```bash

package/docs/ai-native-motion.md

@@ -50,7 +50,7 @@ HF 的卖点是 "same input, same frames, same output"：HTML + 可 seek 的动
 
 - Lemo-Opuscar 明确写着风格是为 Claude Opus 5.5 调的，别的模型不一定复现得好；代码 MIT、demo 与静帧 CC BY 4.0；
 - 它的 59 个风格覆盖纸感、印刷、像素、3D、纪录片等，适合当"语言菜单"，不适合直接当品牌规范；
-- 可借鉴的三件事：`STYLE.md` 作为 style prompt、三张风格帧验收、分镜只在被要求时做；
+- 可借鉴的三件事：`STYLE.md` 作为 style prompt、三张风格帧验收、分镜作为确认材料；
 - 授权上，demo 静帧可商用但需署名 LemoLab；风格文件本身是 MIT。
 
 本仓库的选择：删除自创的 `dark-editorial`，改为 4 套 Lemo 风格（`swiss-motion` / `dataviz` / `blueprint` / `whiteboard`）+ 1 套 Manim 社区的 `3b1b`，每套按 `STYLE.md` + `tokens.json` + `theme.py` + `preview.jpg` 落地；外部参考统一指向 HF。
@@ -125,7 +125,7 @@ manimgx inspect scene.py -t 1.2,4.5,end
 DESIGN.md
   → motion_frames（3–6 帧：开场 / 转折 / 结论）
   → 改场景 → 再出帧（秒级）
-  → 需要给用户看分镜时：6–9 帧（真实代码）
+  → 确认门：脚本 → 分镜 → DESIGN/风格帧 → 用户明确“开始”
   → formula_check
   → motion_render（定稿后）
   → 需要字幕/旁白/混音：进 HF
@@ -150,15 +150,7 @@ DESIGN.md
 - 需要交付时才升级到 `motion_render` / HF；
 - 成片检查（`motion_probe`）只在已经有 mp4 时运行，不做"为了检查而渲染"。
 
-## 参考
-
-- [HyperFrames design systems](https://hyperframes.heygen.com/prompting/design-systems)
-- [HyperFrames examples](https://hyperframes.heygen.com/examples) · [catalog](https://hyperframes.heygen.com/catalog)
-- [HyperFrames CLI rendering](https://hyperframes.heygen.com/guides/rendering)
-- [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) · [DIRECTOR.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/DIRECTOR.md) · [TECHNIQUE.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/TECHNIQUE.md)
-- 本地 `manimgx inspect --help`（manimgx 0.1.1）
-
-## 4.5 效率：大家怎么缩短时间
+## 5. 效率：大家怎么缩短时间
 
 共识是**把检查点前移、把渲染延后**：
 
@@ -178,7 +170,7 @@ DESIGN.md
 - 关键不是"帧比视频快多少"，而是**看帧成本与片长无关**，且不经过编码、起浏览器、抽帧三次搬运；
 - 如果已经在 HF 里，用 `hyperframes snapshot` 而不是"先 render 再 ffmpeg 截图"。
 
-## 4.6 开发调试
+## 6. 开发调试
 
 服务端插件没有 HMR，但也不需要每次重装：
 
@@ -189,7 +181,50 @@ DESIGN.md
 
 细节见 [dev-loop.md](dev-loop.md)。
 
-## 4.7 风格路由：目前怎么做，通用标准是什么
+## 7. 需求卡点：先问，再猜
+
+默认流程多了一个“卡点”，避免在没有信息时自己替用户决定：
+
+```bash
+node scripts/plan-questions.mjs "<brief>" --json
+```
+
+输出可直接交给 `ask_user_question`：
+
+- **画幅**：brief 已有“竖屏/横屏/16:9”就直接写进 assumptions，不再问；没有才给推断的 2 个；
+- **交付**：brief 已有“旁白/静音”就跳过；没有才问；
+- **风格**：`route-style` 的 top 2–3；点名风格时直接省略；
+- **受众**：只对数学/科学、且 brief 未提“高中/大学/大众/专业”时问；选项按平台排（竖屏→大众科普，横屏→高中/大学）；
+- **旁白**：只在交付为旁白、且 brief 未提“中文/英文/双语”时问；选项是语言 + 声音；
+- **时长/语言**：从 brief 提取，不单独问；未回答的写进 `assumptions`。
+
+最多 4 题。关键不是“问满四道”，而是**能推断的不问、选项按上下文生成、问完一次就开做**。同时输出 `assumptions.gateMode`：≤15s 且无旁白为 `light`，15–60s 或有旁白为 `standard`，>60s 或多段为 `full`。
+
+### 确认门（本仓库的硬规则，分档）
+
+需求卡点问完，**不等于开工**。按体量选一档：
+
+| 模式 | 适用 | 阶段 |
+|---|---|---|
+| `light` | ≤15 s、无旁白 | 需求 → **脚本+分镜（合并）** → 视觉 → 开工 |
+| `standard` | 15–60 s，或有旁白 | 需求 → 脚本 → 分镜 → 视觉 → 交付 → 开工 |
+| `full` | >60 s、多段、复杂旁白 | 需求 → 脚本 → 分镜 → **animatic** → 视觉 → 交付 → 开工 |
+
+确认状态落在项目里的 `APPROVALS.json`：
+
+```bash
+node scripts/approvals.mjs init <project> --mode light
+node scripts/approvals.mjs set <project> script_storyboard approved --note "用户确认"
+node scripts/approvals.mjs check <project>
+```
+
+`check` 未全部 approved 时退出 1；不能跳过前置阶段；`start` 必须是用户明确授权。
+
+**是不是太严？** 对 6 秒、无旁白的单公式短片，强制“脚本、分镜、交付清单”三份独立材料确实过重；所以 `light` 把脚本和分镜合并成一张表，保留“明确开工”这一道。对 30 秒以上或带旁白的片子，`standard` 的独立脚本/分镜是值得的；`full` 才加 animatic。
+
+模板在 [skills/animation-router/references/confirmation.md](../skills/animation-router/references/confirmation.md)。
+
+## 8. 风格路由：目前怎么做，通用标准是什么
 
 ### 本仓库
 
@@ -245,7 +280,7 @@ DESIGN.md
 - registry 的 `keywords` 需要随新题材维护；
 - 画幅/音频/复杂度字段目前只记录，还没参与硬约束（比如 9:16 未验证的风格应直接拒绝）。
 
-## 5. 现成的风格体系（2026-10 可直接采用）
+## 9. 现成的风格体系（2026-10 可直接采用）
 
 不必从零写风格文档。这个生态已经沉淀出几套公开、可复用的体系：
 
@@ -263,7 +298,7 @@ DESIGN.md
 1. **风格 = 不变量 + 自由故事。** `STYLE.md` 锁死 look、颜色、字体、运动、声音；故事、镜头、节奏由导演决定（Lemo 的 AGENTS.md 原话：`STYLE.md` is fixed；everything else is yours to direct）。
 2. **风格按名字选，不按形容词选。** 用户说 "swiss-motion" / "瑞士动态排版"，agent 查索引、读 `STYLE.md`；没选就推荐 2–3 个最接近的。
 3. **风格文档有固定骨架。** Lemo 是 11 节；mg-styles-15 是四段式，其中 signature features 必须可检验（"cubic-bezier(0.34,1.56,0.64,1)，错峰 2–4 帧"，不是"要有弹性"）。
-4. **先风格帧，后分镜，最后成片。** 三张真实代码出的风格帧 → 用户要看才做 6–9 张分镜 → 成片；风格帧不过不往下走。
+4. **先确认，后执行。** 脚本 → 分镜 → DESIGN/风格帧 → 交付清单，逐项确认；用户明确说“开始”才写完整场景、出片。
 5. **独立评审。** 另一个 AI 用 rubric 按 7 个维度打分（风格保真、概念、运动、排版、质感、声画同步、技术），给 5–10 条带时间码的修改，再改两轮。
 6. **确定性。** 帧是 `render(t)` 的纯函数；同一输入同一输出，便于批量与回归。
 
@@ -299,3 +334,11 @@ DESIGN.md
 3. 画面仍由 manimgx 画，不复制它们的 Canvas/WebGL demo 代码，只取语法与 prompt；
 4. 交付层继续交给 HF，`frame.md` 只做品牌/版式契约；
 5. 标注来源与许可：Lemo 代码/文档 MIT，demo 静帧 CC BY 4.0（署名 LemoLab）；mg-styles-15 MIT；HF Apache-2.0。
+
+## 参考
+
+- [HyperFrames design systems](https://hyperframes.heygen.com/prompting/design-systems)
+- [HyperFrames examples](https://hyperframes.heygen.com/examples) · [catalog](https://hyperframes.heygen.com/catalog)
+- [HyperFrames CLI rendering](https://hyperframes.heygen.com/guides/rendering)
+- [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) · [DIRECTOR.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/DIRECTOR.md) · [TECHNIQUE.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/TECHNIQUE.md)
+- 本地 `manimgx inspect --help`（manimgx 0.1.1）

package/docs/performance-budget.md

@@ -0,0 +1,73 @@
+# 迭代预算（P0）
+
+依据：30.02 s 成片、882.1 s 端到端的一次真实诊断。
+
+| 指标 | 那次 | 目标 |
+|---|---|---|
+| 首帧 | 261 s | **≤60 s** |
+| 端到端 | 882 s | **≤400 s** |
+| 模型时间 | 740.6 s（84%） | 不单独设目标，随步数/token 降 |
+| 输出 tokens | 126,839 | **≤30k** |
+| 上下文峰值 | 222k / 256k | **≤100k** |
+| 读图 | 32 张 1080p | **≤10 张 sheet/局部** |
+| 全文件重写 | 2 次 | **0 次**（例外见下） |
+| `motion_probe` / `motion_render` | 3 / 4 次 | **1 / 2 次** |
+
+## P0 四条
+
+### 1. 先构图，后动画
+
+- 先写“最小场景”：只放 6–8 个关键构图，不写完整动画；
+- `motion_frames` 出 sheet，确认构图与版式；
+- **60 s 内看不到第一帧就停下来**，检查是不是在盲写；
+- 构图确认后才补时间轴、运动、转场。
+
+### 2. 只做局部 edit
+
+- 默认用 `edit`，不整文件重写；
+- 只有改动超过文件 50%，或文件 <40 行时，才允许重写；
+- 重写必须在回复里说明原因，不能“顺手重写”。
+
+### 3. 图片预算
+
+- 每次迭代只看 **1 张 contact sheet**，宽度约 960 px；
+- 只有可疑格才读全分辨率；
+- 同一张图不重复读；改了场景才重新出图；
+- 目标：整个任务 ≤10 次读图。
+
+### 4. 上下文预算
+
+- 只保留当前场景版本，旧版本用一两句话摘要；
+- 不把旧代码、旧图、已经确认过的长文重复贴回上下文；
+- 目标峰值 ≤100k；接近 100k 时先摘要再继续。
+
+## P1（工具）
+
+已完成：
+
+- [x] `motion_frames` 按场景 fps 取帧：各风格 `theme.py` 在模块层设置 `m.config.frame_rate`；
+- [x] post 强制 CFR，并校验成片时长（`tpad + CFR` 修正后复验）；
+- [x] storyboard 顶部 caption 条加提示，避免误判“裁切”。
+
+明确不做：
+
+- CJK 字符级 `ReplacementTransform` / `Transform` 的字形变形。manimgx 核心按点插值，汉字轮廓点数与顺序不一致，修起来是字形级工程；本仓库按“不支持”处理。
+  - 中文标题/标签：`Write`、`FadeIn/Out`、`Indicate`、改颜色；
+  - 换词：`FadeOut(old)` + `FadeIn(new)`，或按词/行 stagger；
+  - 公式：`TransformMatchingTex`；中文注释放在 `Text`，不混进 MathTex。
+
+待做：
+
+- [ ] `motion_probe` 只在最终成片跑一次；
+- [ ] `--draft` 低分辨率/低帧率、分段渲染、`manimgx preview` 包装、animatic。
+
+## 怎么量
+
+每个项目记录：
+
+```text
+first_frame_s, total_s, model_s, tool_s, render_s,
+output_tokens, context_peak, image_reads, full_rewrites, probes, renders
+```
+
+复测时用同一台机器、同一支 30 s 片，先对比“首帧”和“输出 tokens”，再看总时长。

package/lib/approvals.js

@@ -0,0 +1,60 @@
+/**
+ * 读取项目里的 APPROVALS.json，供工具层做“开工确认”硬门。
+ *
+ * 脚本 scripts/approvals.mjs 负责写；这里只读，避免模型绕过。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+const FILE = 'APPROVALS.json'
+
+export function findApprovals(file) {
+  let dir = dirname(resolve(file))
+  for (let i = 0; i < 4; i += 1) {
+    const candidate = join(dir, FILE)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+export function readApprovals(file) {
+  const path = findApprovals(file)
+  if (!path) return { status: 'missing', path: null, missing: [], mode: null }
+  const data = JSON.parse(readFileSync(path, 'utf8'))
+  const stages = Object.entries(data.stages ?? {})
+  const missing = stages
+    .filter(([, value]) => value.status !== 'approved')
+    .map(([key, value]) => value.label ?? key)
+  return {
+    status: missing.length ? 'pending' : 'approved',
+    path,
+    mode: data.mode ?? null,
+    project: data.project ?? null,
+    missing,
+    data,
+  }
+}
+
+export function assertApproved(file, { allow = false } = {}) {
+  if (allow) return null
+  const report = readApprovals(file)
+  if (report.status === 'missing') {
+    throw new Error(
+      `未找到 ${FILE}：这个项目还没过需求卡点/确认门。\n`
+      + '先跑：node scripts/plan-questions.mjs "<需求>" --json\n'
+      + '再初始化：node scripts/approvals.mjs init <project> --mode light|standard|full\n'
+      + '确认后把 delivery/start 等阶段置为 approved；或设置 DSH_MOTION_ALLOW_UNCONFIRMED=1 仅用于调试。',
+    )
+  }
+  if (report.status === 'pending') {
+    throw new Error(
+      `开工确认未通过（${report.path}）：还缺 ${report.missing.join('、')}。\n`
+      + '用 node scripts/approvals.mjs set <project> <stage> approved --note "用户确认" 更新；\n'
+      + '全部 approved 后才能渲染。',
+    )
+  }
+  return report
+}

package/lib/index.js

@@ -15,6 +15,7 @@ import { appendFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
+import { assertApproved } from './approvals.js'
 import { importFresh } from './fresh.js'
 
 const OPS_URL = new URL('./ops.js', import.meta.url)
@@ -91,7 +92,7 @@ export function apply(ctx, config = {}) {
   ctx.tools.register({
     name: 'motion_render',
     description:
-      '渲染一支数学/科普场景。engine="manimgx"（默认，数学/公式/坐标，无需 LaTeX，自带 layout 检查）或 "manim"（Manim CE 回退）。post 可加运动模糊/颗粒/暗角。返回时长/体积/布局问题清单。',
+      '渲染一支数学/科普场景。engine="manimgx"（默认，数学/公式/坐标，无需 LaTeX，自带 layout 检查）或 "manim"（Manim CE 回退）。post 可加运动模糊/颗粒/暗角。返回时长/体积/布局问题清单。未通过 APPROVALS.json 确认门的项目会拒绝渲染。',
     parameters: {
       type: 'object',
       properties: {
@@ -120,6 +121,9 @@ export function apply(ctx, config = {}) {
     output: textOutput,
     timeoutMs: 900_000,
     async execute(args) {
+      assertApproved(args.file, {
+        allow: config.allowUnconfirmed === true || process.env.DSH_MOTION_ALLOW_UNCONFIRMED === '1',
+      })
       const { renderScene } = await ops()
       const result = await renderScene(config, args)
       log(`render ${result.output} ${result.durationSec}s engine=${result.engine} problems=${result.layoutProblems.length}`)

package/lib/ops.js

@@ -8,7 +8,7 @@
  */
 
 import { execFile } from 'node:child_process'
-import { existsSync, statSync } from 'node:fs'
+import { existsSync, renameSync, statSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { promisify } from 'node:util'
 
@@ -104,10 +104,47 @@ export async function renderScene(config, args) {
     summary.video = finalOut
   }
 
+  // post/ffmpeg 可能因 tmix/丢帧把时长压短；用 CFR 补齐并校验，避免"30s 变 27.4s"。
+  if (summary.durationSec) {
+    const fixed = await ensureDuration(config, summary, fps)
+    if (fixed) summary.normalized = true
+  }
+
   summary.wallSec = Number(((Date.now() - started) / 1000).toFixed(1))
   return summary
 }
 
+/** 成片时长与渲染器报告的时长不一致时，用 tpad + CFR 修正；返回是否修过。 */
+async function ensureDuration(config, summary, fps) {
+  const expected = Number(summary.durationSec)
+  if (!Number.isFinite(expected) || expected <= 0) return false
+  const file = summary.output
+  const before = await probeOutput(config, file)
+  const delta = expected - before.durationSec
+  if (!Number.isFinite(delta) || Math.abs(delta) <= 0.08) return false
+
+  const tmp = `${file}.cfr.mp4`
+  const chain = []
+  if (delta > 0.05) chain.push(`tpad=stop_mode=clone:stop_duration=${delta.toFixed(3)}`)
+  chain.push(`fps=${fps}`)
+  const args = [
+    '-y', '-loglevel', 'error', '-i', file,
+    '-vf', chain.join(','), '-fps_mode', 'cfr',
+    '-c:v', 'libx264', '-crf', '18', '-pix_fmt', 'yuv420p', '-an',
+  ]
+  if (delta < -0.05) args.push('-t', expected.toFixed(3))
+  args.push(tmp)
+  await exec(binaryOf(config, 'ffmpeg'), args, { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
+
+  const after = await probeOutput(config, tmp)
+  if (!Number.isFinite(after.durationSec) || Math.abs(after.durationSec - expected) > 0.12) {
+    throw new Error(`CFR 修正后时长仍不对：期望 ${expected}s，实际 ${after.durationSec}s（${tmp}）`)
+  }
+  renameSync(tmp, file)
+  Object.assign(summary, after)
+  return true
+}
+
 /** 归一化后期参数：枚举/上限之外的值一律夹到合法区间，交给 ffmpeg 之前就把脏输入挡掉。 */
 export function normalizePost(raw) {
   const p = raw && typeof raw === 'object' ? raw : {}
@@ -135,7 +172,8 @@ async function applyPost(config, input, output, fps, post) {
   if (chain.length === 0) return
   await exec(binaryOf(config, 'ffmpeg'), [
     '-y', '-loglevel', 'error', '-i', input,
-    '-vf', chain.join(','), '-c:v', 'libx264', '-crf', '19', '-pix_fmt', 'yuv420p',
+    '-vf', chain.join(','), '-fps_mode', 'cfr', '-r', String(fps),
+    '-c:v', 'libx264', '-crf', '19', '-pix_fmt', 'yuv420p',
     '-an', output,
   ], { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
 }
@@ -252,6 +290,10 @@ export async function inspectFrames(config, args) {
     mode: 'frames',
     requestedTimes: times,
     ...parsed,
+    // 每格顶部约 28px 是 caption 条，不属于画面；不要据此判断"上沿被裁"。
+    storyboardNote: parsed.storyboard.length
+      ? '每格顶部是 caption 条，不是画面；怀疑裁切时看单帧或全图。'
+      : null,
     wallSec: Number(((Date.now() - started) / 1000).toFixed(1)),
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-motion",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Code-generated math & science animations for DeepSeek Harness: frames-first preview, Manim clips, formula checks.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
     "skills",
     "styles",
     "docs",
+    "scripts",
     "cordis.patch.yml",
     "README.md",
     "LICENSE",
@@ -38,10 +39,12 @@
   },
   "scripts": {
     "check": "node --check lib/index.js && node --check lib/ops.js && node --check lib/env.js && node --check lib/doctor.js",
-    "test": "node scripts/test-ops.mjs && node scripts/test-route.mjs",
+    "test": "node scripts/test-ops.mjs && node scripts/test-route.mjs && node scripts/test-plan.mjs && node scripts/test-approvals.mjs",
     "smoke": "node scripts/smoke.mjs",
     "dev": "node scripts/dev.mjs",
     "route": "node scripts/route-style.mjs",
+    "plan": "node scripts/plan-questions.mjs",
+    "approvals": "node scripts/approvals.mjs",
     "styles:index": "node scripts/build-style-index.mjs",
     "styles:check": "node scripts/build-style-index.mjs --check",
     "check:meta": "node scripts/check-meta.mjs",

package/scripts/approvals.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * 项目级确认记录：把“用户确认过什么”落成可追溯的 APPROVALS.json。
+ *
+ *   node scripts/approvals.mjs init <project> --mode light
+ *   node scripts/approvals.mjs set <project> script_storyboard approved --note "用户确认"
+ *   node scripts/approvals.mjs check <project>
+ *   node scripts/approvals.mjs show <project>
+ *
+ * 模式：
+ *   light    ≤15s、无旁白：需求 → 脚本+分镜 → 视觉 → 开工
+ *   standard 15–60s 或有旁白：需求 → 脚本 → 分镜 → 视觉 → 交付 → 开工
+ *   full     >60s 或多段/复杂旁白：再加 animatic
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const FILE = 'APPROVALS.json'
+const LABELS = {
+  requirements: '需求',
+  script: '脚本',
+  script_storyboard: '脚本 + 分镜',
+  storyboard: '分镜',
+  animatic: 'Animatic',
+  look: '视觉（DESIGN + 3 帧）',
+  delivery: '交付清单',
+  start: '开工',
+}
+const MODES = {
+  light: ['requirements', 'script_storyboard', 'look', 'start'],
+  standard: ['requirements', 'script', 'storyboard', 'look', 'delivery', 'start'],
+  full: ['requirements', 'script', 'storyboard', 'animatic', 'look', 'delivery', 'start'],
+}
+const STATUSES = new Set(['pending', 'approved', 'rejected'])
+
+function fail(message) {
+  console.error(message)
+  process.exit(1)
+}
+
+function pathOf(project) {
+  return join(resolve(project), FILE)
+}
+
+function read(project) {
+  const file = pathOf(project)
+  if (!existsSync(file)) fail(`找不到 ${file}；先运行 init`)
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+function write(project, data) {
+  const file = pathOf(project)
+  mkdirSync(resolve(project), { recursive: true })
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+  return file
+}
+
+function init(project, mode) {
+  if (!MODES[mode]) fail(`mode 只能是 ${Object.keys(MODES).join(' / ')}`)
+  const file = pathOf(project)
+  if (existsSync(file)) fail(`${file} 已存在；要重建请先删除`)
+  const stages = {}
+  for (const stage of MODES[mode]) {
+    stages[stage] = { label: LABELS[stage], status: 'pending', at: null, by: null, note: '' }
+  }
+  const data = { version: 1, project: project, mode, createdAt: new Date().toISOString(), stages }
+  write(project, data)
+  console.log(`created ${file} (${mode})`)
+  console.log(`stages: ${MODES[mode].join(' → ')}`)
+}
+
+function set(project, stage, status, options) {
+  if (!STATUSES.has(status)) fail(`status 只能是 ${[...STATUSES].join(' / ')}`)
+  const data = read(project)
+  const order = MODES[data.mode]
+  if (!data.stages[stage]) fail(`${data.mode} 模式没有阶段: ${stage}（有: ${order.join(', ')}）`)
+  if (status === 'approved') {
+    const index = order.indexOf(stage)
+    const missing = order.slice(0, index).filter((key) => data.stages[key].status !== 'approved')
+    if (missing.length) fail(`不能跳过前置阶段: ${missing.map((key) => LABELS[key]).join('、')}`)
+  }
+  data.stages[stage] = {
+    ...data.stages[stage],
+    status,
+    at: new Date().toISOString(),
+    by: options.by ?? 'user',
+    note: options.note ?? data.stages[stage].note ?? '',
+  }
+  write(project, data)
+  console.log(`${stage} → ${status}${options.note ? ` (${options.note})` : ''}`)
+}
+
+function table(data) {
+  const rows = Object.entries(data.stages).map(([key, value]) => {
+    const mark = value.status === 'approved' ? '✅' : value.status === 'rejected' ? '❌' : '⬜'
+    return `${mark} ${value.label.padEnd(14, ' ')} ${value.status.padEnd(8)} ${value.at ?? '-'} ${value.note ?? ''}`
+  })
+  return [`project: ${data.project}  mode: ${data.mode}`, ...rows].join('\n')
+}
+
+function check(project) {
+  const data = read(project)
+  console.log(table(data))
+  const missing = Object.entries(data.stages)
+    .filter(([, value]) => value.status !== 'approved')
+    .map(([key]) => LABELS[key])
+  if (missing.length) {
+    console.error(`\n未确认: ${missing.join('、')}`)
+    process.exit(1)
+  }
+  console.log('\nall approved')
+}
+
+const [command, project, ...rest] = process.argv.slice(2)
+if (!command || !project) fail('用法: node scripts/approvals.mjs init|set|check|show <project> ...')
+
+if (command === 'init') {
+  const modeIndex = rest.indexOf('--mode')
+  const mode = modeIndex >= 0 ? rest[modeIndex + 1] : 'light'
+  init(project, mode)
+} else if (command === 'set') {
+  const [stage, status] = rest
+  const noteIndex = rest.indexOf('--note')
+  const byIndex = rest.indexOf('--by')
+  if (!stage || !status) fail('用法: set <project> <stage> <approved|pending|rejected> [--note ...] [--by ...]')
+  set(project, stage, status, {
+    note: noteIndex >= 0 ? rest[noteIndex + 1] : undefined,
+    by: byIndex >= 0 ? rest[byIndex + 1] : undefined,
+  })
+} else if (command === 'check') {
+  check(project)
+} else if (command === 'show') {
+  console.log(table(read(project)))
+} else {
+  fail(`未知命令: ${command}`)
+}