廢土傳承 — 開發日誌

記錄專案的文件建立與更新歷程。最新的在最上面。

2026-03-08 — USB 遊戲手把支援（Gamepad-to-Keyboard Bridge）

概述

新增 USB 遊戲手把完整支援。採用「Gamepad-to-Keyboard Bridge」架構——手把輸入透過 Gamepad API polling 轉換為合成 KeyboardEvent，dispatch 到 DOM。所有現有鍵盤 handler 自動接收，不需修改任何元件的鍵盤處理邏輯。

新增檔案（3 個）

檔案	說明
`engine/gamepadMapping.ts`	按鈕映射表：Standard（W3C）+ Non-Standard（DirectInput）雙模式
`engine/gamepadPoller.ts`	輪詢引擎：RAF 迴圈、邊緣偵測、長按重複、搖桿死區、連線通知
`hooks/useGamepad.ts`	React hook：管理 GamepadPoller 生命週期，回傳 `{ connected }`

修改檔案（5 個）

檔案	變更
`App.tsx`	啟用 `useGamepad` hook，`gamepadConnected` prop 傳遞
`GameScreen.tsx`	接收 `gamepadConnected` 轉發給 KeyHintBar；新增畫面切換自動 focus
`KeyHintBar.tsx`	手把模式切換：`gamepadConnected` 時顯示手把按鈕提示，隱藏數字快選
`TitleScreen.tsx`	底部提示區手把/鍵盤模式切換
`CharacterCreation.tsx`	修正 focus 復原 + 天選之人問答雙重 listener 衝突

按鈕映射表

手把按鈕	Standard 索引	Non-Standard 索引	模擬鍵	遊戲操作
A（南/×）	0	1	Enter	確認
B（東/○）	1	2	Escape	取消
X（西/□）	2	—	Escape	取消（相容）
Y（北/△）	3	0	Tab	區域切換
L1	4	4	ArrowLeft	上一頁
R1	5	5	ArrowRight	下一頁
D-pad ↑↓←→	12-15	軸 0/1	Arrow Keys	方向導航
左搖桿	axis 0/1	axis 0/1	Arrow Keys	方向導航

除錯紀錄（6 個問題）

問題	原因	修正
A/B 按鈕按下無反應	合成 `KeyboardEvent`（`isTrusted:false`）不觸發 `<button>` 原生 click	`dispatchKey()` 偵測 Enter + `<button>`/`<a>` 時補發 `target.click()`
使用者手把 A=1 B=2（非標準索引）	DirectInput 手把按鈕編號偏移	建立 `BUTTON_MAP_STANDARD` / `BUTTON_MAP_NONSTANDARD` 雙映射表 + 自動偵測
手把報告 `mapping:'standard'` 但 B=2 未映射	手把錯報類型	在 STANDARD 映射表加入按鈕 2→Escape
HMR 後所有按鈕變「未映射」	`onBrowserConnect` 事件搶先設 `_connected=true`，poll 迴圈跳過映射表設定	瀏覽器事件不修改 `_connected`，poll 迴圈為唯一管理者 + 安全網
畫面切換後手把無反應	容器級 `onKeyDown` handler 需焦點在內部才觸發	`CharacterCreation` 加 focus 復原、`GameScreen` 加 `stage.id` 變化時自動 focus
D-pad 上下跳格（天選之人問答）	`CharacterCreation` 與 `ChosenOneQuiz` 各有 `document` 級 keydown listener，同時處理方向鍵導致雙重移動	`CharacterCreation` 在 `step === 2` 時跳過方向鍵處理

技術要點

D-pad 按鈕/軸互斥：許多手把的 D-pad 同時報告 buttons[12-15] 和 axes[0-1]，在 processAxis() 加入互斥邏輯防止雙重觸發
長按重複：方向鍵首次延遲 400ms，之後每 180ms 重複觸發
搖桿死區：axis 值超過 ±0.4 才觸發
未映射按鈕掃描：自動 log 未映射按鈕的按壓事件，輔助診斷非標準手把

commit

d4e8916 — 新增 USB 遊戲手把支援（Gamepad-to-Keyboard Bridge）

規模

8 個檔案變更（3 新增 + 5 修改）

2026-03-06 — AI 停機兩天後復工：語意搜尋大升級 + MCP Server

事故紀錄：開發資源額度耗盡

3/4 晚間 Claude Code 額度耗盡，AI 輔助開發全面停擺。原因是前幾天密集開發（技能系統、部署面板、遊戲指南、封測準備）連續消耗大量 token，觸發用量上限。停機持續約兩天（3/4–3/6），期間無法使用 AI 進行任何開發工作。

教訓：vibe coding 的致命弱點 — 開發節奏完全綁定 AI 額度。額度一斷，等於整個工作室停電。

語意搜尋工具大升級（commit: 719a29b）

復工後首要任務：將語意搜尋工具從 CLI-only 升級為 Claude Code 原生工具。

新增模組

檔案	說明
`queryParser.ts`	查詢理解：規則式解析自然語言，提取情境/類型/季節/稀有度過濾條件
`consistencyChecker.ts`	一致性檢查：比對新事件與既有事件的效果值域、找出潛在衝突
`terminologyChecker.ts`	名詞檢查：比對遊戲專有名詞表，偵測未登錄名詞與不一致用法
`mcpServer.ts`	MCP Server：stdio transport，包裝三個工具供 Claude Code 原生呼叫

重構

searcher.ts：匯出 loadIndex()、performSearch()，CLI 向下相容
consistencyChecker.ts：匯出 performConsistencyCheck()，CLI 向下相容
使用 isDirectRun 模式：偵測直接執行 vs 被 import，同一檔案兼容 CLI 和 MCP

MCP Server 三工具

工具	功能
`search_game_content`	自然語言搜尋遊戲內容（hybrid: BM25 + 向量語意）
`check_content_consistency`	檢查事件檔案的效果一致性 + 名詞規範
`rebuild_search_index`	重建向量索引

MCP Server 啟動時預載索引 + 嵌入模型 + 名詞表，後續查詢 <1 秒。

技術文件

新增 遊戲企劃/技術筆記/語意搜尋工具演進紀錄.md，記錄工具現況與 MCP 整合分析。

API 封測 campaign 功能（commit: 30dabdd）

api/src/routes/campaign.ts 新增封測邀請信批次寄送端點。

Admin 面板（commit: ef20bb3）

新增 admin/index.html，封測管理用簡易面板。

修改檔案一覽

檔案	變更
`tools/semantic-search/src/queryParser.ts`	🔵 新建
`tools/semantic-search/src/consistencyChecker.ts`	🔵 新建
`tools/semantic-search/src/terminologyChecker.ts`	🔵 新建
`tools/semantic-search/src/mcpServer.ts`	🔵 新建
`tools/semantic-search/src/searcher.ts`	🟡 重構匯出
`tools/semantic-search/src/indexer.ts`	🟡 欄位擴充
`tools/semantic-search/src/chunker.ts`	🟡 欄位擴充
`tools/semantic-search/src/types.ts`	🟡 新增型別
`tools/semantic-search/package.json`	🟡 加依賴
`.mcp.json`	🔵 新建（MCP 註冊）
`api/src/routes/campaign.ts`	🟡 封測寄信
`admin/index.html`	🔵 新建
`遊戲企劃/技術筆記/語意搜尋工具演進紀錄.md`	🔵 新建

規模

13 個檔案變更，+3,447 行

2026-03-03 ~ 03-04 — 回合流程重構 + 選單系統 + 遊戲指南

回合流程重構：季初統一部署（commit: 782226e）

將原本「逐人選行動 → 立即執行」改為「全員先部署 → 批次執行」：

新增 DeployPanel.tsx：部署畫面，逐一為族人指定行動（探索/休息/建設/配對/跳過）
回合開始時進入部署階段，所有族人行動確認後才一次性結算
[未安排] 標記以警告色 + 閃爍游標提示玩家
「確認部署」按鈕預設暗色，聚焦時才亮起

遊戲選單面板（commit: 49dfc14）

新增 GameMenuPanel.tsx，由 StatusBar 右側 [選單] 按鈕開啟：

選單項目：族誌、系統日誌、返回主畫面
返回主畫面需二次確認（防誤觸）
系統日誌入口從底部移至選單，SystemLog 移除內建 toggle 按鈕

UI 微調

項目	說明
族誌入口	從 StatusBar 獨立按鈕整合至選單
系統日誌	入口移至選單，展開由 GameScreen 控制
資源列位置	合併到 StatusBar 左側，點擊開啟存檔面板
確認部署按鈕	預設 dim，`:focus` / `:focus-visible` 才亮綠

遊戲指南面板（commit: 7c3711b）

新增 GameGuidePanel.tsx（HELP.SYS — 廢土求生手冊），全螢幕 overlay 手冊：

章節	內容
[1/3] 基本玩法	回合制節奏、五種行動、家園事件、回合結算流程
[2/3] 屬性與檢定	四大屬性、D20 檢定、修正值對照表、族長天選技能
[3/3] 家族經營	四種資源、階段升級條件、資源上限、生育/壽命、設施系統

選單入口位於「族誌」與「系統日誌」之間
沿用 ChroniclePanel 的 overlay 模式（fixed inset-0 z-50）
純靜態內容，不依賴 gameState
Esc / [x] 關閉，與其他面板互斥

修改檔案一覽

檔案	變更
`GameGuidePanel.tsx`	🔵 新建 — 遊戲指南 overlay
`GameMenuPanel.tsx`	🔵 新建 — 遊戲選單面板
`DeployPanel.tsx`	🟡 改 — 確認部署按鈕聚焦樣式
`StatusBar.tsx`	🟡 改 — 選單 + 指南接線、面板互斥
`SystemLog.tsx`	🟡 改 — 移除內建 toggle，改由外部控制
`GameScreen.tsx`	🟡 改 — syslog toggle callback
`index.css`	🟡 改 — deploy-confirm-btn focus 樣式

規模

7 個檔案變更，+393 / -67 行

2026-03-02 ~ 03-03 — 庄園建設系統 + 族長繼承系統

庄園建設系統全數值定案（commit: 228952b）

完成庄園建設系統企劃文件的全部數值填入：

12 座設施完整定價（木材/石材/金屬成本、工期、維護費）
損壞參數：每季劣化率、修復成本比例
庄主機制：取整規則與管理效率公式

庄園建設系統實作（commit: 7a7320a）

新增完整的庄園建設引擎與 UI，涵蓋設施定義、建造流程、效果計算：

新增檔案

檔案	說明
`estate.ts`	庄園引擎模組：設施定義、建造邏輯、效果計算
`SuccessionPanel.tsx`	族長繼承選人 UI（重用 ChosenOneQuiz）

引擎變更

檔案	變更
`types.ts`	新增 `Facility`、`EstateState`、`FacilityEffect`、`SuccessionSub` 型別
`constants.ts`	新增 `RESOURCE_CAPS` 資源上限、`STAGE_REQUIREMENTS` 階段門檻
`simulation.ts`	整合建造進度推進、設施產出（糧水/知識）、`chiefDied` 旗標
`gameState.ts`	新增 `buildFacility` action、繼承流程（`checkAndStartSuccession` / `selectNewLeader` / `completeSuccession`）
`eventEngine.ts`	新增 `facility_level` 條件支援
`saveLoad.ts`	向後相容 `estate` 欄位
`chosenOne.ts`	新增 `removeLeaderSkill()` 反轉函式（繼承時移除前族長技能加成）

UI 變更

檔案	變更
`ActionPanel.tsx`	新增建設設施 UI（設施清單、建造按鈕、進度顯示）
`FamilyPanel.tsx`	顯示族人「建設中」狀態
`GameScreen.tsx`	路由 `SUCCESSION` 子階段

族長繼承系統

族長死亡時觸發繼承流程：

偵測族長死亡（chiefDied 旗標），攔截正常回合流程
玩家從存活族人中選出新族長
重用 ChosenOneQuiz 為新族長賦予天選技能
前族長的技能加成自動反轉（removeLeaderSkill）
GM 快進模式自動解決繼承（選第一個存活族人）
loadGame 向後相容：偵測孤兒狀態（族長 ID 指向已死亡的人）自動修復

家族建立流程調整

收養族人取消重擲功能：MemberCard 新增 canRegenerate prop，收養族人只能確認、不能重骰

規模

14 個檔案變更，+947 / -37 行

2026-02-28 — 長壽基因系統 + 家族創建修正

玩家測試回饋修復（commit: 9fca036）

根據封測玩家回饋，修正家族創建流程三個問題：

Off-by-one Bug：currentExtraIdx + 2 → +1，修正族人編號顯示溢出（4 人家族顯示「族人 5/4」）
收養確認按鈕：步驟 4 人口揭曉後新增確認按鈕，避免直接跳入族人生成的突兀感
敘事文案調整：
- 族長重擲按鈕改為「不對，叫下一個來（老者低喃）」
- 族人確認按鈕改為「乞求老者收養此人」
- 步驟 1 開場改為老者招手敘事
- MemberCard 顯示天選技能
- 移除 MemberCard 不再使用的 surname prop

長壽基因三層系統（commit: 612edb5）

新增長壽基因機制，為未來完整基因系統的先行基礎：

層次	機制	壽命加成
突變池	`長壽基因` 加入 MUTATIONS_ADVANTAGE	+6 年
獨立觸發	每人額外 5% 機率獲得長壽基因	+6 年
家族遺傳	家族建立時擲骰（60%/25%/15%）決定等級 0/1/2	等級×2 年

技術變更

checkMutation() 介面變更：回傳值從 string | null 改為 string[]，支援多重突變共存
calcLifespan() 擴充：新增 tags 和 familyLongevityGene 參數
applyLeaderSkill() 擴充：體質加成連動壽命重算時傳入家族長壽等級
FamilyState 新增 longevityGene 欄位（0 | 1 | 2）
MemberCard：突變顯示改為陣列格式（多個突變用頓號分隔）

族長重擲保留身份

重擲族長時只重擲四大屬性和突變，保留姓名、性別、年齡不變
年齡骰面（ageRolls）保留原始結果顯示

修改檔案（6 個）

檔案	變更
`types.ts`	FamilyState 新增 longevityGene
`simulation.ts`	checkMutation → string[]、calcLifespan 加長壽參數
`chosenOne.ts`	applyLeaderSkill 加家族基因參數
`gameState.ts`	initFamily 接收 longevityGene
`CharacterCreation.tsx`	家族基因擲骰 + 所有 generateMember 傳參 + 族長重擲保留身份
`MemberCard.tsx`	mutation → mutations 陣列顯示

2026-02-26 — 專案整理 + Build 修正

專案整理（commit: b7b39fb）

將先前未追蹤的檔案和目錄整理入 Git：

新增 api/ 後端服務：Hono + Node.js，處理 email 訂閱與 MailerSend 寄信（api.wasteland.tw）
新增 tools/ 語意搜尋工具：本地向量搜尋（先前已建立但未追蹤）
Logo 目錄重整：logo 2/ → logo/
CLAUDE.md 更新：補充第四個服務 api.wasteland.tw 部署設定，三服務改四服務
.gitignore 強化：新增 api/、tools/ 忽略規則，保護 api/data/subscribers.json（含真實訂閱者 email）
新增文件：遊戲行銷/（封測玩家名單、行銷事件）、搬遷教學.md、task/plan-wasteland-lore-skill.md

Build 修正（commit: 60ca590）

修正 game_phase/src/demo/DemoEndScreen.tsx 的 TS6133 錯誤：移除未使用的 onRestart 參數
npm run build 恢復正常

基礎設施修正

修正 .git/hooks/pre-commit CRLF 行尾符號問題（\r 導致 #!/bin/bash 找不到執行程式），轉換為 LF

2026-02-25 — 本地向量資料庫 + 語意搜尋 Skill

向量資料庫（`tools/semantic-search/`）

建立本地語意搜尋工具，用於輔助企劃撰寫和文本比對：

技術棧：Orama（純 TypeScript 向量資料庫）+ Transformers.js（本地嵌入模型）
嵌入模型：Xenova/multilingual-e5-small（384 維，支援繁體中文，~130MB）
索引內容：遊戲企劃/ 下所有 .md 和 events.csv，共 683 個文字區塊
搜尋方式：Hybrid（BM25 全文搜尋 + 向量語意搜尋）
完全離線：模型首次下載後快取在本機，不需外部 API

新增檔案

檔案	說明
`tools/semantic-search/src/config.ts`	路徑、模型名稱、分塊設定
`tools/semantic-search/src/types.ts`	TextChunk 型別定義
`tools/semantic-search/src/embedder.ts`	Transformers.js 封裝（passage/query 前綴）
`tools/semantic-search/src/chunker.ts`	中文 Markdown 分塊（按標題/段落切分）
`tools/semantic-search/src/reader.ts`	讀取 .md + .csv 檔案
`tools/semantic-search/src/indexer.ts`	建置索引主程式
`tools/semantic-search/src/searcher.ts`	CLI 搜尋介面（單次 + 互動模式）

使用方式

bash

cd tools/semantic-search
npm install              # 首次
npm run index            # 建置索引（~4 秒）
npm run search -- "糧食危機"        # 單次搜尋
npm run search:interactive           # 互動模式

Claude Code Skill：廢土知識庫（`/wasteland-lore`）

新增 .claude/skills/wasteland-lore.md，讓 Claude 可用自然語言啟動向量搜尋：

搜尋模式：找故事文本、找相關企劃
比對模式：比較文本、找矛盾
輔助撰寫模式：為新企劃找相關上下文

可用 /wasteland-lore 手動觸發，也會在自然語言提到搜尋需求時自動啟用。

Git Pre-commit Hook

設定 .git/hooks/pre-commit：當 遊戲企劃/ 下的 .md 或 .csv 有變動時，自動重建向量索引。只改程式碼時不觸發，索引失敗不阻擋 commit。

2026-02-23 — UI 設計系統實裝（Phase A–D）+ v0.2.1

UI 重構四階段

依據 UI設計系統規範.md 完成四個 Phase：

Phase A — No-Scroll 基礎建設

固定視窗佈局（h-screen + overflow-hidden）
PaginatedText 分頁元件：自動分頁、頁碼指示、翻頁按鈕
FamilyPanel / SystemLog 改為 overlay 展開（半透明遮罩 + 點擊收合）
StatusBar 單行格式化

Phase B — 桌面響應式佈局

lg: 斷點雙欄佈局：左側欄（家族成員 300px）+ 右主內容區
桌面版最大寬度 min(1100px, 100vh×16/9)，手機版 640px
FamilyPanel 桌面側欄模式（卡片式、分頁控制）
SystemLog 桌面版獨立展開狀態

Phase C — 鍵盤導航系統

:focus-visible 焦點指示器 + .key-cap 按鍵樣式
Tab 區域循環（主內容區 ↔ 側欄）
↑↓ / WS 選項導航、←→ / AD 分頁翻頁
Enter 確認/繼續、Esc 關閉 overlay、1-4 事件快選
新增 KeyHintBar 桌面版底部按鍵提示列（依場景動態切換）
PaginatedText 加 forwardRef + useImperativeHandle 暴露翻頁 API
overlay 狀態上提至 GameScreen 統一管理

Phase D — 內容適配

手機版字體 text-sm、桌面版 sm:text-base
桌面版間距加大（px-8 py-4）

修改檔案一覽

檔案	變更
`index.css`	focus-visible + key-cap 樣式
`PaginatedText.tsx`	新增 — 分頁元件 + forwardRef
`KeyHintBar.tsx`	新增 — 桌面按鍵提示列
`GameScreen.tsx`	雙欄佈局 + Tab 循環 + overlay 狀態上提
`EventDisplay.tsx`	分頁整合 + 鍵盤導航
`ActionPanel.tsx`	分頁整合 + 鍵盤導航
`FamilyPanel.tsx`	overlay + 桌面側欄 + 鍵盤導航
`SystemLog.tsx`	overlay + 外部狀態
`StatusBar.tsx`	單行格式化

2026-02-22 — Session 6–8 + 回合重構 + 探索優化 + 敘事改寫

Session 6：存檔編碼系統

lz-string 壓縮 + WL1 編碼格式

Session 7：Stage 舞台系統重構

統一 UI 場景狀態機，取代原本散落的 gamePhase 判斷

Session 8：家族建立流程重構

依據 PDF 設計稿重寫 CharacterCreation
族人收養敘事文案調整（老者結語、點頭改瞭然）

回合系統重構

每族人每季一次行動（取代原本的一次性派遣）

探索派遣體驗優化

region 過濾、exploredCount、探索日誌標題、結果文字

主線事件改寫

「老人的話」敘事重構：老者沉默取代死亡

其他

字型本地化（Noto Sans Mono）
新增 UI 設計系統規範文件
新增探索派遣系統企劃文件

2026-02-21（晚上）— Session 5 完成 + 遊戲體驗優化

Session 5：派遣探索 + 存檔整合 + 結局畫面

派遣族人探索功能完成，串接事件引擎
存檔 / 讀檔整合（localStorage）
結局畫面（GameOverScreen）統計摘要

遊戲機制調整

家族初始人數改為 1d4+1（範圍 2–5 人），取代固定值
起始糧水改為隨人口浮動 Nd12+N（N=人口數），人多糧多但不保證夠用

UI/UX 改善

自動捲動：新內容出現時自動捲到玩家視線中央
家族建立 UI 文字調整：族長選擇標題加姓氏、開始按鈕改動態文案
族人生成按鈕文案：「重新生成」→「隨機合成X氏的血脈」、「確認」→「收養此人」
底部佔位空間：家族建立流程底部加 50vh，讓最後訊息能捲到畫面中央

Bug 修正

修正 EX 探索事件 auto_check 欄位偏移（CSV 多餘逗號）
防禦性修正探索事件卡住問題：EventDisplay 加 fallback 確認按鈕

文件站 & 官網

文件站新增事件卡片列表頁面（/events/）
簡化文件站首頁、補齊 hero 導覽
官網 footer 加入文件站連結
Landing page 更新 Google 表單連結（等待名單正式上線）

部署踩坑

wasteland.tw 反覆顯示文件站而非 landing page
原因一：環境變數 ZBPACK 拼成 ZAPACK
原因二：Zeabur 服務設定中有殘留的自訂 Dockerfile，覆蓋了環境變數
原因三：Root Directory 設為 / 而非 landing
嘗試加 landing/package.json 作為安全網，反而導致 Zeabur 誤判為 Node.js 專案（404），已移除

2026-02-21（下午）— 部署架構 + Session 3–4 開發

部署架構（wasteland.tw）

購買網域 wasteland.tw，完成三服務獨立部署：

wasteland.tw → 行銷官網（landing/index.html，CRT 終端機風格）
docs.wasteland.tw → VitePress 遊戲企劃文件站
play.wasteland.tw → React 遊戲本體

踩坑紀錄：

嘗試將文件站放在 /gd-doc/ 子路徑，但 Zeabur Caddy SPA fallback 導致子路徑全部導回 index.html
嘗試 base: '/gd-doc/' + outDir + mv 目錄重組，Zeabur 環境不支援
發現 Zeabur zbpack.json 只讀根目錄，子目錄的設定檔會被忽略
最終解法：三服務分開部署，用環境變數 ZBPACK_BUILD_COMMAND / ZBPACK_OUTPUT_DIR 覆蓋每個服務的 build 設定
修正 play.wasteland.tw 手機空白頁：移除 Vite base: '/game/'（舊路徑遺留）

品牌資產

新增 logo/ 資料夾，放入 Mobius logo（PNG × 2 + SVG）
三個網站統一使用 Mobius logo 作為 favicon

Session 3：主畫面 UI + 回合系統

五區塊佈局完成（StatusBar、FamilyPanel、ActionPanel、EventDisplay、SystemLog）
回合結算邏輯（糧水消耗、季節修正、飢荒 D20 檢定、老化、壽命判定）
壽命公式平衡修正

Session 4a：資料載入 + 事件引擎核心

dataLoader.ts：CSV 解析（papaparse）+ Markdown 渲染（marked）
eventEngine.ts：事件池篩選、加權隨機抽取、條件語法解析、冷卻追蹤、D20 檢定
補齊事件系統 TypeScript 型別

Session 4b：事件顯示 UI + 回合事件整合

事件顯示四段結構（標題→正文→選項→結果）
回合內事件觸發整合
劇情腳本可讀性改善（新增 --color-text 柔綠色）

事件內容

新增 Phase 1 探索事件 #11–20（10 個 EX .md 腳本）
新增主線事件（3 個 QT .md 腳本）
新增季節事件（8 個 SN .md 腳本）
新增生命週期事件（6 個 LF .md 腳本）

工單管理

新增 Session 6 存檔編碼系統工單（從 Session 5 拆出獨立追蹤）
Session 4 拆分為 4a（資料+引擎）與 4b（UI+整合）
初始年齡改為 3d6，更新 Session 3/4 工單

2026-02-21（上午）— 企劃文件 + 文件站

新增文件

技能系統.md — 六大技能等級結構（Lv.0–5）、三種學習途徑（庄園訓練/探索經歷/族誌研讀）、師徒傳授與族誌傳承機制、Lv.5 大師副作用、TypeScript 介面定義
VitePress 文件閱讀站 — 建立 package.json、.vitepress/config.mts、zbpack.json、遊戲企劃/index.md，讓所有企劃文件可在手機上瀏覽，支援 Zeabur 靜態站部署

更新文件

開發路線圖.md — 系統清單從 19 個擴充至 22 個（新增命名系統、靈能系統、新玩家建立流程），新增企劃文件索引（11 份），新增企劃文件待辦清單（13 項未規劃機制，依核心/重要/後期分類），更新系統間依賴關係圖
.gitignore — 新增排除 .claude/ 目錄

補推

基因系統.md、存檔機制.md、新玩家家族建立流程.md — 三份先前未追蹤的企劃文件補推上 GitHub

2026-02-20

專案建立

建立 GitHub repo：soking1010/Wasteland_TW
安裝 GitHub CLI（gh）並設定認證
建立「遊戲企劃」資料夾

新增文件

廢土傳承遊戲企劃構想.md — 核心概念、世界觀（核戰後台灣）、三種廢土人分類、傳承機制四層面、源血傳承、族誌系統、雙核心玩法循環、六大技能、四大屬性、D20 檢定、敘事風格六原則
技術棧選擇.md — 確立 React + TypeScript（Vite）方案，與 Twine/ink/Ren'Py 的比較論述
開發路線圖.md — 初版，19 個遊戲系統評估、依賴關係圖、5 階段 MVP 計畫
地圖設計.md — 7 大區域（中部山脈/西部沿海/北部廢墟帶/南部平原/東部海岸/離島/地下遺跡）、35 個地點、R##_L##_S## 編碼規則、輻射等級 1–10、地點狀態 5 階段
命名系統.md — 族人命名（20 廢土姓+20 舊世代姓、字庫 AB）、NPC 綽號制（區域+特徵+識別詞）、靈名系統
台灣歷史常見姓名組合表.md — 姓名參考資料
廢土地域敘事.md — 各區域的敘事文本素材
隨機事件機制.md — 事件編碼 EVT_[情境]_[類型][編號]、5 種事件池（探索/家園/季節/生命/主線）、加權抽取、條件語法 12 種、choices JSON 格式、效果系統 12 目標×5 運算、事件鏈

更新文件

CLAUDE.md — 部署平台改為 Zeabur、專案概述加入「行動優先（Mobile First）」
廢土傳承遊戲企劃構想.md — 擴充內容（外部編輯）

廢土傳承 — 開發日誌 ​

2026-03-08 — USB 遊戲手把支援（Gamepad-to-Keyboard Bridge） ​

概述 ​

新增檔案（3 個） ​

修改檔案（5 個） ​

按鈕映射表 ​

除錯紀錄（6 個問題） ​

技術要點 ​

commit ​

規模 ​

2026-03-06 — AI 停機兩天後復工：語意搜尋大升級 + MCP Server ​

事故紀錄：開發資源額度耗盡 ​

語意搜尋工具大升級（commit: 719a29b） ​

新增模組 ​

重構 ​

MCP Server 三工具 ​

技術文件 ​

API 封測 campaign 功能（commit: 30dabdd） ​

Admin 面板（commit: ef20bb3） ​

修改檔案一覽 ​

規模 ​

2026-03-03 ~ 03-04 — 回合流程重構 + 選單系統 + 遊戲指南 ​

回合流程重構：季初統一部署（commit: 782226e） ​

遊戲選單面板（commit: 49dfc14） ​

UI 微調 ​

遊戲指南面板（commit: 7c3711b） ​

修改檔案一覽 ​

規模 ​

2026-03-02 ~ 03-03 — 庄園建設系統 + 族長繼承系統 ​

庄園建設系統全數值定案（commit: 228952b） ​

庄園建設系統實作（commit: 7a7320a） ​

新增檔案 ​

引擎變更 ​

UI 變更 ​

族長繼承系統 ​

家族建立流程調整 ​

規模 ​

2026-02-28 — 長壽基因系統 + 家族創建修正 ​

玩家測試回饋修復（commit: 9fca036） ​

長壽基因三層系統（commit: 612edb5） ​

技術變更 ​

族長重擲保留身份 ​

修改檔案（6 個） ​

2026-02-26 — 專案整理 + Build 修正 ​

專案整理（commit: b7b39fb） ​

Build 修正（commit: 60ca590） ​

基礎設施修正 ​

2026-02-25 — 本地向量資料庫 + 語意搜尋 Skill ​

向量資料庫（tools/semantic-search/） ​

新增檔案 ​

使用方式 ​

Claude Code Skill：廢土知識庫（/wasteland-lore） ​

Git Pre-commit Hook ​

2026-02-23 — UI 設計系統實裝（Phase A–D）+ v0.2.1 ​

UI 重構四階段 ​

修改檔案一覽 ​

2026-02-22 — Session 6–8 + 回合重構 + 探索優化 + 敘事改寫 ​

Session 6：存檔編碼系統 ​

Session 7：Stage 舞台系統重構 ​

Session 8：家族建立流程重構 ​

回合系統重構 ​

探索派遣體驗優化 ​

主線事件改寫 ​

其他 ​

2026-02-21（晚上）— Session 5 完成 + 遊戲體驗優化 ​

Session 5：派遣探索 + 存檔整合 + 結局畫面 ​

遊戲機制調整 ​

UI/UX 改善 ​

Bug 修正 ​

文件站 & 官網 ​

部署踩坑 ​

2026-02-21（下午）— 部署架構 + Session 3–4 開發 ​

部署架構（wasteland.tw） ​

品牌資產 ​

Session 3：主畫面 UI + 回合系統 ​

Session 4a：資料載入 + 事件引擎核心 ​

Session 4b：事件顯示 UI + 回合事件整合 ​

事件內容 ​

工單管理 ​

2026-02-21（上午）— 企劃文件 + 文件站 ​

廢土傳承 — 開發日誌

2026-03-08 — USB 遊戲手把支援（Gamepad-to-Keyboard Bridge）

概述

新增檔案（3 個）

修改檔案（5 個）

按鈕映射表

除錯紀錄（6 個問題）

技術要點

commit

規模

2026-03-06 — AI 停機兩天後復工：語意搜尋大升級 + MCP Server

事故紀錄：開發資源額度耗盡

語意搜尋工具大升級（commit: 719a29b）

新增模組

重構

MCP Server 三工具

技術文件

API 封測 campaign 功能（commit: 30dabdd）

Admin 面板（commit: ef20bb3）

修改檔案一覽

規模

2026-03-03 ~ 03-04 — 回合流程重構 + 選單系統 + 遊戲指南

回合流程重構：季初統一部署（commit: 782226e）

遊戲選單面板（commit: 49dfc14）

UI 微調

遊戲指南面板（commit: 7c3711b）

修改檔案一覽

規模

2026-03-02 ~ 03-03 — 庄園建設系統 + 族長繼承系統

庄園建設系統全數值定案（commit: 228952b）

庄園建設系統實作（commit: 7a7320a）

新增檔案

引擎變更

UI 變更

族長繼承系統

家族建立流程調整

規模

2026-02-28 — 長壽基因系統 + 家族創建修正

玩家測試回饋修復（commit: 9fca036）

長壽基因三層系統（commit: 612edb5）

技術變更

族長重擲保留身份

修改檔案（6 個）

2026-02-26 — 專案整理 + Build 修正

專案整理（commit: b7b39fb）

Build 修正（commit: 60ca590）

基礎設施修正

2026-02-25 — 本地向量資料庫 + 語意搜尋 Skill

向量資料庫（`tools/semantic-search/`）

新增檔案

使用方式

Claude Code Skill：廢土知識庫（`/wasteland-lore`）

Git Pre-commit Hook

2026-02-23 — UI 設計系統實裝（Phase A–D）+ v0.2.1

UI 重構四階段

修改檔案一覽

2026-02-22 — Session 6–8 + 回合重構 + 探索優化 + 敘事改寫

Session 6：存檔編碼系統

Session 7：Stage 舞台系統重構

Session 8：家族建立流程重構

回合系統重構

探索派遣體驗優化

主線事件改寫

其他

2026-02-21（晚上）— Session 5 完成 + 遊戲體驗優化

Session 5：派遣探索 + 存檔整合 + 結局畫面

遊戲機制調整

UI/UX 改善

Bug 修正

文件站 & 官網

部署踩坑

2026-02-21（下午）— 部署架構 + Session 3–4 開發

部署架構（wasteland.tw）

品牌資產

Session 3：主畫面 UI + 回合系統

Session 4a：資料載入 + 事件引擎核心

Session 4b：事件顯示 UI + 回合事件整合

事件內容

工單管理

2026-02-21（上午）— 企劃文件 + 文件站