1. 為什么“配置”才是把 Pi 變成主力的分水嶺很多人第一次接觸 Pi 這類編碼代理工具注意力幾乎全放在“它能不能寫代碼”“模型強(qiáng)不強(qiáng)”上結(jié)果裝完、跑通一個 demo 就擱置了。我一開始也這樣直到有段時間被一個重復(fù)性的重構(gòu)任務(wù)折磨得不行才回頭認(rèn)真研究它的配置文件。結(jié)論很直接Pi 的上限不取決于你用的是哪個模型而取決于你把它“調(diào)教”到什么程度。同一套模型配置得好和配置得差產(chǎn)出質(zhì)量能差出一個量級。這篇是實(shí)戰(zhàn)系列的第一篇只聊配置。我會把settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md這幾個核心文件拆開講清楚它們各自管什么、為什么這么設(shè)計、字段怎么填、哪些地方最容易踩坑。目標(biāo)很明確——讓你讀完能把自己的 Pi 從“玩具”變成每天真正會打開的主力工具。不管你是剛裝好還沒動過配置的新手還是已經(jīng)用了一陣但總覺得“差點(diǎn)意思”的老用戶這篇都能給你可抄的作業(yè)。先說一個反直覺的點(diǎn)配置的核心不是“告訴 Pi 它能做什么”而是“約束它不要做什么”。大多數(shù)人配置失敗是因?yàn)榘雅渲梦募?dāng)成了功能清單拼命往里塞能力而真正讓 Pi 變好用的是邊界、上下文和默認(rèn)行為的設(shè)定。理解了這一點(diǎn)后面所有字段的取舍都會變得清晰。2. 四個配置文件的分工誰管行為、誰管模型、誰管記憶在動手改任何東西之前得先搞清楚這幾個文件不是平級的它們處在不同的抽象層。很多人把它們混著改改到最后自己都忘了哪條規(guī)則生效這是配置混亂的根源。2.1 settings.json全局行為的總開關(guān)settings.json是 Pi 的主配置入口管的是運(yùn)行時行為——比如默認(rèn)用哪個模型、超時時間、日志級別、是否自動執(zhí)行某些操作、工具調(diào)用的權(quán)限邊界等。你可以把它理解成“操作系統(tǒng)的控制面板”它不定義能力本身而是定義能力怎么被調(diào)用。我建議這個文件保持精簡。新手常犯的錯是把所有能想到的開關(guān)都打開結(jié)果行為變得不可預(yù)測。一個務(wù)實(shí)的做法是只配置你當(dāng)前工作流真正需要的項(xiàng)其余保持默認(rèn)等遇到具體問題再回來加。2.2 models.json模型路由與參數(shù)的中樞models.json專門管模型。它定義有哪些模型可用、各自的接入?yún)?shù)、上下文窗口、默認(rèn)溫度、以及什么場景下路由到哪個模型。這是“配置篇”里技術(shù)含量最高的一塊因?yàn)樗苯記Q定成本和效果的平衡。一個常見的誤區(qū)是只配一個“最強(qiáng)模型”然后所有任務(wù)都用它。實(shí)測下來這種做法既慢又貴而且對簡單任務(wù)反而是負(fù)優(yōu)化——強(qiáng)模型在瑣碎任務(wù)上容易“想太多”。合理的做法是按任務(wù)類型分層后面第 4 節(jié)會詳細(xì)展開。2.3 AGENTS.md項(xiàng)目級的“團(tuán)隊(duì)約定”AGENTS.md是放在項(xiàng)目根目錄的約定文件描述這個項(xiàng)目的結(jié)構(gòu)、技術(shù)棧、編碼規(guī)范、目錄約定、常用命令等。它的作用是讓 Pi 在進(jìn)入一個具體項(xiàng)目時快速獲得這個項(xiàng)目的“背景知識”而不是每次都從零猜測。這個文件的價值在多人協(xié)作或長期項(xiàng)目里尤其明顯。你寫一次之后每次讓 Pi 干活它都自動帶著這些上下文省掉大量重復(fù)解釋。它本質(zhì)上是“項(xiàng)目記憶”的載體。2.4 APPEND_SYSTEM.md追加到系統(tǒng)提示的“私貨”APPEND_SYSTEM.md的內(nèi)容會被追加到系統(tǒng)提示詞后面用來注入你個人的、跨項(xiàng)目的偏好。比如你希望 Pi 永遠(yuǎn)用某種代碼風(fēng)格、永遠(yuǎn)先給方案再動手、永遠(yuǎn)不要自作主張刪文件——這些跨項(xiàng)目的通用約束放這里最合適。它和AGENTS.md的區(qū)別要記牢AGENTS.md是項(xiàng)目級的APPEND_SYSTEM.md是用戶級的。前者跟著項(xiàng)目走后者跟著你走。搞混這兩個就會出現(xiàn)“換個項(xiàng)目規(guī)則就失效”或者“個人偏好污染了團(tuán)隊(duì)項(xiàng)目”的問題。文件作用域管什么改動頻率settings.json全局/用戶級運(yùn)行時行為、權(quán)限、默認(rèn)項(xiàng)低models.json全局/用戶級模型清單、路由、參數(shù)中AGENTS.md項(xiàng)目級項(xiàng)目結(jié)構(gòu)、規(guī)范、命令隨項(xiàng)目APPEND_SYSTEM.md用戶級跨項(xiàng)目個人偏好低提示改配置前先備份。這幾個文件一旦寫錯格式Pi 可能直接啟動異常而報錯信息往往不會直接指向出錯的那一行。3. settings.json 實(shí)戰(zhàn)從默認(rèn)值到“順手”的那幾項(xiàng)settings.json的字段很多但真正影響日常體驗(yàn)的就那么幾個。我把它們按“必調(diào)”和“按需調(diào)”分開說避免你被一堆選項(xiàng)淹沒。3.1 必調(diào)項(xiàng)默認(rèn)模型與超時默認(rèn)模型決定了你敲下命令后第一反應(yīng)由誰處理。如果你按第 4 節(jié)做了模型分層這里就填那個“通用主力”模型。超時時間則要根據(jù)你的網(wǎng)絡(luò)和模型響應(yīng)速度來定——設(shè)太短長任務(wù)被誤殺設(shè)太長卡住時你干等。我的經(jīng)驗(yàn)值是給復(fù)雜任務(wù)留足余量寧可長一點(diǎn)因?yàn)?Pi 卡住時通常會有其他信號提示而不是靠超時兜底。這里有個細(xì)節(jié)超時不要設(shè)成全局統(tǒng)一值。如果配置支持按任務(wù)類型區(qū)分就給輕量任務(wù)短超時、重任務(wù)長超時。統(tǒng)一值必然在某一端上不合適。3.2 權(quán)限邊界自動執(zhí)行到什么程度這是最需要謹(jǐn)慎的一項(xiàng)。Pi 能執(zhí)行命令、改文件權(quán)限給太松它可能在你沒注意時動了不該動的東西給太緊每步都要你確認(rèn)效率又沒了。我的建議是分階段初期所有寫操作和命令執(zhí)行都要求確認(rèn)先觀察它的行為模式。熟悉后把只讀操作、測試命令、格式化命令設(shè)為自動寫文件和刪除操作仍保留確認(rèn)。穩(wěn)定后對信任的項(xiàng)目可以放開更多但刪除、覆蓋、推送這類不可逆操作永遠(yuǎn)保留人工確認(rèn)。這個漸進(jìn)策略不是保守而是因?yàn)?Pi 的行為會隨模型、上下文、提示詞變化你無法保證它永遠(yuǎn)按你預(yù)期行事。保留關(guān)鍵確認(rèn)點(diǎn)是給自己留后路。3.3 日志與可觀測性很多人忽略日志配置出問題時兩眼一抹黑。建議把日志級別調(diào)到能看清“它為什么這么做”的程度——至少能看到它調(diào)用了哪些工具、讀了哪些文件、路由到了哪個模型。這些信息在排查“為什么它沒按我說的做”時是決定性的。日志文件位置也要固定下來方便你事后翻。我習(xí)慣按天切分出問題時直接定位到當(dāng)天。3.4 一個容易忽略的點(diǎn)工作目錄與上下文范圍Pi 默認(rèn)會讀取工作目錄下的文件作為上下文。如果工作目錄設(shè)得太寬比如整個用戶目錄它會讀到大量無關(guān)文件既拖慢速度又干擾判斷設(shè)得太窄又可能漏掉關(guān)鍵依賴。正確做法是把工作目錄限定在當(dāng)前項(xiàng)目根目錄需要跨項(xiàng)目時再顯式指定。這個設(shè)置看起來不起眼但它對輸出質(zhì)量的影響比很多人想象的大。上下文里塞滿無關(guān)內(nèi)容模型注意力會被稀釋這是實(shí)測能明顯感覺到的。4. models.json 的模型分層別用一個模型打天下模型配置是“配置篇”里最能體現(xiàn)功力的一塊。我見過太多人只配一個模型然后抱怨“要么太慢要么太貴要么不夠聰明”。問題不在模型在于你沒做分層。4.1 按任務(wù)類型分三層我的做法是把任務(wù)粗分成三層每層對應(yīng)不同的模型和參數(shù)輕量層格式化、重命名、簡單查找替換、生成注釋。這類任務(wù)要的是快和便宜用響應(yīng)快的小模型溫度調(diào)低保證穩(wěn)定。通用層日常編碼、重構(gòu)、寫測試、解釋代碼。這是主力層用綜合能力均衡的模型溫度適中。重載層架構(gòu)設(shè)計、復(fù)雜調(diào)試、跨文件大改。這類任務(wù)用最強(qiáng)模型溫度可以略高一點(diǎn)以激發(fā)推理但要接受它更慢更貴。分層之后你在settings.json里設(shè)的默認(rèn)模型就是通用層遇到重活再顯式切換。這樣日常使用成本可控關(guān)鍵時刻又不掉鏈子。4.2 上下文窗口與截斷策略每個模型都有上下文窗口上限。配置時要明確當(dāng)上下文超限時是截斷、摘要還是報錯。默認(rèn)截斷最危險因?yàn)樗赡芮那膩G掉關(guān)鍵信息導(dǎo)致 Pi 基于不完整上下文做出錯誤判斷。我的建議是配置成“接近上限時提示并摘要”讓 Pi 主動壓縮歷史而不是硬截斷。這樣雖然多一步但能保證它始終基于完整語義工作。4.3 溫度與采樣參數(shù)怎么定溫度這個參數(shù)被討論得很多但很多人設(shè)了就忘。經(jīng)驗(yàn)值需要確定性輸出的任務(wù)格式化、生成配置、寫測試斷言溫度 0 到 0.2。日常編碼和解釋0.3 到 0.5。需要發(fā)散思考的任務(wù)方案設(shè)計、頭腦風(fēng)暴0.7 以上。關(guān)鍵是按模型分別設(shè)而不是全局一個值。不同模型對溫度的敏感度不一樣照搬數(shù)值往往效果打折。4.4 路由規(guī)則讓 Pi 自己選模型如果配置支持條件路由強(qiáng)烈建議用起來。比如按文件類型、按任務(wù)關(guān)鍵詞、按項(xiàng)目自動切換模型。這樣你不需要每次手動指定Pi 會根據(jù)規(guī)則自己選。規(guī)則要寫得具體避免模糊匹配導(dǎo)致誤路由。一個實(shí)用的路由例子涉及測試文件的操作走輕量層涉及核心業(yè)務(wù)邏輯的走通用層涉及架構(gòu)文件的走重載層。規(guī)則不用多覆蓋高頻場景即可。5. AGENTS.md 怎么寫才算“有用”AGENTS.md是很多人寫了但沒寫對的文件。常見問題是寫成了一份 README 的復(fù)制粘貼堆了一堆對 Pi 干活沒幫助的信息。它應(yīng)該是一份給代理看的操作手冊不是給人看的項(xiàng)目介紹。5.1 必須包含的四類信息一份有效的AGENTS.md至少覆蓋項(xiàng)目結(jié)構(gòu)與關(guān)鍵目錄告訴 Pi 代碼在哪、測試在哪、配置在哪、文檔在哪。它不需要你列全但關(guān)鍵路徑要有。技術(shù)棧與版本約束用什么語言、什么框架、什么版本。版本信息尤其重要因?yàn)椴煌姹镜?API 差異會讓 Pi 寫出跑不通的代碼。編碼規(guī)范與約定命名風(fēng)格、目錄組織、提交信息格式、注釋要求。這些是“團(tuán)隊(duì)約定”Pi 必須遵守。常用命令構(gòu)建、測試、格式化、啟動的命令。寫清楚Pi 就不用猜。5.2 寫法上的三個原則第一具體優(yōu)于籠統(tǒng)?！笆褂靡恢碌拿L(fēng)格”是廢話“組件文件用 PascalCase工具函數(shù)用 camelCase”才有用。第二給例子優(yōu)于給規(guī)則。一條規(guī)則配一個正例一個反例Pi 理解得更準(zhǔn)。第三保持更新。項(xiàng)目結(jié)構(gòu)變了、命令改了AGENTS.md要同步否則它會基于過時信息干活比沒有還糟。5.3 一個真實(shí)的反面案例我見過一個項(xiàng)目的AGENTS.md寫了三百多行把每個文件的用途都列了一遍。結(jié)果 Pi 每次都要讀這一大坨上下文被占滿真正重要的規(guī)范反而被淹沒。后來精簡到四十行只留結(jié)構(gòu)、規(guī)范、命令效果立刻好轉(zhuǎn)。AGENTS.md不是越全越好是越準(zhǔn)越好。注意AGENTS.md放在項(xiàng)目根目錄才會被自動讀取。放在子目錄里除非配置了遞歸查找否則不生效。這個坑我踩過排查了半天才發(fā)現(xiàn)是位置問題。6. APPEND_SYSTEM.md把你的偏好變成默認(rèn)行為如果說AGENTS.md是項(xiàng)目記憶APPEND_SYSTEM.md就是你的個人印記。它追加在系統(tǒng)提示之后優(yōu)先級高影響所有項(xiàng)目。用好了Pi 會越來越像“你的”助手用不好會到處制造沖突。6.1 適合放什么跨項(xiàng)目通用的偏好最適合放這里交互風(fēng)格比如“先給方案再動手”“不確定時先問而不是猜”。輸出格式比如“代碼塊標(biāo)注語言”“解釋用中文代碼注釋用英文”。安全約束比如“不要自動刪除文件”“不要執(zhí)行網(wǎng)絡(luò)請求”。工作習(xí)慣比如“改代碼前先讀相關(guān)測試”“提交前跑格式化”。這些內(nèi)容不依賴具體項(xiàng)目放全局最省事。6.2 不適合放什么項(xiàng)目相關(guān)的規(guī)范不要放這里那是AGENTS.md的活。具體的技術(shù)棧約束也不要放否則換個項(xiàng)目就沖突。APPEND_SYSTEM.md越短越通用越好我自己的這份控制在二十行以內(nèi)只保留最核心的幾條。6.3 優(yōu)先級沖突怎么處理當(dāng)APPEND_SYSTEM.md和AGENTS.md沖突時通常系統(tǒng)提示優(yōu)先級更高。這意味著如果你在APPEND_SYSTEM.md里寫了“永遠(yuǎn)用某種風(fēng)格”而項(xiàng)目AGENTS.md要求另一種項(xiàng)目規(guī)范可能被覆蓋。所以寫全局偏好時要克制只寫那些真正跨項(xiàng)目成立的約束。一個實(shí)用技巧在APPEND_SYSTEM.md里加一條“項(xiàng)目級AGENTS.md的規(guī)范優(yōu)先于本文件的通用偏好”這樣能避免大部分沖突。7. 配置生效驗(yàn)證與常見故障排查配置寫完不代表生效。我見過太多人改完文件就以為萬事大吉結(jié)果跑起來還是老行為。這一節(jié)講怎么驗(yàn)證以及出問題怎么查。7.1 驗(yàn)證配置是否被讀取最直接的辦法是讓 Pi 復(fù)述它的當(dāng)前配置或行為規(guī)則。比如問它“你現(xiàn)在默認(rèn)用哪個模型”“你的編碼規(guī)范是什么”。如果回答和你配置的一致說明生效了如果還是默認(rèn)行為說明文件沒被讀到或格式有問題。另一個辦法是看啟動日志通常會打印加載了哪些配置文件。日志里沒有的文件就是沒生效的文件。7.2 格式錯誤的典型表現(xiàn)JSON 文件最常見的錯誤是多余逗號、引號不匹配、注釋標(biāo)準(zhǔn) JSON 不支持注釋。這些錯誤往往導(dǎo)致整個文件被忽略而不是報錯退出。表現(xiàn)就是“改了沒反應(yīng)”。所以改完 JSON 一定要用工具校驗(yàn)一遍別靠肉眼。Markdown 文件的問題通常是編碼或換行符。如果文件是 Windows 換行符而系統(tǒng)期望 Unix可能讀取異常。統(tǒng)一用 UTF-8 和 Unix 換行最穩(wěn)。7.3 配置不生效的排查順序按這個順序查基本能定位文件位置對不對AGENTS.md在項(xiàng)目根目錄嗎。文件名拼寫對不對大小寫敏感。格式能不能通過校驗(yàn)。有沒有被更高優(yōu)先級的配置覆蓋。需不需要重啟或重新加載才生效。這五步走完九成問題都能解決。剩下的一成通常是多個配置互相沖突需要逐條注釋掉來定位。7.4 一個隱蔽的坑緩存有些實(shí)現(xiàn)會緩存配置改完文件不重啟不生效。如果你確認(rèn)文件沒問題但行為沒變先試試重啟。這個坑很隱蔽因?yàn)槟銜恢睉岩墒亲约簩戝e了其實(shí)是緩存沒刷新。8. 我踩過的幾個配置坑和最終穩(wěn)定下來的方案最后分享幾個真實(shí)踩過的坑都是文檔里不會寫、但實(shí)際會遇到的。第一個坑是過度配置。剛開始我恨不得把每個字段都填滿結(jié)果行為變得難以預(yù)測出問題也不知道是哪條配置導(dǎo)致的。后來砍到只剩必要的幾項(xiàng)反而穩(wěn)定了。配置的原則是“最小可用”需要時再加。第二個坑是模型分層沒做全用最強(qiáng)模型。結(jié)果是簡單任務(wù)慢得讓人抓狂成本也高。分層之后日常體驗(yàn)提升非常明顯而且成本降下來了。第三個坑是**AGENTS.md寫太滿**。前面提過三百行精簡到四十行效果反而更好。上下文是稀缺資源別浪費(fèi)在無關(guān)信息上。第四個坑是權(quán)限放太開。有一次讓 Pi 自動執(zhí)行它把一個我還沒提交的改動覆蓋了。從那以后不可逆操作我一律保留確認(rèn)。這個習(xí)慣救過我很多次。最終我穩(wěn)定下來的方案是settings.json只留默認(rèn)模型、超時、權(quán)限邊界和日志四項(xiàng)models.json做三層模型加簡單路由AGENTS.md每個項(xiàng)目控制在五十行內(nèi)只寫結(jié)構(gòu)、規(guī)范、命令A(yù)PPEND_SYSTEM.md二十行以內(nèi)只寫跨項(xiàng)目偏好。這套配置用了大半年基本沒再大改過。如果你剛開始配建議就從這套最小方案起步跑一段時間遇到具體問題再針對性調(diào)整。配置不是一次性的活是隨著你使用習(xí)慣慢慢長出來的。下一篇我會聊實(shí)際使用中的工作流和提示詞技巧那才是配置真正發(fā)揮價值的地方。