1. 多輪 AI 編程為什么總在第三輪開始崩如果你用 AI 寫過稍微像樣的項目大概率遇到過這個場景第一輪讓它建個 Spring Boot 骨架干凈利落第二輪加個用戶登錄也還行到第三輪讓它補個多租戶隔離它開始把 Controller 的注解寫到 Entity 上把數(shù)據(jù)庫連接池配置塞進 Service 層甚至忘了你前面定好的包名規(guī)范。你不得不把前面聊過的架構(gòu)約定重新貼一遍貼完它又忘了上一輪剛改過的字段名。這不是模型不夠聰明而是無狀態(tài)對話的天然缺陷。每一次新會話AI 對項目的認(rèn)知都從零開始它看不到你上周做的架構(gòu)決策也讀不到你昨天寫的分層規(guī)范。上下文窗口再大也扛不住幾十輪任務(wù)累積的信息量更別說窗口一滿就被截斷。我試過把架構(gòu)規(guī)范寫進系統(tǒng)提示詞效果有限——提示詞是靜態(tài)的項目是動態(tài)演進的。真正的問題在于記憶沒有落地成文件執(zhí)行沒有約束成流程。這套方案要解決的就是這件事。核心思路是把 AI 編程拆成兩個角色一個負(fù)責(zé)“記住并規(guī)劃”一個負(fù)責(zé)“動手并回報”。前者用 Hermes 做記憶中樞后者用 OpenCode 做執(zhí)行終端中間用一套叫 Harness 的工程化約束把兩者串起來。Hermes 是什么你可以把它理解成一個帶長期記憶和技能庫的規(guī)劃智能體它維護項目的架構(gòu)憲法和任務(wù)清單。OpenCode 是什么它是一個能讀寫文件、執(zhí)行命令的編碼終端動手能力強但缺乏長期規(guī)劃。Harness 則是連接兩者的規(guī)則層強制代碼分層、強制先規(guī)劃后執(zhí)行。適合誰適合那些已經(jīng)用 AI 寫過小項目、但一上規(guī)模就失控的開發(fā)者。如果你還在糾結(jié)怎么讓 AI 寫個冒泡排序這篇可能偏重了但如果你想讓 AI 幫你維護一個持續(xù)迭代的后臺系統(tǒng)這套流程值得跟做。整篇文章我會按“問題場景 → 前置準(zhǔn)備 → 可復(fù)制配置 → 驗證請求 → 錯排查 → 工具入口”的順序展開每一步都給能直接復(fù)制的片段。下面先從環(huán)境準(zhǔn)備說起。2. Hermes 記憶中樞與 OpenCode 終端的前置準(zhǔn)備在動手配置之前得先把兩個角色的職責(zé)邊界劃清楚。很多人一上來就急著裝工具結(jié)果配完發(fā)現(xiàn) Hermes 和 OpenCode 各說各話記憶文件寫了沒人讀任務(wù)清單生成了沒人執(zhí)行。根因是沒搞明白它們各自該干什么。Hermes 的定位是記憶與規(guī)劃中樞。它需要具備三樣能力長期記憶存儲、任務(wù)拆解規(guī)劃、架構(gòu)規(guī)范維護。長期記憶不是指模型參數(shù)里的知識而是指它能把你項目的關(guān)鍵決策寫成文件并持續(xù)讀取。任務(wù)拆解是指你給一個模糊需求它能輸出帶優(yōu)先級和依賴關(guān)系的任務(wù)清單。架構(gòu)規(guī)范維護是指它能在生成代碼前檢查分層依賴發(fā)現(xiàn)違規(guī)就攔截。OpenCode 的定位是執(zhí)行終端。它需要能讀寫項目文件、執(zhí)行 shell 命令、調(diào)用模型生成代碼。它不負(fù)責(zé)記住架構(gòu)只負(fù)責(zé)在給定指令下精準(zhǔn)落地。指令里必須帶角色屬性比如“你現(xiàn)在是 java-developer”否則它會用通用風(fēng)格亂寫。兩者之間的橋梁是 Harness 工程化約束。Harness 原本是為 Qwen Code 設(shè)計的一套分層規(guī)范核心是 Layer 0 到 Layer 4 的依賴規(guī)則Layer 0 是純數(shù)據(jù)類型無任何依賴Layer 1 到 2 是工具類和配置Layer 3 是核心業(yè)務(wù)邏輯Layer 4 是控制器和接口。規(guī)則很簡單——高層可以依賴低層低層嚴(yán)禁感知高層。Hermes 在生成代碼前會檢查這個依賴關(guān)系OpenCode 在執(zhí)行時按這個規(guī)則寫文件。前置準(zhǔn)備分三步。第一步確認(rèn)你本地有 Node.js 18 以上和 GitOpenCode 依賴 Node 運行時。第二步準(zhǔn)備一個模型接入點Hermes 和 OpenCode 都需要調(diào)用大模型這里我用 TaoToken 做統(tǒng)一接入后面會給具體配置。第三步建一個空項目目錄比如superboot-admin在里面初始化 Git 倉庫因為 Harness 的 trace 日志和記憶文件都建議納入版本管理。關(guān)于模型接入TaoToken 的 API 地址是https://taotoken.net/api官網(wǎng)是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end。它提供兼容 OpenAI 風(fēng)格的接口Hermes 和 OpenCode 都能直接對接。你需要先去控制臺創(chuàng)建一個 API Key這個 Key 后面會寫進兩個工具的配置文件里。注意Key 只顯示一次創(chuàng)建后立刻復(fù)制保存。環(huán)境就緒后目錄結(jié)構(gòu)建議這樣組織項目根目錄下建harness/放任務(wù)清單和 trace 日志建docs/放架構(gòu)規(guī)范建src/main/java放 Java 代碼。這個結(jié)構(gòu)不是隨便定的Hermes 讀寫記憶文件時依賴固定路徑OpenCode 執(zhí)行任務(wù)時也按這個路徑找文件。路徑一旦定好后面所有配置都圍繞它展開。還有一點容易被忽略Hermes 和 OpenCode 的模型選擇可以不同。Hermes 負(fù)責(zé)規(guī)劃和審查建議用推理能力強的模型OpenCode 負(fù)責(zé)生成代碼可以用響應(yīng)更快的模型。TaoToken 支持在請求里指定 model 參數(shù)所以兩個工具可以各配各的。具體怎么配下一節(jié)給完整片段。3. 可復(fù)制的 Hermes 與 OpenCode 配置片段這一節(jié)是全文最核心的部分所有配置都給完整片段你復(fù)制后改掉 Key 和路徑就能用。配置分三塊Hermes 的記憶層配置、OpenCode 的終端配置、Harness 的分層規(guī)則文件。先看 Hermes 的記憶層配置。Hermes 需要一個配置文件告訴它記憶文件放在哪、用哪個模型、API 地址是什么。在項目根目錄建hermes.config.json內(nèi)容如下{ memory: { tasksFile: harness/tasks.md, architectureFile: docs/ARCHITECTURE.md, traceDir: harness/trace, schemaFile: docs/DATABASE_SCHEMA.md }, model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, modelId: claude-sonnet-4-20250514, temperature: 0.3 }, planner: { enabled: true, maxTasksPerRound: 5, requireArchitectureCheck: true } }這里baseUrl填 TaoToken 的 API 地址apiKey換成你控制臺創(chuàng)建的 KeymodelId按你實際可用的模型填。temperature設(shè) 0.3 是因為規(guī)劃任務(wù)需要穩(wěn)定輸出太高會亂拆任務(wù)。requireArchitectureCheck設(shè)為 true 后Hermes 每次生成代碼前都會讀docs/ARCHITECTURE.md做依賴檢查。再看 OpenCode 的終端配置。OpenCode 的配置文件通常在用戶目錄下的.opencode/config.json如果你用的是項目級配置就放在項目根目錄.opencode/config.json。內(nèi)容如下{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, modelId: claude-sonnet-4-20250514 }, workspace: { root: ./, srcDir: src/main/java, readOnly: [docs/ARCHITECTURE.md] }, execution: { requireRolePrefix: true, logToTrace: true, traceDir: harness/trace } }requireRolePrefix設(shè)為 true 后OpenCode 只接受帶角色前綴的指令比如“你現(xiàn)在是 java-developer”這樣能防止通用指令亂寫代碼。readOnly把架構(gòu)規(guī)范設(shè)為只讀OpenCode 不能改它只有 Hermes 能寫。logToTrace讓每次執(zhí)行都寫日志到harness/traceHermes 后續(xù)讀這些日志做驗證。第三塊是 Harness 的分層規(guī)則文件放在docs/ARCHITECTURE.md。這個文件是 Hermes 和 OpenCode 共同遵守的“法律”內(nèi)容如下# 架構(gòu)規(guī)范 ## 分層規(guī)則 - Layer 0 (Types): 純數(shù)據(jù)對象無任何 import 依賴 - Layer 1-2 (Utils/Config): 工具類與配置可依賴 Layer 0 - Layer 3 (Domain): 核心業(yè)務(wù)邏輯可依賴 Layer 0-2 - Layer 4 (Interfaces): 控制器與接口可依賴 Layer 0-3 ## 禁止事項 - Layer 0 嚴(yán)禁 import Layer 3 或 Layer 4 - Layer 3 嚴(yán)禁 import Layer 4 - 所有實體類必須放在 Layer 0 對應(yīng)包下 - 數(shù)據(jù)庫字段規(guī)范見 docs/DATABASE_SCHEMA.md ## 包結(jié)構(gòu) - com.superboot.types - com.superboot.utils - com.superboot.config - com.superboot.domain - com.superboot.interfaces這個文件寫好后Hermes 在規(guī)劃任務(wù)時會讀它OpenCode 在執(zhí)行時會按它檢查。比如 OpenCode 要寫User.java它會先看這個文件確認(rèn) User 屬于 Layer 0然后檢查有沒有 import Controller 類有就報違規(guī)。三塊配置配完還需要一個任務(wù)清單文件harness/tasks.md作為初始占位。內(nèi)容可以先寫個空模板# 任務(wù)清單 ## 待執(zhí)行 !-- Hermes 會在這里追加任務(wù) -- ## 已完成 !-- OpenCode 完成后由 Hermes 移動到這里 --到這里配置就齊了。你可能會問Hermes 和 OpenCode 怎么知道對方的存在答案是它們不直接通信全靠文件。Hermes 寫tasks.mdOpenCode 讀tasks.mdOpenCode 寫trace/日志Hermes 讀trace/日志。這種文件化通信的好處是解耦任何一方掛了另一方還能繼續(xù)工作而且所有狀態(tài)都可追溯。配置過程中有個坑要注意baseUrl末尾不要加/v1TaoToken 的接口路徑已經(jīng)內(nèi)置了版本處理加了會 404。另外apiKey如果泄露去控制臺吊銷重新生成即可不要硬編碼在會提交到 Git 的文件里建議用環(huán)境變量注入。下一節(jié)我們驗證這套配置能不能跑通。4. 驗證多輪任務(wù)連續(xù)性的完整請求配置寫完不代表能跑得用真實請求驗證。這一節(jié)我給一個完整的多輪任務(wù)場景從 Hermes 規(guī)劃到 OpenCode 執(zhí)行再到 Hermes 驗證每一步都給可復(fù)制的指令和預(yù)期結(jié)果。先啟動 Hermes 的規(guī)劃流程。假設(shè)我們要開發(fā)一個“SuperBoot 后臺管理系統(tǒng)”支持多租戶。你給 Hermes 的輸入是我要一個支持多租戶的 Java 后臺管理系統(tǒng)基于 Spring Boot 3。 請閱讀 docs/ARCHITECTURE.md 和 docs/DATABASE_SCHEMA.md 拆解出第一輪任務(wù)寫入 harness/tasks.md。Hermes 收到后會先讀架構(gòu)規(guī)范和數(shù)據(jù)庫規(guī)范然后啟動 Planner 智能體拆任務(wù)。預(yù)期它會在harness/tasks.md的“待執(zhí)行”下追加類似內(nèi)容## 待執(zhí)行 - [ ] 任務(wù)1: 初始化 Maven 結(jié)構(gòu)創(chuàng)建 pom.xml引入 Spring Boot 3 依賴 - [ ] 任務(wù)2: 設(shè)計 sys_user 表包含 tenant_id 字段寫入 docs/DATABASE_SCHEMA.md - [ ] 任務(wù)3: 在 Layer 0 創(chuàng)建 User 實體類字段與 sys_user 表對應(yīng) - [ ] 任務(wù)4: 在 Layer 3 實現(xiàn)登錄邏輯依賴 Layer 0 的 User如果 Hermes 沒寫tenant_id或者把 User 放到了 Layer 3說明它沒讀架構(gòu)規(guī)范檢查hermes.config.json里的requireArchitectureCheck是否為 true。接下來指揮 OpenCode 執(zhí)行任務(wù)1。你給 OpenCode 的指令必須帶角色前綴你現(xiàn)在是 java-developer。 請閱讀 harness/tasks.md 中的任務(wù)1。 在項目根目錄創(chuàng)建 pom.xml符合 Spring Boot 3 標(biāo)準(zhǔn)。 完成后把執(zhí)行日志寫入 harness/trace/task1.log。OpenCode 執(zhí)行后會生成pom.xml并寫日志。預(yù)期日志內(nèi)容包含它讀了哪些文件、生成了什么、有沒有報錯。你可以用cat harness/trace/task1.log查看。然后讓 Hermes 驗證任務(wù)1。你給 Hermes 的輸入是請閱讀 harness/trace/task1.log 和生成的 pom.xml 檢查是否符合 docs/ARCHITECTURE.md 的規(guī)范。 如果合規(guī)把任務(wù)1移到 harness/tasks.md 的已完成區(qū)。Hermes 會讀日志和 pom.xml檢查依賴版本、包結(jié)構(gòu)。合規(guī)就移動任務(wù)不合規(guī)就生成修正指令寫回tasks.md。關(guān)鍵驗證點在第三輪。假設(shè)任務(wù)1和任務(wù)2都完成了現(xiàn)在執(zhí)行任務(wù)3——創(chuàng)建 User 實體類。你給 OpenCode 的指令是你現(xiàn)在是 java-developer。 請閱讀 harness/tasks.md 中的任務(wù)3 和 docs/DATABASE_SCHEMA.md。 在 src/main/java/com/superboot/types 下創(chuàng)建 User.java 字段與 sys_user 表對應(yīng)嚴(yán)禁 import 任何 Layer 3 或 Layer 4 的類。這里的關(guān)鍵是 OpenCode 能不能記住sys_user表的字段。因為任務(wù)2已經(jīng)把表結(jié)構(gòu)寫進了docs/DATABASE_SCHEMA.mdOpenCode 讀這個文件就能拿到字段不需要你重新貼一遍。這就是記憶文件化的價值——跨輪次的信息不靠對話上下文傳遞靠文件傳遞。執(zhí)行完后讓 Hermes 做架構(gòu)檢查請閱讀 src/main/java/com/superboot/types/User.java 檢查它是否 import 了 Layer 3 或 Layer 4 的類。 如果有違規(guī)生成修正指令寫入 harness/tasks.md。預(yù)期 Hermes 會報告“無違規(guī)”或列出具體違規(guī)行。如果 User.java 里出現(xiàn)了import com.superboot.interfaces.*Hermes 會攔截并生成修正任務(wù)。為了驗證多輪連續(xù)性你可以故意制造一個斷鏈場景清空對話歷史重新啟動 Hermes 和 OpenCode然后直接讓 OpenCode 執(zhí)行任務(wù)4。如果它能通過讀tasks.md和DATABASE_SCHEMA.md正確實現(xiàn)登錄邏輯說明記憶層生效了。如果它問“sys_user 表有哪些字段”說明文件沒讀全檢查hermes.config.json里的schemaFile路徑對不對。整個驗證流程跑通后你會看到harness/trace/下累積了多個日志文件tasks.md里任務(wù)從待執(zhí)行移到已完成docs/下的規(guī)范文件被 Hermes 持續(xù)更新。這套狀態(tài)是跨會話持久的關(guān)掉終端明天再來Hermes 讀一遍文件就能恢復(fù)上下文。驗證時如果遇到請求失敗先看錯誤信息。下一節(jié)我列幾個常見報錯和排查方法。5. 常見報錯排查401、local proxy failed 與 reading choices配置和驗證過程中最容易卡在幾個固定報錯上。這一節(jié)我按真實遇到的錯誤信息逐個拆解每個都給排查路徑。報錯一401 Unauthorized這是最常見的通常出現(xiàn)在 Hermes 或 OpenCode 第一次調(diào)用模型時。錯誤信息類似Error: 401 Unauthorized - invalid api key排查三步。第一檢查hermes.config.json和.opencode/config.json里的apiKey是否填了完整 Key有沒有多余空格。第二確認(rèn) Key 沒有過期或被吊銷去 TaoToken 控制臺的 API Keys 頁面看狀態(tài)。第三確認(rèn)baseUrl填的是https://taotoken.net/api不是首頁地址也不是帶/v1的地址。如果三樣都對還是 401重新生成一個 Key 替換試試。報錯二local proxy failed這個報錯通常出現(xiàn)在 OpenCode 執(zhí)行 shell 命令時信息類似Error: local proxy failed - connection refused根因是 OpenCode 嘗試通過本地代理轉(zhuǎn)發(fā)請求但代理沒啟動或端口不對。排查方法檢查你的環(huán)境變量里有沒有HTTP_PROXY或HTTPS_PROXY指向一個不存在的本地端口。如果有臨時清掉再試unset HTTP_PROXY unset HTTPS_PROXY然后重啟 OpenCode。如果清掉后正常說明是代理配置沖突后續(xù)要么不設(shè)代理要么確保代理服務(wù)真的在跑。另外檢查.opencode/config.json里有沒有誤配proxy字段有就刪掉。報錯三reading choices 相關(guān)錯誤這個報錯出現(xiàn)在模型返回格式不符合預(yù)期時信息類似Error: failed to read choices from response根因通常是modelId填錯了或者 TaoToken 返回的響應(yīng)結(jié)構(gòu)和你用的客戶端解析邏輯不匹配。排查第一確認(rèn)modelId是 TaoToken 支持的模型標(biāo)識不要填成其他平臺的模型名。第二用 curl 直接測一下接口curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的密鑰 \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果 curl 返回正常但工具報錯說明是工具側(cè)的解析問題檢查工具版本是否最新。如果 curl 也報錯說明 Key 或模型 ID 有問題。報錯四OAuth 相關(guān)錯誤如果你在配置過程中看到 OAuth 報錯通常是因為某些工具默認(rèn)走 OAuth 流程但你用的是 API Key 模式。排查檢查配置文件里有沒有authType或oauth字段有就改成apiKey模式。另外確認(rèn)沒有同時啟用兩套認(rèn)證沖突會導(dǎo)致 OAuth 流程被觸發(fā)。報錯五任務(wù)清單讀不到Hermes 或 OpenCode 報“tasks.md not found”或“empty task list”。排查確認(rèn)harness/tasks.md文件存在路徑和配置里的tasksFile一致。如果文件存在但讀不到檢查文件權(quán)限確保當(dāng)前用戶有讀權(quán)限。另外注意路徑是相對項目根目錄還是絕對路徑配置里寫的是相對路徑的話工具的工作目錄必須是項目根目錄。排查完這些基本能覆蓋 90% 的配置問題。如果遇到其他報錯先看錯誤信息里的關(guān)鍵詞再去對應(yīng)工具的文檔里搜。記住一個原則Hermes 的問題多半在記憶文件路徑和模型配置OpenCode 的問題多半在角色前綴和代理設(shè)置。配置跑通后你可能想把這套流程固化下來長期用。下一節(jié)給工具入口和長期使用建議。6. 從單次驗證到長期 AI 編程流的落地入口單次驗證跑通只是開始真正有價值的是把這套流程變成日常開發(fā)習(xí)慣。這一節(jié)說幾個長期使用的關(guān)鍵點和工具入口。第一個關(guān)鍵點是記憶文件的維護節(jié)奏。harness/tasks.md會隨著任務(wù)累積越來越長建議每完成一輪大任務(wù)就歸檔一次把已完成區(qū)的內(nèi)容移到harness/archive/下按日期命名。docs/ARCHITECTURE.md不要頻繁改它是項目的憲法改一次要讓 Hermes 重新讀一遍并檢查現(xiàn)有代碼是否合規(guī)。docs/DATABASE_SCHEMA.md每次加表都要更新OpenCode 生成實體類時依賴它。第二個關(guān)鍵點是角色前綴的規(guī)范。OpenCode 支持多種角色比如java-developer、architect、reviewer。建議固定幾個常用角色寫進docs/ARCHITECTURE.md里讓 Hermes 規(guī)劃任務(wù)時直接指定角色。這樣 OpenCode 執(zhí)行時不用你每次手寫前綴Hermes 會在任務(wù)描述里帶上。第三個關(guān)鍵點是 trace 日志的利用。harness/trace/下的日志不只是記錄Hermes 會讀它們做驗證。建議每次 OpenCode 執(zhí)行后都讓 Hermes 跑一遍驗證形成“執(zhí)行-驗證-修正”的閉環(huán)。時間長了這些日志還能幫你回溯某個決策是什么時候做的、為什么這么做。工具入口方面你需要幾個固定地址。模型對話和調(diào)試用https://taotoken.net/api配合模型對話頁面接入文檔在官網(wǎng)的文檔區(qū)API Key 管理在控制臺。如果你要長期跑編碼任務(wù)和 Agent 流程建議用 Coding Plan它針對多輪任務(wù)做了優(yōu)化比單次調(diào)用更穩(wěn)定。Claude Code 和 Anthropic 相關(guān)的接入配置官網(wǎng)也有對應(yīng)說明。具體操作路徑先去控制臺創(chuàng)建 API Key然后按本文第三節(jié)的配置片段填進 Hermes 和 OpenCode接著按第四節(jié)驗證多輪任務(wù)遇到報錯按第五節(jié)排查。跑通后把配置文件和記憶文件納入 Git 版本管理團隊協(xié)作時每個人拉下來改一下 Key 就能用。這套流程的價值不在于某個工具多強而在于它把 AI 編程從“每次重新解釋需求”變成了“持續(xù)維護一個項目記憶”。Hermes 記住架構(gòu)和任務(wù)OpenCode 執(zhí)行具體編碼Harness 約束質(zhì)量。三者配合多輪任務(wù)不再斷鏈上下文不再丟失。你可以先從一個小項目試起跑順了再往大項目遷移。