Cherry Electron Dev: depure a instância certa sem fechar processos alheios

ANÁLISE EDITORIAL

Depurar um aplicativo Electron pela janela errada é um erro silencioso. O agente pode encontrar uma porta CDP aberta, enxergar uma interface parecida com a esperada e agir em outro checkout, em uma versão empacotada ou em um processo que pertence ao usuário. O comando funciona, mas a evidência deixa de responder à pergunta original.

A Cherry Electron Dev transforma essa fronteira em procedimento. A Skill foi escrita para o checkout de desenvolvimento do Cherry Studio e exige que cada ação de interface seja ligada ao PID, ao diretório de trabalho, à porta CDP, ao alvo exato e ao commit usado no lançamento. Ela também separa renderer, processo principal e processos auxiliares antes de atribuir consumo de CPU ou memória.

Esta não é uma Skill genérica para qualquer aplicativo Electron. Ela conhece o fluxo, os caminhos e as decisões do Cherry Studio. O valor está justamente nessa especificidade, mas ela só deve ser usada dentro do repositório correto e por quem entende que traces, heap snapshots, logs e perfis podem conter dados privados.

O que esta Skill faz

O fluxo cobre implementação cotidiana, correção de bugs, inspeção de interface, análise de console e rede, investigação de travamentos, crescimento de memória, uso alto de CPU e lentidão de inicialização. Antes de editar, o agente declara o comportamento pedido e qual evidência demonstrará a correção. Depois reproduz o cenário, encontra o caminho de código responsável e executa a validação mais estreita que responda ao problema.

O SKILL.md fixado manda reutilizar uma instância saudável do mesmo workspace. Alterações no renderer podem aproveitar HMR e ser verificadas na mesma janela. Reinício só entra quando a camada não recarrega, o processo caiu, o estado deixou de ser confiável ou a medição envolve inicialização.

A entrega não termina em “parece resolvido”. Ela deve informar PID verificado, estado do processo, porta CDP, arquivo de rastreamento, caminhos das evidências, reprodução e verificação. Isso cria uma cadeia mínima entre a mudança e o que foi observado.

Para quem serve

A Skill serve a mantenedores, contribuidores e equipes que desenvolvem o Cherry Studio a partir do código-fonte. Ela é especialmente útil quando mais de uma instância Electron pode estar aberta, quando o aplicativo empacotado convive com um checkout de desenvolvimento ou quando uma investigação de desempenho envolve renderer, processo principal, GPU, Vite e subprocessos.

Também ajuda revisores que precisam repetir um cenário antes e depois de uma correção. O procedimento exige manter duração, rota, dados, tamanho da janela e estado visível das DevTools equivalentes. Sem esse controle, uma diferença de memória ou tempo pode vir do próprio experimento.

Não serve para testar pull requests como fluxo principal. A origem reserva essa tarefa para outra Skill, cherry-pr-test, que não está neste pacote. Também não é uma receita universal de Electron, nem substitui os README e as instruções do checkout atual.

Origem, adoção e versão

A origem auditada é o repositório CherryHQ/cherry-studio. Em 17 de setembro de 2026, a API pública do GitHub registrava 51.925 estrelas e 4.976 forks. O repositório não estava arquivado e declarava licença AGPL-3.0.

A curadoria fixou o commit b112a46b0e2d93105540ddbc9234ce468e9e4b46. O frontmatter da Skill não declara versão própria. O package.json do aplicativo nesse commit informa versão 2.0.14, mas esse número pertence ao Cherry Studio e não deve ser apresentado como versão da Skill.

Estrelas mudam e não provam segurança ou qualidade. Elas atendem ao critério de adoção do catálogo. A referência reproduzível é o commit, os arquivos e seus hashes, não a contagem observada.

Compatibilidade e pré-requisitos

A compatibilidade real começa com um checkout do Cherry Studio. O package.json fixado exige Node.js entre 24.11.1 e antes de 24.16.0, além de pnpm 12.3.4. A documentação do projeto orienta usar o gerenciador de versão indicado por .node-version, habilitar Corepack, instalar dependências e preparar um arquivo .env local.

O projeto documenta desenvolvimento em Windows, macOS e Linux. No Windows, os links simbólicos devem estar habilitados antes do clone. Porém, as referências desta Skill usam comandos Unix como ps, lsof, kill, nohup e sinais POSIX. Em Windows puro, o operador precisa traduzir essas verificações sem reduzir os gates de PID, diretório, porta e propriedade do processo.

Para controle visual, a Skill admite Playwright conectado por CDP ou, opcionalmente, agent-browser. A ausência de um controlador não autoriza abrir outra instância por conveniência. Logs e leitura de código podem ser suficientes para algumas perguntas.

Instalação

O repositório não apresenta a Cherry Electron Dev como pacote independente em um marketplace. Ela vive em .agents/skills/cherry-electron-dev. A instalação mais fiel é copiar essa pasta do commit auditado para o mesmo caminho de um checkout compatível, preservando o SKILL.md e as duas referências.

O download local do Bastidores contém apenas essa documentação, a licença AGPL-3.0 e ORIGEM.md. Depois de baixar, extraia os arquivos dentro de uma pasta chamada cherry-electron-dev no diretório de Skills reconhecido pelo seu cliente. Não mescle os arquivos diretamente com outra Skill.

mkdir -p .agents/skills/cherry-electron-dev
unzip cherry-electron-dev.zip -d .agents/skills/cherry-electron-dev

O comando cria arquivos no projeto. Revise o ZIP e o diff antes de continuar. Instalar a documentação não instala Cherry Studio, Node.js, pnpm, Electron, Playwright nem qualquer dependência.

Configuração antes do primeiro uso

Defina se o trabalho é desenvolvimento persistente ou teste efêmero. A Skill principal exige política persistent: uma instância saudável deve continuar rodando ao final. A referência usa ephemeral apenas para testes limitados de pull request iniciados por outro fluxo.

Crie ou valide .context/cherry-electron-dev/instance.json. O registro deve guardar workspace, Git HEAD, política, proprietário, propósito, relação iniciada ou emprestada, PID do Electron, PID ou sessão do runner, grupo de processos, portas CDP e inspector, URL exata do alvo principal, sufixo do perfil, comando, log e horário de início.

Esse arquivo é uma pista, não prova. Antes de cada ação de interface, confirme que o PID está vivo, o diretório de trabalho corresponde ao checkout, a porta pertence ao processo, a lista CDP contém o alvo esperado e o commit lançado continua compatível com o código atual.

Primeiro uso seguro

Comece com uma tarefa somente leitura. Peça ao agente para localizar uma instância já aberta do checkout e produzir o registro, sem clicar, editar ou reiniciar. Confira PID, cwd, porta, título e URL do alvo. A janela principal normal usa o caminho /windows/main/index.html, mas a porta pode variar.

Depois escolha um cenário curto, como abrir uma rota e coletar métricas do renderer em repouso. Registre TaskDuration, heap, documentos, nós e listeners antes e depois da mesma ação. A própria referência alerta que a fórmula de uso da thread principal é apenas orientação e não representa a CPU completa do aplicativo.

O resultado esperado é evidência ligada à instância certa, sem mudança de código e sem encerrar processos. Só então avance para reprodução e correção.

Como o fluxo organiza o trabalho

A sequência é deliberadamente curta: definir comportamento e prova, ler código e README próximos, validar a instância, reproduzir, coletar a menor evidência útil, rastrear o caminho responsável, mudar somente o necessário e repetir o mesmo cenário.

A referência de instância trata processos preexistentes como pertencentes ao usuário. Uma porta aberta, sozinha, nunca determina propriedade. Uma instância empacotada e outro checkout também não são substitutos.

Quando a substituição é necessária, o procedimento registra identidade e contexto, envia SIGTERM apenas ao PID principal confirmado e espera. Não usa pkill, não mata o dono arbitrário de uma porta e não escala automaticamente para SIGKILL. Se o processo não sair, a execução deve parar e pedir decisão.

Medição de desempenho sem conclusões apressadas

A referência de desempenho escolhe o perfil pela pergunta. Métricas rápidas orientam carga do renderer. Um trace de 5 a 30 segundos procura a causa de um travamento visível. Checkpoints repetidos investigam crescimento. Sampling atribui alocações. O inspector do processo principal entra apenas quando esse PID é o alvo real.

Um valor maior de heap não prova vazamento, pois o V8 pode adiar coleta. RSS inclui V8, alocações nativas, gráficos e buffers de diagnóstico. Nós, documentos e listeners ajudam a triangulação, mas não descrevem tudo. A conclusão precisa combinar sinais em checkpoints equivalentes.

A referência registra ainda um caso importante de desenvolvimento com React 19. Performance Tracks podem reter valores anteriores e atuais de propriedades e aumentar a pegada do processo enquanto heap e DOM permanecem limitados. Limpar medidas e repetir a coleta pode separar retenção de instrumentação de um vazamento equivalente em produção.

Resultado esperado

Para uma correção funcional, a saída esperada combina reprodução anterior, mudança estreita, repetição do mesmo cenário e evidência posterior. O relatório deve nomear a instância observada e dizer se ela permaneceu ativa.

Para desempenho, a entrega inclui alvo, rota, cenário, duração, baseline, deltas, caminhos dos artefatos, evidência mais forte e incerteza. Se houver correção, a comparação precisa usar condições equivalentes. Um profile isolado e sem cenário não basta.

Para inicialização, o fluxo separa rebuild nativo, bootstrap principal, migração de banco, serviços, carregamento do renderer e primeira interface interativa. Medir apenas a duração total de pnpm debug mistura fases diferentes.

Permissões e riscos

O uso funcional pode ler todo o checkout, iniciar comandos, controlar uma interface Electron por CDP, gravar estado e artefatos, anexar profilers, reiniciar a instância rastreada e, quando autorizado, editar código. Conceda somente as capacidades necessárias para a pergunta atual.

Logs, traces, heap snapshots e perfis podem carregar mensagens, URLs, prompts, tokens, caminhos locais e conteúdo privado. Guarde tudo em .context/cherry-electron-dev/, não publique artefatos brutos e sanitize qualquer evidência compartilhada.

O risco mais grave é atuar no processo errado. Não selecione alvo pelo índice zero, pelo nome genérico Electron ou apenas pela porta. Também não chame browser.close(), page.close() ou uma ação de saída no fim da coleta. A referência orienta desconectar somente a sessão de profiling.

Erros comuns e como corrigir

O CDP responde, mas a janela principal não aparece

Liste os alvos novamente e confira título e URL. Splash, migração, configurações, abas destacadas e miniaplicativos são alvos diferentes. Não navegue um alvo apenas para fazê-lo parecer correto.

O arquivo instance.json aponta para um processo encerrado

Trate o registro como obsoleto. Descubra instâncias do mesmo workspace, valide PID, cwd, porta e commit e só então atualize o arquivo. Não lance outra instância antes dessa busca.

O debug encerra logo após iniciar

Leia o log registrado. Procure bloqueio de perfil, rebuild nativo, porta ocupada, falha de banco ou erro de inicialização. Confirme também se o processo antigo realmente saiu antes de criar um substituto.

A memória do processo cresce durante o teste

Compare RSS, heap, DOM, listeners e entradas de desempenho em ciclos iguais. Salve a evidência necessária antes de limpar medidas. Use coleta de lixo forçada apenas como discriminador explícito, nunca como prova automática.

O processo principal usa CPU, mas o profile V8 não explica

Confirme o PID. O custo pode estar em Electron, addon nativo, outra thread ou processo auxiliar. No macOS, a referência admite um sample nativo curto do PID exato. Isso ainda exige interpretação e não atribui culpa sozinho.

Versão, licença e pacote auditado

A Skill sem versão própria foi fixada no commit b112a46b0e2d93105540ddbc9234ce468e9e4b46. O pacote contém cinco arquivos: SKILL.md, duas referências Markdown, LICENSE e ORIGEM.md. O SHA-256 do ZIP é 2a06534e156fe72ef1b5c1ca0c1916936f98198acddfa18333fd9fd92da9fde1.

A licença AGPL-3.0 fixada permite redistribuir o material sob seus termos. O ZIP preserva a licença integral e a origem exata. Quem modificar ou combinar o material deve avaliar as obrigações correspondentes, inclusive a oferta de código-fonte quando aplicável. Isto é descrição técnica da licença, não aconselhamento jurídico.

Limites do pacote local

O ZIP não contém o aplicativo Cherry Studio, código da aplicação, dependências, Electron, Playwright, agent-browser, Node.js, pnpm, scripts, executáveis, lockfiles, configuração, arquivo .env, perfis, bancos, caches ou userData.

Também não contém logs, capturas, traces, CPU profiles, heap snapshots, prompts, mensagens, tokens, chaves, credenciais, dados ou resultados. As duas referências foram incluídas porque o SKILL.md as torna autoridades obrigatórias para instância e desempenho. Removê-las deixaria o procedimento incompleto.

Checklist antes de usar

• Confirme que o checkout é CherryHQ/cherry-studio e registre o Git HEAD.
• Leia as instruções locais e os README próximos ao código afetado.
• Valide PID, cwd, porta, alvo e proprietário antes de controlar a interface.
• Preserve instâncias e dados preexistentes do usuário.
• Defina cenário, duração, dados, rota e evidência antes de medir.
• Separe renderer, processo principal, GPU, Vite e subprocessos.
• Use perfis limitados e desconecte apenas a sessão de diagnóstico.
• Sanitize logs, traces e snapshots antes de compartilhar.
• Não force encerramento nem use comandos amplos sem autorização explícita.
• Compare o mesmo cenário antes e depois da mudança.

Fontes oficiais consultadas

• Repositório oficial Cherry Studio
• Commit auditado
• SKILL.md fixado
• Gestão de instância Electron
• Depuração de desempenho
• Configuração oficial do ambiente de desenvolvimento
• Versões, engines e comandos do projeto
• Licença AGPL-3.0