Project Class Architect（專案類別架構師）
將一個儲存庫轉換為可互動的 UML 類別圖，讓開發者得以探索而非閱讀數百個檔案。分析過程以證據為基礎：圖表中的每個類別、屬性、方法及關係皆指向其來源檔案與行號。所有內容皆非虛構；啟發式發現的結果會標示為 推測（inferred）。
本檔案中的所有路徑皆相對於技能目錄（即包含此 SKILL.md 的資料夾）。
需求
- Node.js 18+（
node --version）。這些腳本沒有外部相依套件：請勿對此技能執行npm install。 - 對儲存庫的讀取權限。分析過程絕不會修改原始碼檔案；只會寫入其輸出資料夾。
- 若無可用的 Node.js，請使用文件末尾所述的備用方案。
工作流程
1. 識別儲存庫
使用使用者所提及專案的絕對路徑（通常為當前工作區）。下列命令從技能目錄執行，因此相對路徑（如 .）會指向技能本身。
2. 產生圖表
node scripts/class-architect.js generate "/absolute/path/to/repo"
常用選項（完整列表請參閱 CLI 參考）：
| 需求 | 選項 |
|---|---|
| 在頁尾加入作者資訊 | --author "姓名" --author-role "軟體工程師" |
| 圖表標題 | --title "帳單服務" |
| 僅處理大型儲存庫的一部分 | --include "src/main/java/com/acme/billing/**"（可重複） |
| 跳過資料夾 | --exclude "legacy/**"（可重複） |
| 限制語言 | --languages java,sql |
| 也分析測試 | --include-tests |
| 初始檢視 / 佈局 | `--view classes |
| 自訂輸出資料夾 | --out "/path/to/output"（預設為 <儲存庫>/.class-architect） |
| 避免在 HTML 中顯示本機路徑 | --hide-root（停用「在編輯器中開啟」連結） |
該命令會在標準輸出（stdout）印出 JSON 摘要（進度訊息會輸出到 stderr）。結束代碼：0 成功，1 使用錯誤，2 無可分析的原始碼檔案，3 模型驗證失敗（未寫入任何內容），4 內部錯誤。
3. 檢查結果
讀取 JSON 摘要（status、outputs、summary.counts、summary.insights、summary.edits、validation）。在輸出資料夾中寫入的檔案：
diagram.html- 可互動的圖表（可在瀏覽器中開啟；可離線運作）。report.md/report.json- 已掃描的檔案、類別、介面、列舉、關係、推測的關係、未解析的引用、被排除的檔案及原因、警告、洞見。model.json- UML 模型（單一事實來源）；overlay.json- 使用者編輯（若有編輯時）。
若結束代碼為 2，請調整 --include / --languages，並說明哪些資料夾被排除及原因（從 JSON 的 details 取得）。若結束代碼為 3，請報告驗證錯誤；請勿手動編輯模型以隱藏這些錯誤。
對於數百個類別的儲存庫，圖表會以概覽（Overview）（模組）開啟，讓使用者可以向下鑽研至模組與套件；您也可以使用 --include 為某個限界上下文（bounded context）產生聚焦的圖表。
4. 向使用者展示圖表
- 提供
diagram.html的路徑（以及outputs.diagramUrl中的file://URL）。除非使用者要求且您的環境允許，否則不要嘗試啟動瀏覽器。 - 僅摘要報告中的內容：類別 / 介面 / 列舉 / 關係的數量、偵測到的框架、依賴循環、架構發現、未解析的引用及警告。請精確引用類別名稱。
- 提及標記為 推測（inferred） 的關係（命名慣例、Go 結構型別）應加以驗證，且衍生的資料表/欄位名稱會標記為衍生。
- 指出主要互動方式：點擊類別或行以檢視詳情（內含原始檔與行號）、搜尋（
/）、篩選、檢視（概覽、套件、類別、資料庫 ER）、放大鏡（L）、編輯模式（E）、洞見（Insights）、匯出（Export）。詳細說明：可互動圖表指南。
5. 程式碼變更後重新整理
再次執行相同命令。它會：
- 僅重新分析已變更的檔案（增量快取），
- 保留所有使用者編輯（來自
overlay.json以及使用者透過儲存按鈕儲存至diagram.html的編輯）， - 將目標從程式碼中消失的編輯報告為孤兒（orphaned）（保留，永不靜默刪除），以及與原始碼變更衝突的編輯，
- 突顯與前次執行相比新增 / 移除 / 修改的類別，
- 保留前次圖表的備份（
diagram.prev.html）。
若使用者已將圖表複製到其他地方，請使用 --edits "/path/to/saved-diagram.html" 傳入。
6. 可選：文件章節
圖表可以在其下方顯示額外文件（表格、流程、步驟、列舉網格、橫幅備註），使用原始範本的元件。僅新增您已在程式碼中驗證的事實，並引用來源檔案。請按照設定指南撰寫 JSON 檔案，並傳入 --notes notes.json。
規則
- 絕不要在此技能中修改、格式化或「修正」受分析的原始碼。
- 絕不要憑空虛構類別、成員或關係，也絕不要將 推測（inferred） 的關係視為確定不變。
- 絕不要刪除或覆寫
overlay.json或使用者儲存的diagram.html：CLI 會為您合併它們。 - 輸出資料夾
.class-architect/是自動產生的；建議將其加入.gitignore，除非使用者想要提交圖表。 - 請勿將圖表或模型上傳至任何地方：它們可能包含專有的程式碼結構。
腳本無法執行時的備用方案
若無可用的 Node.js 18+ 或不允許執行命令：
- 讀取相關原始碼檔案，並依照 UML 模型參考手動撰寫模型 JSON。僅包含您在程式碼中看到的元素，並設定
source.file與source.line；對於不明確的項目，設定confidence: "inferred"。 - 將
templates/viewer.html複製到使用者想要圖表的位置（例如class-diagram.html）。 - 在副本中，將
<script type="application/json" id="pca-data">null</script>中的文字null替換為{"model": <您的模型>, "overlay": null, "meta": {"title": "<專案名稱>"}}，並在 JSON 內將<寫為<。 - 或者，告知使用者開啟
templates/viewer.html並將model.json拖放到頁面上。
如此一來，瀏覽器中的佈局、互動與匯出功能將與產生的圖表完全相同；僅缺少自動提取、變更偵測與驗證報告。請清楚說明模型是手動撰寫的。
其他命令
node scripts/class-architect.js analyze "/abs/repo" # 模型 + 報告，不含 HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor
參考檔案（僅在需要時閱讀）
- references/CLI.md - 所有命令、選項、輸出與結束代碼。
- references/INTERACTIVE-DIAGRAM.md - 使用者在圖表中可進行的操作與鍵盤快速鍵。
- references/RELATIONSHIPS.md - 每種關係類型與多重性的判斷依據、證據與信心程度。
- references/LANGUAGES.md - 支援的語言、框架與 ORM，以及從中提取的內容。
- references/CONFIGURATION.md -
class-architect.config.json、外部實體、閾值、文件備註。 - references/UML-MODEL.md - 模型格式（用於備用方案或其他工具）。
- references/LIMITATIONS.md - 已知的限制，應在相關時提及。