DeepSeek Harness: Instalação de Plugins e Ordem de…

Q: Posso instalar de um registro npm privado?

Sim. Configure .npmrc : text @dsh-plugin:registry=https://my-registry.com/

Q: Múltiplos arquivos de patch podem ser sobrepostos?

Atualmente apenas um cordis.patch.yml é suportado. Se precisar de múltiplos patches, mescle-os em um único arquivo.

Q: Como desinstalar completamente um plugin?

bash # 1. Remover entrada do plugin do cordis.yml # 2. Desinstalar pacote npm pnpm remove @dsh-plugin/database # 3. Reiniciar DSH

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

De "escrever plugins" para "usar plugins" — esta aula foca na instalação prática de plugins e gerenciamento de configuração. Quatro métodos de instalação cobrem todos os cenários, a prioridade de carregamento de configuração garante que "local sobrescreve global", e hot patches tornam as mudanças de emergência em produção seguras e controláveis.

💡 Dica: O passo mais importante após instalar um plugin é --dump-config — confirme que seu plugin realmente aparece na configuração final. Muitos problemas de "plugin não funciona" são apenas erros de prioridade de configuração.

📋 Pré-requisitos: Completou 12-local-plugin.md e 26-bundle-profile.md

1. O Que Você Vai Aprender

Instalação de plugins via npm
Instalação direta de repositório GitHub
Instalação via tarball
Prioridade de carregamento de configuração
Hot patches com cordis.patch.yml
Resolução de conflitos de plugins

Ordem de Carregamento de Config

2. Instalação de Plugins via npm

▶ Exemplo 1：

BASH

# Instalar versão mais recente
pnpm add @dsh-plugin/database

# Instalar versão específica
pnpm add @dsh-plugin/database@1.2.0

# Instalar como devDependency
pnpm add -D @dsh-plugin/debug-tools

(2) Registro Pós-Instalação

Plugins instalados via npm precisam ser registrados no cordis.yml:

YAML

# cordis.yml
plugins:
  '@dsh-plugin/database':
    config:
      connection: 'postgresql://localhost/mydb'

(3) Usando dsh plugin add

O DSH fornece um comando de instalação mais conveniente:

BASH

# Instalar e registrar automaticamente
dsh plugin add @dsh-plugin/database

# Instalar com configuração
dsh plugin add @dsh-plugin/database --config.connection='postgresql://localhost/mydb'

# Saída da instalação
📦 Installing @dsh-plugin/database@1.2.0...
✅ Plugin installed and registered!

▶ Exemplo 4：

JSON

// package.json
{
  "dependencies": {
    "@dsh-plugin/database": "^1.2.0",
    "@dsh-plugin/redis": "~2.1.0"
  }
}

Símbolo	Significado	Intervalo de Atualização
`^1.2.0`	Compatível com 1.x	1.2.0 ~ 1.9.9
`~2.1.0`	Compatível com 2.1.x	2.1.0 ~ 2.1.9
`1.2.0`	Versão exata	Apenas 1.2.0

3. Instalação Direta de Repositório GitHub

(1) Métodos de Instalação

BASH

# Instalar branch padrão
pnpm add github:alice/dsh-plugin-redis

# Instalar branch específica
pnpm add github:alice/dsh-plugin-redis#feature/cluster

# Instalar tag específica
pnpm add github:alice/dsh-plugin-redis#v2.1.0

# Instalar commit específico
pnpm add github:alice/dsh-plugin-redis#abc1234

(2) Usando dsh plugin add

BASH

dsh plugin add github:alice/dsh-plugin-redis

(3) Observações sobre Instalação via GitHub

Observação	Descrição
Requer Git	Git deve estar instalado na máquina
Estrutura do repo	Deve ser um pacote Node.js válido (ter package.json)
Etapa de build	O repo pode precisar ser compilado primeiro
Rede	Requer acesso ao GitHub
Bloqueio de versão	Prefira hash de commit ao nome de branch

(4) Representação no package.json

JSON

{
  "dependencies": {
    "@dsh-plugin/redis": "github:alice/dsh-plugin-redis#v2.1.0"
  }
}

4. Instalação via Tarball

(1) Instalar a partir de URL

BASH

# Instalar de tarball remoto
pnpm add https://example.com/dsh-plugin-custom-1.0.0.tgz

# Instalar de tarball local
pnpm add ./packages/dsh-plugin-custom-1.0.0.tgz

(2) Criando um tarball com npm pack

BASH

# No projeto do plugin
cd dsh-plugin-my-tool
npm pack
# Gera: dsh-plugin-my-tool-1.0.0.tgz

# No projeto DSH
pnpm add ../dsh-plugin-my-tool/dsh-plugin-my-tool-1.0.0.tgz

(3) Casos de Uso de Tarball

Cenário	Descrição
Plugins privados	Não publicados no npm, distribuir tgz diretamente
Instalação offline	Sem acesso ao npm ou GitHub
CI/CD	Instalar artefatos de build diretamente
Teste de pré-lançamento	Instalar versões candidatas para teste

(4) Comparação dos Três Métodos de Instalação

Método	Comando	Rede Necessária	Gerenciamento de Versão	Ideal Para
npm	`pnpm add @dsh-plugin/xxx`	npm registry	✅ semver	Plugins públicos
GitHub	`pnpm add github:user/repo`	GitHub	⚠️ branch/tag	Plugins em desenvolvimento
tarball	`pnpm add ./xxx.tgz`	Nenhuma	❌ manual	Privados/offline

5. Prioridade de Carregamento de Configuração

(1) Cinco Camadas de Prioridade

graph TB
    L5["Camada 5: Parâmetros CLI<br/>(maior prioridade)"]
    L4["Camada 4: cordis.patch.yml"]
    L3["Camada 3: cordis.yml do projeto"]
    L2["Camada 2: Configuração do Profile"]
    L1["Camada 1: Padrões do Bundle<br/>(menor prioridade)"]
    L5 --> L4 --> L3 --> L2 --> L1

▶ Exemplo 2：

TEXT 📖 Somente leitura

Padrões do Bundle:    plugins: [core, llm, tools], port: 5173
Profile (web):        plugins: [+web-ui]
Config do projeto:    plugins: [+my-tool], port: 8080
Patch:                plugins: [+debug-tools], debug: true
CLI:                  port: 3000

Final:                plugins: [core, llm, tools, web-ui, my-tool, debug-tools]
                      port: 3000, debug: true

(3) Tratamento de Plugins de Mesmo Nome

Quando múltiplas camadas registram o mesmo nome de plugin, camadas de maior prioridade sobrescrevem as de menor:

TEXT 📖 Somente leitura

Bundle:            llm → deepseek-adapter
Config projeto:    llm → openai-adapter (sobrescreve)
Patch:             llm → custom-adapter (sobrescreve novamente)

Final: llm → custom-adapter

(4) Visualizando a Ordem de Carregamento

BASH

pnpm dsh web --patch --dump-config

A saída marca a camada de origem para cada valor de configuração.

6. Hot Patches com cordis.patch.yml

(1) Finalidade do Hot Patch

Hot patches ajustam temporariamente as configurações sem modificar a configuração base:

YAML

# cordis.patch.yml
plugins:
  debug-tools:
    $insert: ./dev-plugins/debug-tools
  llm:
    config:
      debug: true

(2) Habilitando Hot Patches

BASH

# Deve adicionar --patch para carregar o arquivo de patch
pnpm dsh web --patch

(3) Hot Patches em Produção

Ao encontrar problemas urgentes em produção, use um patch para correções rápidas:

YAML

# cordis.patch.prod.yml — Desabilitar plugin problemático de emergência
plugins:
  problematic-plugin:
    enabled: false
  llm:
    config:
      maxRetries: 5  # Aumentar tentativas temporariamente

(4) Rollback de Hot Patch

BASH

# Aplicar hot patch
cp cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch

# Reverter hot patch (excluir arquivo de patch)
rm cordis.patch.yml
pnpm dsh web

(5) Hot Patches e Git

TEXT 📖 Somente leitura

# .gitignore
cordis.patch.yml           # Ignorar patch atual
cordis.patch.prod.yml      # Ignorar patch de produção
# cordis.patch.dev.yml    # Commitar patch de dev (para compartilhamento com a equipe)

7. Resolução de Conflitos de Plugins

(1) Tipos Comuns de Conflito

Tipo de Conflito	Manifestação	Causa
Tool de mesmo nome	Registro posterior sobrescreve anterior	Dois plugins registram o mesmo nome de tool
Service de mesmo nome	Registro posterior sobrescreve anterior	Dois Providers registram o mesmo nome de service
Conflito de configuração	Valor de config não entra em vigor	Camada de prioridade incorreta
Incompatibilidade de versão	Erros em tempo de execução	Versão do plugin incompatível com o core do DSH

(2) Conflito de Tool de Mesmo Nome

TEXT 📖 Somente leitura

Plugin A: registra tool 'search'
Plugin B: registra tool 'search'
→ Final: A search do Plugin B entra em vigor

Solução:

YAML

# Desabilitar um deles
plugins:
  plugin-a:
    config:
      tools:
        disabled: ['search']

Ou usar isolamento via realm.

(3) Diagnóstico de Conflito de Configuração

BASH

# 1. Visualizar configuração final
pnpm dsh web --patch --dump-config > dump.yml

# 2. Buscar itens de configuração conflitantes
grep "my-plugin" dump.yml

# 3. Verificar se foi sobrescrito pelo patch
diff cordis.yml cordis.patch.yml

(4) Compatibilidade de Versão

BASH

# Verificar compatibilidade do plugin
dsh plugin check @dsh-plugin/database

# Saída
✅ @dsh-plugin/database@1.2.0 is compatible with dsh@0.5.0
⚠️ Requires: dsh >= 0.4.0

(5) Árvore de Decisão para Resolução de Conflitos

graph TD
    CONFLICT{Tipo de conflito?}
    CONFLICT -->|Tool/Service de mesmo nome| SCOPE{Precisa de ambos?}
    SCOPE -->|Não| DISABLE[Desabilitar um]
    SCOPE -->|Sim| REALM[Isolar com realm]
    CONFLICT -->|Config não entra em vigor| DUMP[Diagnóstico com --dump-config]
    DUMP --> FIX[Corrigir prioridade de configuração]
    CONFLICT -->|Versão incompatível| UPDATE[Atualizar versão do plugin]
    UPDATE --> CHECK[Verificar compatibilidade]

❓ Perguntas Frequentes

P Preciso reiniciar após instalar um plugin?

R Sim. Plugins instalados requerem reinicialização do DSH para serem carregados. O HMR apenas atualiza em tempo real mudanças de código em plugins existentes; não pode carregar plugins recém-instalados.

P Posso instalar de um registro npm privado?

R Sim. Configure .npmrc: text @dsh-plugin:registry=https://my-registry.com/

P Múltiplos arquivos de patch podem ser sobrepostos?

R Atualmente apenas um cordis.patch.yml é suportado. Se precisar de múltiplos patches, mescle-os em um único arquivo.

P Como visualizar as versões de todos os plugins instalados?

R bash dsh plugin list # Ou pnpm list | grep dsh-plugin

P O que fazer se a instalação do plugin falhar?

R Verifique a conexão de rede, acessibilidade do registro npm e correção do nome do pacote. Verifique pnpm-error.log para informações detalhadas do erro.

P Como desinstalar completamente um plugin?

bash # 1. Remover entrada do plugin do cordis.yml # 2. Desinstalar pacote npm pnpm remove @dsh-plugin/database # 3. Reiniciar DSH

📖 Resumo

Quatro métodos de instalação: npm (padrão), GitHub (em desenvolvimento), tarball (privado/offline), caminho local (desenvolvimento)
Cinco camadas de prioridade de configuração: Bundle → Profile → Projeto → Patch → CLI
--dump-config é a ferramenta principal para diagnosticar problemas de configuração
cordis.patch.yml para sobreposições temporárias; --patch o habilita
Conflitos de plugins resolvidos através de desabilitação, isolamento via realm ou ajuste de prioridade
Compatibilidade de versão verificada via dsh plugin check

📝 Exercícios

1. ⭐ Básico： Instale um plugin comunitário via npm (ex.: @dsh-plugin/database), registre e configure-o no cordis.yml, e use --dump-config para confirmar que a configuração entra em vigor.

2. ⭐⭐ Intermediário： Crie um cordis.patch.yml que sobrescreva uma configuração de plugin na camada de patch (ex.: altere o modelo padrão do LLM). Use --dump-config para comparar diferenças de configuração com e sem o patch.

3. ⭐⭐⭐ Desafio： Simule um cenário de conflito de plugins — instale dois plugins que registram tools de mesmo nome, observe o posterior sobrescrevendo o anterior. Depois use isolamento via realm para que ambos tenham espaços de tools independentes.

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