目标是在两天内完成一个可演示的最小系统:用户用自然语言描述剪辑需求,π Agent 通过受控工具生成或修改 HyperFrames 剪辑代码,完成检查与渲染,并在界面中展示 MP4 和执行过程。
- 首个 MVP 只使用 HyperFrames,不同时维护 Remotion。
- 基本交付包含:基础剪辑、可交互界面、Agent 工具调用、MP4 输出、一次同任务自然语言迭代修改。
- 已落地的进阶模块是“慢放识别与恢复”:从帧时间戳识别连续慢放区间,交给 π 生成 1×/变速/1× 结构化计划,并为音频生成恢复时长与音高的派生轨。
- 人声字幕使用本地 MLX Whisper 识别,带时间戳映射到剪辑后时间线;无可信识别时任务会明确失败,不会用“字幕”占位。
- 结构化计划、受控代码生成和自动检查已落地;把 HyperFrames 检查错误回传给 π 自动修复仍是后续增强项。
- PDF 中的“5 段素材、30 秒竖屏、字幕和 BGM”“数据变视频”“批量成片”是能力示例,不自动视为全部必做项。
完整拆解见 docs/01_需求拆解.md,验收口径见 docs/02_MVP验收清单.md,当前技术选择及版本证据见 docs/04_技术选型记录.md。
apps/agent/:本地 π Agent API、素材分析和受控执行器。apps/web/:素材、目标、事件流和动态预览的 Web 工作台。packages/contracts/:Agent、API 与界面共用的结构化协议。examples/hyperframes-baseline/:合成测试素材和 HyperFrames 基线工程,只用于回归测试。examples/slow-motion-restoration/:真实慢放恢复案例的脱敏计划和处理记录,不含原视频。workspace/jobs/<task-id>/:本地任务工作区;每个任务内聚合输入素材、分析、组合、检查和输出,整体不提交 Git。references/:课题原件与文本提取结果。docs/:需求、验收、技术选型和实施记录。scripts/check-env.sh:只读环境检查。
- 系统 Node.js 26.7.0、Codex 随附 Node.js 24.19.0:两者均满足 HyperFrames 的 Node.js >= 22 要求。
- HyperFrames CLI 0.8.6:15 秒、三场景基线的 lint、runtime、layout、motion、contrast 已全部通过。
- Chrome Headless Shell 152:已重新下载并验证可启动。
- FFmpeg / FFprobe 9.0.1:已通过 Homebrew 安装并验证。
- π SDK:
@earendil-works/pi-coding-agent0.84.2 已安装,类型检查、自定义工具 smoke test 和依赖审计通过。 - π 认证:
openai-codexOAuth 已授权,gpt-5.4-mini已完成一次真实规划调用;令牌未写入仓库或日志。 - Agent 纵向切片:已跑通“上传素材 → FFprobe 元数据 → π 结构化计划 → 受控 HyperFrames 组合 → 完整检查 → 真实素材快照 → 人工确认入口”。
- 前端已提供自定义任务名称、已有任务重命名与确认删除、素材与提示词输入、历史任务选择与新建入口、自动/固定时长、事件流、逐段倍率计划、可播放动态预览、同任务继续修改、时间线取样证据、明确的渲染确认按钮,以及不会跳离页面的 MP4 附件下载和 Finder 定位入口。
- 已检查任务会从
workspace/jobs/恢复;本地服务热重启不会让待确认任务从 API 中消失。动态播放器采用单实例生命周期,重启时自动关闭并可按任务重新启动。 - 页面 URL 固定任务 ID;刷新后会恢复指定任务、事件、检查结果和动态预览,不会因后台测试任务更新时间更晚而跳错任务。
- 真实素材任务
64555b01-2826-464b-8c8d-e8d5cae42026:自动识别 6.82s–118.948s 慢放区间,π 生成 1×/4×/1×、41.365667s 计划,完整检查 0 错误、0 警告;视频按计划变速,派生音轨以 1× 播放,避免浏览器保音调策略造成两次预览听感不一致。 - 同任务迭代任务
2dfdb7ca-05f6-4ac8-bab0-ba45af3b8fd9:未重新上传素材,后续指令只把文字改成“二次修改已生效”,第二版重新检查为 0 错误、0 警告。 - 渲染闭环已用合成任务验证:15.0 秒、1920×1080、30 FPS 的 H.264/AAC MP4 已生成并通过独立 FFprobe、SHA-256 和 HTTP Range 206 校验。该文件只证明系统能力,不冒充用户真实作品。
- 用户真实 MP4 尚未渲染;系统不会在用户检查真实素材预览前自动出片。
完整环境搭建与验证命令见 docs/05_环境搭建说明.md。 基线闭环的素材、检查证据与边界见 docs/06_基线闭环记录.md。 Agent 纵向切片的接口与验证记录见 docs/07_Agent纵向切片记录.md。
运行环境检查:
./scripts/check-env.sh本地启动:
npm install --prefix apps/agent
npm install --prefix apps/web
npm run setup:whisper --prefix apps/agent
npm run dev --prefix apps/agent
# 另开终端
npm run dev --prefix apps/web- 不把 API Key、Cookie 或账号凭证写入仓库。
- Agent 只获得白名单工具,不提供任意 shell 或任意文件写入能力。
- 每个任务写入独立工作目录,源素材只读,输出可追溯。
- 只有通过 HyperFrames 完整检查的组合才允许进入渲染步骤。
POST /api/tasks/:id/render只接受ready_for_render状态;前端点击“确认画面并渲染 MP4”是唯一的出片授权入口。