Visão Geral do DeepSeek Harness

O DeepSeek Harness (invocado via comando dsh) é um framework de agentes de inteligência artificial de código aberto, estruturado em torno de uma arquitetura onde "tudo é um plugin". O núcleo do sistema é impulsionado pelo Cordis. O repositório é organizado como um monorepo gerenciado pelo pnpm, contendo centenas de workspaces que abrangem desde a CLI e frontend web até SDKs, sandboxes, clientes MCP e múltiplos backends de LLM. A stack tecnológica baseia-se em Node 22, TypeScript 6, tsdown/rolldown para empacotamento e Vitest para testes.

Configuração do Ambiente

O arquivo de configuração do projeto define restrições rígidas para as engines. Abaixo está a representação dos requisitos de versão:

{
  "runtime_requirements": {
    "node": "^22.19.0 || >=24.0.0"
  },
  "package_manager": "pnpm@11.7.0"
}

A compatibilidade exata entre Node e pnpm é obrigatória para evitar falhas de resolução de dependências. O quadro a seguir detalha a validação do ambiente local:

Clonagem e Instalação de Dependências

O processo inicial de obtenção do código-fonte e instalação dos pacotes é realizado através dos seguintes comandos:

git clone https://atomgit.com/gh_mirrors/de/deepseek-harness.git
cd deepseek-harness
pnpm install

Durante a instalação, que processa centenas de pacotes, alguns avisos não fatais podem aparecer, como a omissão do pacote landlock-run em ambientes Windows e a presença de dependências circulares nos workspaces. O script de pós-instalação do node-pty copiará automaticamente as DLLs necessárias para o suporte a PTY no Windows, não exigindo intervenção manual.

Desafios no Processo de Build

A etapa de compilação é a mais propensa a erros, especialmente em sistemas Windows. Abaixo estão as falhas mais comuns e suas respectivas correções.

Falha 1: Corrupção do Estado de Compilação Incremental

A execução direta do comando de build pode falhar com erros de construtor indefinido. Isso ocorre devido à corrupção dos arquivos de estado .tsbuildinfo, resultando em artefatos ausentes. A solução é forçar a limpeza do cache antes de compilar:

pnpm run clean

Falha 2: Erros Intrínsecos do npx/npm

Tentar iniciar o projeto via npx pode gerar exceções relacionadas a herança de classes no próprio npm. Para contornar isso, deve-se utilizar exclusivamente o ecossistema do pnpm para executar os binários:

pnpm exec dsh web

Falha 3: Dependência de Tipos entre Host e Client

A compilação do client falhará com dezenas de erros de tipo se executada antes do host. O client depende de um registro de tipos gerado dinamicamente pelo plugin dsh-typert-generator, que só é processado durante a fase de empacotamento do host. Portanto, a ordem de execução é crítica.

Fluxo de Compilação Otimizado

Para garantir a integridade dos artefatos, o processo de build deve seguir uma sequência estrita. O script abaixo encapsula a lógica correta:

#!/usr/bin/env bash
set -e

# 1. Limpeza de artefatos anteriores
pnpm run clean

# 2. Fase do Host: Compilação de tipos e empacotamento
pnpm exec tsc -b tsconfig.host.json
pnpm exec tsdown --env.DSH_BUILD_FACE=host

# 3. Fase do Client: Consome o registro typert gerado na fase anterior
pnpm exec tsc -b tsconfig.client.json
pnpm exec tsdown --env.DSH_BUILD_FACE=client

# 4. Empacotamento do Frontend (Vite)
pnpm run build:web

O tempo de execução e os artefatos gerados em cada etapa são detalhados a seguir:

Execução do Servidor Web

Após a conclusão bem-sucedida do build, a interface web pode ser iniciada utilizando o comando abaixo. O parâmetro --no-open é recomendado para ambientes remotos ou SSH, evitando a tentativa de abertura automática do navegador local:

pnpm dsh web --no-open

O servidor ficará disponível no endereço http://127.0.0.1:3080.

Destaques da Arquitetura e Limitações

A arquitetura do framework se baseia na composição espacial e temporal do Cordis, onde o app-boot utiliza mountRootInclude para montar todos os plugins em uma árvore unificada. O registro de tipos typert atua como o枢纽 (ponto central), permitindo que o client acesse remotamente todas as capacidades expostas pelo host de maneira tipada.

Entre as limitações atuais da versão de desenvolvedor, destacam-se a instabilidade na compilação nativa em Windows, a ausência de documentação detalhada fora do diretório docs/, e o tamanho considerável dos bundles de frontend, que incluem chunks de vendor e pacotes de linguagem que podem impactar o tempo de carregamento inicial. Para testes rápidos sem a necessidade de compilação local, a utilização de pacotes pré-compilados via npx @deepseek-ai/dsh web permanece como a alternativa mais viável, desde que o ambiente não apresente as incompatibilidades de engine mencionadas.