MoonshotAI/sync-changelog

Sincronizar Changelog

Visão Geral

kimi-code usa changesets para versionamento. Cada pacote tem seu próprio CHANGELOG.md. O pacote CLI voltado para o usuário, @moonshot-ai/kimi-code, escreve seu changelog aqui:

apps/kimi-code/CHANGELOG.md

Este arquivo é a única fonte upstream para o changelog do site de documentação. Changelogs de pacotes internos como packages/*/CHANGELOG.md não vão para o site de documentação.

Após o fluxo de lançamento ser concluído (PR de lançamento mesclado → Version Packages concluído → npm publicado com sucesso), os mantenedores executam manualmente esta habilidade para copiar as novas entradas do changelog CLI para o site de documentação, traduzir o incremento em inglês para chinês, aguardar uma revisão humana opcional, depois commitar em um branch dedicado e abrir um PR.

Quando Usar

• Uma nova versão foi publicada no npm.
• O topo de apps/kimi-code/CHANGELOG.md contém blocos de versão que ainda não estão em docs/en/release-notes/changelog.md.
• O fluxo gen-docs não executa isso automaticamente; os mantenedores devem fazer isso explicitamente após o lançamento.

Não execute isso antes do PR de lançamento ser mesclado. Nesse ponto, changesets ainda não escreveu a nova versão em apps/kimi-code/CHANGELOG.md.

Origem e Destinos

Arquivo	Função	Editado por
apps/kimi-code/CHANGELOG.md	Única fonte upstream, gerada por changesets	Nunca editar manualmente
docs/en/release-notes/changelog.md	Changelog de documentação em inglês; fonte da verdade para docs	Esta habilidade
docs/zh/release-notes/changelog.md	Changelog de documentação em chinês, traduzido do inglês	Esta habilidade, seguindo translate-docs

Regra principal: o changelog de documentação em inglês é a fonte da verdade, e o chinês é traduzido do inglês. Isso corresponde ao translate-docs.

Pré-condições

Antes de editar, confirme:

• A versão lançada existe no npm (npm view @moonshot-ai/kimi-code versions --json) ou tem uma tag de lançamento GitHub correspondente.
• O topo de apps/kimi-code/CHANGELOG.md é essa nova versão.

Se alguma condição não for verdadeira, pare e confirme com o usuário.

Não edite ou commite diretamente no main. Todo o trabalho de sincronização acontece em um branch dedicado criado na etapa 1.

Fluxo de Trabalho

1. Preparar Branch

Comece a partir de um branch padrão atualizado:

git fetch origin
git checkout main
git pull --ff-only origin main

Antes de criar o branch, veja o intervalo de versão para que o nome do branch corresponda à versão mais recente sendo sincronizada:

rg '^## ' apps/kimi-code/CHANGELOG.md | head -5
rg '^## ' docs/en/release-notes/changelog.md | head -5

Nomeie o branch após a versão upstream mais recente que ainda não está na página de documentação em inglês:

docs/changelog-sync-<versão-mais-recente>

Exemplo: sincronizando 0.2.1 apenas → docs/changelog-sync-0.2.1.

git checkout -b docs/changelog-sync-<versão-mais-recente>

Se o branch já existir localmente ou no remoto, pare e confirme com o usuário em vez de reutilizá-lo.

2. Encontrar o Intervalo de Versão

Use as mesmas listas de versão da etapa 1. Confirme:

• Primeira sincronização: copie todos os blocos de versão upstream para a página em inglês.
• Sincronização incremental: copie cada bloco de versão upstream acima da versão mais recente já presente na página em inglês.

Use a ordem upstream: versão mais recente primeiro.

3. Remover Decorações e Extrair Texto da Entrada

As entradas upstream têm esta aparência:

- [#317](https://github.com/...) [`2f51db4`](https://github.com/...) Thanks [@user](https://github.com/...)! - Limpar avisos de lint ...

Changesets pode adicionar um crédito Thanks ...!, mas ele deve ser removido sempre. Mantenha:

• Cabeçalhos de versão como ## 0.2.0.
• Apenas o texto do corpo de cada entrada, após a decoração de PR/hash e qualquer crédito Thanks ...! ter sido removido.

Remova:

• O H1 upstream # @moonshot-ai/kimi-code porque a página de documentação já tem # Changelog.
• Subtítulos de changesets como ### Patch Changes, ### Minor Changes e ### Major Changes.
• Links de PR como [#317](...).
• Links de hash de commit como [`2f51db4`](...).
• O crédito Thanks [@user](...)!, incluindo a forma multi-autor Thanks [@a](...), [@b](...)!. Remova todo o segmento Thanks ...! sempre, independentemente de o recurso estar habilitado.

Após a remoção, cada entrada é - <texto do corpo>.

Remova detalhes internos de SDK e fornecedor. Este changelog atende aos usuários da CLI e web do @moonshot-ai/kimi-code. Dentro de uma entrada, mantenha apenas o que os usuários da CLI/web podem perceber e remova sentenças que documentam detalhes internos em vez de comportamento visível ao usuário. Aplique isso tanto na página em inglês quanto na em chinês:

• Remova sentenças sobre como o SDK mapeia uma capacidade, constrói aliases de modelo ou expõe uma flag através de uma API como getExperimentalFeatures() — isso pertence ao changelog do SDK, não aqui.
• Remova mecânica de implementação de fornecedor/formato de transmissão (marcadores XML como <tools_added>, explicações de campo de protocolo, "o protocolo de transmissão não mudou", mecânica de cache-hit) a menos que seja o comportamento que um usuário percebe.
• Mantenha o efeito visível ao usuário e quaisquer restrições que os usuários devem seguir (por exemplo "textos de pergunta devem ser únicos").

Não altere fatos ou remova um comportamento real visível ao usuário — apenas corte o arcabouço interno. Para entradas muito longas e com muitos detalhes internos, esse corte se aplica também na página em inglês, não apenas na tradução.

Prefixo web: se a entrada for uma mudança na interface web, prefixe o texto do corpo com web: para que os leitores saibam que afeta a interface web:

- web: <texto do corpo>

Uma entrada conta como mudança na interface web quando seu commit upstream toca em apps/kimi-web/. Verifique com git show --name-only <hash> (o hash do commit é aquele removido acima). gen-changesets escreve esse prefixo para mudanças web, então geralmente já está presente no upstream — preserve quando estiver lá e adicione quando uma entrada web estiver faltando. Quando um commit toca tanto código web quanto não-web, use web: apenas se a mudança visível ao usuário descrita pela entrada estiver na interface web. Mantenha o prefixo web: também na página em chinês — é um marcador de escopo, não texto traduzido.

Regra de idioma upstream: gen-changesets exige que as entradas do changelog estejam em inglês. Se o changelog CLI upstream contiver uma entrada não-inglesa, pare e reporte ao usuário. Não reescreva silenciosamente durante a sincronização de docs.

Regra de texto público: não copie endpoints internos reais, nomes de chaves, nomes de contas ou nomes de serviços para changelogs de documentação. Substitua exemplos com placeholders neutros como example.com, example.test ou YOUR_API_KEY, preservando o significado visível ao usuário.

4. Mesclar, Deduplicar e Classificar Entradas

Antes de classificar, mescle entradas relacionadas e remova redundâncias do changelog voltado ao usuário:

• Mesclar micro-ajustes para a mesma superfície. Agrupe vários pequenos ajustes para a mesma área de UI ou recurso em uma entrada concisa em um nível mais alto. Por exemplo, "alterar a altura padrão do compositor" e "alterar a fonte padrão do compositor" se fundem em "Melhorar o estilo padrão do compositor." Use o ancestral comum mais específico (compositor, página de configurações, cartão de ferramenta, etc.). Classifique a entrada mesclada pelo seu efeito combinado e mantenha o prefixo web: se a mudança combinada ainda for voltada para web.
• Mesclar correções de mesma superfície ou mesmo tipo quando houver três ou mais. A seção Bug Fixes tende a acumular muitas correções estreitas de UI/polimento que soam como ruído quando listadas uma a uma. Quando três ou mais correções visam a mesma área (por exemplo, vários cartões de ferramenta na TUI ou a superfície de sessão/conversação web) ou a mesma classe de problema (por exemplo, várias correções de "pulo/oscilação/colapso durante streaming"), mescle-as em uma entrada de nível mais alto. Exemplos:
  • "Corrigir o colapso do cartão da ferramenta Bash...", "Corrigir o pulo de altura do cartão da ferramenta Edit...", "Corrigir a oscilação do cartão da ferramenta Edit enquanto seu resultado flui..." → "Corrigir vários cartões de ferramenta TUI pulando, oscilando ou colapsando em altura quando os resultados fluem ou terminam com saída curta."
  • "Corrigir a barra lateral recolhida não ocultando...", "Parar o histórico de chat de reproduzir sua animação de entrada...", "Corrigir componentes de ferramenta pulando a conversa quando expandidos/recolhidos" → "web: Corrigir vários problemas de layout e exibição ao alternar sessões, incluindo a barra lateral recolhida não ocultando, o histórico de chat reproduzindo sua animação de entrada e componentes de ferramenta pulando a conversa."
  • Mantenha web: se as correções mescladas forem todas voltadas para web. Classifique como Bug Fixes.
  • Não mescle excessivamente. Deixe uma correção isolada quando for ampla, de alto valor ou genuinamente distinta (por exemplo, bugs de chamada de ferramenta de modelo/fornecedor, corrupção de lista de sessão, lacunas de conclusão de arquivo). A mesclagem é para correções de baixo valor para o leitor e de formato semelhante que soam como uma parede de tópicos semelhantes.
• Remover detalhes de API/servidor cobertos por uma entrada web. Se uma entrada adiciona um recurso de UI web (por exemplo, uma página de sessões arquivadas) e outra entrada adiciona apenas os endpoints de servidor ou REST/WebSocket que existem exclusivamente para alimentar esse recurso web, mantenha a entrada web: e remova a entrada de API. Usuários de CLI e web percebem a página web; a API de suporte é detalhe de implementação sem valor independente neste changelog. Mantenha a entrada de API apenas quando tiver valor independente para o usuário — um novo endpoint público que consumidores de SDK ou servidor chamam diretamente, ou uma capacidade utilizável fora do recurso web. Quando em dúvida, mantenha ambos e deixe o revisor decidir.

O changelog de documentação usa cinco tipos de seção:

Seção em inglês	Seção em chinês	Significado
### Features	### 新功能	Nova funcionalidade visível ao usuário, como um novo comando, flag, modo ou capacidade que não existia antes
### Polish	### 优化	Melhorias visíveis ao usuário em funcionalidades existentes, incluindo ajustes de UX, ajustes de comportamento e melhorias de desempenho que não são correções ou novas capacidades
### Bug Fixes	### 修复	Correções para comportamento que estava quebrado
### Refactors	### 重构	Mudanças internas sem alteração de comportamento visível ao usuário, incluindo build, CI, testes, limpeza de dependências e renomeações internas
### Other	### 其他	Qualquer coisa que não se encaixa acima, como trocas de CDN/endpoint e artefatos relacionados a documentação

Processo de classificação:

1. Classifique a partir do texto da entrada extraída primeiro.
2. Se não estiver claro, inspecione o commit ou PR relacionado:
   • Use o hash do commit extraído com git show <hash>.
   • Ou use o número do PR com gh pr view <NNN>.
3. Se ainda não estiver claro, coloque em Other. Não adivinhe ou force entradas em Features.

Features vs. Polish: pergunte se a entrada introduz algo que o usuário não podia fazer antes. Se sim (novo comando, flag, modo, visualizador ou capacidade), use Features. Se apenas melhora uma superfície existente (um painel de UI que já existia, um prompt existente, um cartão de ferramenta existente, um pipeline de payload existente), use Polish. Verbos como Add não significam automaticamente Features — uma pequena adição visual a uma UI existente ainda é polish.

Mudanças de comportamento padrão: alterar o valor padrão de uma capacidade existente (por exemplo, ativar um recurso por padrão) é geralmente Polish, porque a capacidade já existia. Use Features apenas quando o novo padrão altera materialmente a experiência pronta para uso para a maioria dos usuários de uma forma que eles não podiam obter antes. Quando genuinamente ambíguo, sinalize e confirme com o revisor em vez de adivinhar.

Dicas de palavras-chave:

• Features: Add ... command/flag/option/mode/viewer, Introduce, Support, Allow, Enable, Implement, New ... command/flag/option
• Bug Fixes: Fix, Resolve, Correct, Address, Prevent ... from, Stop ... from, ... no longer ...
• Polish: Polish, Optimize, Improve, Enhance, Speed up, Reduce, Cap, Shorten, Wrap, Clarify, Tweak, Adjust, Offload, Show ... in existing surface, ajustes de desempenho e UX em funcionalidades existentes
• Refactors: Refactor, Rename, Clean up, Simplify, Remove unused, Migrate to, Unify, Restructure, Internal, bumps de dependência, mudanças puras de CI/build/teste
• Other: artefatos de documentação, trocas de CDN/endpoint, qualquer coisa que genuinamente não se encaixa em nenhuma outra seção

Dentro de cada versão, a ordem da seção é:

Features → Polish → Bug Fixes → Refactors → Other

Omita seções vazias. Dentro de cada seção, ordene entradas por valor para o leitor, não por ordem upstream:

1. Coloque as mudanças mais valiosas, óbvias e maiores primeiro.
2. Prefira funcionalidades amplas visíveis ao usuário, correções que alteram fluxo de trabalho, bugs de alta frequência e grandes melhorias transversais em vez de pequeno polimento, casos extremos estreitos e limpeza interna.
3. Dentro de Polish, coloque melhorias de UX ou desempenho diretamente visíveis ao usuário (algo que os usuários podem ver ou sentir) antes de ajustes de protocolo ou comportamento interno (algo que torna o modelo ou pipeline mais confiável, mas é invisível para os usuários).
4. Se entradas tiverem valor semelhante, preserve a ordem upstream.

Não reformule ou exagere entradas apenas para parecerem mais importantes; apenas reordene entradas existentes.

5. Escrever a Página em Inglês

Nunca altere o cabeçalho da página em inglês:

# Changelog

This page documents the changes in each Kimi Code CLI release.

Insira novos blocos de versão imediatamente após o parágrafo do cabeçalho e antes da versão mais recente anterior.

Cada cabeçalho de versão deve carregar sua data de lançamento entre parênteses:

## <versão> (YYYY-MM-DD)

Pegue a data da tag de lançamento GitHub publicada da versão, não de quando você executa a sincronização:

git log -1 --format=%cs "@moonshot-ai/kimi-code@<versão>"

Use o formulário de parêntese de meia largura (YYYY-MM-DD) na página em inglês. Nunca invente ou adivinhe uma data; se a tag estiver faltando, pare e confirme com o usuário.

Exemplo:

## 0.2.0 (2026-05-26)

### Bug Fixes

- Corrige a TUI não restaurando a lista de tarefas atual após retomar uma sessão.

### Refactors

- Limpa avisos de lint em todo o CLI, exemplos de SDK e código de runtime empacotado sem alterar o comportamento do produto.
- Atualiza o fluxo de lançamento nativo para usar ações de artefato GitHub atuais.