Gerenciamento de providers de modelos

Diretriz

Flowral terá uma única UI de providers personalizados acessível em Central de Controle > IA > Providers e no Flower/Flowral Agents > Settings > Providers. Ambas compartilham o mesmo Rust core e a mesma fonte de estado. Interface deve ser compatível com OpenCode V2+, sem tentar suportar sintaxes legadas.

Modelo

ProviderProfile: id, nome, tipo de API/runtime, URL base HTTPS ou localhost permitido, auth reference, headers seguros, modelos, limites, preços opcionais, timeout, estado/teste e escopo (usuário/projeto).

ModelProfile: key, modelID remoto, nome exibido, capabilities conhecidas, context/output limit opcionais, variantes e custos conhecidos (não inventar). Manual override é possível com indicação de origem.

Credencial sempre é referência ao keyring ou variável de ambiente, nunca string serializada no arquivo de tema, profile exportado ou repositório.

Exemplo OpenCode V2 — provider personalizado

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "my-gateway": {
      "name": "My Gateway",
      "env": ["MY_GATEWAY_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.example.org/v1"
      },
      "models": {
        "coding": {
          "name": "Coding Model",
          "modelID": "upstream/coder"
        }
      }
    }
  }
}

Este é um exemplo de schema, sem endpoint/credencial reais. A estrutura V2 usa providers plural, settings.baseURL, models, modelID. Não usar schema V1 provider singular. Ref: https://dev.opencode.ai/v2/docs/providers/.

Fluxos UI

• Adicionar template (OpenAI-compatible, Anthropic-compatible, Ollama local ou custom selecionado conforme catálogo real).
• Definir HTTPS baseURL; mostrar aviso claro para HTTP externo; localhost permitido com consentimento.
• Definir fonte da chave (keyring/env), sem ecoar segredo nos logs.
• Selecionar modelos manualmente ou descobrir via API somente quando compatível; não inferir capabilities inexistentes.
• Testar conexão com custo mínimo possível, mostrar endpoint/status/latença/erro de autenticação; não enviar prompt de teste sem avisar.
• Habilitar/ocultar modelo, escolher defaults por projeto/agente, configurar limite/custo opcional.
• Exportar configurações sem segredo; importar com preview e diff; restore com rollback.

Integração com outros agentes

Não escrever configurações de Claude/Codex/Hermes usando schema OpenCode. Registry é neutro, adapters por ferramenta convertem apenas campos suportados por cada versão. Exibir Not supported em vez de fingir sincronização universal.

Validação e segurança

Validar URL, evitar SSRF por campos remotos (URLs localhost só no contexto solicitado), proibir command injection e paths não autorizados. Usar TLS, timeouts, per-provider rate limits. Nunca compartilhar chaves entre projetos/clients silenciosamente; marcar contas e modelos pagos.

Aceite

Ao criar um provider custom na GUI, um profile OpenCode V2 válido aparece em arquivo de config com schema correto, sem chave plaintext. A seleção de modelo funciona, teste de conexão reporta resultado e desativar reverte mudança sem destruir outros providers.