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