CH 17 · Instalação de Plugins

Número de palavras~6.370 palavrasTempo~20 minPré-requisitosCH 08 (Árvore de Plugins), CH 12 (Integração MCP)NívelReproduzível

Objetivo do Capítulo

No CH 12 você já instalou três plugins de fato — dsh-mcp-client, dshmarket, dsh-skill-mcp-panel — mas foi "instalar no caminho, contanto que funcione", os três métodos de instalação não foram explicados. Este capítulo cobre de forma sistemática instalar plugins: de onde vêm os plugins, onde são instalados, os diferentes métodos de instalação, como gerenciá-los, como verificar após a instalação — e por fim instale um na prática, e deixe o dsh instalá-lo diretamente para você.

Primeiro memorize uma frase: instalar um plugin = adicionar uma dependência npm a um profile. O dsh é "tudo é plugin" (abordado no CH 08), mas a "instalação" em si segue o gerenciamento padrão de pacotes. Quando você entende a instalação, o CH 18 começa a escrever seu primeiro plugin.

Primeiro Veja Sua Instalação

Abra o terminal e primeiro verifique a versão do próprio dsh:

dsh --version

Minha saída:

0.1.1-rc.2

Em seguida, verifique quais plugins o profile web já tem:

dsh plugin --profile web list

Minha saída (resultado da instalação no CH 12):

Legend: production dependency, optional only, dev only

dsh-profile-web C:\Users\mortal\.dsh\profiles\web (PRIVATE)
│
│   dependencies:
├── @deepseek-ai/dsh-mcp-client@0.0.1-rc.1
├── dsh-skill-mcp-panel@2.0.1
└── dshmarket@1.40.0

3 packages

Note que essas três linhas correspondem exatamente aos três métodos de instalação: mcp-client foi instalado pela linha de comando, dshmarket é o mercado instalado pela linha de comando, e dsh-skill-mcp-panel foi instalado com um clique no mercado — e o motivo de poderem entrar diretamente na árvore de configuração e ter efeito é o terceiro mecanismo auto-montagem de bundle. Cada um é explicado abaixo.

De Onde Vêm os Plugins: Quatro Fontes

Um plugin é essencialmente um pacote npm, e as fontes são estas:

Fonte	Sintaxe	Quando usar
Pacote npm	@deepseek-ai/dsh-mcp-client	Mais comum. Pacotes oficiais têm o prefixo @deepseek-ai/, pacotes da comunidade usam seu próprio escopo
Fonte do GitHub	github:owner/repo	Quando você quer instalar a branch main de um repositório, e ele ainda não foi publicado no npm
Diretório local	. ou file:../plugin	Quando você mesmo desenvolve um plugin, instale seu checkout local diretamente, edite e teste
tarball / Artefato de Release	Uma URL .tgz ou caminho local	Quando o autor só envia artefatos construídos, por exemplo, anexos em GitHub Releases

Quanto ao dsh-market (Plugin Market) instalado no CH 12, ele não é uma nova fonte, mas sim uma entrada gráfica: uma vez instalado, você pode navegar, pesquisar e instalar com um clique os plugins da comunidade em Configurações, com ele ainda chamando as fontes acima nos bastidores.

Onde Instalar: Nível de Profile, Segue o Profile

dsh plugin gerencia os plugins de um profile, então o comando precisa vir com --profile <nome>, decidindo em qual ambiente instalar. O pacote instalado fica em:

$DSH_HOME/profiles/<nome>/node_modules

No Windows isso é C:\Users\<seu-usuário>\.dsh\profiles\web\node_modules, gerenciado pelo pnpm, e também escrito no package.json do profile.

Um ponto fácil de confundir — a diferença entre global e Profile:

• O próprio corpo do dsh é instalado globalmente (npm install -g @deepseek-ai/dsh desde antes), todos os profiles compartilham o mesmo dsh.
• Plugins são por profile por padrão: dsh plugin --profile web add xxx só tem efeito para web; se você quer que o headless também use, precisa instalar para o headless também.
• Configuração em nível de máquina é uma camada diferente: $DSH_HOME/cordis.patch.yml é compartilhado por todos os profiles (o termo oficial é "machine-local preferences"), e tem prioridade maior que o cordis.patch.yml do próprio profile — se você quer que todos os ambientes apliquem a mesma mudança, escreva aqui.

Primeiro deixe claro onde esses arquivos estão, não os confunda. O de nível de profile está em C:\Users\<seu-usuário>\.dsh\profiles\web\cordis.patch.yml (o que editamos para a configuração do servidor MCP no CH 12); o de nível de máquina está em C:\Users\<seu-usuário>\.dsh\cordis.patch.yml — note que este arquivo não existe por padrão, só é criado quando você escreve a configuração manualmente, o dsh lê na inicialização, e pula se não existir. Então para verificar "o que escrevi é em nível de máquina", verifique se aparece no diretório raiz .dsh, não em profiles\<nome>\.

• Os bundles integrados oficiais (@deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app etc.) vêm com o dsh, da instalação global; os plugins que você mesmo adiciona são instalados no próprio node_modules do profile.

Uma frase para lembrar: o corpo do dsh é global, plugins seguem o profile, patches em nível de máquina aplicam-se a todo o site.

Três Métodos de Instalação

① Linha de comando dsh plugin: A Mais Fundamental

Este é o método mais fundamental. dsh plugin --profile <nome> repassa os argumentos como estão para o pnpm — então verbos do pnpm como add, remove, update, why, list estão todos disponíveis, e a sintaxe também é a sintaxe de gerenciamento de pacotes npm:

dsh plugin --profile web add @deepseek-ai/dsh-mcp-client

Um exemplo típico da documentação oficial é instalar dois plugins subagent (são bundles opcionais):

dsh plugin --profile web add @deepseek-ai/dsh-subagent-codex @deepseek-ai/dsh-subagent-claude-code
dsh plugin --profile web remove @deepseek-ai/dsh-subagent-codex

Instalar seu próprio plugin a partir de um diretório local também passa por aqui — execute dsh plugin --profile web add . no diretório de origem do plugin, e o que é instalado é o seu checkout atual (caminhos relativos são ancorados ao diretório onde você executou o comando, não ao diretório do profile).

② Plugin Market dsh-market: O Mais Fácil

Instalação gráfica. Primeiro instale o próprio corpo do mercado:

dsh plugin --profile web add dshmarket

Após a instalação, reinicie o dsh (mudanças de bundle exigem reinicialização, explicado abaixo), Configurações terá um novo "Plugin Market", onde você pode navegar por categoria, pesquisar e instalar com um clique os plugins da comunidade. A maioria dos plugins instalados pelo mercado têm efeito apenas atualizando a página, não precisa reiniciar o dsh; alguns plugins de nível host vão pedir "reinicialização necessária", basta seguir as instruções. O dsh-skill-mcp-panel no CH 12 foi localizado no mercado e instalado com um clique.

③ Auto-Montagem de Bundle: Instale e Entre na Árvore de Configuração

Primeiro responda a um fenômeno que você deve ter se perguntado: por que o mcp-client precisa de cordis.patch.yml insert manual para a configuração do servidor após a instalação, enquanto dshmarket e dsh-skill-mcp-panel têm efeito sem nenhuma configuração após a instalação? A resposta está no próprio package.json do plugin — a diferença é se dsh.bundle é declarado. Se um plugin quer "entrar automaticamente na árvore de configuração ao instalar", ele precisa declarar este campo em seu manifesto:

{
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

O dsh, após cada execução bem-sucedida de dsh plugin, vai reconciliar a lista de bundles: qualquer pacote em dependencies que resolva com uma declaração dsh.bundle será automaticamente adicionado à camada de bundle daquele profile (a camada base no fundo da árvore de configuração, abordada no CH 08), sem você precisar inseri-lo manualmente.

Como exemplo, olhe o package.json de dois plugins com declarações. dshmarket@1.40.0:

"dsh": {
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": { "inject": ["@deepseek-ai/dsh-client-connection", "..."], "platform": "web" }
}

dsh-skill-mcp-panel@2.0.1:

"dsh": {
  "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-runtime", "..."] },
  "bundle": { "patch": "./cordis.patch.yml" }
}

Ambos têm declarações bundle.patch, então ambos são automaticamente inseridos na lista de bundles do manifesto do profile. Abra o package.json do profile web, e a camada de bundles se parece com isto:

"dsh": {
  "profile": {
    "bundles": [
      "@deepseek-ai/dsh-base",
      "@deepseek-ai/dsh-web-app",
      "dsh-skill-mcp-panel",
      "dshmarket"
    ]
  }
}

Os dois primeiros são bundles integrados oficiais (que vêm com a instalação global do dsh), os dois últimos são o que você instalou e foram automaticamente montados. E quanto ao dsh-mcp-client? Ele não tem declaração dsh.bundle, então é apenas uma dependência regular — aparecendo em dependencies do package.json do profile, mas não na lista bundles. Uma analogia: um plugin bundle é como uma "ferramenta com instruções autoinstaláveis, pronta para usar"; uma dependência regular é como "apenas a ferramenta, sem instruções" — a mercadoria chega, mas o dsh não vai carregar automaticamente suas capacidades, você mesmo precisa configurá-lo.

dsh-mcp-client é o último caso: é o "motor que conecta a servidores MCP", sabe como conectar, mas não sabe a quais conectar. Você precisa dizer pessoalmente a ele a qual servidor conectar, o endereço, como a chave é passada — essa ação é escrever um insert em cordis.patch.yml (inserindo uma linha de configuração de servidor na árvore de configuração). A configuração do Firecrawl que você escreveu no CH 12 era um desses inserts.

Note também: esses dois plugins também têm declarações dsh.client (platform: web + inject uma lista de plugins client). É por isso que eles podem adicionar interfaces às Configurações do Web UI (Plugin Market, Gerenciamento MCP) — são bundles (entram na árvore de configuração) e declaram injeção de cliente (entram na interface).

Um limite que você deve lembrar: após um membro de bundle (algo na lista bundles) mudar, você precisa reiniciar o profile para ter efeito — um profile em execução retém o conjunto de bundles que tinha na inicialização, bundles recém-instalados só são carregados na próxima inicialização. Note que "reiniciar" aqui é apenas para deixá-lo carregar automaticamente, não para fazer você configurar nada — uma vez que o plugin bundle é carregado está pronto para usar, você não precisa tocar na configuração. Edições regulares de cordis.patch.yml passam por hot-reload, sem necessidade de reinicialização, mas adicionar/remover/atualizar um bundle e reinicializar é inevitável. O motivo de você ter reiniciado o dsh após instalar o dshmarket no CH 12 foi para deixá-lo auto-carregar.

Cola de Comandos de Gerenciamento

Comando	Efeito
dsh plugin --profile web list	Liste o que este profile tem instalado (equivalente a pnpm list)
dsh plugin --profile web add <fonte>	Instale, fonte veja os quatro tipos acima
dsh plugin --profile web remove <pacote>	Remova
dsh plugin --profile web update <pacote>	Atualize para o mais recente (aqueles com declarações de bundle serão reconciliados com o novo)
dsh plugin --profile web why <pacote>	Veja por que este pacote foi instalado (quem depende dele)

Como verificar a instalação depois de concluída? Duas formas:

• Veja dependências e atribuição de bundle: dsh plugin --profile web list mostra dependências; para ver se está na camada de bundle, olhe diretamente no package.json do profile (o dsh.profile.bundles acima).
• Veja se está realmente montado na árvore de configuração: dsh --profile web --dump-config imprime a árvore de configuração completa, procure pelo nome do plugin; para ver apenas a camada base do bundle, use dsh --profile web --dump-default-config.

Instale Três Plugins da Comunidade Que Você Vai Realmente Usar

Os plugins instalados antes eram para explicar o mecanismo, e também eram coisas que realmente eram necessárias no processo — o dsh é exatamente assim, instale o que quiser, tudo é plugin. Agora vamos instalar três plugins da comunidade que "melhoram instantaneamente a experiência", exatamente de fontes GitHub e npm. Não precisa digitar comandos você mesmo, basta passar para o dsh.

dsh-theme: troque a skin da Web UI

Um plugin de tema independente; após instalar, Configurações tem uma nova "Aparência":

• Três modos de aparência: claro / escuro / seguir sistema
• 15 temas curados, incluindo 5 temas orientados a leitura + 1 tema Carbon Code orientado a código
• Cada tema empacota níveis de cor, fonte UI, fonte de código, tamanho de fonte em uma configuração unificada, alternável com um clique
• Ajuste cor de destaque, fundo, primeiro plano, superfície, cor da barra lateral individualmente em tempo real
• Configurações são armazenadas no navegador localmente, não se perdem ao atualizar (não sincronizado entre navegadores ou profiles)

Para fazer o dsh instalar para você, envie na caixa de entrada:

Help me install the dsh-theme plugin to the web profile and confirm it's working; it's in the oil-oil/dsh-theme repo on GitHub.

Open source: oil-oil/dsh-theme. Após instalar reiniciar o profile web, Configurações → Aparência permite trocar temas, fica assim:

dsh-oil-sticky-prompt: fixe a mensagem mais recente do usuário no topo ao rolar

Ao rolar por uma resposta longa, a mensagem mais recente do usuário se torna uma barra compacta de largura total fixada no topo da conversa, clique para voltar ao original:

• Barra sticky única, vários tópicos não conflitam
• Novas linhas originais achatadas para espaços, máximo de duas linhas
• Não modifica a mensagem, não toca no log de sessão, não persiste configurações

Para fazer o dsh instalar para você, envie na caixa de entrada:

Help me install the dsh-oil-sticky-prompt plugin to the web profile and confirm it's working; it's in the oil-oil/dsh-oil-sticky-prompt repo on GitHub.

Open source: oil-oil/dsh-oil-sticky-prompt. Após instalar reiniciar o dsh. A imagem abaixo é uma conversa do dsh realmente instalando para mim — ele explicou que o aviso de Peer dependency é um comportamento esperado, e notou que terá efeito quando o profile web for reiniciado em seguida:

dsh-better-sidebar: transforme a barra lateral em uma bancada de trabalho completa

O mais rico em recursos, transformando a barra lateral direita em uma "bancada de trabalho". Sua filosofia de layout é a mesma linha das barras laterais de ferramentas de programação de IA como Codex — movendo arquivos, terminais, Git para ficarem ao lado do Agent, observar enquanto trabalha:

• Bancada de arquivos: árvore de diretórios + editor de código, pré-visualização inline para imagens / Markdown / HTML / PDF / Office
• Navegador embutido: múltiplas abas de páginas web, conteúdo executado em iframe sandboxed
• Terminal real: xterm + node-pty executa um shell real, reconecta ao desconectar, opcionalmente injeta ferramentas de terminal ao modelo
• Painel Git: diff real, histórico, clique direito stage / commit / revert
• Página de jobs em background: veja topologia de subagent e jobs em background (exit code / saída ao vivo / finalizar à força)
• Barra lateral direita + painel inferior bancada dupla, layout lembrado pela sessão

Para fazer o dsh instalar para você, envie na caixa de entrada:

Help me install the dsh-better-sidebar plugin to the web profile and confirm it's working; it's in the omdsh-dev/DSH-better-sidebar repo on GitHub (npm package name dsh-better-sidebar).

Open source: omdsh-dev/DSH-better-sidebar. Após instalar reiniciar o dsh, então faça um hard-refresh no navegador para ver a barra lateral (é um membro de bundle, só carrega ao reiniciar), o navegador de arquivos à direita + terminal inferior aparecem juntos:

Todos esses três têm declarações bundle, eles auto-montam ao instalar (o mecanismo em ③). Na primeira vez que você instalar esses dois da fonte GitHub, se bloqueado pelo allowBuilds do pnpm, trate de acordo com a entrada em "Armadilhas comuns".

Armadilhas Comuns

Problema	O que está acontecendo	Como lidar
Instalado mas nenhuma mudança na UI?	Se você instalou um membro de bundle, um profile em execução não vai auto-recarregar	Reinicie o dsh e verifique Configurações novamente
O primeiro add de um plugin de fonte Git reporta erro de allowBuilds?	pnpm ≥10 por padrão impede pacotes de fonte de executar scripts de build prepare	Conforme a dica impressa no erro, copie a chave allow para pnpm-workspace.yaml no diretório do profile, então re-execute add
Instalar dsh-better-sidebar reporta "Ignored build scripts"?	pnpm 11 interceptou scripts de build de módulos nativos como node-pty	Execute pnpm approve-builds --all no diretório do profile (C:\Users\<seu-usuário>\.dsh\profiles\web), então faça hard-refresh
Duas barras laterais aparecem após instalar?	Uma linha que você montou manualmente antes foi duplamente montada com o auto bundle	Remova a linha de montagem manual antiga - insert: ... better-sidebar ... em cordis.patch.yml
Instalado no ambiente errado?	--profile decide onde instalar	Confirme que o nome do profile no comando é o que você quer (web / headless …)
Instalado mas sem efeito, sem erro?	Você pode ter instalado uma dependência regular (sem declaração dsh.bundle)	É apenas "pacote chegou", capacidades precisam ser inseridas por você mesmo em cordis.patch.yml para conectar (mcp-client é o caso típico)

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Indique as quatro fontes de plugin (npm / GitHub / diretório local / tarball), e que o Plugin Market não é uma fonte mas uma entrada gráfica
• [ ] Saiba que dsh plugin --profile <nome> gerencia os plugins de um profile, instalando em seu node_modules
• [ ] Distinga: corpo do dsh instalado globalmente, plugins por profile, $DSH_HOME/cordis.patch.yml em nível de máquina e em todo o site
• [ ] Conheça os três métodos de instalação: add por linha de comando / instalação com um clique pelo mercado / dependência com declaração dsh.bundle auto-monta
• [ ] Indique a finalidade dos três plugins da comunidade (dsh-theme skins / dsh-oil-sticky-prompt barra de prompt sticky / dsh-better-sidebar bancada de barra lateral), e instale-os você mesmo
• [ ] Saiba que mudanças em membros de bundle exigem reinicialização do profile, edições regulares de patch passam por hot-reload
• [ ] Use list / remove / update para gerenciar plugins, use --dump-config para verificar se está montado na árvore de configuração