balantrapu87/amds

运动工作室 SDLC 执行手册

当被要求在此仓库中实现功能或修复缺陷时，请严格按照以下步骤执行：

步骤 1：契约同步（规范门）

1. 检查 engine/schemas.py 和 remotion/src/types.ts。
2. 添加或修改字段以满足功能需求。
3. 验证 Pydantic 模型可编译：

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   （注意：如果项目虚拟环境存在，请通过 .venv/bin/python3 调用）。
4. 在两个语言的契约对齐之前，切勿进入实现代码阶段。

步骤 2：红阶段（编写失败测试）

1. 在 tests/（Pytest）或 remotion/src/__tests__/（Vitest/Jest）下编写新的测试文件或测试用例。
2. 断言模式验证、边界情况和预期的序列化输出。
3. 运行测试并确认失败：

   pytest tests/
   # 如果 remotion/package.json 中配置了前端测试运行器：
   npm --prefix remotion test -- --run
   

4. 记录失败跟踪信息。如果测试立即通过，请重写以测试实际的新能力。红阶段仅当测试因预期断言而失败时才视为满足。

步骤 3：绿阶段（最小实现）

1. 在 engine/ 或 remotion/src/ 中编写最少的代码以满足失败的测试。
2. 在 Remotion 中，严格遵守确定性帧法则：
   • 派生必须严格来自 useCurrentFrame() 和 useVideoConfig()。
   • 绝不能使用 Date.now()、Math.random() 或无界的 requestAnimationFrame()。
3. 保留现有的架构模式（<Series>、<Sequence>、<ThreeScene>、<KineticScene>）。
4. 确保矢量资源根据 remotion/svgo.config.mjs 保留 ID 和类，以便 GSAP 进行定位。

步骤 4：质量门与自动自愈循环

跟踪循环迭代计数器（ATTEMPT ∈ {1, 2, 3}）。依次运行每个门，不要屏蔽退出码（不要追加 || true）：

# 第 1 层：静态类型分析
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# 第 2 层：自动化测试套件
pytest tests/
# 如果 remotion/package.json 中配置了前端测试运行器：
npm --prefix remotion test -- --run

# 第 3 层：无头 Chromium 帧栅格化
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

自愈与回滚策略

• 失败时（第 1 或 2 次尝试）：

  1. 捕获确切的文件路径、失败行号以及 stderr/跟踪信息。
  2. 实施一个严格解决报告错误的最小定向补丁。
  3. 增加 ATTEMPT 计数器并重新从第 1 层开始。

• 失败时（第 3 次尝试 - 预算耗尽）： 立即停止推测性修改，并且只恢复已更改和创建的功能文件（绝不要执行全局清理）：

  # 第 4 层耗尽回退：仅针对功能代码范围
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "质量门在 3 次尝试后失败。目标代码路径已恢复到干净基线。"
  exit 1
  

  （替代方法：使用 git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/ 保留更改以供事后分析）

• 成功时（所有层退出码为 0）： 删除临时产物并创建已验证的提交：

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implement verified feature with green test gate"