A DeepSeek voltou a surpreender o mundo da IA open source. A 13 de agosto de 2026, a empresa chinesa publicou o repositório deepseek-harness no GitHub, uma ferramenta que promete fazer pelo desenvolvimento agêntico o que o DeepSeek V3 fez pelos modelos de linguagem em 2025: abrir código que só as grandes tecnológicas tinham. O projeto já soma 239.903 estrelas e 28.807 forks no GitHub (dados verificados a 29 de setembro de 2026), um crescimento raro para uma ferramenta ainda em pré-visualização de programador. Este tutorial mostra, passo a passo, como instalar o DeepSeek Harness, ligá-lo à API da DeepSeek e criar o primeiro agente capaz de ler código, correr comandos e propor correções num projeto real.
Quem trabalha com programação assistida por IA já conhece o Claude Code da Anthropic e ferramentas de terminal como o opencode. O que muda com o Harness é a proposta de licença: todo o código está disponível sob MIT, o que permite ler, alterar e redistribuir o projeto sem pedir autorização a ninguém. Ao longo deste guia vamos instalar o Harness a partir do código-fonte, configurar a autenticação com a API da DeepSeek, arrancar a interface Web local e usar o agente para diagnosticar e corrigir um erro real num pequeno projeto Node.js. No final, vai ter um ambiente de trabalho completo, pronto para experimentar com projetos maiores.
O que é o DeepSeek Harness e porque está a gerar tanto interesse
O DeepSeek Harness (identificado pelo comando dsh) é um framework open source para construir agentes de IA capazes de operar sobre código, terminais e ferramentas externas. A própria página oficial do projeto descreve-o como uma alternativa aberta ao Claude Code da Anthropic, distribuída sob licença MIT. Ao contrário de um chatbot comum, o Harness não se limita a responder perguntas: liga um modelo de linguagem a um ambiente de desenvolvimento real, onde pode inspecionar ficheiros, executar testes e alterar código com supervisão do utilizador.
A arquitetura chama-se “tudo é um plugin” (everything is a plugin) e assenta num motor interno chamado Cordis, responsável por montar, desmontar e gerir as dependências entre módulos. Modelos, ferramentas, competências, sessões, sandboxes, armazenamento, ciclos de execução e até a interface gráfica são todos plugins que podem ser trocados ou recompostos. Esta escolha de desenho explica porque o Harness já suporta múltiplos modelos, incluindo o adaptador para o DeepSeek-V4.1-Flash, com suporte a texto, imagem e atualização de instruções de sistema dentro do histórico da conversa.
O desenho do Cordis segue um artigo técnico interno intitulado “A Programming Paradigm for Spatiotemporal Composability”, referenciado diretamente na documentação do repositório. Sem entrar em detalhes académicos, a ideia prática para quem só quer usar a ferramenta é esta: os plugins não só se combinam no espaço (que funcionalidades estão ativas numa sessão) como também no tempo (que eventos disparam que ações, e em que ordem). É essa camada que permite, por exemplo, que um plugin de webhook do GitHub acorde o agente quando uma issue é aberta, sem que isso exija alterar o núcleo do programa.
Vale referir que o projeto está oficialmente em developer preview. A versão inicial, v0.1, foi lançada em agosto e evoluiu rapidamente: em 29 de setembro de 2026 a etiqueta mais recente no GitHub era v0.2.0-rc.2, o que confirma um ritmo de lançamentos quase diário. O próprio repositório avisa que vão existir mudanças que quebram compatibilidade, por isso este guia trata o Harness como uma ferramenta de experimentação e não como algo para produção crítica sem testes prévios.
O contexto: a corrida aos agentes de código abertos em 2026
O lançamento do Harness não aconteceu isolado. Nas semanas à volta de agosto de 2026, várias empresas chinesas de IA publicaram ferramentas e modelos abertos a um ritmo pouco visto antes. A Alibaba abriu os pesos do Qwen3.8-Max, um modelo de 2,4 biliões de parâmetros, enquanto a Zhipu AI lançou o GLM-5.3 com foco em programação. A @radixark, fundada por veteranos de infraestrutura de IA vindos da xAI e da Nvidia, publicou o Miles v0.1 a 28 de agosto, um framework aberto de reforço e pós-treino compatível com modelos Kimi, DeepSeek, Qwen e MiniMax. Do lado das ferramentas de terminal, o opencode consolidou-se como agente de código open source escrito em TypeScript.
Neste cenário, o Harness posiciona a DeepSeek não só como fornecedora de modelos, mas também como fornecedora da camada que liga esses modelos a tarefas reais de programação. É uma aposta parecida à que a Anthropic fez com o Claude Code, mas com a diferença de abrir o código completo da ferramenta em vez de manter o produto fechado. Para equipas de engenharia em Portugal que já usam modelos DeepSeek via API por custo, o Harness oferece agora uma camada de agente pronta a testar sem depender de um produto comercial fechado.
Pré-requisitos: o que precisa de instalar antes de começar
Antes de avançar para os passos práticos, confirme que tem estas versões instaladas. Os requisitos de Node.js vêm diretamente do ficheiro package.json do repositório oficial, e o gestor de pacotes usado pelo projeto é o pnpm, não o npm nem o yarn.
| Requisito | Versão mínima | Como verificar |
|---|---|---|
| Node.js | ^22.19.0 ou >=24.0.0 | node -v |
| pnpm | 11.7.0 (packageManager do projeto) | pnpm -v |
| Git | Qualquer versão recente | git --version |
| Chave API DeepSeek | Conta ativa na plataforma DeepSeek | Painel da conta DeepSeek |
| Sistema operativo | Linux, macOS ou Windows com WSL2 | – |
Se tiver uma versão de Node.js mais antiga, o passo de compilação vai falhar com erros de sintaxe ou dependências incompatíveis. Recomenda-se instalar o Node através do site oficial ou de um gestor de versões como o nvm ou o fnm, que facilita alternar entre projetos com requisitos diferentes. Para o pnpm, siga o guia oficial de instalação.
Passo 1: Preparar a pasta de trabalho e verificar as versões
Comece por criar uma pasta dedicada para este teste, separada dos seus projetos de produção. Isto é importante porque o agente vai correr comandos no seu sistema, e mantê-lo isolado reduz o risco de alterações indesejadas noutros diretórios. Esta separação vale sobretudo na primeira experiência, antes de conhecer bem que permissões o agente pede e como reage a instruções ambíguas.
mkdir ~/deepseek-harness-lab
cd ~/deepseek-harness-lab
node -v
pnpm -v
git --versionResultado esperado: os três comandos devem devolver números de versão, sem erros do tipo “command not found”. Se o pnpm -v falhar, instale-o com npm install -g pnpm antes de continuar. Confirmar isto agora evita perder tempo a diagnosticar erros de compilação mais à frente.
Passo 2: Clonar o repositório oficial do DeepSeek Harness
O código-fonte está alojado em github.com/deepseek-ai/deepseek-harness, sob a organização oficial deepseek-ai no GitHub, a mesma que publica os modelos da família DeepSeek. Clone-o para a pasta que acabou de criar:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harnessO clone deve trazer várias pastas, incluindo packages/, docs/ e ficheiros como AGENTS.md e README.md. Se preferir testar sem clonar o repositório completo, a própria documentação também disponibiliza uma via mais rápida via npm, que se aborda no passo seguinte como alternativa.
Passo 3: Instalar as dependências com pnpm
Com o repositório clonado, instale as dependências do workspace. O projeto é escrito em TypeScript e organizado como um monorepo pnpm, com várias pastas dentro de packages/ a partilharem dependências comuns, por isso este passo pode demorar alguns minutos na primeira execução enquanto o pnpm resolve e faz cache de tudo.
pnpm installSe preferir não clonar o repositório e só quiser experimentar a interface rapidamente, a DeepSeek disponibiliza também uma via direta via npx, sem necessidade de compilar nada localmente:
npx @deepseek-ai/dsh webPara este tutorial, seguimos a via de código-fonte, porque permite explorar os plugins e a estrutura interna, algo que a via npx esconde.
Passo 4: Compilar o projeto e perceber a estrutura de pastas
Depois da instalação, compile o projeto. Este passo transforma o código TypeScript fonte em JavaScript executável e prepara os pacotes internos que o comando dsh vai usar em tempo de execução:
pnpm run buildEnquanto a compilação corre, vale a pena olhar para a estrutura do repositório. A pasta packages/ contém os plugins individuais (adaptadores de modelo, ferramentas, cliente web, integrações como webhooks do GitHub), enquanto docs/subsystems/ documenta conceitos centrais como o de “workspace”, a pasta de trabalho que o agente usa como raiz das suas operações. Perceber esta divisão ajuda mais tarde a saber onde procurar quando quiser adicionar ou desativar uma funcionalidade específica.
Repare também nos ficheiros AGENTS.md espalhados por várias subpastas do repositório, incluindo dentro de packages/client/. Estes ficheiros descrevem, em linguagem simples, o que cada módulo faz e como se espera que um agente (ou um novo colaborador humano) interaja com ele. É uma boa prática que vale a pena copiar para os seus próprios projetos, sobretudo se planeia deixar um agente de IA a trabalhar sobre o código no futuro.
Passo 5: Obter e configurar a chave da API DeepSeek
O Harness liga-se aos modelos DeepSeek através de um plugin de credenciais que lê, por defeito, a variável de ambiente DEEPSEEK_API_KEY. Depois de gerar a sua chave no painel da conta DeepSeek, defina-a na sessão do terminal ou, de forma mais persistente, num ficheiro .env na raiz do projeto.
# Opção 1: variável de ambiente na sessão atual
export DEEPSEEK_API_KEY="a_sua_chave_aqui"
# Opção 2: ficheiro .env na raiz do projeto
echo 'DEEPSEEK_API_KEY=a_sua_chave_aqui' >> .envSe preferir usar outra variável de ambiente, o plugin de credenciais aceita um parâmetro apiKeyEnv configurável, o que é útil se já tiver convenções de nomenclatura definidas noutros projetos da sua equipa. Nunca coloque a chave diretamente em código-fonte partilhado nem a faça commit para um repositório público, mesmo que seja um projeto de testes. Se acidentalmente publicar uma chave, revogue-a de imediato no painel da DeepSeek e gere uma nova antes de continuar este tutorial.
Passo 6: Arrancar a interface Web do dsh
Com a chave configurada, arranque a interface principal:
pnpm dsh webEste comando inicia a interface Web em http://127.0.0.1:3080 por defeito e abre-a automaticamente no navegador. Se estiver a correr o Harness numa máquina remota ou num contentor sem ambiente gráfico, adicione a opção --no-open para evitar que o comando tente abrir um browser inexistente:
pnpm dsh web --no-openResultado esperado no terminal: uma mensagem a confirmar que o servidor arrancou na porta 3080, seguida do endereço local para abrir manualmente caso a abertura automática não funcione. Se a porta 3080 já estiver ocupada por outro processo, o comando falha com um erro de “address already in use”, situação que se aborda mais à frente na secção de resolução de problemas.
Passo 7: Perceber a arquitetura “tudo é um plugin” com o Cordis
Antes de criar o primeiro agente, ajuda perceber como o Harness organiza as peças internamente. Segundo a conta oficial da DeepSeek, o Cordis é o núcleo (kernel) que trata da montagem, desmontagem e gestão de dependências entre plugins, enquanto serviços e eventos do próprio Cordis permitem que os plugins comuniquem entre si (fonte: anúncio oficial da DeepSeek). Isto significa, na prática, que cada peça do sistema, do modelo de linguagem à sandbox onde os comandos correm, é substituível sem reescrever o resto da aplicação.
O catálogo de configuração público do projeto lista, entre outros, os plugins @deepseek-ai/dsh-llm-deepseek-api-key (autenticação por chave), @deepseek-ai/dsh-llm-deepseek-account (autenticação por conta) e @deepseek-ai/dsh-agent-default-model, que define qual o modelo usado por defeito pelo agente. Cada plugin expõe os seus próprios parâmetros configuráveis em tempo real, o que a documentação designa por campos “Volatile”.
Para quem já usou o Claude Code ou o opencode, a diferença central está aqui: em vez de uma aplicação monolítica, o Harness assume desde o início que vai ser estendido, e por isso separa cada capacidade numa unidade que pode ser trocada por uma equivalente da comunidade.
Passo 8: Configurar o modelo por defeito do agente
O plugin dsh-agent-default-model controla qual o modelo que o agente usa quando nenhum outro é especificado numa sessão. Os três campos documentados são provider (a rota do fornecedor registado), model (o identificador do modelo pertencente a esse fornecedor) e, opcionalmente, reasoningEffort, um parâmetro específico do adaptador que controla o esforço de raciocínio do modelo.
{
"provider": "deepseek",
"model": "deepseek-flash",
"reasoningEffort": "medium"
}Este exemplo aponta para o adaptador deepseek-flash, que corresponde ao modelo DeepSeek-V4.1-Flash e já suporta texto, imagem e atualização de instruções de sistema dentro do histórico da conversa, segundo as notas de lançamento do repositório. Depois de guardar esta configuração através da interface de definições do dsh, reinicie a sessão do agente para que a alteração tenha efeito.
Passo 9: Criar o primeiro projeto de teste para o agente
Com o servidor a correr e o modelo configurado, crie uma pasta separada para servir de “workspace” ao agente, ou seja, a raiz onde ele vai poder ler e escrever ficheiros. Um projeto pequeno e descartável é ideal para esta primeira experiência.
mkdir ~/deepseek-harness-lab/projeto-teste
cd ~/deepseek-harness-lab/projeto-teste
git init
echo "console.log('ola mundo')" > app.js
git add . && git commit -m "commit inicial"Na interface Web do dsh, aponte uma nova sessão para esta pasta. O agente vai indexar os ficheiros existentes antes de aceitar a primeira instrução, o que permite que ele responda com contexto real sobre o código em vez de inventar suposições sobre a estrutura do projeto.
Passo 10: Dar ferramentas ao agente e limitar permissões
Como cada capacidade é um plugin, as ferramentas que o agente pode usar (ler ficheiros, escrever ficheiros, correr comandos de terminal, aceder à rede) também são ativadas ou desativadas individualmente. Antes de pedir qualquer tarefa real, reveja quais os plugins de ferramentas ativos na sua sessão e desligue os que não precisa, sobretudo acesso à rede e execução de comandos com privilégios elevados.
Para o projeto de teste deste tutorial, as únicas ferramentas realmente necessárias são leitura e escrita de ficheiros dentro do workspace, mais a capacidade de correr o comando node para validar o resultado. Não há motivo para ativar acesso à rede ou a outros diretórios do sistema numa experiência tão simples, e reduzir o número de plugins ativos também torna mais fácil perceber, depois, exatamente que ações o agente tomou durante a sessão.
Uma boa prática, sobretudo numa ferramenta ainda em pré-visualização, é exigir confirmação manual antes de qualquer comando com efeitos permanentes, como apagar ficheiros ou fazer push para um repositório remoto. Isto transforma o agente num assistente supervisionado em vez de um processo autónomo sem travões, o que reduz drasticamente o risco de uma instrução mal interpretada causar danos.
Passo 11: Executar a primeira tarefa real: corrigir um bug
Chegou o momento de testar o agente com uma tarefa concreta. Introduza um erro propositado no ficheiro app.js e peça ao agente para o identificar e corrigir:
echo "console.log('ola mundo'" > app.jsNa interface, escreva uma instrução simples como “o app.js está a dar erro de sintaxe quando corro node app.js, encontra e corrige o problema”. Um fluxo típico e esperado é: o agente lê o ficheiro, identifica o parêntesis em falta, propõe a alteração, pede confirmação (se tiver essa opção ativa) e só depois escreve o ficheiro corrigido.
Este exemplo é propositadamente simples, mas serve para validar todo o percurso configurado nos passos anteriores: autenticação com a API, leitura correta do workspace e execução de uma alteração de ficheiro com sucesso. Uma vez confirmado este fluxo básico, pode repetir o mesmo teste com erros mais complexos, como uma exceção não tratada num ficheiro com várias dependências internas, para perceber até que ponto o agente segue referências entre ficheiros antes de propor uma correção.
Resultado esperado depois da correção:
$ node app.js
ola mundoSe o resultado for este, o agente concluiu a tarefa com sucesso: leu o contexto, aplicou uma correção mínima e verificou o resultado antes de terminar.
Passo 12: Rever o histórico e exportar os resultados
Depois de cada sessão, vale a pena rever o registo de chamadas de ferramentas que o agente fez, não só por transparência mas também para detetar padrões, como tentativas repetidas de aceder a ficheiros fora do workspace. A interface Web mantém um histórico da sessão que pode ser consultado a qualquer momento. Este hábito é particularmente útil enquanto o projeto está em developer preview, porque permite comparar o comportamento do agente entre versões diferentes do Harness e perceber se uma atualização mudou a forma como ele interpreta as suas instruções.
Para automação e integração com scripts próprios, o projeto disponibiliza também um SDK em Python (deepseek-harness-sdk) que comunica com o Harness através de um subprocesso, usando JSON-RPC delimitado por quebras de linha na entrada e saída padrão. Isto é útil se quiser correr o agente como parte de um pipeline de integração contínua em vez de o operar manualmente pela interface.
Projeto completo: um agente funcional de ponta a ponta
Juntando os passos anteriores, este é o fluxo completo, do zero até ao primeiro agente a corrigir código, condensado num único bloco de comandos:
# 1. Preparar ambiente
mkdir ~/deepseek-harness-lab && cd ~/deepseek-harness-lab
# 2. Clonar e instalar
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
# 3. Configurar a chave da API
export DEEPSEEK_API_KEY="a_sua_chave_aqui"
# 4. Arrancar a interface
pnpm dsh web --no-open
# abrir manualmente http://127.0.0.1:3080
# 5. Num terminal separado, criar o projeto de teste
mkdir ~/deepseek-harness-lab/projeto-teste
cd ~/deepseek-harness-lab/projeto-teste
git init
echo "console.log('ola mundo')" > app.js
git add . && git commit -m "commit inicial"
# 6. Na interface: apontar sessão para esta pasta,
# configurar provider=deepseek, model=deepseek-flash,
# e pedir ao agente para corrigir bugs introduzidos manualmenteNo final deste fluxo tem um agente a correr localmente, ligado a um modelo DeepSeek real, capaz de ler o seu código, propor alterações e executá-las com a sua supervisão. É a base sobre a qual pode depois adicionar plugins próprios, como integrações com o seu sistema de tickets ou com o pipeline de testes da sua equipa.
Casos de uso práticos para o DeepSeek Harness
Depois de correr o exemplo simples deste tutorial, a pergunta natural é onde o Harness pode encaixar num fluxo de trabalho real. Um uso direto é a triagem de bugs reportados por utilizadores: em vez de um programador abrir manualmente cada ficheiro suspeito, o agente pode receber a descrição do erro, localizar a origem no código e propor uma correção candidata para revisão humana. Outro caso comum é a geração de testes para código já existente mas sem cobertura, uma tarefa repetitiva onde o agente ganha tempo ao programador sem exigir supervisão constante.
Equipas com bases de código antigas também podem usar o Harness para tarefas de documentação, pedindo ao agente para ler módulos pouco documentados e propor explicações em ficheiros README ou comentários. Como a arquitetura de plugins permite integrar webhooks, como o já existente para o GitHub, é possível imaginar fluxos onde o agente reage automaticamente à abertura de uma issue e prepara um primeiro diagnóstico antes de um humano intervir. Dado o estado de developer preview, o conselho mais sensato continua a ser correr estes fluxos em paralelo com o processo normal da equipa, nunca substituindo por completo a revisão humana enquanto o projeto amadurece.
Erros comuns ao instalar e configurar o DeepSeek Harness
Estes são os problemas que mais frequentemente atrapalham quem experimenta o Harness pela primeira vez. A maioria não é exclusiva desta ferramenta, mas surge com mais frequência aqui por ser um projeto novo, com documentação ainda em crescimento e um público que muitas vezes está também a instalar pnpm ou a atualizar o Node.js pela primeira vez.
- Usar npm ou yarn em vez de pnpm: o projeto é um monorepo pnpm e o
package.jsondefinepackageManager: [email protected]. Instalar com npm costuma gerar conflitos de dependências difíceis de depurar. - Versão de Node.js desatualizada: o requisito é Node ^22.19.0 ou >=24.0.0. Versões anteriores falham silenciosamente ou geram erros obscuros durante o
pnpm run build. - Esquecer de definir a variável DEEPSEEK_API_KEY: sem a chave, a sessão arranca mas qualquer pedido ao modelo falha com erro de autenticação.
- Dar acesso total ao terminal sem supervisão: numa ferramenta em pré-visualização, deixar o agente correr comandos sem confirmação pode causar alterações indesejadas em ficheiros fora do workspace pretendido.
- Testar diretamente num repositório de produção: dado o aviso oficial de que vão existir mudanças que quebram compatibilidade, comece sempre por um projeto descartável, como fizemos neste tutorial.
- Ignorar a porta ocupada: se já tiver outro serviço na porta 3080, o
pnpm dsh webfalha e é preciso libertar a porta ou configurar outra.
Resolução de problemas: situações frequentes
Esta tabela resume os problemas mais comuns reportados por quem instala o Harness pela primeira vez e a forma prática de os resolver.
| Problema | Causa provável | Solução |
|---|---|---|
| Erro “command not found: pnpm” | pnpm não instalado globalmente | Correr npm install -g pnpm e confirmar com pnpm -v |
Falha no pnpm run build | Versão de Node.js abaixo do mínimo exigido | Atualizar para Node ^22.19.0 ou >=24.0.0 com nvm ou fnm |
| Erro de autenticação ao chamar o modelo | Variável DEEPSEEK_API_KEY não definida ou chave inválida | Confirmar a chave no painel DeepSeek e reexportar a variável |
| “address already in use” na porta 3080 | Outro processo já usa essa porta | Libertar a porta ou definir outra na configuração do dsh |
| Browser não abre automaticamente | Ambiente sem interface gráfica (servidor remoto, contentor) | Usar pnpm dsh web --no-open e aceder manualmente ao endereço |
| Agente não vê ficheiros do projeto | Sessão não foi apontada para o workspace correto | Reabrir a sessão e selecionar explicitamente a pasta do projeto |
| Instalação muito lenta | Cache do pnpm vazia na primeira instalação do monorepo | Aguardar a primeira execução, as instalações seguintes são mais rápidas |
| Plugin de ferramentas não aparece na interface | Plugin não montado pelo Cordis nesta sessão | Verificar o catálogo de configuração e ativar o plugin em falta |
Dicas avançadas para usar o DeepSeek Harness em produção
Depois de dominar o fluxo básico, há formas de tornar o Harness mais útil no dia a dia. A primeira é isolar cada sessão do agente num contentor ou máquina virtual descartável, sobretudo quando lhe dá acesso a comandos de terminal: isto limita o raio de ação de qualquer erro, seja do modelo, seja de uma instrução mal escrita.
A segunda é explorar o SDK em Python para automatizar tarefas repetitivas, como pedir ao agente para rever pull requests recém-abertos antes de um humano olhar para eles, usando o protocolo JSON-RPC documentado no SDK. A terceira é acompanhar de perto as notas de lançamento no GitHub: dado o ritmo de atualizações (da v0.1 em agosto à v0.2.0-rc.2 a 29 de setembro), a interface de configuração e os nomes de plugins podem mudar de uma semana para a outra.
Por fim, use o reasoningEffort do adaptador com critério. Um valor mais alto tende a produzir respostas mais cuidadosas em tarefas de depuração complexas, mas também aumenta o tempo e o custo de cada pedido à API, algo a considerar se estiver a correr o agente em lote sobre muitos ficheiros.
Outra dica prática é manter um segundo terminal aberto apenas para observar os logs do processo pnpm dsh web enquanto testa o agente pela interface gráfica. Isto ajuda a perceber rapidamente se um erro vem do lado do modelo (respostas mal formatadas, tempo limite excedido) ou do lado dos plugins locais (falha ao montar um módulo, permissão de ficheiro em falta), o que acelera muito a depuração numa ferramenta ainda em fase inicial.
DeepSeek Harness vs Claude Code vs opencode: como se comparam
O Harness entra num mercado já com alternativas conhecidas. A tabela seguinte resume as diferenças mais relevantes para quem está a escolher entre estas três opções de agente de código.
| Característica | DeepSeek Harness | Claude Code | opencode |
|---|---|---|---|
| Licença | MIT (open source) | Proprietário | Open source |
| Linguagem do projeto | TypeScript | Fechado | TypeScript |
| Arquitetura | Plugins sobre o motor Cordis | Integrado, não modular publicamente | Agente de terminal |
| Modelo por defeito | Modelos DeepSeek (ex.: DeepSeek-V4.1-Flash) | Modelos Claude da Anthropic | Configurável por fornecedor |
| Estado | Developer preview (v0.2.0-rc.2) | Produto estável | Open source ativo |
| Interface principal | Interface Web local | Terminal e IDE | Terminal |
A principal vantagem do Harness sobre as alternativas fechadas está na possibilidade de auditar o código-fonte e substituir qualquer componente por um equivalente próprio, algo que a arquitetura de plugins facilita diretamente. A desvantagem é a maturidade: sendo um projeto de poucas semanas em pré-visualização, ainda não tem o histórico de estabilidade de ferramentas já consolidadas no mercado. Para uma equipa que já depende de modelos DeepSeek pelo custo mais baixo face a concorrentes ocidentais, o Harness reduz a fricção de testar um fluxo de agente sem assinar outro serviço comercial, mas isso não elimina a necessidade de validar cuidadosamente cada resultado antes de o aceitar num projeto real.
Segurança: o que ter em conta antes de dar acesso ao terminal
Dar a um agente de IA acesso a um terminal e a um repositório de código levanta questões de segurança que vão além dos bugs comuns de instalação. O primeiro risco é a execução de comandos destrutivos por interpretação errada de uma instrução ambígua, por exemplo um pedido para “limpar ficheiros temporários” que o modelo interpreta de forma mais larga do que o utilizador pretendia. O segundo é a exposição de segredos: se o workspace do agente incluir ficheiros .env ou chaves privadas, um modelo mal configurado pode acabar por os expor numa resposta ou num log.
Um terceiro risco, mais subtil, é a injeção de instruções através de conteúdo externo: se o agente lê ficheiros, páginas web ou respostas de APIs que contenham texto desenhado para manipular o modelo, pode acabar por executar ações não autorizadas pelo utilizador. Por isso, este tutorial recomenda três práticas mínimas: correr o Harness num ambiente isolado (contentor ou máquina virtual descartável), nunca apontar a primeira sessão de testes para um repositório com credenciais reais, e manter a confirmação manual ativa para qualquer comando que escreva, apague ou envie dados para fora do workspace. Estas práticas aplicam-se a qualquer agente de código com acesso a ferramentas, não apenas ao Harness, mas ganham peso extra numa ferramenta que ainda está em developer preview e onde a superfície de plugins muda de versão para versão.
Vale ainda registar que o repositório trata os plugins de webhook, como o de integração com o GitHub, com especial cuidado, porque um webhook mal configurado pode transformar um evento externo (uma issue aberta por qualquer pessoa) num gatilho direto para o agente correr ações no seu workspace. Antes de ativar qualquer plugin deste tipo, confirme quem pode disparar o evento e limite o acesso a repositórios e colaboradores de confiança.
Perguntas frequentes sobre o DeepSeek Harness
O DeepSeek Harness é gratuito?
O próprio software é gratuito e open source, sob licença MIT. O que tem custo é o uso da API da DeepSeek para os pedidos que o agente faz ao modelo, faturado de acordo com os preços da plataforma DeepSeek.
Preciso de saber TypeScript para usar o Harness?
Não para o uso básico descrito neste tutorial, que passa por comandos de terminal e pela interface Web. Só precisa de conhecimentos de TypeScript se quiser escrever plugins próprios ou contribuir diretamente para o repositório.
O Harness funciona com outros modelos além dos da DeepSeek?
A arquitetura de plugins foi desenhada para suportar múltiplos adaptadores de modelo, com o Cordis a tratar cada modelo como um plugin substituível. No entanto, este tutorial cobre apenas os adaptadores oficiais DeepSeek verificados no repositório, que são os documentados e suportados oficialmente à data de publicação.
É seguro dar acesso ao terminal ao agente?
Só com supervisão. Recomenda-se testar sempre num projeto isolado, com confirmação manual ativada para comandos com efeitos permanentes, e nunca dar ao agente acesso direto a credenciais de produção ou a repositórios sensíveis enquanto o projeto estiver em developer preview.
Porque é que o comando pnpm dsh web falha com erro de porta?
Porque outro processo já está a usar a porta 3080, a porta por defeito da interface. Feche esse processo ou configure o Harness para usar outra porta antes de arrancar novamente o servidor.
Qual a diferença entre instalar via npx e via clone do repositório?
O comando npx @deepseek-ai/dsh web descarrega e corre a interface rapidamente, sem expor a estrutura interna do projeto. Clonar o repositório e compilar localmente, como fizemos neste tutorial, dá acesso ao código-fonte dos plugins e é o caminho recomendado para quem quer perceber ou estender a arquitetura.
O DeepSeek Harness substitui o Claude Code?
Para experimentação e para equipas que valorizam código aberto e auditável, sim, é uma alternativa direta. Para uso em produção crítica, o Claude Code tem a vantagem de ser um produto estável há mais tempo, enquanto o Harness ainda está oficialmente em developer preview e sujeito a mudanças que quebram compatibilidade.
Posso correr o DeepSeek Harness dentro de um contentor Docker?
Sim, e é a abordagem recomendada para quem quer dar ao agente acesso ao terminal sem arriscar o sistema principal. Como o Harness só precisa de Node.js, pnpm e acesso de rede à API da DeepSeek, os passos de instalação deste tutorial funcionam da mesma forma dentro de uma imagem Docker baseada numa distribuição Linux recente com Node ^22.19.0 ou superior.
O que acontece se eu não definir o reasoningEffort no modelo?
O campo é opcional segundo o catálogo de configuração do projeto, o que significa que o adaptador do modelo aplica o comportamento por defeito caso o parâmetro fique em branco. Para a maioria das tarefas de teste, como a deste tutorial, não é necessário defini-lo explicitamente.
