如果你也調(diào)過智能體大概率見過這種割裂感大模型嘴上功夫一流真讓它去讀寫文件、查數(shù)據(jù)、發(fā)請(qǐng)求它就當(dāng)場(chǎng)“禮貌無能”只會(huì)說“我可以幫你但需要你手動(dòng)操作”。去年我自己搭了一套叫 agent-skills 的技能庫(kù)項(xiàng)目專門治這個(gè)毛病。它不靠某個(gè)特定框架而是一套把大模型的意圖識(shí)別能力翻譯成“可執(zhí)行技能調(diào)用”的標(biāo)準(zhǔn)做法。這篇文章我會(huì)把當(dāng)初做這個(gè)技能庫(kù)的設(shè)計(jì)思路、目錄結(jié)構(gòu)、核心代碼骨架、多Agent復(fù)用的方案全都拆開講包括我踩過的坑。如果你正在做Agent、準(zhǔn)備接工具調(diào)用、或者糾結(jié)怎么讓自己的智能體能真正“干活”這篇文章應(yīng)該比看一堆概念教程有用。1. 先說清楚agent-skills 到底解決什么問題1.1 一個(gè)常見的翻車現(xiàn)場(chǎng)Agent 死活不干活我接手過一個(gè)內(nèi)部需求讓大模型讀某個(gè)數(shù)據(jù)文件按固定模板生成匯總報(bào)告然后把報(bào)告寫到指定目錄。最開始同事直接打開帶對(duì)話界面的Agent讓它“看一下文件然后生成一份周報(bào)”。結(jié)果模型每次回答都是“我可以幫你總結(jié)”可文件它始終沒讀對(duì)生成的內(nèi)容也是對(duì)話窗口里的一段文字而不是實(shí)際落盤的文件。這就暴露了當(dāng)前大模型的本質(zhì)它擅長(zhǎng)理解意圖、生成文本但天生不適合執(zhí)行精確的、有副作用的動(dòng)作。模型不是不知道“寫文件”是什么而是它沒有穩(wěn)定的“手”去調(diào)文件系統(tǒng)。你讓它連續(xù)做兩次文件操作哪怕參數(shù)一模一樣也可能一次成功、一次漏掉。這種不穩(wěn)定性靠“prompt寫得更好”很難徹底解決真正可靠的辦法是給模型配一套確定性的技能調(diào)用通道。agent-skills 出場(chǎng)的時(shí)機(jī)就在這里把每個(gè)具體動(dòng)作比如“讀取文件”“寫文件”“發(fā)HTTP請(qǐng)求”“查數(shù)據(jù)庫(kù)”“發(fā)郵件”封裝成獨(dú)立的小模塊并在模塊頂部寫清楚“什么時(shí)候用、參數(shù)是什么、返回什么樣”。大模型不需要親手執(zhí)行代碼它只需要從技能清單里挑一個(gè)、把參數(shù)填對(duì)剩下的事情由本地函數(shù)完成。1.2 技能庫(kù)的本質(zhì)把“會(huì)”變成“能做”很多人區(qū)分不了“會(huì)”和“能做”。模型讀完你的技能描述能復(fù)述功能這不難難的是在真實(shí)任務(wù)里穩(wěn)定觸發(fā)對(duì)應(yīng)動(dòng)作、傳對(duì)參數(shù)、處理好返回結(jié)果。技能庫(kù)本質(zhì)上就是在這兩層中間加一道“標(biāo)準(zhǔn)化接縫”。每個(gè)技能完成一個(gè)原子動(dòng)作。什么叫原子就是一次調(diào)用只做一件事別把“讀取文件解析內(nèi)容寫入數(shù)據(jù)庫(kù)”寫成一個(gè)技能。這樣做的好處有三個(gè)第一模型容易理解觸發(fā)條件清晰第二方便復(fù)用多個(gè)Agent都能調(diào)用同一個(gè)技能第三便于排查問題哪個(gè)技能出錯(cuò)直接把范圍縮到那一個(gè)模塊。我用 agent-skills 這個(gè)名稱也是想強(qiáng)調(diào)“技能”而不是“插件”。插件往往綁定宿主系統(tǒng)技能則更像一個(gè)能力單元有名字、有描述、有輸入輸出契約、有版本可以獨(dú)立發(fā)布和更新。換一個(gè)模型、換一個(gè)Agent框架技能定義本身不用大改。1.3 為什么叫 agent-skills而不是 plugins不是故意造詞。plugin 的隱含假設(shè)是“被宿主程序加載”而 skill 的隱含假設(shè)是“被Agent按需發(fā)現(xiàn)”。一個(gè)Agent系統(tǒng)可能同時(shí)對(duì)接文檔處理、API調(diào)用、數(shù)據(jù)分析等能力如果只做插件能力之間容易耦合成一鍋粥。但技能庫(kù)把能力拆成彼此獨(dú)立的“可檢索條目”模型選技能時(shí)更像是“搜索”而不是“調(diào)用加載器”。這個(gè)區(qū)別直接決定了設(shè)計(jì)方式。插件通常要考慮框架生命周期、生命周期鉤子、界面集成技能則只需要考慮三點(diǎn)怎么描述、怎么執(zhí)行、怎么返回。描述決定了模型會(huì)不會(huì)選中它執(zhí)行決定了能不能跑通返回決定了模型下一步怎么走。后面的設(shè)計(jì)基本都是圍繞這三件事展開的。2. 技能庫(kù)的整體設(shè)計(jì)目錄、描述、參數(shù)與返回值2.1 目錄結(jié)構(gòu)與命名規(guī)范我的技能庫(kù)在文件層面就是一個(gè)文件夾里面每個(gè)子目錄對(duì)應(yīng)一個(gè)技能。目錄名就是技能ID全局唯一。整體長(zhǎng)這樣skills/ ├── send_email/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt ├── query_order/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt ├── upload_file/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt └── calculate_date_diff/ ├── SKILL.md └── skill.py命名規(guī)范是我踩過很多次坑之后定下來的技能ID用動(dòng)詞開頭全部小寫、下劃線分隔。比如send_emailquery_order不要用emailService或者file-handling這種既有大小寫又有連字符的寫法。原因是模型在一個(gè)候選列表里做選擇時(shí)對(duì)“動(dòng)詞開頭”的短名字有天然的語義偏向一眼能看出“這技能是干什么的”。如果技能ID本身就模棱兩可模型就容易挑錯(cuò)。我試過把技能叫data_processing結(jié)果用戶說“幫我整理一下表格”時(shí)模型好幾次選了這個(gè)技能實(shí)際它連入?yún)⑹鞘裁炊颊f不清最后還得靠描述補(bǔ)。2.2 SKILL.md 描述文件長(zhǎng)什么樣每個(gè)技能目錄里必須有一個(gè)SKILL.md。這個(gè)文件主要不是給人看的是給模型看的。模型靠讀它來決定“當(dāng)前需求要不要調(diào)用這個(gè)技能”所以里面的字字句句都很關(guān)鍵。我的做法是使用 YAML front-matter 加簡(jiǎn)短說明。下面是一個(gè)例子--- name: send_email version: 1.2.0 description: 發(fā)送一封純文本郵件。適合通知、告警、報(bào)告發(fā)送等場(chǎng)景。 input: 收件人地址、郵件主題、正文。 output: 返回郵件唯一ID發(fā)送失敗時(shí)返回錯(cuò)誤信息。 when_to_use: 用戶明確要求發(fā)送郵件、提醒、告警或者需要把生成結(jié)果發(fā)給某人時(shí)。 when_not_to_use: 用戶只是討論郵件內(nèi)容或者要求發(fā)送附件的場(chǎng)景需要看附件處理技能。 permission: [network, smtp] author: internal --- ## Usage 發(fā)送一封文本郵件到指定地址。 ## Examples 用戶說給 xxxexample.com 發(fā)一封郵件主題是“周報(bào)”正文是“已完成本周工作”。 調(diào)用參數(shù){to: xxxexample.com, subject: 周報(bào), body: 已完成本周工作}你可能會(huì)覺得描述帶when_not_to_use太啰嗦但這一步很有必要。模型在沒有限制時(shí)很容易“強(qiáng)行調(diào)用”技能比如用戶明明只是問“郵件服務(wù)現(xiàn)在通不通”模型卻可能真的去發(fā)一封測(cè)試郵件。把“什么時(shí)候不該用”寫清楚能明顯降低誤調(diào)用率。description原則上不要超過200字。太長(zhǎng)了既占上下文又會(huì)讓模型抓不住重點(diǎn)。我實(shí)測(cè)下來一段100到150字、含觸發(fā)場(chǎng)景和輸入輸出的描述效果最好。2.3 參數(shù)契約讓模型像填表一樣調(diào)用技能技能描述是給模型做“要不要選我”的決策那參數(shù)定義就是給模型做“怎么填表”的決策。這塊必須用結(jié)構(gòu)化Schema不能靠自然語言描述來約束。我習(xí)慣在每個(gè)技能目錄放一個(gè)schema.json里面寫清楚參數(shù)類型、是否必填、取值范圍甚至示例值。例如send_email的參數(shù)定義{ type: object, properties: { to: { type: string, format: email, description: 收件人郵箱地址多個(gè)地址用逗號(hào)分隔 }, subject: { type: string, maxLength: 100, description: 郵件主題盡量簡(jiǎn)短 }, body: { type: string, description: 郵件正文 } }, required: [to, subject] }真正執(zhí)行前我會(huì)先用這個(gè)Schema校驗(yàn)?zāi)Ｐ蜕傻腏SON。比如模型可能把subject寫成 null或者漏掉to校驗(yàn)階段直接攔截不會(huì)進(jìn)入執(zhí)行函數(shù)。這么做不僅安全也能讓你快速發(fā)現(xiàn)問題次數(shù)多的字段反過來優(yōu)化描述。還有一個(gè)容易忽略的點(diǎn)字段名盡量用通用的小寫單詞不要用帶特殊意義的縮寫。模型如果看不懂rcpt_addr這種內(nèi)部叫法它就可能瞎猜。我后來全部改成tosubjectbody這種一看就懂的字段調(diào)用成功率明顯上升。2.4 返回值格式的約束讓結(jié)果可被后續(xù)Agent處理技能執(zhí)行完Model 還要讀返回值決定下一步。如果每個(gè)技能的返回格式都不一樣模型就亂了。所以我在 agent-skills 里統(tǒng)一了返回值格式所有技能都必須返回下面這個(gè)結(jié)構(gòu){ ok: true, data: { mail_id: a1b2c3, sent_at: 2025-01-01 10:00:00 }, error: null }失敗時(shí)返回{ ok: false, data: null, error: { code: SMTP_CONN_FAILED, message: 無法連接到郵件服務(wù)器請(qǐng)檢查網(wǎng)絡(luò)配置 } }為什么這么設(shè)計(jì)因?yàn)槟Ｐ驮跊Q定“是否再調(diào)用下一個(gè)技能”“是否要把錯(cuò)誤反饋給用戶”時(shí)需要快速識(shí)別狀態(tài)。如果每個(gè)技能成功時(shí)返回一個(gè)字符串失敗時(shí)拋個(gè)異常模型處理異常非常困難。統(tǒng)一返回值之后Agent的后續(xù)策略寫起來也簡(jiǎn)單oktrue繼續(xù)下一個(gè)動(dòng)作okfalse讀取error.message決定是否需要重新調(diào)用或告知用戶。經(jīng)驗(yàn)是error.message一定要寫成“人能看懂、模型也能直接引用”的話不要寫internal error code 503。因?yàn)槟Ｐ秃芸赡茉獠粍?dòng)地把這條信息轉(zhuǎn)述給用戶用戶看到“503”多半一臉懵。3. 核心實(shí)現(xiàn)技能注冊(cè)、加載與動(dòng)態(tài)路由3.1 注冊(cè)機(jī)制聲明文件怎么進(jìn)庫(kù)技能庫(kù)的注冊(cè)方式有兩種一種是“顯式注冊(cè)”在代碼里寫register(send_email)另一種是“隱式掃描”啟動(dòng)時(shí)掃目錄自動(dòng)發(fā)現(xiàn)。我最終選了隱式掃描主進(jìn)程代碼不用改新增技能就是“丟一個(gè)文件夾進(jìn)去”這么簡(jiǎn)單。但純掃描目錄還不夠因?yàn)榧寄茴愋臀寤ò碎T有Python函數(shù)有HTTP請(qǐng)求也有本地腳本。所以我實(shí)現(xiàn)了一個(gè)極簡(jiǎn)注冊(cè)表用裝飾器把執(zhí)行函數(shù)綁定到技能名上# registry.py _SKILLS {} def register(name, version): 注冊(cè)一個(gè)技能到全局技能表。 def wrapper(func): _SKILLS[name] {func: func, version: version} return func return wrapper然后技能模塊內(nèi)部可以這樣寫# skill.py import registry registry.register(send_email, 1.2.0) def send_email(params: dict) - dict: 執(zhí)行發(fā)送郵件的真正邏輯。 # ... 郵件發(fā)送代碼 return {ok: True, data: {mail_id: ...}, error: None}注冊(cè)表本身不負(fù)責(zé)技能描述描述還是放在SKILL.md和schema.json里。裝飾器只需要記錄哪個(gè)函數(shù)對(duì)應(yīng)哪個(gè)技能ID真正加載時(shí)再去讀描述文件。3.2 加載器掃描目錄、解析描述、綁定執(zhí)行函數(shù)加載器我寫成一個(gè)SkillManager類它做四件事掃描skills/下所有子目錄讀取每個(gè)目錄里的SKILL.md、schema.json導(dǎo)入目錄里的skill.py拿到注冊(cè)表里對(duì)應(yīng)的執(zhí)行函數(shù)組裝成完整的技能對(duì)象放進(jìn)內(nèi)存列表。示例邏輯import os import json class SkillManager: def __init__(self, skills_rootskills): self.skills_root skills_root self.skills [] def load_all(self): for skill_dir in os.listdir(self.skills_root): path os.path.join(self.skills_root, skill_dir) if not os.path.isdir(path): continue self._load_skill(path) return self.skills def _load_skill(self, path): name os.path.basename(path) skill_md_path os.path.join(path, SKILL.md) schema_path os.path.join(path, schema.json) if not os.path.exists(skill_md_path): return # 解析 SKILL.md 頭部信息簡(jiǎn)單起見用字符串處理或 PyYAML # 讀取 schema schema {} if os.path.exists(schema_path): with open(schema_path, r, encodingutf-8) as f: schema json.load(f) # 這里執(zhí)行目錄里的 skill.py并捕獲注冊(cè)表項(xiàng) # 此處略實(shí)際會(huì) importlib 動(dòng)態(tài)導(dǎo)入 self.skills.append({ name: name, description: parsed_description, schema: schema, exec_func: func_ref, })這里有個(gè)我一開始沒注意的坑動(dòng)態(tài)導(dǎo)入時(shí)技能里的skill.py應(yīng)該用importlib導(dǎo)入并且要給每個(gè)技能一個(gè)獨(dú)立命名空間避免兩個(gè)技能都叫skill.py時(shí)互相覆蓋。用importlib.import_module(f{path}.skill)會(huì)讓模塊緩存混亂我最后是直接用文件路徑的哈希生成模塊名雖然丑但穩(wěn)定。3.3 動(dòng)態(tài)路由模型怎么從小技能列表里選對(duì)技能技能加載完后核心問題就是用戶說了一句自然語言系統(tǒng)怎么知道該調(diào)哪個(gè)技能這里我不建議一上來就讓整個(gè)技能列表直接在模型調(diào)用接口里生成工具列表。技能少可以一旦超過二三十個(gè)上下文占用大模型的選擇準(zhǔn)確率也會(huì)下降。我的方案分兩層第一層是“粗篩”。用文本向量的方式把用戶輸入和每個(gè)技能的 description 做相似度匹配取 topK 候選K一般在5到10之間。這一步不需要大模型參與用本地向量庫(kù)或者簡(jiǎn)單的詞頻計(jì)算都能實(shí)現(xiàn)。第二層是“精排”。把 topK 候選技能的完整描述包括參數(shù)schema發(fā)給大模型讓它從候選里挑出真正匹配的技能并輸出調(diào)用參數(shù)。精排這一步才用到大模型的語義理解能力。這個(gè)“先粗篩后精排”的好處非常明顯上下文從幾百個(gè)技能的描述壓縮到幾個(gè)候選技能調(diào)用速度更快、模型不容易犯選擇困難癥。我早期圖省事把所有技能直接塞進(jìn)prompt結(jié)果技能到100個(gè)左右時(shí)模型經(jīng)常在幾個(gè)相似技能里“舉棋不定”偶爾還會(huì)選一個(gè)明顯不相關(guān)的。3.4 權(quán)限與隔離技能越權(quán)怎么辦技能庫(kù)最大的風(fēng)險(xiǎn)是執(zhí)行危險(xiǎn)動(dòng)作。比如某個(gè)技能可以刪文件、發(fā)外部請(qǐng)求、執(zhí)行 shell 命令如果只靠模型判斷“這個(gè)該不該調(diào)”等于把鑰匙交給一個(gè)容易犯迷糊的人遲早出事。我在 agent-skills 里給每個(gè)技能打上權(quán)限標(biāo)簽并在執(zhí)行前做檢查。比如send_email標(biāo)注permission: network, smtpdelete_file標(biāo)注permission: filesystem然后在運(yùn)行時(shí)設(shè)定一套策略如果當(dāng)前Agent沒有被授予某個(gè)權(quán)限就算模型選擇了技能系統(tǒng)也會(huì)拒絕執(zhí)行并返回PERMISSION_DENIED。對(duì)更底層的隔離我給高危技能加了沙箱機(jī)制。簡(jiǎn)單做法是讓技能跑在一個(gè)受限的臨時(shí)目錄里用完就清理再進(jìn)一步可以用subprocess隔離進(jìn)程限制可執(zhí)行文件路徑。這些措施不用一開始全做但至少要保留一個(gè)“默認(rèn)拒絕高危操作”的開關(guān)否則別人拿到你的技能庫(kù)再配一個(gè)自主權(quán)限過大的Agent風(fēng)險(xiǎn)會(huì)很大。4. 多Agent共享從單個(gè)Agent到技能市場(chǎng)4.1 多Agent場(chǎng)景下為什么需要集中式技能庫(kù)如果你只是跑一個(gè)Demo技能目錄放在本地就夠。但如果系統(tǒng)里有多個(gè)Agent分別處理客服、數(shù)據(jù)分析、自動(dòng)化運(yùn)維你再回頭看就會(huì)發(fā)現(xiàn)問題每個(gè)Agent都在重復(fù)造輪子。A Agent 寫了一個(gè)query_orderB Agent 又開始抄一份改改然后兩邊行為不一致修一個(gè) bug 還要各處同步。我在項(xiàng)目中期做了一次重構(gòu)把技能庫(kù)從“本地文件夾”升級(jí)成“集中管理”。所有技能統(tǒng)一放在一個(gè)服務(wù)里各Agent通過接口獲取技能描述、提交調(diào)用請(qǐng)求。這樣每個(gè)技能只有一份實(shí)現(xiàn)更新一次所有Agent立即生效。集中式還有個(gè)額外好處可以統(tǒng)一記錄調(diào)用日志。誰調(diào)了哪個(gè)技能、傳了什么參數(shù)、返回是否成功都集中到一個(gè)日志系統(tǒng)里。后面排查“是不是技能本身壞了還是模型選錯(cuò)了技能”會(huì)省很多力氣。4.2 技能兼容層同一個(gè)技能服務(wù)多個(gè)模型不同大模型對(duì)工具調(diào)用的格式千奇百怪。有的模型支持原生 function calling有的只支持在 prompt 里給一段 JSON 示例還有的需要用 XML 描述工具。如果每個(gè)模型都重寫一遍技能庫(kù)的適配層那會(huì)累死人。我在技能庫(kù)和模型之間加了一個(gè)兼容層。兼容層內(nèi)部維護(hù)一份統(tǒng)一的技能描述格式然后根據(jù)不同模型的目標(biāo)格式做轉(zhuǎn)譯。比如對(duì)支持 function calling 的模型把技能名、描述、schema 轉(zhuǎn)成該模型的 function 列表對(duì)不支持 function calling 的模型把技能列表轉(zhuǎn)成一個(gè)Available skills:的文本塊讓模型在回復(fù)里夾帶一段{skill: ..., params: {...}}再解析出來。這個(gè)兼容層讓同一個(gè)技能庫(kù)可以同時(shí)服務(wù)多個(gè)Agent也降低了以后換模型的成本。好處是真實(shí)存在的我有一次把某Agent的基礎(chǔ)模型從A換到B整個(gè)過程只改了兼容層里的一個(gè)適配器技能庫(kù)本身完全沒動(dòng)。4.3 技能版本號(hào)與灰度發(fā)布的實(shí)戰(zhàn)取舍技能集中之后版本管理就成了不可回避的問題。假設(shè)query_order之前返回的訂單金額字段叫amount新版改成total_amount所有依賴它的Agent都會(huì)受影響。如果沒做版本控制改一個(gè)字段可能會(huì)炸掉整個(gè)流程。我會(huì)在每個(gè)技能對(duì)象里帶version并在Agent初始化時(shí)聲明自己需要的版本范圍。集中服務(wù)更新技能時(shí)可以保留舊版本一段時(shí)間新調(diào)用走新版本舊調(diào)用繼續(xù)用舊版本直到確認(rèn)沒有異常再下掉舊版本。這一套思路本質(zhì)上就是灰度發(fā)布沒必要一開始做得很重只需要在技能服務(wù)里加一個(gè)路由策略按Agent ID或流量比例選擇不同版本。我踩過的最痛的一個(gè)坑是技能返回結(jié)構(gòu)小改但沒有同步改所有下游腳本結(jié)果某個(gè)Agent后續(xù)流程里讀舊字段得到 null 以后又去調(diào)了另一個(gè)技能最后生成了完全錯(cuò)誤的報(bào)告。自那之后我養(yǎng)成習(xí)慣技能返回結(jié)構(gòu)變更時(shí)必須發(fā)布為新的minor版本不允許原地改字段名。5. 實(shí)操落地我給 agent-skills 寫的骨架代碼5.1 最小化技能定義示例下面是一份能直接跑通最小閉環(huán)的骨架。假設(shè)我們要做一個(gè)read_file技能功能是讀取指定文本文件的原始內(nèi)容。目錄結(jié)構(gòu)skills/ └── read_file/ ├── SKILL.md ├── schema.json └── skill.pySKILL.md--- name: read_file version: 1.0.0 description: 讀取本地文本文件內(nèi)容。適合查看日志、讀取配置、加載文檔等場(chǎng)景。 input: 文件路徑。 output: 文件內(nèi)容如果文件不存在或無法讀取返回明確錯(cuò)誤。 when_to_use: 用戶要求查看某文件內(nèi)容或者后續(xù)操作需要讀取文件數(shù)據(jù)時(shí)。 when_not_to_use: 用戶只是提到文件名但未要求讀取時(shí)不要擅自調(diào)用。 permission: [filesystem] --- 讀取一個(gè)本地文件的純文本內(nèi)容。schema.json{ type: object, properties: { path: { type: string, description: 要讀取的文件的絕對(duì)路徑 } }, required: [path] }skill.pyimport registry registry.register(read_file, 1.0.0) def read_file(params: dict) - dict: path params.get(path) if not path: return {ok: False, data: None, error: {code: MISSING_PATH, message: 缺少參數(shù)path}} try: with open(path, r, encodingutf-8) as f: content f.read() except FileNotFoundError: return {ok: False, data: None, error: {code: FILE_NOT_FOUND, message: f文件不存在: {path}}} except PermissionError: return {ok: False, data: None, error: {code: PERMISSION_DENIED, message: 沒有權(quán)限讀取該文件}} return {ok: True, data: {content: content[:20000]}, error: None}注意我在返回值里把內(nèi)容截?cái)嗟?0000字。這是為了避免技能返回超長(zhǎng)文本撐爆模型上下文。真正需要完整內(nèi)容時(shí)可以追加一個(gè)max_length參數(shù)超出部分讓模型分頁(yè)讀取。5.2 加載與執(zhí)行完整流程技能庫(kù)管理器需要提供兩個(gè)核心方法list_skills和execute。前者讓上層Agent獲取技能描述列表后者按技能名執(zhí)行。# skill_manager.py class SkillManager: def __init__(self): self.skills {} # ... 加載過程省略 def list_skills(self): return [ { name: name, description: skill[description], schema: skill[schema], version: skill[version], } for name, skill in self.skills.items() ] def execute(self, name, params, timeout10): skill self.skills.get(name) if not skill: return {ok: False, data: None, error: {code: SKILL_NOT_FOUND, message: f未找到技能: {name}}} # 參數(shù)校驗(yàn) # 調(diào)用執(zhí)行函數(shù)并做超時(shí)處理 return skill[func](params)執(zhí)行時(shí)用一個(gè)超時(shí)裝飾器避免技能內(nèi)部發(fā)生死循環(huán)或網(wǎng)絡(luò)阻塞。最簡(jiǎn)單的方式是threading.Thread加result_queue或者用concurrent.futures.ThreadPoolExecutor。我實(shí)際寫的是一個(gè)run_with_timeout工具代碼不長(zhǎng)但能在技能掛死時(shí)讓Agent繼續(xù)響應(yīng)。5.3 讓它跑起來一個(gè)簡(jiǎn)單的調(diào)用示例把所有東西串起來以后使用流程大致是這樣manager SkillManager() manager.load_all() # 假設(shè)模型經(jīng)過粗篩和精排后決定調(diào)用 read_file result manager.execute(read_file, {path: /tmp/demo.txt}) print(result)輸出{ok: True, data: {content: hello, agent}, error: None}這個(gè)流程雖然樸素但已經(jīng)覆蓋了技能庫(kù)最核心的閉環(huán)描述驅(qū)動(dòng)模型選技能、參數(shù)校驗(yàn)、執(zhí)行、統(tǒng)一返回。后續(xù)要接任何Agent框架只需要在框架側(cè)把“模型輸出中的技能名參數(shù)”交給manager.execute就行。我建議先跑通這個(gè)最小版本再慢慢加向量檢索、多Agent共享和權(quán)限控制。不要一上來就把架構(gòu)搞得特別復(fù)雜否則還沒體會(huì)到技能庫(kù)的便利先被各種抽象層繞暈了。6. 常見問題與排查技巧實(shí)錄6.1 “模型就是調(diào)用不到某個(gè)技能”怎么排查這是我在群里見到最多的問題。模型明明能看到技能列表但就是不選某個(gè)技能。我排查的順序一般是這樣先看技能描述里有沒有寫到明確的觸發(fā)場(chǎng)景。比如用戶說“幫我看看昨晚的日志”技能描述如果只寫“讀取日志文件”并且沒有提到“昨天”“查看”這類詞模型就很容易漏掉。解決辦法是用真實(shí)對(duì)話語料去調(diào)描述把用戶最常說的幾種說法直接寫進(jìn)去。再看粗篩層有沒有把這個(gè)技能送進(jìn)候選。如果用的是向量相似度技能描述和用戶輸入語義差別太大topK可能就不包含它。這種情況可以在粗篩時(shí)把“技能名”和“技能關(guān)鍵詞”也加入索引不僅僅是描述文本。最后檢查是不是模型在精排階段被其它候選干擾了。如果兩個(gè)技能描述高度相似模型會(huì)難以抉擇。我一般把相似技能拆開要么合并要么在when_not_to_use里顯式區(qū)分。比如query_order和query_refund都涉及訂單就分別寫上“查詢退款信息時(shí)不要調(diào)用訂單查詢技能”。6.2 技能返回結(jié)果太啰嗦影響后續(xù)判斷另一個(gè)常見問題是技能返回了一個(gè)巨大的JSON模型讀取時(shí)占用大量上下文還可能導(dǎo)致后續(xù)調(diào)用參數(shù)填錯(cuò)。典型場(chǎng)景是查數(shù)據(jù)庫(kù)技能把整表幾萬行都帶回來。解決辦法是“大結(jié)果落盤、小結(jié)果回傳”。我把查詢類技能的返回控制在一個(gè)極小的摘要里比如返回總行數(shù)、前幾條樣例、以及一個(gè)可以繼續(xù)讀取的臨時(shí)文件路徑。模型要更多數(shù)據(jù)時(shí)再調(diào)用另一個(gè)read_partial_result技能去取指定行。返回值設(shè)計(jì)原則是只返回模型“做下一步?jīng)Q策”所需的信息不要返回執(zhí)行者覺得“完整”的信息。模型不是給人看的它不需要欣賞完整數(shù)據(jù)它只需要知道“查詢成功、有12條結(jié)果、前3條是xxx”。6.3 技能穩(wěn)定性超時(shí)、并發(fā)與重試技能庫(kù)跑久了穩(wěn)定性問題會(huì)越來越多。我遇到過幾種情況技能內(nèi)部請(qǐng)求外部API超時(shí)Agent被卡住幾十秒。我后來給所有技能執(zhí)行都套了超時(shí)默認(rèn)10秒超過就返回TIMEOUT。對(duì)重任務(wù)我會(huì)拆成“提交任務(wù)”和“查詢?nèi)蝿?wù)狀態(tài)”兩個(gè)技能避免長(zhǎng)任務(wù)長(zhǎng)時(shí)間占住Agent。并發(fā)調(diào)用時(shí)某些技能不是線程安全的。比如寫入同一個(gè)配置文件多個(gè)Agent同時(shí)調(diào)用就可能互相覆蓋。解決辦法是給技能加一把鎖同一時(shí)間只允許一個(gè)執(zhí)行或者把狀態(tài)類技能改成“寫臨時(shí)文件原子重命名”的方式最終一致地落盤。重試也要謹(jǐn)慎。如果技能不是冪等的比如發(fā)郵件、創(chuàng)建訂單重試會(huì)造成重復(fù)操作。我只對(duì)明顯冪等的技能開放自動(dòng)重試其他技能一律讓用戶確認(rèn)后重試。6.4 技能列表太長(zhǎng)導(dǎo)致模型卡頓怎么辦技能庫(kù)最終會(huì)越攢越多我目前維護(hù)的庫(kù)已經(jīng)超過80個(gè)技能。如果每次調(diào)用都把80個(gè)技能的完整描述發(fā)給模型prompt直接膨脹而且模型決策質(zhì)量會(huì)下降。我采用的分層策略是第一層粗篩。先把技能描述做摘要索引只保留約50字的關(guān)鍵描述用輕量關(guān)鍵詞匹配或向量匹配篩出top10。第二層精排。把top10的完整描述和schema發(fā)給模型。第三層動(dòng)態(tài)加載。真正確定調(diào)用某個(gè)技能時(shí)才把該技能的skill.py代碼加載進(jìn)進(jìn)程。大部分技能不需要常駐內(nèi)存。這一套下來我實(shí)測(cè)技能搜索和調(diào)用的整體延遲被壓縮到1秒以內(nèi)模型決策也更準(zhǔn)。如果你的技能數(shù)量超過200我建議再按領(lǐng)域分桶比如support/、data/、ops/Agent默認(rèn)只看到自己所在桶的技能需要跨桶再顯式檢索。7. 一些經(jīng)驗(yàn)總結(jié)7.1 技能不要一開始就設(shè)計(jì)得過于抽象新手做技能庫(kù)時(shí)很容易想造一個(gè)“萬能技能”比如execute_code或run_script覺得這樣什么都能干。我一開始也這么想過結(jié)果是模型經(jīng)常把不該執(zhí)行的代碼也往這里塞既危險(xiǎn)又不可控。后來我改成把能力拆得非常具體read_file就只讀文件write_file就只寫文件run_shell明確限制在白名單命令。雖然看起來笨但每個(gè)技能的職責(zé)清晰模型的選擇成功率一下子就上去了。技能庫(kù)的核心不是“少寫代碼”而是“讓大模型有可靠的手腳”。抽象層級(jí)太高相當(dāng)于給模型發(fā)了一把萬能工具它反而不知道怎么用。7.2 技能描述要寫給人看也要寫給模型看寫描述別只站在開發(fā)者角度要站在模型的角度。我每次新增技能都會(huì)先不看代碼只把description和幾個(gè)示例扔給模型問它“如果用戶說這句話你會(huì)調(diào)用這個(gè)技能嗎”。如果模型說“不確定”說明描述還要改。另外我強(qiáng)烈建議在描述里放一到兩個(gè)“用戶說原話”到“參數(shù)填值”的映射示例。大模型在 few-shot 場(chǎng)景下填參準(zhǔn)確率會(huì)明顯提升。比如calculate_date_diff的描述里寫示例用戶說“從今天到下周五還有幾天”參數(shù)填 {start_date: 今天, end_date: 下周五}注意示例里的參數(shù)值可以保留自然語言讓兼容層去解析模型不需要自己把“下周五”轉(zhuǎn)換成年月日。這樣能降低模型的計(jì)算負(fù)擔(dān)。7.3 保留一條手工執(zhí)行通道方便回滾最后分享一個(gè)非常重要的習(xí)慣技能庫(kù)絕對(duì)不能只有“模型自動(dòng)調(diào)用”這一條路。我在實(shí)際運(yùn)維中經(jīng)常遇到模型選錯(cuò)了技能導(dǎo)致數(shù)據(jù)被誤改的情況。這時(shí)候如果只能跟著模型走排查會(huì)非常痛苦。我在技能庫(kù)里加了一個(gè)命令行工具可以直接手動(dòng)執(zhí)行某個(gè)技能并傳參python cli.py execute read_file --param {path: /tmp/demo.txt}調(diào)試時(shí)還可以用--dry-run只打印參數(shù)和技能信息不真正執(zhí)行。有了這條手工通道定位問題就快很多先手動(dòng)跑一次技能確認(rèn)執(zhí)行函數(shù)沒問題再去查模型為什么沒選對(duì)。很多問題從一開始就能被隔離掉。如果你也在做Agent相關(guān)的項(xiàng)目我特別建議從我有一個(gè)最小技能庫(kù)開始哪怕只有兩三個(gè)技能把“描述、參數(shù)、返回、路由”這個(gè)閉環(huán)跑通再去考慮更多能力。你會(huì)發(fā)現(xiàn)大模型真正從“會(huì)聊天”變成“能干活”關(guān)鍵不在于模型本身而在于你給了它一套多可靠的“手腳”。