Einen Carbon-Forge-Workspace auf einen Cut zurücksetzen

Auch auf: English, Español, Português, 日本語, Français, 한국어, 简体中文, Italiano, हिन्दी · Alle Anleitungen auf Deutsch

Offenlegung: Wir entwickeln Carbon Forge bei 100monkeys.ai, lesen Sie dies also als Bericht des Herstellers. Einer unserer KI-Agenten hat diese Anleitung aus der öffentlichen Doku (auf Englisch) entworfen, vor allem der Katalogseite Snapshots und Working in lanes, und das Unternehmen hat sie geprüft; diese deutsche Ausgabe ist eine Übersetzung der englischen Originalanleitung. Werkzeugnamen, Argumente und zitierte Sätze stammen aus der Doku; Zitate bleiben auf Englisch, mit der Übersetzung daneben. Die Doku gibt für diese Aufrufe kein ausgearbeitetes JSON, daher zeigen wir keines. Wo die Doku eine Frage offen lässt, sagt es der letzte Abschnitt.

Was ein Snapshot und ein Cut sind

Ein Snapshot hält die aktuelle Revision jeder Seite, jedes Atoms, jedes Code-Baums und jedes Bibliothekseintrags fest, dazu die lebenden Patches jeder offenen Lane, "as one sealed manifest of ids and hashes chained to the previous snapshot." (als ein versiegeltes Manifest aus IDs und Hashes, verkettet mit dem vorigen Snapshot.) Er enthält "ids and hashes only, never a body or a blob's bytes" (nur IDs und Hashes, nie einen Inhalt oder die Bytes eines Blobs), kostet also wenig. Ein Cut ist ein Name für einen Snapshot, und "it never moves." (er bewegt sich nie.) Snapshots und Cuts werden nur angehängt: "the database refuses to change or remove either while the workspace exists." (die Datenbank verweigert es, eines von beiden zu ändern oder zu entfernen, solange der Workspace besteht.)

Schritt 1. Den Stand schneiden, den Sie vielleicht zurückwollen

Rufen Sie vor einer großen oder riskanten Änderung snapshots.cut mit einem name auf. Ein Name hat 1 bis 128 Buchstaben, Ziffern, Punkte, Bindestriche und Unterstriche und beginnt mit einem Buchstaben oder einer Ziffer; die Beispiele der Doku sind stable, v0.9 und release-2026.10.16. Einen Namen wiederzuverwenden wird abgelehnt, weil ein Cut sich nie bewegt: Die Ablehnung sagt, den neuen Stand mit einem neuen Cut zu benennen. Schneiden braucht die Rolle Editor.

Schritt 2. Den Cut später finden

cuts.list liefert die Cuts des Workspaces, die neuesten zuerst, jeden mit dem Snapshot, den er benennt. snapshots.get mit cut liefert einen Snapshot: seinen Digest, sein Siegel, seinen Vorgänger, die Zähler und die offenen Lanes, die er festgehalten hat. Beides sind Lesezugriffe für die Rolle Viewer.

Schritt 3. Lesen, was sich seit dem Cut geändert hat

cuts.notes listet jedes Changeset, das nach einer Grenze bis zu einer anderen gelandet ist, in Landereihenfolge, gruppiert nach dem ersten Wort seines Intents. Sein to muss ein Cut oder eine Snapshot-ID sein; um den Cut mit dem heutigen Workspace zu vergleichen, rufen Sie also zuerst snapshots.cut ohne Namen auf und übergeben dann Ihren Cut als from und die ID des neuen Snapshots als to. Mit path_glob behalten Sie nur Changesets, die die Pfade berührt haben, die Sie interessieren. Jedes Changeset nennt seinen Intent, seinen Akteur, die Lane, aus der es gelandet ist, und die berührten Pfade; meist genügt das, um zu sehen, wessen Arbeit Sie gleich rückgängig machen.

Schritt 4. Eine Entität so ansehen, wie der Cut sie hält

snapshots.materialize mit cut liefert eine Seite des Manifests des Cuts, jeder Eintrag mit diesen Feldern:

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

Mit entity_id liefert es diese Entität in der Revision, die der Cut nennt: Inhalt und Metadaten einer Seite, den Inhalt eines Atoms, die Einträge eines Baums, den Hash eines Bibliothekseintrags. "The same snapshot answers the same every time." (Derselbe Snapshot antwortet jedes Mal gleich.) Ein Eintrag, dessen Revision inzwischen gelöscht wurde, antwortet mit purged und trägt keinen Inhalt.

Schritt 5. Prüfen, wer zurücksetzen darf

snapshots.revert braucht die Rolle Admin und steht von den Token-Voreinstellungen nur in full; ein Agent mit einem SCM-Agent- oder SCM-Release-Token kann es also nicht aufrufen. Auf einem Workspace mit geschütztem Trunk wird ein Zurücksetzen, das einen Code-Baum oder Bibliothekseintrag schreiben würde, oder eine Seite oder ein Atom, wo auch Seiten geschützt sind, abgelehnt, bevor etwas geschrieben wird: workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Schritt 6. Auf den Cut zurücksetzen

Rufen Sie snapshots.revert mit cut und intent auf, der Nachricht des Changesets, 1 bis 4.096 Zeichen. "Revert is forward only: nothing is removed or rewritten." (Zurücksetzen geht nur vorwärts: Nichts wird entfernt oder umgeschrieben.) Jede Entität, deren Inhalt vom Cut abweicht, bekommt eine neue Revision mit dem Inhalt des Cuts, alle in einem versiegelten Changeset. Eine wiederhergestellte Revision einer Seite oder eines Atoms trägt den Kommentar Restored from cut <cut> (R#<revision>). Wo der Cut Pfade und Titel festgehalten hat, kehrt eine umbenannte Seite zu ihrem alten Pfad und Titel zurück, und der Pfad, den sie verlässt, leitet weiter auf sie um. Dann wird ein neuer Snapshot geschnitten, markiert mit dem Cut, auf den zurückgesetzt wurde.

Schritt 7. Die Antwort lesen

Die Antwort ist der neue Snapshot mit diesen Feldern:

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

Jede Zeile in restored lautet:

kind, entity_id, from_revision_id, new_revision_id

unchanged ist ein Zähler. collisions listet Entitäten, deren alten Pfad jetzt eine andere lebende Seite oder ein anderes Atom hält: Dort werden "the body and metadata alone are restored, and nothing moves." (nur Inhalt und Metadaten wiederhergestellt, und nichts bewegt sich.) Zwei Ablehnungen schreiben gar nichts: ein Cut, der eine gelöschte Revision nennt, oder eine Entität, die jetzt im Papierkorb liegt, die Sie laut Ablehnung zuerst wiederherstellen sollen; und ein Cut, dem der Workspace schon entspricht, beantwortet mit Every entity already holds what cut <cut> names; nothing changes.

Schritt 8. Mit dem umgehen, was das Zurücksetzen stehen lässt

"Entities created after the cut are reported as extraneous and left as they are." (Nach dem Cut angelegte Entitäten werden als extraneous gemeldet und bleiben, wie sie sind.) Eine Seite, die der nächtliche Agent angelegt hat, ist nach dem Zurücksetzen noch da; entscheiden Sie für jede, ob sie bleibt. Weil das Zurücksetzen ein Changeset wie jedes andere ist, bleiben die Arbeit der Nacht und ihr Rückgängig beide im Verlauf lesbar, und cuts.notes über das Zurücksetzen hinweg zeigt beides. Für eine einzelne Landung statt eines ganzen Workspaces macht changesets.revert ein einzelnes Changeset rückgängig, und es nimmt lane, kann also auf einem geschützten Trunk auf einer Lane abgelegt und dort gelandet werden.

Um Releases mit Cuts zu benennen und zu veröffentlichen, lesen Sie unsere Anleitung Ein Release in Carbon Forge schneiden und zu GitHub pushen.

Was die Doku offen lässt

• Wie man einen geschützten Trunk auf einen Cut zurücksetzt. snapshots.revert nimmt kein lane, und die Doku führt das Zurücksetzen eines ganzen Cuts über eine Lane nicht vor.
• Wie man die extraneous-Entitäten in einem Schritt entfernt. Die Doku meldet sie und hört dort auf.
• Was cut in der Antwort eines Zurücksetzens enthält. Der neue Snapshot wird laut Beschreibung der Doku ohne eigenen Namen geschnitten, und das Feld wird für diesen Aufruf nicht erklärt.
• Ein ausgearbeitetes Beispiel. Der Katalog nennt jedes Argument, gibt aber für diese sieben Werkzeuge keinen Beispielaufruf und keine Beispielantwort.