GuidesOneMux

Cline em produção: configure sessões e recupere-se com segurança

Um guia prático para configurar sessões do ClineCore, separar as definições de runtime da configuração do provedor e criar regras seguras de nova tentativa e recuperação.

AI

Resumo · TL;DR

O ClineCore separa as escolhas de runtime — como modo de backend, recursos, políticas de ferramentas e automação — do provedor e do modelo configurados para cada sessão. Este guia mostra como tornar essa separação explícita e criar comportamentos de recuperação com base em IDs de sessão e estado persistido, em vez de repetir o trabalho às cegas.

Principais pontos

  • Mantenha as configurações de runtime, permissões de ferramentas e provedor/modelo como decisões separadas.
  • Use IDs de sessão e mensagens persistidas para investigar falhas antes de tentar novamente.
  • Considere que novas tentativas podem duplicar efeitos colaterais; defina pontos de verificação e regras de recuperação para seu fluxo de trabalho.
  • A referência da API documenta operações de sessão, mas não especifica a semântica de novas tentativas, formatos de pontos de verificação nem garantias de compatibilidade com provedores.
Nesta página (9)

O ClineCore permite que um aplicativo controle a criação de sessões, a seleção do runtime, as permissões de ferramentas e o histórico das sessões. Em operações de produção, a principal decisão de projeto não é simplesmente se uma chamada com falha deve ser repetida: é como determinar o que já aconteceu antes de executar o trabalho novamente.

A configuração abaixo é ilustrativa, não uma receita de implantação testada. A referência da API do ClineCore documenta as opções e os métodos discutidos aqui; consulte a versão do SDK que você instalar para conhecer os tipos e comportamentos exatos.

Separe as definições de runtime das definições do modelo

Uma divisão útil da configuração tem três partes:

  • Runtime: seleção do backend, identidade do cliente e definições opcionais de conexão remota ou com hub.
  • Política de execução: políticas de ferramentas, recursos e ativação das APIs de automação.
  • Configuração do modelo da sessão: ID do provedor, ID do modelo, credenciais, caminhos do workspace e disponibilidade de ferramentas para uma sessão específica.

Essa separação facilita o gerenciamento da política de runtime sem depender de mudanças no modelo. Ela não torna intercambiáveis os campos específicos do provedor: providerId, modelId e apiKey ainda precisam ser válidos para o provedor selecionado. A referência da API não estabelece compatibilidade com todos os provedores ou endpoints.

Crie um runtime e inicie uma sessão

Pré-requisitos: instale a versão do Cline SDK que pretende implantar, forneça credenciais usando a abordagem de gerenciamento de segredos do seu aplicativo e decida quais ferramentas o agente poderá usar. Não inclua credenciais em logs ou metadados de sessão.

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "repo-maintenance-worker",
  backendMode: "auto",
  toolPolicies: {},
  automation: false,
})

const session = await cline.start({
  prompt: "Inspect the repository and report failing tests. Do not modify files.",
  source: "scheduled-check",
  interactive: false,
  sessionMetadata: { jobId: "job-123" },
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "Follow the task scope and report actions taken.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)

Os valores de provedor e modelo acima correspondem ao exemplo da referência da API; não são uma recomendação nem uma afirmação de compatibilidade com provedores além do que esse exemplo demonstra. A referência documenta os valores de backendMode auto, local, hub e remote, além das definições opcionais hub e remote. Ela não determina qual modo é melhor para uma implantação específica. Escolha deliberadamente e valide a conectividade e as permissões no seu ambiente.

Um objeto toolPolicies vazio não é uma política de segurança. Defina padrões explícitos e políticas por sessão de acordo com os tipos de política compatíveis com o SDK instalado. Use capabilities quando o cliente fornecer executores de ferramentas ou callbacks de aprovação e teste se as ações restritas são realmente negadas.

Crie regras para novas tentativas com base no estado da sessão

Um erro de rede ou tempo limite de um worker não prova que o agente parou antes de concluir o trabalho. Repetir o prompt original pode duplicar edições, chamadas externas ou outros efeitos colaterais. A referência da API lista get, readMessages, getAccumulatedUsage, abort, stop e restore, mas não especifica novas tentativas automáticas, execução exatamente uma vez nem o conteúdo de um ponto de verificação.

Uma sequência operacional mais segura é:

  1. Registre o ID da sessão imediatamente. Persista-o junto com o identificador do trabalho para que um worker reiniciado possa localizar a mesma sessão.
  2. Classifique a falha. Diferencie uma falha terminal confirmada de um tempo limite ou uma conexão perdida em que a conclusão é incerta.
  3. Inspecione antes de reenviar. Use get e readMessages para verificar os metadados da sessão e as mensagens persistidas. Quando relevante, consulte o uso acumulado como indício operacional, não como prova de que uma ação específica foi concluída.
  4. Escolha a estratégia de recuperação deliberadamente. Se a sessão ainda estiver ativa, decida se deve aguardar, abortar ou parar. Se o trabalho precisar continuar, send aceita um ID de sessão e um prompt de acompanhamento. Se houver um ponto de verificação adequado, a API disponibiliza restore; consulte a documentação do SDK para saber os dados de entrada necessários e a semântica do método.
  5. Garanta que os efeitos colaterais possam ser repetidos com segurança. Para ações fora do estado da própria sessão do agente, use chaves de idempotência no nível do aplicativo, deduplicação ou uma etapa de aprovação humana, quando apropriado.

Evite envolver start em um loop incondicional de novas tentativas. Se a solicitação inicial pode ter criado uma sessão antes de o chamador perder a resposta, outro start pode criar um trabalho separado. A referência da API não documenta uma chave de idempotência para start; portanto, não presuma que ela exista.

Solucione falhas comuns em produção

A sessão inicia com o runtime errado

Registre o modo de backend selecionado e os identificadores de sessão que não sejam secretos. Confira as opções backendMode, hub e remote em relação ao ambiente em que o worker é executado. A referência descreve essas opções como seletores de runtime, mas não documenta o comportamento de failover automático; verifique o que auto faz na versão do SDK que você usa, em vez de confiar em um fallback presumido.

As ferramentas não estão disponíveis ou são permitidas inesperadamente

Confira tanto o config da sessão quanto as toolPolicies ou capabilities padrão e por sessão aplicáveis. A referência identifica essas opções como controles de política de ferramentas e de executores/aprovações definidos pelo cliente. O resumo da API fornecido não detalha a precedência das políticas; confirme-a na documentação do SDK instalado e teste casos permitidos e negados.

Um worker perde a conexão durante a execução

Mantenha o ID da sessão e o ID do trabalho no estado persistente do aplicativo. Após a reinicialização, inspecione a sessão existente antes de decidir se deve continuar com send, interrompê-la ou restaurá-la a partir de um ponto de verificação. Não conclua que o trabalho terminou apenas porque uma resposta não chegou.

A configuração do provedor ou do modelo falha

Verifique o ID do provedor, o ID do modelo, as credenciais e os requisitos de endpoint nas documentações do provedor e do Cline correspondentes à configuração escolhida. A referência do ClineCore mostra a estrutura da configuração de provedor/modelo; ela não garante que endpoints arbitrários compatíveis com OpenAI ou parâmetros específicos de provedores funcionem sem alterações.

Lista de verificação para produção

  • Armazene os IDs de sessão de forma persistente e mantenha segredos fora dos logs e metadados.
  • Defina explicitamente as permissões das ferramentas; teste os fluxos de aprovação e negação.
  • Diferencie uma operação com falha de uma operação cujo resultado é desconhecido.
  • Inspecione o histórico da sessão antes de reenviar o trabalho.
  • Torne os efeitos colaterais externos idempotentes ou exija aprovação antes de repeti-los.
  • Valide o comportamento do backend e do provedor no ambiente real de implantação.
  • Libere os recursos do runtime durante o encerramento ordenado, seguindo o ciclo de vida documentado pelo SDK.

A regra prática é simples: só tente novamente depois de saber o que está repetindo. O ClineCore oferece APIs relacionadas a sessões e recuperação, mas um comportamento seguro em produção ainda depende do acompanhamento persistente de trabalhos no aplicativo, do projeto de permissões e do tratamento de efeitos colaterais duplicados.

Perguntas frequentes

Quais definições do ClineCore são independentes do provedor do modelo?

Opções de runtime como `clientName`, `backendMode`, definições opcionais de hub ou remoto, recursos, políticas de ferramentas e automação são separadas dos campos de provedor e modelo da sessão. O comportamento exato das opções deve ser verificado na versão do SDK em uso.

Devo tentar novamente ClineCore.start após um tempo limite?

Não às cegas. Um tempo limite não indica se uma sessão foi criada. Persista o ID da sessão quando estiver disponível e inspecione as sessões existentes antes de iniciar um novo trabalho. A referência da API fornecida não documenta uma chave de idempotência para `start`.

O ClineCore consegue restaurar uma sessão com falha?

A referência da API lista o método `restore`, mas o resumo fornecido não especifica os dados de entrada necessários nem a semântica dos pontos de verificação. Consulte a documentação do SDK instalado antes de planejar a recuperação com base nesse método.

Esta configuração funciona com qualquer provedor compatível com OpenAI?

Isso não é estabelecido pela referência do ClineCore citada. A compatibilidade com provedores e os parâmetros aceitos dependem do suporte documentado ao endpoint e à configuração de provedor selecionada; verifique essas informações em vez de presumir que sejam intercambiáveis.

Artigos relacionados