symbols

Symbols 技能是一個為大型軟體專案設計的高階代碼庫導航引擎。它使 AI 代理能夠查詢符號（如函數、組件、Hook、服務與類型），而無需將整個檔案載入到上下文視窗中。透過利用按領域與架構層進行分塊的預生成符號圖，此技能提供精確的上下文，能顯著提升 Token 使用效率。它主要適用於管理複雜代碼庫的開發者與 AI 代理，在這些情境下，載入完整檔案內容往往是多餘且昂貴的。

• 智慧符號查詢：立即透過名稱、類型、路徑或架構標籤定位特定的代碼成品。
• 架構層感知：支援依專案特定的層級（如路由器、服務、儲存庫或 Schema）進行過濾，讓您僅載入與當前任務相關的代碼。
• 領域專屬分塊：將大型儲存庫整理為可管理的領域（例如 UI、Web、API、Shared），以最佳化上下文視窗的使用。
• 降低 Token 消耗：與標準的完整檔案載入相比，可達成 60-95% 的 Token 使用量減少；透過後端專屬的層級拆分，能額外提供高達 80% 的效率提升。
• 無縫整合：配合配置導向的提取腳本（TypeScript/Python）運作，以維護專案結構的最新事實來源。

使用注意事項與實務建議：

• 每當儲存庫發生重大結構變動時，請務必執行提取與標記腳本 (extract_symbols_*.py, add_layer_tags.py)。
• 當您需要在實作新功能前理解現有的架構模式，或在偵錯跨領域服務互動時，請使用符號工具。
• 此技能僅用於唯讀的導航與分析；當您需要特定函數的實際實作細節時，它無法取代直接讀取檔案的 Read 工具。
• 預期輸入通常為針對符號名稱或路徑過濾器的查詢字串；輸出則提供簡潔的符號簽章、行號與 docstring 摘要。
• 將查詢限制在特定的架構層（例如僅載入 'services'），以最大化大型後端專案中的效能。