戰(zhàn)：subagent編排、skill導(dǎo)入與本地RAG搭建)
1. 先把這個(gè)pi說(shuō)清楚最近這段時(shí)間pi在我的開發(fā)者朋友圈里出現(xiàn)頻率高得嚇人。有人在群里曬 pi agent 自動(dòng)改完一個(gè) PR 的截圖有人討論 pi coding agent 拆 subagent 的技巧還有人問(wèn) oh my pi 桌面版在哪下載。我做開發(fā)十幾年第一反應(yīng)是又一個(gè)套殼工具但實(shí)際用了一周之后我承認(rèn)這工具確實(shí)有獨(dú)到的地方。這篇文章不講產(chǎn)品發(fā)布稿里那套話就從普通用戶的角度把 Pi 是什么、能解決什么問(wèn)題、怎么上手、subagent 和 skill 怎么玩、有哪些坑全部攤開講一遍。你可能剛聽說(shuō)這個(gè)詞也可能已經(jīng)在用同類工具想橫向?qū)Ρ冗@兩種讀者我都盡量照顧到。文章里的路徑、配置和操作步驟基于我本地實(shí)測(cè)和官方文檔整理出來(lái)不同版本之間可能有細(xì)微差別但整體思路是通用的換到別的 agent 工具上也能參考。1.1 它不是一個(gè)聊天窗口而是一個(gè)能自己動(dòng)手的實(shí)習(xí)生Pi 最簡(jiǎn)單的理解是一個(gè)能自主執(zhí)行任務(wù)的編碼智能體。它和聊天 AI 最大的區(qū)別在于它不只是你問(wèn)一句它答一句而是能自己讀代碼庫(kù)、搜索文件、修改代碼、執(zhí)行命令、看測(cè)試結(jié)果再根據(jù)結(jié)果繼續(xù)迭代。你交代一個(gè)目標(biāo)它會(huì)自己走完理解需求、查資料、動(dòng)手改、自我驗(yàn)證、匯報(bào)結(jié)果這一整條鏈路。我用一個(gè)比喻跟朋友解釋這就像你給團(tuán)隊(duì)招了個(gè)實(shí)習(xí)生。你把任務(wù)交代清楚他自己去翻資料、動(dòng)手做把成果拿給你 review。你要做的是把需求拆到足夠清楚并且在他跑偏的時(shí)候及時(shí)喊停。這個(gè)定位決定了它的使用方式——不是問(wèn)問(wèn)題而是派活。你負(fù)責(zé)判斷方向他負(fù)責(zé)執(zhí)行和試錯(cuò)配合得好效率是成倍的。反過(guò)來(lái)如果需求本身一團(tuán)漿糊那再?gòu)?qiáng)的 agent 也只會(huì)給你交出一團(tuán)更精致的漿糊。1.2 和 Cursor、Claude Code 這類工具相比它的差異在哪市面上的 AI 編程工具很多按干活方式大體能分三類。對(duì)話式助手只給答案不碰你的工程IDE 內(nèi)嵌 AI 在你寫代碼的時(shí)候補(bǔ)全、改文件終端里的 agent 類工具能獨(dú)立執(zhí)行任務(wù)。Pi 屬于第三類但它的特點(diǎn)在于多智能體設(shè)計(jì)你可以拆出專門的 subagent讓它們像不同崗位的工程師一樣并行工作由主 agent 做統(tǒng)一協(xié)調(diào)。我按自己平時(shí)使用的體感做個(gè)直觀對(duì)比工具類型典型代表干活方式最適合的場(chǎng)景對(duì)話式助手各類聊天 AI只輸出文字答案查資料、寫小片段IDE 內(nèi) AICursor、Copilot 系在編輯器里補(bǔ)全、改代碼人主導(dǎo)編碼AI 當(dāng)副駕終端編碼智能體Pi、Claude Code 這類自主讀代碼、執(zhí)行命令、多角色協(xié)作把完整任務(wù)交給 AI 自動(dòng)完成實(shí)際體驗(yàn)下來(lái)Pi 最抓我的一點(diǎn)不是單次代碼生成質(zhì)量而是它能把一個(gè)大任務(wù)拆成若干子任務(wù)交給不同身份的 subagent 并行處理。這種模式在處理跨模塊重構(gòu)、批量補(bǔ)測(cè)試、查歷史 bug 這類牽一發(fā)動(dòng)全身的任務(wù)時(shí)優(yōu)勢(shì)特別明顯。單點(diǎn)寫代碼的能力各家差距其實(shí)不大真正比拼的是編排能力也就是讓多個(gè)角色各干各的、最后還能嚴(yán)絲合縫拼起來(lái)的能力。1.3 什么人適合馬上上手我覺得下面三類人可以重點(diǎn)試試。第一類是日常寫代碼經(jīng)常要跨多個(gè)文件改動(dòng)的開發(fā)者這類活兒最費(fèi)神剛好是 agent 的強(qiáng)項(xiàng)。第二類是做技術(shù)調(diào)研和落地驗(yàn)證的人讓 Pi 自己拉代碼、跑示例、寫總結(jié)效率比手動(dòng)搜索高一個(gè)量級(jí)。第三類是剛?cè)腴T、還在猶豫怎么用 AI 提效的新手桌面版帶圖形界面比純命令行友好得多。當(dāng)然不適合的人也有完全不懂代碼、只想一鍵生成整個(gè) App的人大概率會(huì)被 agent 的連環(huán)追問(wèn)和 review 要求勸退。原因很簡(jiǎn)單agent 是執(zhí)行者不是許愿機(jī)。它把一大段代碼交給你你得有基本能力判斷好不好、能不能跑。這部分能力決定你能不能用好它沒有捷徑。2. 五分鐘上手裝桌面版、配環(huán)境、跑通第一個(gè)任務(wù)2.1 桌面版下載與安裝先說(shuō)安裝。去 Pi 官網(wǎng)的下載頁(yè)按自己系統(tǒng)選安裝包就行Windows 是 exemacOS 是 dmgApple Silicon 記得選 arm64 版本Linux 一般是 tar.gz 或 AppImage。我個(gè)人建議直接到官方 release 頁(yè)拿最新版用系統(tǒng)包管理器裝容易滯后一兩個(gè)版本而這類工具迭代非?？彀姹静钜粋€(gè)月體驗(yàn)可能差很多。很多人提到的Oh My Pi其實(shí)是社區(qū)做的一套配置管理腳本類似 oh-my-zsh 之于 zsh 的關(guān)系。它能把主題、快捷鍵、常用參數(shù)統(tǒng)一管理起來(lái)適合喜歡折騰的人。如果你只是想先用起來(lái)默認(rèn)配置完全夠不需要第一步就上這套。安裝完成后首次啟動(dòng)會(huì)有一個(gè)初始化向?qū)ё屇氵x工作目錄、默認(rèn)模型以及一個(gè)很關(guān)鍵的選項(xiàng)命令自動(dòng)執(zhí)行權(quán)限。我的建議是第一次先把自動(dòng)執(zhí)行關(guān)掉讓 agent 處于只讀觀察模式等它在你眼皮底下跑過(guò)幾輪、確認(rèn)不會(huì)亂來(lái)之后再逐步放開權(quán)限。2.2 模型配置和憑證認(rèn)證Pi 支持接入多種模型來(lái)源包括云端的 API也包括本地運(yùn)行的模型。配置里最核心就三樣?xùn)|西接口地址、模型名、憑證。下面是我本地環(huán)境里的一份配置示例{ provider: openai-compatible, base_url: http://127.0.0.1:11434/v1, api_key: sk-local-demo, model: qwen2.5-coder:32b, temperature: 0.2 }base_url 指向本地模型的兼容接口api_key 填一個(gè)占位符就行整個(gè)鏈路在本地閉環(huán)不需要數(shù)據(jù)出本機(jī)。如果你用的是云服務(wù)商的模型就要填真實(shí)的接口地址和 key。這里有個(gè)很容易踩的坑key 填錯(cuò)時(shí) agent 不會(huì)直接報(bào)錯(cuò)而是會(huì)反復(fù)重試表現(xiàn)出一堆莫名其妙的思考行為。所以配置完一定要先點(diǎn)測(cè)試連接確認(rèn)通了再進(jìn)項(xiàng)目這一步能省掉后面半小時(shí)的排查時(shí)間。模型選擇上如果機(jī)器配置一般優(yōu)先選帶 coder 后綴的小參數(shù)模型響應(yīng)快適配 agent 場(chǎng)景比通用對(duì)話模型穩(wěn)得多。機(jī)器好的可以上 32B 以上級(jí)別復(fù)雜推理能力會(huì)有肉眼可見的提升。溫度參數(shù)我習(xí)慣調(diào)低到 0.2 左右agent 任務(wù)追求確定性溫度太高容易放飛自我。2.3 跑通第一個(gè)任務(wù)配置完找一個(gè)小項(xiàng)目試水。我建議第一個(gè)任務(wù)別太野就拿你熟悉的倉(cāng)庫(kù)讓它做信息整理。例如pi 先讀一下當(dāng)前項(xiàng)目的 README 和 src 目錄梳理模塊結(jié)構(gòu)輸出一份總結(jié)你可以看到它先列目錄再挑文件讀最后生成總結(jié)。我第一次用的時(shí)候最直觀的感受是它真的會(huì)拆解動(dòng)作——不是一次性吐一大段文字而是先告訴你我打算先看配置文件再讀入口模塊然后一步一步執(zhí)行。這個(gè)過(guò)程中你隨時(shí)可以打斷它糾正方向。第一個(gè)任務(wù)跑通后你對(duì)它的工作節(jié)奏就有感覺了它更像一個(gè)需要你盯著的執(zhí)行者而不是放出去就不用管的自動(dòng)機(jī)。2.4 第一次使用必須知道的三個(gè)注意事項(xiàng)這一節(jié)的內(nèi)容都是我付過(guò)學(xué)費(fèi)換來(lái)的建議看一眼。第一工作目錄越小越好。別把整個(gè) home 目錄丟給它否則它會(huì)在無(wú)關(guān)文件里浪費(fèi)時(shí)間token 消耗也快得驚人。第二任何自動(dòng)執(zhí)行命令的能力都必須在虛擬環(huán)境或容器里放開不要把生產(chǎn)環(huán)境直接暴露給它它的一次誤操作可能比你手動(dòng)十次還快。第三所有改動(dòng)都要有版本控制兜底哪怕是臨時(shí)實(shí)驗(yàn)也先 git init 再說(shuō)。做到這三點(diǎn)后面再怎么折騰都不會(huì)出大亂子。3. 進(jìn)階玩法Subagent 編排與 Skill 導(dǎo)入3.1 主智能體和子智能體到底怎么配合Pi 的多智能體機(jī)制是它最值得玩的部分。簡(jiǎn)單說(shuō)主 agent 負(fù)責(zé)理解你的總目標(biāo)、拆解計(jì)劃、匯總結(jié)果subagent 是被臨時(shí)拉起來(lái)的專職角色各自有獨(dú)立的上下文窗口和工具權(quán)限。這樣一個(gè) subagent 埋頭查代碼的時(shí)候另一個(gè) subagent 已經(jīng)在寫測(cè)試了互不干擾。類比的話主 agent 是項(xiàng)目經(jīng)理subagent 是不同工種的施工隊(duì)而你才是那個(gè)拍板的人。項(xiàng)目經(jīng)理不會(huì)把所有施工隊(duì)叫到一個(gè)會(huì)議室里開大會(huì)而是分別傳達(dá)任務(wù)、分別驗(yàn)收。這樣做的最大好處是上下文隔離——每個(gè) subagent 只需要關(guān)心自己負(fù)責(zé)的那一小塊不會(huì)因?yàn)閷?duì)話太長(zhǎng)而把前面的指令忘掉。我見過(guò)很多人抱怨agent 用著用著就變傻仔細(xì)一看全是把幾百個(gè)文件的閱讀全都?jí)涸谕粋€(gè)上下文里不傻才怪。3.2 一個(gè) subagent 配置文件長(zhǎng)什么樣subagent 在 Pi 里一般通過(guò)配置文件定義。下面是我項(xiàng)目里一個(gè)后端開發(fā)角色的配置格式做了簡(jiǎn)化字段名不同版本可能有差異但結(jié)構(gòu)思路是通用的--- name: backend-dev description: 負(fù)責(zé)后端模塊開發(fā)、接口實(shí)現(xiàn)與單元測(cè)試 tools: [read, search, edit, run, test] --- 你是項(xiàng)目里的資深后端工程師主要使用 Python 和 FastAPI。 工作規(guī)范 - 動(dòng)手前必須先列出要改動(dòng)的文件清單 - 每個(gè)接口實(shí)現(xiàn)后必須補(bǔ)測(cè)試 - 禁止修改與任務(wù)無(wú)關(guān)的模塊 - 依賴不明確時(shí)先查 requirements.txt 再?zèng)Q定不要自行假定配置里最重要的不是 role 描述寫得多華麗而是 tools 權(quán)限列表。列表越窄越不容易出事故。比如只給它 read、search、edit 三個(gè)權(quán)限它就沒辦法執(zhí)行命令自然干不了刪庫(kù)這種壞事。這是我從翻車經(jīng)歷里總結(jié)出來(lái)的。role 描述部分則要用具體名詞和規(guī)則去約束行為越具象越穩(wěn)定模糊的形容詞反而容易讓模型自由發(fā)揮。每個(gè) subagent 干完活你還得讓它在匯報(bào)里寫清楚改了什么、為什么這么改方便你 review。3.3 用 Web 控制臺(tái)導(dǎo)入 Skill 的完整流程Skill 的概念很好理解就是給 agent 預(yù)裝的操作手冊(cè)。它把一套成熟的工作流打包成角色設(shè)定 規(guī)則 模板別人寫好了你可以直接導(dǎo)入。比如代碼評(píng)審skill會(huì)把評(píng)審步驟、輸出格式、問(wèn)題分級(jí)標(biāo)準(zhǔn)都定義好agent 一調(diào)就能用不用你每次重新交代一遍。pi web 導(dǎo)入 skill這個(gè)操作我實(shí)際走了一遍流程是這樣的啟動(dòng)桌面版之后在瀏覽器里打開本地控制臺(tái)頁(yè)面找到技能市場(chǎng)搜索你需要的 skill點(diǎn)導(dǎo)入后它會(huì)自動(dòng)同步到本地技能目錄一般放在用戶目錄下的.pi/skills/或者項(xiàng)目里的.pi/skills/最后重啟當(dāng)前會(huì)話在對(duì)話里用斜杠命令調(diào)用。不同版本的界面可能有差異但整體流程大差不差。一個(gè) skill 在本地通常是一個(gè)獨(dú)立目錄結(jié)構(gòu)類似~/.pi/skills/ └── code-review/ ├── SKILL.md ├── templates/ │ └── issue-list.md └── scripts/ └── collect_changed_files.pySKILL.md 是核心里面定義了觸發(fā)詞、執(zhí)行步驟和輸出格式。我抄一段簡(jiǎn)化示例--- name: code-review description: 掃描指定范圍代碼輸出問(wèn)題清單與優(yōu)先級(jí) --- 執(zhí)行步驟 1. 先用 git diff 獲取變更文件列表 2. 逐個(gè)文件做增量評(píng)審 3. 按 嚴(yán)重/一般/建議 三級(jí)輸出導(dǎo)入第三方 skill 之前務(wù)必看一眼 SKILL.md 里申請(qǐng)了哪些工具權(quán)限。尤其是帶 run 權(quán)限的等于把執(zhí)行命令的能力交給了別人的腳本風(fēng)險(xiǎn)很高。我自己只導(dǎo)入那些明確不含危險(xiǎn)操作的 skill其他一律先打開源碼確認(rèn)再?zèng)Q定。skill 是可以自己寫的把團(tuán)隊(duì)里反復(fù)用到的工作流沉淀成一個(gè) skill比口頭交代靠譜得多。3.4 什么時(shí)候拆 subagent什么時(shí)候不拆很多新手一上來(lái)就把所有任務(wù)都拆給 subagent結(jié)果發(fā)現(xiàn)反而更慢。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單看任務(wù)粒度。改一個(gè)函數(shù)、修一個(gè)文案主 agent 直接做就行拆 subagent 的開銷比干活本身還大?？缒K重構(gòu)、批量補(bǔ)測(cè)試、查歷史問(wèn)題這類大任務(wù)才值得拆。任務(wù)類型是否需要拆原因修改單個(gè)函數(shù)不拆單線程最快拆了純耗 token跨模塊重構(gòu)拆每個(gè)模塊一個(gè)角色上下文隔離批量寫測(cè)試拆測(cè)試與實(shí)現(xiàn)并行效率翻倍排查歷史 bug拆讓 subagent 專門翻 git log專注不跑神記住一句話拆 subagent 不是目的控制上下文才是目的。哪個(gè)方案能讓每個(gè)智能體專注在最小范圍里就用哪個(gè)方案。有時(shí)候你看著它不并行但實(shí)際上它省下的 token 和避免的沖突比并行省的時(shí)間更有價(jià)值。4. 實(shí)戰(zhàn)復(fù)盤用 Pi 從零搭一個(gè)本地問(wèn)答 API4.1 項(xiàng)目需求和任務(wù)拆解光聊概念沒意思我拿一個(gè)真實(shí)小項(xiàng)目說(shuō)下完整過(guò)程。需求很簡(jiǎn)單做一個(gè)極簡(jiǎn)的本地 RAG檢索增強(qiáng)生成問(wèn)答接口。把某個(gè)目錄下的一堆 Markdown 文檔當(dāng)成知識(shí)庫(kù)提供一個(gè) POST 接口用戶提問(wèn)題系統(tǒng)先檢索出最相關(guān)的片段再交給大模型生成答案最后返回答案和來(lái)源路徑。這個(gè)項(xiàng)目不涉及任何外部依賴非常適合演示 agent 的完整工作流。這個(gè)需求被我拆成三個(gè)子任務(wù)。第一個(gè)是項(xiàng)目骨架初始化包括 FastAPI 應(yīng)用和依賴清單。第二個(gè)是文檔索引模塊負(fù)責(zé)把 Markdown 按段落切塊、向量化、存到本地向量庫(kù)。第三個(gè)是問(wèn)答接口負(fù)責(zé)把檢索結(jié)果和問(wèn)題拼成 prompt調(diào)用本地模型生成回答。每個(gè)子任務(wù)對(duì)應(yīng)一個(gè) subagent最后再由主 agent 統(tǒng)一整合。拆解的過(guò)程本身其實(shí)就是架構(gòu)設(shè)計(jì)的過(guò)程對(duì) pi coding agent 說(shuō)清楚這三塊它就能各自開工。4.2 讓 Pi 動(dòng)手前的關(guān)鍵 Prompt很多人的 agent 用不好問(wèn)題出在 prompt 太含糊。需求只寫一句幫我做個(gè)問(wèn)答系統(tǒng)agent 就只能靠猜交出來(lái)的東西大概率不是你要的。我這次給 Pi 的任務(wù)描述是這么寫的項(xiàng)目本地問(wèn)答 API。 請(qǐng)按以下順序執(zhí)行 1. 創(chuàng)建 FastAPI 項(xiàng)目骨架依賴盡量少 2. 實(shí)現(xiàn) docs 目錄下 Markdown 的索引與檢索使用本地向量庫(kù)持久化 3. 實(shí)現(xiàn) POST /ask接收 question返回 answer 和 sources 4. 最后給出運(yùn)行方式和測(cè)試命令。注意這里我做了兩件事一是給了明確的執(zhí)行順序讓它先搭骨架再填血肉二是要求最后給出運(yùn)行方式和測(cè)試命令等于逼它把交付物補(bǔ)完整而不是只丟一堆代碼。這個(gè)技巧對(duì)提高 agent 交付質(zhì)量非常有效——你要求的交付物越具體它就越不會(huì)糊弄。如果你希望某個(gè)環(huán)節(jié)重點(diǎn)做比如檢索部分性能優(yōu)先也得在 prompt 里明確寫出來(lái)否則它只會(huì)按默認(rèn)方式實(shí)現(xiàn)。4.3 核心代碼從索引到問(wèn)答接口整個(gè)項(xiàng)目的核心代碼不多我把關(guān)鍵文件貼出來(lái)你照著就能跑。先是依賴清單fastapi uvicorn chromadb sentence-transformers httpx索引模塊 indexer.py 負(fù)責(zé)把 Markdown 切塊并寫入本地向量庫(kù)from pathlib import Path from hashlib import md5 import chromadb from sentence_transformers import SentenceTransformer encoder SentenceTransformer(all-MiniLM-L6-v2) client chromadb.PersistentClient(path./data/chroma) collection client.get_or_create_collection(namedocs) def build_index(docs_dir: Path): ids, chunks, metadatas [], [], [] for md in docs_dir.rglob(*.md): text md.read_text(encodingutf-8) for i, para in enumerate(text.strip().split(\n\n)): if not para.strip(): continue chunks.append(para) ids.append(md5(f{md}:{i}.encode()).hexdigest()) metadatas.append({path: str(md), chunk: i}) collection.upsert(idsids, documentschunks, metadatasmetadatas)問(wèn)答接口 main.py 這樣寫from fastapi import FastAPI from pydantic import BaseModel from indexer import collection, encoder from llm import call_llm app FastAPI() class AskRequest(BaseModel): question: str app.post(/ask) def ask(req: AskRequest): results collection.query( query_embeddings[encoder.encode(req.question).tolist()], n_results3, ) sources [m[path] for m in results[metadatas][0]] context \n---\n.join(results[documents][0]) answer call_llm(req.question, context) return {answer: answer, sources: sources}最后是調(diào)用本地模型生成回答的 llm.pyimport httpx def call_llm(question: str, context: str) - str: resp httpx.post( http://127.0.0.1:11434/v1/chat/completions, json{ model: qwen2.5:7b, messages: [ {role: system, content: 你只能根據(jù)提供的上下文回答不要編造事實(shí)。}, {role: user, content: f上下文\n{context}\n\n問(wèn)題{question}}, ], temperature: 0.2, }, timeout60, ) return resp.json()[choices][0][message][content]這個(gè)項(xiàng)目跑起來(lái)之后你往 docs 里丟幾篇 Markdown再 curl 一下接口就能看到返回里帶著答案和來(lái)源文件路徑。整個(gè)鏈路從索引到檢索到生成都在本地閉環(huán)。你也可以把向量庫(kù)換成別的存儲(chǔ)或者把 embedding 模型換大一點(diǎn)的效果更好的但整體結(jié)構(gòu)不需要?jiǎng)印?.4 調(diào)試與 Review 的實(shí)操心得這個(gè)項(xiàng)目我讓 Pi 干了大半天過(guò)程中有幾次典型的翻車正好用來(lái)講經(jīng)驗(yàn)。第一次翻車在 ChromaDB 的參數(shù)上subagent 把query_embeddings和query_texts混用了。原因是它同時(shí)參考了舊版文檔和新版文檔兩邊 API 不一樣。這種細(xì)節(jié)問(wèn)題人眼 review 一眼就能看出來(lái)但 agent 自己很難發(fā)現(xiàn)所以review 代碼這一步絕對(duì)不能省。第二次是測(cè)試用例的問(wèn)題。它寫了一個(gè) test_main.py但測(cè)試?yán)镎娴娜フ{(diào)模型接口導(dǎo)致跑測(cè)試必須先起模型服務(wù)。我讓它在測(cè)試?yán)锇?call_llm 用 monkeypatch 換掉只驗(yàn)證接口邏輯和返回結(jié)構(gòu)。這個(gè)改動(dòng)很小但對(duì)自動(dòng)化測(cè)試的可用性是決定性的。以后每次改動(dòng)都能快速回歸不用背著模型服務(wù)跑測(cè)試。我的操作習(xí)慣是第一步讓 Pi 自己跑測(cè)試把報(bào)錯(cuò)原樣貼回對(duì)話它會(huì)自己修第二步每個(gè) subagent 在獨(dú)立分支上工作最后統(tǒng)一合并避免互相覆蓋第三步合并前我親自讀一遍 diff不信任任何它說(shuō)沒問(wèn)題的結(jié)論。這套流程走下來(lái)項(xiàng)目本身不難但它把用 agent 干活的正確姿勢(shì)演示了一遍目標(biāo)明確、角色拆分、代碼審查、測(cè)試兜底這四步少一步都會(huì)還債。5. 常見問(wèn)題與排查實(shí)錄5.1 問(wèn)題速查表我把這段時(shí)間里遇到的高頻問(wèn)題整理成了一張速查表遇到類似情況可以直接對(duì)號(hào)入座?，F(xiàn)象可能原因處理辦法導(dǎo)入 skill 后對(duì)話里不出現(xiàn)當(dāng)前會(huì)話沒刷新重啟會(huì)話確認(rèn)技能目錄被識(shí)別模型答非所問(wèn)上下文被無(wú)用文件占滿限定讀取范圍用 search 代替讀全文多個(gè) subagent 改出沖突代碼都動(dòng)了公共文件公共模塊改由主 agent 統(tǒng)一執(zhí)行命令執(zhí)行到一半卡住在等用戶確認(rèn)你沒注意檢查授權(quán)配置或換更快的模型token 消耗快得離譜每次都重讀大文件提示 agent 只讀關(guān)鍵片段限制讀取數(shù)量這些問(wèn)題的根源大部分是同一個(gè)上下文管理沒做好。不是模型不行而是你把太多垃圾信息塞給了模型。想明白這一點(diǎn)排查思路就清晰了。5.2 我踩過(guò)最疼的幾個(gè)坑第一個(gè)坑是讓兩個(gè) subagent 并行改同一個(gè)文件。一個(gè)在重構(gòu)接口一個(gè)在加注釋結(jié)果后面的覆蓋了前面的。從那以后我規(guī)定公共文件只能由主 agent 改subagent 只負(fù)責(zé)自己模塊內(nèi)的文件。團(tuán)隊(duì)協(xié)作里文件所有權(quán)的概念在 agent 協(xié)作里同樣成立。第二個(gè)坑是自動(dòng)審批開得太早。當(dāng)時(shí)為了省事允許它直接執(zhí)行命令結(jié)果它為了裝依賴往系統(tǒng) Python 里塞了一堆包把環(huán)境搞得一團(tuán)糟。教訓(xùn)非常明確所有自動(dòng)執(zhí)行操作必須在虛擬環(huán)境或容器里進(jìn)行并且 run 命令要加白名單。這個(gè)白名單不是用來(lái)限制 agent 的而是用來(lái)保護(hù)你的環(huán)境的。第三個(gè)坑是上下文里積累了太多歷史包袱。同一個(gè) session 里連續(xù)跑了好幾個(gè)不相關(guān)的任務(wù)到后面它開始把上一個(gè)任務(wù)的輸出當(dāng)成參考答案越來(lái)越離譜?，F(xiàn)在我的習(xí)慣是一個(gè)大任務(wù)結(jié)束就開新會(huì)話絕不拖著舊狀態(tài)跑新任務(wù)。這個(gè)習(xí)慣看似浪費(fèi)實(shí)際上省下了大量排查錯(cuò)誤的時(shí)間屬于典型的以小換大。5.3 幾個(gè)讓體驗(yàn)翻倍的小技巧關(guān)于 agent 的行為約束我發(fā)現(xiàn)負(fù)向指令比正向指令管用得多。你告訴它不要使用 requirements.txt 之外的庫(kù)比請(qǐng)選擇合適的庫(kù)有效一百倍。因?yàn)樨?fù)向指令是一個(gè)硬邊界模型更容易遵守而正向指令給了它發(fā)揮空間發(fā)揮就意味著可能走偏。走偏一次浪費(fèi)的時(shí)間比省下的時(shí)間還多。第二個(gè)技巧是讓 agent 先寫計(jì)劃書。面對(duì)復(fù)雜任務(wù)第一輪先讓它只輸出實(shí)施計(jì)劃你確認(rèn)了再讓它動(dòng)手。這一步能在早期攔截掉大量方向性錯(cuò)誤比事后返工省錢多了。我在第一次做這個(gè) API 項(xiàng)目的時(shí)候跳過(guò)這步結(jié)果它先寫了個(gè)數(shù)據(jù)庫(kù)同步邏輯跟需求毫無(wú)關(guān)系白白浪費(fèi)了二十分鐘。第三個(gè)技巧是給 subagent 起一個(gè)具象的名字。叫backend-dev比叫assistant穩(wěn)定很多?？雌饋?lái)是玄學(xué)但實(shí)測(cè)下來(lái)身份描述的顆粒度直接影響模型的行為模式——它會(huì)更傾向于表現(xiàn)出對(duì)應(yīng)角色的專業(yè)性。名字和角色描述就是它的人設(shè)人設(shè)越清楚行為越收斂。6. 別搞混了此 pi 非彼 pi寫到這里必須插一段因?yàn)閜i這個(gè)詞在技術(shù)圈里同時(shí)指好幾樣?xùn)|西。你搜pi的時(shí)候可能一半結(jié)果是 AI 編碼智能體另一半是樹莓派或者控制理論。不把這些對(duì)應(yīng)關(guān)系理清楚看文章很容易對(duì)不上號(hào)。6.1 樹莓派玩家說(shuō)的 PiRaspberry Pi 與 RP2040熱詞里有一個(gè)raspberry pi 2040 oled 0.96說(shuō)的是用樹莓派 Pico 開發(fā)板主控芯片是 RP2040驅(qū)動(dòng)一塊 0.96 英寸 OLED 屏屏的驅(qū)動(dòng)芯片一般是 SSD1306走 I2C 接口。這類小項(xiàng)目的典型玩法是幾分鐘點(diǎn)亮屏幕顯示文字from machine import Pin, I2C import ssd1306 i2c I2C(0, sclPin(1), sdaPin(0), freq400000) oled ssd1306.SSD1306_I2C(128, 64, i2c) oled.text(Hello, Pico!, 0, 0) oled.show()如果你要用 0.96 寸 OLED 顯示中文就需要加載字庫(kù)或者預(yù)先取模這是新手最容易卡住的地方。i2c 地址不對(duì)、SCL/SDA 接反也是高頻問(wèn)題。這個(gè)方向跟 AI 編碼智能體完全是兩個(gè)圈子但都叫 pi說(shuō)明縮寫這東西在實(shí)際交流中確實(shí)容易撞車。6.2 控制工程師說(shuō)的 PI比例積分控制器熱詞里mmc環(huán)流抑制器的pi參數(shù)和pll pi控制帶寬fb都是自動(dòng)控制領(lǐng)域的內(nèi)容。PI 控制的傳遞函數(shù)是 Kp 加上 Ki 除以 sKp 決定響應(yīng)速度對(duì)應(yīng)帶寬Ki 負(fù)責(zé)消除穩(wěn)態(tài)誤差。在 MMC模塊化多電平換流器里做環(huán)流抑制工程上常用 PI 或 PR 控制器把內(nèi)部環(huán)流壓到基波附近參數(shù)整定的基本思路是先按期望帶寬定 Kp再讓 Ki 提供足夠的低頻增益同時(shí)加抗積分飽和措施。鎖相環(huán)PLL的 PI 參數(shù)同理帶寬設(shè)得越高鎖相越快但抗擾動(dòng)能力會(huì)下降。實(shí)際調(diào)試時(shí)我一般從期望帶寬的三分之一到二分之一起步觀察動(dòng)態(tài)響應(yīng)再微調(diào)。這類問(wèn)題里說(shuō)的 pi和 AI 編碼智能體沒有一點(diǎn)關(guān)系完全是控制工程的經(jīng)典內(nèi)容。6.3 硬件工程師說(shuō)的 SI/PI信號(hào)完整性與電源完整性在高速 PCB 設(shè)計(jì)領(lǐng)域SISignal Integrity和 PIPower Integrity合在一起簡(jiǎn)寫就是 SI/PI。做高速電路時(shí)疊層設(shè)計(jì)、信號(hào)回流路徑、去耦電容布局、眼圖質(zhì)量這些話題都?xì)w在這一類。如果你刷到的是SI/PI 仿真報(bào)告這類內(nèi)容那大概率是硬件方向的內(nèi)容別往編碼智能體上靠。很多搞硬件的老哥看到 pi 相關(guān)熱搜點(diǎn)進(jìn)去發(fā)現(xiàn)講的是 AI 寫代碼也是一臉懵。6.4 一句話判斷對(duì)方說(shuō)的是哪個(gè) pi最后給一個(gè)快速判斷的口訣出現(xiàn)場(chǎng)景大概率指編程、agent、代碼庫(kù)、subagentAI 編碼智能體 Pi樹莓派、GPIO、OLED、PicoRaspberry Pi / RP2040換流器、鎖相環(huán)、帶寬、參數(shù)整定PI 控制器PCB、仿真、疊層、電源完整性SI/PI另外你搜到的k pi八成是輸入法把 KPI 打成了 k pi那是績(jī)效考核的縮寫跟這些技術(shù)方向完全無(wú)關(guān)。技術(shù)上說(shuō)不上搭邊職場(chǎng)里倒是人人都躲不開但那是另一個(gè)話題了。我把這段時(shí)間的實(shí)際使用感受放在最后。最大的體會(huì)是這類工具的真正價(jià)值不在于替你寫代碼而在于把查資料、翻代碼、跑試驗(yàn)、改小 bug 這類重復(fù)勞動(dòng)接過(guò)去讓你能把注意力放在架構(gòu)、邊界和取舍上。但它跑得越快你越需要具備快速 review 的能力。它要是寫錯(cuò)了你一眼看不出那它幫你節(jié)省的時(shí)間最后都會(huì)以別的方式賠回去。我現(xiàn)在的習(xí)慣是新項(xiàng)目、重構(gòu)任務(wù)、補(bǔ)測(cè)試這類低風(fēng)險(xiǎn)高重復(fù)的活大膽交給它生產(chǎn)環(huán)境的敏感改動(dòng)一律自己過(guò)一遍再上。工具在變但想清楚再讓工具干活這個(gè)習(xí)慣什么時(shí)候都不過(guò)時(shí)。 Pi編碼智能體實(shí)戰(zhàn)：subagent編排、skill導(dǎo)入與本地RAG搭建
1. 先把這個(gè)pi說(shuō)清楚最近這段時(shí)間pi在我的開發(fā)者朋友圈里出現(xiàn)頻率高得嚇人。有人在群里曬 pi agent 自動(dòng)改完一個(gè) PR 的截圖有人討論 pi coding agent 拆 subagent 的技巧還有人問(wèn) oh my pi 桌面版在哪下載。我做開發(fā)十幾年第一反應(yīng)是又一個(gè)套殼工具但實(shí)際用了一周之后我承認(rèn)這工具確實(shí)有獨(dú)到的地方。這篇文章不講產(chǎn)品發(fā)布稿里那套話就從普通用戶的角度把 Pi 是什么、能解決什么問(wèn)題、怎么上手、subagent 和 skill 怎么玩、有哪些坑全部攤開講一遍。你可能剛聽說(shuō)這個(gè)詞也可能已經(jīng)在用同類工具想橫向?qū)Ρ冗@兩種讀者我都盡量照顧到。文章里的路徑、配置和操作步驟基于我本地實(shí)測(cè)和官方文檔整理出來(lái)不同版本之間可能有細(xì)微差別但整體思路是通用的換到別的 agent 工具上也能參考。1.1 它不是一個(gè)聊天窗口而是一個(gè)能自己動(dòng)手的實(shí)習(xí)生Pi 最簡(jiǎn)單的理解是一個(gè)能自主執(zhí)行任務(wù)的編碼智能體。它和聊天 AI 最大的區(qū)別在于它不只是你問(wèn)一句它答一句而是能自己讀代碼庫(kù)、搜索文件、修改代碼、執(zhí)行命令、看測(cè)試結(jié)果再根據(jù)結(jié)果繼續(xù)迭代。你交代一個(gè)目標(biāo)它會(huì)自己走完理解需求、查資料、動(dòng)手改、自我驗(yàn)證、匯報(bào)結(jié)果這一整條鏈路。我用一個(gè)比喻跟朋友解釋這就像你給團(tuán)隊(duì)招了個(gè)實(shí)習(xí)生。你把任務(wù)交代清楚他自己去翻資料、動(dòng)手做把成果拿給你 review。你要做的是把需求拆到足夠清楚并且在他跑偏的時(shí)候及時(shí)喊停。這個(gè)定位決定了它的使用方式——不是問(wèn)問(wèn)題而是派活。你負(fù)責(zé)判斷方向他負(fù)責(zé)執(zhí)行和試錯(cuò)配合得好效率是成倍的。反過(guò)來(lái)如果需求本身一團(tuán)漿糊那再?gòu)?qiáng)的 agent 也只會(huì)給你交出一團(tuán)更精致的漿糊。1.2 和 Cursor、Claude Code 這類工具相比它的差異在哪市面上的 AI 編程工具很多按干活方式大體能分三類。對(duì)話式助手只給答案不碰你的工程IDE 內(nèi)嵌 AI 在你寫代碼的時(shí)候補(bǔ)全、改文件終端里的 agent 類工具能獨(dú)立執(zhí)行任務(wù)。Pi 屬于第三類但它的特點(diǎn)在于多智能體設(shè)計(jì)你可以拆出專門的 subagent讓它們像不同崗位的工程師一樣并行工作由主 agent 做統(tǒng)一協(xié)調(diào)。我按自己平時(shí)使用的體感做個(gè)直觀對(duì)比工具類型典型代表干活方式最適合的場(chǎng)景對(duì)話式助手各類聊天 AI只輸出文字答案查資料、寫小片段IDE 內(nèi) AICursor、Copilot 系在編輯器里補(bǔ)全、改代碼人主導(dǎo)編碼AI 當(dāng)副駕終端編碼智能體Pi、Claude Code 這類自主讀代碼、執(zhí)行命令、多角色協(xié)作把完整任務(wù)交給 AI 自動(dòng)完成實(shí)際體驗(yàn)下來(lái)Pi 最抓我的一點(diǎn)不是單次代碼生成質(zhì)量而是它能把一個(gè)大任務(wù)拆成若干子任務(wù)交給不同身份的 subagent 并行處理。這種模式在處理跨模塊重構(gòu)、批量補(bǔ)測(cè)試、查歷史 bug 這類牽一發(fā)動(dòng)全身的任務(wù)時(shí)優(yōu)勢(shì)特別明顯。單點(diǎn)寫代碼的能力各家差距其實(shí)不大真正比拼的是編排能力也就是讓多個(gè)角色各干各的、最后還能嚴(yán)絲合縫拼起來(lái)的能力。1.3 什么人適合馬上上手我覺得下面三類人可以重點(diǎn)試試。第一類是日常寫代碼經(jīng)常要跨多個(gè)文件改動(dòng)的開發(fā)者這類活兒最費(fèi)神剛好是 agent 的強(qiáng)項(xiàng)。第二類是做技術(shù)調(diào)研和落地驗(yàn)證的人讓 Pi 自己拉代碼、跑示例、寫總結(jié)效率比手動(dòng)搜索高一個(gè)量級(jí)。第三類是剛?cè)腴T、還在猶豫怎么用 AI 提效的新手桌面版帶圖形界面比純命令行友好得多。當(dāng)然不適合的人也有完全不懂代碼、只想一鍵生成整個(gè) App的人大概率會(huì)被 agent 的連環(huán)追問(wèn)和 review 要求勸退。原因很簡(jiǎn)單agent 是執(zhí)行者不是許愿機(jī)。它把一大段代碼交給你你得有基本能力判斷好不好、能不能跑。這部分能力決定你能不能用好它沒有捷徑。2. 五分鐘上手裝桌面版、配環(huán)境、跑通第一個(gè)任務(wù)2.1 桌面版下載與安裝先說(shuō)安裝。去 Pi 官網(wǎng)的下載頁(yè)按自己系統(tǒng)選安裝包就行Windows 是 exemacOS 是 dmgApple Silicon 記得選 arm64 版本Linux 一般是 tar.gz 或 AppImage。我個(gè)人建議直接到官方 release 頁(yè)拿最新版用系統(tǒng)包管理器裝容易滯后一兩個(gè)版本而這類工具迭代非?？彀姹静钜粋€(gè)月體驗(yàn)可能差很多。很多人提到的Oh My Pi其實(shí)是社區(qū)做的一套配置管理腳本類似 oh-my-zsh 之于 zsh 的關(guān)系。它能把主題、快捷鍵、常用參數(shù)統(tǒng)一管理起來(lái)適合喜歡折騰的人。如果你只是想先用起來(lái)默認(rèn)配置完全夠不需要第一步就上這套。安裝完成后首次啟動(dòng)會(huì)有一個(gè)初始化向?qū)ё屇氵x工作目錄、默認(rèn)模型以及一個(gè)很關(guān)鍵的選項(xiàng)命令自動(dòng)執(zhí)行權(quán)限。我的建議是第一次先把自動(dòng)執(zhí)行關(guān)掉讓 agent 處于只讀觀察模式等它在你眼皮底下跑過(guò)幾輪、確認(rèn)不會(huì)亂來(lái)之后再逐步放開權(quán)限。2.2 模型配置和憑證認(rèn)證Pi 支持接入多種模型來(lái)源包括云端的 API也包括本地運(yùn)行的模型。配置里最核心就三樣?xùn)|西接口地址、模型名、憑證。下面是我本地環(huán)境里的一份配置示例{ provider: openai-compatible, base_url: http://127.0.0.1:11434/v1, api_key: sk-local-demo, model: qwen2.5-coder:32b, temperature: 0.2 }base_url 指向本地模型的兼容接口api_key 填一個(gè)占位符就行整個(gè)鏈路在本地閉環(huán)不需要數(shù)據(jù)出本機(jī)。如果你用的是云服務(wù)商的模型就要填真實(shí)的接口地址和 key。這里有個(gè)很容易踩的坑key 填錯(cuò)時(shí) agent 不會(huì)直接報(bào)錯(cuò)而是會(huì)反復(fù)重試表現(xiàn)出一堆莫名其妙的思考行為。所以配置完一定要先點(diǎn)測(cè)試連接確認(rèn)通了再進(jìn)項(xiàng)目這一步能省掉后面半小時(shí)的排查時(shí)間。模型選擇上如果機(jī)器配置一般優(yōu)先選帶 coder 后綴的小參數(shù)模型響應(yīng)快適配 agent 場(chǎng)景比通用對(duì)話模型穩(wěn)得多。機(jī)器好的可以上 32B 以上級(jí)別復(fù)雜推理能力會(huì)有肉眼可見的提升。溫度參數(shù)我習(xí)慣調(diào)低到 0.2 左右agent 任務(wù)追求確定性溫度太高容易放飛自我。2.3 跑通第一個(gè)任務(wù)配置完找一個(gè)小項(xiàng)目試水。我建議第一個(gè)任務(wù)別太野就拿你熟悉的倉(cāng)庫(kù)讓它做信息整理。例如pi 先讀一下當(dāng)前項(xiàng)目的 README 和 src 目錄梳理模塊結(jié)構(gòu)輸出一份總結(jié)你可以看到它先列目錄再挑文件讀最后生成總結(jié)。我第一次用的時(shí)候最直觀的感受是它真的會(huì)拆解動(dòng)作——不是一次性吐一大段文字而是先告訴你我打算先看配置文件再讀入口模塊然后一步一步執(zhí)行。這個(gè)過(guò)程中你隨時(shí)可以打斷它糾正方向。第一個(gè)任務(wù)跑通后你對(duì)它的工作節(jié)奏就有感覺了它更像一個(gè)需要你盯著的執(zhí)行者而不是放出去就不用管的自動(dòng)機(jī)。2.4 第一次使用必須知道的三個(gè)注意事項(xiàng)這一節(jié)的內(nèi)容都是我付過(guò)學(xué)費(fèi)換來(lái)的建議看一眼。第一工作目錄越小越好。別把整個(gè) home 目錄丟給它否則它會(huì)在無(wú)關(guān)文件里浪費(fèi)時(shí)間token 消耗也快得驚人。第二任何自動(dòng)執(zhí)行命令的能力都必須在虛擬環(huán)境或容器里放開不要把生產(chǎn)環(huán)境直接暴露給它它的一次誤操作可能比你手動(dòng)十次還快。第三所有改動(dòng)都要有版本控制兜底哪怕是臨時(shí)實(shí)驗(yàn)也先 git init 再說(shuō)。做到這三點(diǎn)后面再怎么折騰都不會(huì)出大亂子。3. 進(jìn)階玩法Subagent 編排與 Skill 導(dǎo)入3.1 主智能體和子智能體到底怎么配合Pi 的多智能體機(jī)制是它最值得玩的部分。簡(jiǎn)單說(shuō)主 agent 負(fù)責(zé)理解你的總目標(biāo)、拆解計(jì)劃、匯總結(jié)果subagent 是被臨時(shí)拉起來(lái)的專職角色各自有獨(dú)立的上下文窗口和工具權(quán)限。這樣一個(gè) subagent 埋頭查代碼的時(shí)候另一個(gè) subagent 已經(jīng)在寫測(cè)試了互不干擾。類比的話主 agent 是項(xiàng)目經(jīng)理subagent 是不同工種的施工隊(duì)而你才是那個(gè)拍板的人。項(xiàng)目經(jīng)理不會(huì)把所有施工隊(duì)叫到一個(gè)會(huì)議室里開大會(huì)而是分別傳達(dá)任務(wù)、分別驗(yàn)收。這樣做的最大好處是上下文隔離——每個(gè) subagent 只需要關(guān)心自己負(fù)責(zé)的那一小塊不會(huì)因?yàn)閷?duì)話太長(zhǎng)而把前面的指令忘掉。我見過(guò)很多人抱怨agent 用著用著就變傻仔細(xì)一看全是把幾百個(gè)文件的閱讀全都?jí)涸谕粋€(gè)上下文里不傻才怪。3.2 一個(gè) subagent 配置文件長(zhǎng)什么樣subagent 在 Pi 里一般通過(guò)配置文件定義。下面是我項(xiàng)目里一個(gè)后端開發(fā)角色的配置格式做了簡(jiǎn)化字段名不同版本可能有差異但結(jié)構(gòu)思路是通用的--- name: backend-dev description: 負(fù)責(zé)后端模塊開發(fā)、接口實(shí)現(xiàn)與單元測(cè)試 tools: [read, search, edit, run, test] --- 你是項(xiàng)目里的資深后端工程師主要使用 Python 和 FastAPI。 工作規(guī)范 - 動(dòng)手前必須先列出要改動(dòng)的文件清單 - 每個(gè)接口實(shí)現(xiàn)后必須補(bǔ)測(cè)試 - 禁止修改與任務(wù)無(wú)關(guān)的模塊 - 依賴不明確時(shí)先查 requirements.txt 再?zèng)Q定不要自行假定配置里最重要的不是 role 描述寫得多華麗而是 tools 權(quán)限列表。列表越窄越不容易出事故。比如只給它 read、search、edit 三個(gè)權(quán)限它就沒辦法執(zhí)行命令自然干不了刪庫(kù)這種壞事。這是我從翻車經(jīng)歷里總結(jié)出來(lái)的。role 描述部分則要用具體名詞和規(guī)則去約束行為越具象越穩(wěn)定模糊的形容詞反而容易讓模型自由發(fā)揮。每個(gè) subagent 干完活你還得讓它在匯報(bào)里寫清楚改了什么、為什么這么改方便你 review。3.3 用 Web 控制臺(tái)導(dǎo)入 Skill 的完整流程Skill 的概念很好理解就是給 agent 預(yù)裝的操作手冊(cè)。它把一套成熟的工作流打包成角色設(shè)定 規(guī)則 模板別人寫好了你可以直接導(dǎo)入。比如代碼評(píng)審skill會(huì)把評(píng)審步驟、輸出格式、問(wèn)題分級(jí)標(biāo)準(zhǔn)都定義好agent 一調(diào)就能用不用你每次重新交代一遍。pi web 導(dǎo)入 skill這個(gè)操作我實(shí)際走了一遍流程是這樣的啟動(dòng)桌面版之后在瀏覽器里打開本地控制臺(tái)頁(yè)面找到技能市場(chǎng)搜索你需要的 skill點(diǎn)導(dǎo)入后它會(huì)自動(dòng)同步到本地技能目錄一般放在用戶目錄下的.pi/skills/或者項(xiàng)目里的.pi/skills/最后重啟當(dāng)前會(huì)話在對(duì)話里用斜杠命令調(diào)用。不同版本的界面可能有差異但整體流程大差不差。一個(gè) skill 在本地通常是一個(gè)獨(dú)立目錄結(jié)構(gòu)類似~/.pi/skills/ └── code-review/ ├── SKILL.md ├── templates/ │ └── issue-list.md └── scripts/ └── collect_changed_files.pySKILL.md 是核心里面定義了觸發(fā)詞、執(zhí)行步驟和輸出格式。我抄一段簡(jiǎn)化示例--- name: code-review description: 掃描指定范圍代碼輸出問(wèn)題清單與優(yōu)先級(jí) --- 執(zhí)行步驟 1. 先用 git diff 獲取變更文件列表 2. 逐個(gè)文件做增量評(píng)審 3. 按 嚴(yán)重/一般/建議 三級(jí)輸出導(dǎo)入第三方 skill 之前務(wù)必看一眼 SKILL.md 里申請(qǐng)了哪些工具權(quán)限。尤其是帶 run 權(quán)限的等于把執(zhí)行命令的能力交給了別人的腳本風(fēng)險(xiǎn)很高。我自己只導(dǎo)入那些明確不含危險(xiǎn)操作的 skill其他一律先打開源碼確認(rèn)再?zèng)Q定。skill 是可以自己寫的把團(tuán)隊(duì)里反復(fù)用到的工作流沉淀成一個(gè) skill比口頭交代靠譜得多。3.4 什么時(shí)候拆 subagent什么時(shí)候不拆很多新手一上來(lái)就把所有任務(wù)都拆給 subagent結(jié)果發(fā)現(xiàn)反而更慢。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單看任務(wù)粒度。改一個(gè)函數(shù)、修一個(gè)文案主 agent 直接做就行拆 subagent 的開銷比干活本身還大?？缒K重構(gòu)、批量補(bǔ)測(cè)試、查歷史問(wèn)題這類大任務(wù)才值得拆。任務(wù)類型是否需要拆原因修改單個(gè)函數(shù)不拆單線程最快拆了純耗 token跨模塊重構(gòu)拆每個(gè)模塊一個(gè)角色上下文隔離批量寫測(cè)試拆測(cè)試與實(shí)現(xiàn)并行效率翻倍排查歷史 bug拆讓 subagent 專門翻 git log專注不跑神記住一句話拆 subagent 不是目的控制上下文才是目的。哪個(gè)方案能讓每個(gè)智能體專注在最小范圍里就用哪個(gè)方案。有時(shí)候你看著它不并行但實(shí)際上它省下的 token 和避免的沖突比并行省的時(shí)間更有價(jià)值。4. 實(shí)戰(zhàn)復(fù)盤用 Pi 從零搭一個(gè)本地問(wèn)答 API4.1 項(xiàng)目需求和任務(wù)拆解光聊概念沒意思我拿一個(gè)真實(shí)小項(xiàng)目說(shuō)下完整過(guò)程。需求很簡(jiǎn)單做一個(gè)極簡(jiǎn)的本地 RAG檢索增強(qiáng)生成問(wèn)答接口。把某個(gè)目錄下的一堆 Markdown 文檔當(dāng)成知識(shí)庫(kù)提供一個(gè) POST 接口用戶提問(wèn)題系統(tǒng)先檢索出最相關(guān)的片段再交給大模型生成答案最后返回答案和來(lái)源路徑。這個(gè)項(xiàng)目不涉及任何外部依賴非常適合演示 agent 的完整工作流。這個(gè)需求被我拆成三個(gè)子任務(wù)。第一個(gè)是項(xiàng)目骨架初始化包括 FastAPI 應(yīng)用和依賴清單。第二個(gè)是文檔索引模塊負(fù)責(zé)把 Markdown 按段落切塊、向量化、存到本地向量庫(kù)。第三個(gè)是問(wèn)答接口負(fù)責(zé)把檢索結(jié)果和問(wèn)題拼成 prompt調(diào)用本地模型生成回答。每個(gè)子任務(wù)對(duì)應(yīng)一個(gè) subagent最后再由主 agent 統(tǒng)一整合。拆解的過(guò)程本身其實(shí)就是架構(gòu)設(shè)計(jì)的過(guò)程對(duì) pi coding agent 說(shuō)清楚這三塊它就能各自開工。4.2 讓 Pi 動(dòng)手前的關(guān)鍵 Prompt很多人的 agent 用不好問(wèn)題出在 prompt 太含糊。需求只寫一句幫我做個(gè)問(wèn)答系統(tǒng)agent 就只能靠猜交出來(lái)的東西大概率不是你要的。我這次給 Pi 的任務(wù)描述是這么寫的項(xiàng)目本地問(wèn)答 API。 請(qǐng)按以下順序執(zhí)行 1. 創(chuàng)建 FastAPI 項(xiàng)目骨架依賴盡量少 2. 實(shí)現(xiàn) docs 目錄下 Markdown 的索引與檢索使用本地向量庫(kù)持久化 3. 實(shí)現(xiàn) POST /ask接收 question返回 answer 和 sources 4. 最后給出運(yùn)行方式和測(cè)試命令。注意這里我做了兩件事一是給了明確的執(zhí)行順序讓它先搭骨架再填血肉二是要求最后給出運(yùn)行方式和測(cè)試命令等于逼它把交付物補(bǔ)完整而不是只丟一堆代碼。這個(gè)技巧對(duì)提高 agent 交付質(zhì)量非常有效——你要求的交付物越具體它就越不會(huì)糊弄。如果你希望某個(gè)環(huán)節(jié)重點(diǎn)做比如檢索部分性能優(yōu)先也得在 prompt 里明確寫出來(lái)否則它只會(huì)按默認(rèn)方式實(shí)現(xiàn)。4.3 核心代碼從索引到問(wèn)答接口整個(gè)項(xiàng)目的核心代碼不多我把關(guān)鍵文件貼出來(lái)你照著就能跑。先是依賴清單fastapi uvicorn chromadb sentence-transformers httpx索引模塊 indexer.py 負(fù)責(zé)把 Markdown 切塊并寫入本地向量庫(kù)from pathlib import Path from hashlib import md5 import chromadb from sentence_transformers import SentenceTransformer encoder SentenceTransformer(all-MiniLM-L6-v2) client chromadb.PersistentClient(path./data/chroma) collection client.get_or_create_collection(namedocs) def build_index(docs_dir: Path): ids, chunks, metadatas [], [], [] for md in docs_dir.rglob(*.md): text md.read_text(encodingutf-8) for i, para in enumerate(text.strip().split(\n\n)): if not para.strip(): continue chunks.append(para) ids.append(md5(f{md}:{i}.encode()).hexdigest()) metadatas.append({path: str(md), chunk: i}) collection.upsert(idsids, documentschunks, metadatasmetadatas)問(wèn)答接口 main.py 這樣寫from fastapi import FastAPI from pydantic import BaseModel from indexer import collection, encoder from llm import call_llm app FastAPI() class AskRequest(BaseModel): question: str app.post(/ask) def ask(req: AskRequest): results collection.query( query_embeddings[encoder.encode(req.question).tolist()], n_results3, ) sources [m[path] for m in results[metadatas][0]] context \n---\n.join(results[documents][0]) answer call_llm(req.question, context) return {answer: answer, sources: sources}最后是調(diào)用本地模型生成回答的 llm.pyimport httpx def call_llm(question: str, context: str) - str: resp httpx.post( http://127.0.0.1:11434/v1/chat/completions, json{ model: qwen2.5:7b, messages: [ {role: system, content: 你只能根據(jù)提供的上下文回答不要編造事實(shí)。}, {role: user, content: f上下文\n{context}\n\n問(wèn)題{question}}, ], temperature: 0.2, }, timeout60, ) return resp.json()[choices][0][message][content]這個(gè)項(xiàng)目跑起來(lái)之后你往 docs 里丟幾篇 Markdown再 curl 一下接口就能看到返回里帶著答案和來(lái)源文件路徑。整個(gè)鏈路從索引到檢索到生成都在本地閉環(huán)。你也可以把向量庫(kù)換成別的存儲(chǔ)或者把 embedding 模型換大一點(diǎn)的效果更好的但整體結(jié)構(gòu)不需要?jiǎng)印?.4 調(diào)試與 Review 的實(shí)操心得這個(gè)項(xiàng)目我讓 Pi 干了大半天過(guò)程中有幾次典型的翻車正好用來(lái)講經(jīng)驗(yàn)。第一次翻車在 ChromaDB 的參數(shù)上subagent 把query_embeddings和query_texts混用了。原因是它同時(shí)參考了舊版文檔和新版文檔兩邊 API 不一樣。這種細(xì)節(jié)問(wèn)題人眼 review 一眼就能看出來(lái)但 agent 自己很難發(fā)現(xiàn)所以review 代碼這一步絕對(duì)不能省。第二次是測(cè)試用例的問(wèn)題。它寫了一個(gè) test_main.py但測(cè)試?yán)镎娴娜フ{(diào)模型接口導(dǎo)致跑測(cè)試必須先起模型服務(wù)。我讓它在測(cè)試?yán)锇?call_llm 用 monkeypatch 換掉只驗(yàn)證接口邏輯和返回結(jié)構(gòu)。這個(gè)改動(dòng)很小但對(duì)自動(dòng)化測(cè)試的可用性是決定性的。以后每次改動(dòng)都能快速回歸不用背著模型服務(wù)跑測(cè)試。我的操作習(xí)慣是第一步讓 Pi 自己跑測(cè)試把報(bào)錯(cuò)原樣貼回對(duì)話它會(huì)自己修第二步每個(gè) subagent 在獨(dú)立分支上工作最后統(tǒng)一合并避免互相覆蓋第三步合并前我親自讀一遍 diff不信任任何它說(shuō)沒問(wèn)題的結(jié)論。這套流程走下來(lái)項(xiàng)目本身不難但它把用 agent 干活的正確姿勢(shì)演示了一遍目標(biāo)明確、角色拆分、代碼審查、測(cè)試兜底這四步少一步都會(huì)還債。5. 常見問(wèn)題與排查實(shí)錄5.1 問(wèn)題速查表我把這段時(shí)間里遇到的高頻問(wèn)題整理成了一張速查表遇到類似情況可以直接對(duì)號(hào)入座?，F(xiàn)象可能原因處理辦法導(dǎo)入 skill 后對(duì)話里不出現(xiàn)當(dāng)前會(huì)話沒刷新重啟會(huì)話確認(rèn)技能目錄被識(shí)別模型答非所問(wèn)上下文被無(wú)用文件占滿限定讀取范圍用 search 代替讀全文多個(gè) subagent 改出沖突代碼都動(dòng)了公共文件公共模塊改由主 agent 統(tǒng)一執(zhí)行命令執(zhí)行到一半卡住在等用戶確認(rèn)你沒注意檢查授權(quán)配置或換更快的模型token 消耗快得離譜每次都重讀大文件提示 agent 只讀關(guān)鍵片段限制讀取數(shù)量這些問(wèn)題的根源大部分是同一個(gè)上下文管理沒做好。不是模型不行而是你把太多垃圾信息塞給了模型。想明白這一點(diǎn)排查思路就清晰了。5.2 我踩過(guò)最疼的幾個(gè)坑第一個(gè)坑是讓兩個(gè) subagent 并行改同一個(gè)文件。一個(gè)在重構(gòu)接口一個(gè)在加注釋結(jié)果后面的覆蓋了前面的。從那以后我規(guī)定公共文件只能由主 agent 改subagent 只負(fù)責(zé)自己模塊內(nèi)的文件。團(tuán)隊(duì)協(xié)作里文件所有權(quán)的概念在 agent 協(xié)作里同樣成立。第二個(gè)坑是自動(dòng)審批開得太早。當(dāng)時(shí)為了省事允許它直接執(zhí)行命令結(jié)果它為了裝依賴往系統(tǒng) Python 里塞了一堆包把環(huán)境搞得一團(tuán)糟。教訓(xùn)非常明確所有自動(dòng)執(zhí)行操作必須在虛擬環(huán)境或容器里進(jìn)行并且 run 命令要加白名單。這個(gè)白名單不是用來(lái)限制 agent 的而是用來(lái)保護(hù)你的環(huán)境的。第三個(gè)坑是上下文里積累了太多歷史包袱。同一個(gè) session 里連續(xù)跑了好幾個(gè)不相關(guān)的任務(wù)到后面它開始把上一個(gè)任務(wù)的輸出當(dāng)成參考答案越來(lái)越離譜?，F(xiàn)在我的習(xí)慣是一個(gè)大任務(wù)結(jié)束就開新會(huì)話絕不拖著舊狀態(tài)跑新任務(wù)。這個(gè)習(xí)慣看似浪費(fèi)實(shí)際上省下了大量排查錯(cuò)誤的時(shí)間屬于典型的以小換大。5.3 幾個(gè)讓體驗(yàn)翻倍的小技巧關(guān)于 agent 的行為約束我發(fā)現(xiàn)負(fù)向指令比正向指令管用得多。你告訴它不要使用 requirements.txt 之外的庫(kù)比請(qǐng)選擇合適的庫(kù)有效一百倍。因?yàn)樨?fù)向指令是一個(gè)硬邊界模型更容易遵守而正向指令給了它發(fā)揮空間發(fā)揮就意味著可能走偏。走偏一次浪費(fèi)的時(shí)間比省下的時(shí)間還多。第二個(gè)技巧是讓 agent 先寫計(jì)劃書。面對(duì)復(fù)雜任務(wù)第一輪先讓它只輸出實(shí)施計(jì)劃你確認(rèn)了再讓它動(dòng)手。這一步能在早期攔截掉大量方向性錯(cuò)誤比事后返工省錢多了。我在第一次做這個(gè) API 項(xiàng)目的時(shí)候跳過(guò)這步結(jié)果它先寫了個(gè)數(shù)據(jù)庫(kù)同步邏輯跟需求毫無(wú)關(guān)系白白浪費(fèi)了二十分鐘。第三個(gè)技巧是給 subagent 起一個(gè)具象的名字。叫backend-dev比叫assistant穩(wěn)定很多?？雌饋?lái)是玄學(xué)但實(shí)測(cè)下來(lái)身份描述的顆粒度直接影響模型的行為模式——它會(huì)更傾向于表現(xiàn)出對(duì)應(yīng)角色的專業(yè)性。名字和角色描述就是它的人設(shè)人設(shè)越清楚行為越收斂。6. 別搞混了此 pi 非彼 pi寫到這里必須插一段因?yàn)閜i這個(gè)詞在技術(shù)圈里同時(shí)指好幾樣?xùn)|西。你搜pi的時(shí)候可能一半結(jié)果是 AI 編碼智能體另一半是樹莓派或者控制理論。不把這些對(duì)應(yīng)關(guān)系理清楚看文章很容易對(duì)不上號(hào)。6.1 樹莓派玩家說(shuō)的 PiRaspberry Pi 與 RP2040熱詞里有一個(gè)raspberry pi 2040 oled 0.96說(shuō)的是用樹莓派 Pico 開發(fā)板主控芯片是 RP2040驅(qū)動(dòng)一塊 0.96 英寸 OLED 屏屏的驅(qū)動(dòng)芯片一般是 SSD1306走 I2C 接口。這類小項(xiàng)目的典型玩法是幾分鐘點(diǎn)亮屏幕顯示文字from machine import Pin, I2C import ssd1306 i2c I2C(0, sclPin(1), sdaPin(0), freq400000) oled ssd1306.SSD1306_I2C(128, 64, i2c) oled.text(Hello, Pico!, 0, 0) oled.show()如果你要用 0.96 寸 OLED 顯示中文就需要加載字庫(kù)或者預(yù)先取模這是新手最容易卡住的地方。i2c 地址不對(duì)、SCL/SDA 接反也是高頻問(wèn)題。這個(gè)方向跟 AI 編碼智能體完全是兩個(gè)圈子但都叫 pi說(shuō)明縮寫這東西在實(shí)際交流中確實(shí)容易撞車。6.2 控制工程師說(shuō)的 PI比例積分控制器熱詞里mmc環(huán)流抑制器的pi參數(shù)和pll pi控制帶寬fb都是自動(dòng)控制領(lǐng)域的內(nèi)容。PI 控制的傳遞函數(shù)是 Kp 加上 Ki 除以 sKp 決定響應(yīng)速度對(duì)應(yīng)帶寬Ki 負(fù)責(zé)消除穩(wěn)態(tài)誤差。在 MMC模塊化多電平換流器里做環(huán)流抑制工程上常用 PI 或 PR 控制器把內(nèi)部環(huán)流壓到基波附近參數(shù)整定的基本思路是先按期望帶寬定 Kp再讓 Ki 提供足夠的低頻增益同時(shí)加抗積分飽和措施。鎖相環(huán)PLL的 PI 參數(shù)同理帶寬設(shè)得越高鎖相越快但抗擾動(dòng)能力會(huì)下降。實(shí)際調(diào)試時(shí)我一般從期望帶寬的三分之一到二分之一起步觀察動(dòng)態(tài)響應(yīng)再微調(diào)。這類問(wèn)題里說(shuō)的 pi和 AI 編碼智能體沒有一點(diǎn)關(guān)系完全是控制工程的經(jīng)典內(nèi)容。6.3 硬件工程師說(shuō)的 SI/PI信號(hào)完整性與電源完整性在高速 PCB 設(shè)計(jì)領(lǐng)域SISignal Integrity和 PIPower Integrity合在一起簡(jiǎn)寫就是 SI/PI。做高速電路時(shí)疊層設(shè)計(jì)、信號(hào)回流路徑、去耦電容布局、眼圖質(zhì)量這些話題都?xì)w在這一類。如果你刷到的是SI/PI 仿真報(bào)告這類內(nèi)容那大概率是硬件方向的內(nèi)容別往編碼智能體上靠。很多搞硬件的老哥看到 pi 相關(guān)熱搜點(diǎn)進(jìn)去發(fā)現(xiàn)講的是 AI 寫代碼也是一臉懵。6.4 一句話判斷對(duì)方說(shuō)的是哪個(gè) pi最后給一個(gè)快速判斷的口訣出現(xiàn)場(chǎng)景大概率指編程、agent、代碼庫(kù)、subagentAI 編碼智能體 Pi樹莓派、GPIO、OLED、PicoRaspberry Pi / RP2040換流器、鎖相環(huán)、帶寬、參數(shù)整定PI 控制器PCB、仿真、疊層、電源完整性SI/PI另外你搜到的k pi八成是輸入法把 KPI 打成了 k pi那是績(jī)效考核的縮寫跟這些技術(shù)方向完全無(wú)關(guān)。技術(shù)上說(shuō)不上搭邊職場(chǎng)里倒是人人都躲不開但那是另一個(gè)話題了。我把這段時(shí)間的實(shí)際使用感受放在最后。最大的體會(huì)是這類工具的真正價(jià)值不在于替你寫代碼而在于把查資料、翻代碼、跑試驗(yàn)、改小 bug 這類重復(fù)勞動(dòng)接過(guò)去讓你能把注意力放在架構(gòu)、邊界和取舍上。但它跑得越快你越需要具備快速 review 的能力。它要是寫錯(cuò)了你一眼看不出那它幫你節(jié)省的時(shí)間最后都會(huì)以別的方式賠回去。我現(xiàn)在的習(xí)慣是新項(xiàng)目、重構(gòu)任務(wù)、補(bǔ)測(cè)試這類低風(fēng)險(xiǎn)高重復(fù)的活大膽交給它生產(chǎn)環(huán)境的敏感改動(dòng)一律自己過(guò)一遍再上。工具在變但想清楚再讓工具干活這個(gè)習(xí)慣什么時(shí)候都不過(guò)時(shí)。