DeepSeek Harness: Introdução ao DeepSeek Harness

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

DeepSeek Harness (DSH) é o framework Agent de código aberto da DeepSeek, com a filosofia central de "tudo é um plugin" — dos adaptadores de modelo aos sistemas de ferramentas, do gerenciamento de sessões aos mecanismos de sandbox, todos são injetados em um contexto compartilhado como plugins, alcançando extensibilidade máxima.

💡 Dica: A inovação central do DSH está na arquitetura Cordis — plugins não chamam uns aos outros diretamente, mas contribuem serviços, eventos tipados e efeitos colaterais reversíveis para um contexto compartilhado. Esse design mantém os plugins totalmente desacoplados, de modo que adicionar novos recursos nunca requer modificar o código existente.

📋 Pré-requisitos: Nenhuma experiência prévia necessária; conhecimento básico de linha de comando é suficiente

1. O Que Você Vai Aprender

Posicionamento e filosofia central do DeepSeek Harness
Arquitetura de plugin Cordis: serviços, eventos, efeitos colaterais
Visão geral dos quatro modos de execução (Standard / PTC / Minimal / Creative)
DSH vs. outros frameworks Agent
Considerações de uso durante a fase de Developer Preview

Arquitetura de Plugins Cordis

2. A História de Seleção de uma Equipe de Engenharia de IA

(1) Dor: Fragmentação de Frameworks Agent

Alice é arquiteta em uma startup de IA. Sua equipe enfrentou um dilema de seleção de framework Agent no Q2 de 2026:

Claude Code: CLI oficial da Anthropic, mas travado em um único modelo sem opção de troca
Cursor: Excelente integração com IDE, mas capacidades Agent limitadas pelo ambiente do editor
OpenCode: Ferramenta CLI de código aberto, mas ecossistema de plugins fraco
AutoGPT: Conceito primeiro, mas estabilidade de produção insuficiente
LangChain: Orquestração flexível, mas alto custo de execução e depuração difícil

O gerente de produto Bob aumentou a pressão:

"Precisamos de um framework Agent agnóstico a modelo, com plugins encaixáveis, que suporte múltiplos modos de interação. Tem que entrar em ar em três meses."

(2) A Solução do DSH

Após avaliação, Alice escolheu DeepSeek Harness:

TEXT 📖 Somente leitura

Sistema de plugins:     0 extensível → tudo é plugin
Suporte de modelos:     1 provedor → DeepSeek + compatível com OpenAI
Modos de interação:     Somente CLI → Web UI + CLI + SDK + Headless
Custo de execução:      alto → mínimo (Cordis lazy-loading)
Comunidade:             GitHub 187.3k estrelas, licença MIT

A abordagem "tudo é um plugin" do DSH permitiu que a equipe de Alice montasse capacidades sob demanda:

Semana 1: Web UI + DeepSeek API para executar o primeiro Agent
Semana 3: Conectado a um endpoint compatível com OpenAI, mudou para GPT-4o
Semana 6: Plugin de ferramenta customizado, conectado à API interna da empresa
Semana 10: Python SDK integrado ao pipeline de produção

(3) Resultados

Após três meses usando DSH:

Eficiência de desenvolvimento: Ciclo de lançamento de recursos Agent reduzido de 2 semanas para 3 dias
Flexibilidade de modelo: Troca perfeita entre 3 LLMs sem mudança de código
Reutilização de plugins: 5 equipes compartilharam 12 plugins customizados
Custo operacional: Implantação em modo Headless reduziu uso de recursos em 60%

3. O Que É DeepSeek Harness?

DeepSeek Harness (DSH) é um framework Agent de código aberto da equipe DeepSeek, com 187.3k estrelas no GitHub e licença MIT. Não é um Agent em si, mas um framework para executar Agents — fornecendo infraestrutura para adaptação de modelo, orquestração de ferramentas, gerenciamento de sessões e execução em sandbox.

pt-br Visão Geral do DeepSeek Harness

▶ Exemplo 1：

graph TB
    subgraph DSH[DeepSeek Harness]
        C[Cordis Kernel<br/>Plugin Engine]
        M[Model Adapter<br/>DeepSeek / OpenAI]
        T[Tool System<br/>file_edit / shell / search]
        S[Sandbox Engine<br/>Approval & Isolation]
        L[Session Log<br/>append-only log]
    end
    C --> M
    C --> T
    C --> S
    C --> L
    U[Usuário] -->|Web UI / CLI / SDK| DSH

Dimensão	DSH	Frameworks Agent Tradicionais
Filosofia de design	Tudo é um plugin	Funcionalidades hardcoded
Vinculação de modelo	Agnóstico a modelo	Travado em um LLM específico
Método de extensão	Injeção de plugin	Modificar código-fonte ou callbacks
Modos de interação	Web/CLI/SDK/Headless	Geralmente somente CLI
Tempo de execução	Cordis lazy-loading	Inicialização completa

(2) Notas sobre o Developer Preview

DSH está atualmente na fase de developer preview, o que significa:

APIs podem sofrer mudanças incompatíveis em versões futuras
Algumas funcionalidades ainda não estão completas (ex.: multimodal, recursos avançados de sandbox)
A documentação pode estar atrasada em relação ao código
Não recomendado para uso direto em produção

BASH

# Aviso de developer preview durante a instalação
npx @deepseek-ai/dsh web
# ⚠️ DeepSeek Harness is in developer preview.
# APIs may change before stable release.

No entanto, developer preview não significa que é inutilizável — funcionalidades centrais (conversas, ferramentas, plugins) são estáveis e funcionais, e a comunidade está iterando rapidamente.

4. Kernel Cordis: Tudo É um Plugin

Cordis é o framework central do DSH, nomeado a partir da palavra latina para "coração" — é o centro pulsante de todo o sistema.

(1) Modelo de Contribuição de Plugin

Cada plugin contribui três tipos de conteúdo para o contexto compartilhado do Cordis:

TYPESCRIPT

interface PluginContribution {
  services: Service[];        // Capacidades chamáveis expostas pelo plugin
  events: EventType[];        // Fluxos de eventos tipados
  sideEffects: SideEffect[];  // Operações de efeitos colaterais reversíveis
}

Services: Capacidades chamáveis expostas por plugins, como llm.complete(), shell.execute()
Events: Fluxos de eventos tipados, como tool.beforeExecute, session.forked
Side Effects: Operações reversíveis, como modificações de arquivo que podem ser revertidas ou comandos Shell que podem ser desfeitos

▶ Exemplo 2：

graph LR
    P1[LLM Plugin] -->|contribui serviço| CTX[Contexto Compartilhado]
    P2[Tool Plugin] -->|contribui serviço| CTX
    P3[Sandbox Plugin] -->|contribui evento| CTX
    P4[Log Plugin] -->|inscreve-se no evento| CTX
    CTX -->|despacha| P1
    CTX -->|despacha| P2
    CTX -->|despacha| P3
    CTX -->|despacha| P4

Esse design garante:

Zero dependências diretas entre plugins — eles se comunicam indiretamente pelo contexto compartilhado
Adicionar novos plugins não requer modificação do código de plugins existentes
Efeitos colaterais são reversíveis — suportando rollback de operações e restauração de sessão

▶ Exemplo 3：

TYPESCRIPT

import { definePlugin } from '@deepseek-ai/dsh';

export default definePlugin({
  name: 'hello-dsh',
  version: '1.0.0',
  contribute(ctx) {
    ctx.registerService('hello', {
      greet(name: string) {
        return `Hello, ${name}! Welcome to DSH.`;
      }
    });
    ctx.emit('hello.registered', { timestamp: Date.now() });
  }
});

5. Visão Geral dos Quatro Modos de Execução

DSH fornece quatro modos de execução, adaptados para diferentes casos de uso e preferências:

(1) Olhar Rápido nos Modos

Modo	Nome Completo	Características	Casos de Uso
Standard	Standard	Modo padrão, Agent decide autonomamente quando usar ferramentas	Programação geral, Q&A
PTC	Plan-then-Code	Planejar primeiro, depois executar; plano visível e controlável	Tarefas complexas, refatoração de código
Minimal	Minimal	Menos chamadas de ferramentas, Agent depende principalmente de suas próprias capacidades	Q&A simples, consultas de conhecimento
Creative	Creative	Máxima liberdade, encoraja saída exploratória	Escrita criativa, brainstorming

(2) Troca de Modo

BASH

# Troca de modo via CLI
dsh --mode standard
dsh --mode ptc
dsh --mode minimal
dsh --mode creative

Na Web UI, os modos podem ser trocados em tempo real através do menu suspenso no topo.

graph LR
    USER[Entrada do Usuário] --> MODE{Modo de Execução}
    MODE -->|standard| S[Decisão Autônoma do Agent]
    MODE -->|ptc| P[Planejar Primeiro, Depois Codificar]
    MODE -->|minimal| M[Chamadas Mínimas de Ferramentas]
    MODE -->|creative| C[Saída Exploratória]
    S --> TOOLS[Sistema de Ferramentas]
    P --> TOOLS
    M --> TOOLS
    C --> TOOLS

pt-br Quatro Modos de Execução

Para comparação detalhada de modos e configuração, veja 04-modes.md.

6. Comparação com Outros Frameworks Agent

(1) Comparação de Dimensões Centrais

Dimensão	DeepSeek Harness	Claude Code	Cursor	OpenCode
Código Aberto	✅ MIT	❌ Código fechado	❌ Código fechado	✅ MIT
Agnóstico a modelo	✅ Adaptador multi-modelo	❌ Somente Claude	❌ Multi-modelo	✅ Multi-modelo
Sistema de Plugins	✅ Cordis	❌ Nenhum	⚠️ Limitado	❌ Nenhum
Web UI	✅ Integrada	❌ Somente CLI	✅ Integrada na IDE	❌ Somente CLI
SDK	✅ Python	❌	❌	❌
Headless	✅	❌	❌	❌
Sandbox	✅ Configurável	⚠️ Integrado	❌	❌
Estrelas no GitHub	187.3k	—	—	—

(2) Vantagens Diferenciais do DSH

Liberdade de Modelo: Não travado em nenhum fornecedor de LLM; DeepSeek API e endpoints compatíveis com OpenAI são plug-and-play
Ecossistema de Plugins: A arquitetura Cordis transforma extensão de funcionalidades em "escrever plugins" em vez de "modificar código-fonte"
Interação Multicanal: Web UI para iniciantes, CLI para desenvolvedores, SDK para integração, Headless para automação
Efeitos Colaterais Reversíveis: Operações podem ser revertidas, o que é extremamente raro entre frameworks Agent

(3) Cenários Onde DSH Não É Adequado

Necessidade de 100% de estabilidade em produção (developer preview)
Operação puramente no lado do navegador (DSH requer um runtime Node.js)
Ambientes com recursos extremamente limitados (o kernel Cordis tem overhead básico)

7. Visão Geral do Stack Tecnológico

Stack tecnológico completo do DSH:

graph TB
    subgraph Camada de Interação
        WEB[Web UI<br/>React + Vite]
        CLI[CLI<br/>Interação via Terminal]
        SDK[Python SDK<br/>Acesso Programático]
        HEAD[Headless<br/>Execução Autônoma]
    end
    subgraph Camada Central
        CORDIS[Cordis<br/>Plugin Engine]
        SESSION[Session Manager<br/>Gerenciamento de Sessão]
        TRAJ[Trajectory<br/>Log Engine]
    end
    subgraph Camada de Plugins
        LLM[LLM Adapter<br/>DeepSeek / OpenAI]
        TOOLS[Tool Plugins<br/>file_edit / shell / search]
        SANDBOX[Sandbox Plugin<br/>Approval & Isolation]
        PROFILE[Profile Plugin<br/>Configuration Composition]
    end
    WEB --> CORDIS
    CLI --> CORDIS
    SDK --> CORDIS
    HEAD --> CORDIS
    CORDIS --> SESSION
    CORDIS --> TRAJ
    CORDIS --> LLM
    CORDIS --> TOOLS
    CORDIS --> SANDBOX
    CORDIS --> PROFILE

❓ Perguntas Frequentes

P O DSH é gratuito?

R Sim, o DSH em si é totalmente gratuito e de código aberto (licença MIT). No entanto, usar a DeepSeek API ou outras APIs de LLM requer API Keys e taxas correspondentes.

P Developer preview significa que não pode ser usado em projetos reais?

R Não. Funcionalidades centrais (conversas, ferramentas, plugins) são estáveis e utilizáveis, mas APIs podem mudar em versões futuras. Recomendamos validar primeiro em projetos não críticos e aguardar a versão estável antes de usar em produção.

P Qual a diferença entre DSH e AutoGPT?

R DSH é um framework de runtime Agent (Harness), não um Agent em si. AutoGPT é uma implementação específica de Agent. DSH é de nível mais baixo e mais flexível; você pode usar o framework DSH para construir Agents semelhantes ao AutoGPT.

P Preciso usar modelos DeepSeek?

R Não. DSH é agnóstico a modelo. Você pode conectar ao GPT-4o, Claude, Gemini ou qualquer modelo compatível com API através de endpoints compatíveis com OpenAI.

P Cordis é exclusivo do DSH?

R Cordis é um framework de plugins de uso geral desenvolvido pela equipe do DSH que teoricamente poderia ser usado em outros projetos. No entanto, atualmente é lançado junto com o DSH e não foi independentemente open-sourced.

P Que hardware o DSH requer?

R O DSH em si tem requisitos mínimos de hardware (apenas um runtime Node.js). A capacidade de raciocínio do Agent depende da API LLM escolhida. Se usar modelos locais, você precisará de recursos GPU correspondentes.

📖 Resumo

DSH é o framework Agent de código aberto da DeepSeek com a filosofia central "tudo é um plugin"
O kernel Cordis alcança desacoplamento de plugins através de um contexto compartilhado: serviços, eventos, efeitos colaterais reversíveis
Quatro modos de execução se adaptam a diferentes cenários: Standard / PTC / Minimal / Creative
Comparado ao Claude Code, Cursor, etc., as vantagens centrais do DSH são agnóstico a modelo + ecossistema de plugins + interação multicanal
Atualmente na fase de developer preview; funcionalidades centrais são utilizáveis mas APIs podem mudar
GitHub 187.3k estrelas, licença MIT de código aberto, comunidade ativa

📝 Exercícios

1. ⭐ Básico： Visite o repositório GitHub do DSH, leia o README, liste três funcionalidades que mais te atraem e explique por quê.

2. ⭐⭐ Intermediário： Use uma tabela para comparar o DSH com outra ferramenta Agent que você conhece (ex.: Claude Code, Cursor), incluindo pelo menos 6 dimensões de comparação.

3. ⭐⭐⭐ Desafio： Desenhe um diagrama de arquitetura Mermaid mostrando sua compreensão do modelo de contribuição de plugins Cordis — inclua pelo menos 3 plugins, anotando os serviços, eventos e efeitos colaterais que cada um contribui.

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