EcholotGitとチーム
Gitでワークスペースを共有し、変更を小さな差分としてレビューし、シークレットや個人の設定をリポジトリに入れない方法を説明します。
ワークスペースは、Gitで管理することを前提に書かれたテキストファイルのフォルダです。リクエスト1件につき1ファイル、同じ内容なら同じバイト列で、中に非公開のものは入りません。コミットしてプッシュすれば、チームは同じリクエストで作業でき、それぞれが自分の認証情報を使います。
差分に向いたファイル
- リクエスト1件につき1ファイル。 リクエストを変更すると、変更されるのは1ファイルです。リクエストを追加すると、追加されるのは1ファイルです。
- 決定的。 Echolotは同じ内容を毎回同じ方法で書き込みます。同じキーが同じ順序になるので、変更なしで保存しても何も変わらず、差分には変更した部分だけが表示されます。
- 読みやすい。 リクエストはTOMLです。ボディはリクエストの隣に独立したファイル（
create-order.body.json）として置かれ、GraphQLクエリは.graphqlになります。そのため、エスケープされた文字列ではなく、JSONやGraphQLとして差分が取れます。 - 順序はフォルダのファイルに。 フォルダ内の項目の順序は、ファイル名の一部ではなく、
_folder.tomlのリストです。並べ替えても変更されるのは1行です。 - あなたのコメントは残ります。 ファイルに手書きしたコメント（
# why this header）は、Echolotが保存するときに保持されます。先頭のコメントブロック、キーやテーブルの上のコメント、値の後ろのコメントが対象です。すでに存在しないキーに付いたコメントは削除されます。
リクエストの名前を変更すると、そのファイルと、隣にあるボディやスクリプトのファイルの名前も変わります。環境の名前を変更しても、ファイル名は変わりません。
コミットするもの
ワークスペースフォルダ全体をコミットします。中には無視すべきものはありません。Echolotは、シークレットの値、履歴、レスポンスボディ、個人の設定を、決して書き込みません。
| ワークスペース内（共有される） | あなたのMacのみ（共有されない） |
|---|---|
| リクエスト、フォルダ、その順序、ドキュメント、認証、スクリプト | シークレットの値（キーチェーン内） |
| 変数と、そのシークレットでない値 | グローバル変数 |
| 環境と、どれが保護されているか | どの環境がアクティブか |
| MCPサーバ、仕様、モック、フロー | 履歴とレスポンスボディ |
| ワークスペースのエージェントのルール、プロキシ、証明書 | ペインのレイアウトとそのほかのアプリ設定 |
| 共有することを選んだアシスタントの会話 | 信頼したスクリプトとエージェントのルール |
workspace.tomlにあるワークスペースIDは、そのままにしておいてください。Echolotは、これを使って各自のシークレットの値を見つけます。
シークレット変数を通さず、フィールドに直接入力した値は、そのままファイルに書き込まれます。そのような値が入っている認証やプロキシのフィールドには、Echolotがその下に警告（ワークスペースのファイルにプレーンテキストとして保存されます。）を表示します。コミットする前にキーチェーンに移動をクリックしてください。シークレットを参照してください。
共有を始める
- ワークスペースをGitリポジトリに置きます。
.echolotフォルダにリポジトリを作るか、プロジェクトのリポジトリ内にフォルダとしてワークスペースを置きます。workspace.tomlを含むフォルダなら、Echolotで開けます。 - コミットしてプッシュします。
- チームメンバーはリポジトリをクローンし、ファイル › ワークスペースを開く…でワークスペースを開きます。
- チームメンバーは、それぞれ自分のMacでシークレットの値を1回設定します。環境ページには、それぞれにこのMacでは未設定と表示されます。
コマンドラインツールは同じファイルを読むので、CIではコミットしたリクエストが実行されます。CIでテストするを参照してください。
Git、エディタ、エージェントからの変更
Echolotはワークスペースフォルダを監視します。Echolotの外でファイルが変更されると（git pull、ブランチの切り替え、エディタ、エージェントなど）、ウインドウがそれを再読み込みします。サイドバー、開いているリクエスト、環境、仕様、モック、フローがすぐに追従します。
未保存の編集がない、開いているリクエストは、確認なしで新しいバージョンに切り替わります。
リクエストのタブに未保存の編集がある場合、Echolotはどちらかを選びません。リクエストの上にバーが表示されます。このリクエストはディスク上で変更されました、「ここに未保存の編集内容があるあいだに、ほかのアプリまたはGitがファイルを変更しました。」
- 自分の変更を保持は、タブ内の編集を残し、ファイルに上書きします。
- ファイルの内容を使用は、タブ内の編集を破棄し、ディスクからファイルを読み込みます。
選ぶまで、Echolotはそのリクエストを保存しないので、ディスク上の変更はそのままです。
競合中にタブを閉じる
選ぶ前にタブを閉じると、Echolotは確認します。未保存の編集内容があるあいだに「Create order」がディスク上で変更されました。「タブを閉じると、残せるのは1つのバージョンだけです。」自分の変更を保持、ファイルの内容を使用、またはタブを開いたままにするキャンセルを選びます。競合が残っている間にウインドウを閉じたり終了したりすると、編集を保存できないことが伝えられ、破棄する前に確認されます。そのため、どちらのバージョンも、あなたの判断なしに失われることはありません。
マージの競合
Gitのマージの競合は、ほかのテキストファイルと同じように、エディタまたはGitのツールで解決してください。競合マーカーが残っているファイルは、有効なTOMLではありません。ファイルが読めない間、開いているウインドウは以前に読み込んだ内容を保持します。ワークスペースを開こうとすると失敗し、ようこそウインドウに、ファイルを示すメッセージ「…を読み込めませんでした。」が表示されます。ファイルを修正すると、ワークスペースが再び読み込まれます。
Gitからのスクリプトとエージェントのルール
スクリプトはリクエストを送信し、ワークスペースの変数を読み取れるので、Echolotは、あなたがこのMacで信頼したスクリプトだけを実行します。Echolotで書いたスクリプトは信頼されています。Git、読み込み、別のエディタから届いたスクリプト、またはそこでコードが変更されたスクリプトには、読んでスクリプトを信頼をクリックするまで、これらのスクリプトはEcholotの外部から来たものですと表示されます。スクリプトとテストを参照してください。
ワークスペースのエージェントのルールも同様です。ファイルのルールのうち、エージェントにできることを厳しくするものはすぐに適用されます。緩めるものは、そのバージョンをこのMacで信頼した後にのみ有効になります。エージェントを参照してください。
Gitなしで共有する
Gitを使わない人にワークスペースを渡すには、Echolotワークスペースとして書き出します。コピーには新しいIDが付くので、シークレットはあなたのものとは別になり、シークレットの値が書き込まれることはありません。
Finderでワークスペースフォルダをコピーすると、IDは同じままです。同じMac上では、コピーと元のワークスペースが、キーチェーンから同じシークレットの値を読み取ります。