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