1. 從零構(gòu)建 Code Agent 的真實(shí)起點(diǎn)為什么“能跑”和“能穩(wěn)”是兩回事很多人第一次接觸 Claude Code 這類工具時(shí)最直觀的感受是“它怎么什么都能干”。但當(dāng)你真正動手從零構(gòu)建一個(gè) Code Agent才會發(fā)現(xiàn)核心難點(diǎn)從來不是讓模型開口說話而是讓它穩(wěn)定地完成“讀文件、搜代碼、改代碼、跑命令”這一整套動作。我試過直接拿一個(gè)通用對話模型套上幾個(gè)工具函數(shù)就開跑結(jié)果前幾輪還挺像樣任務(wù)一復(fù)雜就開始胡言亂語——要么把文件路徑寫錯(cuò)要么在同一個(gè)報(bào)錯(cuò)上反復(fù)撞墻。這個(gè)場景下你需要的是一個(gè)可對話、可執(zhí)行工具、可追溯的本地 Code Agent。它至少要具備四個(gè)能力第一能理解自然語言需求并拆解成步驟第二能調(diào)用文件系統(tǒng)、搜索、終端等工具去倉庫里找證據(jù)第三能輸出可落地的補(bǔ)丁并安全執(zhí)行第四能在長對話中保持上下文不腐爛。而這一切的底座是模型調(diào)用通道的穩(wěn)定性。我選擇用 TaoToken 作為統(tǒng)一 Key 接入層原因很直接本地開發(fā) Agent 時(shí)最煩的就是在多個(gè)模型供應(yīng)商之間來回切換配置。TaoToken 提供統(tǒng)一的 API 入口兼容 OpenAI 風(fēng)格的 Function Calling 協(xié)議這意味著我的 Agent 主循環(huán)不需要為每個(gè)模型寫適配層。你可以在 https://taotoken.net/api 拿到兼容接口配合 https://taotoken.net/api-keys 生成的 Key 就能直接調(diào)用。這一章先不急著寫代碼而是把整個(gè)鏈路的骨架講清楚。一個(gè) Code Agent 的最小閉環(huán)包含五個(gè)模塊LLM 調(diào)用層、工具注冊中心、ReAct 主循環(huán)、上下文管理器、執(zhí)行器。LLM 調(diào)用層負(fù)責(zé)把消息和工具 Schema 發(fā)給模型工具注冊中心維護(hù)所有可調(diào)用工具的 JSON SchemaReAct 主循環(huán)負(fù)責(zé)“模型輸出 tool_calls → 執(zhí)行工具 → 回填結(jié)果 → 繼續(xù)推理”這個(gè)循環(huán)上下文管理器負(fù)責(zé)截?cái)?、壓縮、分層執(zhí)行器負(fù)責(zé)把模型生成的補(bǔ)丁安全落盤。很多教程一上來就讓你寫幾百行代碼但真正卡住新手的往往是環(huán)境配置和協(xié)議對齊。比如 Function Calling 要求模型返回結(jié)構(gòu)化的 tool_calls而不是自由文本。如果你用的是字符串解析那套 ReAct模型多說一句“好的我來幫你”就會導(dǎo)致正則匹配失敗。所以從第一天起我就建議你直接走 Function Calling 協(xié)議把“模型輸出”當(dāng)成結(jié)構(gòu)化數(shù)據(jù)來處理而不是當(dāng)成作文來批改。還有一個(gè)容易被忽略的點(diǎn)工具返回結(jié)果必須統(tǒng)一格式。如果 Read 工具返回純文本Grep 工具返回 JSON模型就得花額外精力去“理解”每個(gè)工具的輸出結(jié)構(gòu)。更好的做法是定義一個(gè)標(biāo)準(zhǔn)信封包含 status、data、text、stats 四個(gè)字段。模型看到 status 就知道成功還是失敗看到 data 就能直接取結(jié)構(gòu)化數(shù)據(jù)看到 text 就能拿到人類可讀的摘要。這個(gè)設(shè)計(jì)在后面做上下文壓縮時(shí)會省下大量精力。最后說說為什么強(qiáng)調(diào)“從零”。因?yàn)橹挥心阕约捍钜槐椴艜嬲斫?Claude Code 這類產(chǎn)品在工程上做對了什么。它不是模型更聰明而是工具邊界更清晰、調(diào)用協(xié)議更嚴(yán)格、上下文治理更精細(xì)。你把這些工程細(xì)節(jié)補(bǔ)齊哪怕用同一個(gè)模型Agent 的穩(wěn)定性也會有肉眼可見的提升。2. TaoToken 統(tǒng)一 Key 接入前置把模型調(diào)用通道先跑通在寫 Agent 主循環(huán)之前必須先把模型調(diào)用通道跑通。這一步看起來簡單但實(shí)際踩坑的人不少。TaoToken 的接入方式兼容 OpenAI 的 Chat Completions 接口所以你不需要引入額外的 SDK直接用 openai 這個(gè) Python 包就能調(diào)用。關(guān)鍵是把 base_url 指向 https://taotoken.net/api而不是默認(rèn)的 OpenAI 地址。先安裝依賴。我建議用虛擬環(huán)境避免和系統(tǒng)里的包沖突python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install openai httpx然后配置環(huán)境變量。不要把 Key 硬編碼在代碼里這是基本的安全習(xí)慣export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Windows PowerShell換成$env:TAOTOKEN_API_KEY你的Key。配置完成后寫一個(gè)最小調(diào)用腳本驗(yàn)證通道是否通暢import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 用一句話說明什么是 Function Calling}], ) print(resp.choices[0].message.content)如果這一步能打印出正?；卮鹫f明 Key 和通道都沒問題。接下來要驗(yàn)證的是 Function Calling 是否可用。這是 Code Agent 的核心能力必須提前確認(rèn)。寫一個(gè)帶工具定義的請求tools [ { type: function, function: { name: read_file, description: 讀取指定路徑的文件內(nèi)容, parameters: { type: object, properties: { path: {type: string, description: 文件相對路徑} }, required: [path], }, }, } ] resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 幫我讀取 README.md}], toolstools, tool_choiceauto, ) msg resp.choices[0].message print(tool_calls:, msg.tool_calls)如果返回的 message 里包含 tool_calls 字段并且 function.name 是 read_file說明 Function Calling 鏈路正常。這一步非常關(guān)鍵因?yàn)楹竺嬲麄€(gè) Agent 主循環(huán)都依賴這個(gè)協(xié)議。如果這里返回的是純文本而不是 tool_calls說明模型或通道不支持結(jié)構(gòu)化調(diào)用需要換模型或檢查參數(shù)。關(guān)于模型選擇TaoToken 支持多種模型 ID。對于 Code Agent 場景我建議優(yōu)先選支持長上下文和 Function Calling 的模型。你可以在 https://taotoken.net/models 查看可用模型列表。實(shí)際測試下來Claude 系列在工具調(diào)用穩(wěn)定性上表現(xiàn)不錯(cuò)適合作為主循環(huán)的推理模型。還有一個(gè)細(xì)節(jié)超時(shí)和重試。本地開發(fā)時(shí)網(wǎng)絡(luò)波動很常見建議給 client 配置合理的超時(shí)時(shí)間并加一層簡單的重試邏輯client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], timeout60.0, max_retries2, )這樣即使偶發(fā)超時(shí)Agent 也不會直接崩潰。把這一層封裝成一個(gè) LLMClient 類后面主循環(huán)里只調(diào)用這個(gè)類的方法方便統(tǒng)一管理。3. 可復(fù)制配置Agent 主循環(huán)與工具注冊的完整骨架這一章給出可以直接復(fù)制的配置和代碼骨架。先定義項(xiàng)目結(jié)構(gòu)建議這樣組織my_code_agent/ ├── agent/ │ ├── __init__.py │ ├── llm_client.py # 模型調(diào)用封裝 │ ├── registry.py # 工具注冊中心 │ ├── loop.py # ReAct 主循環(huán) │ └── context.py # 上下文管理 ├── tools/ │ ├── __init__.py │ ├── read.py │ ├── grep.py │ └── edit.py ├── config/ │ └── settings.json └── main.py先寫工具注冊中心。它的職責(zé)是維護(hù)工具名到函數(shù)的映射并自動生成 JSON Schema# agent/registry.py import json from typing import Callable, Any class ToolRegistry: def __init__(self): self._tools: dict[str, dict] {} def register(self, name: str, description: str, parameters: dict, func: Callable): self._tools[name] { schema: { type: function, function: { name: name, description: description, parameters: parameters, }, }, func: func, } def get_schemas(self) - list[dict]: return [t[schema] for t in self._tools.values()] def execute(self, name: str, args: dict) - Any: if name not in self._tools: return {status: error, text: f未知工具: {name}} try: return self._tools[name][func](**args) except Exception as e: return {status: error, text: f工具執(zhí)行失敗: {e}}接著寫一個(gè) Read 工具作為示例。注意返回統(tǒng)一信封# tools/read.py import os def read_file(path: str, max_lines: int 500) - dict: if not os.path.exists(path): return {status: error, text: f文件不存在: {path}} with open(path, r, encodingutf-8, errorsignore) as f: lines f.readlines() truncated len(lines) max_lines content .join(lines[:max_lines]) return { status: partial if truncated else success, data: {content: content, total_lines: len(lines)}, text: f讀取 {path}共 {len(lines)} 行 (已截?cái)?if truncated else ), }然后在 main.py 里注冊工具并啟動主循環(huán)# main.py import os from openai import OpenAI from agent.registry import ToolRegistry from tools.read import read_file client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) registry ToolRegistry() registry.register( nameread_file, description讀取指定路徑的文件內(nèi)容, parameters{ type: object, properties: { path: {type: string, description: 文件相對路徑}, max_lines: {type: integer, description: 最大讀取行數(shù)}, }, required: [path], }, funcread_file, ) def run_agent(user_input: str, max_steps: int 10): messages [ {role: system, content: 你是一個(gè)代碼助手可以調(diào)用工具讀取文件。}, {role: user, content: user_input}, ] for step in range(max_steps): resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messagesmessages, toolsregistry.get_schemas(), tool_choiceauto, ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: args json.loads(call.function.arguments) result registry.execute(call.function.name, args) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), }) return 達(dá)到最大步數(shù)限制 if __name__ __main__: print(run_agent(讀取 README.md 并總結(jié)內(nèi)容))這段代碼就是 Agent 的最小閉環(huán)。你可以直接復(fù)制運(yùn)行只要環(huán)境變量配好就能看到模型調(diào)用 read_file 工具并返回結(jié)果。注意 messages 里 assistant 消息必須原樣 appendtool 消息必須帶 tool_call_id這是 Function Calling 協(xié)議的硬要求。如果你用的是 Claude Code 類工具做本地開發(fā)可能還會涉及 settings.json 配置。比如在項(xiàng)目根目錄放一個(gè) config/settings.json{ model: claude-sonnet-4-20250514, base_url: https://taotoken.net/api, max_steps: 20, tool_output_max_lines: 2000, tool_output_max_bytes: 51200 }這個(gè)配置文件后面可以擴(kuò)展成支持 MCP 服務(wù)器列表、Skills 目錄等。把配置和代碼分離改參數(shù)時(shí)不用動主邏輯。4. 驗(yàn)證請求與成功結(jié)果一次端到端工具調(diào)用實(shí)測配置寫完后必須做一次端到端驗(yàn)證。我設(shè)計(jì)一個(gè)最小但完整的測試場景讓 Agent 讀取當(dāng)前目錄下的一個(gè) Python 文件統(tǒng)計(jì)函數(shù)數(shù)量并輸出結(jié)果。這個(gè)任務(wù)需要模型調(diào)用 read_file 工具拿到內(nèi)容后自己分析最后給出答案。準(zhǔn)備一個(gè)測試文件 demo.pydef foo(): pass def bar(): return 1 class Baz: def method(self): pass然后運(yùn)行 Agentprint(run_agent(讀取 demo.py告訴我里面有幾個(gè)函數(shù)定義))預(yù)期流程是這樣的第一輪模型返回 tool_calls調(diào)用 read_file參數(shù) path 為 demo.py。你的代碼執(zhí)行工具把文件內(nèi)容回填到 messages。第二輪模型拿到內(nèi)容后不再調(diào)用工具直接輸出類似“demo.py 中有 2 個(gè)頂層函數(shù)定義foo 和 bar另外 Baz 類里有一個(gè) method 方法”的回答。如果這一步成功說明整條鏈路是通的TaoToken 通道正常、Function Calling 協(xié)議正常、工具注冊和執(zhí)行正常、消息回填正常。這是從零構(gòu)建 Code Agent 的第一個(gè)里程碑。接下來驗(yàn)證多步調(diào)用。讓 Agent 先列目錄再讀文件print(run_agent(先看看當(dāng)前目錄有哪些文件然后讀取 main.py 的前 20 行))這個(gè)任務(wù)需要模型連續(xù)調(diào)用兩次工具。第一次可能是 list_dir第二次是 read_file。你要觀察 messages 數(shù)組是否正確累積tool_call_id 是否一一對應(yīng)。如果模型在第二輪忘記之前的工具結(jié)果說明消息回填有問題。實(shí)測下來最容易出錯(cuò)的點(diǎn)是 arguments 的 JSON 解析。模型有時(shí)會返回帶換行或多余空格的 JSON 字符串直接 json.loads 可能失敗。建議加一層容錯(cuò)def safe_parse_args(raw: str) - dict: try: return json.loads(raw) except json.JSONDecodeError: # 嘗試去掉尾部多余字符 raw raw.strip().rstrip(}) raw } return json.loads(raw)還有一個(gè)驗(yàn)證點(diǎn)是工具返回的 status 字段。如果 read_file 返回 partial模型應(yīng)該知道內(nèi)容被截?cái)嗔?。你可以在系統(tǒng)提示里加一句“如果工具返回 status 為 partial說明內(nèi)容被截?cái)啾匾獣r(shí)可以分段讀取。”這樣模型的行為會更合理。成功結(jié)果的標(biāo)準(zhǔn)是什么不是模型回答得多漂亮而是這三件事同時(shí)成立第一工具被正確調(diào)用且參數(shù)合法第二工具結(jié)果被完整回填且 tool_call_id 匹配第三模型基于工具結(jié)果給出了符合事實(shí)的回答。三者缺一鏈路就不算通。5. 本篇常見錯(cuò)誤排查401、local proxy failed、reading choices、OAuth這一章對照真實(shí)報(bào)錯(cuò)來排查。第一個(gè)高頻錯(cuò)誤是 401 Unauthorized。典型報(bào)錯(cuò)信息是Error code: 401 - {error: {message: Invalid API key}}。原因通常是環(huán)境變量沒生效或者 Key 復(fù)制時(shí)帶了空格。排查步驟先在終端執(zhí)行echo $TAOTOKEN_API_KEY確認(rèn)變量存在然后檢查代碼里讀取的變量名是否一致最后確認(rèn) base_url 是 https://taotoken.net/api 而不是其他地址。如果用的是 .env 文件記得用 python-dotenv 加載。第二個(gè)錯(cuò)誤是local proxy failed或連接超時(shí)。這類報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)環(huán)境不穩(wěn)定時(shí)。排查方向先確認(rèn)能否直接訪問 https://taotoken.net/api可以用 curl 測試curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果 curl 能通但 Python 不通檢查是否有系統(tǒng)級代理設(shè)置干擾。另外把 timeout 調(diào)大一些本地開發(fā)時(shí) 60 秒比較穩(wěn)妥。第三個(gè)錯(cuò)誤是reading choices或KeyError: choices。這通常是因?yàn)榉祷伢w不是標(biāo)準(zhǔn)的 Chat Completions 格式或者請求被攔截返回了錯(cuò)誤頁。排查方法在調(diào)用后先打印完整 resp看結(jié)構(gòu)對不對。如果 resp 里沒有 choices可能是模型 ID 寫錯(cuò)了或者請求體格式有問題。確認(rèn) model 字段用的是 TaoToken 支持的模型 ID可以在 https://taotoken.net/models 查。第四個(gè)錯(cuò)誤是 OAuth 相關(guān)報(bào)錯(cuò)比如OAuth token expired或invalid_grant。如果你用的是 Claude Code 類客戶端可能會遇到 OAuth 認(rèn)證問題。這時(shí)候需要檢查客戶端的認(rèn)證配置。對于 Claude Code 接入推薦使用 API Key 方式而不是 OAuth配置三件套Base URL 填 https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填支持的模型。如果你在用 CC Switch 或 Cline MCP同樣需要確認(rèn)這三項(xiàng)配置一致。還有一個(gè)隱蔽錯(cuò)誤是工具調(diào)用死循環(huán)。模型反復(fù)調(diào)用同一個(gè)工具每次都返回相同結(jié)果。這通常是因?yàn)楣ぞ叻祷氐?text 里沒有明確告訴模型“已經(jīng)完成”或“沒有更多內(nèi)容”。解決辦法是在工具返回里加狀態(tài)提示比如搜索無結(jié)果時(shí)返回{status: success, text: 未找到匹配項(xiàng)建議換關(guān)鍵詞}而不是空字符串。最后提醒一點(diǎn)如果報(bào)錯(cuò)信息里出現(xiàn)tool_call_id mismatch說明你在回填 tool 消息時(shí)用的 id 和 assistant 消息里的 id 不一致。檢查代碼里是否用了call.id而不是自己生成的 id。這個(gè)錯(cuò)誤在手動拼接 messages 時(shí)很常見。6. 語義一致 CTA把統(tǒng)一 Key 接入變成長期可用的開發(fā)習(xí)慣走到這里你已經(jīng)有了一個(gè)能跑通 Function Calling 的 Code Agent 骨架。但要讓它在真實(shí)項(xiàng)目里長期可用還需要把模型調(diào)用通道固化下來。TaoToken 的統(tǒng)一 Key 接入價(jià)值就在這里你不需要在每次換模型時(shí)重寫調(diào)用層只需要改一個(gè) model 字段。對于長期編碼和 Agent 開發(fā)場景可以考慮 Coding Plan把常用模型和額度統(tǒng)一管理減少反復(fù)配置的成本。如果你在排查接入問題時(shí)需要對照文檔接入文檔里有完整的參數(shù)說明和示例。驗(yàn)證模型是否可用時(shí)可以直接用模型對話做快速測試。而 API Keys 頁面則是生成和管理 Key 的入口。這三個(gè)入口配合使用基本覆蓋了從調(diào)試到上線的全流程?；氐?Agent 本身下一步可以擴(kuò)展的方向很多把 Read、Grep、Edit 做成原子工具鏈加上樂觀鎖防止并發(fā)修改引入統(tǒng)一截?cái)鄼C(jī)制把超長工具輸出落盤保存用 Summary 壓縮舊歷史避免長對話上下文腐爛加一層 TraceLogger把每一步 tool_call 和 tool_result 記錄下來方便復(fù)盤。這些工程細(xì)節(jié)才是 Code Agent 從“能跑”到“能穩(wěn)”的關(guān)鍵。我自己的習(xí)慣是每加一個(gè)新工具就先寫一個(gè)最小驗(yàn)證腳本確認(rèn) Function Calling 鏈路正常后再集成到主循環(huán)。這樣出問題時(shí)排查范圍小不會一上來就面對幾百行代碼。你也可以把這個(gè)習(xí)慣保持下去Agent 開發(fā)本質(zhì)上是一個(gè)不斷縮小不確定性的過程。