你注意過沒有AI編程Agent在改代碼時最大的開銷往往不在模型推理本身而在“讀文件”這個動作上。拿一個幾千行的老模塊讓模型改很多Agent會真的把整個文件塞進上下文然后在一堆import和無關(guān)函數(shù)里迷失方向要么輸出格式跑偏要么直接跟你說“超出上下文長度”。這時候通常會冒出一種需求讓Agent按需讀代碼而不是整文件硬啃。我基于這個想法做了個工具名字就叫ast-outline。它的核心思路很簡單用AST把文件抽成一份帶行號、帶結(jié)構(gòu)、帶符號名的大綱Agent先花很少的token看清地圖再針對某個函數(shù)精確讀取源碼區(qū)間。這篇文章就是整套方案的完整復(fù)盤我為什么做它、中間怎么設(shè)計、對接Agent時踩過哪些坑以及實測下來到底能省多少token。1. 直接整文件硬啃到底虧在了哪里先說一個真實場景。幾個月前我讓Agent在一個老項目里加一個新的Metrics上報接口項目里有個controller文件約1800行里面塞了幾十個路由函數(shù)還有一堆幾乎沒人用的歷史兼容邏輯。Agent走的是默認路徑拿read_file工具把整個文件讀進去再開始思考改哪里。結(jié)果模型讀完前400行已經(jīng)開始忘記重點是哪個函數(shù)了當(dāng)它終于看到真正的路由定義時上下文里已經(jīng)被大量的“無關(guān)樣板代碼”塞滿最后生成的補丁把另一個接口給改了。所有用過這類Agent的人大概率都遇到過這種問題。所以第一步我們先算筆賬看看整文件硬啃到底虧在哪些地方。1.1 token消耗的大頭往往不是目標代碼代碼文件有一個特性能正常工作的大型文件大部分內(nèi)容是模塊化積累下來的歷史代碼。對一次具體改動而言真正需要關(guān)注的往往是一個類里的兩三個方法、一個函數(shù)體、若干常量定義。但整文件讀入時你的token消耗和文件總量成正比而不是和“任務(wù)相關(guān)的代碼量”成正比。我拿一個有代表性的文件做過統(tǒng)計一個約2000行的Java服務(wù)類包含8個public方法、6個private方法、一堆字段和getter/setter。如果目標只是修改其中一個方法內(nèi)的日志邏輯真正需要讓模型看到的代碼量大約60行到100行就夠但整文件讀入會消耗約18000到25000 token。這個倍數(shù)關(guān)系不是3倍5倍可能是二十倍甚至更高。尤其要注意的是Agent交互是多次請求。第一次整讀文件后如果后續(xù)對話里模型需要再次確認某段邏輯很多Agent實現(xiàn)會把文件內(nèi)容繼續(xù)留在上下文中。上下文是滾動累積的不是一次性的。一個任務(wù)下來光文件讀取反復(fù)花掉的token就會讓你肉疼。1.2 噪聲讓模型分心比浪費token更致命浪費token還好辦頂多是花錢。更麻煩的是噪聲信息會讓模型產(chǎn)生錯誤聯(lián)想。大模型有個特點它會模仿你給它的上下文中的風(fēng)格和模式。當(dāng)你把一個2000行文件整讀進去里面充斥著歷史遺留的錯誤處理寫法、舊版鑒權(quán)邏輯、甚至幾個相互矛盾的編碼風(fēng)格時模型在生成代碼時會不自覺地去“學(xué)習(xí)”這些噪聲。它可能照抄一個已經(jīng)被標記廢棄的工具方法可能模仿了某段被注釋掉的邏輯甚至因為看到大量try-catch包著return null的模式就把你要的新接口也寫成了吞異常的風(fēng)格。我給團隊內(nèi)部Agent換掉整讀策略后明顯感覺到生成代碼的“風(fēng)格污染”變?nèi)趿?。原因很簡單模型讀到的內(nèi)容從“整個混沌倉庫”變成了“精準命中的代碼片段”它沒有機會去模仿那些無關(guān)代碼。1.3 截斷方案也是一樣的坑也許你會說我們不做整讀我們讓Agent只讀文件前N行或者后N行不就行了問題是你需要的那段代碼可能恰好就不在你截斷的范圍內(nèi)。一旦截斷錯了Agent還意識不到自己漏了信息它會在已有片段基礎(chǔ)上強行推理最后生成一個看似合理但完全不符合原文件上下文邏輯的補丁。這種失敗比上下文超長失敗更難查因為報錯不一定在表面上。比如函數(shù)A在文件前100行定義真正修改點卻在第500行的調(diào)用處截斷到300行的話Agent根本不知道函數(shù)A的完整簽名。它可能創(chuàng)建一個新函數(shù)而不是復(fù)用已有的。所以結(jié)論很直接在大文件場景里問題不是“讀得不夠多”而是“讀得不夠準”。2. ast-outline的設(shè)計讓代碼在Agent腦中變成一張帶行號的地圖圍繞“讀得準”我設(shè)計了一個輕量工具名字就叫ast-outline。目標非常具體把源代碼文件先解析成一棵語法樹然后把語法樹投影成一份結(jié)構(gòu)清單這份清單包含類、方法、函數(shù)、接口、關(guān)鍵變量定義的名字、行號范圍、參數(shù)列表等摘要信息。Agent拿著這份清單就能快速決定下一步要精確讀取哪個區(qū)間。它本質(zhì)上做的是“先給地圖再進胡同”。2.1 基本思路AST的價值不在“完整”而在“可裁剪”很多接觸過編譯原理的同學(xué)對AST的第一印象是“一種完整表示代碼的樹結(jié)構(gòu)”。這個說法沒錯但對Agent場景反而有害——完整語法樹數(shù)據(jù)量巨大。某個文件如果用解析器導(dǎo)出原始AST JSON體積可能是源文件的5到10倍。直接把AST塞給模型等于用一個更大的文件替代原文件這是方向性錯誤。ast-outline做的是反向操作解析AST是為了能準確識別出“哪些節(jié)點是命名定義”然后只保留這些定義節(jié)點的骨架信息。函數(shù)體內(nèi)部的所有語句、循環(huán)、條件分支、賦值表達式這些對結(jié)構(gòu)清單來說暫時都不重要。我們要保留的是“文件里有這些東西它們從哪里開始到哪里結(jié)束”至于內(nèi)部怎么實現(xiàn)屬于下一步按需讀取的范疇。這就像看書時不把整頁文字背下來而是先掃目錄第1章第2節(jié)在第42頁我只需要翻到第42頁去細讀那部分即可。2.2 一個最小的outline長什么樣先看一個具體的Python文件示例。假設(shè)文件叫src/notifier.py內(nèi)容包含一個類、兩個方法# src/notifier.py import smtplib from typing import List EMAIL_TEMPLATE hello {name} class Notifier: def __init__(self, smtp_host: str): self.host smtp_host self._connected False def connect(self) - bool: # 這里省略具體實現(xiàn) return True def send(self, to: List[str], subject: str, body: str) - int: # 略 return 0 def default_notifier(config: dict) - Notifier: return Notifier(config[host])經(jīng)過ast-outline處理之后給模型看的大綱大概長這樣## src/notifier.py (6 definitions) imports: smtplib typing.List module_vars: EMAIL_TEMPLATE: str|Literal [line 5] def default_notifier(config: dict) - Notifier [lines 26-28] class Notifier [lines 7-24] def __init__(self, smtp_host: str) [lines 8-11] def connect(self) - bool [lines 13-15] def send(self, to: List[str], subject: str, body: str) - int [lines 17-24]這個格式有幾個特點每個定義節(jié)點都帶行號區(qū)間Agent可以據(jù)此發(fā)起第二次精確讀取。import只保留模塊名函數(shù)體完全丟棄。有嵌套關(guān)系類的方法掛在類下面不會丟失歸屬信息。文本量極小通常一個幾百行文件的大綱只有幾百到一千個字符折算token約200到300個。2.3 為什么大綱比“全文目錄”更適合Agent有人會問LSP、IDE里的Outline早就有了這算什么新東西區(qū)別在于消費對象。IDE的Outline給人看人腦有很強的視覺補全能力看個名字就知道大致內(nèi)容也不在乎行號是否精確到個位數(shù)。而AI編程Agent是一個需要通過文本接口做決策的程序它需要的是明確的路徑信息幫助它決定下一次調(diào)用讀文件的哪一行到哪一行。緊湊的符號密度一份長度可控的上下文可以覆蓋整個目錄而不只是一個文件。機器可讀或半結(jié)構(gòu)化的格式便于在工具調(diào)用中穩(wěn)定解析。我用“代碼地圖”來類比傳統(tǒng)全文讀取像是直接丟給你一整本《戰(zhàn)爭與和平》讓你找某人第一次出現(xiàn)在第幾頁ast-outline相當(dāng)于先給你一份人物索引和章節(jié)梗概。Agent當(dāng)然最終還是要翻書但它翻到具體頁再讀而不是抱著整本書一遍遍啃。3. 動手實現(xiàn)一個輪廓提取器如果你只想解決問題不一定非要自己寫整套AST工具鏈。但如果你覺得“整文件硬啃”這個痛點真實存在親手實現(xiàn)一遍會極大幫助你理解方案邊界。下面是我的實現(xiàn)路徑完整程度可以當(dāng)作一份最小可復(fù)刻參考。3.1 選型為什么是tree-sitter而不是各個語言自帶parser做多語言工程時第一個要決策的事就是用什么解析器。我一開始想用各語言自己的AST模塊比如Python用ast庫JavaScript用babel/parserJava用javaparser。但這樣會導(dǎo)致Agent工程需要按語言維護一大堆解析代碼接口對齊成本高到不想寫。最終我選了tree-sitter理由有三個它通過一個統(tǒng)一的Parser接口和各類語言grammar提供解析能力支持Python、JS/TS、Java、Go、Rust、C/C等主流語言。tree-sitter的語法定義文件更像“活文檔”查詢語法樹時可以按node.type來做過濾不需要為每個語言定制復(fù)雜邏輯。tree-sitter天然支持語法錯誤容錯即使源碼不完整或者中間有壞塊也能生成部分合法的語法樹。這個特性對“AI正在修改一半的文件”這種場景極其友好。3.2 利用node類型識別“定義節(jié)點”tree-sitter對每種語言都會產(chǎn)生一大類node.type。例如Python函數(shù)定義是function_definition類是class_definitionJavaScript函數(shù)定義可能是function_declaration或method_definition類是class_declaration。窮舉這些類型會累死而且語言一多就失控。更好的方式是觀察tree-sitter生成的node-types.json。每個語法包都會帶這個文件里面描述了該語言里所有可能的節(jié)點類型以及每個節(jié)點是否有name字段。ast-outline的啟發(fā)式策略遍歷整棵語法樹對每個節(jié)點判斷它的type是否出現(xiàn)在“定義類節(jié)點”的集合里。如果這個節(jié)點有name字段則認為它是一個可命名定義。記錄它的kindtypenamestart_pointend_point。如果它是函數(shù)或方法記錄參數(shù)列表的關(guān)鍵字結(jié)構(gòu)。對Python我會額外判斷class_definition節(jié)點下直接包含的function_definition這種情況下函數(shù)的kind標記為method方便在大綱里體現(xiàn)歸屬關(guān)系。對JS/TSclass_declaration字段里同樣可能嵌套method_definition處理邏輯一致。3.3 代碼骨架解析并生成簡化大綱我寫一個Python版本的最小實現(xiàn)片段。它依賴tree_sitter和對應(yīng)語言的Python綁定整體過程是“解析→遍歷→投影”。from tree_sitter import Language, Parser import tree_sitter_python as tsp # 關(guān)鍵映射你想在outline中保留的語法節(jié)點類型 DEFINITION_NODE_TYPES { function_definition, class_definition, decorated_definition, } class OutlineBuilder: def __init__(self): self.result [] def handle_node(self, node): if node.type not in DEFINITION_NODE_TYPES: return name_node node.child_by_field_name(name) if name_node is None: return kind method if self._is_method(node) else node.type.split(_definition)[0] params_text self._extract_params(node) entry { kind: kind, name: name_node.text.decode(utf8, errorsreplace), params: params_text, start_line: node.start_point[0] 1, end_line: node.end_point[0] 1, } self.result.append(entry) # 遞歸處理類節(jié)點內(nèi)部的函數(shù)定義 if node.type class_definition: self._walk_children(node, prefix_childrenTrue) def _walk_children(self, node, prefix_children: bool): for child in node.children: if child.type in {function_definition, method_definition}: self.handle_node(child) def build(self, source_bytes: bytes, filepath: str): parser Parser(Language(tsp.language())) tree parser.parse(source_bytes) root tree.root_node self.result [] self._traverse(root) return self._format_markdown(filepath) def _traverse(self, node): # 先處理當(dāng)前節(jié)點再遞歸孩子 self.handle_node(node) for child in node.children: self._traverse(child)再配合一個調(diào)用入口把結(jié)果渲染成上文那種Markdown大綱。注意一個細節(jié)為了處理裝飾器場景我會把decorated_definition也考慮在內(nèi)然后繼續(xù)下鉆到里面的function_definition或class_definition去拿名字。3.4 輸出協(xié)議與緩存每次實時解析整個文件如果很慢Agent任務(wù)體驗會下降。我加了一層緩存按路徑 文件大小 mtime 文件hash做key解析結(jié)果序列化成JSON落到.ast_outline_cache/目錄里。下次Agent再向ast-outline請求同一個文件的大綱時如果hash沒變就直接從磁盤讀緩存。這個緩存還有一個額外收益對同一個Agent會話連續(xù)多次請求不同文件的大綱時只有首次會觸發(fā)完整解析。加上tree-sitter本身解析速度很快一個2000行文件通常在50ms以內(nèi)最終對Agent決策路徑的影響幾乎可以忽略。4. 接入Agent的“按需讀取”循環(huán)不是把大綱丟給模型就完事有了大綱提取器距離“Agent按需讀代碼”還差一步怎么把它接到Agent的推理循環(huán)里。這部分的坑比解析器本身多得多。很多工具類項目只提供“生成結(jié)構(gòu)”的能力沒有認真設(shè)計Agent如何消費最后就只能拿它生成一份永遠不會被自動調(diào)用的報告。4.1 Agent新增三個工具調(diào)用替代裸read_file我給自己的Agent框架擴展了三個工具而不是直接刪掉其實用的read_file。這三個工具構(gòu)成一個小閉環(huán)1. read_outline(path) 返回文件大綱包含符號名、類型、行號區(qū)間、參數(shù)摘要。 2. read_region(path, start_line, end_line) 精確讀取指定行區(qū)間通常用于查看目標函數(shù)實現(xiàn)。 3. resolve_symbol(path, symbol_name) 根據(jù)大綱中的符號名直接返回該符號定義位置的代碼片段。Agent在改代碼時的自然行為變成先read_outline看結(jié)構(gòu)再決定是read_region還是resolve_symbol。它在決策時消耗的token比原先少了非常多因為它再也不用把整文件導(dǎo)入上下文。4.2 在指令中注入“先看大綱”的偏好純工具加上了但模型不調(diào)用是另一個常見問題。我需要在系統(tǒng)提示里明確告訴AI編程Agent遇到代碼文件時如果文件可能超過300行或者你沒把握準確位置優(yōu)先調(diào)用read_outline而不是read_file只有當(dāng)你確認目標函數(shù)后才用read_region。系統(tǒng)提示的措辭也很關(guān)鍵。不能說“可以訪問大綱”而要給出一個更細粒度的決策樹。我實際在用的提示語大概是每次讀取代碼前先判斷目標是否指向某個明確的符號類/函數(shù)/方法 - 如果明確優(yōu)先使用 resolve_symbol 或 read_outline 定位后再 read_region。 - 如果需要了解某個文件的整體結(jié)構(gòu)使用 read_outline。 - 避免一次性讀取超過300行的原始代碼除非你明確知道該行區(qū)間就是修改點。這種指令方式讓“按需讀取”從推薦動作變成Agent的默認路徑。4.3 遞歸展開策略最多深入多遠按需讀取最怕什么怕Agent順著調(diào)用鏈一發(fā)不可收拾A讀BB讀CC又讀A最后讀了一堆片段上下文依然爆炸。因此一定要給遞歸行為設(shè)邊界。我做了三個約束深度約束單次任務(wù)的符號展開深度默認限制為 3 層。也就是說Agent可以看入口函數(shù)、入口調(diào)用的函數(shù)、那個函數(shù)里再調(diào)用的核心函數(shù)但不鼓勵繼續(xù)查第四層。子節(jié)點數(shù)量約束如果某個類的方法超過40個大綱里只顯示前40個方法和一個省略標記避免Agent因為好奇心把整個類的方法都讀一遍。循環(huán)檢測用一個visit set記錄已經(jīng)讀取過的符號。如果Agent嘗試resolve_symbol一個已經(jīng)查過的函數(shù)直接返回“該符號已在上文獲取過請參考前文內(nèi)容”防止它重復(fù)執(zhí)行。4.4 大綱不是萬能的它負責(zé)找“位置”不負責(zé)找“字符串”當(dāng)你需要查找某個字符串常量、某個魔法數(shù)字、某條日志關(guān)鍵字時AST大綱完全幫不上忙。這是設(shè)計邊界不該硬拗。比如你要改一條報錯信息里的英文提示用大綱翻開十來個方法都找不到因為它是字符串字面量不是符號定義。實際使用中我和Agent的混合策略是如果問題描述里含明確符號函數(shù)名、類名、字段名走outline路線如果含字符串、正則、配置key走grep路線。一個Agent工程里rg工具和outline類工具是互補關(guān)系不存在誰替代誰。這個定位想清楚之后整個接入方案才穩(wěn)定下來。5. 一次不完全對照實驗省了多少token又救回了多少失敗的修復(fù)光說設(shè)計沒有說服力。我在內(nèi)部項目里做了一組對照實驗選擇6個真實的代碼修改任務(wù)目標文件大小從300行到9000行不等。任務(wù)類型包括加接口、修bug、改返回結(jié)構(gòu)、替換廢棄API。對比基線是“Agent直接按原方案整讀文件”對照方案是“ast-outline 按需讀取”。5.1 實驗方法說明我盡量控制變量同一個任務(wù)同樣的模型版本同樣的系統(tǒng)提示只改變“讀文件”的工具鏈路。Agent的workflow分別叫基線模式和outline模式。每一次任務(wù)允許最多20輪工具調(diào)用超時未完成則視為失敗。實驗規(guī)模不大屬于工程場景上的快速驗證結(jié)論僅供趨勢參考。結(jié)果如下任務(wù)類型目標文件規(guī)?；€模式token消耗outline模式token消耗基線是否完成outline是否完成修改Web控制器接口1800行約72k約21k完成但出現(xiàn)一次跑偏完成修復(fù)RPC服務(wù)空指針600行約25k約9k完成完成給遺留工具類加兼容方法3300行觸發(fā)上下文溢出約18k失敗完成替換廢棄API調(diào)用跨3個文件各400-800行約35k約16k完成完成給大型狀態(tài)機增補狀態(tài)9000行觸發(fā)上下文溢出約33k失敗完成錯誤棧定位崩潰原因混合目錄約2萬行約60k約24k部分完成完成token節(jié)省量我取平均大約60%-70%在兩個大文件任務(wù)中基線已經(jīng)無法完成核心原因是上下文溢出導(dǎo)致Agent不再能穩(wěn)定調(diào)用工具。outline模式即使在9000行文件任務(wù)里仍然能完成因為它每輪最多只讀一個300行以內(nèi)的函數(shù)片段。5.2 成功率的提升從哪里來節(jié)省token并不自動等于成功率提升這是兩件事。實際觀察里成功率的提升主要來自兩個機制第一Agent不會在讀到目標函數(shù)之前就“累”了。大模型在超過一定上下文長度后對中部內(nèi)容的注意力衰減很厲害。整文件讀法下模型窗口里裝著大量位于文件前中段的歷史代碼當(dāng)真正需要的函數(shù)在文件后部時模型常常把前面的舊邏輯當(dāng)成當(dāng)前事實生成錯誤補丁。outline模式下模型只有在決定精確讀取后才看到目標函數(shù)注意焦點始終集中。第二失敗了也更容易自查。Agent工具調(diào)用的可觀察性變強了因為它每一步讀取的是明確行區(qū)間父級診斷可以直接看到“它讀了哪一段為什么讀那一段”。整文件模式只能看到“它讀了整個文件然后自己在那瞎猜”。5.3 一個反例什么時候按需讀取會誤事不是所有場景都適合大綱優(yōu)先。我有一次讓Agent重構(gòu)一個配置類這個類的字段順序本身就隱含路由表結(jié)構(gòu)共有40多個字段而且字段注釋是這個對象的唯一文檔。outline模式只列出字段名模型看不到字段之間的聯(lián)系結(jié)果把路由前綴順序改錯了。后來我調(diào)整了規(guī)則如果對象被模型判定為“配置結(jié)構(gòu)”“數(shù)據(jù)模型”那么即便文件很大也應(yīng)該讀取完整定義區(qū)域而不要只讀片段。這個反例說明一個很重要的道理按需讀取不等于越小越好而是要在“任務(wù)需要全局視野”的時候能主動升級成整段讀取。Agent不能只會一種讀取策略。6. 踩過的坑和最后留下的注意清單這大半年里ast-outline從最初幾百行的Python腳本一路演進到帶緩存、帶遞歸控制、帶多種輸出格式的小工具。過程中踩了不少坑有些坑如果不寫下來后面人用同樣的思路可能又得重新趟一遍。6.1 語法錯誤和半成品文件正常解析器直接罷工AI編程Agent最常處理的文件往往就是“正在被修改、還沒改完”的文件。整段代碼缺失、括號不匹配、縮進錯誤這些情況對語言的官方parser來說可能是致命傷但tree-sitter能容忍錯誤并返回partial tree?？删退鉻ree-sitter也會有邊界如果一個函數(shù)體內(nèi)部出現(xiàn)無法恢復(fù)的語法錯誤它的行號區(qū)間可能會跨越整個剩余文件。大綱里就會出現(xiàn)一個“幽靈方法”行號范圍大到覆蓋后續(xù)所有代碼。我的應(yīng)對措施是對每個定義節(jié)點做一次“內(nèi)部完整性檢查”檢查它的結(jié)束行和父節(jié)點結(jié)束行是否接近如果發(fā)現(xiàn)跨度異常超過某個閾值就把該節(jié)點的end_line截斷到父節(jié)點范圍內(nèi)并追加一個truncated: true標記。這樣模型知道這段索引不可完全信任不要試圖一次讀取整個巨大區(qū)間。6.2 注釋和docstring該不該進大綱剛開始我的大綱完全不包含注釋結(jié)果模型經(jīng)常通過函數(shù)名猜不出函數(shù)用途。比如一個叫_handle_sync的函數(shù)誰知道它是同步數(shù)據(jù)庫數(shù)據(jù)還是同步消息隊列如果函數(shù)沒有docstring只有實現(xiàn)細節(jié)光看簽名和行號Agent還是容易誤判。后來我在outline里增加了“文檔首行”字段對Python取docstring的第一個句子對JS/TS取函數(shù)上方最近的三行注釋過濾掉license級的大段頭注釋。這個方法明顯提升了模型對函數(shù)意圖的判斷準確度token增加卻很少。6.3 行號失效和緩存污染比想象中麻煩只要Agent開始改文件文件內(nèi)容就變了。如果ast-outline緩存了舊版大綱那么模型后續(xù)用舊行號發(fā)起read_region可能讀到完全不同的代碼段。解決思路是大綱結(jié)果上打一個source_version字段用文件內(nèi)容的hash表示。當(dāng)Agent執(zhí)行編輯后工具層主動讓該文件的緩存失效并要求下一次讀取時強制重新解析。另一個更徹底的方案是讓ast-outline支持AST節(jié)點路徑定位方式比如指定絕對路徑到函數(shù)定義而非行號但改動量稍大我還在陸續(xù)推進。6.4 多語言特性宏、裝飾器、類字段帶來的差別如果只用Python做demo很多問題會被隱藏。項目鋪到Java、C、Go之后細節(jié)差異開始轟炸C: 函數(shù)聲明和定義分離function_definition有時只是一個空殼聲明。還要關(guān)注模板函數(shù)的template_declaration。Go: 方法定義和函數(shù)定義在tree-sitter里類型不同方法有receiver提取函數(shù)簽名時需要拼上receiver信息。Python: 類級別的字段賦值經(jīng)常是理解狀態(tài)機的關(guān)鍵但class_definition下直接掛expression_statement節(jié)點如果完全不提取Agent看不懂類初始化了哪些字段。Java: 注解大量使用但注解行為本身可能改變函數(shù)語義比如Transactional。outline默認不展開注解但對關(guān)鍵注解應(yīng)該提取出來。沒有萬能語言規(guī)則需要設(shè)計成一個可配置的映射表每接一種語言就補一次映射。6.5 輸出格式模型不是你的API客戶端大綱如果以原始JSON格式回傳模型反而不好消化。實踐下來效果最好的是按層級縮進的Markdown代碼塊而不是JSON對象def login(user, pwd) [line 20-35]原因很簡單模型在預(yù)訓(xùn)練階段見多了Markdown列表能高效解析縮進和冒號結(jié)構(gòu)而JSON嵌套需要模型額外在腦內(nèi)做一次花括號配對更容易出錯。真正給外部程序消費的解析結(jié)果才用JSON輸出。兩套格式一份給人/模型看一份給代碼邏輯用。6.6 如果一個功能只適合“整文件硬啃”別硬犟最后想說一個心態(tài)問題。ast-outline大幅度提升了Agent在大型代碼文件上的表現(xiàn)但它沒有解決所有問題。有些代碼修改本身需要全文件視野比如把整個類從“同步實現(xiàn)”重構(gòu)為“異步實現(xiàn)”改變所有成員方法簽名。這種情況下按函數(shù)片段讀取會遺漏調(diào)用點造成大量重構(gòu)錯誤。我現(xiàn)在的判斷標準是修改點是局部還是全局如果目標只影響文件里一個符號用outline如果目標是全局性重構(gòu)那就老老實實整文件讀取甚至要用多文件聯(lián)合索引。AI編程Agent的代碼讀取策略永遠應(yīng)該跟著任務(wù)的邊界走而不是跟著某個工具走。如果讓我只保留一條經(jīng)驗我會說給Agent喂代碼和管理人類閱讀代碼是一個道理沒人會捧著一整本書去找一句話先看目錄再翻頁必要時才讀整章。想明白這一點ast-outline是否被采用就不重要了因為你隨時可以照這個思路做出自己的版本。 AST代碼大綱：讓AI編程Agent告別整文件硬啃的高效按需讀取方案
你注意過沒有AI編程Agent在改代碼時最大的開銷往往不在模型推理本身而在“讀文件”這個動作上。拿一個幾千行的老模塊讓模型改很多Agent會真的把整個文件塞進上下文然后在一堆import和無關(guān)函數(shù)里迷失方向要么輸出格式跑偏要么直接跟你說“超出上下文長度”。這時候通常會冒出一種需求讓Agent按需讀代碼而不是整文件硬啃。我基于這個想法做了個工具名字就叫ast-outline。它的核心思路很簡單用AST把文件抽成一份帶行號、帶結(jié)構(gòu)、帶符號名的大綱Agent先花很少的token看清地圖再針對某個函數(shù)精確讀取源碼區(qū)間。這篇文章就是整套方案的完整復(fù)盤我為什么做它、中間怎么設(shè)計、對接Agent時踩過哪些坑以及實測下來到底能省多少token。1. 直接整文件硬啃到底虧在了哪里先說一個真實場景。幾個月前我讓Agent在一個老項目里加一個新的Metrics上報接口項目里有個controller文件約1800行里面塞了幾十個路由函數(shù)還有一堆幾乎沒人用的歷史兼容邏輯。Agent走的是默認路徑拿read_file工具把整個文件讀進去再開始思考改哪里。結(jié)果模型讀完前400行已經(jīng)開始忘記重點是哪個函數(shù)了當(dāng)它終于看到真正的路由定義時上下文里已經(jīng)被大量的“無關(guān)樣板代碼”塞滿最后生成的補丁把另一個接口給改了。所有用過這類Agent的人大概率都遇到過這種問題。所以第一步我們先算筆賬看看整文件硬啃到底虧在哪些地方。1.1 token消耗的大頭往往不是目標代碼代碼文件有一個特性能正常工作的大型文件大部分內(nèi)容是模塊化積累下來的歷史代碼。對一次具體改動而言真正需要關(guān)注的往往是一個類里的兩三個方法、一個函數(shù)體、若干常量定義。但整文件讀入時你的token消耗和文件總量成正比而不是和“任務(wù)相關(guān)的代碼量”成正比。我拿一個有代表性的文件做過統(tǒng)計一個約2000行的Java服務(wù)類包含8個public方法、6個private方法、一堆字段和getter/setter。如果目標只是修改其中一個方法內(nèi)的日志邏輯真正需要讓模型看到的代碼量大約60行到100行就夠但整文件讀入會消耗約18000到25000 token。這個倍數(shù)關(guān)系不是3倍5倍可能是二十倍甚至更高。尤其要注意的是Agent交互是多次請求。第一次整讀文件后如果后續(xù)對話里模型需要再次確認某段邏輯很多Agent實現(xiàn)會把文件內(nèi)容繼續(xù)留在上下文中。上下文是滾動累積的不是一次性的。一個任務(wù)下來光文件讀取反復(fù)花掉的token就會讓你肉疼。1.2 噪聲讓模型分心比浪費token更致命浪費token還好辦頂多是花錢。更麻煩的是噪聲信息會讓模型產(chǎn)生錯誤聯(lián)想。大模型有個特點它會模仿你給它的上下文中的風(fēng)格和模式。當(dāng)你把一個2000行文件整讀進去里面充斥著歷史遺留的錯誤處理寫法、舊版鑒權(quán)邏輯、甚至幾個相互矛盾的編碼風(fēng)格時模型在生成代碼時會不自覺地去“學(xué)習(xí)”這些噪聲。它可能照抄一個已經(jīng)被標記廢棄的工具方法可能模仿了某段被注釋掉的邏輯甚至因為看到大量try-catch包著return null的模式就把你要的新接口也寫成了吞異常的風(fēng)格。我給團隊內(nèi)部Agent換掉整讀策略后明顯感覺到生成代碼的“風(fēng)格污染”變?nèi)趿?。原因很簡單模型讀到的內(nèi)容從“整個混沌倉庫”變成了“精準命中的代碼片段”它沒有機會去模仿那些無關(guān)代碼。1.3 截斷方案也是一樣的坑也許你會說我們不做整讀我們讓Agent只讀文件前N行或者后N行不就行了問題是你需要的那段代碼可能恰好就不在你截斷的范圍內(nèi)。一旦截斷錯了Agent還意識不到自己漏了信息它會在已有片段基礎(chǔ)上強行推理最后生成一個看似合理但完全不符合原文件上下文邏輯的補丁。這種失敗比上下文超長失敗更難查因為報錯不一定在表面上。比如函數(shù)A在文件前100行定義真正修改點卻在第500行的調(diào)用處截斷到300行的話Agent根本不知道函數(shù)A的完整簽名。它可能創(chuàng)建一個新函數(shù)而不是復(fù)用已有的。所以結(jié)論很直接在大文件場景里問題不是“讀得不夠多”而是“讀得不夠準”。2. ast-outline的設(shè)計讓代碼在Agent腦中變成一張帶行號的地圖圍繞“讀得準”我設(shè)計了一個輕量工具名字就叫ast-outline。目標非常具體把源代碼文件先解析成一棵語法樹然后把語法樹投影成一份結(jié)構(gòu)清單這份清單包含類、方法、函數(shù)、接口、關(guān)鍵變量定義的名字、行號范圍、參數(shù)列表等摘要信息。Agent拿著這份清單就能快速決定下一步要精確讀取哪個區(qū)間。它本質(zhì)上做的是“先給地圖再進胡同”。2.1 基本思路AST的價值不在“完整”而在“可裁剪”很多接觸過編譯原理的同學(xué)對AST的第一印象是“一種完整表示代碼的樹結(jié)構(gòu)”。這個說法沒錯但對Agent場景反而有害——完整語法樹數(shù)據(jù)量巨大。某個文件如果用解析器導(dǎo)出原始AST JSON體積可能是源文件的5到10倍。直接把AST塞給模型等于用一個更大的文件替代原文件這是方向性錯誤。ast-outline做的是反向操作解析AST是為了能準確識別出“哪些節(jié)點是命名定義”然后只保留這些定義節(jié)點的骨架信息。函數(shù)體內(nèi)部的所有語句、循環(huán)、條件分支、賦值表達式這些對結(jié)構(gòu)清單來說暫時都不重要。我們要保留的是“文件里有這些東西它們從哪里開始到哪里結(jié)束”至于內(nèi)部怎么實現(xiàn)屬于下一步按需讀取的范疇。這就像看書時不把整頁文字背下來而是先掃目錄第1章第2節(jié)在第42頁我只需要翻到第42頁去細讀那部分即可。2.2 一個最小的outline長什么樣先看一個具體的Python文件示例。假設(shè)文件叫src/notifier.py內(nèi)容包含一個類、兩個方法# src/notifier.py import smtplib from typing import List EMAIL_TEMPLATE hello {name} class Notifier: def __init__(self, smtp_host: str): self.host smtp_host self._connected False def connect(self) - bool: # 這里省略具體實現(xiàn) return True def send(self, to: List[str], subject: str, body: str) - int: # 略 return 0 def default_notifier(config: dict) - Notifier: return Notifier(config[host])經(jīng)過ast-outline處理之后給模型看的大綱大概長這樣## src/notifier.py (6 definitions) imports: smtplib typing.List module_vars: EMAIL_TEMPLATE: str|Literal [line 5] def default_notifier(config: dict) - Notifier [lines 26-28] class Notifier [lines 7-24] def __init__(self, smtp_host: str) [lines 8-11] def connect(self) - bool [lines 13-15] def send(self, to: List[str], subject: str, body: str) - int [lines 17-24]這個格式有幾個特點每個定義節(jié)點都帶行號區(qū)間Agent可以據(jù)此發(fā)起第二次精確讀取。import只保留模塊名函數(shù)體完全丟棄。有嵌套關(guān)系類的方法掛在類下面不會丟失歸屬信息。文本量極小通常一個幾百行文件的大綱只有幾百到一千個字符折算token約200到300個。2.3 為什么大綱比“全文目錄”更適合Agent有人會問LSP、IDE里的Outline早就有了這算什么新東西區(qū)別在于消費對象。IDE的Outline給人看人腦有很強的視覺補全能力看個名字就知道大致內(nèi)容也不在乎行號是否精確到個位數(shù)。而AI編程Agent是一個需要通過文本接口做決策的程序它需要的是明確的路徑信息幫助它決定下一次調(diào)用讀文件的哪一行到哪一行。緊湊的符號密度一份長度可控的上下文可以覆蓋整個目錄而不只是一個文件。機器可讀或半結(jié)構(gòu)化的格式便于在工具調(diào)用中穩(wěn)定解析。我用“代碼地圖”來類比傳統(tǒng)全文讀取像是直接丟給你一整本《戰(zhàn)爭與和平》讓你找某人第一次出現(xiàn)在第幾頁ast-outline相當(dāng)于先給你一份人物索引和章節(jié)梗概。Agent當(dāng)然最終還是要翻書但它翻到具體頁再讀而不是抱著整本書一遍遍啃。3. 動手實現(xiàn)一個輪廓提取器如果你只想解決問題不一定非要自己寫整套AST工具鏈。但如果你覺得“整文件硬啃”這個痛點真實存在親手實現(xiàn)一遍會極大幫助你理解方案邊界。下面是我的實現(xiàn)路徑完整程度可以當(dāng)作一份最小可復(fù)刻參考。3.1 選型為什么是tree-sitter而不是各個語言自帶parser做多語言工程時第一個要決策的事就是用什么解析器。我一開始想用各語言自己的AST模塊比如Python用ast庫JavaScript用babel/parserJava用javaparser。但這樣會導(dǎo)致Agent工程需要按語言維護一大堆解析代碼接口對齊成本高到不想寫。最終我選了tree-sitter理由有三個它通過一個統(tǒng)一的Parser接口和各類語言grammar提供解析能力支持Python、JS/TS、Java、Go、Rust、C/C等主流語言。tree-sitter的語法定義文件更像“活文檔”查詢語法樹時可以按node.type來做過濾不需要為每個語言定制復(fù)雜邏輯。tree-sitter天然支持語法錯誤容錯即使源碼不完整或者中間有壞塊也能生成部分合法的語法樹。這個特性對“AI正在修改一半的文件”這種場景極其友好。3.2 利用node類型識別“定義節(jié)點”tree-sitter對每種語言都會產(chǎn)生一大類node.type。例如Python函數(shù)定義是function_definition類是class_definitionJavaScript函數(shù)定義可能是function_declaration或method_definition類是class_declaration。窮舉這些類型會累死而且語言一多就失控。更好的方式是觀察tree-sitter生成的node-types.json。每個語法包都會帶這個文件里面描述了該語言里所有可能的節(jié)點類型以及每個節(jié)點是否有name字段。ast-outline的啟發(fā)式策略遍歷整棵語法樹對每個節(jié)點判斷它的type是否出現(xiàn)在“定義類節(jié)點”的集合里。如果這個節(jié)點有name字段則認為它是一個可命名定義。記錄它的kindtypenamestart_pointend_point。如果它是函數(shù)或方法記錄參數(shù)列表的關(guān)鍵字結(jié)構(gòu)。對Python我會額外判斷class_definition節(jié)點下直接包含的function_definition這種情況下函數(shù)的kind標記為method方便在大綱里體現(xiàn)歸屬關(guān)系。對JS/TSclass_declaration字段里同樣可能嵌套method_definition處理邏輯一致。3.3 代碼骨架解析并生成簡化大綱我寫一個Python版本的最小實現(xiàn)片段。它依賴tree_sitter和對應(yīng)語言的Python綁定整體過程是“解析→遍歷→投影”。from tree_sitter import Language, Parser import tree_sitter_python as tsp # 關(guān)鍵映射你想在outline中保留的語法節(jié)點類型 DEFINITION_NODE_TYPES { function_definition, class_definition, decorated_definition, } class OutlineBuilder: def __init__(self): self.result [] def handle_node(self, node): if node.type not in DEFINITION_NODE_TYPES: return name_node node.child_by_field_name(name) if name_node is None: return kind method if self._is_method(node) else node.type.split(_definition)[0] params_text self._extract_params(node) entry { kind: kind, name: name_node.text.decode(utf8, errorsreplace), params: params_text, start_line: node.start_point[0] 1, end_line: node.end_point[0] 1, } self.result.append(entry) # 遞歸處理類節(jié)點內(nèi)部的函數(shù)定義 if node.type class_definition: self._walk_children(node, prefix_childrenTrue) def _walk_children(self, node, prefix_children: bool): for child in node.children: if child.type in {function_definition, method_definition}: self.handle_node(child) def build(self, source_bytes: bytes, filepath: str): parser Parser(Language(tsp.language())) tree parser.parse(source_bytes) root tree.root_node self.result [] self._traverse(root) return self._format_markdown(filepath) def _traverse(self, node): # 先處理當(dāng)前節(jié)點再遞歸孩子 self.handle_node(node) for child in node.children: self._traverse(child)再配合一個調(diào)用入口把結(jié)果渲染成上文那種Markdown大綱。注意一個細節(jié)為了處理裝飾器場景我會把decorated_definition也考慮在內(nèi)然后繼續(xù)下鉆到里面的function_definition或class_definition去拿名字。3.4 輸出協(xié)議與緩存每次實時解析整個文件如果很慢Agent任務(wù)體驗會下降。我加了一層緩存按路徑 文件大小 mtime 文件hash做key解析結(jié)果序列化成JSON落到.ast_outline_cache/目錄里。下次Agent再向ast-outline請求同一個文件的大綱時如果hash沒變就直接從磁盤讀緩存。這個緩存還有一個額外收益對同一個Agent會話連續(xù)多次請求不同文件的大綱時只有首次會觸發(fā)完整解析。加上tree-sitter本身解析速度很快一個2000行文件通常在50ms以內(nèi)最終對Agent決策路徑的影響幾乎可以忽略。4. 接入Agent的“按需讀取”循環(huán)不是把大綱丟給模型就完事有了大綱提取器距離“Agent按需讀代碼”還差一步怎么把它接到Agent的推理循環(huán)里。這部分的坑比解析器本身多得多。很多工具類項目只提供“生成結(jié)構(gòu)”的能力沒有認真設(shè)計Agent如何消費最后就只能拿它生成一份永遠不會被自動調(diào)用的報告。4.1 Agent新增三個工具調(diào)用替代裸read_file我給自己的Agent框架擴展了三個工具而不是直接刪掉其實用的read_file。這三個工具構(gòu)成一個小閉環(huán)1. read_outline(path) 返回文件大綱包含符號名、類型、行號區(qū)間、參數(shù)摘要。 2. read_region(path, start_line, end_line) 精確讀取指定行區(qū)間通常用于查看目標函數(shù)實現(xiàn)。 3. resolve_symbol(path, symbol_name) 根據(jù)大綱中的符號名直接返回該符號定義位置的代碼片段。Agent在改代碼時的自然行為變成先read_outline看結(jié)構(gòu)再決定是read_region還是resolve_symbol。它在決策時消耗的token比原先少了非常多因為它再也不用把整文件導(dǎo)入上下文。4.2 在指令中注入“先看大綱”的偏好純工具加上了但模型不調(diào)用是另一個常見問題。我需要在系統(tǒng)提示里明確告訴AI編程Agent遇到代碼文件時如果文件可能超過300行或者你沒把握準確位置優(yōu)先調(diào)用read_outline而不是read_file只有當(dāng)你確認目標函數(shù)后才用read_region。系統(tǒng)提示的措辭也很關(guān)鍵。不能說“可以訪問大綱”而要給出一個更細粒度的決策樹。我實際在用的提示語大概是每次讀取代碼前先判斷目標是否指向某個明確的符號類/函數(shù)/方法 - 如果明確優(yōu)先使用 resolve_symbol 或 read_outline 定位后再 read_region。 - 如果需要了解某個文件的整體結(jié)構(gòu)使用 read_outline。 - 避免一次性讀取超過300行的原始代碼除非你明確知道該行區(qū)間就是修改點。這種指令方式讓“按需讀取”從推薦動作變成Agent的默認路徑。4.3 遞歸展開策略最多深入多遠按需讀取最怕什么怕Agent順著調(diào)用鏈一發(fā)不可收拾A讀BB讀CC又讀A最后讀了一堆片段上下文依然爆炸。因此一定要給遞歸行為設(shè)邊界。我做了三個約束深度約束單次任務(wù)的符號展開深度默認限制為 3 層。也就是說Agent可以看入口函數(shù)、入口調(diào)用的函數(shù)、那個函數(shù)里再調(diào)用的核心函數(shù)但不鼓勵繼續(xù)查第四層。子節(jié)點數(shù)量約束如果某個類的方法超過40個大綱里只顯示前40個方法和一個省略標記避免Agent因為好奇心把整個類的方法都讀一遍。循環(huán)檢測用一個visit set記錄已經(jīng)讀取過的符號。如果Agent嘗試resolve_symbol一個已經(jīng)查過的函數(shù)直接返回“該符號已在上文獲取過請參考前文內(nèi)容”防止它重復(fù)執(zhí)行。4.4 大綱不是萬能的它負責(zé)找“位置”不負責(zé)找“字符串”當(dāng)你需要查找某個字符串常量、某個魔法數(shù)字、某條日志關(guān)鍵字時AST大綱完全幫不上忙。這是設(shè)計邊界不該硬拗。比如你要改一條報錯信息里的英文提示用大綱翻開十來個方法都找不到因為它是字符串字面量不是符號定義。實際使用中我和Agent的混合策略是如果問題描述里含明確符號函數(shù)名、類名、字段名走outline路線如果含字符串、正則、配置key走grep路線。一個Agent工程里rg工具和outline類工具是互補關(guān)系不存在誰替代誰。這個定位想清楚之后整個接入方案才穩(wěn)定下來。5. 一次不完全對照實驗省了多少token又救回了多少失敗的修復(fù)光說設(shè)計沒有說服力。我在內(nèi)部項目里做了一組對照實驗選擇6個真實的代碼修改任務(wù)目標文件大小從300行到9000行不等。任務(wù)類型包括加接口、修bug、改返回結(jié)構(gòu)、替換廢棄API。對比基線是“Agent直接按原方案整讀文件”對照方案是“ast-outline 按需讀取”。5.1 實驗方法說明我盡量控制變量同一個任務(wù)同樣的模型版本同樣的系統(tǒng)提示只改變“讀文件”的工具鏈路。Agent的workflow分別叫基線模式和outline模式。每一次任務(wù)允許最多20輪工具調(diào)用超時未完成則視為失敗。實驗規(guī)模不大屬于工程場景上的快速驗證結(jié)論僅供趨勢參考。結(jié)果如下任務(wù)類型目標文件規(guī)?；€模式token消耗outline模式token消耗基線是否完成outline是否完成修改Web控制器接口1800行約72k約21k完成但出現(xiàn)一次跑偏完成修復(fù)RPC服務(wù)空指針600行約25k約9k完成完成給遺留工具類加兼容方法3300行觸發(fā)上下文溢出約18k失敗完成替換廢棄API調(diào)用跨3個文件各400-800行約35k約16k完成完成給大型狀態(tài)機增補狀態(tài)9000行觸發(fā)上下文溢出約33k失敗完成錯誤棧定位崩潰原因混合目錄約2萬行約60k約24k部分完成完成token節(jié)省量我取平均大約60%-70%在兩個大文件任務(wù)中基線已經(jīng)無法完成核心原因是上下文溢出導(dǎo)致Agent不再能穩(wěn)定調(diào)用工具。outline模式即使在9000行文件任務(wù)里仍然能完成因為它每輪最多只讀一個300行以內(nèi)的函數(shù)片段。5.2 成功率的提升從哪里來節(jié)省token并不自動等于成功率提升這是兩件事。實際觀察里成功率的提升主要來自兩個機制第一Agent不會在讀到目標函數(shù)之前就“累”了。大模型在超過一定上下文長度后對中部內(nèi)容的注意力衰減很厲害。整文件讀法下模型窗口里裝著大量位于文件前中段的歷史代碼當(dāng)真正需要的函數(shù)在文件后部時模型常常把前面的舊邏輯當(dāng)成當(dāng)前事實生成錯誤補丁。outline模式下模型只有在決定精確讀取后才看到目標函數(shù)注意焦點始終集中。第二失敗了也更容易自查。Agent工具調(diào)用的可觀察性變強了因為它每一步讀取的是明確行區(qū)間父級診斷可以直接看到“它讀了哪一段為什么讀那一段”。整文件模式只能看到“它讀了整個文件然后自己在那瞎猜”。5.3 一個反例什么時候按需讀取會誤事不是所有場景都適合大綱優(yōu)先。我有一次讓Agent重構(gòu)一個配置類這個類的字段順序本身就隱含路由表結(jié)構(gòu)共有40多個字段而且字段注釋是這個對象的唯一文檔。outline模式只列出字段名模型看不到字段之間的聯(lián)系結(jié)果把路由前綴順序改錯了。后來我調(diào)整了規(guī)則如果對象被模型判定為“配置結(jié)構(gòu)”“數(shù)據(jù)模型”那么即便文件很大也應(yīng)該讀取完整定義區(qū)域而不要只讀片段。這個反例說明一個很重要的道理按需讀取不等于越小越好而是要在“任務(wù)需要全局視野”的時候能主動升級成整段讀取。Agent不能只會一種讀取策略。6. 踩過的坑和最后留下的注意清單這大半年里ast-outline從最初幾百行的Python腳本一路演進到帶緩存、帶遞歸控制、帶多種輸出格式的小工具。過程中踩了不少坑有些坑如果不寫下來后面人用同樣的思路可能又得重新趟一遍。6.1 語法錯誤和半成品文件正常解析器直接罷工AI編程Agent最常處理的文件往往就是“正在被修改、還沒改完”的文件。整段代碼缺失、括號不匹配、縮進錯誤這些情況對語言的官方parser來說可能是致命傷但tree-sitter能容忍錯誤并返回partial tree?？删退鉻ree-sitter也會有邊界如果一個函數(shù)體內(nèi)部出現(xiàn)無法恢復(fù)的語法錯誤它的行號區(qū)間可能會跨越整個剩余文件。大綱里就會出現(xiàn)一個“幽靈方法”行號范圍大到覆蓋后續(xù)所有代碼。我的應(yīng)對措施是對每個定義節(jié)點做一次“內(nèi)部完整性檢查”檢查它的結(jié)束行和父節(jié)點結(jié)束行是否接近如果發(fā)現(xiàn)跨度異常超過某個閾值就把該節(jié)點的end_line截斷到父節(jié)點范圍內(nèi)并追加一個truncated: true標記。這樣模型知道這段索引不可完全信任不要試圖一次讀取整個巨大區(qū)間。6.2 注釋和docstring該不該進大綱剛開始我的大綱完全不包含注釋結(jié)果模型經(jīng)常通過函數(shù)名猜不出函數(shù)用途。比如一個叫_handle_sync的函數(shù)誰知道它是同步數(shù)據(jù)庫數(shù)據(jù)還是同步消息隊列如果函數(shù)沒有docstring只有實現(xiàn)細節(jié)光看簽名和行號Agent還是容易誤判。后來我在outline里增加了“文檔首行”字段對Python取docstring的第一個句子對JS/TS取函數(shù)上方最近的三行注釋過濾掉license級的大段頭注釋。這個方法明顯提升了模型對函數(shù)意圖的判斷準確度token增加卻很少。6.3 行號失效和緩存污染比想象中麻煩只要Agent開始改文件文件內(nèi)容就變了。如果ast-outline緩存了舊版大綱那么模型后續(xù)用舊行號發(fā)起read_region可能讀到完全不同的代碼段。解決思路是大綱結(jié)果上打一個source_version字段用文件內(nèi)容的hash表示。當(dāng)Agent執(zhí)行編輯后工具層主動讓該文件的緩存失效并要求下一次讀取時強制重新解析。另一個更徹底的方案是讓ast-outline支持AST節(jié)點路徑定位方式比如指定絕對路徑到函數(shù)定義而非行號但改動量稍大我還在陸續(xù)推進。6.4 多語言特性宏、裝飾器、類字段帶來的差別如果只用Python做demo很多問題會被隱藏。項目鋪到Java、C、Go之后細節(jié)差異開始轟炸C: 函數(shù)聲明和定義分離function_definition有時只是一個空殼聲明。還要關(guān)注模板函數(shù)的template_declaration。Go: 方法定義和函數(shù)定義在tree-sitter里類型不同方法有receiver提取函數(shù)簽名時需要拼上receiver信息。Python: 類級別的字段賦值經(jīng)常是理解狀態(tài)機的關(guān)鍵但class_definition下直接掛expression_statement節(jié)點如果完全不提取Agent看不懂類初始化了哪些字段。Java: 注解大量使用但注解行為本身可能改變函數(shù)語義比如Transactional。outline默認不展開注解但對關(guān)鍵注解應(yīng)該提取出來。沒有萬能語言規(guī)則需要設(shè)計成一個可配置的映射表每接一種語言就補一次映射。6.5 輸出格式模型不是你的API客戶端大綱如果以原始JSON格式回傳模型反而不好消化。實踐下來效果最好的是按層級縮進的Markdown代碼塊而不是JSON對象def login(user, pwd) [line 20-35]原因很簡單模型在預(yù)訓(xùn)練階段見多了Markdown列表能高效解析縮進和冒號結(jié)構(gòu)而JSON嵌套需要模型額外在腦內(nèi)做一次花括號配對更容易出錯。真正給外部程序消費的解析結(jié)果才用JSON輸出。兩套格式一份給人/模型看一份給代碼邏輯用。6.6 如果一個功能只適合“整文件硬啃”別硬犟最后想說一個心態(tài)問題。ast-outline大幅度提升了Agent在大型代碼文件上的表現(xiàn)但它沒有解決所有問題。有些代碼修改本身需要全文件視野比如把整個類從“同步實現(xiàn)”重構(gòu)為“異步實現(xiàn)”改變所有成員方法簽名。這種情況下按函數(shù)片段讀取會遺漏調(diào)用點造成大量重構(gòu)錯誤。我現(xiàn)在的判斷標準是修改點是局部還是全局如果目標只影響文件里一個符號用outline如果目標是全局性重構(gòu)那就老老實實整文件讀取甚至要用多文件聯(lián)合索引。AI編程Agent的代碼讀取策略永遠應(yīng)該跟著任務(wù)的邊界走而不是跟著某個工具走。如果讓我只保留一條經(jīng)驗我會說給Agent喂代碼和管理人類閱讀代碼是一個道理沒人會捧著一整本書去找一句話先看目錄再翻頁必要時才讀整章。想明白這一點ast-outline是否被采用就不重要了因為你隨時可以照這個思路做出自己的版本。