Files
msd-core/docs/pt-BR/how-to/configure-model-profiles.md
Jakub Zych 6cfa0c55d2 refactor: drop 12 runtimes, keep Claude, Codex, OpenCode, Cursor, ZCode, Antigravity
Removes kilo, kimi, kimi-code, copilot, windsurf, augment, trae, qwen, hermes,
cline, codebuddy and pi end to end: capability descriptors, installer branches
and converters (bin/install.js 14.9k -> 11.2k lines), TypeScript converters,
hook surfaces and runtime homes, review lanes qwen/kimi-code, the two pi
migrations, Kimi payload normalization in the hook guards, dead hostBehaviors
vocabulary, launcher home probes, fixtures, runtime-specific tests and the
prose that presented them as supported.

Installer output for the six kept runtimes is byte-identical to before the
prune. The Kimi tool-vocabulary tests in workflow-guard, read-guard and
read-injection-scanner are left in place pending a decision.
2026-10-06 20:02:40 +02:00

220 lines
8.4 KiB
Markdown

# Como configurar perfis de modelo
Escolha a estratégia de nível de modelo adequada para o seu projeto e ajuste agentes individuais ou tipos de fase inteiros sem precisar escrever um bloco de substituição extenso. Este guia começa pelo controle mais simples e avança até o roteamento dinâmico.
---
## Os quatro perfis (mais `adaptive` e `inherit`)
Defina `model_profile` em `.planning/config.json` ou via `/msd-config --profile <name>`:
| Perfil | Planejador | Executor | Pesquisadores | Verificador | Usar quando |
|--------|-----------|----------|---------------|-------------|-------------|
| `quality` | Opus | Opus | Opus | Sonnet | Trabalho de qualidade para produção onde o custo é secundário |
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | Desenvolvimento normal — o padrão |
| `budget` | Sonnet | Sonnet | Haiku | Haiku | Prototipagem rápida, contextos com restrições de custo |
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolve da mesma forma que os outros níveis em perfis cientes de runtime; use ao alternar entre runtimes com frequência |
| `inherit` | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | Provedores não-Anthropic (OpenRouter, modelos locais) — todos os agentes seguem o modelo atual da sessão |
A tabela acima mostra um subconjunto representativo. Todos os 33 agentes incluídos possuem atribuições de nível explícitas por perfil em `msd-core/bin/shared/model-catalog.json`. Para a tabela completa, consulte [Perfis de Modelo](../CONFIGURATION.md#model-profiles) na referência de configuração.
**Troca rápida via comando:**
```bash
/msd-config --profile balanced # Desenvolvimento normal
/msd-config --profile budget # Prototipagem ou fases de alto custo
/msd-config --profile quality # Lançamento em produção
/msd-config --profile inherit # OpenRouter, modelos locais
```
**Ou edite `.planning/config.json` diretamente:**
```json
{
"model_profile": "balanced"
}
```
---
## Substituições por agente (`model_overrides`)
Se um único agente precisa de um nível diferente sem alterar o perfil inteiro, use `model_overrides`:
```json
{
"model_profile": "balanced",
"model_overrides": {
"msd-executor": "opus",
"msd-codebase-mapper": "haiku"
}
}
```
Valores válidos: `opus`, `sonnet`, `haiku`, `inherit` ou qualquer ID de modelo totalmente qualificado (ex.: `"openai/o3"`, `"google/gemini-2.5-pro"`).
`model_overrides` pode ser definido por projeto em `.planning/config.json` ou globalmente em `~/.msd/defaults.json`. Entradas por projeto têm precedência em conflitos; entradas globais sem conflito são preservadas.
**Importante para Codex e OpenCode:** Esses runtimes incorporam o modelo resolvido na configuração estática de cada agente no momento da instalação. Após editar `model_overrides`, execute novamente o instalador para que a alteração entre em vigor:
```bash
npx @golem15/msd-core@latest --codex --global # ou --opencode, etc.
```
---
## Modelos por tipo de fase (`models`)
Se você quer dizer "Opus para planejamento, Sonnet para todo o resto" sem precisar aprender todos os 33 nomes de agentes, use o bloco `models`. Ele mapeia seis tipos de fase para aliases de nível:
```json
{
"model_profile": "balanced",
"models": {
"planning": "opus",
"discuss": "opus",
"research": "sonnet",
"execution": "opus",
"verification": "sonnet",
"completion": "sonnet"
}
}
```
Tipos de fase e seus agentes:
| Tipo de fase | Agentes cobertos |
|---|---|
| `planning` | `msd-planner`, `msd-roadmapper`, `msd-pattern-mapper` |
| `research` | `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-codebase-mapper`, `msd-ui-researcher` |
| `execution` | `msd-executor`, `msd-debugger`, `msd-doc-writer` |
| `verification` | `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-nyquist-auditor`, `msd-ui-checker`, `msd-ui-auditor`, `msd-doc-verifier`, `msd-code-reviewer` |
| `discuss` | `msd-assumptions-analyzer` |
| `completion` | Reservado — nenhum subagente hoje; aceito pelo esquema para compatibilidade futura |
O bloco `models` aceita apenas aliases de nível (`opus`, `sonnet`, `haiku`, `inherit`). Para um ID de modelo totalmente qualificado, use `model_overrides` por agente.
**Combinando `models` com uma exceção por agente:**
```json
{
"model_profile": "balanced",
"models": {
"research": "sonnet"
},
"model_overrides": {
"msd-codebase-mapper": "haiku"
}
}
```
Todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `msd-codebase-mapper`, que está fixado em `haiku`.
---
## Roteamento dinâmico — comece barato, escale em caso de falha
Se você quiser pagar pelos níveis mais baratos por padrão e só escalar quando um agente falhar em um controle de qualidade, habilite `dynamic_routing`:
```json
{
"dynamic_routing": {
"enabled": true,
"tier_models": {
"light": "haiku",
"standard": "sonnet",
"heavy": "opus"
},
"escalate_on_failure": true,
"max_escalations": 1
}
}
```
Cada agente possui um nível padrão (`light`, `standard` ou `heavy`). Na primeira tentativa, o MSD escolhe `tier_models[default_tier]`. Se o orquestrador detectar uma falha suave (verificação inconclusiva, verificação de plano sinalizada, etc.), ele reinicia o agente um nível acima. `max_escalations` limita o total de novas tentativas.
Agentes que já estão em `heavy` não podem escalar mais.
**Desativar a escalada mantendo a resolução dinâmica:**
```json
{
"dynamic_routing": {
"enabled": true,
"escalate_on_failure": false
}
}
```
Cada tentativa usa `tier_models[default_tier]` independentemente do resultado — útil quando você quer mapeamento explícito de nível para modelo sem o comportamento de escalada.
`dynamic_routing` está **desabilitado por padrão**. Omitir o bloco ou definir `enabled: false` preserva a resolução estática.
---
## Usando o MSD em runtimes não-Anthropic
Se você instalou o MSD para Codex, OpenCode, ou Antigravity CLI, o instalador já definiu `resolve_model_ids: "omit"` na sua configuração. Isso instrui o MSD a pular a resolução de IDs de modelo Anthropic e deixar o runtime escolher seu próprio modelo padrão. Nenhuma configuração manual é necessária para o caso básico.
**Se você quiser modelos por nível no Codex:**
```json
{
"runtime": "codex",
"model_profile": "balanced"
}
```
O MSD resolve cada alias de nível para o modelo nativo do Codex e o esforço de raciocínio definido no mapa de nível do runtime.
**Se você quiser IDs de modelo por agente em qualquer runtime não-Claude:**
```json
{
"resolve_model_ids": "omit",
"model_overrides": {
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3"
}
}
```
Para a referência completa de perfis cientes de runtime e a superfície `model_policy` (predefinições neutras em relação ao provedor adicionadas na v1.42), consulte [Referência de configuração — Perfis de Modelo](../CONFIGURATION.md#model-profiles).
---
## Precedência de resolução (maior para menor)
Quando múltiplas camadas se aplicam, o resolvedor escolhe a entrada de maior prioridade:
```text
1. model_overrides[<agent>] — por agente; IDs completos; exceção direcionada
2. dynamic_routing.tier_models[<tier>] — quando habilitado; escala em falha suave
3. models[<phase_type>] — nível de fase grosseiro
4. model_profile (coluna por agente) — estratégia global de nível
5. Padrão do runtime — quando nada mais se aplica
```
---
## Escolhendo o controle certo
| O que você quer | Use |
|---|---|
| Uma estratégia de nível para todos os agentes | `model_profile` |
| Ajuste grosseiro por fase ("Opus para planejamento") | `models.<phase_type>` |
| Precisão por agente ("forçar Haiku no mapeador de base de código") | `model_overrides[<agent>]` |
| Um ID de modelo totalmente qualificado para um agente específico | `model_overrides[<agent>]: "openai/gpt-5"` |
| Começar barato, escalar apenas em falha | `dynamic_routing` |
| Todos os agentes seguem o modelo da sessão (provedor não-Anthropic) | `model_profile: "inherit"` |
---
## Relacionados
- [Referência de configuração](../CONFIGURATION.md)
- [Orquestração multi-agente](../explanation/multi-agent-orchestration.md)
- [Referência de comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)