Agent2API/agent2api

Normas de Colaboração e Lançamento do Agent2API

Cobre dois tipos de trabalho: colaboração diária (ponto de ancoragem de branches, autoria em PRs, rodapé de Issues, seções 1–3) e lançamento (versão, changelog, tag, Release, verificação, seções 4–7); solução de problemas na seção 8.

0. Duas Linhas Vermelhas Humanas (deve parar e aguardar confirmação)

As duas ações a seguir precisam ser revisadas e aprovadas explicitamente por uma pessoa antes que o agente prossiga; pode preparar um rascunho, listar argumentos, mas não pode decidir sozinho:

1. Lançamento: Antes de iniciar o processo de lançamento (alterar versão, criar commit de lançamento, fazer push para main / beta, criar tag, criar Release), primeiro explique claramente o número da versão e "o que será lançado desta vez" e aguarde a confirmação do usuário. Sem confirmação, não faça push de nenhuma branch ou tag — uma vez que uma tag é enviada, ela aciona a construção, gerando pacotes de instalação públicos e imagens que não podem ser desfeitos.
2. Changelog: O changelog escrito (a mensagem do commit de lançamento, que também é o corpo do GitHub Release) deve ser revisado item por item pelo usuário antes de prosseguir. Se o usuário solicitar alterações na redação, adicionar ou remover itens, ou ajustar prefixos de categoria, após fazer as alterações, peça confirmação novamente, não faça o commit diretamente apenas porque "a alteração foi pequena".

Em um lançamento, ambas as regras se aplicam simultaneamente: é necessária a confirmação do número da versão e a confirmação do changelog; só prossiga após o usuário dizer "continue".

1. Ponto de Ancoragem de Branches: Dia a Dia Apenas beta, Lançamento Mexe em main

Branch	Função	Quando mexer
beta	Branch de integração (ponto de ancoragem padrão)	Modificações diárias, merge de PRs, resolução de conflitos — sempre vá para cá primeiro
main	Branch de lançamento	Apenas durante a construção do lançamento: mude para main, mescle beta aqui, crie a tag

• Ao mesclar um PR, selecione beta como base, não main. Mesclar em main significa colocar alterações não publicadas na branch de lançamento prematuramente; depois, você teria que mesclar main de volta para beta, adicionando um commit de merge desnecessário e uma chance extra de conflito. Se um PR já foi aberto com base=main, primeiro altere a base para beta na página do PR e depois mescle.
• Alterações locais também devem ser commitadas no beta (código, documentação, resolução de conflitos), faça push para origin/beta; a verificação dos resultados do merge e as autoverificações de construção são feitas no beta.
• Somente para lançamentos oficiais, mude para main: git switch main → mescle beta → escreva o commit de lançamento, faça push de main, crie a tag; a tag deve estar no main. Após o lançamento, mescle main de volta para beta para manter ambos consistentes.
• Não escolha a branch de ancoragem por conta própria: Se o usuário não mencionou um lançamento, não faça commit/push para main, nem altere a base do PR para main.
• A versão beta (pré-lançamento) é a única exceção: não mude para main, a tag é criada diretamente na própria branch beta (veja a seção 6).

2. Mesclagem de PRs: Preservar a Autoria do Contribuidor

Ao mesclar um PR de um contribuidor, o autor do commit (author) deve ser o próprio contribuidor — isso determina diretamente se ele aparecerá na lista de Contribuidores da página inicial do repositório e se o commit contará no gráfico de contribuições. A autoria é algo que o contribuidor merece e não deve ser perdida devido ao método de merge.

A regra de atribuição do GitHub é apenas uma: se o e-mail do author no cabeçalho do commit aparecer na lista de e-mails verificados de uma conta, esse commit é atribuído a essa conta; caso contrário, é registrado como anônimo e não entra em Contributors. Existem duas outras regras: as estatísticas só consideram a branch padrão (main neste repositório), e commits de merge e commits vazios não são contados.

• Use por padrão o botão de merge na página do GitHub (Merge pull request / Squash and merge / Rebase and merge): todos os três preservam o autor original; ao usar squash, vários autores no PR são incluídos na lista de co-autores.
• Proibido "baixar e recomitar localmente": Copiar as alterações de outra pessoa e commitá-las você mesmo (fazer git merge --squash localmente e depois commitar, reescrever as alterações ou alterar o autor e commitar) não é permitido — assim o autor é quem mesclou e a autoria do contribuidor fica completamente invisível para o GitHub. Este repositório já passou por isso; não deixe acontecer de novo.
• Se for realmente necessário processar localmente (para resolver conflitos ou ajustes), a autoria deve ser preservada: para um único autor original, use git commit --author="<autor original> <<email do autor original>>"; se houver trabalho de várias pessoas em um commit, adicione um trailer Co-authored-by: Nome <email> ao final da mensagem do commit.
• Remover trailer de co-autoria de IA: Trailers de IA como Co-Authored-By: Claude Code <…> no final da mensagem de commit de contribuidores devem ser removidos ao mesclar — o GitHub os renderizaria como co-autores, e ao entrar em main, apareceriam na lista de Contribuidores, mas IA não é um contribuidor. Remova apenas a linha do trailer em si; preserve o author e o resto da mensagem do commit literalmente. Menções técnicas a produtos de IA no corpo do texto (como "suporte ao cliente Claude Code" ou "endpoint compatível com Claude") não são afetadas e não devem ser alteradas. A remoção afeta o histórico já mesclado na branch; faça isso o mais cedo possível após o merge e antes do lançamento (use git filter-branch --msg-filter para remover a linha e depois force-push). Se atrasar até depois do lançamento, será necessário reescrever main.
• O e-mail deve corresponder a uma conta: Use um endereço verificado na conta GitHub da pessoa; se ela quiser manter privacidade, use o ID+nome de usuá[email protected] fornecido pelo GitHub (encontre nas configurações de Emails da conta). Endereços de intranet, usuário@nome da máquina etc. nunca serão associados a uma conta, e o commit será registrado como anônimo.
• Após o merge, verifique rapidamente: git log --format='%an <%ae>' -1 <commit do merge> ou veja na página do PR se o avatar ao lado do commit aponta para o autor original.

3. Responder a Issues / PRs: Indicar Origem da IA

Cada resposta a uma Issue / PR emitida por um agente de IA (incluindo escrita em nome de outra pessoa) deve ter uma linha separada no final indicando a origem. O destinatário tem o direito de saber com quem está falando — é o mesmo princípio da seção 2: quem disse, escreva quem foi.

Rodapé fixo, use exatamente como está (não mude para "robô", "assistente" ou termos vagos):

🤖 Esta resposta foi gerada por um AI Agent

• Posição: Última linha de toda a resposta, em um parágrafo separado (com uma linha em branco antes e depois); não coloque dentro de parágrafos do corpo, itens de lista, citações ou blocos de código — ao citar outras pessoas, o rodapé deve vir após suas próprias palavras.
• Em inglês (PRs / Issues de contribuidores externos), adicione mais uma linha Generated by an AI agent. abaixo da linha em chinês, dizendo a mesma coisa em ambos os idiomas.
• Se o agente criar uma Issue / PR, adicione o rodapé no final do corpo da mesma forma.
• Escrita em nome de outra pessoa também conta: Se uma pessoa pedir ao agente para transmitir uma mensagem (mesmo que literalmente), adicione o rodapé — ele descreve "quem enviou esta resposta", não "quem a concebeu".
• Aplica-se apenas a respostas em Issues / PRs (comentários, revisões, explicações de fechamento/merge). Não adicione esta linha em mensagens de commit; as regras de autoria estão na seção 2.

4. Número de Versão

• O número da versão segue o formato X.Y.Z (ex.: 2.7.2); um incremento diário de "0.01" significa +1 no último dígito (ex.: 2.7.8 → 2.7.9).
• A amplitude do incremento é determinada pelo usuário: Por padrão, use o "incremento 0.01" acima; se o usuário tiver outra solicitação (como "incremento 0.1 desta vez"), siga sempre o usuário e calcule o novo número de versão com base na amplitude especificada; não aplique a amplitude padrão por conta própria.
• O número da versão deve ser alterado em 5 lugares (faltar um fará com que o pacote de instalação e a versão exibida não correspondam):
  1. package.json (raiz)
  2. desktop-tauri/package.json
  3. desktop-tauri/src-tauri/Cargo.toml
  4. desktop-tauri/src-tauri/tauri.conf.json
  5. desktop-tauri/src-tauri/server/Cargo.toml
• A seção "Sobre" do aplicativo e a verificação de atualizações leem env!("CARGO_PKG_VERSION") (local 5); após a alteração, execute cargo check uma vez para que Cargo.lock seja atualizado.
• Aproveite para revisar a documentação de instalação: As instruções de instalação foram movidas do README para docs/install.md (o README agora contém apenas uma tabela de referência rápida + um link); há também 5 traduções docs/install.{en,zh-Hant,ja,ko,pt-BR}.md, todos com conteúdo correspondente. Se esta alteração afetar etapas de instalação/atualização/desinstalação, nomes de artefatos, portas padrão, variáveis de ambiente ou parâmetros de script de instalação, todos os seis devem ser alterados em conjunto; se a tabela de referência rápida do README for afetada, altere-a também.

5. Fluxo de Lançamento Oficial

Execute em ordem; as duas linhas vermelhas da seção 0 se aplicam a todo o processo.

# 1. Limpe o diretório de trabalho (o código na tag é o código que será lançado)
git status --short        # Deve estar vazio; se houver alterações, faça commit ou limpe
cargo check               # Ou execute uma autoverificação de construção se o frontend foi alterado

# 2. Mude para main e mescle beta
git switch main && git pull
git merge beta

# 3. Altere os números de versão nos cinco lugares (padrão: +1 no último dígito, amplitude conforme o usuário); atualize Cargo.lock
cargo check

# 4. Escreva o commit de lançamento: mensagem do commit = changelog
git commit -am "…changelog…"

# 5. Faça push de main, crie a tag, faça push da tag (uma tag v* aciona todas as construções)
git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

# 6. Após a execução de dois workflows, crie o GitHub Release
gh run list --limit 4       # Antes de executar gh manualmente, configure um proxy, veja seção 8
bash scripts/release.sh vX.Y.Z

A mensagem do commit de lançamento = changelog, porque o script de finalização de lançamento pega o corpo do Release da mensagem do commit apontado pela tag ao criar/atualizar o GitHub Release (git log -1 --format=%B).

• O formato segue a lista numerada de versões anteriores, um item por linha, com prefixos de categoria: Novo: / Otimizado: / Corrigido: / Atualizado: / Removido:; o último item é sempre Versão: X.Y.Z → X.Y.Z+1;
• O conteúdo é compilado a partir de "todos os commits desde a última tag" (git log vX.Y.Z..HEAD --oneline); commits puramente de CI ou depuração temporária podem ser agrupados em uma descrição processual;
• Se não houver alterações de código desta vez, use um commit vazio: git commit --allow-empty -F changelog.txt;
• O rascunho do changelog e as notas de versão históricas devem ser armazenados em docs/release-notes/<numero da versão>.md (ex.: docs/release-notes/2.9.2.md); não crie .release-notes-*.md na raiz do projeto — docs/release-notes/ já está na lista de ignorados (apenas este diretório, outros documentos em docs/ são rastreados normalmente), então não é necessário adicionar regras de ignorar para novos arquivos.

Fazer push de uma tag v* aciona simultaneamente dois workflows (.github/workflows/):

Workflow	Artefatos	Descrição
build.yml (build)	Pacotes de instalação para desktop em 3 plataformas + pacote do servidor Linux	Quatro jobs: macos (dmg) / windows (NSIS exe) / linux-desktop (deb + AppImage) / linux-server (tar.gz para atualização dentro do contêiner). Artefatos macOS e desktop Linux só podem ser construídos em suas respectivas plataformas, não pode compilar cruzadamente do Windows; todos os artefatos são apenas anexados como artifact; o GitHub Release é montado pelo script local
docker.yml (docker)	Docker Hub aimodcc/agent2api:<versão> + :latest (arquiteturas duplas amd64 / arm64)	Quando acionado manualmente via workflow_dispatch, produz apenas a tag de teste :dev, não mexe nas tags oficiais; tags beta (número de versão com -) produzem apenas <versão>, não movem :latest

Acompanhamento do progresso:

gh run list --limit 4
gh run watch <run-id> --exit-status

Finalização do lançamento: O GitHub Release não é publicado pelo CI (o Release não é criado automaticamente), mas montado em uma única etapa pelo script local:

bash scripts/release.sh vX.Y.Z            # Encontra automaticamente o build run bem-sucedido para a tag
bash scripts/release.sh vX.Y.Z <run-id>   # Ou especifique o run explicitamente

O script faz três coisas: Baixa o artifact do pacote de instalação do build para dist/ → Cria/Atualiza o GitHub Release com base na mensagem de commit da tag (= changelog) e anexa os artefatos → Exibe dicas de verificação. É idempotente e pode ser reexecutado (--clobber sobrescreve os anexos).

6. Versão Beta (Pré-lançamento)

O aplicativo tem uma opção "Configurações → Atualizações de Software → Configurações de Atualização → Participar da versão beta": quem ativa recebe atualizações beta; quem não ativa vê apenas os lançamentos oficiais.

Uma versão beta não é uma esteira separada, mas uma variação do fluxo da seção 5 — a única diferença estrutural é "criar a tag com sufixo de pré-lançamento a partir da branch beta"; commit, tag, Release e verificação seguem exatamente o mesmo. As duas linhas vermelhas da seção 0 também se aplicam.

# 1. Trabalhe na branch beta (a versão beta não mexe em main)
git switch beta && git pull
git status --short          # Deve estar vazio

# 2. Altere os números de versão nos cinco lugares para o formato "exatamente igual à tag":
#    tag é v3.1.0-beta.1 → todos os cinco lugares escrevem 3.1.0-beta.1 (lista na seção 4)
cargo check                 # Aproveite para atualizar Cargo.lock

# 3. Faça commit e push da branch beta (mensagem do commit = changelog desta versão beta, formato igual ao da seção 5)
git commit -am "…changelog da versão beta…"
git push origin beta

# 4. Crie a tag e faça push: a tag fica no commit da branch beta
git tag v3.1.0-beta.1
git push origin v3.1.0-beta.1

# 5. Após a execução dos dois workflows, crie o Release (o script marca automaticamente como pré-lançamento com base no `-` na tag)
gh run list --limit 4
bash scripts/release.sh v3.1.0-beta.1

A verificação tem apenas três itens: O Release mostra Prerelease, os anexos exe / dmg / deb / AppImage estão completos, e o horário de Pushed do :latest no Docker Hub não mudou (lista completa na seção 7).

Três pontos que não podem errar, cada um com sintomas claros:

1. Número de versão sem o sufixo nos cinco lugares (escrito como 3.1.0): A comparação é feita com semver; a versão em execução 3.1.0 será considerada "mais nova que a versão online 3.1.0-beta.1", então usuários beta nunca receberão a atualização. Os cinco arquivos aceitam números de versão com sufixo (Cargo / npm / tauri.conf.json aceitam), basta copiar exatamente da tag.
2. Release sem a marcação de pré-lançamento: A marcação é a linha divisória da opção — o canal oficial usa /releases/latest do GitHub, que exclui pré-lançamentos; apenas quem ativou a opção vê a versão beta na lista de /releases. Faltar a marcação = a versão beta é recebida por todos os usuários da versão oficial como se fosse uma atualização oficial. O scripts/release.sh já marca automaticamente com base no - na tag; reexecutar a finalização também corrigirá a marcação, então usando o script não precisa se preocupar.
3. Tag criada em main: beta é a branch de integração; a versão beta precisa de seu snapshot. Uma tag em main ou não contém as novas alterações da branch beta (perda de tempo testando) ou equivale a colocar alterações não publicadas prematuramente em main.

O :latest do docker não é movido por tags beta (.github/workflows/docker.yml); a imagem ainda sai com a tag de versão 3.1.0-beta.1; quem quiser testar, baixa pelo número da versão.

Três situações comuns posteriores:

• Lançar outro beta: O número principal permanece o mesmo, incrementa o número sequencial (3.1.0-beta.2, altere os cinco lugares, execute os mesmos comandos acima). Os números de pré-lançamento podem ser ordenados (beta.2 > beta.1); quem já está no beta receberá a atualização — portanto, entre betas também é necessário manter "tag e número de versão exatamente iguais".
• Promover (lançar versão oficial 3.1.0): Siga a seção 5 em main, remova o sufixo dos cinco lugares. Usuários beta não voltam automaticamente para a versão oficial: quem mantém a opção ativada só vê versões de pré-lançamento (a triagem pick_listed_release filtra por "a versão atual é beta?"), então o 3.1.0 promovido não é uma atualização para eles — quem quiser permanecer no canal beta espera o próximo beta (3.2.0-beta.1 assim que aparecer, recebe); quem quiser voltar para a versão oficial desativa a opção, e só receberá atualizações quando uma versão oficial com número maior que a versão beta que ele tem for lançada (3.1.0 > 3.1.0-beta.1, mas um 3.0.9 anterior não fará downgrade).
• "Ativei mas não acontece nada": Se não houver nenhum Release de pré-lançamento no repositório, ativar a opção mostrará apenas a versão oficial — só fará efeito após o primeiro beta ser lançado.

7. Lista de Verificação

• GitHub Release: gh release view vX.Y.Z (antes de executar gh manualmente, configure um proxy, veja a seção 8) — log do corpo completo, quatro anexos de desktop presentes: Windows Agent2API_<versão>_x64-setup.exe, macOS Agent2API_<versão>_universal.dmg, Linux Agent2API_<versão>_amd64.deb e Agent2API_<versão>_amd64.AppImage (mais dois agent2api-server-linux-*.tar.gz + .sha256, estes são pacotes de atualização dentro do contêiner, veja a seção 5);
• Linux Desktop: Instalar o deb (ou chmod +x e executar o AppImage) deve iniciar, e o painel "Configurações → Atualizações de Software" deve detectar a versão e fornecer a entrada de instalação correspondente ao tipo de pacote (deb → instalador do sistema, AppImage → substituir arquivo);
• Docker Hub: Na página de Tags de aimodcc/agent2api deve aparecer <versão> e latest, com horários de Pushed consistentes;
• O número da versão na página "Sobre" do pacote de instalação corresponde à tag;
• A documentação de instalação corresponde aos artefatos reais: docs/install.md e as 5 traduções devem ter nomes de artefatos, portas, comandos, variáveis de ambiente consistentes com este Release (as tabelas de referência rápida no README também);
• Versão beta tem mais um item: O Release mostra Prerelease, e o latest no Docker Hub não mudou.

8. Problemas Conhecidos e Solução de Problemas

• Novos pacotes GHCR são privados por padrão: Se no futuro as imagens forem enviadas para GHCR, após o primeiro push, é necessário ir às configurações do pacote e alterar manualmente para Público (atualmente está enviando para Docker Hub, sem este problema).

• gh não lê as configurações de proxy do git; antes de executar gh, defina a variável de ambiente de proxy: gh é um programa Go, não lê http(s).proxy em ~/.gitconfig, nem o proxy do sistema Windows (WinINET); só reconhece as variáveis de ambiente HTTPS_PROXY / HTTP_PROXY. Se a conexão direta com o GitHub na máquina local for intermitente, antes de executar comandos gh manualmente, configure:

  export HTTPS_PROXY=$(git config --get-urlmatch http.proxy https://github.com || git config --get https.proxy)
  

  Apenas definir HTTPS_PROXY é suficiente (todas as requisições do gh são HTTPS; na prática, não lê HTTP_PROXY). O scripts/release.sh já incorpora esta etapa (lê da configuração do git e a repassa para gh); usando o script para lançar, não é necessário configurar manualmente. Se o proxy não estiver ativo, o gh reportará imediatamente proxyconnect tcp: ... connection refused sem fazer fallback para conexão direta — comportamento consistente com git push.