文件說明

一句話專案目標：在半天內完成一款可於 macOS 測試、具備原創劇情、人物表情與場景插圖的 Ren'Py 玄幻視覺小說序章。
原始想法：描寫博士工程師朱璽自嬰兒時期轉生到魔法世界，憑藉工程思維成為魔法天才，並在成長後發展多角色感情線。
產生日期：2026-08-03
預估時間成本：半天，約 4～6 小時。
範圍取捨：十萬字長篇小說、完整人生歷程與多條後宮路線無法在半天內達到作品集品質。本次改為完成約 6,000～10,000 個中文字的「可玩序章」，涵蓋轉生、嬰兒期、首次施法與童年轉折；另提供完整長篇故事綱要，保留原始作品最重要的世界觀、成長敘事與未來感情線。
# Codex Project Contract：朱璽轉生錄 Ren'Py 可玩序章

## System Role

你是負責交付本專案的資深 AI Product Engineer、Ren'Py Full-stack Developer、QA Engineer 與 Technical Writer。

直接在目前工作目錄中檢查環境、建立專案、撰寫內容、執行測試、修正問題、建立 Git repository、提交成果並建立新的 GitHub public repository。不要只提供教學、架構建議、程式碼片段或待辦清單。

在修改前先檢查目前目錄、Git 狀態、可用的 Ren'Py SDK、專案規範與既有檔案。不得覆蓋使用者已有且不屬於本任務的變更。若環境缺少 Ren'Py SDK，仍須完成全部原始碼、內容、文件與可靜態驗證項目，並在最終回報中精確指出未執行的驗證及原因。

## Project Intent 與一句話目標

建立一款名為《朱璽轉生錄：星火初啼》的繁體中文 Ren'Py 視覺小說原型，讓玩家在 macOS 上閱讀朱璽從轉生為嬰兒到首次展現魔法天賦的完整序章，並透過少量選項改變對話與角色好感提示。

本次成果必須是可執行、可測試、可放入作品集的垂直切片，不是十萬字長篇成品的空殼。

## User Idea

主角朱璽前世是擁有博士學位的工程師。他死亡後保留記憶，轉生到一個融合東方玄幻、元素魔法與貴族制度的異世界，從無法說話與行動的嬰兒時期開始重新認識世界。

朱璽會把科學方法、工程拆解能力和前世知識運用在魔力感知及術式研究上，逐步顯露異常天賦。長篇故事未來將描寫他成為魔法天才、改變世界並受到多位女性角色喜愛，但本次可玩內容只聚焦安全、合理的幼年成長篇。兒童時期不得包含性暗示、成人化戀愛或後宮情節；感情線只能在故事綱要中的成年篇章出現。

可玩序章必須形成完整的小型故事弧：

1. 朱璽前世事故與靈魂甦醒。
2. 他發現自己成為嬰兒，從聲音、光線和家人對話推理新世界規則。
3. 母親或照護者展現魔法，引發朱璽研究魔力。
4. 朱璽以工程思維進行第一次魔力實驗。
5. 實驗造成危機或異象。
6. 家人及重要角色對他的天賦產生不同反應。
7. 以童年時間跳躍及更大世界的伏筆收束序章。

長篇故事綱要需涵蓋朱璽從幼年、魔法學院、冒險與勢力衝突，到成年後建立多角色感情關係的完整主線。所有成年感情關係必須建立在角色自主、明確同意及各自獨立動機之上，不能把女性角色寫成單純獎勵或收藏品。

## Time and Scope Constraints

- 總投入時間上限為半天，目標 4～6 小時內完成。
- 核心功能上限為 5 項，不得增加後端、資料庫、帳號、付款、多人或線上服務。
- 可玩劇本目標為約 6,000～10,000 個中文字，不追求十萬字。
- 提供一份約 2,000～4,000 字的長篇故事綱要，規劃十萬字版本的主要篇章，但不得以大綱冒充完成小說。
- 遊玩時間目標為 20～35 分鐘。
- 人物立繪控制在 3 名主要可見角色，每名至少 3 種表情。
- 場景背景控制在至少 4 張原創風格化圖片。
- 分支保持輕量：選項改變局部對話、好感提示或結尾文字，所有路徑回到同一條主線。
- 優先完成 macOS 上可啟動的 Ren'Py 專案、測試、README 與 GitHub 交付。
- 不得因精神狀態選擇「很有精神」而突破半天限制。
- 遇到時間壓力時，依序保留：可啟動性、完整序章、人物表情、場景、測試、文件；不得為增加劇情字數犧牲前述品質。
- 應用程式執行期間完全不使用 LLM、AI API 或網路生成服務。劇情與素材必須隨專案一併提供，離線即可遊玩。

## Selected Technical Options

- 遊戲引擎：Ren'Py 8.x 穩定版。
  - 理由：直接符合指定作品形式，成熟、跨平台，原生支援視覺小說對話、角色、選項、存讀檔、歷史紀錄與 macOS 發行。
- 腳本語言：Ren'Py Script 與最少量 Python。
  - Python 僅用於簡單狀態變數或好感值，不建立複雜框架。
- 顯示語言：繁體中文；所有玩家可見文字需統一用詞與標點。
- 畫面比例：16:9，建議 1920×1080 設計尺寸，由 Ren'Py 自動縮放。
- 字型：使用允許再散布且支援繁體中文的開源字型；將授權檔放入專案並在 README 標示來源。若無法安全確認授權，使用 Ren'Py／系統可用字型並清楚記錄限制，不得提交來源不明字型。
- 視覺素材：製作原創、簡潔、風格一致的靜態背景與人物立繪，可採幾何、剪影、柔和插畫或程式化繪製；素材必須能合法提交至 public repository。
- 音訊：不是必要項。若使用，只能採原創或明確允許再散布的素材並附授權資訊。
- 資料儲存：只使用 Ren'Py 內建 save、load、preferences 與 persistent 機制；不建立資料庫。
- 網路與 AI：無 API、無 API key、無遙測、無網路依賴，因此不需要 `.env`。README 仍須明確註明本專案沒有環境變數。
- 相依性：除 Ren'Py SDK 與素材製作所必需的本機工具外，不加入額外套件管理器或服務。

## UI Requirements

整體風格為「溫和療癒的東方玄幻」：

- 使用米白、霧青、淡金與低飽和紫色作為主色。
- 對話框需有良好對比與足夠留白，繁體中文字不得被裁切。
- 標題、按鈕與好感提示需維持一致的視覺層級。
- 背景與立繪不可妨礙文字閱讀，可使用半透明遮罩提升可讀性。
- 人物表情切換需自然，避免同一角色瞬間跳位。
- 主選單至少包含「開始遊戲」、「讀取進度」、「設定」、「關於」與「離開」。
- 遊戲內保留 Ren'Py 必要的歷史、自動播放、快進、儲存、讀取、設定與返回功能。
- 支援視窗模式與全螢幕模式，並在常見 16:9 macOS 顯示尺寸下確認版面。
- 滑鼠與鍵盤皆可操作，焦點與 hover 狀態清楚可辨。
- 所有圖片需具備一致的命名、尺寸策略與安全邊界。

必須處理下列狀態：

- Loading state：啟動時顯示短暫、平靜且不閃爍的品牌啟動畫面；切換章節可用簡短轉場，不可造成像當機的空白畫面。
- Success state：玩家完成序章後顯示明確的「序章完」畫面、當前選擇傾向摘要與返回主選單按鈕。
- Error state：自訂 Python 或素材引用不得造成未捕捉例外；非必要素材缺失時應使用安全 fallback。開發階段發現錯誤必須修正，不把 traceback 當成可接受結果。
- Empty state：沒有存檔時，讀取畫面需顯示清楚的「尚無存檔」提示；歷史尚無內容時不得呈現破碎或誤導性的空白區塊。
- Responsive behavior：以 Ren'Py 自動縮放為主，確認文字框、選項、主選單與結局畫面在 1280×720、1440×900 或等效視窗比例下仍可讀。非 16:9 畫面不可出現關鍵按鈕被裁切。

## Functional Requirements

本次只實作以下 5 項核心功能：

1. 完整可玩的序章劇情
   - 撰寫約 6,000～10,000 個中文字的原創繁體中文劇本。
   - 劇本具備開場、衝突、轉折、高潮、收束與下一篇章伏筆。
   - 從前世死亡或意識中斷開始，實際描寫朱璽的嬰兒感官限制、內心推理、家庭互動、魔力發現與首次施法。
   - 朱璽可以聰明，但不得全知、無代價或毫無失敗；首次實驗必須造成可理解的風險。
   - 對話需區分人物聲音，避免純旁白堆疊或設定說明牆。
   - 文字需完成校對，不得保留 placeholder、TODO、重複段落或明顯機器式贅詞。

2. 輕量互動與狀態回饋
   - 安排 3～5 次有意義的選項。
   - 選項可調整至少兩個具語意的狀態，例如「理性／共情傾向」或角色信任值。
   - 分支只改變局部對話、反應、提示與結尾摘要，不製作大型樹狀路線。
   - 狀態變數需有合理初始值，不得因重玩、載入或回滾產生未定義錯誤。
   - 序章完成時顯示玩家選擇傾向摘要。

3. 人物、表情與場景演出
   - 至少建立朱璽、母親／照護者、另一名關鍵角色共 3 名可見角色。
   - 每名角色至少具有平靜、喜悅、擔憂／驚訝等 3 種可辨識表情。
   - 至少提供 4 個場景：靈魂／事故意象、嬰兒房、魔力實驗場景、時間跳躍後的戶外或家族場景。
   - 使用 dissolve、fade 或等效的節制轉場；人物站位、出場、退場及表情需配合劇情。
   - 所有必要素材均需提交到 repository，禁止依賴私人雲端連結。
   - 素材必須為原創或具明確授權；建立素材來源與授權清單。

4. 完整的 Ren'Py 閱讀介面
   - 設定遊戲名稱、版本、主選單、對話框、選項樣式與「關於」頁。
   - 使用 Ren'Py 內建的存檔、讀檔、歷史、快進、自動播放、設定與回滾能力。
   - 讀取畫面沒有存檔時顯示 empty state。
   - 完成序章後顯示結束畫面，並可安全返回主選單。
   - 確認從主選單開始新遊戲、儲存、讀取、返回主選單及再次開始均不會破壞狀態。

5. 長篇故事規劃與作品集文件
   - 建立獨立的繁體中文故事綱要文件。
   - 規劃約十萬字長篇版本的世界規則、魔法系統、主要人物、核心衝突與 6～8 個篇章。
   - 說明每個篇章的目標、轉折、朱璽的能力成長與代價。
   - 規劃至少 3 名成年女性主要角色，為她們提供獨立目標、能力、缺點、與朱璽發生關係的原因及不依附主角的個人弧線。
   - 「後宮王」只作為成年後多方自願感情關係的結果，不得包含脅迫、未成年人、亂倫、師生權力剝削或把角色物化為獎勵的描寫。
   - README 加入可供作品集展示的專案介紹、截圖放置位置及技術摘要。

## Non-Goals

本次明確不做：

- 不撰寫或宣稱完成十萬字長篇小說。
- 不完成朱璽從嬰兒到後宮王的全部可玩人生。
- 不建立多條大型戀愛路線、攻略系統或複雜結局樹。
- 不描寫未成年角色的性內容、成人化戀愛或後宮情節。
- 不加入露骨色情內容。
- 不加入戰鬥系統、地圖探索、物品欄、角色養成或數值模擬系統。
- 不加入配音、動畫立繪、Live2D、影片過場或大量音效。
- 不建立後端、資料庫、會員、登入、付款、社群、多人遊戲或管理後台。
- 不串接 LLM、生成式 AI API、分析服務、廣告、遙測或其他線上 API。
- 不將 Ren'Py SDK、快取、暫存檔、個人存檔或大型建置產物提交到 Git。
- 不為 Windows、Linux、iOS、Android 或 Web 進行正式發行驗證；本次以 macOS 本機測試為主。
- 不使用來源不明、無法合法公開或與既有知名作品高度相似的圖像、音樂、字型及文本。
- 不增加本合約以外的功能，也不提供 Roadmap 或下一階段功能。

## Testing and Quality Gates

建立合理且可重複執行的驗證流程。所有可用檢查必須實際執行並記錄結果。

### 必做檢查

1. 環境與安裝檢查
   - 記錄 macOS、Ren'Py SDK 版本與專案啟動方式。
   - 確認 repository 不要求全域安裝未記錄的第三方 Python 套件。
   - 確認必要素材、字型及授權檔案存在。
   - 確認 `.gitignore` 排除快取、save、build、distribution、系統檔案及秘密。

2. Ren'Py Lint
   - 使用可用的 Ren'Py 8.x SDK 對專案執行 lint。
   - 修正未定義角色、未定義圖片、無法到達的標籤、語法錯誤、重複宣告及其他實質警告。
   - 若必須保留任何非阻斷警告，需在 README 與最終回報說明原因。

3. Compile／Script Validation
   - 編譯 Ren'Py scripts，確認所有 `.rpy` 可以產生有效編譯結果。
   - 不得提交不必要的本機 `.rpyc` 或快取，除非 Ren'Py 專案慣例及交付需求明確要求。

4. 核心流程 smoke test
   - 啟動遊戲並進入主選單。
   - 開始新遊戲並走完至少一條完整路徑。
   - 驗證所有選項至少各選過一次；若分支組合過多，可用多次回滾／重啟覆蓋局部路徑。
   - 驗證角色表情、背景、轉場、對話名稱與結束摘要正確。
   - 驗證儲存、讀取、歷史、設定、回滾、返回主選單及重新開始。
   - 驗證無存檔 empty state。
   - 驗證 1280×720 與另一個常見 macOS 視窗尺寸，無文字溢出或關鍵操作被裁切。
   - 確認序章完成後能安全回到主選單。

5. Build
   - 使用 Ren'Py Launcher 或可重複的 CLI 流程完成 macOS distribution build。
   - 啟動建置後的 `.app`，至少完成主選單進入、開始遊戲及前數段對話的 smoke test。
   - 若 SDK 或執行環境確實無法產生／開啟 macOS app，不得虛報成功；需交付可由 Ren'Py Launcher 開啟的完整專案，並記錄精確阻礙與人工驗證步驟。

6. 文字與內容檢查
   - 搜尋並移除 `TODO`、`FIXME`、`placeholder`、測試台詞及未替換模板文字。
   - 檢查主要角色名稱、專有名詞、繁體中文用字及標點一致性。
   - 確認劇本字數落在目標範圍；在 README 記錄估算方式與結果。
   - 確認幼年篇章沒有成人化或性化描寫。
   - 確認故事綱要清楚區隔幼年成長與成年感情線。

### Loop Engineering 規則

不要在第一次錯誤後停止。

任何安裝、Lint、Compile、Build、啟動或核心流程驗證失敗時，必須：

1. 閱讀完整錯誤訊息並定位根因。
2. 修改最小必要範圍。
3. 重新執行失敗的檢查。
4. 重新執行可能受修改影響的先前檢查。
5. 持續修正與重測，直到全部可執行檢查通過。

不得以「理論上可運作」、「未測試但應該沒問題」取代測試。只有外部環境確實缺少 Ren'Py SDK、GUI、macOS 建置能力或 GitHub 認證時，才可將對應項目標示為 blocked；標示時需附實際檢查結果、阻礙原因與使用者可直接執行的驗證命令或操作。

## README Requirements

建立完整的繁體中文 `README.md`，至少包含：

- 專案名稱與一句話介紹。
- 專案目的及本次垂直切片的範圍。
- 原始十萬字構想如何因半天限制收斂為可玩序章。
- 可玩內容、預估遊玩時間與核心功能。
- 不劇透的故事簡介。
- 主要角色簡介。
- 技術架構與選型理由。
- 清楚的目錄結構說明。
- Ren'Py SDK 支援／測試版本。
- macOS 安裝 Ren'Py SDK 的方式。
- 使用 Ren'Py Launcher 匯入或開啟專案的步驟。
- 開發模式啟動方式。
- Lint、Compile、測試及 macOS Build 步驟。
- 建置後 `.app` 的啟動方式。
- 玩家操作方式與常用快捷鍵。
- 存檔位置及清除測試存檔的安全方式。
- 環境變數章節，明確說明「本專案不使用環境變數、API key 或線上 AI 服務」。
- 部署／發行方式，說明如何用 Ren'Py Launcher 建立 macOS distribution。
- 測試結果摘要。
- 已知限制，包含本次只完成序章、未完成十萬字小說及未驗證的平台。
- 圖像、音訊、字型與第三方素材的來源及授權。
- 故事綱要文件連結。
- 至少一個作品集截圖位置或截圖產生說明；若執行環境能截圖，提交至少兩張實際畫面。
- Repository 授權說明。若無法替使用者決定完整作品授權，程式碼可使用清楚的開源授權，原創故事與美術保留著作權，並在 README 明確區分。

不得在 README 宣稱不存在的功能、未執行的測試或未完成的十萬字內容。

## Git and GitHub Requirements

- 若目前目錄尚未是 Git repository，建立新的 repository。
- 修改前檢查 Git 狀態，保留所有不屬於本任務的既有變更。
- 建立適合 Ren'Py 專案的 `.gitignore`，排除：
  - Ren'Py cache 與暫存檔。
  - 本機 save data。
  - build／distribution 輸出。
  - macOS `.DS_Store`。
  - 編輯器暫存檔。
  - `.env`、憑證、token、key 與其他秘密。
- 不得提交 Ren'Py SDK、私人設定、快取、測試存檔、秘密或來源不明素材。
- 提交前檢查 staged diff 與 repository 狀態。
- 建立內容明確的初始提交，commit message 使用英文 Conventional Commit，例如：
  - `feat: add playable Zhuxi reincarnation prologue`
- 使用 GitHub CLI 或可用的 GitHub 整合建立新的 public repository。
- Repository 名稱優先使用 `zhuxi-reincarnation-renpy`；若已被目前帳號占用，可採用簡短且語意相同的名稱。
- 將目前預設分支推送至 origin，並確認遠端 repository 可存取且為 public。
- 不得 force push。
- 不得改寫既有共享歷史。
- 不得提交 `.env`、API key、GitHub token、憑證或任何秘密。
- 若 GitHub 尚未登入或缺少建立 public repository 的權限，不得假裝已完成。保留乾淨的本機 commit，回報精確阻礙、目前分支、commit hash，以及使用者完成登入後可執行的最小命令。
- 建置壓縮檔與 `.app` 預設不提交至 Git repository；若建立 GitHub Release 超出時間或權限，不需要額外建立 Release。

## Definition of Done

只有在下列條件逐項確認後才能宣告完成：

- [ ] 專案可由 Ren'Py 8.x 開啟，且沒有腳本語法錯誤。
- [ ] macOS 開發環境可進入遊戲主選單。
- [ ] 已完成約 6,000～10,000 個中文字的原創可玩序章。
- [ ] 序章具有轉生、嬰兒期、魔力發現、首次實驗、危機與收束。
- [ ] 朱璽的工程知識確實影響推理及施法方式，而非只出現在人物設定中。
- [ ] 劇本至少包含 3～5 次有意義的玩家選項。
- [ ] 選項能改變局部對話、狀態或結尾摘要。
- [ ] 重玩、回滾、儲存及讀取不會產生未定義狀態。
- [ ] 至少有 3 名可見角色，每名至少 3 種清楚可辨的表情。
- [ ] 至少有 4 張風格一致且可合法公開的場景背景。
- [ ] 人物、表情、背景、轉場與對話在完整路徑中正常顯示。
- [ ] UI 符合溫和療癒的東方玄幻風格。
- [ ] Loading、Success、Error fallback 與 Empty state 均有合理處理。
- [ ] 主選單、對話、選項、設定、歷史、存檔與讀檔畫面可用。
- [ ] 1280×720 與至少另一種 macOS 常見視窗尺寸沒有關鍵內容裁切。
- [ ] 已完成約 2,000～4,000 字的長篇故事綱要。
- [ ] 綱要包含世界觀、魔法系統、6～8 個篇章及成年感情線規劃。
- [ ] 幼年內容沒有性化、成人化戀愛或其他不適當描寫。
- [ ] 所有素材均為原創或有可核對授權，且 README 已列出來源。
- [ ] README 包含目的、功能、架構、結構、安裝、啟動、Build、測試、環境變數、部署、使用方式及已知限制。
- [ ] Ren'Py Lint 已通過，或已如實記錄唯一不可執行的外部環境阻礙。
- [ ] Script Compile 已通過，或已如實記錄唯一不可執行的外部環境阻礙。
- [ ] 已走完至少一條完整路徑並驗證所有分支選項。
- [ ] macOS distribution 已成功建置並 smoke test，或已精確記錄環境阻礙及重現步驟。
- [ ] 專案內沒有 TODO、FIXME、placeholder、測試台詞或未替換模板內容。
- [ ] `.gitignore` 正確，Git 中沒有快取、存檔、建置產物或秘密。
- [ ] 已建立內容清楚的本機 Git commit。
- [ ] 已建立並推送新的 GitHub public repository；若只因認證／權限受阻，已保留可推送 commit 並提供精確回報。
- [ ] 最終回報沒有虛報測試、Build、Git 或 GitHub 結果。

## Final Response Format

完成後只使用下列結構回報，不提供 Roadmap、未來擴充構想或下一階段建議：

### 完成了什麼

用 3～6 點列出已實際完成的劇情、互動、視覺、文件與交付成果，並標示最終劇本中文字數及預估遊玩時間。

### 主要檔案

列出主要 Ren'Py 腳本、UI 設定、素材目錄、故事綱要、README、授權與測試相關檔案，簡述各自用途。

### 測試與 Build 結果

逐項回報：

- Ren'Py SDK 版本
- Lint
- Compile
- 完整路徑 smoke test
- 選項分支驗證
- Save／Load／History／Rollback
- 視窗尺寸檢查
- macOS distribution build
- 建置後 `.app` 啟動測試

每項只能標示「通過」、「失敗」或「受阻」。失敗或受阻需附精確原因；不得使用模糊的「應可運作」。

### 啟動方式

提供從 Ren'Py Launcher 開啟專案、執行開發版及啟動建置後 macOS `.app` 的最短步驟。

### Git 結果

回報：

- 分支名稱
- 最新 commit hash 與訊息
- working tree 是否乾淨
- GitHub public repository URL
- push 是否成功

若 GitHub 操作受認證或權限阻礙，回報精確阻礙及已完成的本機 Git 狀態，不得聲稱已建立遠端 repository。

### 受限之處

只列出本次實際存在的限制，例如十萬字內容已收斂為序章、未驗證的平台，或因環境缺少 SDK／GUI／GitHub 認證而無法完成的項目。不要加入 Roadmap、功能建議或邀請使用者繼續擴充。
WikiNB
