DeepSeek Harness: Instalação e Inicialização

Q: Posso executar o DSH no Docker?

Sim. DSH fornece uma imagem Docker oficial: docker run -p 3080:3080 -e DEEPSEEK_API_KEY=sk-xxx deepseek/dsh:latest .

Q: Quais são os problemas conhecidos em ambientes Windows nativos?

Problemas de separador de caminho ( \ vs / ) podem causar mau funcionamento de algumas ferramentas. Recomendamos usar WSL2 para executar o DSH para a melhor experiência.

Q: Como posso ver os logs detalhados de inicialização do DSH?

Configure a variável de ambiente DSH_LOG_LEVEL=debug antes de iniciar para ver o processo completo de inicialização e informações de carregamento de plugins.

Q: O que devo fazer se o pnpm install falhar?

Garanta que a versão do Node.js >= 18, então tente: pnpm store prune && pnpm install --force . Para problemas de rede, configure um mirror npm: pnpm config set registry https://registry.npmmirror.com .

Última atualização: 2026-08-31

A instalação do DeepSeek Harness é incrivelmente simples — um único comando para começar, sem necessidade de configuração complexa de ambiente. Seja usando npx para uma experiência one-click ou executando a partir do código-fonte para personalização profunda, o DSH pode estar funcionando em 5 minutos.

💡 Dica: Para primeiro uso, recomendamos npx @deepseek-ai/dsh web para lançamento one-click sem instalação manual de dependências. A abordagem de código-fonte é para desenvolvedores que precisam modificar o framework em si.

📋 Pré-requisitos: Conhecimento básico de linha de comando, ter completado 01-intro.md

1. O Que Você Vai Aprender

Configuração do ambiente Node.js 18+
Lançamento one-click da Web UI do DSH com npx
Executando DSH a partir do código-fonte (pnpm install + pnpm dsh web)
Acesso à Web UI e visão geral da interface
Detalhes da configuração de variáveis de ambiente

Ordem de Carregamento de Config

2. Configuração do Ambiente

(1) Instalação do Node.js

DSH é baseado no runtime Node.js, requerendo Node.js 18+ como mínimo.

BASH

# Verificar versão do Node.js
node --version
# v18.x.x ou superior

# Verificar versão do npm
npm --version
# 9.x.x ou superior

Se Node.js ainda não está instalado:

BASH

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (winget)
winget install OpenJS.NodeJS.LTS

Recomendamos usar Node.js 20 LTS — esta é a versão de suporte de longo prazo mais estável atualmente, e o DSH foi mais testado nela.

(2) Compatibilidade de SO

Sistema Operacional	Status de Suporte	Observações
macOS 12+	✅ Totalmente suportado	Intel e Apple Silicon
Ubuntu 20.04+	✅ Totalmente suportado	Versões LTS recomendadas
Windows 10+	✅ Suportado	Ambiente WSL2 recomendado
Windows (Nativo)	⚠️ Suporte básico	Algumas ferramentas podem ter problemas de caminho

(3) Requisitos de Rede

DSH precisa acessar APIs de LLM. Garanta que seu ambiente de rede:

BASH

# Testar conectividade com a DeepSeek API (requer API Key)
curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" | head -20

# Testar conectividade com endpoint compatível com OpenAI
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -20

3. Lançamento One-Click: Método npx

(1) Iniciando a Web UI

A abordagem mais simples — sem instalação necessária, basta executar:

BASH

npx @deepseek-ai/dsh web

Na primeira execução, npx fará o download automático da versão mais recente do pacote DSH:

TEXT 📖 Somente leitura

Need to install the following packages:
@deepseek-ai/dsh@latest
Ok to proceed? (y) y

🚀 DeepSeek Harness v0.x.x (developer preview)
📦 Starting Web UI...

  ➜  Local:   http://127.0.0.1:3080/
  ➜  Network: http://192.168.1.100:3080/

⚠️  Developer Preview: APIs may change before stable release.

(2) Acessando a Web UI

Abra seu navegador e acesse http://127.0.0.1:3080/:

pt-br Página Inicial da Web UI

TEXT 📖 Somente leitura

http://127.0.0.1:3080/
├── Esquerda: Lista de Sessões
├── Centro: Área de Chat
├── Direita: Painel de Ferramentas
└── Topo: Seleção de Modo + Seleção de Modelo

(3) Características do Método npx

Vantagens	Desvantagens
Zero instalação, executa imediatamente	Pode baixar nova versão a cada execução
Sempre obtém a versão mais recente	Não é possível controlar a versão
Ótimo para testes rápidos	Personalização limitada

▶ Exemplo 4：

BASH

# Especificar um número de versão
npx @deepseek-ai/dsh@0.5.0 web

# Especificar uma versão beta
npx @deepseek-ai/dsh@beta web

4. Executando a Partir do Código-Fonte

(1) Clonando o Repositório

Adequado para usuários que precisam modificar o código do framework ou contribuir para o desenvolvimento:

BASH

# Clonar o repositório
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# Visualizar branches disponíveis
git branch -r
# origin/main
# origin/dev
# origin/feature/...

(2) Instalando Dependências

DSH usa pnpm como gerenciador de pacotes:

BASH

# Instalar pnpm (se ainda não estiver instalado)
npm install -g pnpm

# Instalar dependências do projeto
pnpm install

pnpm install instalará todas as dependências do workspace, incluindo:

TEXT 📖 Somente leitura

packages/
├── core/          # Kernel Cordis
├── cli/           # Ferramenta CLI
├── web/           # Web UI
├── sdk-python/    # Python SDK
├── plugins/       # Plugins integrados
└── tools/         # Ferramentas integradas

▶ Exemplo 3：

BASH

# Iniciar Web UI (modo de desenvolvimento, com hot reload)
pnpm dsh web --dev

# Iniciar modo CLI
pnpm dsh cli

# Iniciar modo Headless
pnpm dsh headless

Diferenças entre modo de desenvolvimento e produção:

Dimensão	Modo de Desenvolvimento `--dev`	Modo de Produção
Hot Reload	✅ Mudanças de código atualizam automaticamente	❌
Source Map	✅ Informações completas de depuração	❌
Performance	Mais lento (não otimizado)	Mais rápido (otimização compilada)
Nível de Log	debug	info

▶ Exemplo 4：

BASH

# Compilar todos os pacotes
pnpm build

# Compilar apenas Web UI
pnpm --filter @deepseek-ai/dsh-web build

# Executar após compilação
pnpm dsh web

5. Configuração de Variáveis de Ambiente

DSH gerencia API Keys, endpoints de modelo e outras configurações através de variáveis de ambiente.

(1) Variáveis de Ambiente Principais

BASH

# DeepSeek API Key (necessário ao usar modelos DeepSeek)
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"

# Endpoint compatível com OpenAI (opcional, ao usar modelos não-DeepSeek)
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"

# Endpoint customizado (opcional, ao usar APIs compatíveis de terceiros)
export DSH_LLM_BASE_URL="https://your-custom-endpoint.com/v1"
export DSH_LLM_API_KEY="your-api-key"

(2) Configuração de Runtime

BASH

# Porta da Web UI (padrão 3080)
export DSH_PORT=3080

# Nível de log (debug / info / warn / error)
export DSH_LOG_LEVEL=info

# Workspace (diretório raiz para operações do Agent)
export DSH_WORKSPACE="/path/to/your/project"

# Modo sandbox (strict / permissive / off)
export DSH_SANDBOX=permissive

(3) Usando um Arquivo .env

Recomendamos criar um arquivo .env na raiz do projeto para gerenciar variáveis de ambiente:

BASH

# Exemplo de arquivo .env
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
DSH_PORT=3080
DSH_LOG_LEVEL=info
DSH_WORKSPACE=/home/alice/my-project
DSH_SANDBOX=permissive

Nota de segurança: O arquivo .env contém informações sensíveis. Certifique-se de adicioná-lo ao .gitignore:

BASH

# Garantir que .env não seja commitado
echo ".env" >> .gitignore

(4) Prioridade das Variáveis de Ambiente

graph LR
    A[Argumentos de Linha de Comando] -->|Maior| RES[Valor Final]
    B[Arquivo .env] --> RES
    C[Variáveis de Ambiente do Sistema] --> RES
    D[Valores Padrão] -->|Menor| RES

6. Inicialização em Modo CLI

Além da Web UI, DSH também suporta interação pura via CLI:

BASH

# Iniciar modo CLI
npx @deepseek-ai/dsh cli

# Ou especificar um workspace
npx @deepseek-ai/dsh cli --workspace /path/to/project

# Especificar um modelo
npx @deepseek-ai/dsh cli --model deepseek-chat

# Especificar um modo de execução
npx @deepseek-ai/dsh cli --mode ptc

Interface de interação do modo CLI:

TEXT 📖 Somente leitura

$ npx @deepseek-ai/dsh cli

🚀 DeepSeek Harness v0.x.x
📂 Workspace: /home/alice/my-project
🤖 Model: deepseek-chat
🔧 Mode: standard

> Me ajude a analisar a estrutura de diretórios deste projeto
🔍 Using tool: search...
📂 Reading directory structure...

Agent: Este projeto é uma aplicação Express.js típica. A estrutura de diretórios é a seguinte:
...

7. Verificando a Instalação

(1) Verificar Versão do DSH

BASH

npx @deepseek-ai/dsh --version
# 0.x.x

(2) Verificar Configuração do Ambiente

BASH

npx @deepseek-ai/dsh doctor

dsh doctor verifica automaticamente:

TEXT 📖 Somente leitura

✅ Node.js: v20.11.0
✅ pnpm: 8.15.0
✅ DEEPSEEK_API_KEY: configured (sk-...xxxx)
⚠️ OPENAI_API_KEY: not configured (optional)
✅ Network: api.deepseek.com reachable
✅ Workspace: /home/alice/my-project (exists)
⚠️ Sandbox: permissive mode (not recommended for production)

(3) Teste Rápido de Funcionalidade

BASH

# Iniciar Web UI e verificar com curl
npx @deepseek-ai/dsh web &
sleep 5
curl -s http://127.0.0.1:3080/api/health | head -5
# {"status":"ok","version":"0.x.x"}

8. Problemas Comuns de Instalação

(1) Versão do Node.js Muito Baixa

TEXT 📖 Somente leitura

Error: DSH requires Node.js 18 or higher.
Current version: 16.x.x

Solução:

BASH

# Usar nvm para gerenciar múltiplas versões do Node.js
nvm install 20
nvm use 20

(2) Porta Já em Uso

TEXT 📖 Somente leitura

Error: Port 3080 is already in use.

Solução:

BASH

# Especificar uma porta diferente
export DSH_PORT=3081
npx @deepseek-ai/dsh web

# Ou encontrar o processo usando a porta
lsof -i :3080    # macOS/Linux
netstat -ano | findstr :3080   # Windows

(3) API Key Inválida

TEXT 📖 Somente leitura

Error: Invalid API key. Please check your DEEPSEEK_API_KEY.

Solução: Verifique se a variável de ambiente está configurada corretamente:

BASH

echo $DEEPSEEK_API_KEY
# Deve exibir sk-xxxxxxxxxxxxxxxx

# Se vazio, configure novamente
export DEEPSEEK_API_KEY="sk-your-actual-key"

❓ Perguntas Frequentes

P O npx baixa toda vez?

R A primeira execução do npx baixa o pacote DSH; execuções subsequentes usam o cache. Se quiser evitar downloads repetidos, instale globalmente: npm install -g @deepseek-ai/dsh, depois inicie diretamente com dsh web.

P Posso executar o DSH no Docker?

R Sim. DSH fornece uma imagem Docker oficial: docker run -p 3080:3080 -e DEEPSEEK_API_KEY=sk-xxx deepseek/dsh:latest.

P Como atualizo o DSH para a versão mais recente?

R O método npx obtém automaticamente a versão mais recente. Para instalações globais, use npm update -g @deepseek-ai/dsh. Para instalações a partir do código-fonte, use git pull && pnpm install.

P Quais são os problemas conhecidos em ambientes Windows nativos?

R Problemas de separador de caminho (\ vs /) podem causar mau funcionamento de algumas ferramentas. Recomendamos usar WSL2 para executar o DSH para a melhor experiência.

P Como posso ver os logs detalhados de inicialização do DSH?

R Configure a variável de ambiente DSH_LOG_LEVEL=debug antes de iniciar para ver o processo completo de inicialização e informações de carregamento de plugins.

P O que devo fazer se o pnpm install falhar?

R Garanta que a versão do Node.js >= 18, então tente: pnpm store prune && pnpm install --force. Para problemas de rede, configure um mirror npm: pnpm config set registry https://registry.npmmirror.com.

📖 Resumo

DSH requer Node.js 18+ no mínimo; Node.js 20 LTS é recomendado
npx @deepseek-ai/dsh web lança a Web UI com one-click, acessível em http://127.0.0.1:3080
Execução a partir do código-fonte: git clone + pnpm install + pnpm dsh web
Variáveis de ambiente são configuradas via arquivo .env ou export; API Key deve ser configurada
O comando dsh doctor pode verificar a configuração do ambiente em um passo
Problemas comuns: versão do Node, conflitos de porta, configuração de API Key

📝 Exercícios

1. ⭐ Básico： Inicie a Web UI do DSH usando o método npx, e tire um screenshot (ou descreva) os elementos da interface da página inicial que você vê.

2. ⭐⭐ Intermediário： Clone o repositório DSH a partir do código-fonte, complete pnpm install e inicie em modo de desenvolvimento. Registre quaisquer problemas encontrados durante a inicialização e como você os resolveu.

3. ⭐⭐⭐ Desafio： Configure o DSH para conectar tanto à DeepSeek API quanto a um endpoint compatível com OpenAI (ex.: Ollama). Troque com sucesso entre os dois modelos na Web UI e envie uma mensagem com cada um.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós