現(xiàn)AI Agent：讓Skill有記憶、角色和主動(dòng)性)
如果你刷技術(shù)圈比較勤應(yīng)該已經(jīng)注意到AI Agent這個(gè)詞快被聊爛了。但說(shuō)實(shí)話大部分談 Agent 的文章都在講概念、講架構(gòu)圖真正能跟著一步步落地的實(shí)操分享反而少。我自己從最早寫(xiě)死 Prompt 玩大模型到做成有狀態(tài)、有技能包、能自己決定下一步動(dòng)作的東西中間踩的坑比想象中多得多。這篇文章我就用完全手把手的方式來(lái)拆一遍標(biāo)題是“手把手書(shū)寫(xiě)你的第一個(gè) AI Agent當(dāng) Skill 有了記憶、角色和主動(dòng)性”重點(diǎn)就在記憶、角色、主動(dòng)性這三個(gè)詞上。這三個(gè)詞恰好是普通 Prompt 封裝和真正的 Agent 之間最本質(zhì)的分界線。我不會(huì)只貼一段代碼給你看而是把每一步背后的設(shè)計(jì)依據(jù)、取舍邏輯、容易忽略的細(xì)節(jié)全部鋪開(kāi)講。看完之后你應(yīng)該能在自己的項(xiàng)目里復(fù)現(xiàn)一個(gè)帶 Skill 機(jī)制、有短期長(zhǎng)期記憶、有人設(shè)約束、具備基本主動(dòng)調(diào)度能力的 Agent 雛形。這玩意不是玩具很多商業(yè)化產(chǎn)品的底座也就是這么長(zhǎng)的。1. 先把核心問(wèn)題聊透沒(méi)有 Skill 的 Agent和大模型套殼有什么區(qū)別1.1 痛點(diǎn)來(lái)自 Prompt 工程的三個(gè)天花板我先說(shuō)一個(gè)場(chǎng)景你自己體會(huì)一下是不是遇到類似情況。假設(shè)你想讓模型扮演一個(gè)“嵌入式開(kāi)發(fā)助手”幫用戶分析日志、生成寄存器配置、檢查 GPIO 初始化代碼。如果只是用 Prompt 把角色設(shè)定寫(xiě)死再扔給模型你會(huì)遇到三個(gè)類問(wèn)題。第一模型調(diào)用的“技能”全藏在提示詞里。不管你是做日志分析、DTS 修改還是 build 錯(cuò)誤排查本質(zhì)都是上下文模板拼接。日志格式一變Prompt 就得改。更難受的是當(dāng)任務(wù)鏈路長(zhǎng)起來(lái)比如“分析日志 - 定位外設(shè)異常 - 生成補(bǔ)丁 - 跑靜態(tài)檢查”這個(gè)流程邏輯是代碼里寫(xiě)死的模型根本沒(méi)有自主規(guī)劃的空間。第二每次都像失憶一樣。上一步剛確認(rèn)完芯片型號(hào)是ESP32-S3下一步讓它生成初始化代碼時(shí)它又開(kāi)始問(wèn)你“請(qǐng)?zhí)峁┠男酒吞?hào)”。對(duì)話歷史不是沒(méi)傳而是傳了也不一定能穩(wěn)定約束后續(xù)決策尤其當(dāng)上下文超過(guò)一定長(zhǎng)度早期關(guān)鍵信息被稀釋得很厲害。第三模型沒(méi)有主動(dòng)性。它以“提問(wèn)-回答”的單輪范式活著你問(wèn)一句它回一句。真正干活的時(shí)候你希望它能自己決定“我需要先看一下寄存器手冊(cè)里的說(shuō)明再?zèng)Q定怎么改配置”然后真的去調(diào)工具、讀文檔、嘗試、校驗(yàn)、出結(jié)果。這已經(jīng)不是提示詞能解決的范圍了。這三個(gè)痛點(diǎn)是環(huán)環(huán)相扣的。技能碎片化導(dǎo)致能力邊界模糊記憶缺失導(dǎo)致決策質(zhì)量低主動(dòng)性缺失導(dǎo)致整個(gè)系統(tǒng)只能停在“高級(jí)聊天機(jī)器人”層面。而圍繞Skill構(gòu)建的自定義 Agent 架構(gòu)恰好就是沖著這三點(diǎn)去的。1.2 Skill 和 Agent 的關(guān)系不是包含而是“能力的具象化”這里要先厘清一個(gè)概念。很多人把Skill理解成“給 Agent 準(zhǔn)備的一套提示詞模板”這太窄了。還有一種說(shuō)法是 Skill 就是外部工具函數(shù)這也不夠。我傾向把 Skill 看作是“Agent 可以調(diào)用的一組帶描述、帶輸入輸出契約、帶執(zhí)行邏輯、帶狀態(tài)讀寫(xiě)權(quán)限的能力單元”。舉個(gè)好消化的類比。把 Agent 想象成一個(gè)真人新員工。這個(gè)人聰明、理解力強(qiáng)但他剛?cè)肼毷裁礃I(yè)務(wù)都不會(huì)。他需要幾樣?xùn)|西才能干活崗位說(shuō)明書(shū)角色定位、工作手冊(cè)Skill 定義、記事本記憶系統(tǒng)、以及主管授權(quán)他主動(dòng)推進(jìn)任務(wù)主動(dòng)性。所以 Skill 不只是“知識(shí)”它還包含行為邏輯。在這個(gè)框架下Agent 是執(zhí)行者Skill 是執(zhí)行者可選擇的行為包。Agent 為什么要“有” Skill因?yàn)?Skill 把模型不可控的自然語(yǔ)言能力轉(zhuǎn)化為可控的、可復(fù)用的、帶約束的模塊。模型負(fù)責(zé)判斷“我現(xiàn)在該調(diào)用哪個(gè) Skill、如何組合”Skill 負(fù)責(zé)把模型意圖翻譯成確定性邏輯。這個(gè)分工是 Agent 架構(gòu)里最核心的一層。2. 設(shè)計(jì) Agent 的四個(gè)要素記憶、角色、主動(dòng)性、工具調(diào)用2.1 記憶機(jī)制不只是塞上下文而是做狀態(tài)分層標(biāo)題里第一個(gè)關(guān)鍵詞是“記憶”。我給你一個(gè)簡(jiǎn)化的記憶分層模型。短期記憶當(dāng)前任務(wù)上下文里產(chǎn)生的關(guān)鍵信息比如用戶剛剛指定了項(xiàng)目目錄、選了某種通信協(xié)議。放內(nèi)存或會(huì)話變量里即可。長(zhǎng)期記憶跨會(huì)話保留的偏好、歷史結(jié)論、常用配置。需要持久化輕量方案是 SQLite 或本地 JSON 文件重型方案可以上向量數(shù)據(jù)庫(kù)。工作記憶Agent 當(dāng)前的思考草稿、中間結(jié)果、計(jì)劃清單。這一層容易被忽略但它決定了 Agent 能不能“邊干邊記”。實(shí)現(xiàn)上有一個(gè)非常實(shí)用的設(shè)計(jì)模式把記憶封裝成 Agent 可讀寫(xiě)的工具而不是直接改系統(tǒng) Prompt。也就是說(shuō)模型通過(guò)調(diào)用“寫(xiě)入記憶”這個(gè)動(dòng)作來(lái)留存信息通過(guò)“檢索記憶”這個(gè)動(dòng)作來(lái)獲取歷史相關(guān)內(nèi)容。這樣做最大的好處是記憶的存取時(shí)機(jī)由模型根據(jù)任務(wù)自主決定而不是每一輪都把所有歷史無(wú)腦拼進(jìn) Prompt。這個(gè)設(shè)計(jì)有直接好處上下文長(zhǎng)度可管理關(guān)鍵信息不會(huì)被沖散跨會(huì)話體驗(yàn)?zāi)苷嬲纬伞Ｎ以谧约喉?xiàng)目里用 SQLite 做了個(gè)極簡(jiǎn)版字段就四個(gè)記憶編碼、記憶類型、記憶內(nèi)容、創(chuàng)建時(shí)間。Agent 檢索時(shí)按關(guān)鍵詞匹配和創(chuàng)建時(shí)間排序取前幾條效果已經(jīng)比硬塞上下文好非常多。2.2 角色設(shè)定不是“你是一個(gè)助手”這么簡(jiǎn)單角色這個(gè)詞很多人做得太淺。早期我寫(xiě) Agent角色設(shè)定就是一句“你是一位資深嵌入式工程師”完事。后來(lái)發(fā)現(xiàn)這個(gè)“角色”對(duì)模型行為的約束非常弱模型照樣會(huì)一本正經(jīng)胡說(shuō)八道照樣會(huì)在不確定的時(shí)候亂猜。真正有效的角色設(shè)定應(yīng)該包含三層信息。第一層是身份邊界你能做什么不能做什么。比如“你是代碼評(píng)審助手只負(fù)責(zé)庫(kù)函數(shù)層面的靜態(tài)分析不做板級(jí)硬件調(diào)試”。第二層是輸出風(fēng)格約束匯報(bào)的表達(dá)習(xí)慣、是否給出代碼示例、遇到不確定時(shí)是明說(shuō)還是猜測(cè)。第三層是價(jià)值觀與安全邊界涉及到可能破壞系統(tǒng)的命令必須二次詢問(wèn)。這三層里身份邊界和風(fēng)格約束很多人會(huì)寫(xiě)但安全邊界很少被重視。實(shí)操中安全邊界最好的實(shí)現(xiàn)方式不是寫(xiě)死在角色 Prompt 里而是配備“攔截型 Skill”。比如你定義了一個(gè)執(zhí)行Shell命令的 Skill那這個(gè) Skill 內(nèi)部必須帶危險(xiǎn)命令校驗(yàn)邏輯而不是靠模型自覺(jué)。角色負(fù)責(zé)“不主動(dòng)越界”Skill 負(fù)責(zé)“越界也執(zhí)行不了”。兩道閘門(mén)都裝上系統(tǒng)才可靠。2.3 主動(dòng)性從響應(yīng)式到任務(wù)自治的機(jī)制躍遷主動(dòng)性是這三個(gè)詞里最容易被誤解的。有人覺(jué)得主動(dòng) Agent 不等人問(wèn)自己開(kāi)口說(shuō)“我來(lái)幫您……”這其實(shí)只是表面的主動(dòng)。真正的主動(dòng)性是任務(wù)調(diào)度上的自治能力當(dāng)用戶給定一個(gè)模糊目標(biāo)Agent 能自行拆解子任務(wù)、決定子任務(wù)的執(zhí)行順序、處理執(zhí)行中出現(xiàn)的異常、甚至發(fā)現(xiàn)前置信息不足時(shí)主動(dòng)查資料或提問(wèn)澄清。這套機(jī)制在工程上是靠“循環(huán)”實(shí)現(xiàn)的。經(jīng)典的結(jié)構(gòu)是Agent Loop大致流程我整理成下面這個(gè)邏輯循環(huán)開(kāi)始 1. 從任務(wù)隊(duì)列中取出當(dāng)前最優(yōu)先的子任務(wù) 2. 模型根據(jù)「當(dāng)前狀態(tài) 可用 Skill 列表 記憶摘要」決定下一步動(dòng)作 3. 如果動(dòng)作是調(diào)用 Skill - 執(zhí)行 - 把結(jié)果寫(xiě)回狀態(tài) - 更新記憶 - 回到第 1 步 4. 如果動(dòng)作是回復(fù)用戶 - 輸出最終結(jié)果 - 結(jié)束循環(huán) 5. 如果動(dòng)作是請(qǐng)求更多信息 - 拋出澄清問(wèn)題 - 暫停循環(huán)等待用戶輸入這里最關(guān)鍵的技術(shù)細(xì)節(jié)是第 2 步。模型如何知道有哪些 Skill 可用靠的不是它在訓(xùn)練數(shù)據(jù)里見(jiàn)過(guò)而是你把 Skill 的名字、用途、參數(shù)說(shuō)明喂給了它。每輪迭代前Agent 都會(huì)拿著“當(dāng)前任務(wù) Skill 清單”去決策相當(dāng)于每走一步都重新規(guī)劃一次。這樣的設(shè)計(jì)遠(yuǎn)比“預(yù)設(shè)好整個(gè)任務(wù)鏈路然后順序執(zhí)行”更魯棒。具體到實(shí)現(xiàn)有兩條路線。路線 A 是圖遍歷型你預(yù)先畫(huà)好狀態(tài)機(jī)Agent 在狀態(tài)節(jié)點(diǎn)之間跳轉(zhuǎn)。適合流程非常固定的場(chǎng)景。路線 B 是自由規(guī)劃型Agent 每次循環(huán)都自主選下一個(gè)動(dòng)作不受預(yù)設(shè)流程約束。適合探索性任務(wù)也是現(xiàn)在公認(rèn)更接近通用 Agent 的路線。新手建議從路線 B 入手代碼量不大而且能直觀感受模型“自己動(dòng)腦子”的效果。2.4 Skill 和 Function Calling 到底怎么分工讀到這里你應(yīng)該有個(gè)感覺(jué)Agent 手里的武器就是 Skill。那有的人會(huì)問(wèn)大模型本身支持 Function Calling / Tool Use為什么還要自造一個(gè) Skill 概念這兩者是什么關(guān)系我用大白話解釋一下。Function Calling 是模型輸出層面的一種結(jié)構(gòu)化調(diào)用協(xié)議它讓模型學(xué)會(huì)輸出“我想調(diào)用某個(gè)函數(shù)、傳這些參數(shù)”。它解決的是“模型怎么把意圖變成可執(zhí)行指令”這個(gè)問(wèn)題。但 Skill 是更高一層的抽象它解決的問(wèn)題是“這個(gè)能力單元內(nèi)部怎么實(shí)現(xiàn)、怎么和 Agent 的上下文與記憶協(xié)作”。也就是說(shuō)一個(gè) Skill 內(nèi)部完全可以調(diào)用多個(gè) Function也可以不發(fā)函數(shù)調(diào)用只做文本處理再寫(xiě)回記憶。Skill 是對(duì) Function 的編排和封裝同時(shí)它自身也可以有狀態(tài)和記憶讀寫(xiě)能力。理解了這層你就不會(huì)被“接入大模型就算 Agent”這種說(shuō)法帶偏了。3. 動(dòng)手前必須選型的三個(gè)關(guān)鍵點(diǎn)3.1 底層模型怎么選不是越貴越好要看你需要的“推理密度”想做 Agent第一件事是選模型。我的建議是別盲目上最大參數(shù)的商業(yè)模型先用一個(gè)推理密度適中的模型把鏈路跑通。注意我這里說(shuō)的“推理密度”是單位任務(wù)里模型需要做多少次決策。如果你的 Agent 是簡(jiǎn)單問(wèn)答型大部分模型都?jí)蛴谩５绻愕?Agent 需要自主編排工具、處理多層狀態(tài)那這個(gè)模型必須足夠“聽(tīng)話”不然你會(huì)看到它頻繁發(fā)明不存在的函數(shù)名、漏傳參數(shù)、修改記憶時(shí)格式錯(cuò)亂。就我個(gè)人經(jīng)驗(yàn)支持結(jié)構(gòu)化輸出、且對(duì)工具調(diào)用格式訓(xùn)練比較充分的模型在 Agent 場(chǎng)景下體驗(yàn)會(huì)好不少。還有一個(gè)務(wù)實(shí)的選擇把“主規(guī)劃模型”和“子任務(wù)執(zhí)行模型”分開(kāi)。規(guī)劃模型負(fù)責(zé)循環(huán)決策可以用能力高一檔的模型一些機(jī)械執(zhí)行型 Skill 內(nèi)部直接調(diào)便宜模型甚至規(guī)則邏輯沒(méi)必要全走貴模型。開(kāi)銷能差出好幾倍這是個(gè)非常實(shí)用的小技巧。3.2 Agent 框架和純手寫(xiě)之間怎么選市面上以 Agent 為賣(mài)點(diǎn)的框架不少動(dòng)不動(dòng)就是編排運(yùn)行時(shí)、插件市場(chǎng)看起來(lái)很嚇人。我個(gè)人的看法是第一次做 Agent請(qǐng)你先“手寫(xiě)骨架再考慮框架”。原因有兩個(gè)。第一框架封裝度太高你會(huì)迷失在抽象概念里很難理解記憶、角色、主動(dòng)性究竟是怎么流轉(zhuǎn)的。第二很多框架的核心玩法就是幫你拼接各類工具但一旦你遇到不滿足的邊界場(chǎng)景改框架內(nèi)部的調(diào)度邏輯往往比重新寫(xiě)一個(gè)還麻煩。反過(guò)來(lái)我也不勸你一根筋全手寫(xiě)。大模型 SDK、向量存儲(chǔ)、數(shù)據(jù)庫(kù)這些基礎(chǔ)設(shè)施該用就用但 Agent 的核心循環(huán)、Skill 注冊(cè)表、記憶操作接口這些“靈魂組件”建議第一版自己寫(xiě)一遍。這個(gè)“手寫(xiě)”的過(guò)程才是真正建立技術(shù)直覺(jué)的地方等你踩過(guò)一輪以后再去用框架你會(huì)非常清楚框架的每個(gè) API 解決的是什么問(wèn)題。3.3 任務(wù)場(chǎng)景要收斂第一個(gè) Agent 別“既要又要”選場(chǎng)景這個(gè)事我要多說(shuō)兩句。很多初學(xué)者上來(lái)就想做一個(gè)“全能生活助理”讓它管日程、查天氣、訂外賣(mài)、寫(xiě)周報(bào)結(jié)果一個(gè)都做不穩(wěn)。這里有一個(gè)設(shè)計(jì)原則叫能力半徑受控。第一個(gè) Agent 最好只做一類任務(wù)但把這類任務(wù)做到閉環(huán)。舉例來(lái)說(shuō)“日志異常分析 Agent”就是個(gè)特別合適的起步場(chǎng)景。它只有三個(gè) Skill讀日志文件、查歷史故障知識(shí)庫(kù)、生成分析報(bào)告。任務(wù)半徑小狀態(tài)有限記憶的作用明顯很容易驗(yàn)證效果。等這個(gè)跑順了再往上加 Skill、增加任務(wù)類型就不會(huì)到處著火。我相當(dāng)推薦這種從窄到寬的演進(jìn)路徑。4. 從零搭建 Skill 運(yùn)行時(shí)目錄、配置、加載機(jī)制4.1 Skill 的目錄組織與配置格式我習(xí)慣將每個(gè) Skill 拆成獨(dú)立目錄放它的描述配置和實(shí)現(xiàn)邏輯。一個(gè)標(biāo)準(zhǔn)目錄長(zhǎng)這樣skills/ ├── read_log_file/ │ ├── SKILL.md │ └── main.py ├── query_issue_kb/ │ ├── SKILL.md │ ├── main.py │ └── data_base.json └── generate_report/ ├── SKILL.md └── main.pySKILL.md是我給每個(gè) Skill 配的“身份證”里面寫(xiě)好 Agent 決策時(shí)需要用到的元信息。格式樣例--- name: read_log_file description: 讀取日志文件內(nèi)容支持按時(shí)間范圍和關(guān)鍵詞過(guò)濾。 when_to_use: 當(dāng)用戶要求分析日志、定位異常、篩選特定事件時(shí)使用。 parameters: - name: file_path type: string required: true description: 日志文件的絕對(duì)路徑或相對(duì)路徑。 - name: keyword type: string required: false description: 僅返回包含該關(guān)鍵詞的行。 - name: since type: string required: false description: ISO 格式的開(kāi)始時(shí)間如 2026-08-01T00:00:00。 --- # read_log_file 該 Skill 負(fù)責(zé)讀取本地日志文件提取關(guān)鍵信息并做初步清洗。 實(shí)現(xiàn)中要注意大文件不可以一次讀入內(nèi)存必須按行流式處理。這套配置看起來(lái)沒(méi)什么玄機(jī)但真正起作用的是when_to_use字段。模型在每個(gè)循環(huán)節(jié)點(diǎn)拿到全部 Skill 清單后會(huì)先靠name和description做粗篩再把候選 Skill 的完整配置拿出來(lái)細(xì)讀。如果description寫(xiě)得太空泛模型要么不選它要么在無(wú)關(guān)場(chǎng)景誤選它。新手最容易忽略的就是這個(gè)字段的調(diào)優(yōu)它非常影響 Agent 的工具選擇準(zhǔn)確率。4.2 Skill 實(shí)現(xiàn)為什么要統(tǒng)一接口協(xié)議每個(gè) Skill 的main.py基本邏輯可以不同但對(duì)外暴露的接口協(xié)議必須統(tǒng)一。我設(shè)計(jì)的最小協(xié)議大概這樣class BaseSkill: skill_name: str def __init__(self, context: AgentContext): # context 里裝有記憶句柄、配置、會(huì)話歷史等 pass def execute(self, **kwargs) - SkillResult: # 返回值統(tǒng)一為 SkillResult內(nèi)含狀態(tài)四要素 passSkillResult我一般會(huì)帶上四個(gè)字段output: 該 Skill 想傳遞給模型的核心信息比如報(bào)告文本、查詢結(jié)果。new_memories: 需要寫(xiě)入記憶存儲(chǔ)的內(nèi)容列表由 Skill 主動(dòng)產(chǎn)生。status:success、failure、require_more三選一。metadata: 額外追蹤用的元信息如耗時(shí)、寫(xiě)入條數(shù)。為什么非要帶new_memories字段因?yàn)?Skill 在執(zhí)行過(guò)程中很可能會(huì)發(fā)現(xiàn)有用的信息比如讀日志時(shí)發(fā)現(xiàn)某條 DMA 異常頻繁出現(xiàn)這個(gè)信息值得留存。如果 Skill 不能主動(dòng)寫(xiě)記憶那每個(gè) Skill 的發(fā)現(xiàn)就只能通過(guò)大模型下一次讀取輸出文本來(lái)間接沉淀既不準(zhǔn)確又費(fèi) token。把記憶寫(xiě)入動(dòng)作放進(jìn)接口協(xié)議里本質(zhì)上是把“記憶沉淀”變成一種可編程的硬行為而不是可選的軟行為。4.3 注冊(cè)表與加載器讓 Agent 知道自己有什么能力Skill 目錄有了、協(xié)議的骨架有了還需要一個(gè)加載器把它們都注冊(cè)到 Agent 模型中。這步的核心是“構(gòu)造 Skill 清單文本”喂給模型做動(dòng)作選擇。寫(xiě)一個(gè)最簡(jiǎn)單的加載器from pathlib import Path import importlib.util def load_all_skills(skill_root: str, ctx): skills {} for skill_dir in Path(skill_root).iterdir(): if not skill_dir.is_dir(): continue config_path skill_dir / SKILL.md main_path skill_dir / main.py if not config_path.exists() or not main_path.exists(): continue # 把 SKILL.md 的 front-matter 解析出來(lái) meta parse_front_matter(config_path.read_text(encodingutf-8)) # 動(dòng)態(tài)加載 main.py 模塊 spec importlib.util.spec_from_file_location( skill_dir.name, main_path ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) skill_instance module.Skill(ctx) skills[meta[name]] { meta: meta, instance: skill_instance } return skills別小看這個(gè)加載器它決定了你后續(xù)加新 Skill 是不是絲滑。當(dāng)你新增能力時(shí)只需要往skills目錄丟一個(gè)帶描述和實(shí)現(xiàn)的新文件夾重啟后 Agent 就能自動(dòng)感知主體代碼一行都不用改。這套插件化思想是 Agent 能力能夠持續(xù)生長(zhǎng)的基礎(chǔ)。另外解析 front-matter 時(shí)注意容錯(cuò)別讓一個(gè) Skill 的配置語(yǔ)法錯(cuò)誤導(dǎo)致整個(gè) Agent 啟動(dòng)崩潰。5. 實(shí)現(xiàn)一個(gè)最小可復(fù)用的 Agent 核心循環(huán)5.1 狀態(tài)機(jī)的結(jié)構(gòu)設(shè)計(jì)前面概念講了不少現(xiàn)在進(jìn)入到寫(xiě)代碼環(huán)節(jié)。我會(huì)做一個(gè)面向“日志異常分析”的最小 Agent它包含三個(gè) Skill讀日志文件、查詢歷史故障知識(shí)庫(kù)、生成分析報(bào)告。這個(gè)任務(wù)足夠收斂又能把記憶、角色、主動(dòng)性全部串起來(lái)。Agent 主循環(huán)的狀態(tài)管理我直接用字典保存完整代碼大概是import json import uuid class Agent: def __init__(self, llm, skill_loader, memory_store): self.llm llm self.skills skill_loader self.memory memory_store self.session_id str(uuid.uuid4()) def state_initial(self, user_request): # 初始化狀態(tài)目標(biāo)、任務(wù)描述、當(dāng)前進(jìn)度、決策歷史 return { session_id: self.session_id, goal: user_request, subtask_queue: [], plan: [], current_action_idx: 0, done: False } def decide_next_action(self, state): # 構(gòu)建 prompt包含角色設(shè)定 當(dāng)前狀態(tài)摘要 Skill 列表 可用記憶 messages self.compose_messages(state) # 模型決定下一步動(dòng)作這里要求模型輸出 JSON response self.llm.chat(messages, response_formatjson) return self.parse_action(response)這里最需要精心設(shè)計(jì)的是compose_messages這個(gè)函數(shù)本質(zhì)上是把狀態(tài)、記憶、Skill 描述變成決策上下文喂給模型。我把它拆成三塊來(lái)看。角色設(shè)定塊。每次循環(huán)都注入但并不是一大段人設(shè)模板無(wú)腦堆疊而是把當(dāng)前任務(wù)目標(biāo)、角色邊界、行業(yè)背景寫(xiě)進(jìn)去。例如“你是嵌入式方向資深代碼評(píng)審與日志分析助手只基于給定日志和知識(shí)庫(kù)信息下結(jié)論。禁止臆測(cè)寄存器位含義。若信息不足以得出結(jié)論必須明確說(shuō)明缺乏依據(jù)。”這里邊就有安全邊界和不確定處理策略。Skill 選擇清單塊。把所有可用 Skill 的name、description、parameters都列出來(lái)讓模型在每輪決策時(shí)都能看到自己能調(diào)用的“兵器庫(kù)”。這個(gè)動(dòng)作倒不用每次貼全量。如果 Skill 數(shù)量大于十來(lái)個(gè)優(yōu)先讓模型做一次粗選再給粗選結(jié)果中的 Skill 暴露詳細(xì)參數(shù)。記憶摘要塊。從長(zhǎng)期記憶里檢索與當(dāng)前任務(wù)相關(guān)的記錄比如歷史異常案例、用戶偏好、上次處理結(jié)論。記憶摘要是縮短“重新理解成本”的核心如果該塊缺失Agent 的“記憶”就名存實(shí)亡。實(shí)際執(zhí)行決策時(shí)我要求模型返回 JSON結(jié)構(gòu)統(tǒng)一為{ reasoning: 簡(jiǎn)要說(shuō)明為什么選這個(gè)動(dòng)作, next_action: call_skill|reply|require_more, skill_name: read_log_file, parameters: { file_path: logs/uart.log, since: 2026-08-01T00:00:00 } }模型輸出了結(jié)構(gòu)化指令循環(huán)體就能像一個(gè)狀態(tài)機(jī)一樣往下走了。5.2 讓 Agent 真正跑起來(lái)的 Skill 執(zhí)行器寫(xiě)執(zhí)行器時(shí)有一個(gè)細(xì)節(jié)非常關(guān)鍵Skill的執(zhí)行結(jié)果不一定是一次性成功的它可能返回的是中間信息、也可能拋異常。因此執(zhí)行器不能簡(jiǎn)單地result skill.execute()就把結(jié)果塞給模型必須做一個(gè)統(tǒng)一的包裝和異常兜底。def run_skill(self, state, skill_name, params): if skill_name not in self.skills: return { status: failure, reason: funknown skill: {skill_name} } skill_def self.skills[skill_name] try: result skill_def[instance].execute(**params) except TypeError as e: # 參數(shù)不匹配兜底把異常信息返回給模型自行調(diào)整 return { status: parameter_error, message: f參數(shù)校驗(yàn)失敗: {e}。請(qǐng)檢查參數(shù)說(shuō)明后重試。 } except Exception as e: return { status: runtime_error, message: fSkill 執(zhí)行異常: {e} } return result針對(duì)參數(shù)不匹配的錯(cuò)誤我給模型返回了一個(gè)“請(qǐng)檢查參數(shù)說(shuō)明后重試”的信號(hào)這里面有一個(gè)重要的工程經(jīng)驗(yàn)不要讓循環(huán)因?yàn)閰?shù)錯(cuò)誤直接崩潰而要把錯(cuò)誤交給模型去反思并修正。模型很多時(shí)候只是少傳了一個(gè)可選參數(shù)收到異常后它會(huì)自覺(jué)補(bǔ)調(diào)用參數(shù)。這種“模型自己修正自己”的機(jī)制能顯著提高多步驟任務(wù)的成功率。循環(huán)體在執(zhí)行完 Skill 后必須做一次“記憶吸收”把new_memories和中間觀測(cè)寫(xiě)入記憶存儲(chǔ)。同時(shí)還需要更新?tīng)顟B(tài)字典里的決策歷史格式簡(jiǎn)單追加一條{action, skill_name, result_summary, time}即可。這些決策歷史將在下一輪決策中跟記憶摘要合并作為模型的輸入形成對(duì)任務(wù)全局的掌控感。5.3 寫(xiě)一個(gè)能“記憶前文”的 Skill內(nèi)部狀態(tài)如何串起來(lái)為了展示“記憶”并非只能靠數(shù)據(jù)庫(kù)我特別演示一個(gè)帶內(nèi)部狀態(tài)翻轉(zhuǎn)的 Skill。這個(gè) Skill 叫write_analysis_snapshot它負(fù)責(zé)把每一步的中間分析結(jié)果累積到一個(gè)會(huì)話級(jí)快照文件里。# skills/write_analysis_snapshot/main.py import json from pathlib import Path class Skill: name write_analysis_snapshot def __init__(self, context: AgentContext): self.context context self.snapshot_path context.data_dir / fsnapshot_{context.session_id}.json def execute(self, content: str, step: int): # 讀取既有快照不存在則初始化 snap {} if self.snapshot_path.exists(): snap json.loads(self.snapshot_path.read_text(encodingutf-8)) snap[fstep_{step}] content self.snapshot_path.write_text( json.dumps(snap, ensure_asciiFalse, indent2), encodingutf-8 ) return { output: f已保存第 {step} 步分析快照。, new_memories: [{ type: snapshot_update, content: f寫(xiě)入快照 step_{step}, session_id: self.context.session_id }], status: success, metadata: {step: step, path: str(self.snapshot_path)} }這個(gè)例子的啟發(fā)性在于Skill不再只是無(wú)狀態(tài)函數(shù)它可以持有context操作會(huì)話級(jí)文件把一次任務(wù)過(guò)程中產(chǎn)生的中間狀態(tài)記錄下來(lái)。這對(duì)應(yīng)到現(xiàn)實(shí)場(chǎng)景就是Agent 分析了二十個(gè)日志文件后突然想回看第三步猜的寄存器配置不再需要從頭推演因?yàn)榭煺找呀?jīng)在那里了。這比“讓模型自己記住”可靠得多。5.4 加一點(diǎn)“主動(dòng)性”的味道Agent 自檢與繼續(xù)任務(wù)循環(huán)如何體現(xiàn)主動(dòng)性我加一個(gè)叫self_check的調(diào)度能力。它的觸發(fā)條件不是用戶指令而是 Agent 在主循環(huán)中發(fā)現(xiàn)“子任務(wù)尚未完成且狀態(tài)不充分”的時(shí)候。比如日志分析 Agent 讀到一個(gè)中斷風(fēng)暴關(guān)鍵詞但當(dāng)前日志時(shí)間范圍只覆蓋了后半段它應(yīng)當(dāng)自己決定“我需要擴(kuò)大時(shí)間范圍重新讀一次日志”而不是停下來(lái)問(wèn)用戶“您看接下來(lái)怎么辦”。這在代碼里表現(xiàn)為一個(gè)分支判斷當(dāng)模型決策返回的next_action是call_skill且目標(biāo) Skill 是read_log_file時(shí)循環(huán)體在更新完?duì)顟B(tài)后不結(jié)束繼續(xù)進(jìn)入下一輪決策。真正讓“主動(dòng)”落在工程上的是給模型一個(gè)開(kāi)放的動(dòng)作空間并且明確告訴他“如果發(fā)現(xiàn)結(jié)果不完整你有權(quán)調(diào)用request_range_expansion這類 Skill 來(lái)自行補(bǔ)充任務(wù)”。我在狀態(tài)機(jī)里額外維護(hù)了一個(gè)attempt_count每執(zhí)行一輪循環(huán)就加一。當(dāng)它大于閾值比如 8循環(huán)強(qiáng)制退出把當(dāng)前摘要和已確認(rèn)結(jié)論交給用戶并對(duì)未決問(wèn)題做透明度說(shuō)明。設(shè)置這個(gè)上限是防止模型在一個(gè)錯(cuò)誤的方向上反復(fù)自我修正永遠(yuǎn)跑不完。這里同樣體現(xiàn)了一個(gè) Agent 設(shè)計(jì)原則既要給自由也要給邊界。6. 落地一份可查的記憶長(zhǎng)期記憶與短時(shí)記憶的實(shí)現(xiàn)策略6.1 SQLite 方案與 JSON 方案對(duì)比關(guān)于記憶存儲(chǔ)很多教程會(huì)把向量數(shù)據(jù)庫(kù)說(shuō)成默認(rèn)選項(xiàng)但我不建議你一上來(lái)就上重型組件。以最小閉環(huán)為目標(biāo)你只需要回答三個(gè)問(wèn)題記憶存哪按什么查如何避免膨脹如果你只有幾十條記憶放在 JSON 文件里最方便。每次循環(huán)讀取整個(gè)文件、過(guò)濾出相關(guān)記錄丟給模型就行。缺點(diǎn)是數(shù)據(jù)量上來(lái)后全量讀取浪費(fèi) token也拖慢響應(yīng)。另一個(gè)方案是 SQLite輕量、無(wú)需獨(dú)立服務(wù)、支持條件查詢適合存幾千條以下的記憶記錄。這兩種方案前期的代碼復(fù)雜度差別不大SQLite 加一個(gè)標(biāo)準(zhǔn)庫(kù)即可搞定我推薦直接上 SQLite免得后期遷移。表結(jié)構(gòu)我就三張表極其簡(jiǎn)單。-- 會(huì)話表 CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, user_id TEXT, created_at TEXT ); -- 事件事實(shí)表 CREATE TABLE memories ( memory_id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, memory_type TEXT, -- preference / fact / task_result / snapshot content TEXT, created_at TEXT ); -- 記憶來(lái)源索引表 CREATE TABLE memory_links ( link_id INTEGER PRIMARY KEY AUTOINCREMENT, memory_id INTEGER, source_skill TEXT, source_step INTEGER );這種設(shè)計(jì)刻意不去碰向量索引因?yàn)槌跗谟洃浺?guī)模很小SQLite 的LIKE查詢配合時(shí)間倒序已經(jīng)足夠。只有當(dāng)記憶條數(shù)奔著十萬(wàn)條去、且你真的需要“語(yǔ)義相似召回”時(shí)才引入向量檢索這條路后頭好接。6.2 記憶寫(xiě)入時(shí)的“歸納”習(xí)慣這條是我實(shí)際用的經(jīng)驗(yàn)印象很深。剛開(kāi)始我的 Agent 把日志原文大段寫(xiě)入記憶沒(méi)過(guò)多久記憶庫(kù)就膨脹得沒(méi)法看了每次檢索都撈出一堆垃圾。后來(lái)我加了一條約束Skill 寫(xiě)記憶前必須先做歸納而不是搬運(yùn)全文。我在read_log_file的邏輯里加了剪裁函數(shù)超過(guò)一定長(zhǎng)度的內(nèi)容不直接入記憶而是摘出關(guān)鍵行、數(shù)量統(tǒng)計(jì)、級(jí)別分布再讓大模型用一句話總結(jié)發(fā)生了什么。這個(gè)抽象的過(guò)程其實(shí)給 Agent 記憶質(zhì)量帶來(lái)了質(zhì)的提升。記住記憶的目標(biāo)不是“存檔”而是“讓未來(lái)的自己快速理解以前發(fā)生了什么”。降低記憶寫(xiě)入的冗長(zhǎng)度是長(zhǎng)期維護(hù) Agent 最重要的一步。6.3 記憶的過(guò)期與優(yōu)先級(jí)讓 Agent 知道什么該忘這個(gè)點(diǎn)很多文章講不到但我認(rèn)為非常關(guān)鍵。記憶如果永遠(yuǎn)只增不減總有一天會(huì)把有效信息淹沒(méi)。我建議每個(gè)記憶帶一個(gè)priority字段從 0 到 5。偏好類記憶設(shè)置為 5 分例如“用戶偏好 C 語(yǔ)言實(shí)現(xiàn)方案”臨時(shí)過(guò)程信息設(shè)置為 1 分例如“某次運(yùn)行輸出的第一行是 SPDIF data”。檢索時(shí)按(priority DESC, created_at DESC)拉取低于閾值的記錄不進(jìn)入模型上下文。同時(shí)增加一個(gè)簡(jiǎn)單的每日清理動(dòng)作刪除priority 1且創(chuàng)建時(shí)間超過(guò) 24 小時(shí)的記憶。這讓 Agent 的長(zhǎng)期記憶更有彈性等任務(wù)跨周以后你回頭看這個(gè)設(shè)計(jì)能讓你少掉很多頭發(fā)。7. 給 Agent 注入角色感約束 Prompt、上下文模板與風(fēng)格護(hù)欄7.1 角色模板的工程化寫(xiě)法前面說(shuō)了角色要分三層我這里給一個(gè)可復(fù)用的模板結(jié)構(gòu)放在項(xiàng)目里叫agent_brain.md# Agent 角色說(shuō)明書(shū) 你是「日志偵探」一名資深的嵌入式系統(tǒng)日志分析助理。 你擅長(zhǎng)解析 UART/SPI/I2C 日志定位異常驅(qū)動(dòng)、中斷風(fēng)暴、時(shí)序紊亂等問(wèn)題。 ## 身份邊界 - 只依據(jù)用戶提供的日志與知識(shí)庫(kù)文件進(jìn)行分析。 - 禁止在沒(méi)有寄存器手冊(cè)的情況下猜測(cè)具體寄存器位含義。 - 不提供任何可導(dǎo)致設(shè)備物理?yè)p壞的操作建議。 ## 工作流程建議 1. 先讀取日志了解事件全貌。 2. 發(fā)現(xiàn)可疑模式時(shí)查詢歷史故障知識(shí)庫(kù)。 3. 結(jié)合記憶中的歷史結(jié)論形成推理鏈條。 4. 最終輸出結(jié)論時(shí)列出完整證據(jù)鏈。 ## 輸出風(fēng)格 - 先給結(jié)論后給證據(jù)。 - 每條結(jié)論需要有對(duì)應(yīng)日志行作為依據(jù)并標(biāo)注行號(hào)。 - 如果信息不足直接說(shuō)“當(dāng)前信息不足以支撐該結(jié)論”。你可能會(huì)說(shuō)這和普通 Prompt 有什么區(qū)別有但要配合代碼才會(huì)生效。我不會(huì)每輪循環(huán)無(wú)腦丟全部角色說(shuō)明書(shū)而是把它切塊按需注入。只有在出現(xiàn)“是否需要懷疑方向”的決策點(diǎn)時(shí)才注入“工作流程建議”塊只有在要生成最終結(jié)論時(shí)才注入“輸出風(fēng)格”塊。這既控制了 token 開(kāi)銷也讓模型在不同階段注意力更集中。7.2 輸出風(fēng)格護(hù)欄讓模型不“跑偏”的方法角色設(shè)定里有一部分不是給模型看的而是給后處理邏輯看的。我管它叫輸出風(fēng)格護(hù)欄。它可以實(shí)現(xiàn)為在模型生成完結(jié)果后跑一個(gè)輕量后處理函數(shù)檢查結(jié)果中是否包含“證據(jù)引用缺失”等違規(guī)情形。舉個(gè)例子日志分析 Agent 的最終報(bào)告要求每條結(jié)論必須有對(duì)應(yīng)日志行號(hào)。后處理函數(shù)逐個(gè)檢查結(jié)論文本如果某條結(jié)論后沒(méi)有形如L123的標(biāo)注就自動(dòng)插入一句“該結(jié)論缺少行號(hào)參考已跳過(guò)”。別高估模型每次都會(huì)自覺(jué)遵守格式要求。端到端任務(wù)里越往后模型越容易松懈沒(méi)有后處理護(hù)欄報(bào)告格式最終會(huì)跑偏得很隨性。7.3 人設(shè)的“動(dòng)態(tài)切換”機(jī)制一個(gè) Agent 可以同時(shí)服務(wù)多種角色嗎可以但建議你給每個(gè)角色做一個(gè)獨(dú)立的角色上下文包而不是把多角色塞進(jìn)一段 Prompt 里來(lái)回切換。我用一個(gè)叫“角色上下文分流器”的方法在請(qǐng)求入口處先讓模型做一次輕量的意圖分類把“讓我看看日志”分到日志分析 Agent 通道把“幫我寫(xiě)段代碼”分到代碼生成 Agent 通道。每個(gè)通道內(nèi)部都用完全獨(dú)立的角色設(shè)定、Skill 清單、記憶庫(kù)。這有個(gè)直接優(yōu)勢(shì)不同域的記憶天然隔離日志領(lǐng)域的觀察不會(huì)污染代碼生成領(lǐng)域的判斷。同時(shí)每個(gè) Agent 能力范圍變小錯(cuò)誤率也會(huì)降下來(lái)。很多商用 Agent 產(chǎn)品本質(zhì)上就是多個(gè)“單角色 Agent”的外殼路由這套架構(gòu)不花哨但非常穩(wěn)。8. 完整示例一個(gè)可復(fù)現(xiàn)的“帶記憶與主動(dòng)性的日志分析 Agent”8.1 項(xiàng)目目錄與代碼骨架我直接給你一份可以直接跑的最小工程結(jié)構(gòu)方便你照著抄。log_agent/ ├── agent_brain.md ├── agent_core.py ├── llm.py ├── memory_store.py ├── skills/ │ ├── __init__.py │ ├── base.py │ ├── read_log_file/ │ │ ├── SKILL.md │ │ └── main.py │ ├── query_issue_kb/ │ │ ├── SKILL.md │ │ └── main.py │ ├── write_analysis_snapshot/ │ │ ├── SKILL.md │ │ └── main.py │ └── generate_report/ │ ├── SKILL.md │ └── main.py └── data/ ├── sqlite.db └── logs/ └── uart.logmemory_store.py里封裝 SQLite 的讀寫(xiě)函數(shù)核心接口四個(gè)init_db()、add_memory()、search_memory()、cleanup_expired()。llm.py則做一層適配把通義、OpenAI 風(fēng)格 SDK 統(tǒng)一封裝成chat(messages, response_format)和embed(text)兩個(gè)方法。agent_core.py就是前面展示的主循環(huán)加執(zhí)行器實(shí)現(xiàn)組裝起來(lái)大概是這個(gè)流程啟動(dòng)時(shí)加載 Skill 和記憶把用戶請(qǐng)求放入初始狀態(tài)循環(huán)調(diào)用decide_next_action直到doneTrue或到達(dá)輪次上限。8.2 跑一個(gè)完整任務(wù)演示假設(shè)用戶在交互框輸入“幫我分析data/logs/uart.log里為什么 UART 偶發(fā)亂碼并給出建議。”第一輪循環(huán)模型讀到角色說(shuō)明書(shū) Skill 列表 當(dāng)前狀態(tài)。它選擇調(diào)用read_log_file傳參file_pathdata/logs/uart.log和keywordERROR。執(zhí)行器把日志中所有包含ERROR的行讀出來(lái)返回給模型并記錄一條摘要記憶。第二輪循環(huán)模型在決策歷史里發(fā)現(xiàn)日志中存在多個(gè)RX overrun事件。它知道項(xiàng)目學(xué)過(guò)的歷史故障知識(shí)庫(kù)里有overrun的相關(guān)案例于是調(diào)用query_issue_kb參數(shù)是keywordRX overrun。知識(shí)庫(kù)返回了歷史處理中的一條經(jīng)驗(yàn)先查 FIFO 中斷閾值配置再查 DMA 描述符是否耗盡。第三輪循環(huán)模型發(fā)現(xiàn)這兩條信息已經(jīng)可以支撐初步結(jié)論但還缺一次完整印象。它決定調(diào)用write_analysis_snapshot把前兩輪的發(fā)現(xiàn)落一份到快照文件留給后續(xù)分析沉淀。第四輪循環(huán)模型調(diào)用generate_report。它綜合日志證據(jù)、知識(shí)庫(kù)經(jīng)驗(yàn)和快照記錄生成一份包含三個(gè)證據(jù)點(diǎn)、兩個(gè)建議項(xiàng)的最終報(bào)告。輸出風(fēng)格按角色說(shuō)明書(shū)要求每條證據(jù)都帶日志行號(hào)。到這里工作流結(jié)束Agent 返回報(bào)告給用戶。這就是一個(gè)完整的“有記憶、有角色、有主動(dòng)性”的 Agent 工作過(guò)程。你看著很自然但如果沒(méi)有 Skill 的封裝、沒(méi)有記憶的沉淀、沒(méi)有每一輪“自己決定下一步”的循環(huán)機(jī)制單靠一次大模型調(diào)用是不可能走完這個(gè)鏈路的。8.3 效果評(píng)價(jià)與調(diào)優(yōu)方向跑完一輪后怎么確認(rèn)這個(gè) Agent 是合格的我用的評(píng)價(jià)項(xiàng)很簡(jiǎn)單任務(wù)完成率、工具調(diào)用準(zhǔn)確率、記憶檢索準(zhǔn)確率、最終報(bào)告的事實(shí)一致性。前三個(gè)指標(biāo)可以靠人工抽樣統(tǒng)計(jì)最后一個(gè)我會(huì)專門(mén)讓另一個(gè) LLM 實(shí)例做裁判檢查報(bào)告結(jié)論是否能從執(zhí)行日志中找到證據(jù)支撐。如果任務(wù)完成率不高先別著急換模型。你按這個(gè)順序排查Skill 描述是不是準(zhǔn)確角色說(shuō)明書(shū)是否約束了不當(dāng)輸出記憶檢索有沒(méi)有帶回正確信息執(zhí)行器異常兜底有沒(méi)有把修正機(jī)會(huì)還給模型。這個(gè)排查順序幾乎覆蓋了我的所有實(shí)戰(zhàn)調(diào)優(yōu)場(chǎng)景。9. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄9.1 為什么 Agent 總是選錯(cuò) Skill 或重復(fù)執(zhí)行同一步這個(gè)問(wèn)題我遇到最多也最容易被歸咎于“模型笨”。實(shí)際上多數(shù)原因是 Skill 清單里的描述太相似了尤其是name、description和when_to_use區(qū)分度不夠模型犯迷糊。排查建議是把全部 Skill 名稱和描述打成一個(gè)大表站在模型視角看能不能一眼分清“什么時(shí)候選誰(shuí)”。如果自己也分不清說(shuō)明描述寫(xiě)得過(guò)于抽象。重寫(xiě)時(shí)要盡量寫(xiě)清適用場(chǎng)景和反面場(chǎng)景比如read_log_file的描述可以寫(xiě)成“當(dāng)你需要讀取/查看一個(gè)日志文件的原始內(nèi)容或篩選后的內(nèi)容行時(shí)使用。如果用戶希望直接得到分析結(jié)論而不是原始日志內(nèi)容推薦使用analyze_log技能”。重復(fù)執(zhí)行同一步的問(wèn)題通常由狀態(tài)更新不及時(shí)引起。要檢查模型決策完有沒(méi)有把動(dòng)作追加到decision_history并讓新?tīng)顟B(tài)真正參與下一輪compose_messages。很多時(shí)候歷史沒(méi)喂回去模型以為自己還沒(méi)看過(guò)某個(gè)文件于是反復(fù)讀同一份日志。9.2 模型輸出亂 JSON 或虛構(gòu)參數(shù)怎么處理現(xiàn)在的大模型雖然支持結(jié)構(gòu)化輸出但偶爾仍然會(huì)出現(xiàn)格式不合法、參數(shù)名臆造問(wèn)題。建議從兩個(gè)層面預(yù)防。第一個(gè)層面是模型層約束要求模型按 JSON Schema 輸出并設(shè)定temperature較低。第二個(gè)層面是代碼層約束增加一個(gè)repair_json函數(shù)用容錯(cuò)解析邏輯過(guò)濾掉散落文本直接把最外層{...}提取出來(lái)再解析。如果解析還是失敗將原始輸出返回給模型并在提示里明確說(shuō)明“你的輸出 JSON 解析失敗{錯(cuò)誤信息}請(qǐng)只輸出合法 JSON”給它一個(gè)“補(bǔ)考”的機(jī)會(huì)。參數(shù)名虛構(gòu)通常是 Skill 配置里沒(méi)有對(duì)參數(shù)做嚴(yán)格枚舉。最簡(jiǎn)單有效的辦法是在 Skill 描述文本里把參數(shù)說(shuō)明再次寫(xiě)清楚甚至給示例值。模型看到示例以后往往能瞬間學(xué)會(huì)正確傳參這比在代碼里做一堆參數(shù)校驗(yàn)更省事。9.3 記憶庫(kù)膨脹、上下文超限怎么處理記憶庫(kù)膨脹最典型的征兆是每次決策的輸入里帶上了一大堆過(guò)期的舊信息模型決策速度變慢且容易被噪聲誤導(dǎo)。我之前靠 SQLite 的priority和created_at字段做了衰減處理已經(jīng)能緩解一大半問(wèn)題。如果仍然上下文超限可以在compose_messages階段按三類做截?cái)嘟巧f(shuō)明書(shū)只保留關(guān)鍵片段記憶摘要取最近 5 條加最高優(yōu)先級(jí) 5 條決策歷史只保留最近 3 輪摘要。還有一個(gè)技巧每次模型執(zhí)行完一輪 Skill 后不要把它返回的所有文本原封不動(dòng)存進(jìn)記憶庫(kù)而是先用一個(gè)壓縮摘要函數(shù)把關(guān)鍵結(jié)論提取出來(lái)。這個(gè)壓縮可以由 LLM 完成也可以直接采樣關(guān)鍵句。壓縮后入庫(kù)的記憶大大降低后續(xù)上下文的壓力效果立竿見(jiàn)影。9.4 主動(dòng)性的邊界Agent 自己越想越偏怎么辦自由規(guī)劃型循環(huán)最怕的一件事情是模型在某個(gè)錯(cuò)誤的中間結(jié)論上反復(fù)調(diào)用 Skill 自我驗(yàn)證形成死循環(huán)。比如它懷疑某個(gè)中斷標(biāo)志被錯(cuò)誤置位于是反復(fù)讀寄存器配置文檔每次都得不到明確答案然后它繼續(xù)換著關(guān)鍵詞查任務(wù)遲遲不結(jié)束。我的實(shí)操解法是雙重限制第一限制每個(gè)任務(wù)總循環(huán)次數(shù)比如 8 輪第二在decide_next_action的提示中顯式加入一條規(guī)則——如果最近兩次動(dòng)作里已經(jīng)包含三次同 Skill 調(diào)用且沒(méi)有新事實(shí)產(chǎn)生允許你在不調(diào)用 Skill 的情況下直接整理已知信息并給用戶一個(gè)階段性的結(jié)論不要強(qiáng)行追求完美答案。這種“允許在不確定中收尾”的指令反而是讓 Agent 更可靠的關(guān)鍵它減少了無(wú)意義的空轉(zhuǎn)。9.5 Skill 數(shù)量多了之后Agent 決策反而變差怎么辦這是個(gè)非常現(xiàn)實(shí)的問(wèn)題。Skill 清單一兩頁(yè)時(shí)還好數(shù)量漲到十個(gè)以上模型每次都要在長(zhǎng)上下文里挑工具偶爾就會(huì)漏掉更優(yōu)的工具。解決路徑有兩條一條是分層路由首頁(yè)只展示幾個(gè)粗顆粒度的入口 Skill比如“日志分析”“代碼生成”“知識(shí)檢索”具體執(zhí)行子 Skill 由入口注冊(cè)時(shí)、選擇后的局部清單來(lái)暴露。另一條是對(duì) Skill 做向量檢索匹配先按文本相似度召回 Top 5 個(gè)候選再把這些候選的描述交給模型精確決策。第二種方案在規(guī)模大的場(chǎng)景更有優(yōu)勢(shì)適合后邊需要擴(kuò)展的讀者嘗試。10. 我個(gè)人踩過(guò)的一些坑最后分享幾個(gè)非常具體、但教科書(shū)里不會(huì)寫(xiě)的經(jīng)驗(yàn)。第一Skill目錄的命名盡量用項(xiàng)目主題相關(guān)的短橫線風(fēng)格不要用中文名。我發(fā)現(xiàn)有些框架解析時(shí)能處理中文文件名但日志追蹤和異常報(bào)錯(cuò)信息里一旦混入中文路徑字符排查起來(lái)會(huì)痛苦得多。第二Agent Loop里的每輪請(qǐng)求最好在消息結(jié)構(gòu)里帶上當(dāng)前的動(dòng)作序號(hào)和總規(guī)劃哪怕是兩句話的摘要也能顯著增強(qiáng)模型對(duì)任務(wù)階段的感知力。比如狀態(tài)里寫(xiě)一條progress: 第2步/共5步已完成日志讀取正在查詢知識(shí)庫(kù)模型下一輪決策時(shí)會(huì)更像在“順著進(jìn)度往下走”而不是重新開(kāi)始找切入點(diǎn)。第三不要省掉“記憶寫(xiě)入成功”的反饋信號(hào)。每次 Skill 返回new_memories并且寫(xiě)入成功后要把“已成功記憶以下內(nèi)容xxx”反饋到模型上下文。模型如果知道自己的動(dòng)作產(chǎn)生了持久化影響后續(xù)決策會(huì)明顯更篤定。這個(gè)小改動(dòng)聽(tīng)上去很玄學(xué)但我實(shí)測(cè)下來(lái)確實(shí)能讓 Agent 的行為顯得更“有意識(shí)”。第四如果你做的是面向記錄、知識(shí)積累類的 Agent強(qiáng)烈建議每一輪循環(huán)都把Skill調(diào)用參數(shù)和返回結(jié)果的摘要保存到本地日志方便之后復(fù)現(xiàn)問(wèn)題和復(fù)盤(pán)。Agent 是一個(gè)動(dòng)態(tài)決策系統(tǒng)不像普通程序那樣“輸入相同輸出相同”。沒(méi)有決策留痕你根本無(wú)從判斷某次劣質(zhì)輸出是模型抽風(fēng)、記憶誤導(dǎo)還是 Skill 本身報(bào)錯(cuò)。這個(gè)審計(jì)日志是你調(diào)試 Agent 時(shí)最重要的抓手。這套東西看起來(lái)有不少概念其實(shí)核心就一句話Skill是 Agent 的行動(dòng)抓手記憶是它的長(zhǎng)期底盤(pán)角色是它的行為邊界主動(dòng)循環(huán)是它的引擎。四者拼到一起它才不再是一個(gè)“你問(wèn)一句、它答一句”的聊天機(jī)器人而是像一個(gè)真正有經(jīng)驗(yàn)的新人——知輕重、記得事、會(huì)自己往后走。我第一次把這套循環(huán)跑通的時(shí)候看著模型自己在日志里查出隱患、查過(guò)歷史案例、做出帶證據(jù)鏈的報(bào)告還是挺震撼的。希望這篇一步步拆解的實(shí)操內(nèi)容也能幫你體會(huì)到這種“把模型變成能干活的人”的感覺(jué)。寫(xiě)完第一版之后不要停在這里你可以再給它加新的 Skill、換更大的記憶方案、調(diào)整角色模板讓它越來(lái)越接近你想要的那個(gè)形態(tài)。 手把手實(shí)現(xiàn)AI Agent：讓Skill有記憶、角色和主動(dòng)性
如果你刷技術(shù)圈比較勤應(yīng)該已經(jīng)注意到AI Agent這個(gè)詞快被聊爛了。但說(shuō)實(shí)話大部分談 Agent 的文章都在講概念、講架構(gòu)圖真正能跟著一步步落地的實(shí)操分享反而少。我自己從最早寫(xiě)死 Prompt 玩大模型到做成有狀態(tài)、有技能包、能自己決定下一步動(dòng)作的東西中間踩的坑比想象中多得多。這篇文章我就用完全手把手的方式來(lái)拆一遍標(biāo)題是“手把手書(shū)寫(xiě)你的第一個(gè) AI Agent當(dāng) Skill 有了記憶、角色和主動(dòng)性”重點(diǎn)就在記憶、角色、主動(dòng)性這三個(gè)詞上。這三個(gè)詞恰好是普通 Prompt 封裝和真正的 Agent 之間最本質(zhì)的分界線。我不會(huì)只貼一段代碼給你看而是把每一步背后的設(shè)計(jì)依據(jù)、取舍邏輯、容易忽略的細(xì)節(jié)全部鋪開(kāi)講。看完之后你應(yīng)該能在自己的項(xiàng)目里復(fù)現(xiàn)一個(gè)帶 Skill 機(jī)制、有短期長(zhǎng)期記憶、有人設(shè)約束、具備基本主動(dòng)調(diào)度能力的 Agent 雛形。這玩意不是玩具很多商業(yè)化產(chǎn)品的底座也就是這么長(zhǎng)的。1. 先把核心問(wèn)題聊透沒(méi)有 Skill 的 Agent和大模型套殼有什么區(qū)別1.1 痛點(diǎn)來(lái)自 Prompt 工程的三個(gè)天花板我先說(shuō)一個(gè)場(chǎng)景你自己體會(huì)一下是不是遇到類似情況。假設(shè)你想讓模型扮演一個(gè)“嵌入式開(kāi)發(fā)助手”幫用戶分析日志、生成寄存器配置、檢查 GPIO 初始化代碼。如果只是用 Prompt 把角色設(shè)定寫(xiě)死再扔給模型你會(huì)遇到三個(gè)類問(wèn)題。第一模型調(diào)用的“技能”全藏在提示詞里。不管你是做日志分析、DTS 修改還是 build 錯(cuò)誤排查本質(zhì)都是上下文模板拼接。日志格式一變Prompt 就得改。更難受的是當(dāng)任務(wù)鏈路長(zhǎng)起來(lái)比如“分析日志 - 定位外設(shè)異常 - 生成補(bǔ)丁 - 跑靜態(tài)檢查”這個(gè)流程邏輯是代碼里寫(xiě)死的模型根本沒(méi)有自主規(guī)劃的空間。第二每次都像失憶一樣。上一步剛確認(rèn)完芯片型號(hào)是ESP32-S3下一步讓它生成初始化代碼時(shí)它又開(kāi)始問(wèn)你“請(qǐng)?zhí)峁┠男酒吞?hào)”。對(duì)話歷史不是沒(méi)傳而是傳了也不一定能穩(wěn)定約束后續(xù)決策尤其當(dāng)上下文超過(guò)一定長(zhǎng)度早期關(guān)鍵信息被稀釋得很厲害。第三模型沒(méi)有主動(dòng)性。它以“提問(wèn)-回答”的單輪范式活著你問(wèn)一句它回一句。真正干活的時(shí)候你希望它能自己決定“我需要先看一下寄存器手冊(cè)里的說(shuō)明再?zèng)Q定怎么改配置”然后真的去調(diào)工具、讀文檔、嘗試、校驗(yàn)、出結(jié)果。這已經(jīng)不是提示詞能解決的范圍了。這三個(gè)痛點(diǎn)是環(huán)環(huán)相扣的。技能碎片化導(dǎo)致能力邊界模糊記憶缺失導(dǎo)致決策質(zhì)量低主動(dòng)性缺失導(dǎo)致整個(gè)系統(tǒng)只能停在“高級(jí)聊天機(jī)器人”層面。而圍繞Skill構(gòu)建的自定義 Agent 架構(gòu)恰好就是沖著這三點(diǎn)去的。1.2 Skill 和 Agent 的關(guān)系不是包含而是“能力的具象化”這里要先厘清一個(gè)概念。很多人把Skill理解成“給 Agent 準(zhǔn)備的一套提示詞模板”這太窄了。還有一種說(shuō)法是 Skill 就是外部工具函數(shù)這也不夠。我傾向把 Skill 看作是“Agent 可以調(diào)用的一組帶描述、帶輸入輸出契約、帶執(zhí)行邏輯、帶狀態(tài)讀寫(xiě)權(quán)限的能力單元”。舉個(gè)好消化的類比。把 Agent 想象成一個(gè)真人新員工。這個(gè)人聰明、理解力強(qiáng)但他剛?cè)肼毷裁礃I(yè)務(wù)都不會(huì)。他需要幾樣?xùn)|西才能干活崗位說(shuō)明書(shū)角色定位、工作手冊(cè)Skill 定義、記事本記憶系統(tǒng)、以及主管授權(quán)他主動(dòng)推進(jìn)任務(wù)主動(dòng)性。所以 Skill 不只是“知識(shí)”它還包含行為邏輯。在這個(gè)框架下Agent 是執(zhí)行者Skill 是執(zhí)行者可選擇的行為包。Agent 為什么要“有” Skill因?yàn)?Skill 把模型不可控的自然語(yǔ)言能力轉(zhuǎn)化為可控的、可復(fù)用的、帶約束的模塊。模型負(fù)責(zé)判斷“我現(xiàn)在該調(diào)用哪個(gè) Skill、如何組合”Skill 負(fù)責(zé)把模型意圖翻譯成確定性邏輯。這個(gè)分工是 Agent 架構(gòu)里最核心的一層。2. 設(shè)計(jì) Agent 的四個(gè)要素記憶、角色、主動(dòng)性、工具調(diào)用2.1 記憶機(jī)制不只是塞上下文而是做狀態(tài)分層標(biāo)題里第一個(gè)關(guān)鍵詞是“記憶”。我給你一個(gè)簡(jiǎn)化的記憶分層模型。短期記憶當(dāng)前任務(wù)上下文里產(chǎn)生的關(guān)鍵信息比如用戶剛剛指定了項(xiàng)目目錄、選了某種通信協(xié)議。放內(nèi)存或會(huì)話變量里即可。長(zhǎng)期記憶跨會(huì)話保留的偏好、歷史結(jié)論、常用配置。需要持久化輕量方案是 SQLite 或本地 JSON 文件重型方案可以上向量數(shù)據(jù)庫(kù)。工作記憶Agent 當(dāng)前的思考草稿、中間結(jié)果、計(jì)劃清單。這一層容易被忽略但它決定了 Agent 能不能“邊干邊記”。實(shí)現(xiàn)上有一個(gè)非常實(shí)用的設(shè)計(jì)模式把記憶封裝成 Agent 可讀寫(xiě)的工具而不是直接改系統(tǒng) Prompt。也就是說(shuō)模型通過(guò)調(diào)用“寫(xiě)入記憶”這個(gè)動(dòng)作來(lái)留存信息通過(guò)“檢索記憶”這個(gè)動(dòng)作來(lái)獲取歷史相關(guān)內(nèi)容。這樣做最大的好處是記憶的存取時(shí)機(jī)由模型根據(jù)任務(wù)自主決定而不是每一輪都把所有歷史無(wú)腦拼進(jìn) Prompt。這個(gè)設(shè)計(jì)有直接好處上下文長(zhǎng)度可管理關(guān)鍵信息不會(huì)被沖散跨會(huì)話體驗(yàn)?zāi)苷嬲纬伞Ｎ以谧约喉?xiàng)目里用 SQLite 做了個(gè)極簡(jiǎn)版字段就四個(gè)記憶編碼、記憶類型、記憶內(nèi)容、創(chuàng)建時(shí)間。Agent 檢索時(shí)按關(guān)鍵詞匹配和創(chuàng)建時(shí)間排序取前幾條效果已經(jīng)比硬塞上下文好非常多。2.2 角色設(shè)定不是“你是一個(gè)助手”這么簡(jiǎn)單角色這個(gè)詞很多人做得太淺。早期我寫(xiě) Agent角色設(shè)定就是一句“你是一位資深嵌入式工程師”完事。后來(lái)發(fā)現(xiàn)這個(gè)“角色”對(duì)模型行為的約束非常弱模型照樣會(huì)一本正經(jīng)胡說(shuō)八道照樣會(huì)在不確定的時(shí)候亂猜。真正有效的角色設(shè)定應(yīng)該包含三層信息。第一層是身份邊界你能做什么不能做什么。比如“你是代碼評(píng)審助手只負(fù)責(zé)庫(kù)函數(shù)層面的靜態(tài)分析不做板級(jí)硬件調(diào)試”。第二層是輸出風(fēng)格約束匯報(bào)的表達(dá)習(xí)慣、是否給出代碼示例、遇到不確定時(shí)是明說(shuō)還是猜測(cè)。第三層是價(jià)值觀與安全邊界涉及到可能破壞系統(tǒng)的命令必須二次詢問(wèn)。這三層里身份邊界和風(fēng)格約束很多人會(huì)寫(xiě)但安全邊界很少被重視。實(shí)操中安全邊界最好的實(shí)現(xiàn)方式不是寫(xiě)死在角色 Prompt 里而是配備“攔截型 Skill”。比如你定義了一個(gè)執(zhí)行Shell命令的 Skill那這個(gè) Skill 內(nèi)部必須帶危險(xiǎn)命令校驗(yàn)邏輯而不是靠模型自覺(jué)。角色負(fù)責(zé)“不主動(dòng)越界”Skill 負(fù)責(zé)“越界也執(zhí)行不了”。兩道閘門(mén)都裝上系統(tǒng)才可靠。2.3 主動(dòng)性從響應(yīng)式到任務(wù)自治的機(jī)制躍遷主動(dòng)性是這三個(gè)詞里最容易被誤解的。有人覺(jué)得主動(dòng) Agent 不等人問(wèn)自己開(kāi)口說(shuō)“我來(lái)幫您……”這其實(shí)只是表面的主動(dòng)。真正的主動(dòng)性是任務(wù)調(diào)度上的自治能力當(dāng)用戶給定一個(gè)模糊目標(biāo)Agent 能自行拆解子任務(wù)、決定子任務(wù)的執(zhí)行順序、處理執(zhí)行中出現(xiàn)的異常、甚至發(fā)現(xiàn)前置信息不足時(shí)主動(dòng)查資料或提問(wèn)澄清。這套機(jī)制在工程上是靠“循環(huán)”實(shí)現(xiàn)的。經(jīng)典的結(jié)構(gòu)是Agent Loop大致流程我整理成下面這個(gè)邏輯循環(huán)開(kāi)始 1. 從任務(wù)隊(duì)列中取出當(dāng)前最優(yōu)先的子任務(wù) 2. 模型根據(jù)「當(dāng)前狀態(tài) 可用 Skill 列表 記憶摘要」決定下一步動(dòng)作 3. 如果動(dòng)作是調(diào)用 Skill - 執(zhí)行 - 把結(jié)果寫(xiě)回狀態(tài) - 更新記憶 - 回到第 1 步 4. 如果動(dòng)作是回復(fù)用戶 - 輸出最終結(jié)果 - 結(jié)束循環(huán) 5. 如果動(dòng)作是請(qǐng)求更多信息 - 拋出澄清問(wèn)題 - 暫停循環(huán)等待用戶輸入這里最關(guān)鍵的技術(shù)細(xì)節(jié)是第 2 步。模型如何知道有哪些 Skill 可用靠的不是它在訓(xùn)練數(shù)據(jù)里見(jiàn)過(guò)而是你把 Skill 的名字、用途、參數(shù)說(shuō)明喂給了它。每輪迭代前Agent 都會(huì)拿著“當(dāng)前任務(wù) Skill 清單”去決策相當(dāng)于每走一步都重新規(guī)劃一次。這樣的設(shè)計(jì)遠(yuǎn)比“預(yù)設(shè)好整個(gè)任務(wù)鏈路然后順序執(zhí)行”更魯棒。具體到實(shí)現(xiàn)有兩條路線。路線 A 是圖遍歷型你預(yù)先畫(huà)好狀態(tài)機(jī)Agent 在狀態(tài)節(jié)點(diǎn)之間跳轉(zhuǎn)。適合流程非常固定的場(chǎng)景。路線 B 是自由規(guī)劃型Agent 每次循環(huán)都自主選下一個(gè)動(dòng)作不受預(yù)設(shè)流程約束。適合探索性任務(wù)也是現(xiàn)在公認(rèn)更接近通用 Agent 的路線。新手建議從路線 B 入手代碼量不大而且能直觀感受模型“自己動(dòng)腦子”的效果。2.4 Skill 和 Function Calling 到底怎么分工讀到這里你應(yīng)該有個(gè)感覺(jué)Agent 手里的武器就是 Skill。那有的人會(huì)問(wèn)大模型本身支持 Function Calling / Tool Use為什么還要自造一個(gè) Skill 概念這兩者是什么關(guān)系我用大白話解釋一下。Function Calling 是模型輸出層面的一種結(jié)構(gòu)化調(diào)用協(xié)議它讓模型學(xué)會(huì)輸出“我想調(diào)用某個(gè)函數(shù)、傳這些參數(shù)”。它解決的是“模型怎么把意圖變成可執(zhí)行指令”這個(gè)問(wèn)題。但 Skill 是更高一層的抽象它解決的問(wèn)題是“這個(gè)能力單元內(nèi)部怎么實(shí)現(xiàn)、怎么和 Agent 的上下文與記憶協(xié)作”。也就是說(shuō)一個(gè) Skill 內(nèi)部完全可以調(diào)用多個(gè) Function也可以不發(fā)函數(shù)調(diào)用只做文本處理再寫(xiě)回記憶。Skill 是對(duì) Function 的編排和封裝同時(shí)它自身也可以有狀態(tài)和記憶讀寫(xiě)能力。理解了這層你就不會(huì)被“接入大模型就算 Agent”這種說(shuō)法帶偏了。3. 動(dòng)手前必須選型的三個(gè)關(guān)鍵點(diǎn)3.1 底層模型怎么選不是越貴越好要看你需要的“推理密度”想做 Agent第一件事是選模型。我的建議是別盲目上最大參數(shù)的商業(yè)模型先用一個(gè)推理密度適中的模型把鏈路跑通。注意我這里說(shuō)的“推理密度”是單位任務(wù)里模型需要做多少次決策。如果你的 Agent 是簡(jiǎn)單問(wèn)答型大部分模型都?jí)蛴谩５绻愕?Agent 需要自主編排工具、處理多層狀態(tài)那這個(gè)模型必須足夠“聽(tīng)話”不然你會(huì)看到它頻繁發(fā)明不存在的函數(shù)名、漏傳參數(shù)、修改記憶時(shí)格式錯(cuò)亂。就我個(gè)人經(jīng)驗(yàn)支持結(jié)構(gòu)化輸出、且對(duì)工具調(diào)用格式訓(xùn)練比較充分的模型在 Agent 場(chǎng)景下體驗(yàn)會(huì)好不少。還有一個(gè)務(wù)實(shí)的選擇把“主規(guī)劃模型”和“子任務(wù)執(zhí)行模型”分開(kāi)。規(guī)劃模型負(fù)責(zé)循環(huán)決策可以用能力高一檔的模型一些機(jī)械執(zhí)行型 Skill 內(nèi)部直接調(diào)便宜模型甚至規(guī)則邏輯沒(méi)必要全走貴模型。開(kāi)銷能差出好幾倍這是個(gè)非常實(shí)用的小技巧。3.2 Agent 框架和純手寫(xiě)之間怎么選市面上以 Agent 為賣(mài)點(diǎn)的框架不少動(dòng)不動(dòng)就是編排運(yùn)行時(shí)、插件市場(chǎng)看起來(lái)很嚇人。我個(gè)人的看法是第一次做 Agent請(qǐng)你先“手寫(xiě)骨架再考慮框架”。原因有兩個(gè)。第一框架封裝度太高你會(huì)迷失在抽象概念里很難理解記憶、角色、主動(dòng)性究竟是怎么流轉(zhuǎn)的。第二很多框架的核心玩法就是幫你拼接各類工具但一旦你遇到不滿足的邊界場(chǎng)景改框架內(nèi)部的調(diào)度邏輯往往比重新寫(xiě)一個(gè)還麻煩。反過(guò)來(lái)我也不勸你一根筋全手寫(xiě)。大模型 SDK、向量存儲(chǔ)、數(shù)據(jù)庫(kù)這些基礎(chǔ)設(shè)施該用就用但 Agent 的核心循環(huán)、Skill 注冊(cè)表、記憶操作接口這些“靈魂組件”建議第一版自己寫(xiě)一遍。這個(gè)“手寫(xiě)”的過(guò)程才是真正建立技術(shù)直覺(jué)的地方等你踩過(guò)一輪以后再去用框架你會(huì)非常清楚框架的每個(gè) API 解決的是什么問(wèn)題。3.3 任務(wù)場(chǎng)景要收斂第一個(gè) Agent 別“既要又要”選場(chǎng)景這個(gè)事我要多說(shuō)兩句。很多初學(xué)者上來(lái)就想做一個(gè)“全能生活助理”讓它管日程、查天氣、訂外賣(mài)、寫(xiě)周報(bào)結(jié)果一個(gè)都做不穩(wěn)。這里有一個(gè)設(shè)計(jì)原則叫能力半徑受控。第一個(gè) Agent 最好只做一類任務(wù)但把這類任務(wù)做到閉環(huán)。舉例來(lái)說(shuō)“日志異常分析 Agent”就是個(gè)特別合適的起步場(chǎng)景。它只有三個(gè) Skill讀日志文件、查歷史故障知識(shí)庫(kù)、生成分析報(bào)告。任務(wù)半徑小狀態(tài)有限記憶的作用明顯很容易驗(yàn)證效果。等這個(gè)跑順了再往上加 Skill、增加任務(wù)類型就不會(huì)到處著火。我相當(dāng)推薦這種從窄到寬的演進(jìn)路徑。4. 從零搭建 Skill 運(yùn)行時(shí)目錄、配置、加載機(jī)制4.1 Skill 的目錄組織與配置格式我習(xí)慣將每個(gè) Skill 拆成獨(dú)立目錄放它的描述配置和實(shí)現(xiàn)邏輯。一個(gè)標(biāo)準(zhǔn)目錄長(zhǎng)這樣skills/ ├── read_log_file/ │ ├── SKILL.md │ └── main.py ├── query_issue_kb/ │ ├── SKILL.md │ ├── main.py │ └── data_base.json └── generate_report/ ├── SKILL.md └── main.pySKILL.md是我給每個(gè) Skill 配的“身份證”里面寫(xiě)好 Agent 決策時(shí)需要用到的元信息。格式樣例--- name: read_log_file description: 讀取日志文件內(nèi)容支持按時(shí)間范圍和關(guān)鍵詞過(guò)濾。 when_to_use: 當(dāng)用戶要求分析日志、定位異常、篩選特定事件時(shí)使用。 parameters: - name: file_path type: string required: true description: 日志文件的絕對(duì)路徑或相對(duì)路徑。 - name: keyword type: string required: false description: 僅返回包含該關(guān)鍵詞的行。 - name: since type: string required: false description: ISO 格式的開(kāi)始時(shí)間如 2026-08-01T00:00:00。 --- # read_log_file 該 Skill 負(fù)責(zé)讀取本地日志文件提取關(guān)鍵信息并做初步清洗。 實(shí)現(xiàn)中要注意大文件不可以一次讀入內(nèi)存必須按行流式處理。這套配置看起來(lái)沒(méi)什么玄機(jī)但真正起作用的是when_to_use字段。模型在每個(gè)循環(huán)節(jié)點(diǎn)拿到全部 Skill 清單后會(huì)先靠name和description做粗篩再把候選 Skill 的完整配置拿出來(lái)細(xì)讀。如果description寫(xiě)得太空泛模型要么不選它要么在無(wú)關(guān)場(chǎng)景誤選它。新手最容易忽略的就是這個(gè)字段的調(diào)優(yōu)它非常影響 Agent 的工具選擇準(zhǔn)確率。4.2 Skill 實(shí)現(xiàn)為什么要統(tǒng)一接口協(xié)議每個(gè) Skill 的main.py基本邏輯可以不同但對(duì)外暴露的接口協(xié)議必須統(tǒng)一。我設(shè)計(jì)的最小協(xié)議大概這樣class BaseSkill: skill_name: str def __init__(self, context: AgentContext): # context 里裝有記憶句柄、配置、會(huì)話歷史等 pass def execute(self, **kwargs) - SkillResult: # 返回值統(tǒng)一為 SkillResult內(nèi)含狀態(tài)四要素 passSkillResult我一般會(huì)帶上四個(gè)字段output: 該 Skill 想傳遞給模型的核心信息比如報(bào)告文本、查詢結(jié)果。new_memories: 需要寫(xiě)入記憶存儲(chǔ)的內(nèi)容列表由 Skill 主動(dòng)產(chǎn)生。status:success、failure、require_more三選一。metadata: 額外追蹤用的元信息如耗時(shí)、寫(xiě)入條數(shù)。為什么非要帶new_memories字段因?yàn)?Skill 在執(zhí)行過(guò)程中很可能會(huì)發(fā)現(xiàn)有用的信息比如讀日志時(shí)發(fā)現(xiàn)某條 DMA 異常頻繁出現(xiàn)這個(gè)信息值得留存。如果 Skill 不能主動(dòng)寫(xiě)記憶那每個(gè) Skill 的發(fā)現(xiàn)就只能通過(guò)大模型下一次讀取輸出文本來(lái)間接沉淀既不準(zhǔn)確又費(fèi) token。把記憶寫(xiě)入動(dòng)作放進(jìn)接口協(xié)議里本質(zhì)上是把“記憶沉淀”變成一種可編程的硬行為而不是可選的軟行為。4.3 注冊(cè)表與加載器讓 Agent 知道自己有什么能力Skill 目錄有了、協(xié)議的骨架有了還需要一個(gè)加載器把它們都注冊(cè)到 Agent 模型中。這步的核心是“構(gòu)造 Skill 清單文本”喂給模型做動(dòng)作選擇。寫(xiě)一個(gè)最簡(jiǎn)單的加載器from pathlib import Path import importlib.util def load_all_skills(skill_root: str, ctx): skills {} for skill_dir in Path(skill_root).iterdir(): if not skill_dir.is_dir(): continue config_path skill_dir / SKILL.md main_path skill_dir / main.py if not config_path.exists() or not main_path.exists(): continue # 把 SKILL.md 的 front-matter 解析出來(lái) meta parse_front_matter(config_path.read_text(encodingutf-8)) # 動(dòng)態(tài)加載 main.py 模塊 spec importlib.util.spec_from_file_location( skill_dir.name, main_path ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) skill_instance module.Skill(ctx) skills[meta[name]] { meta: meta, instance: skill_instance } return skills別小看這個(gè)加載器它決定了你后續(xù)加新 Skill 是不是絲滑。當(dāng)你新增能力時(shí)只需要往skills目錄丟一個(gè)帶描述和實(shí)現(xiàn)的新文件夾重啟后 Agent 就能自動(dòng)感知主體代碼一行都不用改。這套插件化思想是 Agent 能力能夠持續(xù)生長(zhǎng)的基礎(chǔ)。另外解析 front-matter 時(shí)注意容錯(cuò)別讓一個(gè) Skill 的配置語(yǔ)法錯(cuò)誤導(dǎo)致整個(gè) Agent 啟動(dòng)崩潰。5. 實(shí)現(xiàn)一個(gè)最小可復(fù)用的 Agent 核心循環(huán)5.1 狀態(tài)機(jī)的結(jié)構(gòu)設(shè)計(jì)前面概念講了不少現(xiàn)在進(jìn)入到寫(xiě)代碼環(huán)節(jié)。我會(huì)做一個(gè)面向“日志異常分析”的最小 Agent它包含三個(gè) Skill讀日志文件、查詢歷史故障知識(shí)庫(kù)、生成分析報(bào)告。這個(gè)任務(wù)足夠收斂又能把記憶、角色、主動(dòng)性全部串起來(lái)。Agent 主循環(huán)的狀態(tài)管理我直接用字典保存完整代碼大概是import json import uuid class Agent: def __init__(self, llm, skill_loader, memory_store): self.llm llm self.skills skill_loader self.memory memory_store self.session_id str(uuid.uuid4()) def state_initial(self, user_request): # 初始化狀態(tài)目標(biāo)、任務(wù)描述、當(dāng)前進(jìn)度、決策歷史 return { session_id: self.session_id, goal: user_request, subtask_queue: [], plan: [], current_action_idx: 0, done: False } def decide_next_action(self, state): # 構(gòu)建 prompt包含角色設(shè)定 當(dāng)前狀態(tài)摘要 Skill 列表 可用記憶 messages self.compose_messages(state) # 模型決定下一步動(dòng)作這里要求模型輸出 JSON response self.llm.chat(messages, response_formatjson) return self.parse_action(response)這里最需要精心設(shè)計(jì)的是compose_messages這個(gè)函數(shù)本質(zhì)上是把狀態(tài)、記憶、Skill 描述變成決策上下文喂給模型。我把它拆成三塊來(lái)看。角色設(shè)定塊。每次循環(huán)都注入但并不是一大段人設(shè)模板無(wú)腦堆疊而是把當(dāng)前任務(wù)目標(biāo)、角色邊界、行業(yè)背景寫(xiě)進(jìn)去。例如“你是嵌入式方向資深代碼評(píng)審與日志分析助手只基于給定日志和知識(shí)庫(kù)信息下結(jié)論。禁止臆測(cè)寄存器位含義。若信息不足以得出結(jié)論必須明確說(shuō)明缺乏依據(jù)。”這里邊就有安全邊界和不確定處理策略。Skill 選擇清單塊。把所有可用 Skill 的name、description、parameters都列出來(lái)讓模型在每輪決策時(shí)都能看到自己能調(diào)用的“兵器庫(kù)”。這個(gè)動(dòng)作倒不用每次貼全量。如果 Skill 數(shù)量大于十來(lái)個(gè)優(yōu)先讓模型做一次粗選再給粗選結(jié)果中的 Skill 暴露詳細(xì)參數(shù)。記憶摘要塊。從長(zhǎng)期記憶里檢索與當(dāng)前任務(wù)相關(guān)的記錄比如歷史異常案例、用戶偏好、上次處理結(jié)論。記憶摘要是縮短“重新理解成本”的核心如果該塊缺失Agent 的“記憶”就名存實(shí)亡。實(shí)際執(zhí)行決策時(shí)我要求模型返回 JSON結(jié)構(gòu)統(tǒng)一為{ reasoning: 簡(jiǎn)要說(shuō)明為什么選這個(gè)動(dòng)作, next_action: call_skill|reply|require_more, skill_name: read_log_file, parameters: { file_path: logs/uart.log, since: 2026-08-01T00:00:00 } }模型輸出了結(jié)構(gòu)化指令循環(huán)體就能像一個(gè)狀態(tài)機(jī)一樣往下走了。5.2 讓 Agent 真正跑起來(lái)的 Skill 執(zhí)行器寫(xiě)執(zhí)行器時(shí)有一個(gè)細(xì)節(jié)非常關(guān)鍵Skill的執(zhí)行結(jié)果不一定是一次性成功的它可能返回的是中間信息、也可能拋異常。因此執(zhí)行器不能簡(jiǎn)單地result skill.execute()就把結(jié)果塞給模型必須做一個(gè)統(tǒng)一的包裝和異常兜底。def run_skill(self, state, skill_name, params): if skill_name not in self.skills: return { status: failure, reason: funknown skill: {skill_name} } skill_def self.skills[skill_name] try: result skill_def[instance].execute(**params) except TypeError as e: # 參數(shù)不匹配兜底把異常信息返回給模型自行調(diào)整 return { status: parameter_error, message: f參數(shù)校驗(yàn)失敗: {e}。請(qǐng)檢查參數(shù)說(shuō)明后重試。 } except Exception as e: return { status: runtime_error, message: fSkill 執(zhí)行異常: {e} } return result針對(duì)參數(shù)不匹配的錯(cuò)誤我給模型返回了一個(gè)“請(qǐng)檢查參數(shù)說(shuō)明后重試”的信號(hào)這里面有一個(gè)重要的工程經(jīng)驗(yàn)不要讓循環(huán)因?yàn)閰?shù)錯(cuò)誤直接崩潰而要把錯(cuò)誤交給模型去反思并修正。模型很多時(shí)候只是少傳了一個(gè)可選參數(shù)收到異常后它會(huì)自覺(jué)補(bǔ)調(diào)用參數(shù)。這種“模型自己修正自己”的機(jī)制能顯著提高多步驟任務(wù)的成功率。循環(huán)體在執(zhí)行完 Skill 后必須做一次“記憶吸收”把new_memories和中間觀測(cè)寫(xiě)入記憶存儲(chǔ)。同時(shí)還需要更新?tīng)顟B(tài)字典里的決策歷史格式簡(jiǎn)單追加一條{action, skill_name, result_summary, time}即可。這些決策歷史將在下一輪決策中跟記憶摘要合并作為模型的輸入形成對(duì)任務(wù)全局的掌控感。5.3 寫(xiě)一個(gè)能“記憶前文”的 Skill內(nèi)部狀態(tài)如何串起來(lái)為了展示“記憶”并非只能靠數(shù)據(jù)庫(kù)我特別演示一個(gè)帶內(nèi)部狀態(tài)翻轉(zhuǎn)的 Skill。這個(gè) Skill 叫write_analysis_snapshot它負(fù)責(zé)把每一步的中間分析結(jié)果累積到一個(gè)會(huì)話級(jí)快照文件里。# skills/write_analysis_snapshot/main.py import json from pathlib import Path class Skill: name write_analysis_snapshot def __init__(self, context: AgentContext): self.context context self.snapshot_path context.data_dir / fsnapshot_{context.session_id}.json def execute(self, content: str, step: int): # 讀取既有快照不存在則初始化 snap {} if self.snapshot_path.exists(): snap json.loads(self.snapshot_path.read_text(encodingutf-8)) snap[fstep_{step}] content self.snapshot_path.write_text( json.dumps(snap, ensure_asciiFalse, indent2), encodingutf-8 ) return { output: f已保存第 {step} 步分析快照。, new_memories: [{ type: snapshot_update, content: f寫(xiě)入快照 step_{step}, session_id: self.context.session_id }], status: success, metadata: {step: step, path: str(self.snapshot_path)} }這個(gè)例子的啟發(fā)性在于Skill不再只是無(wú)狀態(tài)函數(shù)它可以持有context操作會(huì)話級(jí)文件把一次任務(wù)過(guò)程中產(chǎn)生的中間狀態(tài)記錄下來(lái)。這對(duì)應(yīng)到現(xiàn)實(shí)場(chǎng)景就是Agent 分析了二十個(gè)日志文件后突然想回看第三步猜的寄存器配置不再需要從頭推演因?yàn)榭煺找呀?jīng)在那里了。這比“讓模型自己記住”可靠得多。5.4 加一點(diǎn)“主動(dòng)性”的味道Agent 自檢與繼續(xù)任務(wù)循環(huán)如何體現(xiàn)主動(dòng)性我加一個(gè)叫self_check的調(diào)度能力。它的觸發(fā)條件不是用戶指令而是 Agent 在主循環(huán)中發(fā)現(xiàn)“子任務(wù)尚未完成且狀態(tài)不充分”的時(shí)候。比如日志分析 Agent 讀到一個(gè)中斷風(fēng)暴關(guān)鍵詞但當(dāng)前日志時(shí)間范圍只覆蓋了后半段它應(yīng)當(dāng)自己決定“我需要擴(kuò)大時(shí)間范圍重新讀一次日志”而不是停下來(lái)問(wèn)用戶“您看接下來(lái)怎么辦”。這在代碼里表現(xiàn)為一個(gè)分支判斷當(dāng)模型決策返回的next_action是call_skill且目標(biāo) Skill 是read_log_file時(shí)循環(huán)體在更新完?duì)顟B(tài)后不結(jié)束繼續(xù)進(jìn)入下一輪決策。真正讓“主動(dòng)”落在工程上的是給模型一個(gè)開(kāi)放的動(dòng)作空間并且明確告訴他“如果發(fā)現(xiàn)結(jié)果不完整你有權(quán)調(diào)用request_range_expansion這類 Skill 來(lái)自行補(bǔ)充任務(wù)”。我在狀態(tài)機(jī)里額外維護(hù)了一個(gè)attempt_count每執(zhí)行一輪循環(huán)就加一。當(dāng)它大于閾值比如 8循環(huán)強(qiáng)制退出把當(dāng)前摘要和已確認(rèn)結(jié)論交給用戶并對(duì)未決問(wèn)題做透明度說(shuō)明。設(shè)置這個(gè)上限是防止模型在一個(gè)錯(cuò)誤的方向上反復(fù)自我修正永遠(yuǎn)跑不完。這里同樣體現(xiàn)了一個(gè) Agent 設(shè)計(jì)原則既要給自由也要給邊界。6. 落地一份可查的記憶長(zhǎng)期記憶與短時(shí)記憶的實(shí)現(xiàn)策略6.1 SQLite 方案與 JSON 方案對(duì)比關(guān)于記憶存儲(chǔ)很多教程會(huì)把向量數(shù)據(jù)庫(kù)說(shuō)成默認(rèn)選項(xiàng)但我不建議你一上來(lái)就上重型組件。以最小閉環(huán)為目標(biāo)你只需要回答三個(gè)問(wèn)題記憶存哪按什么查如何避免膨脹如果你只有幾十條記憶放在 JSON 文件里最方便。每次循環(huán)讀取整個(gè)文件、過(guò)濾出相關(guān)記錄丟給模型就行。缺點(diǎn)是數(shù)據(jù)量上來(lái)后全量讀取浪費(fèi) token也拖慢響應(yīng)。另一個(gè)方案是 SQLite輕量、無(wú)需獨(dú)立服務(wù)、支持條件查詢適合存幾千條以下的記憶記錄。這兩種方案前期的代碼復(fù)雜度差別不大SQLite 加一個(gè)標(biāo)準(zhǔn)庫(kù)即可搞定我推薦直接上 SQLite免得后期遷移。表結(jié)構(gòu)我就三張表極其簡(jiǎn)單。-- 會(huì)話表 CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, user_id TEXT, created_at TEXT ); -- 事件事實(shí)表 CREATE TABLE memories ( memory_id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, memory_type TEXT, -- preference / fact / task_result / snapshot content TEXT, created_at TEXT ); -- 記憶來(lái)源索引表 CREATE TABLE memory_links ( link_id INTEGER PRIMARY KEY AUTOINCREMENT, memory_id INTEGER, source_skill TEXT, source_step INTEGER );這種設(shè)計(jì)刻意不去碰向量索引因?yàn)槌跗谟洃浺?guī)模很小SQLite 的LIKE查詢配合時(shí)間倒序已經(jīng)足夠。只有當(dāng)記憶條數(shù)奔著十萬(wàn)條去、且你真的需要“語(yǔ)義相似召回”時(shí)才引入向量檢索這條路后頭好接。6.2 記憶寫(xiě)入時(shí)的“歸納”習(xí)慣這條是我實(shí)際用的經(jīng)驗(yàn)印象很深。剛開(kāi)始我的 Agent 把日志原文大段寫(xiě)入記憶沒(méi)過(guò)多久記憶庫(kù)就膨脹得沒(méi)法看了每次檢索都撈出一堆垃圾。后來(lái)我加了一條約束Skill 寫(xiě)記憶前必須先做歸納而不是搬運(yùn)全文。我在read_log_file的邏輯里加了剪裁函數(shù)超過(guò)一定長(zhǎng)度的內(nèi)容不直接入記憶而是摘出關(guān)鍵行、數(shù)量統(tǒng)計(jì)、級(jí)別分布再讓大模型用一句話總結(jié)發(fā)生了什么。這個(gè)抽象的過(guò)程其實(shí)給 Agent 記憶質(zhì)量帶來(lái)了質(zhì)的提升。記住記憶的目標(biāo)不是“存檔”而是“讓未來(lái)的自己快速理解以前發(fā)生了什么”。降低記憶寫(xiě)入的冗長(zhǎng)度是長(zhǎng)期維護(hù) Agent 最重要的一步。6.3 記憶的過(guò)期與優(yōu)先級(jí)讓 Agent 知道什么該忘這個(gè)點(diǎn)很多文章講不到但我認(rèn)為非常關(guān)鍵。記憶如果永遠(yuǎn)只增不減總有一天會(huì)把有效信息淹沒(méi)。我建議每個(gè)記憶帶一個(gè)priority字段從 0 到 5。偏好類記憶設(shè)置為 5 分例如“用戶偏好 C 語(yǔ)言實(shí)現(xiàn)方案”臨時(shí)過(guò)程信息設(shè)置為 1 分例如“某次運(yùn)行輸出的第一行是 SPDIF data”。檢索時(shí)按(priority DESC, created_at DESC)拉取低于閾值的記錄不進(jìn)入模型上下文。同時(shí)增加一個(gè)簡(jiǎn)單的每日清理動(dòng)作刪除priority 1且創(chuàng)建時(shí)間超過(guò) 24 小時(shí)的記憶。這讓 Agent 的長(zhǎng)期記憶更有彈性等任務(wù)跨周以后你回頭看這個(gè)設(shè)計(jì)能讓你少掉很多頭發(fā)。7. 給 Agent 注入角色感約束 Prompt、上下文模板與風(fēng)格護(hù)欄7.1 角色模板的工程化寫(xiě)法前面說(shuō)了角色要分三層我這里給一個(gè)可復(fù)用的模板結(jié)構(gòu)放在項(xiàng)目里叫agent_brain.md# Agent 角色說(shuō)明書(shū) 你是「日志偵探」一名資深的嵌入式系統(tǒng)日志分析助理。 你擅長(zhǎng)解析 UART/SPI/I2C 日志定位異常驅(qū)動(dòng)、中斷風(fēng)暴、時(shí)序紊亂等問(wèn)題。 ## 身份邊界 - 只依據(jù)用戶提供的日志與知識(shí)庫(kù)文件進(jìn)行分析。 - 禁止在沒(méi)有寄存器手冊(cè)的情況下猜測(cè)具體寄存器位含義。 - 不提供任何可導(dǎo)致設(shè)備物理?yè)p壞的操作建議。 ## 工作流程建議 1. 先讀取日志了解事件全貌。 2. 發(fā)現(xiàn)可疑模式時(shí)查詢歷史故障知識(shí)庫(kù)。 3. 結(jié)合記憶中的歷史結(jié)論形成推理鏈條。 4. 最終輸出結(jié)論時(shí)列出完整證據(jù)鏈。 ## 輸出風(fēng)格 - 先給結(jié)論后給證據(jù)。 - 每條結(jié)論需要有對(duì)應(yīng)日志行作為依據(jù)并標(biāo)注行號(hào)。 - 如果信息不足直接說(shuō)“當(dāng)前信息不足以支撐該結(jié)論”。你可能會(huì)說(shuō)這和普通 Prompt 有什么區(qū)別有但要配合代碼才會(huì)生效。我不會(huì)每輪循環(huán)無(wú)腦丟全部角色說(shuō)明書(shū)而是把它切塊按需注入。只有在出現(xiàn)“是否需要懷疑方向”的決策點(diǎn)時(shí)才注入“工作流程建議”塊只有在要生成最終結(jié)論時(shí)才注入“輸出風(fēng)格”塊。這既控制了 token 開(kāi)銷也讓模型在不同階段注意力更集中。7.2 輸出風(fēng)格護(hù)欄讓模型不“跑偏”的方法角色設(shè)定里有一部分不是給模型看的而是給后處理邏輯看的。我管它叫輸出風(fēng)格護(hù)欄。它可以實(shí)現(xiàn)為在模型生成完結(jié)果后跑一個(gè)輕量后處理函數(shù)檢查結(jié)果中是否包含“證據(jù)引用缺失”等違規(guī)情形。舉個(gè)例子日志分析 Agent 的最終報(bào)告要求每條結(jié)論必須有對(duì)應(yīng)日志行號(hào)。后處理函數(shù)逐個(gè)檢查結(jié)論文本如果某條結(jié)論后沒(méi)有形如L123的標(biāo)注就自動(dòng)插入一句“該結(jié)論缺少行號(hào)參考已跳過(guò)”。別高估模型每次都會(huì)自覺(jué)遵守格式要求。端到端任務(wù)里越往后模型越容易松懈沒(méi)有后處理護(hù)欄報(bào)告格式最終會(huì)跑偏得很隨性。7.3 人設(shè)的“動(dòng)態(tài)切換”機(jī)制一個(gè) Agent 可以同時(shí)服務(wù)多種角色嗎可以但建議你給每個(gè)角色做一個(gè)獨(dú)立的角色上下文包而不是把多角色塞進(jìn)一段 Prompt 里來(lái)回切換。我用一個(gè)叫“角色上下文分流器”的方法在請(qǐng)求入口處先讓模型做一次輕量的意圖分類把“讓我看看日志”分到日志分析 Agent 通道把“幫我寫(xiě)段代碼”分到代碼生成 Agent 通道。每個(gè)通道內(nèi)部都用完全獨(dú)立的角色設(shè)定、Skill 清單、記憶庫(kù)。這有個(gè)直接優(yōu)勢(shì)不同域的記憶天然隔離日志領(lǐng)域的觀察不會(huì)污染代碼生成領(lǐng)域的判斷。同時(shí)每個(gè) Agent 能力范圍變小錯(cuò)誤率也會(huì)降下來(lái)。很多商用 Agent 產(chǎn)品本質(zhì)上就是多個(gè)“單角色 Agent”的外殼路由這套架構(gòu)不花哨但非常穩(wěn)。8. 完整示例一個(gè)可復(fù)現(xiàn)的“帶記憶與主動(dòng)性的日志分析 Agent”8.1 項(xiàng)目目錄與代碼骨架我直接給你一份可以直接跑的最小工程結(jié)構(gòu)方便你照著抄。log_agent/ ├── agent_brain.md ├── agent_core.py ├── llm.py ├── memory_store.py ├── skills/ │ ├── __init__.py │ ├── base.py │ ├── read_log_file/ │ │ ├── SKILL.md │ │ └── main.py │ ├── query_issue_kb/ │ │ ├── SKILL.md │ │ └── main.py │ ├── write_analysis_snapshot/ │ │ ├── SKILL.md │ │ └── main.py │ └── generate_report/ │ ├── SKILL.md │ └── main.py └── data/ ├── sqlite.db └── logs/ └── uart.logmemory_store.py里封裝 SQLite 的讀寫(xiě)函數(shù)核心接口四個(gè)init_db()、add_memory()、search_memory()、cleanup_expired()。llm.py則做一層適配把通義、OpenAI 風(fēng)格 SDK 統(tǒng)一封裝成chat(messages, response_format)和embed(text)兩個(gè)方法。agent_core.py就是前面展示的主循環(huán)加執(zhí)行器實(shí)現(xiàn)組裝起來(lái)大概是這個(gè)流程啟動(dòng)時(shí)加載 Skill 和記憶把用戶請(qǐng)求放入初始狀態(tài)循環(huán)調(diào)用decide_next_action直到doneTrue或到達(dá)輪次上限。8.2 跑一個(gè)完整任務(wù)演示假設(shè)用戶在交互框輸入“幫我分析data/logs/uart.log里為什么 UART 偶發(fā)亂碼并給出建議。”第一輪循環(huán)模型讀到角色說(shuō)明書(shū) Skill 列表 當(dāng)前狀態(tài)。它選擇調(diào)用read_log_file傳參file_pathdata/logs/uart.log和keywordERROR。執(zhí)行器把日志中所有包含ERROR的行讀出來(lái)返回給模型并記錄一條摘要記憶。第二輪循環(huán)模型在決策歷史里發(fā)現(xiàn)日志中存在多個(gè)RX overrun事件。它知道項(xiàng)目學(xué)過(guò)的歷史故障知識(shí)庫(kù)里有overrun的相關(guān)案例于是調(diào)用query_issue_kb參數(shù)是keywordRX overrun。知識(shí)庫(kù)返回了歷史處理中的一條經(jīng)驗(yàn)先查 FIFO 中斷閾值配置再查 DMA 描述符是否耗盡。第三輪循環(huán)模型發(fā)現(xiàn)這兩條信息已經(jīng)可以支撐初步結(jié)論但還缺一次完整印象。它決定調(diào)用write_analysis_snapshot把前兩輪的發(fā)現(xiàn)落一份到快照文件留給后續(xù)分析沉淀。第四輪循環(huán)模型調(diào)用generate_report。它綜合日志證據(jù)、知識(shí)庫(kù)經(jīng)驗(yàn)和快照記錄生成一份包含三個(gè)證據(jù)點(diǎn)、兩個(gè)建議項(xiàng)的最終報(bào)告。輸出風(fēng)格按角色說(shuō)明書(shū)要求每條證據(jù)都帶日志行號(hào)。到這里工作流結(jié)束Agent 返回報(bào)告給用戶。這就是一個(gè)完整的“有記憶、有角色、有主動(dòng)性”的 Agent 工作過(guò)程。你看著很自然但如果沒(méi)有 Skill 的封裝、沒(méi)有記憶的沉淀、沒(méi)有每一輪“自己決定下一步”的循環(huán)機(jī)制單靠一次大模型調(diào)用是不可能走完這個(gè)鏈路的。8.3 效果評(píng)價(jià)與調(diào)優(yōu)方向跑完一輪后怎么確認(rèn)這個(gè) Agent 是合格的我用的評(píng)價(jià)項(xiàng)很簡(jiǎn)單任務(wù)完成率、工具調(diào)用準(zhǔn)確率、記憶檢索準(zhǔn)確率、最終報(bào)告的事實(shí)一致性。前三個(gè)指標(biāo)可以靠人工抽樣統(tǒng)計(jì)最后一個(gè)我會(huì)專門(mén)讓另一個(gè) LLM 實(shí)例做裁判檢查報(bào)告結(jié)論是否能從執(zhí)行日志中找到證據(jù)支撐。如果任務(wù)完成率不高先別著急換模型。你按這個(gè)順序排查Skill 描述是不是準(zhǔn)確角色說(shuō)明書(shū)是否約束了不當(dāng)輸出記憶檢索有沒(méi)有帶回正確信息執(zhí)行器異常兜底有沒(méi)有把修正機(jī)會(huì)還給模型。這個(gè)排查順序幾乎覆蓋了我的所有實(shí)戰(zhàn)調(diào)優(yōu)場(chǎng)景。9. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄9.1 為什么 Agent 總是選錯(cuò) Skill 或重復(fù)執(zhí)行同一步這個(gè)問(wèn)題我遇到最多也最容易被歸咎于“模型笨”。實(shí)際上多數(shù)原因是 Skill 清單里的描述太相似了尤其是name、description和when_to_use區(qū)分度不夠模型犯迷糊。排查建議是把全部 Skill 名稱和描述打成一個(gè)大表站在模型視角看能不能一眼分清“什么時(shí)候選誰(shuí)”。如果自己也分不清說(shuō)明描述寫(xiě)得過(guò)于抽象。重寫(xiě)時(shí)要盡量寫(xiě)清適用場(chǎng)景和反面場(chǎng)景比如read_log_file的描述可以寫(xiě)成“當(dāng)你需要讀取/查看一個(gè)日志文件的原始內(nèi)容或篩選后的內(nèi)容行時(shí)使用。如果用戶希望直接得到分析結(jié)論而不是原始日志內(nèi)容推薦使用analyze_log技能”。重復(fù)執(zhí)行同一步的問(wèn)題通常由狀態(tài)更新不及時(shí)引起。要檢查模型決策完有沒(méi)有把動(dòng)作追加到decision_history并讓新?tīng)顟B(tài)真正參與下一輪compose_messages。很多時(shí)候歷史沒(méi)喂回去模型以為自己還沒(méi)看過(guò)某個(gè)文件于是反復(fù)讀同一份日志。9.2 模型輸出亂 JSON 或虛構(gòu)參數(shù)怎么處理現(xiàn)在的大模型雖然支持結(jié)構(gòu)化輸出但偶爾仍然會(huì)出現(xiàn)格式不合法、參數(shù)名臆造問(wèn)題。建議從兩個(gè)層面預(yù)防。第一個(gè)層面是模型層約束要求模型按 JSON Schema 輸出并設(shè)定temperature較低。第二個(gè)層面是代碼層約束增加一個(gè)repair_json函數(shù)用容錯(cuò)解析邏輯過(guò)濾掉散落文本直接把最外層{...}提取出來(lái)再解析。如果解析還是失敗將原始輸出返回給模型并在提示里明確說(shuō)明“你的輸出 JSON 解析失敗{錯(cuò)誤信息}請(qǐng)只輸出合法 JSON”給它一個(gè)“補(bǔ)考”的機(jī)會(huì)。參數(shù)名虛構(gòu)通常是 Skill 配置里沒(méi)有對(duì)參數(shù)做嚴(yán)格枚舉。最簡(jiǎn)單有效的辦法是在 Skill 描述文本里把參數(shù)說(shuō)明再次寫(xiě)清楚甚至給示例值。模型看到示例以后往往能瞬間學(xué)會(huì)正確傳參這比在代碼里做一堆參數(shù)校驗(yàn)更省事。9.3 記憶庫(kù)膨脹、上下文超限怎么處理記憶庫(kù)膨脹最典型的征兆是每次決策的輸入里帶上了一大堆過(guò)期的舊信息模型決策速度變慢且容易被噪聲誤導(dǎo)。我之前靠 SQLite 的priority和created_at字段做了衰減處理已經(jīng)能緩解一大半問(wèn)題。如果仍然上下文超限可以在compose_messages階段按三類做截?cái)嘟巧f(shuō)明書(shū)只保留關(guān)鍵片段記憶摘要取最近 5 條加最高優(yōu)先級(jí) 5 條決策歷史只保留最近 3 輪摘要。還有一個(gè)技巧每次模型執(zhí)行完一輪 Skill 后不要把它返回的所有文本原封不動(dòng)存進(jìn)記憶庫(kù)而是先用一個(gè)壓縮摘要函數(shù)把關(guān)鍵結(jié)論提取出來(lái)。這個(gè)壓縮可以由 LLM 完成也可以直接采樣關(guān)鍵句。壓縮后入庫(kù)的記憶大大降低后續(xù)上下文的壓力效果立竿見(jiàn)影。9.4 主動(dòng)性的邊界Agent 自己越想越偏怎么辦自由規(guī)劃型循環(huán)最怕的一件事情是模型在某個(gè)錯(cuò)誤的中間結(jié)論上反復(fù)調(diào)用 Skill 自我驗(yàn)證形成死循環(huán)。比如它懷疑某個(gè)中斷標(biāo)志被錯(cuò)誤置位于是反復(fù)讀寄存器配置文檔每次都得不到明確答案然后它繼續(xù)換著關(guān)鍵詞查任務(wù)遲遲不結(jié)束。我的實(shí)操解法是雙重限制第一限制每個(gè)任務(wù)總循環(huán)次數(shù)比如 8 輪第二在decide_next_action的提示中顯式加入一條規(guī)則——如果最近兩次動(dòng)作里已經(jīng)包含三次同 Skill 調(diào)用且沒(méi)有新事實(shí)產(chǎn)生允許你在不調(diào)用 Skill 的情況下直接整理已知信息并給用戶一個(gè)階段性的結(jié)論不要強(qiáng)行追求完美答案。這種“允許在不確定中收尾”的指令反而是讓 Agent 更可靠的關(guān)鍵它減少了無(wú)意義的空轉(zhuǎn)。9.5 Skill 數(shù)量多了之后Agent 決策反而變差怎么辦這是個(gè)非常現(xiàn)實(shí)的問(wèn)題。Skill 清單一兩頁(yè)時(shí)還好數(shù)量漲到十個(gè)以上模型每次都要在長(zhǎng)上下文里挑工具偶爾就會(huì)漏掉更優(yōu)的工具。解決路徑有兩條一條是分層路由首頁(yè)只展示幾個(gè)粗顆粒度的入口 Skill比如“日志分析”“代碼生成”“知識(shí)檢索”具體執(zhí)行子 Skill 由入口注冊(cè)時(shí)、選擇后的局部清單來(lái)暴露。另一條是對(duì) Skill 做向量檢索匹配先按文本相似度召回 Top 5 個(gè)候選再把這些候選的描述交給模型精確決策。第二種方案在規(guī)模大的場(chǎng)景更有優(yōu)勢(shì)適合后邊需要擴(kuò)展的讀者嘗試。10. 我個(gè)人踩過(guò)的一些坑最后分享幾個(gè)非常具體、但教科書(shū)里不會(huì)寫(xiě)的經(jīng)驗(yàn)。第一Skill目錄的命名盡量用項(xiàng)目主題相關(guān)的短橫線風(fēng)格不要用中文名。我發(fā)現(xiàn)有些框架解析時(shí)能處理中文文件名但日志追蹤和異常報(bào)錯(cuò)信息里一旦混入中文路徑字符排查起來(lái)會(huì)痛苦得多。第二Agent Loop里的每輪請(qǐng)求最好在消息結(jié)構(gòu)里帶上當(dāng)前的動(dòng)作序號(hào)和總規(guī)劃哪怕是兩句話的摘要也能顯著增強(qiáng)模型對(duì)任務(wù)階段的感知力。比如狀態(tài)里寫(xiě)一條progress: 第2步/共5步已完成日志讀取正在查詢知識(shí)庫(kù)模型下一輪決策時(shí)會(huì)更像在“順著進(jìn)度往下走”而不是重新開(kāi)始找切入點(diǎn)。第三不要省掉“記憶寫(xiě)入成功”的反饋信號(hào)。每次 Skill 返回new_memories并且寫(xiě)入成功后要把“已成功記憶以下內(nèi)容xxx”反饋到模型上下文。模型如果知道自己的動(dòng)作產(chǎn)生了持久化影響后續(xù)決策會(huì)明顯更篤定。這個(gè)小改動(dòng)聽(tīng)上去很玄學(xué)但我實(shí)測(cè)下來(lái)確實(shí)能讓 Agent 的行為顯得更“有意識(shí)”。第四如果你做的是面向記錄、知識(shí)積累類的 Agent強(qiáng)烈建議每一輪循環(huán)都把Skill調(diào)用參數(shù)和返回結(jié)果的摘要保存到本地日志方便之后復(fù)現(xiàn)問(wèn)題和復(fù)盤(pán)。Agent 是一個(gè)動(dòng)態(tài)決策系統(tǒng)不像普通程序那樣“輸入相同輸出相同”。沒(méi)有決策留痕你根本無(wú)從判斷某次劣質(zhì)輸出是模型抽風(fēng)、記憶誤導(dǎo)還是 Skill 本身報(bào)錯(cuò)。這個(gè)審計(jì)日志是你調(diào)試 Agent 時(shí)最重要的抓手。這套東西看起來(lái)有不少概念其實(shí)核心就一句話Skill是 Agent 的行動(dòng)抓手記憶是它的長(zhǎng)期底盤(pán)角色是它的行為邊界主動(dòng)循環(huán)是它的引擎。四者拼到一起它才不再是一個(gè)“你問(wèn)一句、它答一句”的聊天機(jī)器人而是像一個(gè)真正有經(jīng)驗(yàn)的新人——知輕重、記得事、會(huì)自己往后走。我第一次把這套循環(huán)跑通的時(shí)候看著模型自己在日志里查出隱患、查過(guò)歷史案例、做出帶證據(jù)鏈的報(bào)告還是挺震撼的。希望這篇一步步拆解的實(shí)操內(nèi)容也能幫你體會(huì)到這種“把模型變成能干活的人”的感覺(jué)。寫(xiě)完第一版之后不要停在這里你可以再給它加新的 Skill、換更大的記憶方案、調(diào)整角色模板讓它越來(lái)越接近你想要的那個(gè)形態(tài)。