Riportare un workspace Carbon Forge a un cut

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Carbon Forge è sviluppato da noi di 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica (in inglese), soprattutto la pagina di catalogo Snapshots e Working in lanes, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Nomi degli strumenti, argomenti e frasi citate sono quelli della documentazione, le citazioni in inglese con la traduzione accanto; la documentazione non dà JSON di esempio per queste chiamate, quindi qui non ne mostriamo. Dove la documentazione lascia una domanda aperta, l'ultima sezione lo dice.

Cosa sono uno snapshot e un cut

Uno snapshot registra la revisione attuale di ogni pagina, atom, albero di codice e voce di libreria, e le patch vive di ogni lane aperta, "as one sealed manifest of ids and hashes chained to the previous snapshot." (come un unico manifesto sigillato di id e hash concatenato allo snapshot precedente). Contiene "ids and hashes only, never a body or a blob's bytes" (solo id e hash, mai un corpo o i byte di un blob), quindi costa poco. Un cut è il nome di uno snapshot, e "it never moves." (non si sposta mai). Snapshot e cut si possono solo aggiungere: "the database refuses to change or remove either while the workspace exists." (il database si rifiuta di modificare o rimuovere l'uno o l'altro finché il workspace esiste).

Fate un cut dello stato che potreste rivolere

Prima di una modifica grande o rischiosa, chiamate snapshots.cut con un name. Un nome è da 1 a 128 lettere, cifre, punti, trattini e trattini bassi, e comincia con una lettera o una cifra; gli esempi della documentazione sono stable, v0.9 e release-2026.10.16. Riusare un nome viene rifiutato, perché un cut non si sposta mai: il rifiuto dice di dare un nome al nuovo stato con un nuovo cut. Fare un cut richiede il ruolo editor.

Ritrovate il cut più tardi

cuts.list restituisce i cut del workspace, dal più recente, ciascuno con lo snapshot che nomina. snapshots.get con cut restituisce uno snapshot: digest, sigillo, predecessore, conteggi e le lane aperte che ha registrato. Entrambe sono letture per il ruolo viewer.

Leggete cosa è cambiato dopo il cut

cuts.notes elenca ogni changeset integrato dopo un estremo fino a un altro, in ordine di integrazione, raggruppati per la prima parola dell'intent. Il suo to deve essere un cut o l'id di uno snapshot, quindi per confrontare il cut con il workspace com'è adesso chiamate prima snapshots.cut senza nome, poi passate il vostro cut come from e l'id del nuovo snapshot come to. Aggiungete path_glob per tenere solo i changeset che hanno toccato i percorsi che vi interessano. Ogni changeset indica intent, autore, la lane da cui è stato integrato e i percorsi toccati, il che di solito basta per vedere di chi è il lavoro che state per annullare.

Guardate un'entità come la conserva il cut

snapshots.materialize con cut restituisce una pagina del manifesto del cut, ogni voce con questi campi:

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

Aggiungete entity_id e restituisce quell'entità alla revisione indicata dal cut: corpo e metadati di una pagina, corpo di un atom, voci di un albero, hash di una voce di libreria. "The same snapshot answers the same every time." (lo stesso snapshot risponde ogni volta allo stesso modo). Una voce la cui revisione è stata nel frattempo eliminata risponde purged e non porta contenuto.

Verificate chi può fare il revert

snapshots.revert richiede il ruolo admin e, tra i preset dei token, è solo in full, quindi un agente con un token SCM agent o SCM release non può chiamarlo. In un workspace con il trunk protetto, un revert che scriverebbe un albero di codice o una voce di libreria, o una pagina o un atom dove anche le pagine sono protette, viene rifiutato prima di scrivere qualsiasi cosa: workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Fate il revert al cut

Chiamate snapshots.revert con cut e intent, il messaggio del changeset, da 1 a 4.096 caratteri. "Revert is forward only: nothing is removed or rewritten." (il revert va solo avanti: niente viene rimosso o riscritto). Ogni entità il cui contenuto differisce da quello del cut riceve una nuova revisione con il contenuto del cut, tutto in un solo changeset sigillato. Una revisione ripristinata di una pagina o di un atom porta il commento Restored from cut <cut> (R#<revision>). Dove il cut ha registrato percorsi e titoli, una pagina rinominata torna al vecchio percorso e titolo, e il percorso che lascia continua a reindirizzare a essa. Poi viene fatto un nuovo snapshot, marcato con il cut da cui è stato fatto il revert.

Leggete la risposta

La risposta è il nuovo snapshot con questi campi:

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

Ogni riga di restored è:

kind, entity_id, from_revision_id, new_revision_id

unchanged è un conteggio. collisions elenca le entità il cui vecchio percorso è ora occupato da un'altra pagina o atom vivo: lì "the body and metadata alone are restored, and nothing moves." (vengono ripristinati solo corpo e metadati, e niente si sposta). Due rifiuti non scrivono nulla: un cut che nomina una revisione eliminata, o un'entità ora nel cestino, che il rifiuto vi dice di ripristinare prima; e un cut a cui il workspace corrisponde già, a cui si risponde con Every entity already holds what cut <cut> names; nothing changes.

Occupatevi di ciò che il revert lascia stare

"Entities created after the cut are reported as extraneous and left as they are." (le entità create dopo il cut sono segnalate come extraneous e lasciate come sono). Una pagina creata dall'agente nella notte è ancora lì dopo il revert; decidete per ciascuna se resta. Poiché il revert è un changeset come gli altri, il lavoro della notte e il suo annullamento restano entrambi leggibili nella cronologia, e cuts.notes eseguito a cavallo del revert li mostra tutti e due. Per un'integrazione sola invece di un intero workspace, changesets.revert annulla un singolo changeset e accetta lane, quindi su un trunk protetto può essere salvato su una lane e integrato da lì.

Per dare un nome alle release con i cut e pubblicarle, leggete la nostra guida Creare una release in Carbon Forge e pubblicarla su GitHub.

Cosa lascia senza risposta la documentazione

• Come riportare un trunk protetto a un cut. snapshots.revert non accetta lane, e la documentazione non mostra il revert di un intero cut attraverso una lane.
• Come rimuovere in un passo solo le entità extraneous. La documentazione le segnala e si ferma lì.
• Cosa contiene cut nella risposta di un revert. Nella descrizione della documentazione il nuovo snapshot viene fatto senza un nome proprio, e il campo non è spiegato per questa chiamata.
• Un esempio completo. Il catalogo indica ogni argomento ma non dà una chiamata o una risposta di esempio per questi sette strumenti.