humanize (hmz)
humanize（hmz，https://github.com/humanfia/humanize，文件 https://docs.humanfia.ai/humanize/）
能夠在流程中執行編碼代理 CLI（claude、codex、agy……）：這些流程是決定誰工作、誰審查以及何時停止的循環。它是一個來自 PyPI 的 uv 工具（uv tool install hmz，~/.local/bin/hmz）；hmz update 可升級它。單純的 hmz 會為當前目錄開啟 TUI，hmz exec 以無頭模式執行流程，hmz web 則在瀏覽器中提供所有工作區的執行記錄。本文基於 0.2.2 版本撰寫；此 alpha 版本變化頻繁，因此請以 hmz exec --help 為準。
使用者的預設值（請根據你的設定編輯）
| 設定 | 預設值 |
|---|---|
| 流程 | rlar：Claude 實作，Codex 審查 |
| 實作者 | claude/claude-opus-5-5:high |
| 審查者 | codex/gpt-6.1-sol:high（有時為 :ultra） |
| 配額 | budget.duration=1d，無成本或代幣上限 |
除非使用者另有說明，或者工作區已儲存預設值（見下方），否則請使用這些設定。請不要詢問配額相關問題。
hmz exec -f rlar \
-a actor=claude/claude-opus-5-5:high \
-a reviewer=codex/gpt-6.1-sol:high \
-p budget.duration=1d \
--json "$(cat "$TASK")" > "$LOG" 2>&1
工作流程
- 前置檢查
- 在
~/.hmz/settings.yaml的workspaces:下查詢目錄。如果有對應項目，則優先使用其流程、代理、環境和配額，而非上述預設值。 - 檢查你傳入的每個模型和努力等級是否存在於
~/.hmz/models/<cli>.json中。hmz 不會提前驗證規格：錯誤的規格只會在第一次使用該規格的回合中失敗，因此在rlar中，錯誤的審查模型會在實作者完成整個第一回合後才顯現。 - 檢查
git status。hmz 代理執行時會繞過批准。如果儲存庫有你未建立的未提交工作，或者它可能影響即時系統（基礎設施、部署腳本、憑證），請告知使用者並建議在開始前建立 git worktree。
- 在
- 編寫任務檔案（下一節）於暫存區，若任務非簡單或定義模糊，請向使用者展示。
- 在背景啟動 使用
run_in_background並將--json導向暫存區中的日誌。執行時間從數小時到數天不等。回報命令、任務檔案、日誌路徑以及如何觀看：在該目錄中執行hmz會開啟該次執行的 TUI，或使用hmz web。 - 讀取結果（參見結果），然後自行檢查儲存庫差異並執行專案的檢查，再宣告完成。審查者的「完成」是證據，而非證明。
- 停止。停止你啟動的背景任務。絕對不要單純使用
pkill hmz，因為使用者通常有其他執行中的任務。檢查pgrep -af hmz並僅停止你的 PID。 - 恢復。在同一目錄中使用相同的
-f搭配--resume（限制見下方）。
編寫任務
實作者只會看到任務，而在 rlar 中，審查者會根據任務判斷儲存庫狀態，因此模糊的任務會導致無窮的審查循環或過早的「完成」。請包含：
- 目標：以一到兩句話說明結果，而非步驟。
- 優先閱讀：定義工作的檔案、規格或文件（例如 OpenSpec 變更、議題、設計註記），讓代理不需重新發現它們。
- 完成條件：具體的驗收標準，審查者可以檢查：必須通過的命令、必須保持的行為、要達到的數值。
- 範圍外事項：不應觸碰的內容，以及任何需要人類介入的操作（部署、推送、刪除、付費服務、即時系統變更）。
- 慣例：提交策略（提交或保持未提交、訊息風格）、日誌和產出物的放置位置。
將其寫入檔案，並傳遞 "$(cat "$TASK")"，或告訴代理先讀取該檔案。以 - 開頭的任務需放在 -- 之後。
命令格式
hmz exec -f FLOW -a ROLE=SPEC[,...] [-e ROLE=SPEC[,...]] -p KEY=VALUE[,...] [opts] task
-f：流程名稱。內建流程為裸名（rlar）；使用者的自訂流程為@user/NAME（來自~/.hmz/flows/NAME/），專案流程為@local/NAME。也可以是.、/或~開頭的路徑、git+URL#subdir，或NAME:OTHER（同一模組內的其他流程）。裸名會先解析最近的匹配，因此使用者的流程可以覆蓋內建流程。-a：ROLE=CLI[@PROVIDER]/MODEL[:EFFORT]，每個流程定義的代理角色一個。可以重複旗標或以逗號分隔。-e：ROLE=BACKEND[@PROVIDER][/WORKDIR]，用於包含環境角色的流程。PROVIDER是儲存在設定中的執行環境，或對於 ssh 而言，是方括號中的主機：box=ssh@[user@host:22]/abs/path。若未提供提供者，則為本機。-p：流程參數，會根據參數的型別或 JSON 進行解析。除了chat之外，每個流程都需要配額：budget.duration（1d、2h30m、PT1H）、budget.cost（美元）、budget.output_tokens。budget.graceful=true讓最後一個回合完成（或使用budget.graceful.<limit>指定特定限制）。--json：將 NDJSON 事件輸出至 stdout。當你需要讀取結果時使用。--resume：從此流程在此處的最新執行中繼續，前提是該流程可恢復（ralph_loop和continue_loop不行）。恢復rlar時，新的實作者只會收到最後一次審查，而非舊的實作者會話。--backup NAME：將史詩級任務備份到設定中儲存的備份目標（none關閉備份）。--profile-flow/--profile-environment：在執行追蹤中加入取樣。僅在診斷慢速執行時使用。- 在每個內建循環流程中，失敗的回合會終止執行，因此不要依賴循環重試。
選擇流程
| 流程 | 角色 | 使用時機 |
|---|---|---|
rlar | actor、reviewer | 預設。需要獨立檢查的工作。實作者在單一會話中工作，新的審查者每輪根據儲存庫檢查實作者的聲明，當審查者宣告完成時結束。 |
chat | assistant | 單一代理，一次性，無循環且無配額。適用於問題和小型編輯。 |
goal | worker | 單一 /goal <task> 會話，直到模型認為目標達成。適用於具有明確標準且可自我驗證的工作。 |
continue_loop | agent | 傳送任務一次，然後持續發送「繼續」。適用於單一上下文中長時間的耗費。 |
ralph_loop | agent | 每輪使用相同任務的全新會話。進度存在於儲存庫中，而非上下文中。 |
stateful_ralph | agent | 單一會話，每輪重新傳送任務。 |
flame_chase | first_chaser、second_chaser | 兩個代理在全新會話中輪流執行。 |
使用者的流程位於 ~/.hmz/flows/<name>/__init__.py。使用 ls ~/.hmz/flows/ 列出它們，並在使用前閱讀文件字串以了解角色和參數。要獲取任何流程的完整合約：
~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)"。
結果
- 每次執行都是
~/.hmz/epics/<以破折號代替斜線的目前工作目錄>/<時間戳記>/下的一個史詩級任務，epic.jsonl包含摘要事件：began（流程、任務）、opened（每個代理會話）、usage（成本、輸出代幣數、秒數）以及帶有how欄位的ended：當流程自身的停止條件滿足時為done，否則為stopped（可能還有其他值）。 --json日誌包含完整的事件串流，包括錯誤，例如回合失敗時的HarnessUnrecoverable。閱讀其結尾以了解執行結束的原因。- 回報結果、來自
usage的成本和持續時間，以及你自己的差異檢查。
設定說明
- 已儲存的執行環境指定代理 CLI 的執行位置，搭配
harness:（affinity:是舊名稱，仍會讀取）。如果遠端機器上沒有設定 harness 的執行環境，不會回退到在本機執行 CLI，因此當遠端主機沒有 CLI 時，請設定harness: local。 - 僅當
btw設定為代理名稱時（設定 › 一般），對史詩級任務的/btw側面問題才能運作。 hmz web執行頁面位於#/epics/下。