CH 03 · Instalar e Iniciar

Tamanho~3.130 palavrasTempo~20 minNívelReproduzível

Objetivo do Capítulo

Este capítulo coloca o dsh em funcionamento do zero: confirma/instala o Node.js, depois lança a Web UI com um comando, completa a configuração inicial (chave de modelo + workspace) e finalmente envia sua primeira tarefa real. Depois de fazer isso, você está oficialmente dentro.

Antes da Prática: Você Só Precisa de Duas Coisas

1. Node.js — o dsh roda em Node; esta é a única dependência de ambiente. Sem banco de dados, sem Java para configurar.
2. Uma DeepSeek API Key — o dsh em si é gratuito e open-source, mas chamar o modelo custa dinheiro. Vá até a DeepSeek Open Platform, registre-se e faça login, depois na barra lateral esquerda "API Keys" → Create, copie e salve. A Key é mostrada por completo apenas uma vez, no formato de string longa com prefixo sk-; guarde-a em algum lugar seguro antes de fechar a página.

Passo 1: Verificar o Node.js Local

Abra um terminal (no Windows pressione Win + R, digite cmd, pressione Enter), e digite:

node --version
npm --version

Se você vir números de versão, está pronto. O dsh tem requisitos de versão do Node: a declaração oficial é ^22.19 || >=24. Em palavras simples: Node 22.x em 22.19 ou superior, ou Node 24 e superior. Em outras palavras: 22.x anteriores a 22.19, e versões ímpares como Node 23, não são suportados e falharão ao iniciar.

Se, como eu, você já tinha Node instalado e a versão atende ao requisito, pule para o passo 3.

Passo 2: Não Tem Node.js? Instale Um (Windows)

Abra o site do Node.js, baixe o instalador Windows da versão LTS (.msi, 64-bit), clique duplo e siga Next. Por padrão ele também instala o npm e os adiciona ao PATH do sistema.

Depois de instalar, lembre-se de reabrir o terminal antes de verificar novamente — muitos problemas do tipo "acabei de instalar mas o comando não é encontrado" são apenas variáveis de ambiente não atualizadas:

node --version
npm --version

Passo 3: Trocar o npm para um Mirror da China (Opcional mas Recomendado)

Puxar pacotes npm diretamente na China costuma ser lento ou dar timeout. Trocar para o mirror Taobao ajuda bastante:

npm config set registry https://registry.npmmirror.com
npm config get registry

Se você vir https://registry.npmmirror.com, está em vigor.

Passo 4: Instalar e Iniciar o dsh

Este tutorial usa uma instalação global via npm: um comando para instalar, depois o comando dsh fica disponível em qualquer lugar sem precisar baixar de novo — mais fácil para iniciantes.

Instale o pacote global:

npm install -g @deepseek-ai/dsh

Depois de instalar, verifique a versão:

dsh --version

Em seguida, inicie a Web UI:

dsh web

A primeira execução gastará um ou dois minutos baixando dependências, com uma série de logs rolando no terminal — isso é normal. Quando você vir algo como o seguinte, está no ar:

dsh web: http://127.0.0.1:3080
dsh web: opening the default browser; pass --no-open to disable

Para atualizar para a versão mais recente (instalações globais não se atualizam sozinhas; faça manualmente):

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

Passo 5: Abrir a Web UI

Na primeira vez que você executar dsh web, ele abrirá automaticamente o navegador na interface. Se não abrir sozinho, abra manualmente o navegador e visite:

http://127.0.0.1:3080

Este é o endereço de loopback local; só funciona nesta máquina e não é exposto à rede externa.

Na primeira vez que você abrir, um aviso de beta aparece — o DeepSeek Harness 0.1 ainda é uma versão de teste voltada para desenvolvedores e continuará iterando rapidamente. Clique em Continue para entrar na interface principal.

Passo 6: Configuração Inicial (Key + Workspace)

6.1 Preencha a API Key Depois de clicar Continue no passo anterior, o dsh abrirá diretamente um guia "Add an API Key to get started" — cole sua chave com prefixo sk- na caixa de entrada e clique em Save and Continue. (Para mudar a Key ou trocar o modelo depois, vá até o botão Settings no canto inferior esquerdo → Models.)

A Key é gravada apenas localmente em C:\Users\<seu-usuário>\.dsh\.credentials.yaml; a UI nunca exibe o texto puro. Não tire prints e compartilhe.

6.2 Escolha um workspace Depois de preencher a Key, você entra na interface principal. Clique no dropdown Choose workspace e escolha um diretório onde você quer que o Agent trabalhe (por exemplo, a pasta do seu projeto). Até que um workspace seja selecionado, a caixa de entrada na parte inferior continuará dizendo "Pick a workspace to start" — isso é de propósito: sem dizer ao Agent onde trabalhar, ele não vai ousar agir.

6.3 Escolha um modelo e uma permissão (configure antes de enviar a primeira tarefa) Depois de selecionar um workspace, um seletor de modelo aparece no canto inferior direito; você verá os três modelos DeepSeek:

Model ID	Posicionamento
deepseek-v4-pro	Flagship — mais forte, porém mais caro
deepseek-v4-flash	Rápido, alta relação custo-benefício
deepseek-v4-flash-vision-exp	Versão multimodal com visão: consegue ler imagens, ver screenshots, analisar gráficos; no mesmo nível do flash para texto puro, significativamente à frente em multimodal

deepseek-v4-flash-vision-exp é o primeiro modelo de visão da família DeepSeek V4 (experimental, API lançada em 21 de agosto de 2026; pesos open-sourced em 31 de agosto). Consegue ler imagens, ver screenshots, analisar gráficos e também executar tarefas normais de texto. Todas as demonstrações neste livro usam este modelo — selecione-o no painel, escolha um reasoning effort (High padrão serve), salve e entra em vigor imediatamente; sem necessidade de reiniciar.

À esquerda da caixa de entrada há também um seletor de permissão (mostrando Workspace Write no screenshot), que determina o que o Agent pode tocar no seu computador — mantenha o padrão por enquanto. As diferenças detalhadas entre essas opções (o que cada um dos três níveis de permissão pode fazer, como escolher um reasoning effort) são cobertas no CH 04 quando passarmos pela interface.

Passo 7: Execute Sua Primeira Tarefa

Crie uma nova sessão e digite uma frase, por exemplo:

Summarize the DeepSeek harness repository and identify its main modules.

O Agent começará a ler arquivos, executar comandos e manter um plano, com cada chamada de ferramenta exibida na interface — o screenshot mostra a cadeia completa de execução Context injection → Think → Pwsh → Read. Para operações sensíveis, ele exibe um diálogo de aprovação conforme a política de permissão atual. No canto superior esquerdo da interface há duas abas, Conversation / Trajectory; a Trajectory é a mesma Trajectory mencionada no CH 02, e vamos detalhá-la depois.

Depois que ele termina, você obtém um resumo completo — minha resposta desta vez foi intitulada "DeepSeek Harness Repository Summary": o posicionamento em uma linha é "Everything is a plugin AI Agent runtime framework / workbench, built on Cordis", e também percorreu a estrutura de diretórios packages/apps/docs do repo e os principais módulos da série de pacotes dsh-*.

Depois que você passou por essa etapa, está oficialmente dentro.

Uso Avançado

Mudar a porta (quando a 3080 está ocupada): use o seguinte comando em vez de dsh web ao iniciar —

dsh web --port 8080

Depois visite http://127.0.0.1:8080.

Tarefa de linha de comando one-shot (headless):

dsh --profile headless "Run the tests in the current directory and summarize the results"

Ele imprime o resultado e sai, adequado para scripts e CI. O manual completo de headless (múltiplos pontos de entrada, parâmetros CLI, prática real) é coberto no CH 05.

Ver a árvore de configuração realmente efetiva (muito útil para resolução de problemas):

dsh web --dump-config

Resolução de Problemas Comuns

Sintoma	Resolução
node não é um comando interno ou externo	Node não está instalado corretamente, ou o terminal não foi reaberto. Reabra o PowerShell e tente novamente
Node version ... is not supported	Versão abaixo de 22.19, ou Node 23. Atualize para 22.19+ / 24
Primeira instalação trava ou download falha	Problema de rede. Configure o registry npmmirror primeiro e tente novamente
Porta 3080 ocupada	Mude a porta: dsh web --port 8080
A página não abre	Confirme que o terminal onde o comando de inicialização roda ainda está aberto; o endereço é http://127.0.0.1:3080
Reporta MISSING_CREDENTIAL	Nenhuma API Key armazenada (vá em Settings → Models para adicionar uma) ou a janela não foi reaberta
Reporta UNKNOWN_MODEL	Um modelo não configurado foi selecionado; adicione o Model ID sob um provider customizado
Erros de compilação nativa (ex. node-pty)	No Windows, instale o Visual Studio Build Tools (com componentes C++)

Lembrete de segurança: sua API Key é sua carteira. Não tire print dela em grupo de chat nem faça commit em repositório Git. Se suspeitar que vazou, vá até a plataforma e revogue e recrie; a Key antiga se torna imediatamente inválida.

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Usar node --version para confirmar que o Node está em 22.19+ / 24+ (se não, instale conforme o passo 1)
• [ ] Instalar o dsh com npm install -g @deepseek-ai/dsh, iniciar com dsh web e abrir http://127.0.0.1:3080
• [ ] Completar a configuração inicial: Settings → Models com a API Key, e escolher um workspace
• [ ] Enviar sua primeira tarefa real com sucesso e ver o Agent em ação