DeepSeek Harness: Carregando Plugins Locais

Q: Qual a diferença entre cordis.yml e dsh.config.yaml?

cordis.yml é a configuração do framework Cordis, gerenciando carregamento e substituições de plugins. dsh.config.yaml é a configuração da aplicação DSH, gerenciando modos, políticas de aprovação, etc. Eles se complementam e não entram em conflito.

Q: O cordis.yml será lido sem --patch?

Não. Sem --patch , o DSH usa a configuração padrão e ignora o cordis.yml. Isso é intencional — para evitar que a configuração de desenvolvimento afete acidentalmente a produção.

Q: O cordis.patch.yml pode ser colocado em outro lugar?

Atualmente apenas cordis.patch.yml na raiz do projeto é suportado. Se precisar de múltiplos conjuntos de patch, você pode trocar manualmente o conteúdo do arquivo.

Q: Preciso reiniciar após modificar a configuração?

Sim, você precisa reiniciar dsh web --patch para que alterações no cordis.yml entrem em vigor. Veja 18-hot-reload.md para mecanismos HMR.

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

Entender o mecanismo de carregamento de plugins é o salto-chave de "escreveu um plugin" para "desenvolver plugins eficientemente." cordis.yml é o hub de configuração do DSH, e o mecanismo de sobreposição --patch permite sobrepor plugins locais flexivelmente sem modificar a configuração padrão.

💡 Dica: A ideia central do mecanismo --patch é "sobrepor, não substituir" — a configuração padrão permanece inalterada, e suas modificações locais são sobrepostas encima. Isso permite que depuração de desenvolvimento e implantação de produção compartilhem a mesma configuração base.

📋 Pré-requisitos: Ter completado 11-first-plugin.md, capaz de criar um plugin mínimo

1. O Que Você Vai Aprender

Detalhes do arquivo de configuração cordis.yml
Operações $insert e $replace
Seleção entre caminho absoluto vs. relativo
Princípios do mecanismo de sobreposição --patch
--dump-config para visualizar configuração final
Fluxo de trabalho de desenvolvimento e depuração local

Fluxo de Carregamento de Patch

2. Detalhes da Configuração cordis.yml

(1) Localização do Arquivo de Configuração

cordis.yml é o arquivo de configuração central do DSH, localizado na raiz do projeto:

TEXT 📖 Somente leitura

my-dsh-project/
├── cordis.yml        ← Configuração principal
├── cordis.patch.yml  ← Configuração de patch (opcional)
├── package.json
└── src/

(2) Estrutura Básica

▶ Exemplo 1: Estrutura do cordis.yml

YAML

# Estrutura básica do cordis.yml
plugins:
  plugin-name:
    # Itens de configuração do plugin
    enabled: true
    config:
      key: value

# Configuração global
hostname: localhost
port: 5173

(3) Formato de Entrada de Plugin

Cada entrada de plugin contém três informações:

Campo	Descrição	Exemplo
Nome do plugin	A chave é o identificador do plugin	`my-plugin:`
Caminho	De onde carregar	`$insert` ou nome do pacote npm
Configuração	Parâmetros passados ao plugin	Campos sob `config:`

YAML

plugins:
  # Plugin de pacote npm
  @dsh-plugin/database:
    config:
      connection: "postgresql://localhost/mydb"
  
  # Plugin local
  my-local-plugin:
    $insert: /home/alice/dev/my-plugin
    config:
      debug: true

3. Operações $insert e $replace

(1) $insert: Adicionar um Plugin

▶ Exemplo 2: Inserindo um Plugin Local

$insert adiciona um plugin à lista de plugins existente:

YAML

plugins:
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool

O efeito é equivalente a:

TEXT 📖 Somente leitura

Lista padrão de plugins: [core, llm, tools, shell, ...]
Após insert:       [core, llm, tools, shell, ..., my-tool]

(2) $replace: Substituir um Plugin

$replace substitui um plugin existente por uma nova implementação:

YAML

plugins:
  # Substituir o adaptador LLM padrão por um customizado
  llm:
    $replace: /home/alice/dev/custom-llm-adapter

Efeito:

TEXT 📖 Somente leitura

Padrão: llm → @deepseek-ai/dsh-plugin-llm
Substituído: llm → /home/alice/dev/custom-llm-adapter

⚠️ $replace deve especificar um nome de plugin existente; não é possível substituir uma entrada inexistente.

(3) Combinando Insert e Replace

YAML

plugins:
  # Adicionar ferramenta local
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool
  
  # Substituir shell padrão por versão segura
  shell:
    $replace: /home/alice/dev/dsh-plugin-safe-shell
  
  # Adicionar outro plugin local
  my-monitor:
    $insert: /home/alice/dev/dsh-plugin-monitor

(4) Prioridade das Operações

Quando o mesmo plugin tem $insert e $replace:

TEXT 📖 Somente leitura

Prioridade: $replace > $insert

Se o alvo de $replace não existe, ele recua para o comportamento de $insert.

4. Estratégia de Caminhos

(1) Caminhos Absolutos

YAML

plugins:
  my-plugin:
    $insert: /home/alice/dev/my-plugin

Vantagens:

Não é afetado pelo diretório de trabalho
Caminho claro durante depuração
Configuração reutilizável entre projetos

Desvantagens:

Caminho de usuário fixo, não portátil
Membros da equipe têm caminhos diferentes

(2) Caminhos Relativos

YAML

plugins:
  my-plugin:
    $insert: ./plugins/my-plugin

Caminhos relativos são resolvidos com base no diretório que contém cordis.yml.

Vantagens:

Portátil, adequado para colaboração em equipe
Plugins podem ser versionados com o projeto

Desvantagens:

Depende do diretório de trabalho na inicialização
Cálculo de caminho é complexo para diretórios aninhados

(3) Recomendações de Seleção de Caminho

Cenário	Recomendado	Motivo
Desenvolvimento pessoal	Caminho absoluto	Claro, sem ambiguidade
Colaboração em equipe	Caminho relativo	Portátil, consistente entre ambientes
CI/CD	Caminho relativo	Caminhos do ambiente de build variam
Depuração temporária	Caminho absoluto	Rápido para localizar, sem problemas de caminho

5. Mecanismo de Sobreposição --patch

(1) Modelo de Camadas de Configuração

A configuração do DSH é construída a partir de múltiplas camadas:

graph TB
    BASE[Camada Base<br/>Configuração Padrão] --> BUNDLE[Camada Bundle<br/>dsh-base / dsh-web-app]
    BUNDLE --> PROFILE[Camada Profile<br/>web / headless]
    PROFILE --> PATCH[Camada Patch<br/>cordis.yml + --patch]
    PATCH --> FINAL[Configuração Final]

Cada camada sobrepõe itens de configuração de mesmo nome da camada anterior, similar à prioridade de cascata CSS.

(2) Parâmetro --patch

BASH

# Aplicar camada de patch na inicialização
pnpm dsh web --patch

Sem --patch, o DSH lê apenas a configuração padrão e ignora $insert/$replace no cordis.yml. Com --patch, as operações de substituição no cordis.yml entram em vigor.

(3) cordis.patch.yml

Além da configuração principal, você pode usar cordis.patch.yml como uma camada de patch extra:

YAML

# cordis.patch.yml — apenas para ambientes de desenvolvimento
plugins:
  debug-tools:
    $insert: ./dev-plugins/debug-tools

--patch lê tanto cordis.yml quanto cordis.patch.yml, com o último tendo prioridade mais alta.

(4) Regras de Mesclagem de Sobreposição

TEXT 📖 Somente leitura

Config base:  { a: 1, b: 2, c: 3 }
Camada patch: { b: 20, d: 4 }
─────────────────────────────
Config final: { a: 1, b: 20, c: 3, d: 4 }

Campos com mesmo nome: Camada patch sobrepõe a camada base
Novos campos: Adicionados diretamente
Campos não afetados: Permanecem inalterados

6. --dump-config para Visualizar Configuração Final

(1) Uso Básico

▶ Exemplo 3: Visualizando Configuração Mesclada

BASH

pnpm dsh web --patch --dump-config

Exibe a configuração final completamente mesclada:

YAML

# === Configuração Mesclada ===
hostname: localhost
port: 5173
plugins:
  core:
    enabled: true
  llm:
    enabled: true
    config:
      provider: deepseek
  tools:
    enabled: true
  my-tool:              # ← Seu insert
    $insert: /home/alice/dev/my-tool
    config:
      debug: true
  debug-tools:          # ← Adicionado pelo patch.yml
    $insert: ./dev-plugins/debug-tools

(2) Depurando Problemas de Configuração

Quando um plugin não carrega como esperado, use --dump-config para investigar:

BASH

# Passos de troubleshooting
pnpm dsh web --patch --dump-config > config-dump.yml
# Verifique se seu plugin aparece na configuração final
# Verifique se o caminho $insert está correto

(3) Visualizar Apenas Plugin Específico

BASH

# Filtrar para ver configuração de plugin específico
pnpm dsh web --patch --dump-config | grep -A 10 "my-plugin"

7. Fluxo de Trabalho de Desenvolvimento e Depuração Local

(1) Loop de Desenvolvimento Padrão

graph LR
    CODE[Escrever Código do Plugin] --> REG[Registrar no cordis.yml]
    REG --> START[Iniciar dsh web --patch]
    START --> TEST[Testar Comportamento do Plugin]
    TEST --> BUG{Bugs?}
    BUG -->|Sim| CODE
    BUG -->|Não| DONE[Concluído]

(2) Dicas para Iteração Rápida

Fluxo de trabalho típico de Alice ao desenvolver um plugin de ferramenta:

BASH

# 1. Configuração única do cordis.yml
cat > cordis.yml << 'EOF'
plugins:
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool
EOF

# 2. Loop de desenvolvimento
# Editar código → reiniciar → testar
pnpm dsh web --patch
# Ao terminar os testes, Ctrl+C para parar

# 3. Verificar configuração
pnpm dsh web --patch --dump-config | grep my-tool

(3) Desenvolvimento Paralelo de Múltiplos Plugins

Bob desenvolvendo dois plugins simultaneamente:

YAML

# cordis.yml
plugins:
  tool-a:
    $insert: /home/bob/dev/dsh-plugin-a
  tool-b:
    $insert: /home/bob/dev/dsh-plugin-b

Desenvolva em terminais separados; ambos os plugins carregam ao reiniciar o DSH.

(4) Desabilitando Temporariamente um Plugin

Sem necessidade de desinstalar — basta comentar na configuração:

YAML

plugins:
  my-tool:
    $insert: /home/alice/dev/my-tool
  # experimental-tool:       # Temporariamente desabilitado
  #   $insert: /home/alice/dev/exp-tool

❓ Perguntas Frequentes

P Qual a diferença entre cordis.yml e dsh.config.yaml?

R cordis.yml é a configuração do framework Cordis, gerenciando carregamento e substituições de plugins. dsh.config.yaml é a configuração da aplicação DSH, gerenciando modos, políticas de aprovação, etc. Eles se complementam e não entram em conflito.

P O que acontece se o caminho $insert aponta para um diretório sem package.json?

R O DSH tentará carregar o diretório como um plugin. Se campos obrigatórios (como a entrada principal) estiverem ausentes, reportará um erro e pulará. Recomendamos sempre garantir que diretórios de plugins locais tenham um package.json.

P O cordis.yml será lido sem --patch?

R Não. Sem --patch, o DSH usa a configuração padrão e ignora o cordis.yml. Isso é intencional — para evitar que a configuração de desenvolvimento afete acidentalmente a produção.

P O cordis.patch.yml pode ser colocado em outro lugar?

R Atualmente apenas cordis.patch.yml na raiz do projeto é suportado. Se precisar de múltiplos conjuntos de patch, você pode trocar manualmente o conteúdo do arquivo.

P Preciso reiniciar após modificar a configuração?

R Sim, você precisa reiniciar dsh web --patch para que alterações no cordis.yml entrem em vigor. Veja 18-hot-reload.md para mecanismos HMR.

📖 Resumo

cordis.yml é o hub de configuração de plugins do DSH, contendo caminhos de plugins e itens de configuração
$insert adiciona plugins, $replace substitui plugins existentes
Caminhos absolutos para desenvolvimento pessoal, caminhos relativos para colaboração em equipe
--patch habilita o mecanismo de sobreposição, sobrepondo cordis.yml à configuração padrão
--dump-config mostra a configuração final mesclada — uma ferramenta poderosa para troubleshooting de problemas de carregamento
Loop de desenvolvimento: editar código → registrar no cordis.yml → dsh web --patch → testar

📝 Exercícios

1. ⭐ Básico： Registre o plugin hello-world da lição anterior usando $insert no cordis.yml, e use --dump-config para confirmar que ele aparece na configuração final.

2. ⭐⭐ Intermediário： Registre o mesmo plugin usando caminhos absolutos e relativos, e use --dump-config para comparar as diferenças de saída entre as duas configurações.

3. ⭐⭐⭐ Desafio： Crie dois plugins locais A e B, e use $insert para ambos no cordis.yml. Tente usar $replace para substituir um dos plugins de ferramenta built-in do DSH pela sua versão customizada, e verifique a substituição com --dump-config.

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