未知项野外指南 · 实现之后
← 全部示例

合并前先考我一遍

让 Claude 生成一份报告,并附上一个必须通过的小测验,能把"我扫了一眼 diff"变成经过验证的理解——不真正弄懂,这份产物就不会让你觉得"完事了"。

提示词
I want to make sure I understand everything that happened in this change before I merge. Give me an HTML report on the export-feature diff — context, intuition, what was done — with a quiz at the bottom that I must pass.

中文大意:在合并之前,我想确保自己完全理解这次改动里发生的一切。请针对导出功能的 diff 给我一份 HTML 报告——背景、直觉、做了什么——并在底部附上一个我必须通过的小测验。

Claude 的产出
Acme · 合并就绪报告

片段导出:改了什么,为什么改

这个涉及 14 个文件的 diff 为审阅讨论串加入了服务端片段导出。先读完下面三节,再通过小测验。过不了,就说明你还没准备好合并——这正是本页的用意。

feature/clip-exportmain · 14 个文件 · 9 次提交
14
文件变更
+612
新增行数
−148
删除行数

心智模型

一张图胜过 14 个文件:导出请求现在走哪条路,之前又走哪条。

在这次改动之前,"导出片段"意味着浏览器用 MediaRecorder 在客户端逐帧拼接并上传结果——又慢、又锁死标签页,而且在 Safari 上根本跑不通。现在客户端只负责发起导出请求;新增的 worker 会基于原始媒体在服务端渲染,客户端则轮询任务状态,直到拿到签名下载 URL(signed URL)。

改动前 · 客户端渲染
ReviewPlayer.tsx
MediaRecorder 采集(在标签页内)
约 40–90 秒,标签页被锁死
PUT /uploads(整个文件)
S3 exports/ 存储桶
改动后 · 服务端任务
ReviewPlayer.tsx
POST /api/exports(返回任务 id)
export-worker(新增,ffmpeg)
S3 exports/ 存储桶
jobs 表(新增)
客户端每 2 秒轮询一次
GET /api/exports/:id → 签名 URL

本次改动引入的三个不易察觉的行为

这些是扫一眼 diff 看不出来的部分。每一条都是刻意为之——理由如下。

01

导出基于原始上传件渲染,而不是审阅者看的代理版本

是什么worker 拉取的是 media/originals/,从不使用 720p 审阅代理。因此导出的片段可能比审阅者当初画批注时看到的画面更清晰
为什么剪辑师导出片段是要交付给客户的;把压缩过的代理版本交出去会让他们丢面子。批注坐标以归一化形式(0–1)存储,所以能正确地重新投影到全分辨率画面上。
在哪里worker/export/render.ts:41 worker/export/burn_in.ts:88
02

导出任务能扛住 worker 崩溃——靠可见性超时(visibility timeout),而非重试

是什么任务行通过设置 locked_until = now() + 10min 被认领。如果 worker 在渲染中途挂掉,不会触发任何重试;锁到期后,下一个空闲的 worker 会从头接手这个任务。
为什么ffmpeg 渲染在中途不具备幂等性,而重试队列又需要我们暂时不想引入的死信(dead-letter)处理。靠锁过期,只用一个字段就实现了至少一次(at-least-once)语义。代价是:崩溃的任务在恢复前最多会显示"处理中"长达 10 分钟。
在哪里db/migrations/0142_export_jobs.sql worker/export/claim.ts:19
03

下载 URL 24 小时后过期——导出文件本身保留 7 天

是什么GET /api/exports/:id 返回的 S3 签名 URL 有效期为 24 小时,但底层对象要等 7 天生命周期规则触发后才会删除。重新请求该接口会签发一个新 URL,无需重新渲染。
为什么短效 URL 能限制链接被转发到工作区之外(导出内容可能包含未发布的素材);而对象保留期更长意味着救活一条失效的 Slack 链接只需一次 API 调用,而不是 90 秒的重新渲染。
在哪里api/exports/get.ts:57 infra/s3_lifecycle.tf:23
所依赖的既有行为

工作区级签名 URL 鉴权。 GET /api/exports/:id 自己不做任何权限检查——它复用了已经守护所有媒体路由的 requireWorkspaceMember 中间件。一旦这个中间件的会话处理发生变化(有一张关于访客审阅者会话的未关闭工单 BL-2214),导出下载的行为也会跟着变。而这个 diff 里没有任何东西会提醒你这一点。

第二部分 · 证明你懂了

合并前的六道题

不是冷知识——每一题都是你在故障处理或代码评审中必须做对的决定。
得分:0 / 6 · 已答 0

可以合并了

6/6——这次改动,你已经能讲清楚给任何为它被 on-call 叫醒的人听。标准清单如下。

  • 理解已验证(本测验 6/6)
  • feature/clip-export 分支 CI 全绿 · 412 个测试
  • 迁移 0142 已审 — 纯新增,无需回填
  • squash 合并,用上面的摘要作为提交说明正文
  • 部署后盯 export-worker 仪表盘 30 分钟
  • 在合并评论里注明对 BL-2214 的依赖

还不行——请重读以下小节

下面这些题你答错了。这些盲区可以直接对应回报告的相应小节: