DeepSeek Super-agent: configuração e arquitetura Router/Worker

Comece o teste do DeepSeek Super-agent com um repositório, um único solicitante autorizado e uma conta dedicada no sistema operacional. O Router transforma solicitações autorizadas em Tickets, enquanto os Workers usam sessões e diretórios separados. Mantenha observe ativado no início, mas saiba que solicitações explícitas ainda podem ser executadas.

Em 2026-11-09, o dsh-superagent-prototype é código de pesquisa, não um produto oficial da DeepSeek nem um serviço pronto para produção. Seu manifesto de pacote declara a versão 0.1.0 e a licença MIT. A implementação pública também difere do sistema interno da equipe e da implementação descrita no artigo de arquitetura.

O que fazem Router, Ticket e Worker

A principal diferença é o recebimento contínuo de tarefas, não outro modelo nem uma nova interface de programação. O pacote roda dentro do DeepSeek Harness, acompanha um repositório do GitHub e pode receber mensagens do Feishu opcionalmente.

O modelo de domínio separa os eventos recebidos do trabalho autorizado. A avaliação, chamada Eval, decide se uma possível tarefa justifica criar um Ticket. Cada Ticket aceito recebe um Mandate, que registra sua autorização e seu escopo.

O Router é a sessão principal do agente que decide como encaminhar as solicitações. O Worker executa a tarefa aceita. Nas páginas de configuração, esse Worker é chamado de Executor.

Cada Worker tem sua própria sessão e seu diretório de trabalho. Os resultados voltam à conversa original, por exemplo, em um comentário no GitHub com um pull request. Um diretório separa as cópias de trabalho; não restringe os arquivos que o processo pode ler.

Por exemplo, dois relatos de bugs sem relação podem virar Tickets separados, em vez de compartilhar uma conversa de programação. Isso ajuda quando coordenar as tarefas recebidas exige mais atenção do que iniciar uma tarefa individual.

Para uma única alteração interativa, mantenha seu agente de programação atual. Para delegar trabalho com escopo limitado, comece com subagentes do Claude Code somente para leitura e com seleção explícita do modelo.

Por que observe não é um sandbox de segurança

observe limita o trabalho inferido do contexto, não toda a execução. As regras de autorização permitem solicitações explícitas em todos os modos de aceitação.

Em observe, avaliações positivas de tarefas inferidas geram registros “would accept”, sem criar trabalho a partir deles. Em auto, uma avaliação positiva pode aceitar trabalho inferido. Uma pessoa autorizada que mencione o agente pode pedir trabalho em qualquer modo.

A lista de pessoas autorizadas não é o único controle de admissão. Uma célula da tabela de admissão também pode conceder autorização explícita a pessoas fora da lista. Configure a política de solicitante único descrita abaixo, em vez de depender apenas de observe.

O que significa danger-full-access

Use uma conta do sistema operacional que contenha apenas as credenciais do agente. O aviso sobre isolamento da documentação de implantação vale para dsh-superagent-router e dsh-superagent-worker. Ambos rodam como o usuário do sistema operacional do operador, com danger-full-access.

Os wrappers de credenciais selecionam contas; não isolam processos. Os Workers podem executar programas por caminhos absolutos e ler o diretório pessoal do operador. O guia de implementação também concede ao Router ferramentas de shell e leitura de arquivos.

Para o primeiro teste, use uma máquina temporária ou virtual com uma conta do agente sem privilégios de administrador. Deixe fora desse ambiente as credenciais pessoais, os segredos de produção e os repositórios não relacionados ao teste. Essas são precauções de implantação, não proteções fornecidas pelo protótipo.

Mantenha também um perfil separado do Harness. O plugin altera PATH e as configurações do git para todo o processo. Deixe o painel vinculado a 127.0.0.1; não exponha esse teste como um serviço web público.

Configure um teste apenas com GitHub

Siga os passos manuais abaixo com uma conta e um perfil novos. O repositório também oferece um SETUP.md para configuração com ajuda de um agente.

Confira os pré-requisitos

Instale Node.js 22.19+ ou 24+, pnpm, git 2.32+, Python 3.8+, tmux e GitHub CLI 2.48+. Esses são os pré-requisitos documentados.

Você também precisa de um repositório em github.com e de um provedor de modelos para o DeepSeek Harness. GitHub Enterprise Server não é compatível. Instale git-lfs se o repositório de destino usar Git LFS.

Use um repositório de teste que não esteja vazio e contenha README.md. Para a primeira verificação, prefira um repositório privado acessível apenas a você e ao agente.

O Feishu é opcional e fica fora deste teste. A configuração documentada exige também um aplicativo Feishu ou Lark com bot e o lark-cli. O projeto informa que testou a versão 1.0.90.

Faça login apenas como o agente

Crie uma conta de usuário dedicada no GitHub e conceda acesso de escrita ao repositório de teste. Execute estes comandos no Bash, usando a conta dedicada do sistema operacional.

unset GH_TOKEN GITHUB_TOKEN
gh auth login --hostname github.com --git-protocol https
gh api user --jq .login
gh auth setup-git --hostname github.com

Conclua o login interativo do GitHub CLI como o agente. O comando gh api deve mostrar o nome de usuário dele. Remover as duas variáveis impede que credenciais do ambiente tenham prioridade sobre o login salvo.

A etapa separada gh auth setup-git configura o Git para usar o GitHub CLI como auxiliar de credenciais. Isso importa porque a preparação e o envio de branches usam o Git diretamente.

Crie o clone local com a sintaxe documentada do GitHub CLI:

read -r -p "Repository (owner/name): " TARGET_REPOSITORY
mkdir -p "$HOME/src"
gh repo clone "$TARGET_REPOSITORY" "$HOME/src/superagent-target"

Depois, verifique o acesso HTTPS separadamente de gh api:

GIT_TERMINAL_PROMPT=0 git ls-remote \
  "https://github.com/$TARGET_REPOSITORY.git" HEAD

GIT_TERMINAL_PROMPT=0 git -C "$HOME/src/superagent-target" push --dry-run \
  "https://github.com/$TARGET_REPOSITORY.git" \
  HEAD:refs/heads/agent-auth-check

O git ls-remote deve retornar o HEAD remoto. Em um repositório público, essa leitura pode funcionar anonimamente. A verificação com push --dry-run testa a conexão de envio sem atualizar referências remotas.

Os dois comandos precisam terminar com sucesso. Ainda assim, use o envio real da branch para criar o PR como verificação final da entrega.

Este exemplo usa gh diretamente porque toda a conta do sistema operacional pertence ao agente. Não reutilize a configuração de uma conta pessoal com vários logins do GitHub.

Instale um perfil dedicado do Harness

Use a versão do Harness fixada na documentação de implantação: 0.2.1-rc.3. O manifesto do pacote exige que engines.dsh satisfaça ^0.2.1-alpha.2.

Defina DSH_HOME antes de qualquer comando dsh. A referência da CLI dessa versão coloca perfis nomeados em $DSH_HOME/profiles/<name>. Neste teste, $HOME/.dsh é o local escolhido explicitamente.

Os comandos Bash a seguir servem apenas para uma instalação nova:

export DSH_HOME="$HOME/.dsh"

npm install -g @deepseek-ai/dsh@0.2.1-rc.3
git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git
cd dsh-superagent-prototype
pnpm install
pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"

Não execute novamente o comando de criação do perfil em uma instalação existente. Ele substitui o perfil e exclui seu cordis.patch.yml. Para atualizar, siga o procedimento da documentação de implantação.

Confirme que o manifesto do perfil existe antes de gravar a configuração da máquina. Continue na mesma sessão do Bash:

test -f "$DSH_HOME/profiles/superagent/package.json" || exit 1

cat > "$DSH_HOME/profiles/superagent/cordis.patch.yml" <<EOF
- id: webserver
  config:
    host: 127.0.0.1
    port: 3082
- id: dsh-superagent
  config:
    stateDir: "$DSH_HOME/state/superagent"
EOF

if tmux list-sessions >/dev/null 2>&1; then
  tmux set-environment -g DSH_HOME "$DSH_HOME"
  if tmux has-session -t '=dsh-superagent' 2>/dev/null; then
    tmux set-environment -t '=dsh-superagent' DSH_HOME "$DSH_HOME"
  fi
fi

scripts/dsh-superagent start
scripts/dsh-superagent status

O script do serviço executa dsh --profile superagent por meio do tmux. Um novo servidor tmux herda o ambiente exportado. O bloco também atualiza o ambiente do tmux de um servidor ou de uma sessão já existente.

Abra http://127.0.0.1:3082 em um navegador na máquina do servidor. Nas configurações do Harness, Open configuration file deve abrir o caminho superagent/cordis.patch.yml indicado acima. Pare se abrir outro local. Não sobrescreva esse arquivo de patch depois de adicionar as configurações do provedor.

Selecione Superagent na barra lateral. É esperado um aviso de configuração incompleta enquanto faltarem os ajustes do repositório e da conta. Antes de configurar o recebimento de solicitações, conclua a seção de seleção do modelo mais abaixo.

Configure o recebimento e as árvores de trabalho por Ticket

Use Superagent → Settings e seus grupos documentados.

Em Sources → GitHub, informe seu repositório como owner/name e defina a CLI do agente como gh. Deixe desligadas as opções de receber todos os Issues, pull requests, comentários e eventos de CI da branch padrão. Mantenha o Feishu desativado.

Em Eval → On each Source → GitHub, deixe apenas seu nome de usuário pessoal em GitHub accounts that may originate work. Remova as outras entradas e deixe a lista de bots vazia. Defina como ignore todas as células visíveis de admissão para pessoas fora da lista, inclusive as que se dirigem ao agente. Salve com o modo de aceitação observe.

Esses padrões para pessoas fora da lista estão definidos na matriz de admissão. Eles restringem solicitações de trabalho novo. Não impedem que mensagens de discussões acompanhadas pelo agente cheguem como contexto a Tickets existentes. Limite a conversa de teste a você e ao agente.

Em Execution, comece com concorrência 1 como configuração de teste. Mantenha o diretório raiz padrão. Cole o conteúdo abaixo no campo do comando de preparação; ele roda com sh, e a sintaxe também é válida no Bash.

git -C "$HOME/src/superagent-target" fetch --no-tags \
  "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C "$HOME/src/superagent-target" worktree add \
  -b "agent/$DSH_SUPERAGENT_NAME" \
  "$DSH_SUPERAGENT_DIR" \
  "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"

O exemplo adapta a receita de árvores de trabalho da documentação de implantação ao clone criado acima. Ele busca a revisão correspondente e cria a branch e a cópia de trabalho do Ticket. Sem um comando de preparação, o Worker começa em um diretório vazio.

Em Prompts, defina a identidade do autor dos commits e o texto que informa a participação do agente. Exija que uma pessoa faça o merge e não forneça uma conta separada para essa operação. As instruções do prompt são orientações, não proteções impostas pelo repositório.

É possível usar outro modelo?

Sim, por meio dos provedores configurados no DeepSeek Harness. O guia de provedores na tag dsh-v0.2.1-rc.3 documenta os passos abaixo para a versão instalada.

Abra Settings → Models no Harness. Insira e salve a chave de API no cartão da DeepSeek ou escolha Add model provider para outro provedor compatível. Insira as credenciais localmente nessa interface, não em uma discussão no GitHub.

Para Custom model API, informe um Provider ID em letras minúsculas, a URL base, o protocolo de API correspondente, a credencial e pelo menos um modelo. Use os valores documentados pelo provedor. Salvar um provedor não comprova que o modelo consegue realizar as chamadas de ferramentas necessárias.

Em seguida, use Choose workspace para adicionar e selecionar $HOME/src/superagent-target, seguindo o guia da interface web dessa versão. Inicie uma sessão comum e escolha um modelo configurado no seletor de modelos. Essa escolha define o padrão para novas sessões.

Abra outra sessão nova e confirme que ela mostra o mesmo provedor e modelo antes de enviar uma solicitação. Peça para ler README.md e retornar o primeiro título sem editar nada. Compare a resposta com o arquivo. Não use nenhum dos presets gerenciados dsh-superagent-* nesse teste.

Depois, selecione explicitamente esse provedor e modelo testados em Superagent → Settings → Eval e Execution. Eval fornece o modelo de Router e de avaliação; Execution fornece o modelo do Worker. Este teste não depende de um padrão não confirmado. Deixe qualquer uma dessas seleções sem definição somente depois de verificar o modelo padrão do perfil.

A seleção do Executor se aplica quando uma sessão é criada. Sessões existentes do Worker mantêm seu modelo, e Retry reutiliza a mesma sessão. Verifique uma mudança posterior de modelo com um Ticket novo.

Verifique uma solicitação e localize a falha

Verifique uma solicitação completa no GitHub e sua resposta antes de pedir alterações no código. Um painel em execução não comprova que a autorização, a preparação e as chamadas ao modelo funcionam.

Primeiro, execute scripts/dsh-superagent status novamente. Exija código de saída 0 e nenhuma pendência de configuração. Publique um comentário novo em uma issue pela conta pessoal autorizada. Substitua @AGENT_LOGIN pelo nome de usuário do agente:

@AGENT_LOGIN Read README.md and reply here with its first heading.
Do not edit files, push a branch, or open a pull request.

O procedimento de teste da documentação de implantação coloca o Ticket resultante em Overview. Confira se a resposta na conversa original do GitHub contém o título correto.

Depois que isso funcionar, peça uma pequena alteração na documentação e um pull request para revisão humana. Confirme que a branch foi enviada, que o PR pertence à conta do agente e que o diff respeita o escopo. Essas são verificações de aceitação, não resultados garantidos do modelo.

Se um Ticket não aparecer, confira o usuário autorizado, as células de admissão, o repositório e a integridade da fonte GitHub. Depois, publique um novo comentário mencionando o agente.

Em falhas do serviço, o script retorna 1 para problemas no processo ou na execução, 2 para erros de componentes e 3 para configuração incompleta. Reiniciar pode ajudar no caso de 1; corrija a causa informada para 2 ou 3.

Para falhas transitórias do modelo ou da rede, o guia de execução prevê três novas tentativas com intervalos crescentes. Isso inclui os códigos HTTP 408, 429 e 5xx. Falhas no comando de preparação ficam fora dessa repetição automática.

Retome o trabalho após uma falha na preparação

Inspecione o erro de preparação registrado e o diretório do Ticket antes de selecionar Retry. A implementação de inicialização só executa a preparação quando esse diretório não existe. Um diretório existente é tratado como preparado, mesmo que contenha trabalho incompleto.

Quando o diretório não existir, corrija o problema de credenciais ou do comando de preparação e selecione Retry. A nova inicialização tenta executar a preparação novamente.

Quando o diretório existir, copie o caminho dos detalhes do Ticket e inspecione-o no Bash:

read -r -p "Ticket directory (absolute path): " TICKET_DIR
git -C "$TICKET_DIR" rev-parse --show-toplevel
git -C "$TICKET_DIR" status --short --branch

O diretório raiz informado deve ser o diretório do Ticket, não uma cópia de trabalho em um diretório superior. Confira a branch e o estado da árvore de trabalho, os arquivos esperados e cada etapa de preparação que falhou.

Use Retry em um diretório existente somente depois de concluir e verificar sua preparação. Retry não o reconstrói. Se não puder restaurar uma cópia incompleta com segurança, preserve-a, interrompa esse Ticket, corrija o comando e envie uma solicitação em uma nova issue. Confirme que o Ticket substituto usa um diretório novo antes de continuar.

Depois que um Ticket falha, mensagens de CI e de bots não reativam seu Worker. Uma pessoa precisa intervir. Pare o serviço de teste ao terminar:

scripts/dsh-superagent stop

Quando manter o serviço em execução

Mantenha o protótipo apenas quando suas decisões de encaminhamento e as alterações entregues justificarem o trabalho operacional. Comece com escopo restrito. Aumente a concorrência somente depois de medir resultados úteis e o uso do provedor.

Compare o custo por alteração aceita, não apenas o preço do modelo. Inclua encaminhamento, avaliação, chamadas do Worker e recuperação no orçamento do teste. O guia de custo por tarefa de agentes de programação oferece uma forma de comparar o modelo junto com seu ambiente de execução.

Não trate uma demonstração interna como equivalente a esse código público. O repositório alerta que algumas ideias do artigo mais amplo ainda não foram implementadas. Mantenha a implantação isolada e sob revisão humana até que suas verificações justifiquem ampliar o uso.