他の言語: English, Español, Português, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · 日本語のガイド一覧
開示: Carbon Forge は 100monkeys.ai で開発しているため、作り手による説明として読んでください。このガイドは公開ドキュメント、主にカタログの Snapshots ページと Working in lanes をもとに当社の AI エージェントが下書きし、当社が確認しました。この日本語版は英語の原文ガイドの翻訳です。ツール名、引数、引用文はドキュメント自身のもので、引用は英語のまま載せ、訳を添えています。ドキュメントにはこれらの呼び出しの JSON の例がないため、ここでも載せていません。ドキュメントが答えていない点は、最後の節に書いています。
スナップショットとカットとは
スナップショットは、すべてのページ、アトム、コードツリー、ライブラリエントリの現在のリビジョンと、開いているすべてのレーンの生きたパッチを記録します。"as one sealed manifest of ids and hashes chained to the previous snapshot."(前のスナップショットに連結された、ID とハッシュの封印済みマニフェスト 1 つとして)。保持するのは "ids and hashes only, never a body or a blob's bytes"(ID とハッシュだけで、本文やブロブのバイトは決して含まない)ので、取るのに手間はかかりません。カットは 1 つのスナップショットにつけた名前で、"it never moves."(決して動かない)。スナップショットとカットは追記のみです。"the database refuses to change or remove either while the workspace exists."(ワークスペースがある限り、データベースはどちらの変更も削除も拒む)。
ステップ 1. 戻したくなるかもしれない状態をカットする
大きな変更や危険な変更の前に、name を付けて snapshots.cut を呼びます。名前は 1 から 128 文字の英字、数字、ドット、ハイフン、アンダースコアで、英字か数字で始まります。ドキュメントの例は stable、v0.9、release-2026.10.16 です。カットは動かないので、名前の再利用は拒否され、拒否のメッセージは新しい状態には新しいカットの名前を付けるよう伝えます。カットには編集者のロールが必要です。
ステップ 2. 後でカットを見つける
cuts.list はワークスペースのカットを新しい順に、それぞれが指すスナップショットとともに返します。cut を付けた snapshots.get は 1 つのスナップショットを返します。ダイジェスト、封印、直前のスナップショット、件数、記録された開いているレーンです。どちらも閲覧者のロールで読めます。
ステップ 3. カット以降に変わったことを読む
cuts.notes は、ある境界の後から別の境界までにランディングしたチェンジセットを、ランディング順に、インテントの最初の単語ごとにまとめて並べます。to はカットかスナップショット ID でなければならないので、カットを今のワークスペースと比べるには、まず名前なしで snapshots.cut を呼び、自分のカットを from、新しいスナップショットの ID を to に渡します。path_glob を加えると、気になるパスに触れたチェンジセットだけに絞れます。各チェンジセットはインテント、実行者、ランディング元のレーン、触れたパスを示すので、これから取り消すのが誰の作業かはたいていそれでわかります。
ステップ 4. カットが保持するとおりにエンティティを見る
cut を付けた snapshots.materialize は、カットのマニフェストを 1 ページ分返し、各エントリには次のフィールドがあります。
kind, entity_id, revision_id, content_hash, seal_hash, path, titleentity_id を加えると、カットが指すリビジョンでのそのエンティティを返します。ページなら本文とメタデータ、アトムなら本文、ツリーならエントリ、ライブラリエントリならハッシュです。"The same snapshot answers the same every time."(同じスナップショットは毎回同じ答えを返す)。その後リビジョンがパージされたエントリは purged を返し、内容を持ちません。
ステップ 5. 誰が戻せるかを確かめる
snapshots.revert には管理者のロールが必要で、トークンのプリセットでは full にしか含まれません。SCM agent や SCM release のトークンを持つエージェントは呼べません。トランクが保護されたワークスペースでは、コードツリーやライブラリエントリを書く戻し、またはページも保護されている場合のページやアトムを書く戻しは、何かを書く前に拒否されます。workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane
ステップ 6. カットへ戻す
cut と、チェンジセットのメッセージである 1 から 4,096 文字の intent を付けて snapshots.revert を呼びます。"Revert is forward only: nothing is removed or rewritten."(戻しは前進のみ。何も削除も書き換えもされない)。内容がカットと異なるエンティティはそれぞれ、カットの内容を持つ新しいリビジョンを 1 つ受け取り、すべてが封印済みのチェンジセット 1 つにまとまります。復元されたページやアトムのリビジョンには Restored from cut <cut> (R#<revision>) というコメントが付きます。カットがパスとタイトルを記録していれば、名前を変えたページは元のパスとタイトルに戻り、離れたパスは引き続きそのページへリダイレクトします。その後、戻し元のカットを示す印の付いた新しいスナップショットがカットされます。
ステップ 7. 答えを読む
答えは次のフィールドを持つ新しいスナップショットです。
snapshot, cut, changeset_id, restored, unchanged, extraneous, collisionsrestored の各行は次のとおりです。
kind, entity_id, from_revision_id, new_revision_idunchanged は件数です。collisions は、元のパスを今は別の生きたページやアトムが使っているエンティティを並べます。そこでは "the body and metadata alone are restored, and nothing moves."(本文とメタデータだけが復元され、何も移動しない)。何も書かない拒否が 2 つあります。パージされたリビジョンやゴミ箱にあるエンティティを指すカット(拒否は先に復元するよう伝えます)と、ワークスペースがすでに一致しているカットで、後者には Every entity already holds what cut <cut> names; nothing changes. と答えます。
ステップ 8. 戻しても残るものに対処する
"Entities created after the cut are reported as extraneous and left as they are."(カットの後に作られたエンティティは extraneous として報告され、そのまま残される)。夜のエージェントが作ったページは戻した後も残っているので、それぞれ残すかどうかを決めてください。戻しもほかと同じチェンジセットなので、夜の作業とその取り消しはどちらも履歴で読め、戻しをまたぐ範囲の cuts.notes は両方を示します。ワークスペース全体ではなく 1 つのランディングだけなら、changesets.revert が 1 つのチェンジセットを取り消します。こちらは lane を取るので、保護されたトランクではレーンに保存してそこからランディングできます。
カットでリリースに名前を付けて公開するには、ガイドCarbon Forge でリリースを切り、GitHub にプッシュするを読んでください。
ドキュメントが答えていないこと
- 保護されたトランクをカットへ戻す方法。
snapshots.revertはlaneを取らず、ドキュメントはカット全体の戻しをレーン経由で行う手順を示していません。 extraneousのエンティティを一度に消す方法。ドキュメントは報告するだけで、そこで止まっています。- 戻しの答えの
cutに何が入るか。ドキュメントの説明では新しいスナップショットは独自の名前なしでカットされ、この呼び出しでのフィールドの意味は説明されていません。 - 実例。カタログはすべての引数を示していますが、この 7 つのツールの呼び出しや答えの例はありません。