我維護(hù)的幾個開源項目這幾年最讓我頭疼的其實(shí)不是寫代碼而是review別人的PR。一個中型項目每個PR平均要改二三十個文件等CI跑完、一行行過diff、再對著PR討論半天基本一個上午就沒了。更要命的是人看代碼會有狀態(tài)波動累了就容易漏掉潛在問題。所以我一直在找能把初篩這件事自動化掉的東西——不是那種只查空行和分號的Lint工具而是真正能讀懂代碼邏輯、看出設(shè)計問題的助手。我從上個月開始系統(tǒng)性折騰Hermes Agent配合DeepSeek的API做了一套自動化GitHub PR審查的流程。說人話就是PR一提交Hermes自動拉取diff、結(jié)合項目規(guī)范和模型能力做一輪代碼評審把踩坑點(diǎn)、潛在bug、安全隱患直接評論到PR下面。用下來的感受是它不能替代人工終審但至少能幫我把80%的機(jī)械性檢查工作干了。這篇文章我不講廣告詞只講我怎么從零部署、怎么接入GitHub、怎么把審查規(guī)則調(diào)到能用以及這一路踩過的坑。1. 為什么我決定把PR審查交給Hermes代碼評審的痛點(diǎn)與自動化思路1.1 代碼評審的真實(shí)痛點(diǎn)先說一個大家心知肚明的問題代碼評審這事做得認(rèn)真還是敷衍差別非常大但它的成本又高得離譜。我統(tǒng)計過自己一個中等規(guī)模的前端倉庫單次PR從打開到合入reviewer平均需要花40分鐘到1小時而且這是在沒有歷史包袱的情況下。如果碰上改動的模塊涉及多個團(tuán)隊、跨服務(wù)調(diào)用這個時間還會翻倍。另一個經(jīng)常被忽略的問題是評審質(zhì)量不穩(wěn)定。同一個人在上午九點(diǎn)和下午四點(diǎn)看同一段代碼給出的意見深度完全不一樣。我見過不少PR在合并之后幾天才被人發(fā)現(xiàn)少處理了一個邊界情況而那個邊界在評審時其實(shí)就擺在眼前只是當(dāng)時沒人注意到。傳統(tǒng)的靜態(tài)檢查工具ESLint、SonarQube、CodeQL能解決的是規(guī)則類問題比如未使用的變量、明顯的反模式、已知漏洞的CVE匹配。但它們對這個函數(shù)的抽象邊界是不是合理這次改動會不會影響另一條鏈路這類語義性問題無能為力。這些問題恰恰才需要人反復(fù)看也恰恰是最耗時的。1.2 Hermes到底是什么角色我在調(diào)研自動化評審方案時一開始關(guān)注的是那種專門做Code Review的SaaS服務(wù)。它們往往很貴而且代碼要經(jīng)過第三方云很多公司過不了合規(guī)那一關(guān)。后來我注意到Hermes Agent這個方向——它是一個Agent形態(tài)的智能體框架而不是一個吃死規(guī)則的靜態(tài)分析器。它的工作方式在設(shè)計上就跟傳統(tǒng)工具有本質(zhì)區(qū)別你可以把Hermes接入GitHub當(dāng)一個PR出現(xiàn)時它會通過GitHub API獲取PR的完整上下文——不光是diff還有提交信息、關(guān)聯(lián)Issue、被改動文件所在模塊的歷史變更——然后把它整理成一個大模型能理解的結(jié)構(gòu)化輸入再調(diào)用模型我接的是DeepSeek逐文件做推理分析最后把審查意見作為PR評論發(fā)回去。整個過程不需要開發(fā)團(tuán)隊把代碼同步給任何第三方平臺數(shù)據(jù)鏈路是你自己的服務(wù)器到模型API可控性更強(qiáng)。我后來在團(tuán)隊內(nèi)部做了一次對比測試同一批PR分別用SonarQube和Hermes跑結(jié)果顯示Sonar對死代碼和配置錯誤的捕獲更穩(wěn)定但Hermes能在改動是否會破壞現(xiàn)有調(diào)用方新加的異常處理是不是吞掉了關(guān)鍵錯誤這類邏輯性問題上給出有用的提示。這兩者其實(shí)不是替代關(guān)系Hermes更適合做人工評審前的語義初篩。在動手部署之前建議你先想清楚一個問題你希望它做全自動拍板還是人機(jī)協(xié)作的初篩我強(qiáng)烈建議后者。后面所有配置思路我都默認(rèn)你和我一樣把Hermes定位在先替我過一遍、再把有價值的發(fā)現(xiàn)標(biāo)出來的角色。2. 自動化PR審查的核心設(shè)計從diff理解到Skill機(jī)制2.1 機(jī)器要理解一個PR難點(diǎn)在哪要讓AI把代碼評審這件事干好首先要理解這件事的輸入邊界。一個PR的diff雖然有幾十上百個文件但很多文件往往只是格式化、挪位置、加注釋真正的邏輯變化可能集中在三四個關(guān)鍵文件里。模型如果平鋪直敘地讀diff很容易被大段的純格式變化帶偏把注意力放在無關(guān)緊要的行上。所以第一步是信息壓縮。我在配置里做了兩件事一是讓Hermes只針對發(fā)生結(jié)構(gòu)性變動的文件做深度分析通過文件變更統(tǒng)計來判斷比如刪除行數(shù)超過文件總行數(shù)30%的或者有新增函數(shù)定義的二是把PR的描述、提交信息和關(guān)聯(lián)Issue拼進(jìn)上下文讓模型先知道這次改動想干嘛再去對照diff看有沒有做對。這個意圖對齊環(huán)節(jié)非常重要沒有它模型經(jīng)常會在評論區(qū)問一些你為什么要改這個的廢話。我舉一個真實(shí)的例子有個PR的描述寫的是修復(fù)訂單超時問題改動涉及訂單服務(wù)和定時任務(wù)兩個模塊。Hermes拿到這個意圖之后會重點(diǎn)檢查兩個模塊的改動是不是都圍繞超時問題展開而不是孤立地給每個文件挑語法毛病。這樣產(chǎn)出的審查意見明顯更接近一個懂業(yè)務(wù)的老同事會說的話。2.2 Hermes的Agent-Skill機(jī)制我理解的Hermes核心設(shè)計是Agent Skill。Agent負(fù)責(zé)調(diào)度、規(guī)劃、跟外部工具交互Skill是具體的一項能力比如代碼審查生成單元測試解析日志每個Skill會定義自己的輸入輸出格式和觸發(fā)條件。PR審查就是這樣一個Skill。這個抽象的好處是你不用每次寫死一個腳本而是在Skill內(nèi)部組織好幾輪觀察-分析-輸出的循環(huán)。比如審查一個PR時Skill會先拉diff然后調(diào)用一次模型判斷哪些文件值得深看再針對重點(diǎn)文件逐文件發(fā)第二次分析請求最后匯總生成統(tǒng)一的review意見。整個過程對使用者是透明的但你可以通過調(diào)Skill的prompt模板來控制它怎么思考、重點(diǎn)查什么。后面講規(guī)則定制時我會給具體的配置。2.3 三種接入方式怎么選Actions、Webhook還是CLIHermes掛在GitHub上有幾種接法適用場景完全不同GitHub Actions方式在倉庫里加一個workflow當(dāng)PR被標(biāo)記為synchronize或opened時觸發(fā)臨時環(huán)境里跑一次Hermes再把結(jié)果通過GitHub API寫回評論。優(yōu)點(diǎn)是事件驅(qū)動、零常駐進(jìn)程適合大多數(shù)托管在GitHub上的公開或內(nèi)部倉庫。Webhook方式自己起一個常駐服務(wù)接收GitHub發(fā)來的Webhook事件再做處理。適合私有化部署、需要對多個倉庫統(tǒng)一管理或者你想在Hermes輸出結(jié)果后接一個通知到IM的場景。純CLI方式把Hermes當(dāng)成手動命令在本地跑一下作為給自己的輔助檢查。適合我這種周末開源項目不想配一堆遠(yuǎn)端權(quán)限的時候。我用的是Actions方式因?yàn)樗挥镁S護(hù)一臺常駐服務(wù)器workflow的觸發(fā)邏輯也清晰出問題還好排查。后面第三章、第四章就是圍繞這個方式展開的。3. Windows部署Hermes Agent安裝步驟與避坑記錄3.1 環(huán)境準(zhǔn)備我平時主力機(jī)是Windows 11所以這次全程在Windows上部署也踩了不少Windows特有的坑。先列一下環(huán)境清單Python 3.10以上版本我實(shí)際用的是3.11Hermes的依賴?yán)镉胁糠諧擴(kuò)展太老的Python版本會編譯報錯。conda作為虛擬環(huán)境管理也可以直接用venv但我習(xí)慣conda用來隔離依賴很方便。Git for Windows需要用到git命令解析diff內(nèi)容。Docker可選如果你不想在當(dāng)前環(huán)境里裝一堆依賴可以直接拉Hermes的鏡像跑。不過我是在conda環(huán)境里直接裝的后面再單獨(dú)說Docker方式。創(chuàng)建環(huán)境的時候有個小技巧直接用國內(nèi)conda鏡像切到清華源速度會快很多。我環(huán)境里那個channels配置是channels: - defaults - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/然后執(zhí)行conda create -n hermes python3.11 -y conda activate hermes3.2 安裝Hermes及依賴Hermes的安裝我建議在干凈的虛擬環(huán)境里做避免和別的項目依賴打架。執(zhí)行安裝pip install hermes-agent如果你網(wǎng)絡(luò)環(huán)境下載慢也可以把pip源切到國內(nèi)鏡像pip install hermes-agent -i https://mirrors.aliyun.com/pypi/simple/裝完之后執(zhí)行一下自檢命令確認(rèn)能跑hermes doctor這個命令會檢查模型API配置、GitHub Token是否有效、核心依賴版本等我建議第一次跑的時候一定認(rèn)真看一下輸出。如果提示缺某個模塊就用pip裝。如果你想用圖形界面管理配置和Skill可以順手裝一個Hermes Studio的桌面端它在Windows上有安裝包界面能直接看到任務(wù)隊列和審查日志。不過我個人在實(shí)際部署時更習(xí)慣先CLI因?yàn)榉奖阍贏ctions里復(fù)現(xiàn)同一條命令。3.3 配置DeepSeek模型Hermes本身不提供模型算力需要你自己配置一個大模型API作為大腦。我用的DeepSeek一是因?yàn)锳PI價格相對實(shí)惠二是它在代碼理解和變更分析這類任務(wù)上的效果我看到不少正面反饋。配置方式是在Hermes的配置目錄一般在用戶目錄下也可以在項目目錄里建配置文件設(shè)置模型相關(guān)參數(shù)大致長這樣model: provider: deepseek api_key: sk-xxxxxxx model_name: deepseek-chat temperature: 0.2 max_tokens: 4096這里有個細(xì)節(jié)temperature我故意調(diào)低到0.2。代碼審查需要的是穩(wěn)定、可復(fù)現(xiàn)的判斷而不是發(fā)散式的創(chuàng)意temperature高了會經(jīng)常給出其實(shí)也可以考慮用xx模式重構(gòu)這類似是而非的建議。API Key建議通過環(huán)境變量注入不要硬編碼在倉庫里。我后面在GitHub Actions里也是通過Secrets傳入的。3.4 Windows上安裝時的特有坑這里分享幾個我在Windows上實(shí)打?qū)嵅冗^的坑你在部署時大概率也會遇到第一個是conda環(huán)境激活后在PowerShell里執(zhí)行hermes命令報無法加載因?yàn)樵诖讼到y(tǒng)上禁止運(yùn)行腳本。這是PowerShell的執(zhí)行策略問題臨時放開當(dāng)前會話的權(quán)限就行Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass第二個是某些依賴庫在Windows上需要Microsoft C Build Tools如果你在安裝階段看到Microsoft Visual C 14.0 or greater is required的紅色報錯去裝一下Build Tools并勾選使用C的桌面開發(fā)工作負(fù)載然后重新裝依賴就能過去。第三個是路徑問題。Hermes默認(rèn)會把審核工作目錄、緩存都放在用戶目錄下如果你的Windows用戶名是中文某些依賴解析路徑時可能會出問題。建議安裝時額外配置一個純英文路徑的臨時目錄和緩存目錄能省很多麻煩。4. 接入GitHub并跑通第一單PR自動審查4.1 準(zhǔn)備一個有權(quán)限的GitHub Token要讓Hermes讀PR、寫評論需要在GitHub上創(chuàng)建一個Personal Access TokenPAT或者更安全地創(chuàng)建一個GitHub App。個人項目我建議直接用Fine-grained PAT權(quán)限只勾你需要的倉庫范圍別圖省事用老的full-token方案。在GitHub設(shè)置里新建PAT時倉庫權(quán)限至少勾這兩項Pull requests: Read and writeHermes要讀取PR信息和提交評論Contents: Read讀取diff和倉庫文件生成后把Token復(fù)制出來先在本地環(huán)境變量里用KEY的名字存好比如$env:GITHUB_TOKENghp_xxxx4.2 初始化項目級配置為了讓Hermes在不同的倉庫里有不同的行為我會在每個項目倉庫里放一個配置文件。以一個Node.js項目為例配置長這樣provider: github token_env: GITHUB_TOKEN review: enabled: true review_depth: full comment_mode: single rules: - id: no-magic-number pattern: banned-number level: warning這里面的review_depth有兩個可選值full表示分析整個PRfast表示只挑關(guān)鍵文件看。我平時用full因?yàn)镻R數(shù)量不多寧可慢一點(diǎn)也不想漏。comment_mode選single意思是把整個review匯總成一條評論避免刷屏。rules那一段是自定義規(guī)則的雛形后面我會講更完整的規(guī)則玩法。有一點(diǎn)要說明在Actions模式下觸發(fā)邏輯主要由workflow的on字段控制這個配置主要負(fù)責(zé)審查行為本身如果你用的是Webhook或常駐服務(wù)模式才會用到auto_trigger_events這類觸發(fā)配置。4.3 在GitHub Actions里跑Hermes接下來就是把Hermes掛到GitHub Actions。在倉庫的.github/workflows目錄下新建一個文件內(nèi)容大概是這樣name: Hermes PR Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install Hermes run: pip install hermes-agent - name: Run Hermes Review env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} run: hermes github-review --repo ${{ github.repository }} --pr ${{ github.event.pull_request.number }}這里有兩個容易出問題的點(diǎn)。第一fetch-depth: 0必須加上否則Actions默認(rèn)拉的是淺克隆Hermes拿不到完整的git歷史分析這個PR是不是重復(fù)了之前已修過的bug時會缺少依據(jù)。第二GITHUB_TOKEN直接用secrets.GITHUB_TOKEN就行GitHub在Actions環(huán)境里會自動生成不用自己費(fèi)勁創(chuàng)建PAT但如果你的Hermes配置里要用的Skill需要以倉庫身份做更多操作那還是需要自己準(zhǔn)備一個有額外權(quán)限的Token放到Secrets里。4.4 第一單自動審查的完整流程復(fù)盤配置完成后我隨便開了一個測試PR故意在里面放了幾個常見問題一個不判空的數(shù)組訪問、一個遺留下來的console.log、一段沒有對應(yīng)單元測試的邏輯分支。然后看著Actions跑起來。實(shí)時的執(zhí)行日志大致是這樣[info] pull request #42 detected [info] fetching diff: 12 files changed, 340 -87 [info] preparing context: issue #41, commit messages [info] analyzing file: src/services/order.js [info] analyzing file: src/utils/validator.js [info] generating review summary [info] posting comment to PR #42大概兩分多鐘后PR下面出現(xiàn)了一條Hermes的評論分成高危問題建議優(yōu)化提問三個板塊。三個故意埋的點(diǎn)它逮到了前兩個沒看到單元測試缺失那條是我沒在配置里要求它檢查測試覆蓋這個后面說。整體上輸出格式比我想象的清楚沒有出現(xiàn)一堆廢話建議。5. 讓Hermes更懂你的項目規(guī)則配置與Prompt調(diào)優(yōu)5.1 通用審查維度怎么落地默認(rèn)情況下Hermes的PR審查Skill會覆蓋幾個通用維度語法與運(yùn)行時錯誤例如可能拋出的空指針、數(shù)組越界、明顯的類型不匹配。邏輯正確性例如條件判斷倒置、返回值順序錯誤、循環(huán)邊界問題。安全風(fēng)險例如把未驗(yàn)證的用戶輸入直接拼進(jìn)SQL、敏感信息硬編碼。性能隱患例如在循環(huán)里發(fā)HTTP請求、大數(shù)組無謂拷貝?？删S護(hù)性例如重復(fù)代碼、過深的嵌套、命名完全無意義的變量。這些維度不需要你寫代碼實(shí)現(xiàn)它們是靠prompt層面的知識表達(dá)出來的。也就是說審查質(zhì)量高度依賴你給模型的上下文是否充分。我發(fā)現(xiàn)一個有效做法先在項目根目錄維護(hù)一個CONTRIBUTING.md或docs/review-guideline.md把團(tuán)隊自己的約定寫清楚然后在Hermes配置里把這份文檔的路徑掛到項目規(guī)范引用字段。這樣每次審查時Hermes會把這份文檔作為背景知識喂給模型效果比你在prompt里零零散散地寫十條規(guī)則好得多。5.2 項目規(guī)范定制實(shí)操我舉個我真正用過的例子。我的一個Python倉庫要求所有對外接口必須做參數(shù)類型校驗(yàn)并且禁止在業(yè)務(wù)代碼里出現(xiàn)裸的except。我把這個要求寫進(jìn)項目規(guī)范文件然后Hermes配置里這樣引用review: guideline_file: docs/review-guideline.md extra_instructions: | 1. 重點(diǎn)檢查是否有裸except如果有必須標(biāo)記為error。 2. 檢查所有標(biāo)記為public的接口是否有類型校驗(yàn)沒有則標(biāo)記為warning。 severity_threshold: warning這樣配置之后新PR再進(jìn)來它給出的意見會更貼合我們倉庫的實(shí)際情況。我強(qiáng)烈建議你花一點(diǎn)時間把項目里最重要、最容易踩的3到5條規(guī)則先寫上不要一上來就列二三十條否則模型注意力分散關(guān)鍵規(guī)則反而不突出。5.3 控制誤報率的幾個參數(shù)AI review最讓人頭疼的就是誤報和廢話建議。我調(diào)過一輪之后經(jīng)驗(yàn)是這幾個參數(shù)影響最大temperature前面說過壓到0.2左右穩(wěn)定優(yōu)先。max_tokens不要給太少否則審查意見寫到一半被截斷也不要給太多我用4096基本夠一個中大型PR的匯總。comment_mode盡可能用single模式一條匯總評論而不是逐文件刷評論。review_depth如果倉庫PR特別頻繁建議用fast模式先跑發(fā)現(xiàn)可疑點(diǎn)再人工跟進(jìn)。另外一個很重要的心得是PR審查的輸出格式最好固定成結(jié)構(gòu)化的markdown塊比如高危/中危/建議三欄這樣你自己寫個小腳本或者人工瀏覽時都能快速定位。我在配置里通過prompt把輸出模板固定下來實(shí)測下來模型的輸出穩(wěn)定性會比自由發(fā)揮高很多。比如我要求每條意見必須包含文件路徑: 行號問題描述建議改法這樣就方便直接跳轉(zhuǎn)定位。6. Hermes實(shí)踐中的常見問題與排查實(shí)錄6.1 高頻問題速查表我整理了一張表覆蓋我遇到以及幫朋友排查過的高頻問題。現(xiàn)象可能原因解決方法Actions運(yùn)行時提示GITHUB_TOKEN權(quán)限不足使用的是自動生成的默認(rèn)Token倉庫操作權(quán)限不足換成自己創(chuàng)建的PAT并放Secrets里傳入拉取PR diff超時或連接失敗網(wǎng)絡(luò)環(huán)境到GitHub API不穩(wěn)定、請求被限流檢查網(wǎng)絡(luò)連通性確認(rèn)請求頭里帶上了Token避開限流模型返回內(nèi)容被截斷max_tokens太小設(shè)大一點(diǎn)至少4096審查意見全是套路化建議prompt太泛、沒有項目上下文接入項目規(guī)范文檔細(xì)化規(guī)則中文亂碼或編碼報錯Windows控制臺默認(rèn)編碼不是UTF-8設(shè)置PowerShell編碼:$OutputEncoding[Console]::OutputEncoding[Text.UTF8Encoding]::new()Actions里每次都重新裝依賴很慢pip安裝未走緩存增加緩存步驟緩存pip依賴或直接用Docker鏡像方式6.2 Windows部署專屬問題Windows上跑Hermes除了前面安裝階段那幾個坑運(yùn)行時也有幾個容易翻車的地方。一個是路徑分隔符。如果你在一個路徑里給Hermes傳了帶有反斜杠的路徑部分解析diff的模塊會對不上。我一般統(tǒng)一用正斜杠或者在Git Bash里運(yùn)行命令來規(guī)避。另一個是防火墻。如果你選擇Webhook方式自建服務(wù)Windows防火墻第一次會彈窗詢問是否允許Python監(jiān)聽端口記得放行。如果是個人測試機(jī)干脆直接用Actions方式不用開端口。還有一點(diǎn)如果你裝了多個Python版本conda激活環(huán)境后hermes可能還是會找到別的Python安裝路徑這時候在環(huán)境里顯式執(zhí)行一下python -m hermes doctor會比直接敲hermes穩(wěn)定得多。6.3 判斷AI review值不值得信最后說一下主觀感受。我用了兩三個星期之后逐漸形成了自己的判斷標(biāo)準(zhǔn)不要把AI review當(dāng)成真理把它當(dāng)成一個快速但有時會過度聯(lián)想的初級同事。它對常識性錯誤的識別率很高但對業(yè)務(wù)語義的理解有上限尤其當(dāng)項目里充滿歷史包袱和非典型寫法時它會給出似是而非的重構(gòu)建議。我的做法是高危級別的意見我一定要親眼看一下對應(yīng)代碼中危的交給提交者自查建議級的基本跳過。這樣既不會被它帶偏也不會放過真正的風(fēng)險點(diǎn)。順便說一個擴(kuò)展方向Hermes的Skill機(jī)制可以讓你把同樣一套流程復(fù)制到別的地方比如用它在合并前自動生成CHANGELOG片段或者對特定類型的改動自動補(bǔ)一個單元測試初稿。我把PR審查跑順之后下一步就是在項目里試這個方向。