CH 05 · Rodar pela Linha de Comando: headless + CLI
Objetivo do Capítulo
Os capítulos anteriores ficaram clicando na Web UI. Este capítulo muda a forma: sem interface nenhuma, um único comando no terminal deixa o dsh terminar um trabalho e sair — isso é headless. Enquanto isso, passaremos por todas as portas que o "launcher" do dsh pode abrir; será útil depois para scripts, CI e jobs em lote.
Primeiro Entenda: o dsh É um Launcher Multi-Entrada
O dsh não é apenas "aquela página web". Ele é um launcher — o mesmo Harness, a mesma pilha de plugins, pode iniciar em diferentes formas:
Os pontos de entrada oficiais são estas portas:
| Entrada | Propósito | Em palavras simples |
|---|---|---|
web | A bancada de trabalho web com interface | Aquela que você usou nos capítulos anteriores |
headless | Executa uma tarefa, imprime a resposta, sai | Tarefa one-shot pela linha de comando, a estrela deste capítulo |
sdk | Serviço JSON-RPC stdio | Atua como backend para programas, permite que outras aplicações o chamem |
acp | Serviço ACP stdio | Fornece serviço para clientes de automação |
plugin | Gerenciamento de plugins para o profile | Instalar plugins, adicionar dependências a um profile — é para isso que serve |
Não importa por qual porta você entra, a mesma pilha de plugins está fazendo o trabalho por baixo. O CH 02 disse "tudo é um plugin"; a essa altura você deveria sentir isso: até a "entrada" em si é uma combinação de plugins.
headless: Uma Frase, Uma Tarefa
O headless é a tarefa one-shot em modo linha de comando. O uso é bem simples:
dsh --profile headless "o que você quer que ele faça"Seu comportamento, em uma frase oficial: abre uma sessão persistente novinha → faz o trabalho → imprime a resposta final → sai.
Alguns pontos-chave:
- Workspace = o diretório em que você está ao executar o comando. Onde quer que você rode o comando, é onde ele trabalha (sem necessidade de escolher manualmente um workspace como na Web UI).
- "Abre uma sessão persistente novinha" é literal: cada execução headless equivale a abrir uma nova sessão no diretório atual como workspace, e salvá-la em
$DSH_HOME/sessions. Isso é fácil de confundir, então deixa eu desembaraçar para você — no nível de arquivo: as sessões são armazenadas por pasta de workspace, sobC:\Users\<seu-usuário>\.dsh\sessions\, onde você pode ver diretamente diretórios nomeados conforme os caminhos de workspace (como--E-software-workspace-...--), contendo arquivos de sessão compactados; no nível da Web UI: a sessão de uma execução headless aparece na categoria Ungrouped, não automaticamente sob qualquer grupo de workspace (na versão atual). Armazenamento de arquivo é por workspace, exibição na UI fica em Ungrouped — são duas coisas separadas. A seção prática abaixo mostrará isso. - O modelo padrão é
deepseek-v4-flash: o cenário CLI não tem UI nem necessidade de imagens, então o padrão oficial dá o flash de melhor custo-benefício. - Sem UI, mas o pipeline completo está lá: injeção de contexto, planejamento, chamadas de ferramentas, pensamento, encerramento — nada falta, ele simplesmente não desenha para você.
Prática: Primeira Tarefa headless
Dê ao Agent uma "tarefa grande": ler o repo, resumir a arquitetura e escrever um documento em chinês. Rode no workspace:
dsh --profile headless "Read the deepseek-harness subdirectory's code and docs, summarize the overall architecture of DeepSeek Harness (plugin mechanism, layering, entry points, main packages and directories), and write a Chinese markdown architecture document saved to the current directory with the filename deepseek-harness-arch.md"Resultado impresso após rodar:
Done. I read the key source and docs in the deepseek-harness subdirectory, organized it into a Chinese architecture document and saved it to the current directory.
File: E:\software-workspace\DeepSeek harness demo\deepseek-harness-arch.md (about 295 lines)Volte para a Web UI para verificar essa sessão: você pode encontrá-la na lista de sessões, mas note que ela aparece na categoria Ungrouped, não sob um grupo de workspace (sessões headless não são agrupadas automaticamente, este é o comportamento real da versão atual):
À direita você pode ver todo o processo de execução: context injection → think → Pwsh list directory → read doc → write file. A barra de estatísticas inferior mostra 1 turn · 18 steps, LLM 2m1s, cache hit 92%, input 1.1M tokens.
Cheatsheet de Parâmetros CLI
| Comando | Efeito |
|---|---|
dsh --profile <nome> "tarefa" | Inicia com o profile especificado (headless é um deles) |
dsh web | Alias para --profile web, inicia a Web UI |
dsh --dump-config | Imprime a árvore de configuração combinada completa (joia para resolução de problemas, veja abaixo) |
dsh --dump-default-config | Imprime a árvore de configuração padrão sem mudanças do usuário |
dsh --patch <caminho> | Empilha outra camada de configuração sobre o profile |
dsh plugin --profile <nome> add <pacote> | Instala um plugin em um profile |
dsh --help | Vê a ajuda do próprio launcher |
--dump-config merece um destaque à parte: ele imprime a combinação final efetiva de plugins para um profile. Rode de verdade:
O que você vê é uma longa lista de plugins @deepseek-ai/dsh-* empilhados em uma árvore — llm (modelo), session (sessão), credentials (chaves), session-persistence-jsonl (persistência de sessão)... você também pode ver diretamente que agent-default-model está configurado como deepseek-v4-flash. Ao resolver problemas ou tentar descobrir "de onde vem esse comportamento", despeje a árvore de configuração primeiro.
Há um truque ainda mais conveniente para resolução de problemas: basta deixar a IA rodar este comando por si mesma. Por exemplo, em uma sessão peça a ela "use dsh --profile headless --dump-config para verificar a árvore de configuração atual e ver por que o modelo padrão não é o que eu quero" ou "verifique se um plugin não está fazendo efeito" — a IA executará --dump-config por si mesma, lerá a árvore de configuração, e trabalhará a configuração entrada por entrada para ajudá-lo a localizar o problema. Essa combinação é um soco muito prático na resolução de problemas.
Quando Usar headless, Quando Usar web
| Cenário | Qual usar |
|---|---|
| Quer ver o Agent trabalhando, interromper a qualquer momento, resolver problemas passo a passo | web |
| Scripts, CI, tarefas agendadas, processamento em lote, só o resultado importa | headless |
| Outros programas/ferramentas precisam chamar as capacidades do dsh | sdk / acp |
| Quer confirmar configuração, resolver problemas de inicialização | --dump-config / --help |
Lembre-se também de um limite oficial: cada chamada headless executa apenas uma tarefa, sem acompanhamento interativo. Se você precisar de várias rodadas ou de ver ele trabalhando, volte para web.
O que você aprendeu neste capítulo
Você passa se conseguir completar os itens abaixo:
- [ ] Descrever pelo menos quatro pontos de entrada do dsh (web / headless / sdk / acp / plugin) e o que cada um faz
- [ ] Rodar uma tarefa one-shot pela linha de comando com
dsh --profile headless "tarefa"e explicar seu comportamento (nova sessão → trabalho → imprime resposta → sai) - [ ] Saber que o workspace do headless é o diretório atual ao rodar o comando, e que cada execução abre uma sessão persistente (armazenada por workspace sob $DSH_HOME/sessions; na lista de sessões da Web UI, sessões headless estão em Ungrouped)
- [ ] Indicar os cenários para os quais headless é adequado (lote, CI, agendado, análise de repo) e o limite oficial (uma tarefa por chamada, sem interação)
- [ ] Usar
dsh --dump-configpara ver a árvore de configuração, e conhecer seu uso para resolução de problemas - [ ] Julgar se um cenário deve usar web ou headless