OpenSpec 項目實戰（二） | 工具註冊中心：從骨架到模塊化架構

第一期做完後，shuge AI Toolbox 得一個空骨架：首頁顯示項目名，404 正常跳轉，但 catalog.ts 嘅 tools 數組係空嘅，路由寫死兩條規則，首頁永遠顯示「暫無工具」。今期要做嘅係 工具註冊中心（change name: tool-registry）。一句話需求：catalog 驅動路由生成、Layout 共享佈局、首頁按分類展示工具、未實現嘅工具顯示佔位頁。

完成之後，後續加工具只需兩步：喺 catalog.ts 註冊，再喺 modules/ 下實現組件。唔使改路由配置、改首頁佈局、改任何已有代碼。完整流程同第一期一致，都係 5 步：Explore → Propose → Apply → Verify → Archive。

今期嘅 Explore 階段雖然只係一輪討論，但涉及多個關鍵決策點，包括 ToolManifest 接口使唔使加 stage 字段、分類策略用動詞定係功能名、路由結構係 catalog 驅動定係靜態配置、Layout 係咪共享，同埋 佔位頁邏輯。AI 逐條分析後得出結論：加上 stage 字段，分類用文本處理/數據轉換呢類功能名，路由由 catalog 動態生成，Layout 共享兼包埋 Home，佔位頁唔加反饋連結。

相比第一期嘅 Explore 只係決定用 React 定 Vue，今期嘅 Explore 雖然輪次少咗，但決策點多咗一倍。作者話，如果唔提前諗清楚，propose 階段 AI 會自行做主，而呢啲架構級決策會影響後續每個工具。所以 Explore 係核心防線，唔可以 skip。

Explore 結束後執行 /opsx:propose，AI 按照 with-review schema 嘅依賴順序生成 5 個工件：proposal.md（點解要註冊中心）、design.md</highlightinline>（核心設計決策）、specs/</highlightinline>（三個 capability）、review.md（五維度審查）、tasks.md（8 個任務組，38 個子任務）。

人工檢查 review.md 同 tasks.md 只需要 1-2 分鐘，確認冇 TBD 或 TODO 佔位符。5 個工件完整記錄咗「點解做」、「做咩」、「點樣做」、「做得好唔好」同埋「按咩順序做」。

export interface ToolManifest {
 id: string;
 name: string;
 route: string;
 category: string;
 description: string;
 stage: 'active' | 'beta' | 'planned';
}

const tools: ToolManifest[] = [
 { id: 'text-summary', name: '文本摘要', route: '/tools/text-summary', category: '文本處理', description: '快速提取長文本嘅核心觀點', stage: 'active' },
 { id: 'json-formatter', name: 'JSON 格式化', route: '/tools/json-formatter', category: '數據轉換', description: '美化 JSON 數據結構', stage: 'active' },
 // ... code-explainer(beta), image-generator(planned), markdown-table(planned)
];

export function getTools(): ToolManifest[] { return tools; }
export function getToolById(id: string): ToolManifest | undefined { return tools.find((t) => t.id === id); }
export function getToolsByCategory(category: string): ToolManifest[] { return tools.filter((t) => t.category === category); }

Apply 階段執行 /opsx:apply tool-registry，AI 讀取所有工件後按 tasks.md 順序實現。最後新增/修改咗 16 個文件，包括 6 個測試文件（跟 TDD 流程：先寫失敗測試，再寫實現代碼）。關鍵實現包括：catalog.ts 擴展接口同填充數據、router/index.tsx 改為 catalog 驅動動態路由、Layout.tsx + TopNav.tsx 共享佈局、Home.tsx 按分類展示工具卡片、PlaceholderPage.tsx 顯示 planned 工具佔位頁，同埋 validate-catalog.ts 構建時校驗腳本。

呢期首次啟用 Verify 步驟。第一次執行 /opsx:verify 就發現咗一個 CRITICAL 問題（task 7.5 git commit 未做）同 3 處編譯錯誤（import 錯誤、vite.config.ts 類型問題、tsconfig.app.json 嘅 baseUrl 廢棄）。修復後第二次 verify 全部通過，npm run build 成功，瀏覽器驗證首頁分類卡片同佔位頁行為正確。

今期嘅 tool-registry 屬於架構級變更，涉及接口設計、路由重構、佈局組件、首頁改造，複雜度比第一期嘅腳手架變更高好多。但用 OpenSpec 管理嘅核心收益唔係「AI 幫你寫代碼」，而係 決策可追溯。5 個工件將成個變更過程完整記錄，三個月後返嚟睇每個設計決策都有理由。

一個有趣嘅觀察：第二期嘅 Explore 輪次反而比第一期少（2 輪 vs 2-3 輪），但決策點更多。原因係作者喺 explore 前已經諗清需求，一輪提問就覆蓋所有決策點。所以 Explore 階段唔係靠輪數多，而係靠問題到位。

tasks 嘅粒度喺更高複雜度下仍然達標，因為每個改動有明確邊界：catalog 擴展係 catalog 嘅事，路由重構係路由嘅事，Layout 獨立，首頁改造只涉及 Home.tsx。呢種狀態嚟自 Explore 同 design 階段劃清咗邊界。