master-of-orion2-remake-cht

Imported from wicanr2/master-of-orion2-remake-cht (AGENTS.md). Install upstream with npx skills add wicanr2/master-of-orion2-remake-cht. Copyright stays with the author.

Codex 工作規範：銀河霸主 II go/ebiten remake

本檔是本儲存庫的代理人工作規範。它承接 CLAUDE.md 的長期原則，但不複製 WORKLIST.md 的剩餘工作或任何百分比快照；現況一律以程式碼、測試輸出、Git 紀錄與 WORKLIST.md 頂端的活表為準。

接手順序

開始任何工作前，依序讀取：

1. CLAUDE.md
2. CONTEXT.md
3. docs/HONEST-STATUS.md
4. WORKLIST.md 頂端的「剩餘工作」表

若要追查逆向證據，只讀 docs/re/01-gap-report.md 開頭的「煉出來的規則」，再 依需要查對應編號；它是硬資料與工程日誌，不是現況清單。

語言與文件

• 面向使用者、提交文件與程式碼註解預設使用繁體中文。
• 程式識別字、命令、檔名、API 與產品名稱保留原文；必要英文技術名詞先寫中文，再於括號補英文。
• 不在文件複製會過期的「剩餘 N 項」、完成百分比或狀態摘要。
• 做完一項工作，立即更新它唯一所在的活表；刪除已被程式碼推翻的舊斷言，不保留刪節線或訂正殘影。
• 重大規則、數值與逆向結論必須標示證據等級：已證實、強推論、假說或未知。
• 玩家可見文案不得硬編在 Go 程式；以穩定鍵值從 assets/i18n/*.json 載入。程式內只保留識別字、除錯訊息與非玩家可見測試文字。

Docker-only 執行邊界

• 分析、搜尋大量資料、轉檔、建置、測試、抓圖、執行程式、DOSBox、Wine、Xvfb、SDL、音訊與 GUI 自動化，一律在一次性 Docker 容器內執行。
• 預設使用 docker run --rm --network none，設定相稱的 --memory、--cpus、--pids-limit，並以目前使用者 UID/GID 執行可寫容器。
• 原始遊戲檔、私有反組譯資料與正版字型只讀掛載；不得把有版權資產或私有研究資料加入 Git。
• 優先使用既有工具鏈映像：moo2-ebiten（CGO/X11/Xvfb）與 golang:1.25-bookworm（純 Go）。不要因一次啟動失敗就建立重複映像。
• 一輪 Docker 工作後檢查專案相關容器；停止並移除不再需要的容器，不留下背景 Xvfb 或長時間程序。
• 主機控制面只做必要的 Docker、Git、工作樹狀態檢查與檔案編輯；不要在主機直接跑專案程式或測試。

Remake 與逆向原則

• 目前採 RE-first gate：先補齊 docs/re/parity-matrix.tsv 中所有玩家可見玩法列的 反組譯證據，再討論規格與實作。閘門關閉前，新發現只更新證據、未知邊界與 remake 差異； 不撰寫新的玩法規格，也不修改 Go／Ebitengine 玩法行為。RE 知識庫閉合後，仍須由使用者 明確確認才恢復「RE → READY spec → 實作」流程。
• 原版執行檔是行為 oracle；只用來建立行為與格式證據，不抄寫反編譯器控制流，也不散布原版資料。
• 來源優先序：原版執行檔立即數／交叉參照 > 官方手冊與 patch 資料 > openorion2 原始碼 > LBX 尺寸交叉驗證 > 量圖或猜測。
• 純規則、資料解析、UI 與儲存分層；把原版特定規則留在 internal/gamedata 或 internal/shell，不要過早抽成泛用引擎。
• 先做一個垂直切片：真實資料 → 型別解析 → 規則 → UI → 存檔往返；再批量擴充。
• 未知欄位保留原始位元組與定位資訊，不以推測性欄位名取代證據。
• 反組譯註記不可覆蓋原始函式名、位址、偏移、運算元或交叉參照；匯出時同列顯示原始定位、語意、證據等級與出處。
• 每項「已證實」結論都要能回查到檔名、雜湊、工具版本、位址基準、位元組範圍、手冊頁碼、原版截圖或可重現實驗。
• 編譯器生成 helper、C runtime／標準函式庫與 Windows API／平台內部函式不屬於玩法 RE 或 remake 範圍，例如 stack probe、stack overflow check、SEH、fopen、fclose、fork 及一般檔案／程序／記憶體包裝函式。只建立足以辨識並跨過的 pattern；若呼叫前後會改變 玩家可見結果，才保存最小輸入、輸出、錯誤與時序契約，不追函式內部，也不納入完成分母。

銀河霸主 II 專案不變規則

• 邏輯畫布固定 640×480；uiScale 只改內部輸出倍率，不用螢幕尺寸重算版面與熱區。
• overlayScreen 的中文化採擦底疊字；英文模式應讓原版烘字露出。新增面板必須經 fillPanel 或 drawPanelImage 形成 z 序屏障。
• 戰鬥必須分開檢查兩條路徑：快速結算（battleVolley／ResolveBattle）與格子戰術（tacticalScreen／CombatShip）。任何武器、護盾、艦艇元件或狀態效果都要問兩條是否都接線。
• 「元件表有」不等於「效果有接」；盤點元件時同時找消費端、呼叫端與兩條戰鬥路徑。
• 單元測試綠只證明 remake 內部自洽，不代表與原版對齊。原版核對先窮盡靜態來源；靜態資料不足才規劃 DOSBox 實測，不用 archive.org 線上版逐畫面替代 oracle。
• docs/screenshots/ 的畫廊是逐位元驗收資料；30_netwait.png 的 StateFingerprint 改變時必須查明持久化狀態原因。
• 不自評單一還原度百分比。依 2026-08-25 使用者決策，README 可列有日期、公開分母與權重的 remake 功能、原版玩法對齊、發行驗證三項儀表板；三者不得合成總分。仍須把「功能已實作」 「手冊／反組譯已錨定」「未經原版實測」「刻意簡化」分開書寫。
• Windows API／Win95 平台內部行為不是玩法 RE 目標；只確認玩家可見契約，平台內部以明示的 現代近似完成，避免把作業系統考古重新列成 remake 缺口。

驗證與交接

按風險由低至高使用：純規則測試、真實資料解析測試、存檔往返／突變差異、headless 畫廊、原版實驗、正常玩家路徑、打包 smoke test。

每次停止前：

• 記錄精確 HEAD、工作樹狀態與 Docker 清理狀態。
• 分開列出已驗證事實、強推論、未知與外部 oracle 依賴。
• 記錄實際執行的命令與通過／失敗輸出。
• 移除與現況矛盾的舊待辦；深層證據連結到原始文件，不在交接檔複製全文。
• 下一步只能寫成最小、可重現的行動，並區分實作、逆向、動態 oracle、視覺、打包與可選現代化。

常用 Docker 入口

scripts/build.sh
scripts/test.sh ./internal/shell/
scripts/test-ebiten.sh ./cmd/moo2/
scripts/screenshot.sh <遊戲資料目錄> out.png -- -lbx fleet.lbx -asset 0

遊戲資料、字型與私有反組譯工作區只可由本機唯讀掛載到容器；不要在 repo 內提交這些輸入。