Skip to content

Commit c1db796

Browse files
SanHsienclaude
andcommitted
docs(upstream): record the 933ae3e batch, advance commit, PR and issue watermarks
Commit watermark 933ae3e, PR watermark heygen-com#6479, issue watermark heygen-com#6465. Every PR from heygen-com#6460 on and issue heygen-com#6465 now has a conclusion against its current head SHA. Also fixes two inaccuracies in the previous entry: a literal backslash-n that had become a real newline inside inline code, and the description of the golden changes. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 6bdc7cd commit c1db796

4 files changed

Lines changed: 56 additions & 7 deletions

File tree

‎docs/DECISIONS.md‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -628,12 +628,11 @@ fork 專有程式與這批 commit 重疊的只有 17 個檔(上面 5 個衝突
628628

629629
**判準八掃描**:對 `ad4d3fad1..8f618c5ff` 的 1,497 行新增行(分兩段:`ad4d3fad1..15367a9f6` 1,191 行、`15367a9f6..8f618c5ff` 306 行)掃空白夾內容、`eval(`/`new Function(`/`globalThis.`/`global.require`/`atob(`/`fromCharCode`、120 字元以上的 base64/hex、零寬與雙向控制字元、400 字元以上單行:0 命中。另對 22 個 open PR 的目前 head diff 掃同一組:只有 #6433 測試裡的 puppeteer `page.$eval`、#6454 測試裡把包裝後腳本放進假 `window` 的 `new Function(`,都是良性。
630630

631-
**唯一衝突:#6436 與本 fork 的 `Function()` 包裝**(`compositionScoping.ts`)。前一輪預判「不能照抄」,這次實測確認。上游在原始碼兩側插入 `/*hf-authored-begin*/`/`end`,頁面端的 `authorScriptsMayRegisterTimelines` 只讀兩標記之間的文字,藉此把包裝自己的 `__timelines` 排除。本 fork 把作者程式放進 `Function(...)` 的 JSON 字串字面值,如果標記圍在字面值外面,掃描讀到的就是整個包裝,包裝自己提到 `__timelines`,永遠回 true,修正等於不生效。做法:標記放進字面值內(`jsonScriptLiteral(BEGIN + source + "
632-
" + END)`),begin 標記與第一行原始碼同一行,錯誤行號不位移。證據:
631+
**唯一衝突:#6436 與本 fork 的 `Function()` 包裝**(`compositionScoping.ts`)。前一輪預判「不能照抄」,這次實測確認。上游在原始碼兩側插入 `/*hf-authored-begin*/`/`end`,頁面端的 `authorScriptsMayRegisterTimelines` 只讀兩標記之間的文字,藉此把包裝自己的 `__timelines` 排除。本 fork 把作者程式放進 `Function(...)` 的 JSON 字串字面值,如果標記圍在字面值外面,掃描讀到的就是整個包裝,包裝自己提到 `__timelines`,永遠回 true,修正等於不生效。做法:標記放進字面值內(`jsonScriptLiteral(BEGIN + source + "\n" + END)`),begin 標記與第一行原始碼同一行,錯誤行號不位移。證據:
633632

634633
- 新增 `packages/engine/src/services/frameCapture-authorScan.scopedWrapper.test.ts`,用 `@hyperframes/core/compiler` 的真實 `wrapScopedCompositionScript` 輸出跑上游的掃描;把標記拿掉再重建 core dist,第一個測試失敗(`expected true to be false`),放回後 3 通過。
635634
- `compositionScoping.test.ts` 的分隔符測試改寫成釘性質(作者程式在標記之間、包裝自己的 `__timelines` 在標記之外、含引號與角括號的 `__timelines` 仍在區內、begin 標記同行);原本釘「字面值等於原始碼」的測試改成等於「標記+原始碼+標記」。
636-
- `pageBuild.preview.html`/`pageBuild.render.html` 兩份 golden 只多兩行標記註解(逐行比對 diff)。
635+
- `pageBuild.preview.html`/`pageBuild.render.html` 兩份 golden 各有 3 個 wrapper,每個 wrapper 的改動是:開頭那一行行尾接上 begin 標記(1 行改動),結尾多出一行獨立的 end 標記(作者程式後的 `\n` 讓原結尾行前多一個空行,結尾行本身變成 end 標記開頭);每份 golden 共 +9/-6(逐行比對 diff,見 `90423ccbd` 的 merge diff)。
637636

638637
**逐項處理(commit 軸)**:
639638

@@ -666,3 +665,48 @@ fork 專有程式與這批 commit 重疊的只有 17 個檔(上面 5 個衝突
666665
- player 23 項失敗是 Node 26 的 `localStorage` 全域;`NODE_OPTIONS=--no-experimental-webstorage` 後 386 通過。studio 18、studio-server 134 通過。
667666
- `scripts/package-subpaths.test.mjs` 仍只有已知的路徑寫死失敗(`/repo/...` vs `C:\repo\...`)。
668667
- 提交:`LEFTHOOK_EXCLUDE=fallow`,其餘 hook 實跑(`typecheck`、`cli-process-ownership`、`commitlint` 等);`fallow` 理由同前幾條。`8f618c5ff` 那次 merge 我誤跑過一次不帶排除的 `git commit --no-edit`,hook 全數實跑並通過,隨後用排除 fallow 的 amend 改訊息(沒有 `--no-verify`)。
668+
669+
## 2026-10-27(第五續):上游追到 `933ae3eb5`,commit 水位推進,PR 水位 #6479,issue 水位 #6465
670+
671+
**決定**:前一條「未審完」的清單(PR #6460 起、issue #6465)在此逐筆處理完,三個水位一起推進。審查期間上游又前進兩次(先是 `8f618c5ff` → `6dee9d144`,再到 `933ae3eb5`,PR 編號從 #6476 長到 #6479),所以這一批追到的是提交前最後一次 `git fetch upstream` 的 `933ae3eb5`;之後若再前進,`--strict` 會是紅的,這是預期。commit 軸以 5 個 merge 帶入,各自可單獨還原:`6263c2b3b`(`306f21a1b`)、`3e29570a5`(`6dee9d144`)、`0296f41ac`(`020e6c99f`)、`97dc6e63a`(`e42318d08`)、`ee2ea67c5`(`933ae3eb5`),另有一個修正 commit `6bdc7cdf5` 把 `永不採用` 的上游身分資訊拿掉(見下)。
672+
673+
**判準八掃描**:commit 軸對 `8f618c5ff..6dee9d144` 的 187 行與 `6dee9d144..933ae3eb5` 的 670 行新增行;PR 軸對 12 筆新的 open PR(首次 head 共 1,251 行新增行)與 10 筆前一輪仍 open 的 PR 目前 head。掃空白夾內容(`\S\s{40,}\S`)、`eval(`/`new Function(`/`globalThis.`/`global.require`/`atob(`/`fromCharCode`/`Buffer.from(…base64)`、120 字元以上的 base64、120 位元組以上的 hex、零寬與雙向控制字元、400 字元以上單行:全部 0 隱藏內容。命中的都是已知良性:`#6454` 測試把包裝後腳本放進假 `window` 求值的 `new Function(`(commit 軸 1 次)、`#6433` 測試的 puppeteer `page.$eval`(3 次)。**審查中有兩筆被強推換版,換版後各重掃一次**:`#6444` 從 `b42613181` 換成 `2d9037311`(28 檔 +801 → 31 檔 +874/-35;差異是把 `studioServer.ts` 的四個編碼欄位收進 `encoderJobOptions()`、位元率上限多接受 `G` 單位、因 #6467 合併而改動 `integration-tests.json`),`#6474` 從 `f465e9cb9` 換成 `ce894665a`(只差一個測試呼叫的排版)。所有 PR 的結論都針對下表記的 head,之後再換版要重掃。
674+
675+
**commit 軸(已合併進上游的)**:
676+
677+
| 上游 | 內容 | 本 fork 的狀態 | 結論 |
678+
| --- | --- | --- | --- |
679+
| #6458 `306f21a1b`(原列 open,`d6f782686`) | 組合路徑錯誤訊息帶出解析後的入口與專案目錄;`renderArgs.ts` 的 `--composition` 解析搬到新檔 `compositionEntry.ts` | 6 檔皆非分歧檔 | 合併;`renderArgs`、`cloud/render` 2 檔 50 通過、1 跳過 |
680+
| #6463 `6dee9d144`(`ea99169c6`) | `init` 建檔在拒絕硬連結的環境也能用,`writeNewFileSync` 改呼叫 `@hyperframes/core/atomic-file` 的 `createFileAtomically` | **這筆本線需要**:fork 從 #6464 帶進 `createFileAtomically` 後,只有 `projectLock.ts` 在用,`writeNewFile.ts` 仍是自己的 `linkSync`(呼叫端 `init.ts`、`capture/scaffolding.ts`、`tts/synthesize.ts`、`projectConfig.ts` 都沒受益),在 FAT/exFAT 或拒絕硬連結的磁碟上 `init` 會失敗;`atomicFile.ts` 的 `NO_HARD_LINKS` 含 `EPERM`/`ENOTSUP`/`EOPNOTSUPP`/`EXDEV`/`EISDIR`。`projectConfig.create.test.ts` 是分歧檔(fork 把「dangling symlink」測試加上 Windows 無權建立符號連結時的跳過),但上游 hunk 在檔案開頭與 `47` 行附近,fork 的差異在 `55` 行之後,自動合併 | 合併;`projectConfig.create` 3 通過(新增的 EPERM 測試通過、符號連結那項照舊在 Windows 跳過),加 `commands/init*`、`capture/scaffolding`、`projectConfig*` 共 10 檔 156 通過、3 跳過 |
681+
| #6454 `020e6c99f`(原列 open,`5caeff07d`) | `check` 處理切掉下伸部的遮罩,與共用場景自己的選擇器;`compositionScoping.ts` 的選擇器正規化多一段,兩份 golden 重算 | 前一條預告「合併時 golden 要對 #6436 的標記重算」:`compositionScoping.ts` 的 hunk 在 wrapper 前置程式,fork 的 `Function()` 字串與 `AUTHORED_SOURCE_BEGIN`/`END` 標記在後面,不重疊;兩份 golden 自動合併,標記保留,且多出 `__hfTimelineRootSelectorPattern` 一行與一個 `if` 區塊 | 合併;core `compositionScoping`+`pageBuild` 3 檔 89 通過(重建 core dist 後);engine `frameCapture-authorScan.scopedWrapper`+`subTimeline*` 4 檔 37 通過;cli `layout-audit*` 2 檔 230 通過。**未驗證**:`layout-audit.chromium.test.ts` 需要 Chrome,本機 Chrome 在 30 秒的 hook 內起不來(與前幾條同一個環境問題),63 項被跳過 |
682+
| #5255 `5279b6f47` | parsers 的媒體來源寫入在各自的詞法範圍解析 | 非分歧檔 | 合併;parsers `mediaSrcMutation` 17 通過;lint `media` 145 通過(要先 `bun run --cwd packages/parsers build`,否則 3 項因 dist 過期失敗);producer `probeStage`(`bun:test`)70 通過 |
683+
| #6467 `9b339e37c`(`0484fe2ff`) | producer 的整合測試清單移到 `integration-tests.json`,`test-reachability.json` 的 pin 跟著換 | `test-classification.mjs` 非分歧檔,fork 的檔案雜湊與上游舊 pin 相同;合併後 sha256 為 `e0874fac…`,與 `test-reachability.json:50` 一致 | 合併;`node --test scripts/test-classification.test.mjs` 6 通過。`scripts/check-test-reachability.mjs` 本 fork 的 CI 與 hook 都沒接,手動跑印出 2,099 行,全是 `no CI runner selects this test`(fork CI 只有 Windows 用的 workflow),沒有 pin 不符的訊息;合併前的輸出沒有留,所以不能說這 2,099 行不是新增的 |
684+
| #6470 `933ae3eb5`(`9c2cbc214`) | drawElement 的 worker 編碼失敗改走 fresh-session 復原(`asDrawElementCaptureFailure`) | `frameCapture.ts` 非分歧檔,缺陷在本 fork 存在(`captureFrameToBufferPipelined` 直接取 `produceDrawElementFrame` 的 `encodeResult`) | 合併;`frameCapture-freshFallback` 20 通過 |
685+
| #6468 `25b7cbd45`(`83ecb8f83`) | `docs/download-attribution.js`:點擊 `hyperframes.dev/studio/download` 時把 docs 訪客的 PostHog `distinct_id` 以 `ph_id` 附上 | 純文件站腳本,只在 Mintlify 站上跑,且只有頁面已載入 PostHog(`docs.json` 的 `integrations.posthog`,fork 既有,帶上游的 `apiKey`)、訪客沒有拒絕追蹤時才作用;腳本只在點擊時改 `href`,點完還原。本 fork 沒有部署 docs 站(`FORK.md`、`README.md` 沒有 Mintlify 的紀錄) | 合併,**目前是惰性的**。**觸發條件(要移除)**:fork 一旦把 `docs/` 部署到任何站,要同時移除 `docs/download-attribution.js` 與 `docs.json` 的 `integrations.posthog`,否則會把 fork 訪客的 id 送到上游的 PostHog 專案與 `hyperframes.dev`。這是維護者的隱私決定,本次沒有替維護者做 |
686+
| #6407/#6408/#6411 `08eeb4979`、`772cc95e8`、`e42318d08` | npm homepage 指向 `hyperframes.heygen.com`、官方 MCP registry 的 `server.json`、認領 context7(`context7.json` 的 `url`+`public_key`) | 「2026-10-26(補)」已寫 **永不採用**:fork 不發佈,也不該替上游登錄或認領 | commit 軸必須整批 merge,所以先合併再用 `6bdc7cdf5` 還原三處(刪 `server.json`、`context7.json` 與 `packages/cli/package.json` 還原到合併前);日後上游再動這三個檔,合併時一樣取 fork 這一邊 |
687+
688+
**PR 軸(#6460–#6479,19 筆 PR+issue #6465)**:已合併的 #6461、#6464、#6469 上一批已帶入,#6463、#6467、#6468、#6470 在上表。其餘 12 筆全部 open,逐筆取目前 head、讀 diff、對合併後的樹做 `git apply --check`(全部可套用);全部不採用、等上游合併後隨 commit 軸帶入,除非下面另有觸發條件。
689+
690+
| PR | 審查時 head | 內容 | 本 fork 對應檔案的實際狀態 | 結論與觸發 |
691+
| --- | --- | --- | --- | --- |
692+
| #6460 | `8549d66af6a3a332bf1517f4a0328529680513b2`(24 檔 +248/-180,維護者) | 暫停預覽的 seek 落在組合自己的 frame rate:runtime 的 `canonicalFps` 改為 `renderFps ?? data-fps ?? 30`,studio 的逐格、時間碼、跳格、尺規改用組合的 rate,`parseFps` 搬到 `core/src/fps.ts`,protocol 把 `n/1001` 的 rate 精確送出 | **缺陷在本 fork 存在**:`core/src/runtime/init.ts:541` 是 `state.canonicalFps = exportRenderFps.fps ?? state.canonicalFps`(預設 `state.ts:102` 的 30);`studio/src/player/lib/time.ts:1` 的 `STUDIO_PREVIEW_FPS = 30` 仍是各 helper 的預設,`linkedClipPreferences.ts:27` 的 `compositionFps` 只有 `OutOfSyncBadge` 在讀。所以 25、60、29.97 fps 的組合在預覽逐格會落在 30 fps 的格線上(PR 內文的量測:29.97 fps 在 600 格中只有 1 格正確)。fork 分歧檔:只有 `ShortcutsPanel.test.tsx`,PR 沒碰 | 不採用:24 檔橫跨 runtime 訊息協定與 studio 的格數運算,open 中。**觸發:合併**;或本線有人回報非 30 fps 組合在預覽逐格錯位。這筆合併時不需要特別處理,但要在 Windows 上實跑一次非 30 fps 的預覽逐格 |
693+
| #6462 | `eb804f0a6b64b39b1bf2b93fa8f1fe9b9f7965fd` | 三個 Dockerfile 的 Node 基底映像 22.23.3 → 22.23.4(CVE-2026-111497) | 只動 `Dockerfile.test`、`cli/src/docker/Dockerfile.render`、`gcp-cloud-run/Dockerfile`(後兩者與 `Dockerfile.test` 在 fork 各有 1 行差異,不重疊);已被 #6440 涵蓋(同三檔,另外升 bun 到 1.4.4) | 不採用;Windows 原生路徑不用這些映像。觸發:合併,或本線開始建置這些映像 |
694+
| #6466(對應 issue #6465) | `5a20b67ddd7445109569e65f0a436b3b847256a4`(外部) | `findPreviewServerForProject` 的 loopback 探測先用 `node:net` 以 1 秒為界連線再 `fetch`,因為 WSL 2 mirrored 網路或隱身模式防火牆會丟棄而不是拒絕連線,`fetch` 要等 10 秒 | 缺陷在本 fork 存在(`studioSelectionClient.ts:66` 的 `fetchImpl: typeof fetch = fetch`,無界);**但本機實測不會發生**:這台 Windows 對關閉的 `127.0.0.1:5190` 的 `fetch` 在 31 ms 內回 `ECONNREFUSED`(Node v26.12.1) | 不採用。觸發:合併,或本線在 WSL 2 mirrored/有防火牆丟棄封包的環境回報 `render`/`check`/`snapshot` 多等 10 秒。**issue #6465**:同上,等 #6466 |
695+
| #6471 | `c216986ba94ec4999651a9bff61c38c93d3d9e55`(外部,4 檔 +29/-15) | 下載連結多帶 `src=cli`/`src=browser-editor`,讓 `hyperframes.dev` 分辨連結從哪裡點的 | `desktopApp.ts`、`desktopRoutes.ts` 非分歧檔;只加查詢參數,不含識別資料 | 不採用;觸發:合併(合併後 Windows 的 `desktopDownloadUrl()` 會變成 `…?os=windows&src=cli`,測試要跟著換)。是上游的行銷歸因,對本線無用 |
696+
| #6472 | `21968d83d0bdd67d3f664095bb020d00e0d97bdb`(外部) | 兩份 docs 加 `keywords` | 純文件 | 不採用;觸發:合併 |
697+
| #6473 | `0348f90f0c977d15b7483c87740ad7fab9138bb3`(codegen bot) | 重新產生雲端 render 客戶端型別,**移除** `CreateHyperframesRenderRequest.page_motion_blur` | **這個 PR 單獨會讓型別檢查失敗**:本 fork 的 `commands/cloud/render.ts:814,843` 與 `render.pageMotionBlur.test.ts` 都在用這個欄位;PR 自己的 CI 也是 `Typecheck` 紅燈、`REVIEW_REQUIRED` | 不採用。觸發:合併(且上游同時處理 `page_motion_blur` 的使用處);合併前不要手動套這個型別檔 |
698+
| #6474 | `ce894665aab3cdbacf57ece6b32a117b13faa3a0`(10 檔 +149/-22,維護者;先讀的是 `f465e9cb9`) | **Windows**:TEMP 資料夾拒絕刪除時,音訊暫存的清理(`rmSync`)與 `renameWithRetry` 的 `EPERM` 不再讓整個 render 變成「Audio mix failed; output would be video-only」;新增 `removeScratch`、rename 重試用盡後改複製 | 缺陷在本 fork 存在(`audioMixer.ts`、`aacEncode.ts`、`audioFxRender.ts`、`audioPadTrim.ts`、`audioStage.ts` 都是裸 `rmSync`,`renameWithRetry.ts` 重試用盡就拋出);回報條件是受限的 TEMP(`icacls` 拒絕子項刪除),本機預設 TEMP 不適用 | 不採用:open 中,且 PR 內文自述沒有在真實使用者環境驗證,只有 CI 上一個 ACL 拒絕刪除的案例。**觸發:合併,或本線 Windows render 出現 `Audio mix failed … EPERM`**(這種情況可以先單獨移植 `removeScratch` 與複製後備) |
699+
| #6475 | `fc0462abda4f05c0585e99284e6c23f5e823bd31`(4 檔 +203/-98,維護者) | `history show --diff` 不再呼叫 `git diff --no-index`,改用自寫的 Myers 差異(`unifiedDiff.ts`);移除「git 輸出檔路徑在 git 結束後被換掉」的競爭測試(隨著被取代的程式碼一起拿掉) | 缺陷在本 fork 存在(`history.ts` 的 `textDiff` 呼叫 `spawnSync("git", …)`,沒有 git 就拒絕);本機有 git,不受影響。PR 的移除不削弱防線:被刪的是它取代的那段 spawn+讀回輸出檔的程式碼 | 不採用;觸發:合併,或本線在沒有 git 的 Windows 上回報 `--diff needs git on PATH` |
700+
| #6476 | `ad89ecd73f27548e460a7b15dd1ba7b46ebc6c74`(2 檔 +27/-1) | 把檔案當成專案資料夾傳入時,錯誤訊息指出該傳哪個資料夾 | `utils/project.ts` 非分歧檔 | 不採用;訊息改進。觸發:合併 |
701+
| #6477 | `21e313f3045432c590bb24d2883d8e26f99d88d5`(6 檔 +244/-5,維護者) | studio 的媒體探測與縮圖解碼讀不到檔案時,兩次重試後放棄並只印一行(不含 URL),取代 mediabunny 預設對同源網路失敗的無限重試 | `mediaProbe.ts`、`thumbnailVideoDecoder.ts` 非分歧檔;缺陷在本 fork 存在;被其他程式鎖住的媒體檔在 Windows 比較常見 | 不採用;觸發:合併,或本線 studio 預覽出現成串的 `TypeError: Failed to fetch` |
702+
| #6478 | `6239ad722a7aa431aebe74e5bd7f45fe41448d7e`(外部,6 檔 +14/-12) | docs:HyperFrames app 的 Windows 設定資料夾(`%APPDATA%\HyperFrames`)、快捷鍵、「your computer」措辭 | 純文件 | 不採用;觸發:合併 |
703+
| #6479 | `34cf685dc181fd1d823e74c5c88dc45b0eb740bc`(2 檔 +68/-2,維護者) | `HYPERFRAMES_BROWSER_PATH` 指向不存在的路徑時立刻報錯並點名;首次下載 Chrome 時每 15 秒印一行提示 | `browser/manager.ts` 非分歧檔;行為改變:現在是靜默繼續找其他瀏覽器,合併後變成拋出 | 不採用;觸發:合併。合併時確認維護者的環境變數沒有指向一個已不存在的路徑 |
704+
705+
**前一輪仍 open 的 PR 目前 head**(`git apply --check` 對合併後的樹全部可套用;結論不變,等上游合併):#6428 `781935309`、#6433 `85748ef02`、#6434 `8106c6bad`、#6437 `0d618045d`、#6440 `c18b1d9ee`(3 檔 +5/-5:三個 Dockerfile 的 Node 22.23.4 與 bun 1.4.4,**這次讀了 diff**,涵蓋 #6462)、#6441 `2deec4775`、#6444 `2d9037311`(換版,見上;**這次讀了 diff**:與 fork 分歧檔的重疊是 `engine/src/index.ts`、`producer/src/server.ts`,hunk 不同區)、#6452 `68ddd6411`、#6456 `eabf072d8`。#6438 `4b10a8d3e` 的 base 仍是 `fix/player-audio-joins`(39 檔 +893/-270),不能獨立合併。#6444 與已合併的 #6467 都動 `test-classification.mjs`/`integration-tests.json`/`test-reachability.json`,合併時要重新對一次。
706+
707+
**驗證**(皆在合併後的樹,Windows 11 本機,Node 26;`NODE_OPTIONS=--no-experimental-webstorage --disable-warning=DEP0205`):
708+
709+
- 型別:每個 merge commit 的 pre-commit `typecheck` hook 實跑並通過(`6263c2b3b`、`3e29570a5`、`0296f41ac`、`97dc6e63a`、`ee2ea67c5`)。
710+
- 測試:見上表各列;另外 cli 的 `projectLock` 與 `previewLifecycle` 等前一批的檔案這次沒有重跑。
711+
- 未驗證:`layout-audit.chromium.test.ts`(Chrome 起不來);producer 的整合測試(`deliveryRender.integration`、`wrappedMountTiming.integration` 等)沒有執行。
712+
- 提交:`LEFTHOOK_EXCLUDE=fallow`,其餘 hook 實跑(`tracked-artifacts`、`lint`、`format`、`largefiles`、`cli-process-ownership`、`typecheck`、`commitlint`);`fallow` 理由同前幾條。

0 commit comments

Comments
 (0)