xuyanwen2012/humanize

humanize (hmz)

humanize (hmz, https://github.com/humanfia/humanize, docs https://docs.humanfia.ai/humanize/) executa CLIs de agentes de codificação (claude, codex, agy, …) dentro de fluxos: loops que decidem quem trabalha, quem revisa e quando a execução para. É uma ferramenta uv do PyPI (uv tool install hmz, ~/.local/bin/hmz); hmz update a atualiza. hmz puro abre uma TUI para o diretório atual, hmz exec executa um fluxo sem interface, hmz web serve todas as execuções do espaço de trabalho em um navegador. Escrito para a versão 0.2.2; este alpha muda frequentemente, então confie em hmz exec --help em vez de este arquivo.

Padrões do usuário (edite para sua configuração)

Configuração	Padrão
Fluxo	rlar: Claude implementa, Codex revisa
Ator	claude/claude-opus-5-5:high
Revisor	codex/gpt-6.1-sol:high (às vezes :ultra)
Orçamento	budget.duration=1d, sem limite de custo ou tokens

Use estes a menos que o usuário diga o contrário, ou o espaço de trabalho tenha padrões salvos (abaixo). Não pergunte sobre o orçamento.

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

Fluxo de trabalho

1. Pré-voo.
   • Consulte o diretório em ~/.hmz/settings.yaml em workspaces:. Se tiver uma entrada, prefira seu fluxo, agentes, ambientes e orçamento aos padrões acima.
   • Verifique se cada modelo e esforço que você passar existe em ~/.hmz/models/<cli>.json. O hmz não valida especificações de antemão: uma falha só aparece na primeira etapa que a usa, então um modelo de revisor errado em rlar surge após toda a primeira etapa do ator.
   • Verifique git status. Os agentes do hmz executam com aprovações ignoradas. Se o repositório tiver trabalho não commitado que você não criou, ou puder alterar sistemas ativos (infraestrutura, scripts de deploy, credenciais), avise e sugira uma git worktree antes de começar.
2. Escreva o arquivo de tarefa (próxima seção) no scratchpad e mostre ao usuário se a tarefa for não trivial ou foi dada de forma vaga.
3. Inicie em segundo plano com run_in_background e --json redirecionado para um log no scratchpad. As execuções duram horas a dias. Informe o comando, o arquivo de tarefa, o caminho do log e como monitorar: hmz nesse diretório abre a TUI na execução, ou hmz web.
4. Leia o resultado (consulte Resultados), depois verifique o diff do repositório e execute as verificações do projeto você mesmo antes de considerar concluído. A conclusão do revisor é evidência, não prova.
5. Parando. Pare a tarefa em segundo plano que você iniciou. Nunca use pkill hmz puro, pois o usuário geralmente tem outras execuções em andamento. Inspecione pgrep -af hmz e pare apenas o seu PID.
6. Retomando. --resume com o mesmo -f no mesmo diretório (limitações abaixo).

Escrevendo a tarefa

O ator vê apenas a tarefa, e em rlar o revisor julga o repositório contra ela, então tarefas vagas resultam em rodadas de revisão intermináveis ou uma conclusão prematura. Inclua:

• Objetivo: o resultado em uma ou duas frases, não os passos.
• Leia primeiro: os arquivos, especificações ou documentos que definem o trabalho (por exemplo, uma alteração no OpenSpec, um issue, uma nota de design), para que o agente não os redescubra.
• Concluído quando: critérios de aceitação concretos que o revisor possa verificar: comandos que devem passar, comportamento que deve ser mantido, números a atingir.
• Fora do escopo: o que não tocar e qualquer ação que precise de um humano (deploys, pushes, exclusões, serviços pagos, alterações em sistemas ativos).
• Convenções: política de commit (commitar ou deixar não commitado, estilo de mensagem), onde colocar logs e artefatos.

Escreva em um arquivo e passe "$(cat "$TASK")", ou diga ao agente para ler o arquivo primeiro. Uma tarefa começando com - vai depois de --.

Forma do comando

hmz exec -f FLUXO -a PAPEL=ESPEC[,...] [-e PAPEL=ESPEC[,...]] -p CHAVE=VALOR[,...] [opções] tarefa

• -f: um nome de fluxo. Os embutidos são puros (rlar); os do usuário são @usuario/NOME (de ~/.hmz/flows/NOME/) e do projeto @local/NOME. Também um caminho começando com ., / ou ~, git+URL#subdir, ou NOME:OUTRO para outro fluxo no mesmo módulo. Um nome puro resolve o mais próximo primeiro, então um fluxo do usuário pode sombrear um embutido.
• -a: PAPEL=CLI[@FORNECEDOR]/MODELO[:ESFORÇO], um por papel de agente que o fluxo define. Repita a flag ou separe por vírgulas.
• -e: PAPEL=BACKEND[@FORNECEDOR][/DIRETORIO] para fluxos com papéis de ambiente. FORNECEDOR é um runtime salvo nas configurações ou, apenas para ssh, um host entre colchetes: box=ssh@[usuario@host:22]/caminho/abs. Sem um fornecedor, é esta máquina.
• -p: parâmetros do fluxo, interpretados como o tipo do parâmetro ou como JSON. Todo fluxo exceto chat precisa de um orçamento: budget.duration (1d, 2h30m, PT1H), budget.cost (USD), budget.output_tokens. budget.graceful=true permite que a última etapa termine (ou budget.graceful.<limite> para um limite).
• --json: eventos NDJSON para a saída padrão. Use quando precisar ler o resultado.
• --resume: retoma a execução mais recente deste fluxo aqui, se o fluxo puder ser retomado (ralph_loop e continue_loop não podem). Retomar rlar entrega ao ator apenas a última revisão, não a sessão antiga do ator.
• --backup NOME: faz backup do épico em um destino de backup salvo nas configurações (none desativa).
• --profile-flow / --profile-environment: adiciona amostragem ao trace da execução. Use apenas ao diagnosticar uma execução lenta.
• Uma etapa com falha encerra a execução em todo fluxo de loop embutido, então não conte com o loop para tentar novamente.

Escolhendo um fluxo

Fluxo	Papéis	Use quando
rlar	ator, revisor	Padrão. Trabalho que precisa de uma verificação separada. O ator trabalha em uma sessão, um revisor novo verifica o repositório contra as alegações do ator a cada rodada, e termina quando o revisor disser concluído.
chat	assistente	Um agente, uma execução, sem loop e sem orçamento. Perguntas e pequenas edições.
goal	trabalhador	Uma sessão /goal <tarefa> que executa até o modelo dizer que o objetivo foi atingido. Trabalho com auto-verificação e critérios claros.
continue_loop	agente	Envia a tarefa uma vez, depois continua enviando "continue”. Longas execuções em um contexto.
ralph_loop	agente	Sessão nova a cada rodada com a mesma tarefa. O progresso vive no repositório, não no contexto.
stateful_ralph	agente	Uma sessão, tarefa reenviada a cada rodada.
flame_chase	primeiro_perseguidor, segundo_perseguidor	Dois agentes se alternam em sessões novas.

Fluxos do usuário ficam em ~/.hmz/flows/<nome>/__init__.py. Liste-os com ls ~/.hmz/flows/ e leia a docstring para papéis e parâmetros antes de usar um. Para obter o contrato completo de qualquer fluxo: ~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)".

Resultados

• Toda execução é um épico em ~/.hmz/epics/<cwd-com-barras-como-travessões>/<timestamp>/, e epic.jsonl contém os eventos resumidos: began (fluxo, tarefa), opened (cada sessão do agente), usage (custo, output_tokens, segundos) e ended com um campo how: done quando a condição de parada do próprio fluxo foi atendida, stopped caso contrário (outros valores podem existir).
• O log --json tem o fluxo completo de eventos, incluindo erros como HarnessUnrecoverable quando uma etapa falha. Leia seu final para saber por que a execução terminou.
• Relate o resultado, o custo e a duração de usage, e sua própria verificação do diff.

Notas de configuração

• Runtimes salvos dizem onde o CLI do agente executa com harness: (affinity: é o nome antigo e ainda é lido). Um runtime em outra máquina sem harness definido não recai para executar o CLI aqui, então defina harness: local quando o host remoto não tiver o CLI.
• Perguntas secundárias /btw para o épico só funcionam quando a configuração btw nomeia um agente (Configurações › Geral).
• As páginas de execução de hmz web estão em #/epics/.