/github-year-in-review

你在 GitHub 上的一年，化作一支 45 秒的影片，可以隨時分享。

這是 /brag 的姊妹技能：/brag 將一個專案變成啟動影片，而這個技能則將一個人的年度變成影片。它們使用相同的渲染路徑（HyperFrames）與相同的交付方式（預告海報作為第 0 幀、分享文案）。不同之處在於，故事素材是數據，因此數據與節奏邏輯以腳本形式提供，而 AI 代理的任務是檢驗數據、潤飾文案、檢查幀畫面並完成交付。

觸發方式

/github-year-in-review
/github-year-in-review --user octocat --year 2025
/github-year-in-review --include-private --no-music

選項	預設值
`--user`	已通過驗證的 `gh` 使用者
`--year`	今年（12 月 31 日前會標示「至今」）
`--tz`	本機時區（用於「每日活躍時段」節拍）
`--include-private`	關閉：私有倉庫會被計入，但不會被指名
`--no-music`	若有可用音樂則開啟
`--format`	`portrait` 1080x1350（唯一提供的格式）

輸出檔案會放在當前目錄下的 year-in-review-<使用者>-<年份>/ 資料夾中（若已存在則加上時間戳記）。<skill-dir> 是存放此檔案的目錄。

需求

gh 已通過驗證（gh auth status）、Python 3.9+、Node 18+ 並安裝 npx hyperframes、ffmpeg。需要 HyperFrames 領域技能（hyperframes-core、hyperframes-cli）來進行檢查與渲染。

步驟 1：收集資料

python3 <skill-dir>/scripts/collect.py --user <登入名稱> --year <年份> --out <輸出目錄>/year.json

對於活躍帳號約需兩分鐘（提交歷史會被抽樣以分析時段規律）。它會寫入總計數、每日日曆、節奏（連續天數、時段、工作日）、熱門倉庫、程式語言、Pull Request、新倉庫、今年獲得的星星數，以及自動化：至少 60% 的抽樣提交共用同一則訊息模板（像是以使用者名義執行的 cron 任務）的倉庫。自動化資料不會進入節奏與「工作」節拍，而是成為一個獨立的驚喜節拍。

它也會收集可選的主題性資料：代理（與程式碼代理共同撰寫的提交，僅從簽名檢測，加上透過註腳、應用作者與 claude/ 風格分支前綴的代理 PR）、今年標記的版本，以及最大的合併 PR。這些只有在數量達到門檻時才會成為節拍（門檻定義在 references/story.md 中）。

關卡： 在建構前閱讀 year.json 並進行合理性檢查。頭條總計數應與使用者 GitHub 個人頁面上該年份的數字相符。如果發現問題（例如檢測器未偵測到的機器人、不應被指名的倉庫），請修正收集器或在 story.json 中使用覆寫；切勿手動編輯數字到合成腳本中。

步驟 2：故事腳本

python3 <skill-dir>/scripts/build.py <輸出目錄>/year.json --out <輸出目錄> \
  [--music <音樂檔.mp3> --cues <音樂提示點.json>]

這會寫入 <輸出目錄>/story.json（節拍、文案、時間點）、<輸出目錄>/composition/（影片檔案）與 <輸出目錄>/thumbnail/（用於封面的結尾定格畫面，長度 1 秒，請見步驟 4）。節拍、其資料與後備方案在 references/story.md 中定義。資料不足的節拍會被移除，因此安靜的一年會產生較短的影片，而非空白的影片。

然後閱讀 story.json，並在你能比預設文案更具體的地方改進文案（字幕、原型名稱與原因、工作節拍的引言）。規則：

每一項聲明都必須與 year.json 中的資料相符。不得發明數字，不得使用資料不支持的誇飾。
句子要簡短。字體刻意設計得很大；任何超過約 12 個詞的句子都無法停留足夠時間。
除非使用 --include-private，否則不得提及私有倉庫名稱。
不使用表情符號、不省略破折號、不使用「超棒」這類口吻。這是要放在 LinkedIn 上的。
將代理與自動化框架定位為使用者領導的團隊（「與...一同交付」、「與...共同撰寫」）。絕不貶低、絕不暗示這些工作較不屬於使用者；代理計數是下限值。

從編輯後的故事腳本使用 --story <輸出目錄>/story.json 重新建構（時間點會重新推導）。

音樂：如果已安裝 /brag，其內含的音樂與提示點預設值可以直接使用（<brag-dir>/assets/music/*.mp3、<brag-dir>/assets/music/cues/*.music-cues.json）。偏好選擇至少與影片等長的音樂。使用 --cues 時，場景開始點會對齊最近的節拍。若無音樂，影片將為無聲，這也沒問題：LinkedIn 預設靜音播放。

步驟 3：檢查、渲染、審視

cd <輸出目錄>/composition
npx hyperframes check                       # 關卡：零錯誤；也要修復 line_unread 與 type-floor 警告
npx hyperframes render --quality draft --output ../draft.mp4

從每個節拍中提取一個穩定的幀畫面，並在渲染最終版本前親自檢查每一幀。同時檢查每個章節卡片在其指令輸入完成後的畫面（約卡片開始後 2.5 秒）：完整的指令必須顯示在畫面上，單行，暗色背景上的白色文字。

for t in $(jq -r '.beats[]|.start+.duration-0.5' ../story.json); do
  ffmpeg -loglevel error -ss $t -i ../draft.mp4 -frames:v 1 ../frame-$t.png; done

檢查是否有：文字溢出或被裁切、與 year.json 不符的數字、空白或無趣的節拍、在手機尺寸下無法閱讀的文字（將幀畫面縮放到 540 像素寬）、薄弱的開頭畫面。在 story.json 中修正原因（文案），或將其回報為技能問題；然後：

npx hyperframes render --quality high --output ../year-in-review.mp4

步驟 4：交付

預告海報：鉤子的穩定幀畫面（約 2.9 秒處）將作為縮圖。將其燒錄為第 0 幀，以便每個平台都能顯示（與 /brag 步驟 4 相同的技巧）：

cd <輸出目錄>
ffmpeg -ss 2.9 -i year-in-review.mp4 -frames:v 1 -q:v 2 poster.jpg
ffmpeg -y -i year-in-review.mp4 -i poster.jpg \
  -filter_complex "[0:v][1:v]overlay=0:0:enable='eq(n,0)'[v]" \
  -map "[v]" -map '0:a?' -c:v libx264 -crf 20 -preset slow -pix_fmt yuv420p \
  -c:a aac -b:a 160k -movflags +faststart tmp.mp4 && mv tmp.mp4 year-in-review.mp4

縮圖：結尾畫面（年份日曆、使用者名稱、「<年份>，回顧。」）作為乾淨的靜態圖片，不含投影片計數器、雜湊標籤、底部導航欄或行動呼籲按鈕。將其上傳為 LinkedIn 影片的自訂縮圖（它符合 LinkedIn 預期的影片 4:5 比例），並在需要封面圖片的任何地方使用：

cd <輸出目錄>
npx hyperframes check thumbnail
npx hyperframes snapshot thumbnail --at 0.5 --no-end -o thumbnail/shots
cp thumbnail/shots/frame-00-at-0.5s.png thumbnail.png

關卡： year-in-review.mp4 為 H.264 格式、1080x1350 解析度、小於 50 MB、長度 25-75 秒（建構時上限為 70 秒加上章節卡片）；poster.jpg 存在；thumbnail.png 為 1080x1350 解析度，且你已經親自看過（沒有計數器、沒有導航欄、沒有被裁切的內容）。

寫入 <輸出目錄>/share-copy.txt：以使用者語氣寫成的兩到三句簡明句子，基於最有力的真實事實（原型、一個數字、一個專案）。不要使用一堆主題標籤；最多兩個。範例：「我的 2026 GitHub 年度，至今：30 個新倉庫、連續 44 天活躍、還有一個比我提交還多的機器人。由 github-year-in-review 製作。」

告知使用者影片、縮圖、預告海報與分享文案的位置，並用一句話說明影片的內容。

創意法則

第 0 幀就是貼文。 姓名、年份與頭條數字，穩定呈現。
每個節拍只有一個問題、一個焦點。 一個大數字或一個形狀；其他都是標籤。
身分高於庫存清單。 影片以他們是誰（原型）作結，而不是以總計數。
誠實。 自動化會被指名、私有名稱會被隱藏、部分年度會標示「至今」。
靜音時也可讀。 每個節拍在無聲狀態下仍有意義。
Git，不是 GitHub。 輸入的提示、雜湊標籤、差異區塊與註腳；沒有標誌、沒有 GitHub 綠色或 UI 介面元素。
原創風格。 references/story.md 中定義的帳本風格；不要將其重新設計成 Wrapped 或 Unwrapped 風格。

github-year-in-review