TheCreepero/event-pack-create

事件包：建立包或新增事件

規劃一個包或新事件，詳細到每一個文本、效果與圖片，全部放在一個計畫檔案中，由 event-pack-implement 執行。在 Phase 4 之前，請先閱讀 docs/source-format.md 和 docs/style-guide.md。

規則

• 每個事實都必須在其頁面上驗證。 事實只有從 Phase 3a 的 KEEP 或 FIX 結果中，附帶來源和引文，才能進入事實表；任何未經檢查頁面陳述的細節，無論看起來多麼合理，都不能寫入文本。
• 授權由工具決定。 圖片只有在 build.ps1 -FetchPicture ... -DryRun 印出 ACCEPTED 之後，才能進入計畫。
• 編輯必須通過每一段文本。 任何事件若未經編輯在最新一輪回覆為 KEEP，其計畫就不能設為 READY。
• 此處不碰觸已發布的包。 此技能只撰寫計畫、research/<key>/ 下的檔案，以及 scratch/ 下的檔案；source/ 和 packs/ 的變更則在計畫執行時發生。唯一的例外是全新包的 -NewPack（Phase 0）；該包的縮圖將在執行時製作（Phase 3，步驟 5）。
• 保留研究資料夾。 所有研究資料夾都保留在 research/<key>/ 中，絕不刪除或截斷，即使計畫被放棄也是如此：未選中的候選事件與未使用的事實，正是日後擴展包的起點。唯一的新增內容是 Phase 5.4 的 Used: 和 Checked: 行。這些內容將在計畫發布時，或應擁有者要求時，隨計畫一起提交。
• 僅在 Phase 0 和 Phase 2 向擁有者提問。

Phase 0：範疇

1. 在單一訊息中詢問擁有者：國家（及其標籤，若不明確）、時期（預設：1936 年至其戰爭開始，加上前幾個月）、事件數量（預設 10 到 15 個）、需強調或避免的種類，以及包不得觸及的任何內容。將答案記錄在計畫的「Decisions」中。
2. 新包：使用 hoi4-vanilla-lookup 技能（Get-HoiCountry）確認標籤，然後執行 powershell -File .\build.ps1 -NewPack -Pack <key> -Tag <TAG> -DisplayName "<Country>"；它會使用 Modding Manager 的 New-HoiThumbnail.ps1 在該家族的預設載入畫面上渲染出第一個縮圖（若無法執行，則複製 assets/thumbnail_master.png 並印出命令），此縮圖將在 Phase 3 被取代。撰寫 source/<key>/workshop-intro.bbcode：兩到三句關於該包的簡潔句子，以及由 -NewPack 草擬的資訊行。
3. 複製 docs/plans/TEMPLATE-pack.md 到 docs/plans/<YYYY-MM-DD>-<key>-<what>.md，並填寫標頭、「Context」和「Decisions」。若為現有包：記下其最後一個事件的 ID；新事件的 ID 從該 ID 之後接續。

Phase 1：研究

1. 如果 research/<key>/ 存在，請閱讀其研究資料夾。其中沒有 Used: 標記且符合時期與種類的候選事件，也是此計畫的候選；記下它們的鍵值。帶有 Checked: 行的候選事件，表示已在其他頁面上檢查過；請根據其最新 Checked: 行所指名的位置來判斷，而非根據其下所寫的事實。該處的事實表包含所有已檢查的事實。計畫的「Fact verification」僅包含修正與放棄，因此研究資料夾中未提及的事實皆為保持不變。即使被選中，它仍需要經過 Phase 3a。
2. 所需的候選事件：大約是所需事件數的 1.5 倍，減去可用的先前候選事件。將它們分成最多 12 個一組，每組涵蓋其自己的時期區段（例如 30 個事件：1936、1937-1938、1939-1940），並分配一個 ep-historical-researcher 給每組，所有組別平行執行。每個研究員都需要：國家、標籤、其時期區段、其候選事件數量、Phase 0 的種類、該包現有事件的標題、每個早期研究資料夾的候選事件（附鍵值、日期和一列摘要），以及其自己的路徑 research/<key>/<YYYY-MM-DD>-dossier.md（若當天已有檔案，則加上 -2 等後綴）。等待所有摘要完成。

Phase 2：選擇

閱讀新的研究資料夾。刪除關鍵事實為 UNVERIFIED、無法用引述事實填滿 40 個單詞、或與另一組候選事件重複的候選事件。將其餘的候選事件（可用的早期候選事件標記為「可用」）以簡短列表形式呈現給擁有者（鍵值、日期、種類、閘門：日期區間或遊戲狀態、一行摘要），附上您建議保留哪些以及原因，然後讓擁有者選擇。

Phase 3：圖片

1. 分配 ep-picture-researcher 給選中的事件：提供鍵值、日期、地點以及研究資料夾的圖片點子。
2. 對每個事件，在其第一個提案上執行 powershell -File .\build.ps1 -FetchPicture -Pack <key> -File "<File:...>" -Key <picture key> -DryRun；若收到 REJECTED，則嘗試下一個。沒有接受檔案的事件將使用原版圖片（vanilla:GFX_report_event_<name>，可透過 hoi4-vanilla-lookup 技能的 Find-HoiUsage 找到），並在計畫中加註。
3. 依圖片選擇裁切與色調：黑白照片使用 warm（與遊戲自身圖片匹配），彩色藝術作品使用 none；除非研究員的裁切註記要求，否則裁切比例保持為 50。
4. 將乾執行印出的結果填入計畫的「Pictures」表格中。
5. 縮圖，適用於新包或 assets/thumbnail.json 中沒有 packs.<key>.background 的包：背景應是該包自己的事件圖片之一，而非原版載入畫面。Modding Manager 的 New-HoiThumbnail.ps1 會以其固定的事件包版面（遊戲邊框、「EVENT PACK」和國家名稱在底部標題板、包的標籤旗幟在右上角）繪製其餘部分，因此只需選擇圖片及其裁切方式。選擇一張已印出 ACCEPTED 的圖片，優先選擇 PD 或 CC0 授權；CC BY 也可接受，因為產生的 Workshop 描述會註明每個事件使用的圖片。觀察圖片及其主題所在的位置：標題板大約覆蓋正方形底部三分之一，旗幟在右上角，因此優先選擇主題可以位於中上方的圖片。橫向圖片會填滿正方形的整個高度，因此裁切（"center"、"left"、"right"）只在橫向移動；直向圖片則填滿其寬度，"top" 或 "bottom" 可使主題保持在內；[x, y] 中心比例則可置於其間。寫下 Thumbnail: <picture key>, crop <crop> 並在「Implementation steps」的步驟 4 中填入圖片鍵值、裁切（JSON 格式）以及 Modding Manager 的絕對路徑作為 <Manager root>（此儲存庫上兩層的資料夾）。其命令使用 -Path .，因此 Phase 5 的演練只會寫入和修改其副本。乾執行不會下載任何東西，因此縮圖將在執行時、步驟 3 之後，從 -FetchPicture 儲存在 sources-cache/<key>/ 中的副本（Commons 渲染，最寬 1600 px）製作，而非從 210x176 DDS 檔案。已有自己縮圖的包：寫下 Thumbnail: unchanged 並讓步驟 4 的內容變為 Thumbnail unchanged: nothing to run.，以保持步驟編號不變。

Phase 3a：驗證

在擁有者選擇後執行，並可與 Phase 3 同時進行；研究員的引文僅是線索，尚未經過檢查。

1. 分配 ep-audit-researcher 給選中的事件，每個代理最多處理五個事件，所有代理平行執行。將每個事件的研究資料夾區段完整貼上；不傳送圖片。
2. 只有 KEEP 和 FIX 的事實會繼續使用，每個事實都附帶檢查員回傳的來源和引文。驗證細節少於 40 個單詞的事件將返回 Phase 2 進行更換，更換後的事件也必須通過 Phase 3a。
3. 填寫計畫的「Fact verification」：代理以及每個代理負責的事件；每個已檢查的事件（包括被更換的）、KEEP、FIX 和 DROP 的計數，每個已修正的事實及其更正，以及每個被放棄的事實；被更換的事件。

Phase 4：撰寫

1. 僅根據 Phase 3a 的結果，為計畫的 markdown fact-sheets 區塊撰寫每個選中事件的章節：每個事實行都必須是 - <事實>. Source: <URL> (<頁面標題>). Quote: «<該頁面的一行>»。絕不直接複製研究資料夾中的事實。
2. 將事件寫入 json events 區塊：對於現有包，從目前的 source/<key>/events.json 開始並在其中新增。遵循 docs/source-format.md 設定每個欄位，並遵循 docs/style-guide.md 撰寫每個文本。效果要小且與其選項匹配；只有當事件值得一個時效性理念時才添加。編輯會根據以下三個規則審核您：
   • 不得透過拼接兩個事實來做出聲明，除非其中一個引文明確陳述了該拼接的聲明。
   • 頭銜與角色應使用事件發生當時的名稱，而非後來才有的稱謂。
   • 文本在 fire 視窗內的每一天都必須保持真實：文本中稱之為「近期」或「即將到來」的事件，在視窗內的其他日子可能尚未發生或已經結束。
   • 關於戰爭或戰爭準備的事件，應以 fire.trigger 中的遊戲狀態為閘門（參見 AGENTS.md），而非以日期為閘門；其文本不得提及戰爭開始或準備工作的歷史日期。和平時期的事件在國家參戰後應被封鎖。在將觸發條件放入計畫之前，請使用 Find-HoiDoc 查詢其作用域，並使用 Get-HoiState、Get-HoiCountryHistory、Find-HoiUsage 查詢其在視窗開始時所指涉的每個標籤、省分和旗幟：一個語法正確的觸發條件，在正常遊戲中仍可能永遠不會成真（例如一個起始不存在的國家，或一個由其他國家擁有的省分）。計畫中承諾稍後進行的查詢，必須在計畫設為 READY 之前完成。
3. 在編輯看到任何觸發條件之前，先加以驗證。分配 trigger-checker 代理（Modding Manager 的 Agents/trigger-checker.md，已安裝於使用者層級；Antigravity 會將該檔案傳遞給 invoke_subagent），並提供計畫路徑、事件鍵值和包的標籤。它會將每個 fire.trigger 對照事件 fire.after 時的遊戲檔案進行解析，並針對每個事件回答：觸發條件在視窗內是否可能為真、維持每週檢查多久、文本在觸發條件允許的情況下是否為假、以及視窗是否與文本的日期相符。按照給定的方式套用每個 FIX，將修改後的事件再次透過檢查器執行，並將每個事件的判定結果記錄在計畫的「Trigger verification」中：OK、包含取代舊觸發條件的 FIX、或 OPEN（附帶探查結果或擁有者的決定）。任何在沒有探查結果或擁有者決定的情況下標記為 OPEN 的事件，其計畫都不能設為 READY。編輯建議的條件是此步驟的線索，而非觸發條件。
4. 分配 ep-editor，並提供計畫路徑（其 markdown fact-sheets 區塊即為事實表）和事件鍵值。按照給定的方式套用每個 REWRITE；放棄或更換 REJECT（返回 Phase 2 進行更換）。將每一輪記錄在「Editor record」中。將修改後的事件送回編輯，直到每個事件都標記為 KEEP；最多三輪，之後請詢問擁有者。
5. 判斷包的 Workshop 簡介 source/<key>/workshop-intro.bbcode：在 Test-WorkshopText.ps1 -Mod "Event Packs" -Pack <key> 通過後，以 Mod 模式分配 workshop-editor（Modding Manager 的 docs/workshop-text-style.md（..\..\docs\workshop-text-style.md），章節「Auditing a page」），並提供 Mod 資料夾（儲存庫根目錄）和該檔案。簡介只能說明該包 events.json 和 pictures.json 中顯示的內容（事件數量、哪些事件包含時期圖片、效果是什麼），並使用其他包簡介中對於相同事實的措辭。按照給定的方式套用每個 REWRITE，執行 -Generate、Sync-WorkshopRegions.ps1 和機械檢查，然後將簡介送回編輯，直到標記為 KEEP；最多三輪，之後請詢問擁有者。將各輪記錄在「Editor record」中。

Phase 5：閘門

1. 在不觸碰儲存庫的情況下演練計畫：robocopy . scratch\rehearsal /MIR /XD .git scratch artifacts sources-cache，然後在 scratch\rehearsal 中完全按照計畫所述執行步驟 1 到 8（它們只會寫入副本）。每個步驟都必須產生它所說的預期結果；修正計畫，而不是副本，然後再次演練。步驟 4 會編輯副本的 assets\thumbnail.json；使用 Read 工具開啟它所命名的預覽，並在標題板或旗幟遮住主題時選擇另一張圖片或裁切方式。步驟 8 會將每個事件繪製為遊戲視窗（scratch\rehearsal\artifacts\workshop-images\<key>/）：使用 Read 工具開啟圖像，並縮短渲染時印出 [WARN] 的標題或選項：表示它溢出了其方塊，進入下方的文本 [GUW-027]。
2. 填寫「Events」，在「Kept on judgment」列表中列出演練中 -Check -Pack <key> 或 -RenderEvents -Pack <key> 印出的任何保留的 [WARN]，並設定 Status: READY。
3. 刪除副本：Remove-Item -Recurse -Force scratch\rehearsal。
4. 在研究資料夾中，針對該候選事件鍵值的每個章節（研究資料夾和附錄）：
   • READY 計畫中的每個事件，在其 ## <key> 標題下方新增一行 Used: <計畫檔案名稱>。
   • 每個經 Phase 3a 檢查的候選事件（包括被更換的），則在該行下方（如果沒有 Used: 行，則在標題下方；如果已有 Checked: 行，則在該行下方）新增一行：Checked: <計畫檔案名稱>, <K> kept, <F> fixed, <D> dropped. 以下事實為研究員的筆記，非經檢查之事實：請參見 <位置>。。其計數取自「Fact verification」中該事件自己的數據。<位置> 對於計畫中的事件是 source/<key>/fact-sheets.md，對於被更換的事件則是 the plan's "Fact verification"。
   • 不要更改研究資料夾中的任何其他內容。從未經過檢查的候選事件保持不標記，即研究員撰寫時的狀態。

Phase 6：交接

向擁有者回報：計畫路徑、研究資料夾路徑（附帶它們為日後保留了多少候選事件）、事件及其標題、圖片授權（PD、CC0、CC BY 各有多少）、縮圖的圖片與裁切、事實驗證總計、編輯總計，以及 event-pack-implement 將執行此計畫。然後停止。

Antigravity：將每個代理的簡報路徑傳遞給 invoke_subagent；如果無法分派子代理，請自行閱讀簡報並完成工作，並在一個單獨的階段中處理編輯的工作，該階段只能讀取草稿、事實表和樣式指南。