boshu2/using-gc

GCの使用

呼び出し元が明示的にGas Cityを選択した場合にのみ使用してください。これは、正しさや完了の境界ではなく、交換可能な実行アダプタとして扱ってください。 このアダプタはAgentOpsのセマンティクスを選択したり、バインディングの判定を下したり、ファクトリーの完了を納品や検証の証明に変えたりすることはできません。

最初にファクトリーを選択する

AgentOpsは、外部ソフトウェアファクトリーランタイムとしてGas CityとAgentic Coding Flywheelの両方をサポートしています。このスキルはGas Cityにのみ使用してください。呼び出し元がFlywheelを選択した場合は、using-flywheelとそのネイティブワークフローに切り替え、Gas Cityでラップしないでください。

AgentOpsは、どちらのファクトリーにもスキルとエビデンスコントラクトを提供します。独自のGas Cityフォーミュラやロールパックは必要ありません。ワーカーを起動する前に、AgentOpsスキルをプロバイダーランタイムにインストールまたはリンクしてください。これにより、上流のメイヤー、コーディネーター、ワーカーがplan、implement、test、validate、およびその他のAgentOpsスキルを通常通り検出して選択できるようになります。

Gas City 1.4 オペレーティングモデル

Gas City 1.4はラン中心です。スーパーバイザーはダッシュボードと型付けされたページネーション付きのセッション/ランAPIを提供します。グラフを所有する各都市またはリグスコープには、独自のcore.control-dispatcherが必要です。この決定論的ワーカーがフォーミュラ制御ビーズを進めます。エージェントワーカーはルーティングされた作業を要求します。上流のgc.mayorスキルがガイド付きコーディネーターであり、gc.run-operatorがフォーミュラを起動して監視します。

通常のAgentOpsパスは以下の通りです：

1. 上流のgascityワークフローとリグロールのインポートをインストールしてピン留めします。
2. プロジェクトをリグとして追加し、そのストックメンテナーランタイムを準備し、AgentOpsスキルをそのプロバイダーセッションから見えるようにします。
3. 呼び出し元が所有するソースインテントビーズを作成し、そのIDをメイヤーに渡します。メイヤーはワークフロービーズを作成し、利用可能なアーティファクトに一致する上流のbuild-basic、継続、レビュー、または実装フォーミュラをディスパッチします。
4. ラン、セッション、ビーズ、アーティファクト、および判定の状態を読み取ります。完了はチャットやペインの散文から推測されることはありません。

最初のビルドの前に、出荷されたAgentOps CLIを使用してリグを準備および修飾します（リポジトリのチェックアウトは不要）：

ao gc prepare --city /path/to/city --rig /path/to/rig
ao gc check --city /path/to/city --rig /path/to/rig

このコマンドは、正確な公式ワークフローとロールのピンを検証し、上流の検証スクリプトとスキーマをリグの.gcランタイム内に変更せずにスナップショットし、フォーミュラチェックパスに小さなAgentOps所有のラッパーのみをインストールし、PyYAMLをインポートできる既存のPythonを選択し、AgentOpsスキルを都市とリグのCodexシンクにリンクします。スキルは、存在する場合は囲んでいるAgentOpsチェックアウトから取得され、それ以外の場合はインストールされたスキルルートから取得されます。異なるディレクトリをピン留めするには--skills-sourceを渡します。GCバイナリ、キャッシュ、フォーミュラ、ロール、または上流パックを決して変更しません。checkはネイティブの検査コマンドのみを発行し、アダプタファイルを書き込まず、そのランタイムコントラクトが欠落または逸脱している場合、モデル費用が発生する前に失敗します。

prepareはまた、実行時に存在するすべてのセッションディレクトリ（都市とリグのルート、各.gc/agents/**セッションホーム、および各リグのワークツリールート）に対してCodexトラストを事前シードするため、それらのディレクトリ内のCodexセッションがインタラクティブなトラストダイアログでブロックされることはありません。両方の永続化レイヤーが$CODEX_HOME/config.tomlにシードされます。ワークスペーストラスト（[projects."<dir>"] trust_level = "trusted"）がなければ、Codexはそのディレクトリにフックがまったくないと静かに報告します。そして、フックごとのトラスト（[hooks.state."<hooks.json>:<event>:<m>:<h>"] trusted_hash = "sha256:..."）は、パックのプロバイダーごとの.codex/hooks.jsonがそうでなければプロンプトを表示するものです。フックダイジェストはCodex自身のhooks/listから読み戻され、再計算されることはありません。

トラストはテーブルの存在ではなく、値によって判断されます。prepareは欠落しているエントリのみを追加し、エントリが存在するがトラストを付与しない場合（明示的なtrust_level = "untrusted"、Codexがトラストされてから変更されたと報告するフック、Codexがまだ拒否する記録されたフック、またはenabled = falseとして記録されたフック（無効なフックは信頼できる動作中のフックではありません））は、エントリに名前を付けて拒否します。オペレーターの決定を上書きすることはなく、再実行は何も行いません。また、Codexが空または認識できないフックリストを返した場合、続行せずに失敗します。トラストストア自体はその場で編集されることはありません。マージされたコンテンツは最初にメモリ内で解析され、その後CLIの耐久性のあるアトミックライターでインストールされるため、障害パスが部分的に書き込まれたCodex設定を残すことはありません。

ao gc checkはローカル状態のみから同じ事前シードを検証します。Codexサブプロセスを実行せず、何も書き込まず、ディレクトリ自身のhooks.jsonから各期待されるフックキーを導出し、prepareがシードするのと同じルールを使用して特定の不足しているディレクトリまたはフックに名前を付けます。

名前付きの2つの制限。

1. checkは古いハッシュを検出できません。 Codexに問い合わせないため、フックの現在のコンテンツに一致しなくなった記録されたtrusted_hashは満たされたものとして読み取られ、実際のセッションではまだトラストダイアログが表示されます。これを見るのはprepareだけです。Codexはフックが変更されたと報告し、prepareは拒否します。したがって、緑色のcheckは「トラストが記録されている」ことを意味し、「トラストが最新である」ことを意味しません。
2. prepare後に作成されたホームはカバーされません。 発見はファイルシステムマーカーによるものであるため、保証はprepare時に存在するセッションディレクトリをカバーします。Gas Cityが後でマテリアライズするセッションホームは、最初のスパーン時にまだ信頼されていないフックを持ちます。prepareはまだホームがない設定済みエージェントに名前を付けます。

両方に続く運用ルール：prepareを実行し、都市を起動し、ディスパッチする前にprepareを再度実行します（これはべき等です）。

推奨パックとレジストリ

組み込みのmainレジストリは公式パックをカタログ化します。コミュニティレジストリはオプションの設定です：

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

searchはローカルレジストリキャッシュを読み取ります。showはリリースの provenance と正確なインポートコマンドを報告します。gc import addはソース/バージョンを宣言し、gc import installはそれをpacks.lockに解決します。再現可能な都市には正確な承認済みリリースを優先してください。

AgentOpsは公式のgascityビルドパック、公開メンテナーシティファクトリーで表示可能なワークフローファミリーを優先します。現在の承認済み参照は、コミット3b3b89f2011e06d84459aa7bea1552382f13930aのgascity 0.1.6です：

• ダッシュボード：https://factory.gascity.com;
• ワークフロー：build-basic, build-from-*, implement, review, issue, およびPRフロー;
• ストックリグロール：gc.run-operator, gc.implementation-worker、プランナー、レビュアー、パブリッシャー;
• スコープローカルフォーミュラ制御：core.control-dispatcher;
• ガイド付きコーディネーション：上流のgc.mayorスキル。

gc pack registry show main:gascityによって返された正確なコマンドに従って、ワークフローパックを都市スコープに、その兄弟ロールパックを作業を実行するすべてのリグにインストールします。ストックのgc.*名前空間を維持し、ロールをAgentOpsパックの背後でネストまたは名前変更しないでください。

作業はメイヤーを通じて都市に入ります。呼び出し元は受け入れ条件を含む1つのソースインテントビーズを作成し、そのIDをメイヤーに渡します。メイヤーは分解し、ワークフロービーズを作成し、ディスパッチします。呼び出し元は決してgc slingを自分で実行しません。オペレーターがスリングしたランは、そのワークフローのリトライ、再ディスパッチ、およびテンディングを所有するコーディネーターをバイパスします。

gc bd create "exportコマンドに--jsonフラグを追加"
gc mail send mayor -s "ago-XXXXをビルド" \
  -m "ago-XXXXのビーズに対してbuild-basicを分解して起動し、push=true open_pr=trueとします。" --notify

または、インタラクティブなメイヤーセッションで：

スキルgc.mayorを使用

直接のgc slingは、ライブメイヤーのない都市のためのデバッグツールのままです。そのように開始されたランにはコーディネーターがなく、オペレーターがそのテンディングを継承します。

AgentOpsスキルは、それらのファクトリーエージェントが利用できるツールであり、ワークフローの代替ではありません。その動作が必要な場合は、ビーズまたはプロンプトでスキルを明示的に指定してください。現在の上流の分解は、呼び出し元が所有するソースビーズからの自由形式の「必須スキル」セクションを生成されたすべての作業アイテムに自動的に伝播しません。実装前に分解を検査し、その使用が受け入れ条件である場合、実際の作業アイテムまたはワーカープロンプトに必須スキル名を配置してください。スキルの存在とスキルの呼び出しは異なる事実です。

既存の都市を1.4にアップグレードする

オーケストレーターを起動する前に、都市ごとに1回実行します：

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOSで古い直接スーパーバイザーが残っている場合
gc start

次に確認します：

• gc versionが意図されたパスから1.4.0を報告すること;
• gc doctorにブロッキング障害がないこと;
• グラフを所有する各リグにサスペンドされていないcore.control-dispatcherがあること;
• インポートとpacks.lockが解決すること;
• ao gc checkが含まれているメンテナーランタイムとAgentOpsスキルリンクを受け入れること;
• macOSでは、スーパーバイザーLaunchAgentが選択されたgcバイナリと同じ実行可能ファイルに解決すること;
• 古いスタンドアロンダッシュボードのブックマークまたはリバースプロキシが削除されていること。

登録された古い都市は、すべての起動をブロックする可能性があります。gc doctor --fixでその都市を修復するか、意図的に引退させた場合は明示的に登録を解除してください。

古いHQ/カナリアを正確な登録名またはパスで引退させ、その代替に必要なマシン全体のスーパーバイザーを停止せずに行います：

gc cities --json
gc stop /path/to/old-city --timeout 45s
gc unregister /path/to/old-city
gc cities --json

unregisterは、不明なターゲットを静かに受け入れるのではなく、失敗します。そのBeads状態がバックアップされるか、破棄可能であると確認されるまで、都市ディレクトリを保持してください。上流のGas Cityテンプレートから代替を作成し、ピン留めされたインポートをインストールし、gc cities --json、gc --city <new-city> status、およびgc --city <new-city> doctor --jsonで検証します。

メイヤーを通じたオーケストレーション：テンディングループ

インテントをメイヤーに渡した後、オーケストレーターは5つの動詞を実行します。各動詞には1つの所有者がいます。所有者をまたぐことが、このセクションが存在して止めようとする再発する失敗クラスです。

動詞	所有者	表面
モニター	オーケストレーター	$API/runs/censusと$API/runs/<run-id>を固定の周期で、さらにメイヤーの返信についてはgc mail inbox。censusでfailed > 0、failed/canceled状態のラン、または未読のメイヤーメールがアクション信号です。それ以外はすべてティックです。
観察	オーケストレーター	アクション信号時に、可視性レイヤーを順に（census、ラン詳細、ビードグラフ、セッション名簿、ペイン真実）ウォークし、最初に説明するレイヤーで停止します。ペイン真実から開始しないでください。
ナッジ	オーケストレーター、1回	readyビーズ：そのgc.run_targetに1回ディスパッチします。ルーティングされたビーズでライブセッションがある場合：gc session wake <run_target>を1回。同じサブジェクトに対する2回目のナッジは診断が間違っていることを意味します。代わりにメイヤーにメールしてください。
リダイレクト	メイヤー	優先度、スコープ、キャンセル、またはモデル/プロバイダーの変更は、ビード/ランIDを添えたメールで伝達されます。オーケストレーターは決して再スリングしたり、ワークフロービーズを編集したり、ライブランをパッチしたりしません。
リワーク	GCが最初に、次にメイヤー	失敗したレビュー結果は、ネイティブの修正ループ（review_fix_formula、デフォルトはfix-loop-base）を通じてランに再入力されます。境界のあるゲート付きリトライはgc convergeループです。failed/canceledの終端状態のラン、または結果が呼び出し元の受け入れを満たさない完了したランだけが、メイヤーに戻ります。ランIDと失敗証拠をメールで送り、再分解と再起動を行います。

オーケストレーターが手動でリワークを実行すると（失敗したランのワークツリーを編集したり、そのフォーミュラを再スリングしたり、そのビーズを閉じたり）、同じインテントに対して2番目の調整されていない作成者が生まれます。メイヤーの再起動はそれと競合します。

スタールプロトコル

最初にビーズを分類します。

• まだready：そのgc.run_targetに1回ディスパッチし、停止して検査します。

• すでにルーティング済み/進行中：再スリングはNO-OPです。所有するワーカーを1回ウェイクします：

  gc session wake <run_target>
  

次に、セッション状態によって指定された正確なtmuxペインをキャプチャし、gc doctorを実行します。その都市の内部から都市を修復しないでください。

決してパック所有のセッションを手動で作成しないでください。シングルトンまたはスケーリングされたエージェント（core.control-dispatcher、ロールワーカー）に対するgc session newは、スコープを誤ったセッションを作成し、start-pendingで正規の名前を占有し、レコンサイラーが実際のものをスポーンするのをブロックします。これにより、修復しようとしているまさにそのスタールが延長されます。セッションのライフサイクルはレコンサイラーと需要スケーリングに属します。都市自体がテンディングを必要とする場合（スタールしたレコンサイラー、ドレインを決して離れないセッション、モデルまたはプロバイダーの再配線）、リクエストをメイヤーに送信します：

gc mail send mayor -s "<件名>" -m "<ビードIDを含むリクエスト>" --notify

上流パックは、将来のアフィニティバウンドステップを、すでにドレインACKを送信したセッションに割り当てる可能性があります。これは都市の外部からのみ診断してください：

ao gc recover-affinity --city /path/to/city --rig /path/to/rig

デフォルトはドライランです。リストされたすべての割り当てが正しい場合は、--applyを付けて繰り返します。制限された修復は、そのgc.session_affinity=requireセッションがもうライブではない、現在ready状態のフォーミュラビーズ上の割り当て先のみをクリアします。スリング、リトライ、クローズ、再起動、または作業の選択は行いません。

可視性：4つのレイヤー

1. スーパーバイザー/ラン状態 — gc dashboard、ラン詳細、gc status、およびgc session list --json。ラン詳細は、ステージラダー、構造化トランスクリプト、トークンレート、推定バーンレートを統合します。名簿はプロバイダーがウェッジしている間にアクティブを報告する場合があります。

   プログラムによるラン状態は、スーパーバイザーの型付けされたランAPIから取得されます。これはダッシュボードがレンダリングするのと同じデータです。gc statusはAPIベースを出力します。gc status --jsonや他のCLIサブコマンドはランオブジェクトを保持しません。

   API="http://127.0.0.1:<port>/v0/city/<city-name>"
   curl -s "$API/runs/<run-id>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, ...}}
   

2. ビーズグラフ — 特定のランにスコープされたソースインテントから派生したワークアイテムのDAG。各ビーズは、ソースインテント（「何を」）、id、ステータス、ターゲット、タイムスタンプ、およびフォーミュラが解決するプロンプトおよびコンテキストアーティファクトのリストを保持します。gc bd get <bead-id>はフィールドを読み取ります。決して書かないでください。gc.bd-cookを介して作成します。

3. セッション名簿 — 実行中のワーカーのリスト。gc session list --jsonを使用します。

4. ペイン真実 — ライブワークスペースのシェル（tmux、ターミナル、またはIDEタブ）。最後に確認します。ペインは無関係な出力、進行中のプロンプト、またはイベント中のプロンプトのためにミスリーディングになります。

ランの停止と終了

gc stop <run-id>
gc stop <run-id> --cancel

stopはランの現在のステップを完了させ、さらなるディスパッチを防ぎます。--cancelはすぐに停止します。canceledまたはfailedランは捨てられます。削除はありません。都市を再起動するか、メイヤーに新しいランを依頼してください。

コンフィグとテンプレート

gc configは都市レベルの設定を管理します。テンプレートはgc templateを介して管理されます。カスタムテンプレートはgc template createで作成できます。

gc config list
gc config get <key>
gc config set <key> <value>
gc template list
gc template create <name>

トラブルシューティング

gc doctorは一般的な問題を診断します。gc logはログを表示します。詳細についてはgc log --tailを使用してください。

gc doctor
gc log --tail

セキュリティ

Gas Cityは、APIキーによる認証とロールベースのアクセス制御（RBAC）をサポートしています。APIキーは、gc config set api_key <key>を使用して設定します。ロールはgc config set role <role>を使用して設定します。