Clay workflows — バージョン履歴: スナップショット（保存時点の記録）を表示したり、何が変わったかを確認したり、以前の状態に戻したり編集を取り消したりできます。 次のような場合に使用: ユーザーがスナップショットについて言及したときや、編集の取り消しをリクエストしたとき。
Clay workflows — version history: view snapshots, see what changed, and restore or undo a previous state. Use when the user mentions snapshots or asks to undo an edit.
スナップショットは、ワークフロー全体（ノード、エッジ、プロンプト、スクリプト、ツール、配置）を特定時点で丸ごと記録した、変更不可の静止画像です。
自動作成: グラフを変更するノード編集（clay workflows nodes のcreate|update|delete、またはSculptor のedit_node）が行われたとき、および実行開始時に自動で作成されます。data[0] は作成日時（createdAt）が最新のものですが、現在のグラフとは限りません。トリガー（実行の開始条件）を既存ノードに割り当てたり共有したりしてもスナップショットは記録されません。その場合は、トリガーを削除して元に戻してください（復元ではなく）。設定のみを変更するトリガーの更新・削除もスナップショットは記録されません。設定を修正するか再作成し、トリガー自体は削除しないでください。graph format（グラフの整形）は、検証エラーがない場合に2つのスナップショットを記録します（整形前と整形後）。詳細は「取り消し」を参照してください。
復元しても一覧は並び替わらない: snapshots restore でドラフトは上書きされますが、スナップショット一覧は作成されたり並べ替わったりしません。ハッシュ値が同じスナップショットが既に存在する場合は、作成日時（createdAt）を更新せずに既存の行を再利用します。復元後、data[0] が現在のグラフではない、より古い履歴エントリになる可能性があります。そのため、次の編集での data[1] は、復元前のグラフではなく古い状態を指す場合があります。data[1] を取り消しの対象と見なす前に、最新スナップショットと現在のグラフを比較するか、一覧から現在のグラフに合致する行を確認してください。
ハッシュで内容を管理: 各スナップショットは、その内容をSHA-256 ハッシュ化して管理されます。まったく同じワークフロー状態なら、同じハッシュに統約されます。
変更不可: スナップショットが一度作成されると、そのグラフ内容は二度と変わりません。
実行の独立性: 実行は特定のスナップショットに紐付けられます。その後ワークフローを編集しても、実行中の処理には影響しません。
同じスナップショット表に、2つの役割が共存しています:
| 役割 | 発生するタイミング | 用途 |
|---|---|---|
| ドラフト履歴 | 編集時、実行開始時に自動作成 | 取り消し機能と実行に紐付けるためのログ。リリース番号なし |
| 公開版 | ユーザーがエディタで「公開」ボタンをクリック | 番号付きリリース（version、オプションでname）。これが実際に動く最新のワークフロー |
公開版を作成すると、現在のドラフトのスナップショットが番号付きリリースとしてマークされます。別の保存場所は作られません。ドラフトと公開版の詳細は、ワークフロー・エントリーポイント・スキルの publishing.md を参照してください。
このスキルは取り消し・履歴機能向け（list / get / restore）です。公開処理は別のコマンド（clay workflows publish）であり、公開版だけを一覧表示するCLI はありません。
clay workflows snapshots list の出力は id、hash、createdAt、nodeCount、edgeCount のみです。version / name / どのスナップショットが公開中かは表示されません。一覧を「リリース選択ツール」ではなく「新しい順の履歴」として扱ってください。復元後は直線的な取り消しスタックではなくなります。
clay がPATH に含まれていない場合、または clay whoami が認証に失敗する場合は、setup スキルを実行してください。
clay workflows snapshots list <workflowId>
{ data: [...] } を返します（新しい順）。各エントリに id、hash、createdAt、nodeCount/edgeCount が含まれます。data[0] は作成日時が最新のスナップショットですが、現在のグラフとは限りません（復元の項を参照）。
clay workflows snapshots get <workflowId> <snapshotId>
clay workflows snapshots get <workflowId> <snapshotId> --node-id <nodeId>
記録されたグラフ全体を返します。nodes（型、プロンプト、コード、ツール付き）と edges が含まれます。--node-id を指定すると、nodes を1つだけに絞ります（エッジはそのまま残ります）。
内蔵の比較ツールはありません。両方を取得して jq で比較してください。ただし、以下は生の diff 出力であり、ユーザーに見せるものではなく基礎メカニズムです:
clay workflows snapshots get <workflowId> <oldSnapshotId> | jq '.nodes' > old.json
clay workflows snapshots get <workflowId> <newSnapshotId> | jq '.nodes' > new.json
diff <(jq -S . old.json) <(jq -S . new.json)
生の diff 出力を貼り付けるのではなく、差分を日本語で分かりやすく説明してください。例：「ノード『メール検索』のプロンプトが変更されました。エッジ『リサーチ→下書き』が削除されました。新しいノード『リード評価』が追加されました」。グラフ構造を変える変更（ノード・エッジの追加・削除・再配線）の場合は、変更前後のMermaid 図（図解）をレンダリングして、テキストだけでなく視覚的に理解できるようにしてください（ワークフロー・エントリーポイント・スキルの presenting.md を参照）。
内蔵の図表コマンドは、常にワークフロー現在のグラフをレンダリングします:
clay workflows diagram <workflowId> | jq -r '.diagram' # 常に現在のグラフ
任意のスナップショットIDの図表コマンドはないため、そのスナップショットの nodes/edges から小さなノード・エッジ一覧を手で作成してください。図表に「変更前」「変更後」というラベルを付けてください。「変更前」は変更元の状態、「変更後」は変更先の状態です。上記コマンドは、現在のグラフがどちらかの側になるときに使います。復元をプレビューする場合（下の「スナップショットに復元」を参照）、復元は現在のグラフをスナップショットで上書きするため、現在のグラフが「変更前」、復元対象のスナップショットが「変更後」です。
clay workflows snapshots restore <workflowId> <snapshotId>
ワークフロー全体を、スナップショットが記録した状態に完全に戻します。現在のすべてのノード、エッジ、プロンプト、スクリプト、ツールが置き換わります。復元は破壊的で、現在のグラフのスナップショットは事前には記録されず、復元後も一覧の先頭に移動しません。data[0] は依然として後の履歴エントリになり得ます。復元前の状態を取り戻すには、その後の編集または実行開始が自動でそれを記録しているスナップショットが必要です（スナップショットは各グラフ変更編集の後と実行開始時に自動作成）。現在のグラフに記録されていない変更があり、それを戻したい場合は、まず snapshots list を実行して、data[0] を盲目的に選ぶのではなく、現在のグラフに合致するスナップショットを確認してください。
復元 ≠ 公開。 復元はドラフトのみを上書きします。どのスナップショットが公開中かは変わらず、編集を取り消しても公開中のオートメーションはロールバックされません。ユーザーが公開中のトリガーを復元したドラフトと同期させたい場合は、エディタで再度公開する必要があります（ワークフロー・エントリーポイント・スキルの publishing.md を参照）。
復元前に、ユーザーが何が変わるかを確認できるようにしてください。 現在のグラフと復元対象のスナップショットの違いを日本語で分かりやすく説明し、構造が異なる場合は変更前後の図表を表示してください（「2つのスナップショットを比較」を参照）。ユーザーが内容を確認してから復元が現在の状態を破壊的に上書きするようにしてください。復元後は、復元されたグラフをレンダリングして、結果をユーザーに見せてください。
すべてのグラフ変更編集は、完了後にスナップショットをスケジュールします（ファイア・アンド・フォーゲット方式のため、新しい行は遅延する可能性があります）。data[0] が現在のグラフか、data[1] が復元前のグラフであると仮定しないでください。
トリガー作成は、新しいキャンバス・ノードを割り当てるときだけスナップショットを記録します。既存の workflowNodeId を共有する場合はスナップショット・ハッシュに含まれません。その場合は復元ではなく clay workflows triggers delete で取り消してください（Sculptor では「削除」を表示）。設定のみを変更するトリガーの更新・削除もスナップショットには記録されません。設定を修正または再作成してください。トリガーは削除しないでください。
graph format は検証エラーがない場合、2段階です。整形前スナップショットは待機してから、整形後スナップショットがスケジュールされます。整形前のID（ノード・エッジは同じだが配置が異なる）に復元してください。検証エラーがあった場合、整形前スナップショットはスキップされます。.data[1] は無関係な古いスナップショットの可能性があります。それに復元しないでください。グラフに以前のスナップショットがなかった場合、整形後の行が到着するまで待ってから .data[1] を取り消し対象と見なしてください。
snapshots get と現在のグラフを比較（clay workflows graph get --mode full、Sculptor: MCP の read で mode: "full"）して、現在のグラフと作成日時が最新のものを区別してください。一覧の行が現在のグラフに合致しない場合、編集後のスナップショットはまだ送信中の可能性があります。ポーリングするか、.data[0] に復元してください（ステップ4を参照）。記録されていない現在のグラフのスナップショットを探さないでください。Bash(clay *) / Bash(jq *) のみを使用してください。シェルの for/seq/sleep ループでポーリングしないでください（それらはこのスキルのallowed-tools 外です）。
clay workflows snapshots list <workflowId> | jq -r '.data[0].id' # 最新 — 常に現在のグラフではない
clay workflows snapshots list <workflowId> | jq -r '.data[1].id' # 次の古い — 常に復元前ではない
clay workflows snapshots restore <workflowId> <snapshotId>
編集前に before_id を確認: .data[0] が現在のグラフに合致すれば、before_id は .data[0].id です。合致しなければ、一覧を歩いて合致する行を見つけます。そのIDが before_id です。合致する行がなければ、復元可能な復元前スナップショットはありません。restore にnull IDを渡さないでください。
before_id がある場合（ノード・トリガー編集）: 書き込み後、before_id に復元してください。.data[1] をプロキシとして復元しないでください。復元後、そのIDは後の履歴エントリになり得ます。
before_id がある場合（graph format 後）: before_id に復元してください。ただし、そのIDが整形前の現在のグラフ
Snapshots are immutable, point-in-time captures of the entire workflow graph — nodes, edges, prompts, scripts, tools, and positions.
clay workflows nodes create|update|delete; Sculptor: edit_node) and when a
run starts. data[0] is newest-by-createdAt, not necessarily the current
graph. Sharing/binding a trigger onto an existing node does not snapshot —
undo that create by deleting the trigger, not restore. Settings-only trigger
update/delete also do not snapshot — revert or recreate the settings; do not
delete the trigger and do not restore. graph format takes two snapshots when
validation has no errors (pre-layout, then post-layout); details under Undo.snapshots restore rewrites the draft but does not create or reorder snapshots. Duplicate hashes reuse the existing row without updating createdAt. After a restore, data[0] can be a later history entry that is not the current graph, so the next edit's data[1] is often that stale entry rather than the pre-edit graph. Compare the latest snapshot to the current graph (or find the list row that matches) before treating data[1] as the undo target.The same snapshot table holds two roles:
| Role | When | Purpose |
|---|---|---|
| Draft-history | Auto on edits / run start | Undo log and run pegging. No release number. |
| Published version | User clicks Publish in the editor | Numbered release (version, optional name). Becomes the live graph automation runs. |
Publishing marks a snapshot of the current draft as a numbered release; it does not create a separate store. See the workflows entry-point skill's publishing.md for draft vs live.
This skill is for undo/history (list / get / restore). Publishing is a separate command (clay workflows publish); there is no CLI to list only published versions.
clay workflows snapshots list projects only id, hash, createdAt, nodeCount, and edgeCount. It does not show version / name / which snapshot is live. Treat the list as newest-first history, not a release picker — after a restore it is not a linear undo stack.
If clay isn't on PATH or clay whoami fails on auth, run the setup skill.
clay workflows snapshots list <workflowId>
Returns { data: [...] }, newest first, each with id, hash, createdAt, and
nodeCount/edgeCount. So data[0] is the most recent snapshot by createdAt,
which may not be the current graph (see restore above).
clay workflows snapshots get <workflowId> <snapshotId>
clay workflows snapshots get <workflowId> <snapshotId> --node-id <nodeId>
Returns the full captured graph: nodes (with types, prompts, code, tools) and
edges. --node-id narrows nodes to a single node (edges are left intact).
There is no built-in diff. Fetch both and compare with jq — but this raw diff
is the underlying mechanism, not the thing you show the user:
clay workflows snapshots get <workflowId> <oldSnapshotId> | jq '.nodes' > old.json
clay workflows snapshots get <workflowId> <newSnapshotId> | jq '.nodes' > new.json
diff <(jq -S . old.json) <(jq -S . new.json)
Translate the diff into a plain-language change summary rather than pasting the
raw diff output — e.g. "Node Find Email's prompt changed; the edge Research →
Draft was removed; a new Score Lead agent node was added." When the change alters
the graph's structure (nodes or edges added/removed/rewired), render before/after
Mermaid diagrams so the user can see it, not just read it (see the workflows
entry-point skill's presenting.md).
The only built-in diagram command always renders the workflow's current graph:
clay workflows diagram <workflowId> | jq -r '.diagram' # always the current graph
There's no diagram command for an arbitrary snapshot id, so hand-write a small
node/edge list from that snapshot's nodes/edges for its side. Label the diagrams
by the direction of the change: "before" is the state you're changing from, "after"
is the state you're ending up with — and use the command above for whichever side is
the current graph. When previewing a restore (see "Restore to a snapshot" below), the
restore overwrites the current graph with the snapshot, so the current graph is the
"before" and the snapshot you're restoring to is the "after".
clay workflows snapshots restore <workflowId> <snapshotId>
Restores the workflow to the exact state captured in the snapshot. This replaces
all current nodes, edges, prompts, scripts, and tools. Restore is destructive and
does NOT snapshot the current graph first, and does not move the restored
snapshot to the top of list — data[0] can still be a later history entry.
The pre-restore state is recoverable only if a later edit or run already
triggered a fresh snapshot capturing it (snapshots are taken automatically
after each graph-mutating edit and at run start). If the current graph has
unsnapshotted changes you might want back, run snapshots list first and note
the snapshot that matches the current graph, not blindly data[0].
Restore ≠ publish. Restore rewrites the draft only. It does not change which
snapshot is live, and undoing an edit does not roll back live automation. If the
user wants live triggers to match the restored draft, they must Publish again
in the editor (see the workflows entry-point skill's publishing.md).
Before restoring, show the user what will change. Summarize the difference between the current graph and the target snapshot in plain language, and — when the structure differs — show before/after diagrams (see "Diff two snapshots" above), so the user can confirm the revert before it destructively overwrites the current state. After restoring, render the restored graph so they can see the result.
Every graph-mutating write schedules a snapshot after it completes — fire-and-forget,
so the new row may lag. Do not assume data[0] is the current graph or that data[1] is
the pre-edit graph.
Trigger create only snapshots when it allocates a new canvas node. Sharing an existing
workflowNodeId is not in the snapshot hash — undo that create with
clay workflows triggers delete (Sculptor: surface delete), not restore. Settings-only
trigger update/delete also are not snapshotted: revert or recreate the settings; do not
delete the trigger and do not restore.
graph format is two steps when validation has no errors: a pre-layout snapshot is
awaited, then a post-layout snapshot is scheduled. Restore the pre-layout id (same
nodes/edges, different positions). If validation had errors, the pre-layout snapshot is
skipped — .data[1] may be an older unrelated snapshot; do not restore it. If the graph
had no prior snapshot, wait until the post-layout row has landed before treating
.data[1] as the undo target.
Compare snapshots get vs the current graph (clay workflows graph get --mode full;
Sculptor: MCP read with mode: "full") to tell current from newest-by-createdAt. If no
row matches, the post-edit snapshot may still be in flight — poll or restore .data[0]
(step 4); do not search for a snapshot of the unsnapshotted current graph. Only use
Bash(clay *) / Bash(jq *) — poll by repeating list, not a shell for/seq/sleep
loop (those are outside this skill's allowed-tools).
clay workflows snapshots list <workflowId> | jq -r '.data[0].id' # newest — not always current
clay workflows snapshots list <workflowId> | jq -r '.data[1].id' # next older — not always pre-edit
clay workflows snapshots restore <workflowId> <snapshotId>
before_id before the edit: if .data[0] matches the current graph, before_id
is .data[0].id. If not, walk the list until a row matches — that id is before_id. If
none match, there is no restorable pre-edit snapshot; do not pass a null id to restore.before_id (node/trigger edits): after the write, restore before_id. Do not
restore .data[1] as a proxy — after a restore that id can be a later history entry.before_id (after graph format): restore before_id only if that id
matched the current graph before format. If you had no matching snapshot before
format, call list until .data[0] matches the current (post-layout) graph, then
restore .data[1].id only if it is the pre-layout graph (same nodes/edges, different
positions). If validation had errors, that pre-layout row was never created — .data[1]
can be an older unrelated snapshot; if so (or if .data[1] is missing), report no
restorable pre-layout snapshot rather than rolling back more than the layout.before_id (late undo): compare .data[0] to the current graph. If they
match, restore .data[1].id only if it exists — and only when you know .data[0] was
already the current snapshot before the last edit (usual linear history). If .data[1] is
missing, report no restorable pre-edit state. If they do not match, walk the list for
a row that matches the current graph. If an older row matches (post-restore), restore
that id — not .data[1], which can roll the workflow forward. If no row matches,
the post-edit snapshot has not landed (fire-and-forget lag): poll list a few times. If
.data[0] then matches, follow the match case above. If still none, restore .data[0]
(still the pre-edit graph in linear history). Do not look for a snapshot of the current
unsnapshotted graph — it cannot exist until that async row lands. Do not pass a null
snapshot id to restore.To undo multiple edits, pick an older snapshot id from the list instead.
Remember: this only rolls back the draft. Live automation (if already published) keeps running the previously published version until the user publishes again.
List snapshots, then diff two of them with the jq recipe above.
Since runs are pegged to snapshots, inspect the exact workflow state a run used by
looking up the run's snapshot id and passing it to snapshots get.
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。