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。
- 在
- 编写任务文件（下一节），将其放在 scratchpad 中，如果任务非平凡或给定得很宽松，则展示给用户。
- 在后台启动，使用
run_in_background并将--json重定向到 scratchpad 中的日志。运行时间从数小时到数天不等。报告命令、任务文件、日志路径以及如何查看：在该目录下运行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 事件。在需要读取结果时使用。--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/下。