Volte um workspace do Carbon Forge a um corte

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública, principalmente a página Snapshots do catálogo e Working in lanes, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Nomes de ferramentas, argumentos e frases citadas são os da documentação, e as citações ficam em inglês com a tradução ao lado; a documentação não dá JSON de exemplo para estas chamadas, então nenhum é mostrado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

O que são um snapshot e um corte

Um snapshot registra a revisão atual de cada página, átomo, árvore de código e entrada de biblioteca, e os patches vivos de cada lane aberta, "as one sealed manifest of ids and hashes chained to the previous snapshot." (como um único manifesto selado de ids e hashes encadeado ao snapshot anterior). Ele guarda "ids and hashes only, never a body or a blob's bytes" (só ids e hashes, nunca um corpo nem os bytes de um blob), então custa pouco tirá-lo. Um corte é um nome para um snapshot, e "it never moves." (ele nunca se move). Snapshots e cortes só são acrescentados: "the database refuses to change or remove either while the workspace exists." (o banco de dados se recusa a alterar ou remover qualquer um dos dois enquanto o workspace existir).

Passo 1. Corte o estado que talvez queira de volta

Antes de uma mudança grande ou arriscada, chame snapshots.cut com um name. Um nome tem de 1 a 128 letras, dígitos, pontos, hífens e sublinhados, começando por letra ou dígito; os exemplos da documentação são stable, v0.9 e release-2026.10.16. Reutilizar um nome é recusado, porque um corte nunca se move: a recusa diz para nomear o novo estado com um novo corte. Cortar exige o papel de editor.

Passo 2. Encontre o corte depois

cuts.list responde os cortes do workspace, do mais recente para o mais antigo, cada um com o snapshot que nomeia. snapshots.get com cut responde um snapshot: seu digest, seu selo, seu predecessor, suas contagens e as lanes abertas que registrou. Ambas são leituras para o papel de leitor.

Passo 3. Leia o que mudou desde o corte

cuts.notes lista cada changeset integrado depois de um limite até outro, em ordem de integração, agrupado pela primeira palavra da intenção. O to deve ser um corte ou um id de snapshot, então, para comparar o corte com o workspace como está agora, chame primeiro snapshots.cut sem nome e depois passe o seu corte como from e o id do snapshot novo como to. Acrescente path_glob para manter só os changesets que tocaram os caminhos que interessam. Cada changeset nomeia sua intenção, seu autor, a lane de onde foi integrado e os caminhos que tocou, o que costuma bastar para ver de quem é o trabalho que você vai desfazer.

Passo 4. Veja uma entidade como o corte a guarda

snapshots.materialize com cut responde uma página do manifesto do corte, cada entrada com estes campos:

kind, entity_id, revision_id, content_hash, seal_hash, path, title

Acrescente entity_id e ele responde essa entidade na revisão que o corte nomeia: o corpo e os metadados de uma página, o corpo de um átomo, as entradas de uma árvore, o hash de uma entrada de biblioteca. "The same snapshot answers the same every time." (O mesmo snapshot responde o mesmo toda vez). Uma entrada cuja revisão foi expurgada desde então responde purged e não traz conteúdo.

Passo 5. Confira quem pode reverter

snapshots.revert exige o papel de administrador e, entre os perfis de token, está só em full, então um agente com um token SCM agent ou SCM release não pode chamá-lo. Num workspace cujo trunk é protegido, uma reversão que gravaria uma árvore de código ou uma entrada de biblioteca, ou uma página ou átomo onde as páginas também são protegidas, é recusada antes de gravar qualquer coisa: workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Passo 6. Reverta para o corte

Chame snapshots.revert com cut e intent, a mensagem do changeset, de 1 a 4.096 caracteres. "Revert is forward only: nothing is removed or rewritten." (A reversão só anda para a frente: nada é removido nem reescrito). Cada entidade cujo conteúdo difere do corte recebe uma revisão nova com o conteúdo do corte, tudo num único changeset selado. Uma revisão restaurada de página ou átomo traz o comentário Restored from cut <cut> (R#<revision>). Onde o corte registrou caminhos e títulos, uma página renomeada volta ao caminho e título antigos, e o caminho que ela deixa continua redirecionando para ela. Depois um snapshot novo é cortado, marcado com o corte de onde veio a reversão.

Passo 7. Leia a resposta

A resposta é o snapshot novo com estes campos:

snapshot, cut, changeset_id, restored, unchanged, extraneous, collisions

Cada linha de restored é:

kind, entity_id, from_revision_id, new_revision_id

unchanged é uma contagem. collisions lista as entidades cujo caminho antigo agora pertence a outra página ou átomo vivo: ali "the body and metadata alone are restored, and nothing moves." (só o corpo e os metadados são restaurados, e nada se move). Duas recusas não gravam nada: um corte que nomeia uma revisão expurgada, ou uma entidade que agora está na lixeira, que a recusa manda restaurar primeiro; e um corte com o qual o workspace já coincide, respondido com Every entity already holds what cut <cut> names; nothing changes.

Passo 8. Cuide do que a reversão não toca

"Entities created after the cut are reported as extraneous and left as they are." (Entidades criadas depois do corte são informadas como extraneous e deixadas como estão). Uma página que o agente da noite criou continua lá depois da reversão; decida para cada uma se ela fica. Como a reversão é um changeset como qualquer outro, o trabalho da noite e o desfazer continuam legíveis no histórico, e cuts.notes num intervalo que atravesse a reversão mostra os dois. Para uma única integração em vez de um workspace inteiro, changesets.revert desfaz um único changeset, e aceita lane, então num trunk protegido ele pode ser guardado numa lane e integrado por ela.

Para nomear versões com cortes e publicá-las, leia o nosso guia Corte uma versão no Carbon Forge e envie-a ao GitHub.

O que a documentação deixa sem resposta

• Como voltar um trunk protegido a um corte. snapshots.revert não aceita lane, e a documentação não mostra a reversão de um corte inteiro por uma lane.
• Como remover de uma vez as entidades extraneous. A documentação as informa e para aí.
• O que cut contém na resposta de uma reversão. Na descrição da documentação, o snapshot novo é cortado sem nome próprio, e o campo não é explicado para esta chamada.
• Um exemplo completo. O catálogo indica cada argumento, mas não dá nenhuma chamada ou resposta de exemplo para estas sete ferramentas.