簡介Claude Code 的完整源碼以 zip 壓縮包形式提供適合希望深入理解 AI 編程助手實現(xiàn)原理的開發(fā)者、研究者以及正在進階 TypeScript 工程化的學(xué)員參考。資源共包含 1903 個文件主體為 1332 個 ts 文件與 552 個 tsx 文件另有少量 js 腳本和 md 文檔壓縮后體積約 9.43MB便于快速下載和本地閱讀。源碼在結(jié)構(gòu)上嚴格遵循模塊化與面向?qū)ο笤O(shè)計核心算法、數(shù)據(jù)處理邏輯與工具函數(shù)拆分清晰并通過大量注釋、API 文檔和測試用例保證可讀性與可維護性。與此同時項目依托 Git 管理代碼變更開發(fā)者指南和用戶手冊等材料也為后續(xù)二次開發(fā)提供了明確指引。目前已有 289 人學(xué)習(xí)下載適合作為學(xué)習(xí)大型開源項目架構(gòu)、代碼組織方式和工程實踐的學(xué)習(xí)樣本。1. Claude Code源碼這不是又一個AI殼子而是一套端到端的coding agent工程先說個反直覺的結(jié)論Claude Code在終端里跑起來只是命令行工具但真正拉開差距的是它那套滲透到源碼層面的代號為“harness”的調(diào)度機制。很多人以為裝個npm包就要排隊等Claude的API實際用下來你會發(fā)現(xiàn)它能聽懂你在編輯器里選中了哪一段代碼能在你翻車的時候自動做unit test循環(huán)修復(fù)這才是源碼級工程該有的樣子。這份源碼包適合誰兩類人最賺一是被各種GUI套殼工具折磨過的前端和全棧開發(fā)者想從命令行拿到上下文感知的AI輔助二是想研究“agent循環(huán)”——也就是讓模型自己感知、計劃、執(zhí)行、驗證的工程師。你拿到的不只是代碼而是一整套能跑起來的agent框架。我的建議是別當(dāng)普通工具安裝直接去讀它的entry point和bash executor相關(guān)源碼比翻十篇博客都漲功力。以下內(nèi)容來自我對這套源碼實拆后的記錄從架構(gòu)到部署、從參數(shù)到避坑全部是實操踩過的路徑。項目本體是基于TypeScript的harness實現(xiàn)下載源碼包后按下面的步驟走十分鐘內(nèi)能跑起來之后慢慢拆。2. 拆源碼先看骨架從CLI入口到agent循環(huán)的調(diào)用鏈2.1 頂層目錄一眼認出這條鏈路里誰在干什么Claude Code的源碼工程解壓后第一件事不是跑npm install而是先把目錄結(jié)構(gòu)摸了。它的核心分四塊cli/面向用戶的所有命令入口也就是你在終端里輸入的claude命令對應(yīng)的邏輯。harness/agent循環(huán)的核心負責(zé)把模型輸出轉(zhuǎn)成行動。包括plan、exec、observation三個環(huán)節(jié)的銜接。integrations/和外部工具通信的適配層比如編輯器插件VSCode、Git、終端命令執(zhí)行。tools/模型允許調(diào)用的工具集合比如讀文件、寫文件、執(zhí)行bash命令、搜索代碼。還有一個容易被忽略的bash-server/目錄這是專門在隔離環(huán)境里執(zhí)行shell命令用的項目通過它規(guī)避注入風(fēng)險。這個設(shè)計直接關(guān)系到后面避坑章節(jié)里“命令執(zhí)行權(quán)限”的問題先留個印象。2.2 入口文件拆解命令行參數(shù)是怎么變成agent動作的找到cli/entrypoint.js部分版本里叫cli/entrypoint.ts這是整個程序的起點。它不是簡單讀取參數(shù)然后調(diào)函數(shù)而是用了一個類事件循環(huán)的機制。核心邏輯偽碼如下// 簡化后的入口邏輯 async function main() { const options parseCommandLineArgs(); const conversation new Conversation(options); // 會話管理保留上下文 const runtime new HarnessRuntime({ model: options.model, maxTurns: options.maxTurns }); // 首次用戶輸入進來后進入agent循環(huán) const userTask options.prompt || await readStdin(); const result await runtime.run(userTask, { cwd: options.cwd, allowedTools: options.allowedTools, onStepComplete: (step) printStep(step, options.verbose), }); if (options.outputFormat json) { console.log(JSON.stringify(result, null, 2)); } }這里有幾個參數(shù)要說明allowedTools決定模型能調(diào)用哪些工具默認是全量允許但生產(chǎn)環(huán)境一般要白名單收斂。maxTurns是agent循環(huán)的最大輪數(shù)默認50我一般會調(diào)到80因為復(fù)雜任務(wù)經(jīng)常要“嘗試-失敗-再試”好幾輪。onStepComplete是回調(diào)鉤子你可以在這里做日志、狀態(tài)上報、甚至做自定義的門禁校驗。這個入口的設(shè)計思路是把命令行參數(shù)解析和真正的agent邏輯解耦。參數(shù)只是一堆配置真正打架的活全在HarnessRuntime里也就是下一節(jié)要拆的循環(huán)。2.3 HarnessRuntime調(diào)度細節(jié)工具調(diào)用的“解釋-執(zhí)行-驗證”三步真正的核心在harness/runtime.ts這里實現(xiàn)了agent循環(huán)。簡單來說它做三件事把模型返回的文本解釋成結(jié)構(gòu)化的工具調(diào)用執(zhí)行調(diào)用把結(jié)果反饋給模型。循環(huán)直到模型認為任務(wù)完成或觸發(fā)最大輪數(shù)為止。我摘一段核心的循環(huán)代碼這是理解全源碼的關(guān)鍵async run(userTask: string, ctx: RuntimeContext): PromiseRunResult { let messages: Message[] [{ role: user, content: userTask }]; for (let turn 0; turn ctx.maxTurns; turn) { const modelResponse await this.model.complete(messages, { tools: ctx.allowedTools, // 關(guān)鍵參數(shù)強制模型思考后再行動能大幅減少無效工具調(diào)用 thinking: { budget: 2000 }, }); messages.push(modelResponse.message); if (modelResponse.stopReason end_turn) { return { status: done, messages }; } // 解析模型輸出中的工具調(diào)用意圖 const toolUse parseToolUse(modelResponse.text); if (!toolUse) { // 模型回答了但沒有調(diào)用工具判定為無效回復(fù)給它一次糾錯機會 messages.push({ role: assistant, content: 你的回復(fù)沒有觸發(fā)工具調(diào)用請重新規(guī)劃并選擇一個工具。, }); continue; } const toolResult await this.executeTool(toolUse, ctx); messages.push({ role: user, content: toolResultContent(toolResult) }); } return { status: max_turns_exceeded, messages }; }這里值得在源碼里重點標(biāo)注的是thinking.budget這個參數(shù)。Claude Code能“想清楚再動手”靠的是讓模型在內(nèi)部生成綜合性的中間思維但如果預(yù)算給得太大每一輪耗時會明顯拉長給得太小復(fù)雜任務(wù)容易開局就翻車。經(jīng)驗值是2000到4000之間。executeTool內(nèi)部會根據(jù)工具名走不同分支bash類工具會送進bash-server獨立進程執(zhí)行文件工具直接在項目進程內(nèi)操作。這個隔離設(shè)計是安全底線源碼改了這里就等于改了安全模型不建議動。3. 把源碼跑起來從零到能獨立改代碼的最小可運行路徑3.1 環(huán)境準備與依賴安裝源碼是TypeScript工程跑起來需要Node.js環(huán)境。我這邊測試用的是Node 20npm 10。版本太老的Node會在編譯依賴時直接報錯建議線上跑之前先node -v確認。# 1. 安裝依賴最好用pnpmnpm有時候會卡在postinstall腳本上 pnpm install # 2. 構(gòu)建所有包cli、harness、integrations一次全編譯 pnpm build # 3. 把命令行工具軟鏈到全局方便直接跑 npm link注意第一行如果報權(quán)限錯誤檢查npm源是不是被修改過企業(yè)內(nèi)部源經(jīng)常缺包切回官方源再試一次。pnpm build在這份源碼里不會只編譯一個包而是按依賴順序構(gòu)建全部子包所以輸出比較長看到多個built提示就是成功。3.2 認證配置拿到會話密鑰并設(shè)置模型參數(shù)Claude Code依賴Anthropic的API但這里的認證方式不是直接把API Key寫在配置里而是走一個登錄會話機制。跑claude命令會提示你去瀏覽器里完成授權(quán)完成后密鑰會存在本地的配置目錄里。# 初始化配置按提示完成登錄 claude # 如果你想指定模型和開關(guān)用下面的參數(shù)組合 claude --model claude-3-7-sonnet-latest --max-turns 80--model參數(shù)要注意不同版本源碼支持的模型標(biāo)識符不完全一樣如果跑--help看不到你想要的模型去model-registry相關(guān)源碼里查一份常量列表別憑記憶猜。--max-turns上面提過控制單次對話最大循環(huán)輪數(shù)默認50對大多數(shù)任務(wù)夠用但你讓它一口氣修20個編譯錯誤的話50輪確實會不夠。還有一個非交互模式適合在CI里跑# 非交互模式直接給任務(wù)輸出結(jié)果后退出 claude -p 讀一下 src/main.ts找出所有未處理的 Promise rejection 并修復(fù) --output-format json這個模式配合--output-format json非常實用你可以在CI腳本里拿到它修改過的文件列表和狀態(tài)。JSON結(jié)構(gòu)里messages就是完整對話記錄fileEdits是實際改動文件的路徑集合自己寫校驗?zāi)_本時直接用這兩個字段。3.3 自定義工具擴展加一個“獲取PR變更列表”的工具源碼的價值在擴展性。官方?jīng)]提供“Github PR信息拉取”能力但通過寫一個工具函數(shù)并注冊進去模型就能學(xué)會用它。工具注冊的代碼在tools/registry.ts里有明確的位置直接加進數(shù)組即可。// 在 tools/registry.ts 里追加這個工具 const githubTools [ { name: get_pr_changes, description: 獲取指定PR的變更文件列表和每處變更的diff, input_schema: { type: object, properties: { prNumber: { type: number, description: PR編號比如 342 }, repo: { type: string, description: 倉庫名如 owner/repo }, }, required: [prNumber, repo], }, async execute({ prNumber, repo }: { prNumber: number; repo: string }) { const response await fetch(https://api.github.com/repos/${repo}/pulls/${prNumber}/files, { headers: { Accept: application/vnd.github.v3.diff }, }); return await response.text(); }, }, ];注冊以后模型在收到“分析PR #342 的改動影響”這類請求時就會自主選擇調(diào)用這個工具。input_schema寫不好會導(dǎo)致模型頻繁傳錯參數(shù)——兩個最典型的錯誤是required數(shù)組里漏字段、或者字段描述太模糊。描述要具體到“倉庫名格式如 owner/repo不要帶 git 前綴”這種程度模型才會正確生成參數(shù)。這種改造方式不用動harness主循環(huán)只要工具上報的返回內(nèi)容足夠簡單直接模型理解成本低成功率就上去了。4. 四個必踩的坑配置、依賴和誤判哪個都能卡你半小時4.1 模型顯示“Not Available in Your Country”現(xiàn)象第一次跑claude登錄完成后控制臺直接打印一行note: claude code might not be available in your country. check supported countries然后退出。原因源碼里內(nèi)置了一組受支持的國家或地區(qū)代碼判斷依據(jù)是賬戶資料里的地區(qū)設(shè)置。這一步在網(wǎng)絡(luò)正常狀態(tài)下也會被觸發(fā)確實是賬戶歸屬地判斷不是終端環(huán)境能繞過的。解決確認賬戶歸屬地。如果你長期使用不支持地區(qū)的賬戶看下onboarding相關(guān)源碼里面對supportedCountries有明確的常量定義。檢查你當(dāng)前用來登錄的賬戶是否匹配。和網(wǎng)絡(luò)環(huán)境本身沒有關(guān)系不要試圖通過修改網(wǎng)絡(luò)出口來解決換個賬戶或修改賬戶地區(qū)設(shè)置是唯一通道。4.2pnpm install卡在 postinstall 不動現(xiàn)象依賴安裝時長時間停在anthropic-ai/claude-code: postinstall或esbuild相關(guān)腳本。原因這份源碼里 esbuild 的二進制包需要在安裝時下載對應(yīng)平臺的二進制文件如果當(dāng)前 npm 源不包含該包postinstall 腳本就會一直重試。國內(nèi)開發(fā)者常遇到的另一個情況是環(huán)境變量里配置了不兼容的代理導(dǎo)致下載請求被攔。解決先清掉代理環(huán)境變量再裝unset HTTP_PROXY HTTPS_PROXY ALL_PROXY pnpm install --no-frozen-lockfile注意不要開任何系統(tǒng)級代理工具讓 esbuild 直接走默認通道下載成功率最高。如果換源務(wù)必選一個 esbuild 二進制完整的鏡像源否則即使安裝成功啟動時也會報esbuild: command not found。4.3 修改代碼后pnpm build不重新編譯現(xiàn)象你改了cli/下的某個源文件重新跑claude命令發(fā)現(xiàn)改動不生效。原因npm link軟鏈到的目錄不是你當(dāng)前源碼目錄而是官方包的全局安裝目錄。解決用pnpm build之后直接跑源碼目錄的入口文件不要依賴軟鏈node cli/entrypoint.js --model claude-3-7-sonnet-latest如果你想繼續(xù)用claude命令必須確認軟鏈指向which claude ls -l $(which claude) # 看指向是否是你當(dāng)前工作目錄軟鏈指向錯了就重新npm link指向?qū)α说€是舊代碼那就是 build 輸出目錄緩存問題執(zhí)行rm -rf dist pnpm build強制全量構(gòu)建。4.4 工具調(diào)用陷入死循環(huán)同一段代碼反復(fù)改現(xiàn)象讓Claude Code修復(fù)一個lint錯誤結(jié)果它改一個文件跑一次lint報錯再改再跑。有時候同一個位置改了七八次都沒法收斂。原因這類問題大概率是模型在“修復(fù)”和“驗證”之間缺少足夠的信息傳遞——它看不到lint的完整輸出或者工具返回里只有摘要沒有具體行列號。循環(huán)結(jié)構(gòu)本身沒問題問題在信息密度。解決檢查工具返回內(nèi)容是否被截斷。在harness/runtime.ts里找toolResultContent這個函數(shù)看它對長輸出的截斷策略。如果你被截斷到只有前500字符模型當(dāng)然只能盲猜。把截斷閾值調(diào)高并強制保留錯誤出現(xiàn)的上下文尾部function toolResultContent(result: ToolResult): string { const fullOutput result.text; // 默認只保留頭部修改為保留頭部和尾部各1000字符 if (fullOutput.length 2000) { return ${fullOutput.slice(0, 1000)}\n...中部省略...\n${fullOutput.slice(-1000)}; } return fullOutput; }這樣改完后模型能同時看到附件的錯誤開頭和收尾信息對“哪里錯了”的判斷會準確很多。5. 讓agent更懂你的項目代碼庫上下文工程的三個有效手段5.1 用CLAUDE.md喂項目經(jīng)驗效果比任何prompt都持久Claude Code源碼里對CLAUDE.md有天然的支持每個目錄下如果有這個文件它的內(nèi)容會被自動注入到全局上下文中。這比你在對話開頭粘貼一大段說明靠譜得多因為每次新對話它都會自動加載。我在項目根目錄放的內(nèi)容一般分三塊項目技術(shù)棧清單什么語言、什么框架、包管理器是什么常見操作約定測試命令、lint命令、構(gòu)建命令歷史踩坑記錄這個項目最容易出錯的地方在哪以及為什么# CLAUDE.md - 項目指引 ## 技術(shù)棧 - 后端Node.js 20 TypeScript - 前端React 18 Vite - 包管理器pnpm ## 常用命令 - 本地開發(fā)pnpm dev - 跑測試pnpm test -- --runInBand - 構(gòu)建pnpm build pnpm start ## 容易踩坑的點 1. src/db/migrations 下的文件不要手動改用 pnpm migration:generate 生成 2. 修改 API 路由后需要同時更新 openapi.yaml否則 CI 會掛 3. 不要直接在 main 分支上跑 --force先切 feature 分支模型在遇到相關(guān)任務(wù)時會直接從這些條目里找依據(jù)。比如你讓它改數(shù)據(jù)庫相關(guān)代碼它就自己去讀migrations目錄并意識到“這個項目對遷移文件有特殊約定”。這種上下文注入方式比你在對話里反復(fù)強調(diào)要穩(wěn)定很多而且可以隨項目演進持續(xù)更新。5.2 自定義slash command把高頻操作壓縮成一條命令源碼支持在.claude/commands/目錄下創(chuàng)建自定義命令格式是markdown文件文件名就是命令名。比如我寫了一個fix命令用來一鍵跑“跑測試-修編譯錯誤-檢查lint”的triple loop--- description: 修復(fù)失敗的測試或編譯錯誤 argument-hint: 可選的失敗范圍描述如只修復(fù)utils模塊 --- 我會按順序執(zhí)行以下操作 1. 讀取 package.json 中的 test 腳本定義 2. 運行 pnpm test 并記錄失敗用例 3. 針對失敗用例逐個定位源碼問題 4. 修復(fù)后重新運行測試驗證 用戶輸入的范圍限制{{argument_hint}} 如果沒有明確范圍默認處理全部失敗用例。{{argument_hint}}是占位符輸入claude /fix 只處理auth模塊時這里會被替換成“只處理auth模塊”。這比每次手動敲“請幫我跑一下測試如果掛了就修修完再跑”高效十倍。創(chuàng)建完重啟claude會話即可在交互界面里看到新命令。這個方法適合把團隊流程固化成模板讓模型遵守統(tǒng)一的代碼路徑。5.3 利用會話恢復(fù)把長任務(wù)拆成多段跑源碼里有個容易被忽略但很實用的能力會話持久化。在交互式進程退出后對話記錄會保留在磁盤上。下次運行帶--resume或--continue參數(shù)可以接上一次的上下文繼續(xù)干。claude --continue -- 繼續(xù)處理剛才的編譯錯誤還剩3個這意味著你可以把一個大任務(wù)拆給不同時段的它去干。比如上午讓它掃描代碼庫并列出需要重構(gòu)的模塊下午回來直接--continue讓它基于上午的分析結(jié)果開始改代碼上下文沒斷。這在處理大型代碼庫時特別有用不用一次性把上下文撐爆。6. 調(diào)出“全程廣播”模式用verbose日志和dry-run把黑盒變成白盒--verbose參數(shù)是Claude Code里最被低估的調(diào)試工具。默認輸出只是簡明結(jié)果但帶上這個參數(shù)以后harness會把每一步模型思考、工具選擇、具體執(zhí)行參數(shù)都打印出來。我第一次打開的時候才真正搞懂“為什么它要改這個文件”——原來是在前一步的錯誤日志里猜了個根源而它選工具的依據(jù)全在這一層日志里。我推薦的標(biāo)準調(diào)試流程是這樣# 1. 先用 dry-run 看計劃如果需要 claude -p 重構(gòu) src/utils/date.ts 中的日期格式化函數(shù) --dry-run # 2. 正式跑但開 verbose 記錄完整決策鏈 claude -p 重構(gòu) src/utils/date.ts 中的日期格式化函數(shù) --verbose 21 | tee run.log--dry-run如果源碼版本支持會在不真正改動文件的情況下展示它打算執(zhí)行哪些操作。這對評估“改動范圍是否符合預(yù)期”非常有用——尤其是在批量重構(gòu)場景下先看行動計劃確認無誤再放行改真實文件。tee run.log是Linux/macOS下的標(biāo)準操作Windows PowerShell 用戶換成| Tee-Object run.log。verbose日志里最值得盯的三個模式第一Tool Use段看模型調(diào)了什么工具、傳了什么參數(shù)。如果它頻繁調(diào)用Read而不是Grep說明代碼庫太大模型在靠讀文件碰運氣找內(nèi)容性能會明顯變慢。這時候最好在CLAUDE.md里明示代碼結(jié)構(gòu)。第二Observation段看工具返回結(jié)果里模型截取了什么。如果模型總是忽略報錯里的文件路徑那屬于上下文管理問題調(diào)小返回截斷閾值不要調(diào)大逼它用Grep定位。第三Thinking段中的“推理預(yù)算用量”?？吹?“thinking budget exhausted” 字樣說明模型在復(fù)雜任務(wù)中思考超預(yù)算被截斷這時候把配置里的thinking.budget參數(shù)調(diào)大比改prompt更直接。從這之后我每次讓它干涉及多文件的活都會先把--verbose日志跑一份存下來干完再對一下它實際做了哪些改動。遇到意外改動直接回看日志里的決策段就能定位到是哪一步推理跑偏了。這個習(xí)慣幫我省下了解謎的時間也讓我敢把更復(fù)雜的活交給它。希望這套源碼拆解和調(diào)試流程能幫到你上手之后記得改一版你自己的CLAUDE.md——我保證這個動作比任何參數(shù)調(diào)優(yōu)都值。本文還有配套的精品資源點擊獲取