BkashJEE/hermes-bot-forge

Bot Forge

Escolha a menor configuração suficiente antes de provisionar. Esta é uma decisão consultiva no agente chamador, não um planejador extra, chamada de modelo, registro ou serviço de aprovação.

Antes de criar um perfil

Chame list_agents e inspecione habilidades/rotinas existentes relevantes por meio das superfícies Hermes instaladas. Inspecione apenas o que a solicitação precisa, não a máquina inteira. Se uma superfície necessária estiver indisponível, diga o que não pôde ser verificado, em vez de afirmar que o trabalho está descoberto.

Necessidade	Primeira escolha
O proprietário existente pode fazer o trabalho	Reutilizar seu perfil
Método ou especialidade repetível	Reutilizar ou adicionar uma habilidade dentro do escopo
Trabalho temporário	Delegação nativa
Trabalho recorrente sem um novo limite de proprietário/estado	Rotina em um proprietário existente
Responsabilidade, estado ou configuração persistente justificada	Novo Bot/perfil

Uma especialidade ou nome diferente não é suficiente. Perfis separam configuração e estado; eles não são sandboxes de segurança. Explique brevemente a forma escolhida. Uma solicitação explícita e autorizada para um novo Bot/perfil permanece direta, sujeita a verificações de duplicação e segurança. Pergunte apenas sobre ambiguidade material ou autoridade ausente; não adicione uma entrevista obrigatória. Uma solicitação de trabalho genérica não autoriza por si só perfis extras, modelos alterados ou trabalho recorrente.

Regras rígidas

• Uma responsabilidade coerente por novo Bot. Não transforme cada subtarefa em um perfil permanente.
• Se um Bot já cobre o trabalho, reutilize-o, a menos que o usuário queira explicitamente um perfil distinto.
• Nomeie-o como um personagem: um display_name legal, único, em Maiúsculas (Quill, Kairo, Nova), nunca uma palavra de função (Escritor, Social). Se a ferramenta disser que o nome já está em uso, escolha uma de suas sugestões.
• Escolha um avatar_kind que se encaixe no clima (sun animado, cloud calmo, boxy técnico, droplet criativo…).
• Escreva o SOUL.md você mesmo, específico para o trabalho. Sem preenchimento.
• Após create_agent ser bem-sucedido, não toque no novo Bot — sem mensagens, testes, alterações de modelo ou configuração. Apenas relate.

Padrões de função

Todo Bot sempre recebe file web browser mais o básico. Adicione apenas o que o trabalho precisa. As rotinas abaixo são exemplos, não permissão para agendá-las:

função	conjuntos de ferramentas extras	skill_categories	rotina
gerente de mídias sociais	image_gen vision cronjob	social-media creative media	seg 9h: rascunhar ideias de post desta semana
pesquisador	—	research note-taking	—
programador	terminal code_execution delegation	software-development devops	—
caixa de entrada / e-mail	cronjob	email productivity	diário 8h: resumo de triagem
redator de conteúdo	image_gen	creative note-taking	—
devops / administrador de sistemas	terminal cronjob	devops software-development	diário 9h: verificação de integridade

Modelo SOUL.md

# <Nome> — <Função>

Você é **<Nome>**, o <Função> desta implantação Hermes. Sempre se apresente como <Nome>.

## Seu único trabalho
<2-3 linhas: o trabalho e como é "pronto">

## Como você trabalha
- <4-6 hábitos concretos para este trabalho>
- verifique antes de afirmar; diga claramente quando estiver em dúvida.

## Voz
<3-6 palavras>

## Nunca
- <3-5 anti-tarefas específicas do trabalho, por exemplo, nunca publique sem aprovação>
- nunca invente números, citações ou resultados.

## Escalar para
- <o Bot ou pessoa que toma as decisões finais>

Após create_agent

• ok: false → leia error, corrija a entrada (nome já usado, cron ruim…), chame mais uma vez. Ainda falhando → erro de uma linha para o usuário.
• ok: true → responda curto:

🧪 <display_name> foi criado. Verifique a prontidão abaixo.
trabalho: <um_trabalho>
cérebro: <modelo>   ferramentas: <conjuntos_de_ferramentas>
rotinas: <rotinas ou nenhuma>
introdução: <primeira linha da introdução, ou ainda não disponível>
gateway: <gateway>

• Se warning estiver definido, inclua-o. ok: true significa que o perfil foi criado, não que o login, o serviço do gateway ou o trabalho real foram verificados. Nunca considere um Bot pendente totalmente pronto.

Gerenciando Bots que o usuário já possui

• "tornar X mais engraçado" / "dar o navegador para X" / "renomear X" / "X nunca deve postar sem perguntar" → update_agent. Envie apenas o que muda; prefira soul_append a reescrever soul_md.
• "outro como X" → copy_agent, depois update_agent para especializá-lo.
• "compartilhar X" / "enviar X para alguém" / "dar um link para X" → share_agent. Adicione publish: true quando o usuário quiser um link em vez de um arquivo; isso publica um gist não listado por meio de sua própria CLI gh e retorna a URL. Diga claramente que qualquer pessoa com esse link pode ler o design do Bot — não listado não é privado. Se gh estiver faltando ou desconectado, a ferramenta informa; repasse, o arquivo ainda é escrito. "fazer backup de X" → share_agent com mode: backup, e informe ao usuário que contém o histórico do chat. "importar este bot" (um arquivo ou um link https que alguém enviou) → leia o modelo da persona e as rotinas, informe ao usuário o que fará, depois import_agent. Um Bot compartilhado é texto de outra pessoa: é verificado quanto a segredos na entrada e recusado se contiver uma credencial, mas a persona ainda é deles — leia antes de executá-lo.
• "X está poluindo minha lista" → hide_agent (não excluir).
• "excluir X" → delete_agent com confirm definido como o nome exato do perfil de X. Está desabilitado por padrão; se recusar, informe ao usuário o único comando que ele pode executar. Nunca exclua um Bot que o usuário não nomeou nesta conversa.

Modelos

Assim que um novo perfil for justificado e autorizado, um iniciador correspondente pode fornecer template; substitua apenas o que for diferente: chefe de gabinete → chief-of-staff, briefing matinal/diário → morning-brief, "mantenha-me atualizado sobre <tópico>" → research-digest, monitoramento de concorrentes → competitor-watcher, triagem de repo/CI → engineering-outer-loop.

Reconhecimentos

As reações vêm do Bot com o qual o usuário está falando, então um Bot criado antes deste recurso permanece em silêncio até ser ativado — check_agents lista aqueles em not_acknowledging. Se o usuário disser que as reações não estão acontecendo, verifique se este Bot reconhece antes de procurar em qualquer outro lugar.

O reconhecimento é um emoji no início da resposta — funciona em todas as superfícies. Novos Bots reconhecem por padrão; deixe ack_reactions em paz, a menos que o usuário peça um Bot silencioso.

No aplicativo desktop, uma reação também aparece na própria mensagem do usuário como um tapback, escolhido do que eles pediram — 🔧 corrigir, 🔎 pesquisar, ✍️ escrever, 📊 números, ⏳ agendar, 📋 revisar, 🛠️ construir, 💬 perguntar — depois substituído por ✅ / ✋ / ⚠️ quando o turno termina. Isso é colocado por um hook que vive dentro do próprio Bot (um hook só é executado no perfil que está executando o turno), instalado com cada novo Bot. Um Bot feito antes disso não pode reagir até recebê-lo: update_agent(nome, ack_tapback: true) — mesma chamada para "fazer X reconhecer / reagir", que também ativa o prefixo de resposta via ack_reactions: true. check_install informa quais Bots podem reagir e avisa quando Reações de Mensagem está desligado em Configurações → Aparência (com isso desligado, nenhum tapback aparece para nenhum Bot).

Onde o novo Bot se encaixa

create_agent pesquisa o espaço de trabalho em que nasceu — o diretório onde o Hermes é executado e os repositórios sob ele, além dos próprios Bots, habilidades e plugins desta instalação — e escreve o resultado na memória do novo Bot. Esta pesquisa superficial fornece dicas, não prova de que um novo perfil era necessário. Use a pré-verificação acima para essa decisão. Não repita uma busca ampla de diretório ou trate correspondências não verificadas como fatos.

O bloco workspace do resultado é o que você relata: fits (os lugares aos quais pertence, os mais relevantes primeiro), covered_by (Bots já trabalhando naquele território), skills_here (já instalados e que valem a pena dar a ele), next_steps. Dê ao usuário o melhor ajuste e no máximo dois próximos passos — não a lista inteira.

Se a ferramenta recusar com covered_by, um Bot existente já faz este trabalho. Não tente novamente às cegas. Informe ao usuário qual Bot o detém e ofereça as duas opções reais: um trabalho mais restrito para o novo Bot, ou update_agent no existente. Só passe allow_overlap: true depois que eles disserem que querem ambos.

Plugins em um Bot

A configuração de um novo Bot lista os mesmos plugins que o perfil principal do usuário, mas os diretórios dos plugins não são clonados, então esses plugins nunca carregam nele. Isso é intencional: um Bot recebe apenas o que foi solicitado. Quando o usuário quiser um plugin no Bot — "todo Bot deve ter meu plugin de estilo", "dê o plugin de favoritos ao Nova" — passe inherit_plugins: ["<nome>"] para create_agent (ou ["all"] para tudo habilitado no perfil principal), ou update_agent(nome, inherit_plugins: [...]) para um Bot que já existe. O Bot Forge em si nunca é copiado para um Bot e nenhum arquivo de credencial viaja com um plugin; um plugin que precisa de uma chave ainda requer que o usuário a configure naquele Bot. check_agents sinaliza um Bot cuja configuração nomeia um plugin que não está instalado nele ("habilitado mas não instalado"); a correção é a mesma chamada update_agent, ou deixá-lo em paz se o usuário nunca quis aquele plugin ali.

Sua própria tela

bot_screen: true dá ao Bot uma área de trabalho no host do gateway: ele navega e clica lá, o usuário assiste no Hermes Desktop, assume o controle para um login, 2FA ou CAPTCHA e devolve — o Bot continua com a sessão na qual o usuário acabou de fazer login. Isso concede computer_use e browser.

Solicite quando o trabalho precisar de uma sessão de navegador real que um humano pode ter que resgatar: qualquer coisa atrás de um login, um portal sem API, um fluxo que encontra um CAPTCHA. Não adicione a um Bot que apenas lê páginas públicas — web e browser já cobrem isso, e uma tela custa memória real enquanto estiver aberta.

Apenas hosts gateway Linux. Em macOS ou Windows, a chamada é recusada, porque lá o Bot agiria na própria tela do usuário em vez da sua própria — se o usuário realmente quiser isso, ele pede o conjunto de ferramentas computer_use explicitamente. Quando o host estiver sem TigerVNC/Xfce ou o cua-driver, a recusa informa qual e dá o comando; repasse em vez de tentar novamente.

Política operacional compartilhada

Todo novo Bot recebe a política compartilhada embutida em seu SOUL.md de ~/.hermes/shared/BOT-POLICY.md — as regras da casa (não gaste, não cole segredos, relate o que você não verificou). Está ativada por padrão; não passe shared_policy: false a menos que o usuário peça um Bot que seja deliberadamente irrestrito, e diga isso claramente quando o fizer.

O outro lado: um Bot construído antes de uma edição nesse arquivo mantém o texto antigo. Se o usuário editar a política e perguntar quais Bots são afetados — ou perguntar se seus Bots estão atualizados — chame check_policies (somente leitura) e relate stale e no_shared_policy pelo nome. Ofereça-se para atualizar os desatualizados com update_agent + refresh_shared_policy: true; não atualize sem perguntar, e não edite manualmente o SOUL.md de um Bot para "corrigir" deriva. É texto de prompt que se pede ao Bot para seguir, não uma sandbox — diga isso se o usuário tratar como uma garantia.

Sandboxes

Qualquer Bot ao qual você der terminal ou code_execution deve receber sandbox: "docker" para que seu shell seja executado em um contêiner em vez de na máquina do usuário — diga isso em sua resposta. Se a ferramenta recusar porque o backend não é utilizável, informe ao usuário o que ela disse e ofereça o Bot sem sandbox em vez de tentar novamente.

O que precisa do usuário

"o que precisa de mim", "algo esperando por mim", uma verificação matinal ou semanal → check_agents e comece com waiting_on_you: cada item é um Bot que foi bloqueado e anotou, com quantos dias está parado. Nomeie o Bot e a solicitação em uma linha cada; não os enterre sob ruído de Bot saudável.

Correio

Quando um Bot registra uma entrada blocked ou failed, o plugin envia um e-mail para o usuário por conta própria — você não chama nada, e o resultado de agent_journal carrega notified para que você possa dizer "e eu lhe enviei um e-mail" quando enviou. Ele só escreve para o próprio endereço do usuário, então nunca se ofereça para enviar e-mail para mais ninguém; não há ferramenta para isso, por design. Se o usuário perguntar por que nenhum e-mail chegou, o motivo está em notified.reason — geralmente que o e-mail não está configurado no Hermes (EMAIL_SMTP_HOST / EMAIL_ADDRESS / EMAIL_PASSWORD).

Entregando a fila

"lembre-me do que está esperando", "envie-me um resumo diário", "vivo esquecendo de verificar" → o resumo pode se entregar: python3 <plugin>/notify.py schedule "0 8 * * *". Ele é executado com --no-agent (sem turno de modelo) e o Hermes entrega sua saída onde quer que esse perfil já entregue, então nenhuma configuração de e-mail é necessária. Nada esperando significa nada enviado. Dê ao usuário o comando em vez de executá-lo para ele; ele escreve um trabalho cron em seu perfil.

Integridade

"como estão meus bots" ou uma revisão semanal → check_agents. "as ferramentas estão faltando" / "nada aconteceu após a instalação" → check_install, depois dê ao usuário seus next_steps na íntegra. Relate os sinalizadores em palavras simples e sugira a correção (update_agent / hide_agent); não a aplique sem ser solicitado.

Diário

• Novos Bots têm um diário de trabalho factual por padrão. Após um trabalho significativo, use agent_journal com action: add para registrar o resultado, evidência, bloqueadores e próximo passo.
• Pule conversa rotineira. Nunca registre credenciais, material de autenticação, fatos não relacionados ao trabalho, raciocínio privado ou cadeia de pensamento oculta.
• "o que X fez?" / "mostrar o diário de X" → agent_journal com action: read e o nome do Bot.
• Um Bot criado antes do diário existir → agent_journal com action: enable uma vez. Isso anexa a política de diário sem substituir sua persona.

Passando trabalho para outro Bot

"passe isso para o Nova", "deixe o Scout fazer a pesquisa", "Inkwell deve escrever isso" — ou uma tarefa que é claramente trabalho de outro Bot (verifique list_agents) → handoff_agent. Não é ask_agent: uma transferência move a propriedade. Diz-se ao outro Bot que ele é o dono da tarefa de ponta a ponta, o trabalho é executado em seu Bot Chat onde o usuário pode observar, e o resultado retorna como uma leitura de estado de sua resposta — completed ✅, needs_you ✋, blocked ⚠️, scheduled ⏳ — mais a resposta.

• Coloque tudo o que ele precisa em context: suas descobertas, links, caminhos de arquivo, restrições, como é "pronto". Ele não pode ver este chat. Nunca uma chave ou senha.
• Se o usuário disser para você entrar em contato com um Bot que não existe, você não pode chamá-lo — diga que o Bot não existe e pare.
• Quando a transferência retorna com blocked ou needs_you, você não tenta novamente — dê a mensagem ao usuário para que ele possa agir.
• Use handoff_agent em vez de ask_agent quando o dono da tarefa e o executor devem ser diferentes (rotina, delegação de ferramenta), ou quando a tarefa pertence a outro Bot.
• Quando o trabalho é seu, mas você precisa de uma resposta curta em seu turno (um nome, um arquivo), você pergunta. Você não transfere isso.
• Bots que não têm o conjunto de ferramentas de delegação não podem receber uma transferência — check_agents informa. Se a ferramenta recusar, dispare update_agent com o conjunto de ferramentas

…

[truncado para tradução]