Arquitetura

Esta página explica como a distribuição é montada e por quê. Ela serve para quem vai contribuir com o código ou precisa entender o que roda na máquina.

Construído sobre o DeepSeek Harness (MIT, © DeepSeek). Não é um produto oficial da DeepSeek.

Distribuição, não fork

O Neuro Harness não altera o código do DeepSeek Harness.

• O Harness é instalado do npm (@deepseek-ai/dsh), na versão fixa 0.2.1-alpha.2, em ~/.neuro-harness/runtime.
• A distribuição acrescenta o que é dela pelas portas de extensão do próprio Harness: perfis, patches de configuração, plugins de interface e pacotes de idioma.

Por que não um fork: o Harness está em developer preview e muda toda semana. Manter um fork do monorepo custaria mais do que ele traz.

O código

• Directoryneuro-harness/

  • Directorylib/

    • harness.js núcleo: instala, configura, sobe e para (usado pela CLI e pelo app)
    • cli.js CLI neuro-harness
    • credentials.js importação de chaves do Hermes e do OpenCode para o cofre
  • Directoryplugins/

    • Directoryneuro-harness-brand/ marca: espaços da interface, título e ícone da aba

      • …
    • Directoryneuro-harness-pt-br/ idioma pt-BR: addLanguage e dicionários

      • …
  • Directoryapps/

    • Directorydesktop/ app Electron (macOS arm64, Windows x64)

      • …
  • Directory.github/

    • Directoryworkflows/ CI do app desktop

      • …

O núcleo (lib/harness.js) não tem dependências. A CLI e o app desktop chamam as mesmas funções: setup, start, stop, doctor e as outras.

Como o Harness sobe

1. A CLI (ou o app) confere se já há um Harness rodando, pelo PID em ~/.neuro-harness/harness.pid. Se houver, reaproveita.
2. Ela procura a porta: a 3082 ou, se estiver ocupada, uma porta livre.
3. Ela inicia o dsh do runtime com o perfil neuro, em 127.0.0.1, na pasta de trabalho e com o ambiente limpo das sessões.
4. A saída vai para ~/.neuro-harness/harness.log. A CLI lê o endereço com o token desse log.

O Harness roda como processo próprio, sem tmux, do mesmo jeito no macOS, no Linux e no Windows.

Ambiente limpo: o PATH começa por ~/.neuro-harness/bin, sem pastas do Claude Code; o cache npm é próprio; e nenhuma chave de provedor vem do ambiente. Os detalhes estão em Variáveis de ambiente. O mapa das pastas em uso está em Pastas e arquivos.

Repositórios

Repositório	Visibilidade	Papel
neuro-harness	Privado	A distribuição: CLI, núcleo, plugins de marca e idioma, app desktop e Releases
neuro-harness-install	Público	Só os scripts do instalador de uma linha, sem segredos
neuro-mv-edit	Privado	Motor de edição de vídeo: skill, CLI, Remotion e HyperFrames. Também é plugin do Claude Code, do Hermes, do OpenCode e do Open Design
neuro-ads-manager	Privado	Plugin de tráfego pago (Meta Ads), instalado pelo setup
neuro-mv-superagent	—	O agente com fila de vídeos, aprovações e painel de vídeos, a partir do dsh-superagent-prototype. Em desenvolvimento, não vem na instalação
neuro-harness-site	—	O site harness.neuros.my e esta documentação: apresentação, download, scripts do instalador e a API de versão

Decisões

• Perfil gerenciado: a distribuição só escreve entre # >>> neuro-harness e # <<< neuro-harness no cordis.patch.yml do perfil. O resto (provedores e preferências que o painel grava) é seu.
• Plugins copiados, não ligados: o setup copia os plugins para ~/.neuro-harness/plugins. Assim, mover o clone ou atualizar o app não quebra o perfil. O --link serve só para desenvolvimento.
• Plugins da casa fixados por versão: o motor e o neuro-ads-manager são clonados da tag fixada, uma pasta por versão, e ligados ao perfil.
• Bundles de cliente escritos à mão: os plugins de interface são um window.__ModuleLoader__.load(...) gerado por script, que usa o React do próprio Harness. Não há etapa de build com bundler.
• Plugin sem bundle não é instalado: um bundle de cliente faltando derrubaria a interface. O setup pula esse plugin e avisa.
• Sem tmux: o Harness sobe como processo próprio, com PID e log.

Versões e Releases

• Uma versão para tudo: a CLI e o app desktop compartilham a mesma versão, seguindo o Versionamento Semântico.
• Cada versão tem uma tag vX.Y.Z e uma Release no GitHub.
• CI: o workflow App desktop roda a cada tag v* (e à mão). Ele monta o .dmg num runner macOS (Apple Silicon) e o .exe num runner Windows e os anexa à Release.
• Assinatura: os apps saem sem assinatura de código. O CI está pronto para receber os certificados como segredos do repositório.

O histórico está em Novidades.

Créditos

• DeepSeek Harness: MIT (alguns pacotes sob BSD-3-Clause), © DeepSeek. Usado sem modificação, numa versão fixa.
• dsh-superagent-prototype: MIT, © DeepSeek. Base do neuro-mv-superagent.
• Cordis: MIT, incluído no DeepSeek Harness.
• pi-ai (@earendil-works/pi-ai): provedores de modelo usados pelo DeepSeek Harness.
• Electron e electron-builder: MIT, no app desktop.

“DeepSeek Harness” é marca registrada da DeepSeek. O Neuro Harness não é endossado pela DeepSeek. As regras de uso do nome estão em Identidade visual.