414960701/harness-distiller

Harness Distiller（Agent Harness 蒸馏器）

Converte evidências públicas em Agent Harnesses realizáveis, verificáveis e atualizáveis. Trate nomes de produtos como receitas de comportamento e capacidade, não copie marcas, prompts proprietários, materiais protegidos ou implementações internas não verificáveis.

Obrigatório segui

1. Diferencie code, official-doc, protocol, behavior, inference; nunca escreva inferências de produtos fechados como fatos de código-fonte.
2. Os quatro níveis de maturidade compartilham o mesmo protocolo, modelo de estado e limites de módulo; upgrade apenas adiciona capacidade e otimização, não gera quatro conjuntos incompatíveis de engenharia.
3. Primeiro implemente uma fatia vertical completa: modelo → Agent loop → uma ferramenta de leitura → permissão → execução → evento → estado → interface.
4. Mantenha o runtime headless; CLI, TUI, IDE, desktop e Web interagem apenas por um protocolo command/event versionado.
5. Separe approval policy de sandbox enforcement; aprovação do usuário não substitui limites obrigatórios de SO, contêiner, caminho ou rede.
6. Cada "implementado" deve ter uma localização de código; cada "verificado" deve ter um teste executável ou evidência de comportamento reproduzível.
7. Não considere que "o modelo pode chamar o shell" como "Harness completo". Deve implementar cancelamento, falha, recuperação, persistência, permissões e reconstrução de estado da interface.

Leia sob demanda

• Para selecionar produto e verificar integridade do catálogo: leia references/catalog.md.
• Para selecionar nível ou atualizar entre níveis: leia references/levels.md.
• Para decidir quando uma capability pode ser marcada como verificada: leia references/capabilities.md.
• Para avaliar confiabilidade de evidências: leia references/evidence.md e references/source-registry.md.
• Para entender os limites compartilhados: leia references/architecture.md.
• Antes de começar a codificar: deve ler references/implementation/index.md, depois carregue as especificações de implementação conforme sua rota.
• Para selecionar capacidades compartilhadas: leia references/knowledge/index.md, carregue apenas os módulos de conhecimento selecionados pela blueprint.
• Para replicar um produto: leia references/products/<product>/index.md e carregue os 13 dossiês desse produto na ordem especificada pelo índice.
• Para criar um novo projeto: leia references/workflows/build.md.
• Para atualizar um projeto existente: leia references/workflows/upgrade.md.
• Para validar um projeto: leia references/workflows/validate.md.

Analisar requisição

A partir da requisição do usuário e do repositório de destino, analise:

• recipe: um produto, hybrid ou custom;
• level: runnable, usable, productive ou polished;
• surfaces: cli, tui, ide, desktop, web, sdk, headless;
• execution: local, container, remote ou combinação;
• stack: prefira manter a pilha do repositório de destino; para novos projetos, escolha conforme superfície do produto e requisitos de segurança;
• providers: provedores de modelo, modelo local e requisitos de degradação de capacidade;
• security: modelo de ameaça pessoal, de equipe ou empresarial;
• distribution: código-fonte, pacote, extensão, aplicativo desktop ou serviço hospedado.

Quando o usuário disser apenas "faça um produto como Codex/Claude Code/QoderWork", selecione por padrão a recipe correspondente, usable, a superfície principal do produto mais headless, e registre as suposições no registro de decisões.

Quando outras escolhas faltarem, use fallbacks padrão: execution=local, security=personal, distribution=source; para Codex-like padrão Rust + headless/TUI, para Claude-Code-like padrão TypeScript + headless/CLI, para QoderWork-like padrão TypeScript + Tauri/Rust executor + headless/Desktop, para Aider-like padrão Python + headless/CLI, para OpenCode padrão TypeScript/Bun + headless/TUI, para OpenHands padrão Python + TypeScript/React + headless/Web/SDK, para AgentScope, LangGraph e Deep Agents padrão Python + headless/SDK. Quando o provedor não for especificado, implemente primeiro o contrato provider-neutral, fixture scriptado determinístico e interface de adapter OpenAI-compatible, sem vincular a serviços pagos por conta própria; antes da integração real, peça ao usuário a configuração do provedor.

Fluxo de geração

1. Verifique repositório, stack tecnológica, instruções existentes, dirty changes e ambiente de execução disponível.
2. Confirme em references/catalog.md que o produto está no nível de implementação; receitas planejadas mas sem 13 dossiês completos não devem gerar réplica de produto; primeiro complete os dossiês ou troque explicitamente para hybrid/custom. Em seguida, execute scripts/new_blueprint.py para criar .harness-distill/blueprint.yaml.
3. Leia index.md, product-contract.md, recipe.md, acceptance-tests.md do produto.
4. Conforme a recipe, carregue as especificações de implementação e documentos de conhecimento compartilhado, estabelecendo o fecho de dependências de capabilities.
5. Escreva .harness-distill/evidence.md, registrando alegações, URLs, datas, versões/commits, tipos de evidência e nível de confiança.
6. Escreva .harness-distill/decisions.md, registrando escolhas arquiteturais, inferências de fontes fechadas, não-objetivos, riscos e pontos de reversão.
7. Implemente primeiro o protocolo, esqueleto de estado e uma fatia vertical executável; salve e reproduza seu trace de eventos.
8. Complete as capacidades na ordem: schema → protocol → runtime → executor/policy → surface → migration.
9. Adicione simultaneamente testes de contrato, cenário, segurança, recuperação, migração e teste de caixa preta do produto.
10. Execute scripts/validate_blueprint.py, a verificação do repositório de destino e acceptance-tests.md do produto.
11. Marque como verified apenas as capacidades que possuem localização de implementação e evidência de teste.

Contrato mínimo da entrega

O projeto de destino deve conter os limites equivalentes:

.harness-distill/
  blueprint.yaml       # escolha, nível, capacidades, estado e versão do contrato
  evidence.md          # evidências públicas e limites de inferência
  decisions.md         # decisões arquiteturais, não-objetivos, riscos e migração
src/
  protocol/            # command/event/error/schema/capability negotiation
  runtime/             # máquina de estados turn, cancelamento, retry, budget, steering
  model/               # adaptador de provedor e negociação de capacidade
  context/             # instruções, recuperação, memória, budget, compressão, cache
  tools/               # schema, registry, router, lifecycle, artifact
  policy/              # allow/deny/ask/amend e escopo de aprovação
  execution/           # workspace, arquivo, shell, patch, rede, sandbox
  state/               # thread/turn/item/event/checkpoint/migration
  surfaces/            # adaptadores CLI/TUI/IDE/Desktop/Web
tests/
  contracts/           # contratos de protocolo, provedor, ferramenta e armazenamento
  scenarios/           # loops fechados de tarefas reais
  security/            # vazamento de fronteira, injeção, segredos, rede e escape
  recovery/            # crash, entrega duplicada, desconexão e migração

É permitido renomear conforme as convenções da linguagem, mas não se pode mesclar os limites entre política e execução, estado de domínio e projeção de UI, histórico do modelo e fatos persistentes.

Portão de integridade

Somente considere como Harness completo do nível selecionado se todas as condições abaixo forem atendidas:

• blueprint, contrato do produto e localizações de implementação estão consistentes;
• para runnable, o trace thread/turn/item/event é persistível e reproduzível; para usable, suporta paginação e recuperação após reinicialização do processo; para polished, exige migração entre versões;
• pares tool call/result atômicos, com semântica clara de cancelamento, timeout e resultado tardio;
• após compressão do contexto selecionado, não quebra atomicidade de chamadas de ferramenta, hierarquia de instruções e escopo de auditoria;
• ações restritas são primeiro decididas pela política e depois impostas pelos limites reais de execução;
• UI reconstruível a partir de snapshot + evento, sem depender de objetos em memória do runtime;
• para usable ou superior, recuperação de crash não repete efeitos colaterais irreversíveis;
• os cenários do nível atual em acceptance-tests.md do produto passam;
• a nota de entrega lista comportamentos não suportados, lacunas de evidência e caminho direto de upgrade.

Atualização entre níveis

Ao atualizar diretamente de qualquer nível inferior para um nível superior:

1. Valide a blueprint atual, protocolo e schema de banco de dados;
2. Calcule o delta de capacidades e expanda as dependências intermediárias;
3. Migre schema primeiro, depois estenda protocolo, runtime, executor e interface;
4. Mantenha configurações antigas e eventos antigos por pelo menos um limite de migração compatível;
5. Para ações externas irreversíveis, estabeleça checkpoint, chave idempotente ou confirmação manual;
6. Execute todos os testes de regressão do nível inferior e os de aceitação do novo nível;
7. Após aprovação nos testes, atualize o status das capacidades.