CH 04 · Conheça a Web UI
Objetivo do Capítulo
No capítulo anterior você instalou o dsh, preencheu a Key, escolheu um workspace e executou sua primeira tarefa. Este capítulo faz uma pausa para ler a interface: o que cada área faz, quais opções estão escondidas no painel de configurações, o que cada um dos três níveis de permissão permite ao Agent fazer, e como ler a visualização Trajectory. Quando terminar, você vai perceber que a frase "cada execução é rastreável" do CH 02 está bem ali no canto superior esquerdo da interface — a uma aba de distância.
Layout da Interface: Familiarize-se
Este é o screenshot de tela cheia que tirei depois de executar a primeira tarefa, com as principais áreas anotadas:
Responsabilidades das áreas:
| Área | O que faz | Notas |
|---|---|---|
| Esquerda | Lista de workspaces | Um workspace por diretório de projeto; escolha o workspace aqui (abra a lista e escolha um, ou "⊕ New Session" para criar); embaixo fica o botão Settings |
| Centro | Área de sessão | Onde você envia mensagens, o Agent trabalha e os resultados são mostrados; no topo ficam as abas Conversation / Trajectory |
| Inferior | Área de entrada | À esquerda do botão Send fica o anel de ocupação de contexto; mais à esquerda estão os seletores Model e Permission; abaixo fica a barra de estatísticas |
Painel de Configurações: A Engrenagem no Canto Inferior Esquerdo
O botão Settings fica no canto inferior esquerdo da interface. Quando aberto, o lado esquerdo lista categorias de recursos — General Settings / Models / Plugins / Agent Presets:
Primeiro, a página General Settings: idioma, aparência e comportamento da tecla Enter enquanto ocupado estão todos aqui, mais dois importantes — Permission (o modo de permissão padrão para novas sessões; o meu é Workspace Write) e Agent Preset (atualmente "Standard"). O Agent Preset aqui é os quatro modos de runtime (Standard / Code / Minimal / Creator) que cobrimos no CH 02 — o que você escolhe aqui é "qual combinação de plugins novas sessões usarão por padrão". Note a linha abaixo: "Takes effect for newly created sessions. Already-running sessions keep the preset they started with." — padrões definidos em General Settings só se aplicam a novas sessões, uma regra que você vai encontrar várias vezes.
Agora olhe para Settings → Models: a API Key está preenchida no card DeepSeek (se preenchida, aparece como configurada), e no final você pode add a Provider (usando um diretório embutido como Anthropic ou OpenAI) e add a Custom Provider (para seu próprio gateway ou modelo local — preencha Provider ID, endereço da API, protocolo, chave e pelo menos um modelo). Mudanças no roteamento de modelos entram em vigor imediatamente; sem necessidade de reiniciar o serviço. A Key é apenas escrita: depois de salvar, a página mostra apenas um descritor mascarado, e o texto puro só vai para $DSH_HOME/.credentials.yaml localmente — o mesmo caminho mencionado no CH 03.
Três Níveis de Permissão: O que Pode Tocar no Seu Computador
Esta é a coisa que você deve entender logo de cara sobre o dsh. O sandbox de arquivos oficial é definido como três modos:
Compare com o seletor de permissão à esquerda da caixa de entrada na sua interface (no painel que aparece depois de escolher um workspace):
Os três níveis em palavras simples:
| Permissão | O que pode fazer | Quando usar |
|---|---|---|
read-only | Apenas leitura, não consegue alterar um único byte | Análise somente leitura, revisão de código, Q&A puro |
workspace-write (padrão) | Gravável no workspace + área temporária do sistema; fora do workspace, exibe um diálogo e pergunta antes | Trabalho diário, a grande maioria dos casos |
danger-full-access | Leitura/escrita total em qualquer lugar, sem fronteira | Para tarefas de manutenção de sistema que realmente precisam de mudanças globais; o interruptor exigirá uma segunda confirmação |
Mais uma observação sobre a semântica oficial: o limite de escrita para workspace-write é "a raiz do workspace + a área temporária prometida pelo backend"; read-only recusa escritas de qualquer forma; danger-full-access ignora completamente o isolamento. Note que permissões regem apenas efeitos no sistema de arquivos — visibilidade de rede e processos não é coberta por essa definição.
Para o trabalho diário, mantenha o padrão workspace-write, familiarize-se primeiro, e considere o terceiro nível apenas quando precisar realmente agir globalmente.
Trocar vem em dois sabores, não confunda:
- Apenas para esta sessão, temporariamente: digite
/permissionna caixa de entrada e escolha um nível. Afeta apenas a sessão atual. - Mudar o padrão (para que futuras novas sessões o usem): vá em Settings → General → Permission. Afeta apenas sessões criadas depois; sessões já em execução ficam intocadas.
Modelo e Reasoning Effort
No seletor de modelo, você vê os modelos configurados (depois de preencher a Key, os da DeepSeek aparecem automaticamente). Há uma regra oficial explícita: o modelo escolhido no seletor de modelo é o padrão para novas sessões; sessões que já enviaram requests manterão o modelo que estavam usando quando iniciaram, e não mudarão com o padrão (a sessão registra seu próprio modelo, mudar o padrão não reescreve silenciosamente requests passados).
Então se você quer que sessões diferentes usem modelos diferentes (trabalho diário leve em flash, tarefas pesadas em pro ou mais forte), basta abrir novas sessões — cada uma é independente.
Reasoning effort é outro botão; o modelo oficial DeepSeek tem quatro níveis:
| Nível | Característica |
|---|---|
off | Desativa pensamento, mais rápido e barato |
low | Pensamento leve, suficiente para Q&A simples |
high (padrão) | Raciocínio profundo, mais preciso em tarefas complexas, ligeiramente mais lento e mais caro |
max | Intensidade máxima, apenas para o trabalho mais difícil |
Para o trabalho diário, mantenha high; se achar lento, diminua. O conteúdo mais profundo sobre "o que cada nível realmente afeta e como mudar" é coberto no CH 06. Mudanças de modelo também entram em vigor no próximo request, sem necessidade de reiniciar.
Trajectory: O "Rastreável" do CH 02 Está Escondido Aqui
Lembra daquela frase "cada execução é rastreável" do CH 02? Olhe para o canto superior esquerdo da interface — Conversation / Trajectory ficam lado a lado. Clique em Trajectory e o registro completo de execução dessa rodada é exibido diante de você. Veja este screenshot real:
Como ler isso:
- No meio está uma timeline; ASSISTANT (think/speak) e TOOL (chamadas de ferramentas) se alternam, e de cima para baixo está a ordem real em que o Agent trabalhou.
- Para cada linha TOOL: o nome da ferramenta fica à esquerda (
pwsh/read/web_search), e à direita estão os parâmetros reais enviados e os principais resultados retornados. - Clique em qualquer linha TOOL, e o painel direito expande os detalhes dessa etapa: Summary / Payload / Result / Schema / Timing, além de Status (Completed) e Hierarchy.
- No topo há uma visão geral de Duration / Turns / Calls, mais uma caixa de busca para encontrar etapas por palavra-chave.
Na minha tarefa desta vez você pode ver o Agent realmente tropeçando: primeiro leu config, leu arquivos, e quando tentou usar pwsh para buscar diretamente os documentos oficiais, a conexão SSL falhou; ele disse "Outbound HTTPS from pwsh is blocked", então mudou para web_search para continuar procurando — todos esses tropeços estão registrados na Trajectory. Isso é "rastreável".
A barra de estatísticas inferior é o outro lado da mesma moeda:
| Métrica | Significado |
|---|---|
| Turns · Steps | Quantas etapas o Agent deu nesta rodada |
| LLM time / Tool call time | Tempo gasto "pensando" e "fazendo" |
| First-token mean / tok/s | Velocidade de saída |
| Cache hit | A proporção de tokens de entrada que acertaram o cache de contexto (veja abaixo) |
| Input / Output tok | Tokens alimentados ao modelo e produzidos pelo modelo nesta rodada |
Cache de Contexto: Por que a Taxa de Acerto É Tão Alta
O "cache hit" na barra de estatísticas não é um recurso do dsh; por trás dele está o cache de contexto em disco da DeepSeek API. A abordagem oficial: armazenar conteúdo esperado para ser reutilizado em um array de discos distribuídos; quando a próxima entrada contém uma porção repetida, lê do cache em vez de recomputar — reduzindo latência e custo.
A cobrança para tokens de entrada que acertam o cache é muito mais barata do que para misses. Tome deepseek-v4-flash como exemplo: no preço oficial atual, entrada com cache-hit custa cerca de 0,1 yuan por milhão de tokens, enquanto entrada com cache-miss custa cerca de 1,5–3 yuan por milhão de tokens (dependendo de horário fora do pico / pico) — essa porção em cache da entrada custa apenas uma fração do custo do miss.
Por que a taxa de acerto é tão alta em uma única sessão? Porque cada entrada de etapa na mesma sessão inclui o system prompt anterior, definições de ferramentas e histórico de conversa — um prefixo repetido estável. A primeira chamada não tem nada em cache, mas a partir da segunda, o segmento anterior é cacheado. Na minha tarefa tive 160K tokens de entrada com alta taxa de acerto, então apenas uma pequena porção foi cobrada pelo preço cheio de miss. É por isso também que tarefas de Agent são melhor feitas na mesma sessão — quanto mais longa a sessão, mais você economiza depois.
Anel de Ocupação de Contexto
O indicador circular à esquerda do botão Send na área de entrada mostra a razão de ocupação da janela de contexto da sessão atual. Veja o teste real:
O anel na imagem mostra "2% context used" — a sessão acabou de começar, quase nenhum uso. A janela de contexto é finita; conforme o Agent executa tarefas longas, o histórico de conversa e os resultados de ferramentas se acumulam, e o anel permite ver de relance quanto espaço resta. Quando estiver quase cheio, você tem três opções: iniciar uma nova sessão, pedir ao Agent para encerrar com um resumo, ou simplesmente digitar /compact na caixa de entrada — ele condensa as informações-chave da conversa atual em um resumo mais enxuto, e a IA continua trabalhando com esse resumo. É como colocar a sessão em uma dieta, sem precisar recomeçar.
Execute a Primeira Tarefa do Início ao Fim
O exemplo de tarefa no README oficial é este:
Summarize this repository and identify its main packages.
Que traduzido é o que você executou no capítulo passado: resumir o repositório do DeepSeek harness e identificar seus módulos principais. Então você já executou o exemplo oficial.
Ao executar, note como a interface "abre" o processo: o Agent primeiro injeta contexto, planeja, depois chama ferramentas (lê arquivos, executa comandos, consulta coisas), cada etapa visível; para ações que precisam de aprovação, exibe um diálogo. Depois que termina, mude para a aba Trajectory e faça replay, depois confira os números com a barra de estatísticas — a primeira tarefa geralmente tem uma entrada enorme (a minha foi 160K tokens), mas com alta taxa de acerto do cache, o custo real é muito baixo.
O que você aprendeu neste capítulo
Você passa se conseguir completar os itens abaixo:
- [ ] Descrever o que cada área da Web UI (esquerda / centro / inferior) é, e onde escolher um workspace
- [ ] Conhecer as categorias do painel de configurações (General Settings / Models / Plugins / Agent Presets), e que "padrões só se aplicam a novas sessões"
- [ ] Explicar a diferença entre os três níveis de permissão
read-only/workspace-write/danger-full-access, e por que usar o segundo para o trabalho diário - [ ] Saber que
/permissionmuda temporariamente a permissão da sessão atual, enquanto Settings → General → Permission muda o padrão - [ ] Saber que a escolha do seletor de modelo é o padrão para novas sessões; sessões que já rodaram mantêm seu modelo original
- [ ] Ler a visualização Trajectory: timeline ASSISTANT / TOOL + painel de detalhes à direita + barra de estatísticas
- [ ] Explicar o que é "cache hit", e por que sessões longas têm alta taxa de acerto