DeepSeek Harness: instalação, recursos e primeiro lançamento

DeepSeek Harness, ou dsh, é um agente de IA de código aberto da DeepSeek AI. Se a modelo responde às perguntas, o arnês dá as mãos: lê e edita arquivos, executa comandos, realiza sessões, mostra a trajetória de execução e se permite ser expandido com plugins. O projeto é distribuído sob a licença do MIT e está em pré-visualização pública.

A ideia principal do DeepSeek Harness é formulada como “tudo é um plugin” – literalmente “tudo é um plugin”. Todo o produto é construído sobre isso: adaptadores de modelo, um registro de ferramentas, um log de sessão, uma interface e até mesmo o próprio ciclo do agente. Ele é baseado na estrutura Cordis, portanto, um desenvolvedor pode não apenas adicionar um novo comando, mas substituir todo o comportamento do agente sem bifurcar o kernel.

Você pode trabalhar com o dsh de várias maneiras: por meio da interface da web local, por meio de um aplicativo de desktop, pela linha de comando no modo headless ou pelo SDK do Python. Abaixo está a instalação, o primeiro lançamento e uma visão geral dos recursos.

O que você precisa

A interface da web e a CLI exigem Node.js. O projeto tem requisitos rigorosos:

  • Node.js 22.19.0 ou posterior na linha 22.x.
  • Node.js 24.0.0 ou posterior na linha 24.x.
  • Node.js 23.x não é compatível em nenhum patch: esta linha não é LTS e já foi descontinuada.

Além do Node.js, você precisará da chave API DeepSeek. Ele é criado em sua conta pessoal em platform.deepseek.com. O aplicativo de desktop não precisa do Node.js – o ambiente já está empacotado lá.

Você pode verificar a versão com o comando:

node -v

Instalação via npx

A maneira mais rápida de conhecer o projeto é não instalar nada globalmente. Basta executar:

npx @deepseek-ai/dsh web

O comando irá baixar o pacote @deepseek-ai/dsh do npm, configurar um servidor web local e abrir a interface no navegador. Por padrão, ele escuta o endereço:

Se você não precisa abrir o navegador, por exemplo, em uma máquina remota, adicione o sinalizador –no-open:

npx @deepseek-ai/dsh web --no-open

Quando iniciado via SSH, dsh imprime o endereço, mas não tenta abrir o navegador: o endereço local pertence ao cliente ou editor SSH.

Instalação global

Se você precisa de uma ferramenta constantemente, é mais conveniente instalá-la globalmente. O pacote fornece o binário dsh:

npm install -g @deepseek-ai/dsh
dsh web

Depois disso, o comando dsh estará disponível em qualquer diretório. A atualização é realizada da maneira usual:

npm install -g @deepseek-ai/dsh@latest

Aplicativo de desktop

Para aqueles que não querem manter um terminal e Node.js, DeepSeek lança versões para desktop. Eles estão disponíveis na página oficial de download:

  • macOS – Apple Silicon, macOS 13 ou posterior, formato DMG.
  • Windows – assembly de 64 bits, formato EXE.

O aplicativo funciona com os mesmos arquivos locais, pode realizar tarefas em segundo plano e armazenar sessões da mesma forma que a versão web. Esta é uma opção conveniente para o trabalho diário, quando você não deseja acionar o servidor manualmente todas as vezes.

Construindo a partir de fontes

Se você precisar de controle total sobre o código, seus próprios patches ou desenvolvimento de plugins, o projeto é coletado do repositório. Você precisará do pnpm, e o repositório corrige uma versão específica, então você deve primeiro habilitar o Corepack:

corepack enable
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

O comando pnpm run build prepara pacotes e artefatos de frontend, e pnpm dsh web executa a versão já compilada sem reconstruir. Para desenvolvimento, existe um modo pnpm run dev:web: ele constrói, inicia o servidor e reconstrói pacotes de clientes quando as fontes mudam.

Primeiro lançamento

Após iniciar a interface web, o procedimento é o seguinte.

Primeiro, abra Configurações → Modelos e insira a chave da API DeepSeek. A chave é salva no arquivo $DSH_HOME/.credentials.yaml, e apenas um link para ela permanece nas configurações. A página de configurações recebe uma descrição já mascarada do segredo, portanto é impossível ler a chave de volta na interface. As alterações de modelo são aplicadas a partir da próxima solicitação; não há necessidade de reiniciar o servidor.

Em seguida, selecione sua pasta de trabalho em Escolher espaço de trabalho. Enquanto o espaço de trabalho não estiver selecionado, o campo de entrada da tarefa permanecerá esmaecido. Isso é feito intencionalmente: o agente deve compreender os limites dentro dos quais pode ler e alterar arquivos.

Depois disso, você pode enviar a primeira tarefa. Por exemplo:

Summarize this repository and identify its main packages.

O agente irá ler o projeto, traçar um plano, chamar as ferramentas necessárias e mostrar o resultado. Para operações que requerem confirmação com base na política de acesso atual, o dsh perguntará antes de executar.

Modelos e provedores

O DeepSeek se conecta em uma única etapa: o cartão do provedor nas configurações contém apenas um campo para a chave API. Além disso, você pode adicionar serviços de terceiros. O diretório integrado conhece identificadores como antrópico, openai, moonshotai para Kimi e zai para GLM.

Para seu próprio gateway, proxy corporativo ou servidor local, existe um modo API de modelo personalizado. Ele pergunta:

  • identificador permanente do provedor;
  • nome de exibição;
  • Endereço base da API;
  • protocolo: conclusões de bate-papo OpenAI, respostas OpenAI ou mensagens antrópicas;
  • chave e lista de modelos.

O protocolo é importante: um provedor fala um protocolo. Se um gateway suportar OpenAI e Anthropic, ele deverá ser descrito por dois provedores. Para modelos, você pode especificar o tamanho da janela de contexto, o número máximo de tokens de saída e os tipos de dados de entrada suportados, incluindo imagens.

Os modelos DeepSeek têm níveis de raciocínio desativado, baixo, alto e máximo. O nível é selecionado no menu Esforço próximo ao modelo. Para tarefas rotineiras no repositório, um modelo rápido é suficiente, mas para tarefas arquitetônicas complexas faz sentido aumentar o esforço ou adotar um modelo de classe superior.

Plugins e modo Criador

Plugins são o principal recurso do DeepSeek Harness. Através deles, são adicionadas ferramentas, habilidades, elementos de interface e aplicações inteiras. A interface possui um gerenciador de plugins com conjuntos oficiais e experimentais: comandos de agente, confirmação automática, tarefas agendadas, entrada de voz, terminal, subagentes.

O modo Criador se destaca separadamente. Neste modo, você pode pedir ao agente para escrever um plugin diretamente no chat. Ele fará o download da habilidade de desenvolvimento do plugin Cordis, criará uma estrutura de pacote, escreverá o código, instalará o plugin e verificará seu status. Há um exemplo na página oficial do projeto onde um temporizador Pomodoro flutuante é montado desta forma.

Plugins também podem ser instalados a partir da linha de comando. Para um perfil da web, o comando é semelhante a este:

dsh plugin --profile web add some-dsh-plugin

Pacotes Npm, links como github:owner/repo, diretórios locais e arquivos tgz são suportados. Após a instalação, é útil verificar se a camada do plugin está realmente incluída na configuração:

dsh --profile web --dump-config

O comando imprime a árvore de plugins montada sem iniciar o servidor. Se não houver nenhuma nova camada, o pacote provavelmente não declarou um manifesto dsh.bundle e foi instalado como uma biblioteca regular, e não como um plugin incluído.

As configurações experimentais incluem Mercados de plug-ins personalizados. Este é um arquivo JSON de índice com uma lista de plugins, suas versões, ícones e fontes. Ao ativar o conjunto, você obtém uma guia Discover na página de plug-ins e a capacidade de conectar mercados de terceiros. Como qualquer fonte de terceiros, tal mercado só deve ser adicionado se você confiar em seus autores.

Trajetória e auditoria

Para cada sessão, o dsh grava um log de eventos somente anexado – Trajetória. Ele armazena o prompt do sistema, o raciocínio, as chamadas de ferramentas e seus resultados, o agendamento de subagentes e as inserções de contexto. A retomada da sessão, bifurcações, pesquisa e reprodução são construídas neste log.

O benefício prático é que a conversa deixa de ser uma caixa preta. Na interface, você pode abrir a trajetória e ver quais ferramentas foram chamadas, quanto tempo durou cada etapa, quais arquivos foram alterados e quantos tokens foram gastos na solicitação. Se um agente se comportou de forma estranha, o motivo geralmente fica visível aqui, e não em uma resposta curta no chat.

As sessões estão localizadas em ~/.dsh/sessions na forma de logs JSONL. Você pode lê-los, pesquisá-los e construir suas próprias análises. Isso também torna possível calcular com precisão despesas e ocorrências de cache que não são visíveis em uma fatura normal de API.

Tarefas e programações em segundo plano

DeepSeek Harness pode funcionar não apenas no modo “perguntar e receber uma resposta”. As tarefas podem ser iniciadas em segundo plano e agendadas. Por exemplo, peça ao agente para coletar um relatório semanal das notas do projeto todas as sextas-feiras às 17h. Na interface, tais tarefas são visíveis separadamente: você pode verificar o status, visualizar o histórico e abrir detalhes de execução.

Existe um perfil sem cabeça para automação. Inicia uma sessão, imprime a resposta final e sai:

dsh --profile headless "run the tests"

Este modo é conveniente para CI, cron e scripts onde uma interface web não é necessária. Além do headless, estão disponíveis os perfis sdk e acp: o primeiro atende clientes SDK via JSON-RPC, o segundo atende clientes de automação via ACP stdio.

Subagentes, MCPs e habilidades

Uma tarefa complexa pode ser decomposta entre subagentes. O agente principal planeja o trabalho e os subagentes individuais trabalham em suas áreas. Isso ajuda a manter o contexto compacto e a não arrastar todo o histórico para cada solicitação.

Ferramentas externas e fontes de dados são conectadas via MCP. A documentação inclui um guia separado para memória MCP, bem como integrações como sessões de revisão do GitHub. As habilidades descrevem procedimentos repetíveis que o agente carrega conforme necessário, em vez de manter todas as instruções em um prompt do sistema o tempo todo.

Perfis, pacotes e patches

A configuração dsh é montada a partir de três camadas. Bundle é um conjunto de linhas de configuração e código de plugin, ou seja, uma funcionalidade pronta. Perfil é uma composição nomeada de pacotes configuráveis, que é armazenada em $DSH_HOME/profiles/<name>. Patch é um arquivo YAML que altera linhas já carregadas por identificador, desativa-as ou adiciona novas.

A ordem de aplicação é a seguinte: primeiro os pacotes na ordem do perfil, depois o patch do perfil, depois o patch geral $DSH_HOME/cordis.patch.yml e no final as sobreposições transmitidas via –patch. Isso significa que quase qualquer configuração pode ser substituída sem tocar nas fontes do pacote. Você pode visualizar a árvore resultante com o comando:

dsh --profile web --dump-config

Um perfil da web padrão é chamado de web, um perfil sem servidor é chamado de headless. Seus arquivos de configuração ficam em $DSH_HOME/profiles/web/cordis.patch.yml e $DSH_HOME/profiles/headless/cordis.patch.yml. É aqui que o dsh grava as alterações feitas na interface de configurações.

SDK para Python

Existe um SDK oficial para projetos Python. Ele é instalado em um ambiente virtual e traz consigo um runtime nativo, portanto o sistema Node.js não é necessário para o funcionamento normal:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install deepseek-harness-sdk

Um exemplo de inicialização mínima é assim:

from pathlib import Path

from deepseek_harness import DeepSeekHarness

workspace = Path("C:/work/disposable-workspace").resolve()
dsh_home = Path("C:/work/example-dsh-home").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

O SDK inicia o processo dsh empacotado com o perfil sdk-minimal e o reutiliza antes de sair do gerenciador de contexto. O perfil mínimo é intencionalmente limitado: possui bash ou pwsh, leitura de imagens e um diretório de trabalho, mas não possui ferramentas da web, subagentes ou algumas das ferramentas de arquivo. Para tarefas únicas, isso é uma vantagem: há menos superfície para controlar.

No que prestar atenção

DeepSeek Harness é uma prévia do desenvolvedor versão 0.1.0-rc.x. O README avisa explicitamente que a compatibilidade será interrompida. Para experimentos, projetos pessoais e automação, tudo bem, mas para um processo que dá dinheiro agora, vale a pena pesar o risco e manter um plano de backup.

O segundo ponto é o Node.js. Se você tiver 22.18 ou 23.x, a instalação irá travar ou se comportar de maneira imprevisível. Verifique a versão com antecedência: o projeto usa node:sqlite e o apagamento integrado do TypeScript de tipos que precisam de uma nova ramificação.

O terceiro ponto é a sandbox e os direitos. Por padrão, o agente opera em uma política próxima à gravação no espaço de trabalho: ele pode alterar arquivos na pasta selecionada e operações potencialmente perigosas exigem confirmação. O modo de acesso total ao perigo oferece mais liberdade, mas o risco aumenta. Antes de experimentar um repositório real, é útil fazer um commit ou backup.

O quarto ponto é o custo. O DSH em si é gratuito, mas para inferência você paga ao provedor em tokens. Para sessões longas, o cache de prefixo é importante: o dsh compõe as solicitações para que o histórico e os esquemas da ferramenta permaneçam inalterados pelo maior tempo possível. Se a pontuação for maior do que o esperado, observe não apenas o preço por token, mas também a parcela dos acertos em dinheiro na trajetória.

Vale a pena tentar

DeepSeek Harness é de interesse principalmente para aqueles que desejam não apenas “outro bate-papo com uma modelo”, mas um ambiente controlado para agentes. Há uma trajetória transparente, trabalho normal com arquivos e comandos, tarefas em segundo plano, subagentes e expansão verdadeiramente profunda por meio de plugins. A capacidade de substituir um loop de agente pelo seu próprio é rara e potencialmente muito útil para pesquisa e orquestração personalizada.

Se você precisa de uma ferramenta estável para o trabalho diário remunerado, agora é mais sensato tratar o dsh como um segundo agente ao lado do principal: experimente em um projeto pessoal, compare o custo e a qualidade de suas tarefas e só então transfira-o para o fluxo de trabalho.

Links

https://www.deepseek.com/harness/
https://www.deepseek.com/download/
https://github.com/deepseek-ai/deepseek-harness
https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
https://deepseek-harness.github.io/deepseek-harness/en/guide/providers
https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk
https://platform.deepseek.com/

Fontes

https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md
https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.md
https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
https://deepseek-harness.github.io/deepseek-harness/en/guide/providers
https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk
https://deepseek-harness.github.io/deepseek-harness/en/guide/plugin-market
https://dshdocs.com/getting-started/installation/
https://dshdocs.com/concepts/profiles-bundles-patches/
https://dshdocs.com/guides/dsh-vs-claude-code/