Harmonist：用 IDE hook 把 agent 協議變成硬性閘門
Portable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.
秒懂
- 它是什麼？
- Harmonist 是一套以 Python 標準庫與 bash 寫成的多 agent 編排框架，主張把「先跑 QA、先做安全審查」這類規則從提示詞移進 hook，讓沒通過檢查的回合無法結束。本文拆解它的 hook 機制、記憶體寫入路徑與供應鏈雜湊，並指出它不適合誰。
- 適合誰用？
- 如果你的團隊已經在用 Cursor 或 Claude Code，而且真的吃過「模型口頭答應跑 QA、結果沒跑就交件」的虧，Harmonist 值得先在一個非關鍵 repo 上試裝，重點驗證三件事：stop hook 在你們的 hook 執行環境裡是否真的會擋下回合、loop_limit 耗盡後的 incident 記錄長什麼樣、以及 memory.py append 的 schema 是否容得下你們既有的決策記錄格式。反過來說，如果你的 agent 流程本來就不經過 IDE、或你無法接受每次改動都要多一輪 hook 往返，這套框架的閘門只會變成噪音。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 98 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它想解決的是提示詞管不住模型這件事
README 把問題講得很直白：每個認真的工程流程都有不可協商的規則，例如金額不能用浮點數、合併前要跑 QA、碰認證程式碼前要有安全審查。模型可以被「告知」這些規則，但沒有任何機制強迫它遵守。它可以點頭、往下走，然後默默跳過那一步。順利的話你會發現，不順利的話 bug 就上線了。
Harmonist 的目標讀者是已經在用 Cursor、Claude Code、Copilot、Windsurf、Aider 這類 AI 編碼助理的人，而且在意的是「規則有沒有被執行」而不是「能不能串起更多 agent」。README 對現況的描述分成兩類：LangChain、CrewAI、AutoGen、MetaGPT 這類框架提供編排原語，但把執行責任留給提示詞，模型永遠可以覆寫自己的協議；另一邊是企業級平台，用獨立執行期、資料庫與廠商綁定換取治理能力，代價是得先有基礎設施，裝不進單人開發者的筆電，也沒辦法逐檔稽核。Harmonist 選的是第三條路：把協議執行做成 IDE 層級的 hook，用 shell 與 Python 腳本觀察每一次 subagent 派送、每一次檔案編輯、每一次 session 結束。
stop hook 如何讓未完成的回合結束不了
機制寫在 README 的 .cursor/hooks/ 說明裡。stop hook 會從 session 中解析 subagent 派送標記，檢查 qa-verifier 是否跑過、是否有必要的 reviewer 缺席、session-handoff.md 是否更新過。只要有一項沒滿足，hook 就回傳一個結構化的 followup_message 給 AI，並拒絕讓這個回合完成。重試次數由 loop_limit 控制，README 給的值是 3。用完之後會記錄一筆 incident，並在下一個 session 浮出來。
這裡的關鍵差異是執行位置。多數框架的「你必須先跑 QA」是一行提示詞，模型的輸出通道和規則的檢查通道是同一個，所以規則可以被說服掉。Harmonist 把檢查放在 hook，也就是 IDE 呼叫的外部程序，模型的文字輸出必須先穿過這道程序才能結束回合。README 的措辭是「模型無法跟它爭論；它是磁碟上的狀態機」。這個說法在 hook 確實被觸發的前提下成立，而 hook 是否被觸發取決於你的 IDE 與版本，這一點文件沒有替你保證。
correlation_id 由 hook 產生，模型只讀不寫
記憶體系統有兩個設計值得分開看。第一是識別碼的產生位置。每一筆記憶體條目帶一個 correlation_id，格式是 <session_id>-<task_seq>，由 hook 在 session 開始時產生，session_id 本身是 <unix-seconds><pid4>，README 說這是為了在平行 session 之間避免碰撞。模型透過 CLI 讀取當前有效的 ID，但從不自己寫入 ID。
第二是寫入路徑。memory.py append 是唯一支援的寫入方式，它會用 YAML schema（memory/SCHEMA.md）驗證每一筆條目、拒絕重複，並掃描內文中的機密樣式，README 列出的類別約 30 種，涵蓋 AWS access key、GitHub PAT、Stripe token、Slack webhook、GCP service account、Azure connection string、Telegram bot token、Discord token、Heroku 與 Postmark 的 UUID（有上下文範圍限制）、加上 secret: 前綴的高熵字串，以及內嵌帳密的資料庫連線字串。樣板用的佔位符寫法 ${VAR} 與 <NAME> 會讓掃描跳過，所以範本還是能正常寫入。
把這兩個設計放一起看，得到的效果是：同一項任務產生的 state、decision、pattern 三類條目之間的關聯，從 hook 的角度是有序的，而不是交給模型自行宣稱。這個保證的邊界也很清楚，它管的是 ID 的來源，不是內容的正確性。模型仍然可以寫進一筆語意上胡說八道但格式合法的 decision。
MANIFEST.sha256 擋得住什麼，擋不住什麼
隨包出貨的執行期內容，包含 agents/、hooks/、memory/、playbooks/ 與根目錄文件，都會被雜湊進 MANIFEST.sha256。CI 設定與 repo metadata 屬於 pack repo 專用，被排除在外。upgrade.py 在把每個來源複製進專案之前會先做 sha 驗證。README 舉的例子是被竄改的 security-reviewer.md，比如一份對所有東西都回 approve 的版本，會被拒絕，永遠進不了專案。install_extras.py 對按需安裝的專科 agent 沿用同一道防線。
這道防線的範圍要講清楚。它驗的是「從 pack 到專案」這一段的完整性，也就是來源檔在傳遞過程中沒被動過。它不驗專案裡已經存在的檔案是否被本地修改過，也不驗你 fork 之後自己改的 agent 定義。如果你的團隊會在安裝後調整 reviewer 的行為，那些調整落在雜湊涵蓋範圍之外，升級時的衝突得靠你自己處理。README 稱這是 OSS agent 目錄裡偏執等級的供應鏈姿態，這個自我評價是否成立，取決於你有沒有真的走 upgrade.py 這條路徑而不是手動複製檔案。
安裝與升級的實際操作面
README 對安裝流程給的指示相當特殊：如果你是 AI agent 被要求安裝或整合這個 pack，去讀 integration-prompt.md 並執行其中的步驟。同時它明確警告，不要把 AGENTS.template.md 當成 pack 資料夾裡的有效規則套用，那份檔案是在整合過程中變成使用者專案 AGENTS.md 的範本。這個警告本身就是一個常見的誤用模式，值得照做。
環境需求在 README 的徽章與 Requirements 段落中標示為 Python 3.9+，依賴欄位寫的是 stdlib only，也就是執行期不需要安裝任何第三方套件。這對想在公司內部網路或受限環境部署的人來說是實質優點，不需要處理套件來源與授權審查。
升級走 upgrade.py，它會在複製前逐檔做 sha 驗證。on-demand 的專科 agent 走 install_extras.py，同一道驗證。這兩個腳本加上 memory.py append，構成你日常會碰到的三個入口。其餘的 hook 與 agent 定義是資料，不是程式。
版本節奏方面，可查的發布紀錄顯示 v1.1.0 在 2026-06-08、v1.2.0 與 v1.2.3 都在 2026-06-09，後兩者相隔約一小時。這種同日連發的模式意味著升級前最好先看 CHANGELOG.md 而不是只看版本號跳動。
193 個專科 agent 是資產也是維護面積
README 的徽章與目錄章節對 agent 數量給出不一致的數字：徽章寫 193，描述欄位寫 186，標題區塊則寫 193，而目錄索引指向 agents/index.json。這種不一致本身不影響功能，但反映文件在快速迭代中沒有同步，採用前應該以 agents/index.json 的實際內容為準，而不是任何一個寫在文字裡的數字。
設計取向上，Harmonist 拒絕「一個通用 coder 打天下」，改成 16 個類別下的策劃專科。這個選擇的實際後果是：你能拿到針對特定領域寫好的審查視角，代價是你要維護的 agent 定義變多，而且每一個都是需要被雜湊驗證的檔案。當你只想改一個 reviewer 的判斷標準，你要動的是 catalogue 裡的一份定義，並且要考慮它與 MANIFEST 的關係。專科化在品質上通常划算，在維護上不划算，這是一個明確的取捨而不是免費的升級。
什麼情況下它會變成阻礙
最明顯的失敗模式是 hook 沒有被觸發。整套強制力建立在 IDE 會在對應時機呼叫 .cursor/hooks/ 下的腳本，如果你的助理版本、設定或執行環境不支援這個 hook 點，你得到的是一堆躺在磁碟上的 markdown 與 Python，以及一個以為自己有閘門的錯覺。這種情況下它比純提示詞方案更糟，因為你會誤以為檢查已經發生。
第二個邊界是回合的形狀。loop_limit 設為 3，意思是 hook 最多再要求三次補做。如果你的工作流程本來就會產生大量小改動，每個改動都要走一輪 hook 往返，累積的延遲會讓人開始找繞道，而繞道正是這套設計想消滅的東西。
第三個是記憶體 schema 的剛性。memory.py append 是唯一寫入路徑，好處是格式一致與機密掃描，代價是你既有的決策記錄格式必須先被改寫成符合 memory/SCHEMA.md 的形狀，否則就得放棄把那些記錄納入。這對已經有一套內部 ADR 流程的團隊是實實在在的遷移成本。
與 LangChain 類框架的差異在哪裡
把 Harmonist 和 LangChain、CrewAI、AutoGen、MetaGPT 放在一起比，差別不在功能清單而在控制點的位置。那些框架給你的是編排原語：定義 agent、定義工具、定義誰呼叫誰。協議執行留給提示詞，模型可以在推理過程中覆寫自己的計畫。Harmonist 不提供一般意義上的編排 API，它提供的是一組 hook 與一份 agent 目錄，控制點在 IDE 與檔案系統之間。
這個差異決定了適用場景。你要寫一個會呼叫外部 API、需要動態決定下一步的服務，LangChain 那類框架是對的工具，Harmonist 幫不上忙。你要的是「在這個 repo 裡，任何改動都不能跳過 qa-verifier」，那 Harmonist 的 hook 才是對的位置，而 LangChain 在這件事上沒有對應機制。兩者不是替代關係，重疊的部分比行銷語言暗示的少。
企業級治理平台是另一個對照組。它們用獨立執行期與資料庫換取集中控管，代價是安裝門檻與逐檔稽核的困難。Harmonist 的立場是不要執行期、不要資料庫、不要廠商綁定，只有 markdown、標準庫 Python 與 bash。這個立場讓它能在單人筆電上跑，也讓它的稽核單位是單一檔案。
編輯結論
如果你的團隊已經在用 Cursor 或 Claude Code，而且真的吃過「模型口頭答應跑 QA、結果沒跑就交件」的虧，Harmonist 值得先在一個非關鍵 repo 上試裝，重點驗證三件事：stop hook 在你們的 hook 執行環境裡是否真的會擋下回合、loop_limit 耗盡後的 incident 記錄長什麼樣、以及 memory.py append 的 schema 是否容得下你們既有的決策記錄格式。反過來說，如果你的 agent 流程本來就不經過 IDE、或你無法接受每次改動都要多一輪 hook 往返，這套框架的閘門只會變成噪音。它的 MIT 授權讓商用沒有額外負擔，但 MANIFEST.sha256 只涵蓋隨包出貨的內容，你自己 fork 後改過的 agent 定義不在驗證範圍內，這點要在第一次升級前確認清楚。
社群筆記