sync-docs

sync-docs 技能是一款專為軟體工程師設計的專業自動化工具，旨在維護高品質且即時更新的專案文件。它作為一個編排引擎，分析原始程式碼與專案文件之間的關聯，確保 README、變更日誌與技術文件能反映程式碼庫的真實狀態。透過整合 Git 並利用 repo-map 等靜態分析工具，它能識別在快速開發週期中經常出現的差異，例如被移除的函式匯出、教學中過時的程式碼片段或匯入路徑的變更。此技能適用於 Pull Request 審核前、版本發佈準備階段或重大重構後，以確保專案產出物中不會堆積技術債。

• 自動根據變更檔案及如 README.md、CHANGELOG.md 等檔案模式發現相關文件。

• 透過比較 package.json 中的專案元資料與文件版本進行版本驗證。

• 匯出項目分析，用以偵測出現在文件中但實際上已不存在於實作中的程式碼符號，有效找出過時的參考資訊。

• 變更日誌維護，透過掃描「Unreleased」區段並驗證提交訊息與紀錄之變更是否對齊。

• 智慧型備援機制，若未安裝如 ast-grep 等進階 AST 工具，則自動改用基於正規表示式 (regex) 的偵測方式。

• 結構化的結果回報，在不進行未經授權之直接修改的前提下提供可操作的回饋，讓開發者在套用變更前能先進行檢閱。

• 使用者應透過以下語法調用此技能：sync-docs [report|apply] [--scope=all|recent|before-pr] [--include-undocumented]。

• 預設範圍集中在自上次提交至 main 分支以來的變更，這針對開發期間的快速檢查進行了優化。

• --include-undocumented 旗標對於發掘缺乏技術文件說明的公開 API 介面非常實用。

• 雖然工具提供了 apply 模式，但它是在安全優先的架構下運作，由編排器負責管理最終的變更套用。

• 限制：若能初始化 repo-map.json，將能顯著增強符號偵測的有效性；在較大型且複雜的儲存庫中，系統可能會建議使用者安裝 ast-grep 以達到最高準確度。