Windy3f3f3f3f/claude-code-from-scratch

解決的問題

本專案提供一個最小化、教育性的程式碼代理實作，旨在幫助開發者理解複雜AI程式碼助手（如Claude Code）的內部運作原理，而無需瀏覽數十萬行生產程式碼。它彌補了簡單LLM聊天與能管理檔案、執行shell命令並維持長期記憶的完全自主代理之間的差距。

如何運作

本專案實作了一個核心「代理迴圈」，用於管理大型語言模型（LLM）與一組工具之間的互動。支援TypeScript與Python兩種實作。系統透過向LLM（支援Anthropic與OpenAI相容後端）傳送提示，接收工具呼叫，於本地執行這些工具，並將結果反饋回迴圈，直到任務完成為止。

關鍵架構元件包括：

• 工具系統：13個內建工具，用於檔案編輯、搜尋與shell執行，具備mtime保護機制，防止覆蓋變更。
• 上下文管理：四層壓縮管道（預算截斷、過時片段剔除、微壓縮、自動壓縮），以維持令牌使用效率。
• 記憶系統：使用側查詢（side-queries）實作語意回憶，以檢索相關記憶。
• 技能與代理：支援從目錄載入自訂技能，並為複雜任務產生子代理的系統。
• MCP整合：透過stdio上的JSON-RPC支援Model Context Protocol（MCP），連接外部工具伺服器。

適合對象

希望遵循逐步教程，從基礎迴圈逐步進階到多代理編排與語意記憶等高階功能，學習如何建構自主AI代理（特別是程式碼代理）的開發者。

主要亮點

• 分步教程：13章逐步開發，每章均包含可執行的程式碼快照。
• 零密鑰執行：可使用本地模擬執行每章程式碼，無需API密鑰即可學習。
• 雙語言支援：TypeScript與Python均提供完整實作。
• 高階代理功能：包含平行工具執行、串流輸出與宣告式權限系統（用於安全）。
• 預算控制：內建美元成本與回合數限制，防止API費用失控。