DeepSeek Harness: Bundle e Profile

Q: Como resolver conflitos de camadas de configuração?

Use --dump-config para visualizar a configuração final: bash pnpm dsh web --patch --dump-config Isso mostra o resultado de todas as camadas mescladas, facilitando a localização da fonte do conflito.

Q: Posso usar o DSH sem nenhum bundle integrado?

Sim, use --bundle dsh-base para carregar apenas o conjunto core mínimo e monte o seu próprio via cordis.yml.

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

Um projeto DSH pode precisar de múltiplas configurações de execução — uma para desenvolvimento Web UI, outra para implantação headless, outra para testes de CI. Um Profile é um esquema de montagem nomeado; um Bundle é um pacote de configuração + código distribuível. Juntos, eles tornam a implantação do DSH tão simples quanto trocar de canal.

💡 Dica: Um profile é "quais plugins selecionar"; um bundle é "como configurá-los." O Profile seleciona a combinação; o Bundle configura os detalhes. Entenda essa camada e você terá dominado a arquitetura de configuração do DSH.

📋 Pré-requisitos: Completou 12-local-plugin.md, entende a configuração cordis.yml

1. O Que Você Vai Aprender

profile: montagens nomeadas (web/headless)
bundle: formato de distribuição de configuração + código
campos dsh.profile e dsh.bundle
dsh-base / dsh-web-app / dsh-headless
Ordem de composição das camadas de configuração
Mecanismo de sobreposição de patch

2. profile: Montagem Nomeada

(1) Conceito de profile

Um profile é um esquema de combinação de plugins predefinido, identificado por nome:

TEXT 📖 Somente leitura

web profile:       → Inclui plugins Web UI, ferramentas interativas
headless profile:  → Sem UI, execução pura via API + script
ci profile:        → Conjunto mínimo de plugins, apenas o que os testes precisam

(2) Configurando um profile

Declare profiles no package.json:

JSON

{
  "name": "my-dsh-project",
  "dsh": {
    "profiles": {
      "web": {
        "description": "Web UI mode for interactive development",
        "plugins": [
          "@deepseek-ai/dsh-web-app",
          "@deepseek-ai/dsh-plugin-tools-interactive"
        ]
      },
      "headless": {
        "description": "Headless mode for automation",
        "plugins": [
          "@deepseek-ai/dsh-headless",
          "@deepseek-ai/dsh-plugin-tools-basic"
        ]
      }
    }
  }
}

▶ Exemplo 3：

BASH

# Usar profile web
pnpm dsh web --profile web

# Usar profile headless
pnpm dsh headless --profile headless

(4) Composição do profile

Componente	Descrição
Lista de plugins	Quais plugins incluir
Descrição	Finalidade do profile
Configuração padrão	Parâmetros padrão para os plugins

3. bundle: Formato de Distribuição de Configuração + Código

(1) Conceito de bundle

Um bundle é um formato de empacotamento profile + configuração + código, distribuível como um pacote npm:

TEXT 📖 Somente leitura

profile:  Quais plugins selecionar
bundle:   Plugins + config + bloqueio de versão → pacote distribuível

▶ Exemplo 2：

TEXT 📖 Somente leitura

dsh-bundle-my-team/
├── package.json        ← campo dsh.bundle
├── cordis.yml          ← Configuração padrão
├── plugins/
│   ├── team-tools/     ← Plugin integrado
│   └── team-lint/      ← Plugin integrado
└── profiles/
    ├── web.yml         ← Configuração do profile web
    └── headless.yml    ← Configuração do profile headless

▶ Exemplo 3：

JSON

{
  "name": "@my-team/dsh-bundle",
  "version": "1.0.0",
  "dsh": {
    "bundle": true,
    "profiles": {
      "web": "./profiles/web.yml",
      "headless": "./profiles/headless.yml"
    },
    "baseConfig": "./cordis.yml",
    "plugins": [
      "./plugins/team-tools",
      "./plugins/team-lint"
    ]
  }
}

(4) Instalando um bundle

BASH

# Instalar do npm
pnpm add @my-team/dsh-bundle

# Iniciar usando o profile do bundle
pnpm dsh web --bundle @my-team/dsh-bundle --profile web

4. dsh-base / dsh-web-app / dsh-headless

(1) Bundles Integrados

O DSH fornece três bundles integrados:

Bundle	Descrição	Plugins Principais Incluídos
dsh-base	Conjunto base mínimo	core, llm, sessions, trajectory
dsh-web-app	Versão completa Web UI	dsh-base + web-ui, interactive-tools
dsh-headless	Versão sem UI	dsh-base + headless-runner, basic-tools

(2) Relações de Dependência

graph TB
    BASE[dsh-base<br/>core + llm + sessions] --> WEB[dsh-web-app<br/>+ Web UI + ferramentas interativas]
    BASE --> HEADLESS[dsh-headless<br/>+ Headless runner + ferramentas básicas]

(3) Comportamento Padrão

Sem o parâmetro --bundle, o DSH usa por padrão dsh-web-app:

BASH

# Equivalente a pnpm dsh web --bundle dsh-web-app
pnpm dsh web

(4) Escolhendo um Bundle Base

BASH

# Bundle mínimo (apenas core)
pnpm dsh web --bundle dsh-base

# Bundle Web UI (padrão)
pnpm dsh web --bundle dsh-web-app

# Bundle headless
pnpm dsh headless --bundle dsh-headless

5. Ordem de Composição das Camadas de Configuração

(1) Sobreposição de Configuração em Múltiplas Camadas

A configuração final do DSH é composta por múltiplas camadas, com prioridade crescente de baixo para cima:

graph TB
    L1[Camada 1: Config padrão do Bundle<br/>cordis.yml] --> L2[Camada 2: Config do Profile<br/>profiles/web.yml]
    L2 --> L3[Camada 3: Config do projeto<br/>project cordis.yml]
    L3 --> L4[Camada 4: Config de Patch<br/>cordis.patch.yml]
    L4 --> L5[Camada 5: Parâmetros CLI<br/>--patch, --config]

(2) Regras de Sobreposição

TEXT 📖 Somente leitura

Bundle padrão: { plugins: [core, llm], port: 5173 }
Profile:       { plugins: [+web-ui], debug: true }
Config projeto: { plugins: [+my-tool], port: 8080 }
Patch:         { plugins: [+debug-tool] }

Final:         { plugins: [core, llm, web-ui, my-tool, debug-tool],
                port: 8080, debug: true }

(3) Mesclagem da Lista de Plugins

Operação	Efeito
Novo plugin	Adicionado diretamente
Plugin de mesmo nome	Camada posterior sobrescreve a anterior
`$insert`	Adicionado ao final da lista
`$replace`	Substitui plugin de mesmo nome

(4) Mesclagem de Valores de Configuração

TEXT 📖 Somente leitura

Inferior: { a: 1, b: { x: 1, y: 2 } }
Superior: { b: { y: 3, z: 4 }, c: 5 }

Resultado: { a: 1, b: { x: 1, y: 3, z: 4 }, c: 5 }

Objetos aninhados fazem merge profundo; valores escalares sobrescrevem diretamente.

6. Mecanismo de Sobreposição de Patch

(1) cordis.patch.yml

O arquivo de patch é a sobreposição de configuração de mais alta prioridade, adequado para ajustes temporários durante o desenvolvimento:

YAML

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

(2) Parâmetro --patch

BASH

# Aplicar camada de patch
pnpm dsh web --patch

# Não aplicar patch
pnpm dsh web

(3) Patches para Múltiplos Ambientes

TEXT 📖 Somente leitura

config/
├── cordis.yml              ← Configuração base
├── cordis.patch.dev.yml    ← Patch de desenvolvimento
├── cordis.patch.staging.yml ← Patch de staging
└── cordis.patch.prod.yml   ← Patch de produção

Trocando de ambiente:

BASH

# Desenvolvimento
cp config/cordis.patch.dev.yml cordis.patch.yml
pnpm dsh web --patch

# Produção
cp config/cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch

(4) Sobreposição Direta via CLI

O método de configuração de mais alta prioridade:

BASH

# Sobrescrever porta diretamente
pnpm dsh web --config.port=8080

# Sobrescrever modelo LLM diretamente
pnpm dsh web --config.plugins.llm.config.model=deepseek-reasoner

❓ Perguntas Frequentes

P Qual a relação entre profile e bundle?

R Um bundle contém profiles. Um bundle pode definir múltiplos profiles (web/headless/ci etc.); você seleciona um na inicialização.

P Posso usar o DSH sem escrever campos dsh?

R Sim. O DSH usa por padrão o bundle dsh-web-app com configuração padrão. Os campos dsh são necessários apenas para personalização.

P Qual a diferença entre um bundle e um pacote npm?

R Um bundle é um superconjunto de um pacote npm — é um pacote npm com campos dsh.bundle adicionais que informam ao DSH como carregar configurações e plugins.

P Como resolver conflitos de camadas de configuração?

R Use --dump-config para visualizar a configuração final: bash pnpm dsh web --patch --dump-config Isso mostra o resultado de todas as camadas mescladas, facilitando a localização da fonte do conflito.

P Posso usar o DSH sem nenhum bundle integrado?

R Sim, use --bundle dsh-base para carregar apenas o conjunto core mínimo e monte o seu próprio via cordis.yml.

P Arquivos de patch devem ser commitados no git?

R Patches de desenvolvimento podem ser commitados (para compartilhamento com a equipe); patches de produção não devem (contêm configurações sensíveis). Recomenda-se .gitignore excluindo cordis.patch.prod.yml.

📖 Resumo

profile é um esquema de montagem de plugins nomeado (web/headless/ci etc.)
bundle é profile + config + código em um pacote distribuível
Três bundles integrados: dsh-base (mínimo), dsh-web-app (Web UI), dsh-headless (sem UI)
Sobreposição de cinco camadas de configuração: Bundle → Profile → Projeto → Patch → CLI; camadas posteriores sobrescrevem anteriores
cordis.patch.yml é o arquivo de config de mais alta prioridade; --patch o habilita
--dump-config visualiza a configuração final mesclada; essencial para resolver conflitos

📝 Exercícios

1. ⭐ Básico： Adicione campos dsh.profiles ao package.json do seu projeto, definindo profiles web e headless. Inicie o DSH com cada profile e compare as listas de plugins carregados.

2. ⭐⭐ Intermediário： Crie um cordis.patch.dev.yml que carregue o plugin debug-tools e habilite o log de requisições LLM no modo dev. Inicie com --patch e use --dump-config para verificar o efeito de sobreposição da camada de patch.

3. ⭐⭐⭐ Desafio： Crie um pacote bundle completo com um profile personalizado, dois plugins integrados e uma configuração padrão. Publique em um registro npm local (ou use o protocolo file:), instale a partir de outro projeto e inicie usando este bundle.

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