Zions-store/project-ledger

版權所有 (C) 2026 ZionXiaoxiSuOGLocGo SPDX-License-Identifier: GPL-3.0-or-later

project-docs

建立與維護三份文件的專案知識體系。支援 project-onboard 可偵測的所有專案類型，並根據專案類型自動選用正確的範本。

三份文件系統

檔案	目的	更新頻率
AGENTS.md	專案概覽：專案識別、目錄結構、類別架構、進入點、相依性、備註	每個里程碑（約 3-5 個新檔案/類別）
PROJECT_STATE.md	即時文件：完整的類別/原始碼清單（含參數）、設定、模組地圖、系統流程、完成/待辦清單	每次會話結束時
DEVLOG.md	開發日誌：時間線條目——做了什麼、為什麼、學到了什麼	每天或每個功能里程碑

請參閱 maintenance-spec.md 以取得關於更新觸發條件、內容邊界和一致性檢查的詳細規則。

範本選擇

範本的選擇遵循與 project-onboard 規則套件相同的自動發現模式。此工具會嘗試載入 templates/<type>/PROJECT_STATE.md.tmpl，其中 <type> 是 AGENTS.md 基本資訊中 Type 欄位的小寫值。如果沒有符合類型的範本，則會回退到 templates/PROJECT_STATE.md.tmpl。

templates/<type>/PROJECT_STATE.md.tmpl 存在？→ 使用它
                                        不存在 → 使用 templates/PROJECT_STATE.md.tmpl（通用回退）

若要新增支援新的引擎或框架：建立 templates/<type>/PROJECT_STATE.md.tmpl。無需修改程式碼——此工具會自動發現它。

所有類型共用 templates/DEVLOG.md.tmpl（與專案類型無關）。

AGENTS.md → PROJECT_STATE.md 欄位對應

從 AGENTS.md 的資料預先填入 PROJECT_STATE.md 時，請使用以下對應：

AGENTS.md 區段	AGENTS.md 欄位	STATE 範本區段	STATE 佔位符
基本資訊	Type, Language, Framework/Engine, Key Dependencies	§1 專案識別	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
基本資訊	Engine（適用於遊戲專案）	§1 專案識別	{{ENGINE_VERSION}}
目錄結構	目錄與說明	§2 目錄結構	{{DIRECTORY_TREE}}（通用）或 Source/{{MODULE_NAME}}/...（UE）
核心架構	主要檔案/類別與角色	§3 原始碼/腳本清單	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
相依性	套件摘要	§4 設定 / §7 相依性	{{CONFIG_KEY}}, {{DEP_NAME}}（依上下文而定）
建置與執行	建置/測試指令	§9 建置與執行	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
進入點	啟動檔案/場景與角色	§1 專案識別（模組）	{{MODULE_NAME}}

對於非英文輸出：翻譯區段標題、標籤和佔位符描述，但保留 {{PLACEHOLDER}} 標記不變。

何時使用此技能

• 使用者說「init project docs」/「建立文檔體系」/「project-docs」
• 新專案需要建立 PROJECT_STATE.md 和 DEVLOG.md
• 現有專案已有 AGENTS.md 但缺少其他兩個文件
• 使用者在某次會話後要求更新專案狀態

工作流程

1. 初始化（新專案 / 缺少文件）

0. 詢問使用者要以何種語言生成文件。如果使用者跳過或說「無所謂」，則預設為英文。LLM 能輸出的任何語言都支援——代理會在生成時進行翻譯：

   「請問要以何種語言撰寫專案文件？預設：英文。LLM 能輸出的任何語言都支援。」

1. 檢查 AGENTS.md 是否存在。

   • 如果不存在：提議先執行 project-onboard 技能來生成 AGENTS.md。在此步驟停止。
   • 如果存在：讀取 AGENTS.md 並提取：
     • 專案名稱
     • 類型（來自基本資訊——例如「unreal」、「unity」、「nodejs」、「python」）
     • 核心架構（類別、檔案、角色）

2. 偵測範本：根據提取的類型（小寫），嘗試載入類型專用的範本。如果沒有相符項目，則回退到通用範本：

   • 首先嘗試 templates/<type>/PROJECT_STATE.md.tmpl
   • 如果該檔案不存在，則使用 templates/PROJECT_STATE.md.tmpl（通用）

3. 從選定的範本生成 PROJECT_STATE.md：

   • 使用上述欄位對應表，從 AGENTS.md 的資料預先填入 §1-§3。
   • 將其餘區段保留其佔位符結構，以供未來更新。

4. 從 templates/DEVLOG.md.tmpl 生成 DEVLOG.md：

   • 填入專案名稱。
   • 保留條目範本，準備好供第一個開發日誌條目使用。

5. 在 AGENTS.md 頂端、# Project Name 標題行之後（但在其餘內容之前），插入以下區塊：

   ## 請先閱讀此處
   
   1. 閱讀 `PROJECT_STATE.md`——當前任務狀態與待辦事項（§10）
   2. 閱讀 `DEVLOG.md`——近期開發歷史
   
   ---
   

6. 報告已建立哪些文件、使用了哪個範本，以及使用何種語言。

2. 更新（現有文件）

1. 讀取 PROJECT_STATE.md → 識別 §10 待辦清單
2. 詢問使用者完成了什麼 / 發生了什麼變更
3. 更新受影響的區段：
   • §1-§2：如果專案識別或目錄結構有變更
   • §3：新增的類別、檔案或主要成員
   • §4：設定變更（藍圖屬性、預製體設定或通用設定）
   • §5：輸入綁定、動作對應或模組/套件變更
   • §6：系統邏輯、架構流程或遊戲系統變更
   • §7：場景/關卡設定或外部服務變更
   • §8：任何數值參數變更
   • §9：建置問題、新的編譯錯誤或指令變更
   • §10：務必更新——完成清單、待辦清單、已知問題
4. 將條目附加到 DEVLOG.md（依據 maintenance-spec.md 的格式）
5. 如果架構有變更（新的類別、插件、目錄）→ 更新 AGENTS.md

3. 一致性檢查

在任何更新之後，請驗證：

• AGENTS.md 與 PROJECT_STATE.md 之間沒有重疊的資料（架構概覽 vs 參數細節）
• AGENTS.md 中的目錄結構條目在 PROJECT_STATE.md 中都有對應項目
• PROJECT_STATE.md §8 的參數值與實際原始碼預設值一致（例如 .h 預設值、設定檔值、BP CDO 覆蓋值）
• PROJECT_STATE.md §10 的待辦清單與 DEVLOG.md 的最新條目沒有矛盾（如果 DEVLOG 顯示已完成，STATE 也應相符）
• 三份文件之間沒有重複資訊（一個事實 = 一個位置）

範本

範本會依據專案類型自動發現——無需硬編碼對應表。目錄結構與 project-onboard 的參考結構一致：

templates/
├── DEVLOG.md.tmpl              ← 所有類型（通用）
├── PROJECT_STATE.md.tmpl       ← 回退（通用）
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

templates/<type>/PROJECT_STATE.md.tmpl 檔案為選擇性。此工具會嘗試載入一個與 AGENTS.md 類型相符的檔案；如果不存在，則使用根目錄的通用範本。

新增新的類型：建立 templates/<type>/PROJECT_STATE.md.tmpl，並包含類型專用的區段。此工具會在下次執行時自動發現它——無需修改任何程式碼。

規則

• 絕不覆寫現有檔案。如果文件已存在，則在原地更新。
• 尊重內容邊界：AGENTS.md = 架構概覽。PROJECT_STATE.md = 參數細節 + 狀態。DEVLOG.md = 時間線敘述。
• 維護規範：請參閱 maintenance-spec.md 以取得確切的更新觸發條件、內容邊界以及禁止的做法。
• STATE/DEVLOG 中的專案特定路徑/類別名稱是預期的——這些是專案文件，而非可重複使用的說明書。