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/
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/
Leave a Reply