1. 為什么我花了三天時間才真正把 WorkBuddy 用起來第一次打開 WorkBuddy 的時候我的反應(yīng)和大多數(shù)人一樣這不就是個套殼的對話窗口嗎界面上一個輸入框左邊一排功能按鈕看起來跟市面上任何一個 AI 助手沒什么本質(zhì)區(qū)別。我隨手丟了幾個問題進去回答質(zhì)量還行但也沒覺得有什么驚艷的地方。直到我在一個技術(shù)群里看到有人提到models.json和Skill這兩個詞我才意識到自己完全用錯了方向——WorkBuddy 真正的價值不在于聊天而在于它是一個AI Agent 工作臺核心玩法是配置模型和掛載技能。這個認知轉(zhuǎn)變很關(guān)鍵。如果你把 WorkBuddy 當(dāng)成一個問答機器人那它確實平平無奇但如果你把它當(dāng)成一個可以自定義模型接入、可以編寫 Skill 腳本、可以編排多步驟任務(wù)流的 Agent 中臺那它的上限就完全不一樣了。我從零開始摸索了三天踩了不少坑也總結(jié)出了一些官方文檔里沒寫的經(jīng)驗。這篇文章就是把這整個過程拆開來講——從安裝部署到模型配置從 Skill 編寫到實際項目落地再到那些讓人抓狂的緩存目錄和權(quán)限問題盡量一次講透。不管你是剛聽說 WorkBuddy 想試試水還是已經(jīng)裝好了但不知道怎么深入用或者你正在對比 WorkBuddy 和 CodeBuddy 的區(qū)別、糾結(jié)選哪個下面的內(nèi)容應(yīng)該都能幫你省下不少時間。我會盡量說人話把每個操作背后的邏輯也講清楚而不是只丟一堆步驟讓你照著做。2. 安裝部署那些安裝教程里不會告訴你的細節(jié)2.1 版本選擇國際版和國內(nèi)版到底差在哪WorkBuddy 目前有國內(nèi)版和國際版兩個分發(fā)渠道很多人第一步就卡在這里不知道該裝哪個。我兩個版本都實際跑過說幾個關(guān)鍵差異。國內(nèi)版的優(yōu)勢在于網(wǎng)絡(luò)連通性和賬號體系的本地化登錄、更新、模型調(diào)用基本不需要額外配置開箱即用的體驗更好。國際版在模型選擇上更靈活部分海外模型供應(yīng)商的接入更順暢但你需要自己處理一些網(wǎng)絡(luò)層面的配置問題。如果你主要用國內(nèi)的大模型國內(nèi)版完全夠用如果你需要頻繁切換不同廠商的模型做對比測試國際版的模型管理界面會更順手一些。注意兩個版本的配置文件格式是兼容的models.json的結(jié)構(gòu)基本一致所以你在一個版本里調(diào)好的配置可以遷移到另一個版本不用重新配一遍。安裝包的大小大概在 200MB 到 400MB 之間取決于版本和平臺。Windows 和 macOS 都有原生客戶端Linux 用戶目前主要通過命令行版本使用功能上會少一些圖形界面的便利但核心的 Agent 能力是完整的。2.2 安裝過程中最容易忽略的三個設(shè)置第一個是安裝路徑。默認會裝在系統(tǒng)盤的用戶目錄下如果你 C 盤空間緊張一定要在安裝時手動改到 D 盤或其他數(shù)據(jù)盤。為什么強調(diào)這個因為 WorkBuddy 運行過程中會產(chǎn)生大量緩存文件包括模型響應(yīng)的臨時數(shù)據(jù)、Skill 執(zhí)行日志、會話歷史等用久了輕松占掉幾個 G。第二個是系統(tǒng)緩存目錄的位置。這是問得最多的一個問題WorkBuddy 的系統(tǒng)緩存目錄能改到 D 盤嗎答案是能但不是在安裝界面改而是要裝完之后手動修改配置文件。具體操作是找到安裝目錄下的config文件夾編輯里面的路徑配置項把緩存路徑指向你想要的盤符。改完之后需要重啟應(yīng)用才能生效。第三個是權(quán)限設(shè)置。Windows 上如果不開管理員權(quán)限某些 Skill 腳本在執(zhí)行時會被系統(tǒng)攔截表現(xiàn)為腳本執(zhí)行失敗但沒有任何錯誤提示。macOS 上則需要在安全性與隱私里給 WorkBuddy 授予文件和網(wǎng)絡(luò)訪問權(quán)限否則 Skill 讀取本地文件時會靜默失敗。# Linux 版本安裝后的目錄結(jié)構(gòu)參考 ~/.workbuddy/ ├── config/ │ ├── models.json # 模型配置文件 │ └── settings.json # 全局設(shè)置 ├── skills/ # Skill 腳本存放目錄 ├── cache/ # 緩存目錄可遷移 └── logs/ # 運行日志2.3 首次啟動后的必做檢查清單裝好之后別急著用先花五分鐘做幾個檢查能避免后面很多莫名其妙的報錯。確認版本號在設(shè)置頁面的關(guān)于里看一下版本確保不是幾個月前的老版本新版本對 Skill 的支持完善很多。測試模型連通性隨便發(fā)一條消息看是否能正常收到回復(fù)。如果一直轉(zhuǎn)圈大概率是模型配置或網(wǎng)絡(luò)問題。檢查 Skill 目錄確認skills文件夾存在且可寫后面寫自定義 Skill 都要放這里?？匆谎廴罩灸夸浿廊罩驹谀某鰡栴}的時候第一時間去看比在網(wǎng)上到處問快得多。3. models.json 配置模型接入的核心邏輯與常見報錯3.1 這個文件到底管什么models.json是 WorkBuddy 的模型注冊表。你可以把它理解成一個模型通訊錄——每一條記錄告訴 WorkBuddy有這么一個大模型可以用它的接口地址是什么用什么密鑰調(diào)用支持哪些能力比如是否支持圖片輸入、是否支持函數(shù)調(diào)用。很多人裝完 WorkBuddy 之后發(fā)現(xiàn)只能用默認的那一兩個模型想換別的卻找不到入口就是因為不知道要改這個文件。圖形界面上雖然有一些模型切換的選項但真正要接入自定義模型或者第三方兼容接口必須手動編輯models.json。一個典型的配置結(jié)構(gòu)長這樣{ models: [ { name: my-model, provider: openai-compatible, base_url: https://api.example.com/v1, api_key: sk-xxxxxxxxxxxx, model_id: gpt-4-turbo, capabilities: [chat, function_call], max_tokens: 4096 } ] }3.2 配置字段的坑點逐個拆provider 字段決定了 WorkBuddy 用哪種協(xié)議去調(diào)用模型。如果你接的是兼容 OpenAI 接口的服務(wù)就填openai-compatible如果是其他協(xié)議需要查對應(yīng)文檔。這個字段填錯了表現(xiàn)是請求發(fā)出去但返回格式解析失敗日志里會看到 JSON 解析錯誤。base_url 字段最容易出錯的地方是結(jié)尾的斜杠和路徑版本號。有些服務(wù)要求 URL 結(jié)尾帶/v1有些不需要有些對結(jié)尾斜杠敏感多一個少一個都會 404。我的經(jīng)驗是先不加斜杠試一次報錯再加別憑感覺猜。api_key 字段建議不要直接寫在models.json里尤其是如果你會把配置文件同步到 Git 或者分享給別人。更好的做法是用環(huán)境變量引用WorkBuddy 支持${ENV_VAR_NAME}這種寫法實際調(diào)用時會從系統(tǒng)環(huán)境變量里讀取。capabilities 字段決定了 WorkBuddy 會不會把某些任務(wù)路由到這個模型。比如你配了一個不支持 function_call 的模型但某個 Skill 需要函數(shù)調(diào)用能力WorkBuddy 就會自動跳過這個模型。這個機制很實用但前提是你配置的時候要如實填寫不要為了看起來更強而虛報能力。3.3 模型切換策略什么時候該用哪個模型實際用下來我的建議是至少配兩個模型一個能力強的作為主力處理復(fù)雜推理和代碼生成一個響應(yīng)快的作為輔助處理簡單的文本改寫、格式轉(zhuǎn)換、信息提取這類任務(wù)。WorkBuddy 支持在對話中手動切換模型也支持根據(jù)任務(wù)類型自動路由。自動路由的規(guī)則可以在設(shè)置里配比如包含代碼的任務(wù)用模型 A純文本任務(wù)用模型 B。這個功能在批量處理任務(wù)的時候特別省心不用每次都手動切。任務(wù)類型推薦模型特征原因代碼生成與調(diào)試強推理、大上下文需要理解復(fù)雜邏輯和長文件文本改寫與翻譯響應(yīng)快、成本低任務(wù)簡單不需要強推理多步驟 Agent 任務(wù)支持 function_callSkill 編排依賴函數(shù)調(diào)用長文檔分析大上下文窗口需要一次性讀入大量內(nèi)容4. Skill 機制WorkBuddy 真正的殺手锏4.1 Skill 是什么為什么它比提示詞更重要如果說models.json決定了 WorkBuddy 能用哪些大腦那 Skill 就決定了它能做哪些動作。一個 Skill 本質(zhì)上是一段可復(fù)用的指令集或者腳本它告訴 WorkBuddy當(dāng)遇到某類任務(wù)時應(yīng)該按照什么步驟、調(diào)用什么工具、遵循什么規(guī)則來處理。舉個例子。你可以寫一個周報生成Skill里面定義了讀取本周的 Git 提交記錄、提取關(guān)鍵變更、按照固定模板組織內(nèi)容、輸出 Markdown 格式。以后你只需要說幫我生成本周周報WorkBuddy 就會自動執(zhí)行這一整套流程而不需要你每次都把步驟重復(fù)一遍。這就是 Skill 和普通提示詞的本質(zhì)區(qū)別提示詞是一次性的Skill 是可持久化、可復(fù)用、可組合的。你寫好的 Skill 可以分享給團隊其他人也可以在不同的項目里反復(fù)調(diào)用。4.2 從零寫一個 Skill完整流程拆解寫 Skill 沒有想象中那么難但有幾個關(guān)鍵點需要注意。我以一個實際場景為例——自動整理會議紀要——把整個流程走一遍。第一步確定 Skill 的觸發(fā)條件。你需要在 Skill 的描述里寫清楚什么情況下應(yīng)該觸發(fā)它。比如當(dāng)用戶提到會議紀要、會議記錄、meeting notes 等關(guān)鍵詞且提供了原始文本或音頻轉(zhuǎn)寫內(nèi)容時觸發(fā)。第二步定義輸入和輸出。輸入是什么格式純文本、文件路徑、還是結(jié)構(gòu)化數(shù)據(jù)輸出是什么格式Markdown、JSON、還是保存到指定文件。這一步想清楚后面寫邏輯會順很多。第三步編寫執(zhí)行邏輯。這部分可以用自然語言描述步驟也可以嵌入腳本代碼。WorkBuddy 支持在 Skill 里調(diào)用外部工具和 API所以你可以讓 Skill 去讀文件、發(fā)請求、寫數(shù)據(jù)庫。# Skill: 會議紀要整理 ## 觸發(fā)條件 用戶提供會議原始記錄并要求整理成紀要 ## 執(zhí)行步驟 1. 提取會議的基本信息時間、參與人、主題 2. 識別討論的主要議題每個議題歸納為一個小節(jié) 3. 提取每個議題下的關(guān)鍵結(jié)論和待辦事項 4. 待辦事項需要標注負責(zé)人和截止時間如果原文有提到 5. 按照標準模板輸出包含會議概要、議題討論、決議事項、待辦清單 ## 輸出格式 Markdown 格式使用二級標題分隔各部分第四步測試和迭代。寫完 Skill 之后一定要用真實數(shù)據(jù)測試特別要注意邊界情況輸入為空怎么辦格式不符合預(yù)期怎么辦信息缺失怎么處理這些在測試階段發(fā)現(xiàn)比在實際使用中翻車好得多。4.3 Skill 組合把單個能力串成工作流單個 Skill 解決單個問題但真正強大的是把多個 Skill 組合起來形成工作流。比如你可以把信息提取Skill、數(shù)據(jù)分析Skill、報告生成Skill 串在一起實現(xiàn)從原始數(shù)據(jù)到最終報告的自動化。WorkBuddy 支持在 Skill 里引用其他 Skill也支持定義 Skill 之間的依賴關(guān)系和執(zhí)行順序。這個機制在官方文檔里叫Skill 編排實際用起來就像搭積木——每個 Skill 是一個功能塊你決定它們怎么連接。提示Skill 編排的時候盡量讓每個 Skill 的職責(zé)單一。一個 Skill 只做一件事組合起來才靈活。如果一個 Skill 里塞了太多邏輯后面想復(fù)用其中一部分就很麻煩。4.4 社區(qū)里那些有意思的 Skill 案例在社區(qū)里逛了一圈發(fā)現(xiàn)大家寫的 Skill 五花八門有些思路很值得借鑒。有人寫了一個數(shù)學(xué)建模Skill輸入是題目描述輸出是完整的建模思路、代碼實現(xiàn)和結(jié)果分析。這個 Skill 內(nèi)部其實調(diào)用了多個子 Skill一個負責(zé)理解題意一個負責(zé)選擇模型一個負責(zé)寫代碼一個負責(zé)驗證結(jié)果。還有人做了Book to Skill的嘗試——把一本書的核心方法論提取出來寫成一個 Skill這樣以后遇到相關(guān)問題就可以直接調(diào)用這本書的思維框架來分析。這個思路挺有意思的相當(dāng)于把知識庫變成了可執(zhí)行的工具。另外看到有做 Unity 開發(fā)的同行寫了一個技能攻擊指示器相關(guān)的 Skill用來輔助生成游戲里的技能范圍顯示邏輯。這類垂直領(lǐng)域的 Skill 雖然通用性不強但在特定場景下效率提升非常明顯。5. 實戰(zhàn)避坑我踩過的那些坑和解決方案5.1 緩存目錄遷移后 Skill 找不到文件前面提到可以把緩存目錄改到 D 盤但改完之后我遇到了一個問題某些 Skill 在執(zhí)行時找不到之前緩存的中間文件。排查了半天才發(fā)現(xiàn)Skill 腳本里如果用了相對路徑它是相對于緩存目錄來解析的。你把緩存目錄改了相對路徑的基準就變了。解決方案很簡單在 Skill 腳本里統(tǒng)一使用絕對路徑或者用 WorkBuddy 提供的路徑變量來引用緩存目錄。不要硬編碼相對路徑這是血的教訓(xùn)。5.2 模型響應(yīng)超時導(dǎo)致的 Agent 任務(wù)中斷跑多步驟 Agent 任務(wù)的時候如果中間某一步的模型響應(yīng)特別慢整個任務(wù)鏈可能會超時中斷。默認的超時時間對于簡單對話夠用但對于需要長時間推理的復(fù)雜任務(wù)就不夠了。你可以在settings.json里調(diào)整超時參數(shù)把默認的 30 秒改成 120 秒甚至更長。但要注意超時時間設(shè)太長也有風(fēng)險——如果模型真的掛了你會等很久才收到錯誤提示。我的建議是根據(jù)任務(wù)復(fù)雜度動態(tài)調(diào)整簡單任務(wù)保持默認復(fù)雜任務(wù)手動調(diào)大。5.3 Skill 權(quán)限問題導(dǎo)致的靜默失敗這個坑最隱蔽。Skill 腳本需要讀取本地文件或者調(diào)用系統(tǒng)命令時如果 WorkBuddy 沒有對應(yīng)的權(quán)限腳本會直接失敗但界面上可能只顯示執(zhí)行完成而沒有任何輸出。你以為是 Skill 邏輯寫錯了其實是權(quán)限被攔截了。排查方法去看日志文件搜索 permission 或 denied 關(guān)鍵詞。如果確認是權(quán)限問題Windows 上以管理員身份運行 WorkBuddymacOS 上在系統(tǒng)設(shè)置里授予完全磁盤訪問權(quán)限。5.4 多個 Skill 之間的命名沖突當(dāng)你裝了很多 Skill 之后可能會遇到命名沖突的問題。兩個 Skill 用了相同的觸發(fā)關(guān)鍵詞WorkBuddy 不知道該調(diào)哪個結(jié)果就是隨機選一個執(zhí)行行為不可預(yù)測。解決辦法是給 Skill 起名的時候加前綴或命名空間比如weekly-report和meeting-report而不是都叫report。觸發(fā)條件也要盡量具體避免模糊匹配。6. WorkBuddy 和 CodeBuddy 到底怎么選這是被問得最多的問題之一。兩個產(chǎn)品名字很像功能也有重疊但定位其實不一樣。WorkBuddy 的定位是通用 AI 工作臺核心是 Agent 能力和 Skill 機制適合需要編排多步驟任務(wù)、需要接入多種模型、需要自定義工作流的場景。它的強項在于靈活性和可擴展性。CodeBuddy 更偏向編程輔助在代碼補全、代碼審查、Bug 定位這些場景下體驗更專注。如果你主要就是寫代碼CodeBuddy 的開箱體驗可能更好但如果你需要把 AI 能力嵌入到更廣泛的工作流程里WorkBuddy 的上限更高。實際使用中很多人是兩個都用——日常寫代碼用 CodeBuddy做項目規(guī)劃、文檔整理、數(shù)據(jù)分析這些用 WorkBuddy。兩者不沖突各取所長。7. 一些讓 WorkBuddy 更好用的個人經(jīng)驗用了一段時間之后我總結(jié)了幾條讓 WorkBuddy 效率翻倍的習(xí)慣分享出來供參考。給 WorkBuddy 定幾條全局規(guī)則。在設(shè)置里可以配置全局的系統(tǒng)提示詞這些規(guī)則對所有任務(wù)都生效。比如我會設(shè)定輸出代碼時始終包含注釋、回答技術(shù)問題時先給結(jié)論再給解釋、不確定的信息要明確標注不確定。這樣就不用每次對話都重復(fù)交代了。定期清理緩存和日志。前面說了緩存目錄會越來越大建議每個月清理一次。日志文件如果不需要排查問題也可以定期刪能省不少空間。把常用的 Skill 做成模板。如果你發(fā)現(xiàn)自己反復(fù)在寫類似的 Skill說明這個場景值得抽象成一個通用模板?；〞r間把模板打磨好后面每次用都是賺的。關(guān)注版本更新。WorkBuddy 的迭代速度挺快的新版本經(jīng)常會加一些實用的功能比如新的 Skill 觸發(fā)方式、更細粒度的權(quán)限控制、更好的模型路由策略。保持更新能讓你一直用到最新的能力。不要把所有任務(wù)都丟給最強的模型。成本是一方面另一方面是強模型在簡單任務(wù)上不一定比快模型好。根據(jù)任務(wù)難度選擇合適的模型既省錢又省時間。最后說一個我自己的體會WorkBuddy 這類工具的價值很大程度上取決于你投入多少時間去配置和調(diào)優(yōu)。開箱即用的體驗只是起點真正讓它變成你工作流一部分的是那些你根據(jù)自己需求定制的 Skill 和規(guī)則。前期花時間搭好架子后面每天都能省出時間來。