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