codesight：用 AST 編譯一份給 AI 讀的專案說明書

每一次新對話都要重新自我介紹的代價

問題本身很具體。你開一個新的 Claude Code session，第一句話還沒打完，助理已經在讀 package.json、tsconfig、路由目錄和 schema 檔，試圖拼出這個專案長什麼樣。這幾千個 token 花掉的不是錢，是注意力預算：真正要解的 bug 還沒進到上下文，視窗已經被架構猜測佔走。codesight 的定位就是把這段「自我介紹」預先編譯好，讓 AI 從一份現成的索引開始，而不是從零開始翻檔案。

它鎖定的使用者是每天在同一個 repo 裡工作、而且已經把 AI 助理接進日常流程的人。README 列出的整合對象包含 Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Windsurf、Cline、Aider，以及任何讀得懂 markdown 的工具。這個清單的意義是：codesight 不綁定單一 IDE，輸出是純文字檔，所以切換工具時不必重做。

要注意的是它處理的是「專案結構」這一層的上下文，不是程式邏輯本身。README 描述 wiki 是「a narrative layer on top of data your codebase already contains」，敘事層疊在既有資料上。如果你的困擾是助理不懂某段演算法的意圖，codesight 幫不上忙。

從 AST 到 wiki：資料怎麼流動

執行 npx codesight 之後，工具會掃描專案並推斷框架、路由、資料模型與中介層。TypeScript 專案走完整的 AST 解析，其餘語言則用 README 所稱的 regex 偵測，覆蓋同一批 30 多個框架與 14 個 ORM parser。這是一個明確的取捨：AST 精準但需要語言層的支援，regex 便宜但容易誤判，README 自己用了「battle-tested regex detection」這個說法。

--wiki 產出的不是單一檔案，而是一組文章。根據 README 的目錄範例，.codesight/wiki/ 底下會有 index.md 作為文章目錄，約 200 tokens；overview.md 描述架構與高影響力檔案，約 500 tokens；其餘像 auth.md、payments.md、database.md、users.md、ui.md 則按領域切分；log.md 是 append-only 的操作記錄。這個切法是關鍵：AI 不需要載入整份 5K token 的 context map，只要挑一篇文章讀。

README 給的對照表把差距寫得很直接。問「auth 怎麼運作」，沒有 wiki 時助理要讀八個以上的檔案，約 12K tokens；有 wiki 時讀 auth.md，約 300 tokens。問「有哪些 model」，前者約 5K，後者讀 database.md 約 400。新 session 啟動從約 5K 降到讀 index.md 的約 200。這些數字來自專案文件，我沒有獨立驗證，但數字的來源與切分方式在邏輯上是一致的。

另一條路徑是 --mode knowledge。它掃描 .md 檔而不是原始碼，輸出 .codesight/KNOWLEDGE.md，把 ADR、會議紀錄、決策筆記整理成決策清單與待解問題。README 的範例輸出顯示它會標示「47 notes · 12 decisions · 8 open questions」並附上日期區間，決策以條列呈現。這條路徑處理的是程式碼以外的上下文，跟 --wiki 是兩件事。

安裝與實際會用到的旗標

安裝就是一行：npx codesight，在專案根目錄執行，README 說不需要設定、不需要 API key。其餘功能靠旗標展開：

npx codesight --wiki 產生 .codesight/wiki/ 知識庫。 npx codesight --init 產生 CLAUDE.md、.cursorrules、codex.md、AGENTS.md。 npx codesight --mcp 以 MCP server 形式啟動，提供 14 個工具。 npx codesight --blast src/lib/db.ts 顯示某個檔案的影響半徑。 npx codesight --profile claude-code 產生針對特定工具最佳化的設定。 npx codesight --benchmark 顯示 token 節省的明細。 npx codesight --open 在瀏覽器開啟互動式 HTML 報告。 npx codesight --native-ast 選擇性啟用更多語言的 AST 外掛，README 指向 docs/wasm-plugins.md。 npx codesight --mode knowledge 或 npx codesight --mode knowledge ~/vault 掃描筆記目錄。

wiki 的維護靠 --watch 在開發時持續更新，或 --hook 在每次 commit 時重新產生。MCP 路徑另外提供三個 wiki 工具：codesight_get_wiki_index 取得目錄，codesight_get_wiki_article 依名稱讀取單篇文章，codesight_lint_wiki 檢查孤兒文章、缺少的交叉連結與過期內容。lint 工具的存在說明一件事：這份 wiki 會腐化，而且專案自己承認需要檢查機制。

環境需求是 Node.js 18 以上，零依賴，MIT 授權。

非 TypeScript 專案要面對的推斷誤差

README 把語言支援寫成一份長清單：TypeScript、JavaScript、Python、Go、Ruby、Elixir、Java、Kotlin、Rust、PHP、Dart、Swift、C#，以及 BrightScript/BrighterScript。但緊接著一句話限縮了範圍：TypeScript 專案獲得完整 AST 精準度，其他語言用 regex 偵測。

這個區分不是行銷話術，是架構事實。AST 知道某個函式是不是真的被註冊成路由，regex 只知道某一行長得像路由註冊。動態組出來的路由、字串拼接的 ORM 查詢、透過變數間接呼叫的中介層，regex 都可能漏掉或誤認。專案提供 --native-ast 作為補救，但它是 opt-in，而且指向一份 wasm-plugins 文件，意味著這條路需要額外安裝與設定，不是預設體驗。

所以如果你維護的是 Go 或 Rust 服務，codesight 產出的 wiki 文章值得當草稿看，不該當成事實陳述直接餵給助理。錯的架構描述比沒有描述更糟，因為助理會照著錯的模型推理。

另一個限制是 wiki 的時效性。它是一份快照，commit 進 git 之後就固定了。--watch 和 --hook 解決的是更新流程，不是正確性。如果團隊有人改了路由卻沒重跑，index.md 和 auth.md 就會開始說謊，而 codesight_lint_wiki 只能抓到孤兒文章與缺少連結這類結構問題，抓不到語意過期。

跟直接把檔案餵給助理有什麼不同

最接近的替代方案是自己寫一份 CLAUDE.md 或 AGENTS.md，手動維護專案說明。差別在維護方式：手寫文件靠人記得更新，codesight 靠指令重新產生，而且 --hook 可以掛在 commit 上。手寫文件的優勢是能寫出 regex 抓不到的意圖與歷史脈絡，codesight 的優勢是不會忘記某個新模組。

另一條路是讓 AI 助理自己探索，也就是現在的預設行為。這在小型專案可行，在有多個子系統的 repo 裡就是每次對話重付一次學費。codesight 的 wiki 切分方式讓助理按需讀取，而不是一次載入全圖，這個設計比單純產生一份大文件更省。

README 提到 wiki 概念受 Karpathy 的 LLM wiki pattern 啟發，但強調一個差異：codesight 的 wiki 是從 AST 編譯出來的，不是 LLM 寫的，零 API 呼叫。這個差異在成本與可重現性上成立，在敘事品質上則是劣勢，因為樣板產生的文章不會告訴你為什麼當初選 Polar.sh 而不是 Stripe Connect。那類內容要靠 --mode knowledge 從你的筆記裡撈。

授權、維護與升級的實際成本

授權是 MIT，這對內部工具與商業專案都是低摩擦的選擇，但授權條款的最終解釋仍應由法務確認，本文不提供法律意見。

維護成本主要落在兩處。第一是 .codesight/wiki/ 進 git 之後的 diff 噪音：每次重跑都可能改動多個 markdown 檔，review 時要決定這些變更要不要看。第二是版本跟進，專案從 v1.6.2 的 wiki 功能走到 v1.9.3 的 knowledge mode，功能線在動，但這次取得的資料沒有列出任何 release 記錄，所以無法從版本節奏判斷穩定性。README 提到 149 個測試與 25 個以上的 OSS 專案測試經驗，這些是專案自述，我沒有重跑。

零依賴是實質優點：不必擔心傳遞依賴的漏洞或版本衝突，Node.js 18 以上的環境就能跑。相對地，任何解析能力的擴充都得等上游更新，你無法自己換掉某個 parser。

升級前值得確認的是 .codesight/ 目錄的內容有沒有被 CI 或 hook 依賴。一旦 --hook 掛上 commit，工具行為的改變就會直接影響提交流程。

編輯結論

如果你主要寫 TypeScript，而且每天在同一個 repo 裡反覆對 Claude Code 或 Cursor 解釋架構，codesight 值得先跑一次 npx codesight --wiki 看它把 auth、database、payments 拆成什麼樣子，再決定要不要把 .codesight/wiki/ 提交進 git。若你的專案以 Go、Rust 或 Java 為主，請先確認 regex 偵測在你手上的框架組合裡認得出路由與 ORM，因為 README 明說只有 TypeScript 走完整 AST，其餘語言靠 regex。判斷的門檻不在功能清單，而在 index.md 是否真的涵蓋你專案裡最難解釋的那幾個模組。

官方來源

1. Houseofmvps/codesight on GitHub
2. Issues
3. License: MIT
4. Project website
5. README