コンテンツにスキップ

ライブ changeset(設計)

状態: 採用済みの設計。実装済み(手順 1 から 3、およびローカルの MCP 起動役)。git ブランチ上の changeset 以降は git のブランチの上で動きます。

目的

アシスタントが提案を作っていく様子を、その場で見られ、止められ、前の任意の時点に戻せるようにします。その際、changeset が提供しているものは手放しません。 人が採用するまで実際の設計は変わらず、チェックは元の設計と提案を比べ、採用・破棄の時点で証拠が保存されます。

そのため、changeset はレビューの単位のままです。変わるのは、changeset が「最後に届く結果」ではなく「目の前で育っていく作業ブランチ」になることです。 アシスタントが作業コピーを編集している間、UI はその作業コピーを表示します。git ブランチ上の changeset からは文字どおりそうなりました。 作業コピーはブランチ undine/<project>/<id> の git worktree で、書き込み者のリースが終わるとブランチにコミットされます。以下はその作業コピーについての話です。

実際の設計をその場で(Undo 付きで)編集する方式は採用しませんでした。変更前後のチェックと証拠が失われ、実際の設計に対する人の編集とアシスタントの編集が混ざり、 MCP 経由の外部エージェントには同じ規則を適用できないからです。

決めたこと

問い 決定
アシスタントの作業中に、人が提案を編集できるか できない。changeset ごとに書き込み者は同時に 1 人で、サーバーが強制する(下記)
「戻す」とは何か 選んだチェックポイントの設計状態を復元し、新しい記録として残す。Undo の繰り返しではない
どのチェックポイントに戻せるか changeset のタイムライン上の、最初から今(最後)までの任意の時点。途中の 1 項目だけを戻すことは(まだ)しない
レビューは自動で開くか 開く。依頼を送った画面で、最初の変更が確定したときに一度だけ

1. 順序と識別子(PR 1)

操作ログはライブラリごとにあります(history/<lib>.jsonl、seq はファイルごと)。changeset は複数のライブラリに触れることがあるので、 そのタイムラインにはライブラリをまたいだ 1 つの順序が必要です。作業コピーは changeset のブランチの worktree なので、そのログは起点でのプロジェクトの ログから始まります。changeset 自身の記録は、ライブラリごとに起点での最後の seq(記録の base_seq。ログの 床)より後のものです。 changeset の作業コピーに書かれる記録には、次の 3 つのフィールド(と、その id を示す changeset)が加わります:

フィールド 意味
gseq changeset の中での位置。すべてのライブラリを通して数える(1、2、3 …)。記録を追加するときに割り当てる
opid 書き込み者から見た 1 つの操作: アシスタントのツール呼び出し 1 回、人の HTTP リクエスト 1 回。3 つのビューを作る create_cell は、同じ opid の記録を 3 つ書く。チェックポイントは操作と操作の間にだけ置き、操作の途中には置かない
turn 操作が属するアシスタントのターン(会話の中の 1 回の依頼)。人の編集なら null

UI は gseq を追います。gseq が新しい記録が確定すると図面を更新するので、失敗したツール呼び出しでも、確定した変更は表示されます。 番号付け、タイムライン、復元、レビューの操作、Undo と Redo は、床より上の記録だけを見ます。起点より前のプロジェクトの履歴や、以前に採用した changeset の記録(それ自身の gseq を持つ)は、この changeset のものではありません。起点にあるレイアウトのジャーナル(プロジェクトの保存していない レイアウトの編集)は作業コピーでは再生せず、作業コピーはファイルから始まります。

2. changeset ごとに書き込み者は 1 人(PR 1)

changeset には書き込みのリース(貸し出し)が最大 1 つあります: {owner, kind: turn | mcp, since, expires?, stop_requested}。リースが保持されている間、 作業コピーへのそれ以外の人による設計の書き込みはすべて拒否されます(409): 手動の編集、Undo / Redo、チェックポイントの復元、そして changeset の採用・破棄です。 チェック(DRC / LVS のジョブ)は設計の書き込みではないので実行できます。

確認は、すべての書き込みが通る場所で行います。回路図エディタとレイアウトのデータベースは、何かを変える前に作業コピーの操作ログのフックに問い合わせます。 HTTP のルート、アプリ内のアシスタント、MCP のいずれもそこを通るので、別のタブや外部のクライアントが迂回することはできません。

  • アプリ内のアシスタント: ターンは、開いている changeset で始まるとき、または changeset を開いたときにリースを取り、終わったとき(完了、停止、失敗、中断)に返します。
  • MCP クライアント にはターンという概念がありません。セッションは changeset に最初に書き込んだときにリースを取り、書き込んでいる間保持します。 書き込みが 120 秒途絶えると切れます。MCP のセッションを止めると、そのリースは取り消され、そのセッションからのそれ以降の書き込みは拒否されます。
  • 1 つの MCP セッションの複数のエージェント(1 つの mcp-stdio の中継を使うクライアントのサブエージェント)は、呼び出しごとに エージェント名(agent)を渡せば、それぞれが別の書き手になります。それぞれが自分の changeset とリースを持ち(所有者 mcp:<session>:<agent>、ラベル <client>/<agent>、actor agent:<client>/<agent>)、あるエージェントが他のエージェントの持つ changeset に書き込むことはなく、止めるとそのエージェントだけが止まります。セッションが終わると、そのすべてのエージェントのリースが 解放されます。名前のない呼び出しは、セッション自身の書き手(mcp:<session>)で、すべてが 1 つの changeset を共有します。
  • 名前付きのシェルのセッションはエージェント。 undine call --session NAME は、agent を渡さない呼び出しすべてに agent=NAME を付けます。これでシェルのセッションどうしも、サブエージェントと同じように区別されます(所有者 mcp:<session>:NAME、actor agent:undine-cli/NAME)。既定のセッション(--session なし)は名前なしのままです。 この版より前に名前付きのセッションで開いた changeset は、そのセッションの名前なしの書き手のものです。最初の呼び出しが、 その名前をセッション自身のものと示し(_meta: {"undine/own_agent": true})、サーバーはその changeset とリースを 名前の側に渡すので、エージェントはそのまま続けられます。止められた書き手は止まったままです。これは一度だけです。 クライアントはその後、セッションファイルでそのセッションに named の印を付けます。クライアント自身が作ったセッションには、 初めから付けます。なので、セッションの名前なしのエージェントが後で開いた changeset(agent="")は、そのエージェントのものの ままです。
  • 自分は誰か。 open_changeset と list_changesets は、呼び出し元をレビューと同じ呼び方で you に返します (undine-cli/bootsw-a (MCP session 3fa693cf))。監査ログには MCP の呼び出しごとにセッションを残します。 他のエージェントのセッションで動いている呼び出し(2 つのエージェントが 1 つの補助スクリプトを共有したときなど)は、すぐにわかります。

3. アシスタントのターンをジョブにする(PR 1)

チャットのリクエストは、アシスタントの作業が終わるまで待たされることはなくなります。ターンのジョブを作り、すぐにその ID を返します。

  • 受付: リクエスト、会話、ターン、クライアントのリクエスト ID を、まず保存します。同じクライアントのリクエスト ID を再送すると、同じターンを返します (応答が失われて POST をやり直しても、2 つ目のターンは始まりません)。
  • 進捗: ジョブはイベントを追記します: アシスタントの文章、ツール呼び出しの開始、それが確定した記録(gseq)、ツール呼び出しの終了(成功またはエラー)。 クライアントはあるインデックス以降のイベントを読むので、再読み込みしたページも続きから表示できます。
  • 状態: running → done | failed、stopping → stopped、interrupted。停止すると stopping になり、ループはモデルの呼び出しとツールの呼び出しの前ごとに それを確かめます。そのため、編集中のツール呼び出しは、その編集を終えてから止まります。すでに確定した変更は残ります。
  • サーバーの再起動: 終わっていないターンは interrupted になり、確定した変更は残し、再実行はしません。
  • アシスタントが始めたチェックはそれ自身のジョブです。ターンを止めてもチェックは止まらず、UI は両者を分けて表示します。
  • 会話には、ターンを受け付けたときに利用者のメッセージを、ターンが終わったときに応答を保存します。終わらなかったターンはその状態とともに表示し、 完了したものとしてモデルに渡し直すことはしません。

4. タイムラインとチェックポイントの復元(PR 2)

レビューには、オブジェクトごとの表示の隣にタイムラインの表示が加わります。操作を gseq の順に、ターンごとにまとめて並べ、その間に人の編集が入ります。

チェックポイント G への復元 は、作業コピーを、gseq が G で終わる操作の直後の状態に戻します:

  • 目標の状態は、今効いているものを Undo するのではなく、ログから計算します。G より後の記録を新しいものから順にたどり、それぞれを反転します。 Undo / Redo の記録も含みます(Undo の反転は、それが取り消したものを再び適用することです)。これで「追加 → チェックポイント → Undo」の場合も扱えます。 Undo を積み重ねるだけでは、これは戻せません。
  • 触るすべてのライブラリとセルのビューに、全か無かで適用します。どこかが失敗したら、適用済みの部分を戻し、何も記録しません。
  • to: G を持つ restore の記録を書きます。触ったセルのビューごとに適用した効果を持つものを 1 つ、対象のライブラリごとに目印を 1 つ(view: null)です。 changeset の操作の一覧、Undo の履歴、ブランチのコミットはいずれもこれに従います。ログの差し引きは、復元より前のすべての記録から、この changeset の G より後の記録を除いて計算し直します(同じログにある以前の changeset の記録は残ります)。そのため、レビューには実際に効いているものが正確に表示され、 ブランチの次のコミットには復元したファイルが入ります。
  • G より後に作られたセルは削除します。回路図やシンボルのファイル(v)やレイアウトのセル(c)は、作ったときのままで、残るものから参照されていない場合に限り削除し、 そうでなければ理由を付けて復元を拒否します(これは作業コピーについての規則です。採用済みの changeset を取り消す場合は、追加したファイルを残します)。
  • チェックの結果は削除しません。履歴として残り、入力のハッシュが一致する間だけ有効です。

アシスタントの次のターンには、復元したチェックポイント、取り消した範囲、今の設計が明示的に伝えられます。そのため、会話の前の方にある「ota を作った」を 今の状態と取り違えません。前回のターン以降の変更の報告は、今効いている操作ではなく、ログの記録(Undo、Redo、復元を含む)から作ります。

5. 開くことと追従(PR 3)

  • 依頼を送った画面は、最初の変更が確定したときに、一度だけレビューを開きます。その changeset を表示しているほかの画面には、アシスタントが作業中であることを表示します。
  • 人が閉じたレビューは、その後の変更で開き直しません。
  • 図面は、アシスタントが編集しているセルに追従します。別のセルを選んだり、タイムラインの前の時点を見たりすると追従を一時停止し、「最新に戻る」で再開します。 「追従を止める」と「アシスタントを止める」は別の操作です。
  • 再読み込みするのは変わったセルだけで、位置と倍率は保ちます。

6. 1 歩の操作と再送(batch、request_id)

  • 1 歩。 batch は、複数のツール呼び出しを 1 つの操作(1 つの opid)として、全部か無しかで実行します。
  • Changesets.batch は作業コピー(すべてのライブラリの最上位のフォルダ、history、project.json、undine.lock)と changeset の記録を退避します。 退避先は worktree の隣(.changesets/<project>/<id>/.batch-*)で、worktree の中には置きません。
  • 操作が失敗したとき、また試し実行のときは必ず、退避したものを書き戻します。
  • 復元が失敗したときに使うのと同じ、退避と書き戻しの仕組みです。
  • 番号は繰り返さない。 記録を書き戻すと、gseq が、追従中の画面がすでに見た番号より下から振り直されてしまいます。 そこで、これまでに振った最大の番号を worktree の隣の .changesets/<project>/<id>/gseq.floor に残し(ブランチにコミットされることも、 プロジェクトにマージされることもありません)、次の記録はそれより先の番号にします。
  • 実行中の歩の記録は、activity のエンドポイントから隠します(srv.batching)。残した歩はすぐに見え、書き戻した歩は一度も見えません。
  • 要求 ID。 request_id 付きの書き込みは、プロジェクトごとに高々 1 回だけ実行します。成功した結果を changesets/requests.jsonl(直近 1000 件)に残し、同じ ID には同じ結果を返します。
  • 結果はそれぞれ changesets/requests/ の別のファイルに置きます。クライアントが結果を丸ごと受け取っても(netlist を読む batch など)、 書き込みのたびに探す一覧は小さいままです。100000 文字を超える結果は、長い結果と同じように 中で短くして残し、そう書き添えます。
  • 同じ ID で引数が違う呼び出しは拒みます。失敗した呼び出しは何も変えていないので残しません。最初の呼び出しの実行中に届いた再送は、その完了を待ちます。
  • これで「自分の呼び出しは通ったか」に常に答えがあります。GUI ツールへの橋渡しは、タイムアウトした要求が実行されたかを知る手段がないため、ここを解決できません。

7. 他の changeset を読んで確かめる

検証役(設計者の作業を確かめるエージェント)は、その changeset の作業コピーでチェックを実行しますが、書き手になってはいけません。 open_changeset id=... で開くと、それが検証役の changeset になり、最初の書き込みでリースを取り、検証役のジョブがセッションの その changeset の記録に入ってしまいます。

  • 読み取りとチェックのツールの changeset。 get_layout_info、get_device_geometry、query_shapes、render_layout、 get_drc_report、get_lvs_report、get_netlist、get_intent、run_checks、check_specs、sweep、run_simulation、 extract_parasitics、get_parasitics、wait_for、plot_waveform、sample_waveform、cancel_job とその他の読み取りは changeset: cs-... を受け付けます。呼び出しは、呼び出し元の文脈の写しで、changeset をそれにし、読み取り中の印 (ToolCtx.reading)を付けて実行します。呼び出し元自身の文脈、開いている changeset、セッションのその記録には触れません。 答えは読んだ changeset を示します。JSON の答えは先頭に changeset、テキストの答えは先頭に changeset: cs-... の行が 付きます。changeset は、呼び出し元自身の changeset でも、そのリースを持っていなければ読み取りになります。チェックする changeset を以前に開いた(open_changeset id=...)検証役も読み手のままで、書き手が書いている間に拒否されず、書き手の リースが切れたときにリースを取る(書き手の作業を自分の名前でコミットする)こともありません。答えが次に呼ぶよう示すもの (wait_for、get_parasitics、run_simulation job=)には changeset が付き、その changeset の外で探したジョブは、 changeset を渡すよう答えます。batch は changeset を持つ操作を拒否します(batch は呼び出し元自身の changeset で動きます)。
  • リースなし。 読み取りの呼び出しはリースを取りも延長もせず、作業コピーに書き込む経路(need_changeset)は拒否します。 changeset を渡した書き込みのツールは、実行前に拒否します。書き手は検証中も書き続けられ、検証役の行いが書き手の編集と取り違えられることはありません。
  • 持ち主と同じく記録する。 run_checks は、書き手が実行したときと同じように行を changeset に記録し(verify)、 抽出とシミュレーションはその作業コピーの runs/ で実行します。書き手の get_parasitics、check_specs (extracted)、 レビューはそこで見つけます。読み手はチェックの前に作業コピーをコミットしません(書き手自身の run_checks かリースの終わりが コミットします)。各チェックは、実行したレイアウトと回路図(レイアウトのロックの下で、メモリから取ったハッシュ)を記録するので、 その後の編集で行は「古い」になり、間違いにはなりません。書き手が一度も保存していないレイアウトは、メモリにあるとおりにチェックします。
  • ジョブ。 どのジョブも、始めた者を記録します(owner、読み手なら reader: true も。live.started_by)。 シミュレーション、DRC、LVS、抽出、RTL シミュレーション、LibreLane の実行、シンボルのチェックのすべてです。読み手は自分が 始めたジョブを止められ(cancel_job changeset=... が止めるのは、そこで呼び出し元が始めたものだけ)、古いサーバーからの 最初の再起動でも、読み手のシミュレーションを読み手の changeset とは見なしません(Sessions._seed)。
  • ジョブ ID は秒までの時刻と 16 進 4 桁です(20261104-133330-00b7)。先頭の 3 桁はそのプロセスでのその秒の ID を 数えるので、同じ秒の ID も作った順に並びます(セルの最新の実行は最後の ID です)。最後の 1 桁は乱数です。1 つのプロセスは 同じ ID を二度出さず(1 秒に 4096 を超えると接尾辞は乱数)、実行ディレクトリは排他的に作り、あれば別の ID にします。 1 秒に 60 のチェックを始めても重なりません。

手順

PR 内容
1 記録への gseq / opid / turn、書き込みのリースと全書き込みでの確認、ターンのジョブ(受付、進捗、停止、中断)、進捗と停止ボタンを表示するチャットの UI
2 タイムラインの表示、チェックポイントへの復元(作成したセルを含む)、復元と Undo を次のターンに伝える
3 最初の変更でレビューを開く、変わったセルだけの更新、編集中のセルへの追従