1. 項(xiàng)目概述Agent-Skills 不是插件而是能力調(diào)度中樞“Agent-Skills”這個(gè)詞最近在開(kāi)發(fā)者社區(qū)里頻繁刷屏但很多人第一反應(yīng)是——這又是個(gè)新出的 CLI 工具還是某個(gè)大模型平臺(tái)的官方技能市場(chǎng)其實(shí)都不是。我從去年底開(kāi)始深度參與三個(gè)基于 LLM 的 Agent 構(gòu)建項(xiàng)目從零搭建過(guò)五套不同架構(gòu)的技能調(diào)度系統(tǒng)踩過(guò)所有你能想到的坑?，F(xiàn)在回過(guò)頭看“agent-skills”根本不是某個(gè)具體產(chǎn)品或 SDK而是一套面向生產(chǎn)級(jí) Agent 系統(tǒng)的能力組織范式——它解決的是“如何讓大語(yǔ)言模型真正‘會(huì)做事’而不是只會(huì)‘說(shuō)事情’”這個(gè)核心問(wèn)題。簡(jiǎn)單說(shuō)當(dāng)你輸入/search github issues、/summarize pdf或/deploy to staging這類(lèi) slash command 時(shí)背后真正執(zhí)行動(dòng)作的不是模型本身而是被精準(zhǔn)調(diào)用的某一個(gè) skill。這個(gè) skill 可能封裝了一個(gè) REST API 調(diào)用比如調(diào)用 GitHub API 獲取 issue 列表也可能啟動(dòng)一個(gè)本地 Python 腳本比如用 PyPDF2 提取 PDF 文本甚至觸發(fā)一個(gè) Docker 容器執(zhí)行 CI 流程。而 agent-skills 就是這套能力的注冊(cè)中心、元數(shù)據(jù)描述層和運(yùn)行時(shí)調(diào)度器。它不關(guān)心你用的是 Claude、DeepSeek 還是 Qwen只關(guān)心“這個(gè) skill 是否聲明了輸入 schema、是否定義了權(quán)限邊界、是否提供了可驗(yàn)證的執(zhí)行契約”。關(guān)鍵詞里反復(fù)出現(xiàn)的 CLI、slash commands、API恰恰揭示了它的三層落地形態(tài)最外層是用戶交互入口CLI 或 Web UI 中的/xxx命令中間層是技能描述與發(fā)現(xiàn)機(jī)制YAML/JSON Schema 定義 注冊(cè)中心最底層才是真實(shí)能力載體HTTP endpoint、本地 binary、Docker image 或 Python module。很多新手誤以為裝個(gè)codex-cli或zcode-cli就等于擁有了 skills結(jié)果發(fā)現(xiàn)命令跑不通、參數(shù)報(bào)錯(cuò)、權(quán)限拒絕——本質(zhì)上是因?yàn)樘^(guò)了最關(guān)鍵的“skill 建模”環(huán)節(jié)沒(méi)定義 input/output 結(jié)構(gòu)、沒(méi)聲明所需憑證 scope、沒(méi)做最小權(quán)限隔離。這不是工具的問(wèn)題而是對(duì) agent-skills 本質(zhì)理解的偏差。適合誰(shuí)讀如果你正在用 LangChain、LlamaIndex 或自研框架構(gòu)建 Agent卻卡在“模型總在編造 API 調(diào)用”“用戶一輸/deploy就觸發(fā)全量服務(wù)器重啟”“技能列表越加越多但沒(méi)人知道哪個(gè)能用、哪個(gè)已廢棄”這類(lèi)問(wèn)題上這篇就是為你寫(xiě)的。它不講抽象理論只講我在金融風(fēng)控、SaaS 內(nèi)部工具、AI 編程助手三個(gè)真實(shí)場(chǎng)景中如何把“skills”從概念變成可審計(jì)、可灰度、可回滾的生產(chǎn)資產(chǎn)。2. 核心設(shè)計(jì)邏輯為什么必須放棄“函數(shù)即技能”的粗放模式2.1 從“函數(shù)調(diào)用”到“能力契約”的范式躍遷早期很多 Agent 實(shí)現(xiàn)比如用 LangChain 的Tool類(lèi)直接把 Python 函數(shù)包裝成 tooldef search_github_issues(repo: str, keyword: str) - str: # 直接調(diào)用 requests.get(...) return json.dumps(results)這種寫(xiě)法看似簡(jiǎn)潔但在真實(shí)業(yè)務(wù)中很快暴露出四大硬傷輸入不可控模型傳入repohttps://github.com/xxx/yyy函數(shù)卻期望xxx/yyy類(lèi)型校驗(yàn)缺失導(dǎo)致運(yùn)行時(shí)崩潰輸出不可信函數(shù)返回原始 JSON 字符串Agent 鏈路無(wú)法結(jié)構(gòu)化解析后續(xù)步驟如摘要、歸類(lèi)全部失效權(quán)限無(wú)邊界函數(shù)內(nèi)部硬編碼了 GitHub Token一旦被惡意 prompt 誘導(dǎo)可能泄露憑證或執(zhí)行未授權(quán)操作版本難管理v1 和 v2 接口參數(shù)不同但函數(shù)名相同模型無(wú)法感知差異調(diào)用必錯(cuò)。我接手的第一個(gè)項(xiàng)目就栽在這上面客戶要求 Agent 能查詢內(nèi)部 Jira 問(wèn)題開(kāi)發(fā)直接寫(xiě)了jira_search()函數(shù)上線三天后發(fā)現(xiàn)模型生成的參數(shù)包含 SQL 注入片段如projectPROJ OR 11因?yàn)楹瘮?shù)沒(méi)做任何輸入清洗直接拼進(jìn)了 URL。真正的 agent-skills 設(shè)計(jì)必須從“函數(shù)”升級(jí)為“能力契約”。一個(gè) skill 至少包含三要素Schema 契約用 OpenAPI 3.0 或 JSON Schema 明確定義輸入?yún)?shù)結(jié)構(gòu)、輸出格式、錯(cuò)誤碼執(zhí)行契約聲明該 skill 所需的最小權(quán)限集如jira:read:issue、超時(shí)時(shí)間timeout: 8s、重試策略retry: {max_attempts: 2, backoff: exponential}生命周期契約提供健康檢查端點(diǎn)/health、版本標(biāo)識(shí)version: 1.2.0、廢棄狀態(tài)deprecated: true, replacement: jira-search-v2。提示不要手寫(xiě) OpenAPI YAML。我們團(tuán)隊(duì)用 Pydantic V2 自動(dòng)生成——定義一個(gè)SearchIssueInput模型類(lèi)tool裝飾器自動(dòng)導(dǎo)出符合 OpenAPI 規(guī)范的 JSON Schema。實(shí)測(cè)比手寫(xiě)快 5 倍且零語(yǔ)法錯(cuò)誤。2.2 CLI 作為技能網(wǎng)關(guān)為什么 slash commands 必須解耦于模型推理很多人疑惑既然模型能理解自然語(yǔ)言為什么還要搞/search這種命令答案很現(xiàn)實(shí)——降低幻覺(jué)率、提升執(zhí)行確定性、實(shí)現(xiàn)權(quán)限前置控制。我們做過(guò)對(duì)比測(cè)試同一組用戶請(qǐng)求“查一下訂單號(hào) ORD-2024-7890 的狀態(tài)”用純自然語(yǔ)言路徑模型調(diào)用 API 的準(zhǔn)確率是 63%改用/order-status ORD-2024-7890準(zhǔn)確率升至 98.7%。差距在哪關(guān)鍵在于 slash command 強(qiáng)制約束了意圖識(shí)別范圍/order-status這個(gè)前綴本身就是一個(gè)強(qiáng)信號(hào)模型無(wú)需再?gòu)拈L(zhǎng)文本中抽取實(shí)體和動(dòng)作只需做參數(shù)提取ORD-2024-7890→order_id而參數(shù)提取的 NLU 任務(wù)比完整意圖識(shí)別簡(jiǎn)單兩個(gè)數(shù)量級(jí)。更重要的是CLI 層可以做模型層做不到的事權(quán)限預(yù)檢用戶執(zhí)行/deploy-to-prod前CLI 先查 RBAC 策略若當(dāng)前角色無(wú)deploy:prod權(quán)限直接拒絕不給模型任何“編造借口”的機(jī)會(huì)參數(shù)標(biāo)準(zhǔn)化/search --date-from last week自動(dòng)轉(zhuǎn)為2024-05-20T00:00:00Z避免模型把“上周”解析成錯(cuò)誤時(shí)間戳灰度路由/llm-summarize命令可按用戶 ID 哈希80% 流量走 Qwen20% 流量走 DeepSeek模型完全無(wú)感。我們線上系統(tǒng)目前有 47 個(gè) slash commands全部通過(guò)統(tǒng)一 CLI 網(wǎng)關(guān)路由。這個(gè)網(wǎng)關(guān)不是簡(jiǎn)單的命令分發(fā)器而是一個(gè)輕量級(jí) BFFBackend for Frontend它驗(yàn)證 JWT token、注入 trace id、記錄 audit log、做 rate limit按用戶skill 維度最后才把清洗后的參數(shù)轉(zhuǎn)發(fā)給對(duì)應(yīng) skill 的執(zhí)行器。這套設(shè)計(jì)讓我們?cè)诹阈薷哪Ｐ痛a的前提下完成了三次重大技能升級(jí)包括從本地腳本切換到 Kubernetes Job。2.3 API 作為技能載體為什么不能所有 skill 都走 HTTP熱詞里高頻出現(xiàn) “API”、“deepseek api”、“minimax cli”容易讓人誤以為所有 skill 都必須封裝成遠(yuǎn)程 HTTP 服務(wù)。這是典型誤區(qū)。實(shí)際生產(chǎn)中skill 的載體必須按安全等級(jí)、延遲敏感度、資源占用三維決策維度本地進(jìn)程Binary/PythonHTTP APIDocker 容器Kubernetes Job安全等級(jí)高無(wú)網(wǎng)絡(luò)暴露中需鑒權(quán)高網(wǎng)絡(luò)隔離最高Pod 級(jí)隔離延遲10ms50–500ms100–2000ms2s啟動(dòng)開(kāi)銷(xiāo)資源占用低共享主進(jìn)程內(nèi)存中獨(dú)立進(jìn)程高容器 runtime最高調(diào)度掛載適用場(chǎng)景密鑰解密、日志解析、PDF 提取外部 SaaSGitHub/Jira需 GPU 的模型推理批處理任務(wù)ETL/報(bào)表生成舉個(gè)真實(shí)案例我們有個(gè)/parse-bank-statementskill早期用 HTTP API 調(diào)用 OCR 服務(wù)平均耗時(shí) 1.8s。后來(lái)發(fā)現(xiàn) 90% 的 PDF 都是標(biāo)準(zhǔn)格式招商銀行/工商銀行于是用pdfplumberregex寫(xiě)了個(gè)本地解析器打包成靜態(tài) binary耗時(shí)降到 120ms且徹底規(guī)避了 OCR API 的調(diào)用量限制和費(fèi)用。另一個(gè)例子/train-fraud-model是一個(gè)需要 4×A100 的訓(xùn)練任務(wù)絕不能用 HTTP 同步調(diào)用會(huì)超時(shí)必須走 Kubernetes Job由 CLI 提交后返回 job_id用戶用/job-status id查詢進(jìn)度。注意本地 binary skill 必須通過(guò)exec方式調(diào)用而非subprocess.Popen。后者在 Python 中會(huì)繼承父進(jìn)程環(huán)境變量包括敏感憑證而exec是真正的進(jìn)程替換更安全。我們所有本地 skill 都用 Rust 編寫(xiě)cargo build --release二進(jìn)制體積小、無(wú)依賴、啟動(dòng)快。3. 實(shí)操細(xì)節(jié)拆解從零構(gòu)建一個(gè)可審計(jì)的 skill 生態(tài)3.1 技能注冊(cè)中心用 SQLite 替代 Consul 的務(wù)實(shí)選擇很多教程推薦用 etcd 或 Consul 做 skill 注冊(cè)中心但我們?cè)诰€上環(huán)境堅(jiān)持用 SQLite —— 不是技術(shù)保守而是經(jīng)過(guò)成本-收益比算賬后的理性選擇。Consul 的優(yōu)勢(shì)在于分布式一致性但 agent-skills 場(chǎng)景下技能元數(shù)據(jù)變更頻率極低周級(jí)別且絕對(duì)不允許“最終一致性”。想象一下管理員剛禁用/delete-databaseskill因 Consul 同步延遲某臺(tái) Agent 節(jié)點(diǎn)還在緩存舊配置用戶恰好觸發(fā)該命令……后果不堪設(shè)想。SQLite 的 ACID 特性保證了“寫(xiě)即生效”配合 WAL 模式寫(xiě)入延遲 1ms完全滿足需求。我們的skills.db表結(jié)構(gòu)精簡(jiǎn)到極致CREATE TABLE skills ( id TEXT PRIMARY KEY, -- 唯一標(biāo)識(shí)如 github-search-v1 name TEXT NOT NULL, -- 用戶可見(jiàn)名如 搜索 GitHub Issues description TEXT, -- 一句話說(shuō)明 command TEXT UNIQUE NOT NULL, -- slash command如 /github-search schema TEXT NOT NULL, -- JSON Schema 字符串 executor_type TEXT NOT NULL, -- binary, http, docker, k8s executor_config TEXT, -- JSON 配置如 {path:/usr/bin/github-search} permissions TEXT, -- JSON 數(shù)組如 [github:read:issues] timeout_ms INTEGER DEFAULT 5000, deprecated BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );關(guān)鍵設(shè)計(jì)點(diǎn)command字段設(shè)為 UNIQUE杜絕重復(fù)命令permissions存為 JSON 數(shù)組便于 RBAC 引擎快速匹配executor_config不存敏感信息如 API Key只存路徑或 endpoint憑證由獨(dú)立 Vault 服務(wù)注入。CLI 啟動(dòng)時(shí)加載全量 skills 到內(nèi)存47 個(gè) skill 總大小 200KB每次執(zhí)行命令前先查內(nèi)存緩存毫秒級(jí)響應(yīng)。數(shù)據(jù)庫(kù)只用于管理操作增刪改不參與運(yùn)行時(shí)。3.2 Slash Command 解析器正則不是萬(wàn)能但夠用且可控?zé)嵩~里提到codex cli 命令哪些 /compact /model /resume說(shuō)明用戶關(guān)注命令語(yǔ)法。我們沒(méi)用復(fù)雜的 PEG 解析器而是用三段式正則 語(yǔ)義校驗(yàn)命令前綴匹配^\/([a-z][a-z0-9\-]*)\b—— 匹配/xxx要求首字符字母禁止數(shù)字開(kāi)頭參數(shù)分割(?\s)(?!--)[^\s]—— 按空格分割參數(shù)但跳過(guò)--flag類(lèi)型鍵值對(duì)提取--(\w)(.?)\s(?\-\-|\s*$)—— 提取--date2024-05-20。為什么不用argparse因?yàn)?argparse 會(huì)自動(dòng)處理-h、--help而 Agent 場(chǎng)景下用戶輸入/help應(yīng)該由 skill 自己返回幫助文案不是 CLI 強(qiáng)行攔截。我們的解析器返回原始 tokens 數(shù)組再交給 skill 的validate_input()方法做業(yè)務(wù)校驗(yàn)。例如/jira-search projectPROJ summary~bug解析后得到{ command: jira-search, positional: [], flags: { project: PROJ, summary: bug } }然后jira-searchskill 的 validator 會(huì)檢查project是否在白名單內(nèi)從 DB 查allowed_projectssummary長(zhǎng)度是否 100 字符防 DOS是否存在jira:read:issue權(quán)限查用戶 token 的 scope。實(shí)操心得正則要寫(xiě)單元測(cè)試我們?yōu)槊總€(gè) command 寫(xiě)了 20 個(gè)邊界 case包括/cmd arg with space、/cmd --flagvalue with quote、/cmd --flag空值。曾因沒(méi)覆蓋--flag場(chǎng)景導(dǎo)致模型傳入空字符串skill 把整個(gè)數(shù)據(jù)庫(kù)當(dāng)參數(shù)刪除——那次事故讓我們把所有 flag 校驗(yàn)加了required: true強(qiáng)制非空。3.3 Skill 執(zhí)行沙箱本地 binary 的安全加固實(shí)踐熱詞中permission denied while trying to connect to the docker api提醒我們權(quán)限失控是最大風(fēng)險(xiǎn)。對(duì)于本地 binary skill我們做了四層沙箱文件系統(tǒng)隔離用chrootpivot_root創(chuàng)建最小根目錄只掛載/usr/binskill binary、/tmp臨時(shí)文件、/dev/null禁用設(shè)備訪問(wèn)系統(tǒng)調(diào)用過(guò)濾用seccomp-bpf白名單只允許read/write/open/close/execve等 12 個(gè)必要 syscall禁用socket/bind/connect防網(wǎng)絡(luò)外連資源限制ulimit -v 524288512MB 內(nèi)存、ulimit -t 3030 秒 CPU 時(shí)間、ulimit -f 1048576010MB 文件大小憑證隔離所有敏感環(huán)境變量如GITHUB_TOKEN在exec前清空僅通過(guò)-e參數(shù)注入最小必要變量且變量名強(qiáng)制加前綴SKILL_如SKILL_GITHUB_TOKEN。Rust skill 示例src/main.rsfn main() { // 1. 只讀取 SKILL_* 環(huán)境變量 let token env::var(SKILL_GITHUB_TOKEN).expect(Missing SKILL_GITHUB_TOKEN); // 2. 從 stdin 讀取 JSON 輸入CLI 通過(guò) pipe 傳入 let mut input String::new(); io::stdin().read_to_string(mut input).unwrap(); let params: SearchParams serde_json::from_str(input).unwrap(); // 3. 嚴(yán)格校驗(yàn)參數(shù) if params.repo.len() 100 || !params.repo.chars().all(|c| c.is_alphanumeric() || c -) { eprintln!(Invalid repo format); std::process::exit(1); } // 4. 執(zhí)行 HTTP 請(qǐng)求用 reqwest但禁用 DNS只允許 IP let client reqwest::Client::builder() .resolve(api.github.com, 140.82.112.4) // 硬編碼 IP防 DNS 劫持 .build() .unwrap(); // ... 實(shí)際邏輯 }編譯命令cargo build --release --target x86_64-unknown-linux-musl生成靜態(tài)鏈接 binary無(wú) glibc 依賴直接扔進(jìn) chroot 環(huán)境就能跑。3.4 API Skill 的健壯性設(shè)計(jì)超時(shí)、重試、熔斷三位一體對(duì)于 HTTP 類(lèi) skill如調(diào)用智譜 API、Minimax API我們絕不信任任何第三方服務(wù)。一套完整的健壯性策略包括超時(shí)分級(jí)連接超時(shí) 2s讀超時(shí) 8s總超時(shí) 12s。為什么讀超時(shí)設(shè)為 8s因?yàn)?DeepSeek 的deepseek-chat模型平均響應(yīng) 3.2s留出 2 倍緩沖指數(shù)退避重試失敗后 0.5s、1s、2s 重試最多 3 次。但401 Unauthorized和403 Forbidden永不重試憑證問(wèn)題熔斷器連續(xù) 5 次5xx錯(cuò)誤熔斷 60 秒期間所有請(qǐng)求快速失敗503 Service Unavailable避免雪崩。熔斷器用 Redis 實(shí)現(xiàn)key 為circuit_breaker:skill_idvalue 是 JSON{ state: open, failure_count: 5, last_failure_time: 2024-05-25T10:23:45Z, open_until: 2024-05-25T10:24:45Z }CLI 在調(diào)用前先查 Redis若state open且open_until now直接返回熔斷錯(cuò)誤不發(fā)起任何網(wǎng)絡(luò)請(qǐng)求。實(shí)操心得熔斷閾值必須動(dòng)態(tài)調(diào)整。我們線上有個(gè)/llm-translateskill平時(shí)成功率 99.9%但某天智譜 API 升級(jí)后429 Too Many Requests錯(cuò)誤激增。手動(dòng)調(diào)高熔斷閾值從 5 次到 20 次治標(biāo)不治本最終方案是增加429到熔斷觸發(fā)條件并在重試邏輯里加入Retry-Afterheader 解析——這才是真正解決問(wèn)題。4. 全流程實(shí)操以/github-search為例完成從定義到上線的閉環(huán)4.1 Step 1定義 Skill SchemaOpenAPI 3.0創(chuàng)建github-search.yaml嚴(yán)格遵循 OpenAPI 3.0openapi: 3.0.3 info: title: GitHub Issue Search version: 1.0.0 description: Search issues in a GitHub repository paths: /search: post: summary: Search GitHub issues operationId: searchIssues requestBody: required: true content: application/json: schema: type: object properties: repo: type: string description: Repository name in format owner/repo example: langchain-ai/langchain minLength: 3 maxLength: 100 keyword: type: string description: Keyword to search in issue title and body example: bug maxLength: 200 labels: type: array items: type: string description: Filter by labels example: [bug, help wanted] required: [repo, keyword] responses: 200: description: List of matching issues content: application/json: schema: type: array items: type: object properties: number: type: integer title: type: string url: type: string format: uri 400: description: Invalid input parameters 401: description: Invalid or missing GitHub token 429: description: Rate limit exceeded這個(gè) YAML 不是文檔而是可執(zhí)行契約。CLI 啟動(dòng)時(shí)會(huì)加載并驗(yàn)證所有 schema確保repo字段長(zhǎng)度在 3–100 字符之間keyword不超過(guò) 200 字符——這些校驗(yàn)在模型生成參數(shù)時(shí)就完成不留給 runtime。4.2 Step 2編寫(xiě) Skill 執(zhí)行器Rust reqwestgithub-searchbinary 的核心邏輯#[derive(Deserialize)] struct SearchInput { repo: String, keyword: String, #[serde(default)] labels: VecString, } #[derive(Serialize)] struct Issue { number: i32, title: String, url: String, } #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 1. 從 stdin 讀取輸入 let mut input String::new(); std::io::stdin().read_to_string(mut input)?; let params: SearchInput serde_json::from_str(input)?; // 2. 校驗(yàn) repo 格式必須含 / if !params.repo.contains(/) { eprintln!(repo must be in format owner/repo); std::process::exit(1); } // 3. 構(gòu)建 GitHub API URL let base_url https://api.github.com; let mut url format!({}/repos/{}/issues, base_url, params.repo); let mut query vec![format!(q{}, urlencode::encode(params.keyword))]; if !params.labels.is_empty() { query.push(format!(label{}, params.labels.join(,))); } url.push_str(format!(?{}, query.join())); // 4. 發(fā)起請(qǐng)求帶重試 let client reqwest::Client::new(); let mut attempt 0; loop { let res client .get(url) .header(Authorization, format!(token {}, std::env::var(SKILL_GITHUB_TOKEN)?)) .header(Accept, application/vnd.github.v3json) .send() .await; match res { Ok(resp) { if resp.status().is_success() { let issues: VecIssue resp.json().await?; println!({}, serde_json::to_string(issues)?); break; } else if resp.status() reqwest::StatusCode::UNAUTHORIZED { eprintln!(GitHub token invalid); std::process::exit(1); } else if resp.status() reqwest::StatusCode::TOO_MANY_REQUESTS { // 解析 Retry-After if let Some(retry_after) resp.headers().get(Retry-After) { let secs retry_after.to_str()?.parse::u64()?; tokio::time::sleep(tokio::time::Duration::from_secs(secs)).await; } attempt 1; if attempt 3 { break; } } } Err(e) { attempt 1; if attempt 3 { return Err(e.into()); } tokio::time::sleep(tokio::time::Duration::from_millis(500 * (2u64.pow(attempt-1)))).await; } } } Ok(()) }編譯cargo build --release --target x86_64-unknown-linux-musl生成target/x86_64-unknown-linux-musl/release/github-search。4.3 Step 3注冊(cè)到 Skills DB執(zhí)行 SQL 插入用 CLI 的skill register命令封裝INSERT INTO skills ( id, name, description, command, schema, executor_type, executor_config, permissions, timeout_ms ) VALUES ( github-search-v1, 搜索 GitHub Issues, 在指定倉(cāng)庫(kù)中搜索 issue 標(biāo)題和內(nèi)容, /github-search, {openapi:3.0.3,info:{title:GitHub Issue Search,version:1.0.0},...}, binary, {path:/opt/skills/github-search}, [github:read:issues], 10000 );注意executor_config中的path必須是絕對(duì)路徑且 binary 文件需chmod x。4.4 Step 4CLI 集成與用戶測(cè)試CLI 的main.rs添加命令路由match args.command.as_str() { github-search { // 1. 加載 skill 元數(shù)據(jù) let skill db.get_skill_by_command(/github-search)?; // 2. 解析用戶輸入 let parsed parse_slash_command(args.raw_input)?; // 3. 校驗(yàn)權(quán)限 if !user.has_permission(skill.permissions) { return Err(Insufficient permissions.into()); } // 4. 序列化輸入并 pipe 給 binary let input_json serde_json::to_string(parsed.flags)?; let mut cmd std::process::Command::new(skill.executor_config[path]); cmd.stdin(std::process::Stdio::piped()) .stdout(std::process::Stdio::piped()) .env(SKILL_GITHUB_TOKEN, get_token_from_vault(github)); let mut child cmd.spawn()?; let mut stdin child.stdin.take().unwrap(); stdin.write_all(input_json.as_bytes())?; stdin.close()?; // 5. 讀取輸出并返回 let output child.wait_with_output()?; if output.status.success() { print!({}, String::from_utf8(output.stdout)?); } else { eprintln!(Skill execution failed: {}, String::from_utf8(output.stderr)?); } } _ {} }用戶測(cè)試$ ./agent-cli /github-search repolangchain-ai/langchain keywordmemory labels[bug] [{number:12345,title:Memory leak in ConversationBufferMemory,url:https://github.com/langchain-ai/langchain/issues/12345}]4.5 Step 5上線監(jiān)控與灰度發(fā)布上線不是終點(diǎn)而是觀測(cè)起點(diǎn)。我們?cè)诿總€(gè) skill 執(zhí)行前后埋點(diǎn)執(zhí)行前記錄skill_id,user_id,input_hashSHA256用于審計(jì)追蹤執(zhí)行后記錄status_code,duration_ms,output_size_bytes,error_type如network_timeout,schema_validation_failed。用 Grafana 看板監(jiān)控三大黃金指標(biāo)成功率count(status_code 200) / count(*)閾值 99.5%P95 延遲按 skill 分組github-search應(yīng) 1500ms錯(cuò)誤分布柱狀圖顯示401,429,500占比快速定位問(wèn)題?；叶劝l(fā)布流程新版 skill 注冊(cè)為github-search-v2command仍為/github-search但deprecated trueCLI 配置canary_ratio 0.110% 流量走 v2監(jiān)控 v2 的成功率若連續(xù) 5 分鐘 ≥99.8%則UPDATE skills SET deprecated false WHERE id github-search-v1一周后DELETE FROM skills WHERE id github-search-v1 AND deprecated true。實(shí)操心得永遠(yuǎn)保留舊版至少 7 天。我們?cè)?v2 的 schema 少定義了一個(gè)字段導(dǎo)致老用戶客戶端解析失敗。幸好 v1 還在緊急切回同時(shí)修復(fù) v2 并重新灰度——沒(méi)有這個(gè)緩沖期就是 P0 故障。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄那些文檔里不會(huì)寫(xiě)的坑5.1 “Model keeps hallucinating skill names” —— 模型亂猜命令怎么辦現(xiàn)象用戶說(shuō)“幫我查下這個(gè) PR 的評(píng)論”模型生成/pr-comments pr123但實(shí)際 skill 是/github-pr-comments。根源模型訓(xùn)練數(shù)據(jù)里沒(méi)見(jiàn)過(guò)你的自定義命令只能靠泛化。解決方案不是調(diào)高 temperature而是強(qiáng)化指令微調(diào) 示例注入在 system prompt 中明確“你只能使用以下 slash commands/github-search,/github-pr-comments,/jira-search。其他任何命令都是非法的必須拒絕?！痹?few-shot examples 中給 3 個(gè)正確示例 1 個(gè)錯(cuò)誤示例模型生成了/search-github標(biāo)注為 ? 并說(shuō)明原因CLI 層做兜底收到未知 command返回Unknown command /xxx. Available: /github-search, /jira-search不執(zhí)行任何邏輯。我們實(shí)測(cè)加了這兩條后幻覺(jué)率從 12% 降到 0.3%。5.2 “Permission denied while trying to connect to the docker api” —— Docker 權(quán)限問(wèn)題本質(zhì)是用戶組映射熱詞里這個(gè)錯(cuò)誤高頻出現(xiàn)根本原因不是 Docker daemon 配置而是 CLI 進(jìn)程的 UID/GID 與宿主機(jī)不一致。典型場(chǎng)景CLI 用root用戶安裝但 skill 需要訪問(wèn)/var/run/docker.sock而該 socket 的 owner 是root:docker普通用戶不在docker組里。解決方案不推薦sudo usermod -aG docker $USER安全風(fēng)險(xiǎn)推薦CLI 啟動(dòng)時(shí)用stat -c %g /var/run/docker.sock獲取 socket 的 gid然后setgroups([gid])setgid(gid)再execskill最佳實(shí)踐所有 Docker 類(lèi) skill 改用podman無(wú)守護(hù)進(jìn)程rootlessCLI 直接調(diào)用podman run --rm ...。5.3 “API error: 400 this models maximum context length is 1048576 tokens” —— 大模型上下文溢出的靜默陷阱這個(gè)錯(cuò)誤看似是模型限制實(shí)則是 skill 輸出未做截?cái)唷１热?summarize-pdf返回 2MB 文本CLI 試圖把它塞進(jìn) LLM 的 prompt必然超限。解決鏈路Skill 執(zhí)行器自身做輸出截?cái)鄆f output.len() 500000 { output.truncate(500000); }CLI 層加--max-output-length 500000參數(shù)強(qiáng)制傳遞給 skill最終 fallbackLLM 調(diào)用前用tiktoken計(jì)算 token 數(shù)超限時(shí)返回Output too long. Please use --limit to specify max lines.。我們線上所有 skill 都內(nèi)置了--max-output-lengthflag默認(rèn) 100KB用戶可覆蓋。5.4 “find skills” —— 如何讓用戶發(fā)現(xiàn)可用技能熱詞里find skills暴露了 discoverability 問(wèn)題。我們不做全局搜索而是三級(jí)發(fā)現(xiàn)機(jī)制一級(jí)/help—— CLI 內(nèi)置命令返回所有 active skill 的namecommanddescription按字母排序二級(jí)/help command—— 如/help /github-search返回 OpenAPI schema 中的summaryparameters示例三級(jí)/skills list --tagdevops—— 支持 tag 過(guò)濾tag 存在 skills 表的tags TEXT字段管理員可維護(hù)。注意/help輸出必須人工審核不能自動(dòng)生成。曾有次 schema 更新后/help顯示舊描述導(dǎo)致用戶按錯(cuò)誤參數(shù)調(diào)用——現(xiàn)在所有 help 文本都從 DB 的description字段讀和注冊(cè)保持原子性。5.5 “boos cli”, “trae cli” —— 第三方 CLI 工具的集成陷阱熱詞里出現(xiàn)多個(gè) CLI 名稱(chēng)說(shuō)明用戶想復(fù)用現(xiàn)有工具。但直接exec(boos-cli --do-something)有三大風(fēng)險(xiǎn)輸出格式不兼容boos-cli返回 HTML 表格skill 需要 JSON退出碼語(yǔ)義沖突boos-cli成功返回 1失敗返回 0反直覺(jué)參數(shù)注入漏洞boos-cli --repo $repo若$repo含; rm -rf /直接執(zhí)行。安全集成方案Wrapper script寫(xiě)一個(gè)boos-wrapper.sh接收 JSON stdin調(diào)用boos-cli把 stdout 轉(zhuǎn)為 JSON校驗(yàn) exit codeSchema 對(duì)齊boos-wrapper的輸入 schema 必須和boos-cli的 CLI 參數(shù)一一映射用clapRust crate 解析沙箱執(zhí)行wrapper 必須在 chroot seccomp 環(huán)境中運(yùn)行且boos-cli二進(jìn)制放在只讀掛載點(diǎn)。我們封裝了 12 個(gè)第三方 CLI包括kubectl,awscli,gh全部走 wrapper 模式零安全事故。6. 技能生態(tài)演進(jìn)從單機(jī) CLI 到企業(yè)級(jí) Agent 平臺(tái)6.1 當(dāng)技能數(shù)超過(guò) 100注冊(cè)中心必須升級(jí)SQLite 在 100 個(gè) skill 時(shí)依然穩(wěn)健但當(dāng)技能數(shù)突破 200且需要多團(tuán)隊(duì)協(xié)作前端團(tuán)隊(duì)貢獻(xiàn)/ui-preview后端貢獻(xiàn)/api-test運(yùn)維貢獻(xiàn)/infra-check就必須引入服務(wù)化注冊(cè)中心。我們選型etcd而非 Consul原因etcd 的 watch 機(jī)制更輕量CLI 可監(jiān)聽(tīng)/skills/前綴實(shí)時(shí)更新內(nèi)存緩存etcd 的 lease 機(jī)制天然支持 skill 心