boshu2/using-gc

使用 GC

僅在呼叫者明確選擇 Gas City 時使用。將其視為可替換的執行轉接器，而非正確性或完成性邊界。此轉接器無法選擇 AgentOps 語意、發出綁定性裁決，或將工廠完成轉換為交付或驗證證明。

先選擇工廠

AgentOps 同時支援 Gas City 與 Agentic Coding Flywheel 作為外部軟體工廠執行環境。此技能僅用於 Gas City。如果呼叫者選擇 Flywheel，請切換至 using-flywheel 及其原生工作流程，而非將其包裝在 Gas City 中。

AgentOps 為任一工廠提供技能與證據合約。它不需要自身的 Gas City 公式或角色套件。在啟動 workers 之前，將 AgentOps 技能安裝或連結至提供者執行環境；上遊市長、協調器與 workers 隨後即可正常發現並選擇 plan、implement、test、validate 及其他 AgentOps 技能。

Gas City 1.4 操作模型

Gas City 1.4 以執行（run）為中心。監督者提供儀表板以及類型化、分頁的 session/run API。每個擁有圖形的城市或 rig 範圍都需要自己的 core.control-dispatcher；該確定性 worker 負責推進公式控制珠子。代理 workers 領取路由後的工作。上遊的 gc.mayor 技能是指導型協調器；gc.run-operator 啟動並監督公式。

標準的 AgentOps 路徑為：

1. 安裝並鎖定上遊的 gascity 工作流程與 rig 角色匯入。
2. 將專案新增為 rig，準備其 stock maintainer 執行環境，並使 AgentOps 技能對其提供者 sessions 可見。
3. 建立一個由呼叫者擁有的來源意圖珠子，並將其 id 交給 Mayor，Mayor 會撰寫工作流程珠子並調度與可用產出物相符的上遊 build-basic、continuation、review 或 implementation 公式。
4. 讀取 run、session、bead、artifact 與 verdict 狀態。完成狀態絕不能從聊天或面板 prose 中推斷。

在使用隨附的 AgentOps CLI（無需 repo checkout）進行首次建置前，準備並驗證 rig：

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

此命令會驗證精確的官方工作流程與角色鎖定、在 rig 的 .gc 執行環境內保持上遊驗證腳本與 schema 不變、僅在公式檢查路徑安裝小型的 AgentOps 自有包裝器、選擇一個可匯入 PyYAML 的現有 Python，並將 AgentOps 技能連結至 city 與 rig 的 Codex sinks。技能來自於外層的 AgentOps checkout（如果存在），否則來自已安裝的技能根目錄；傳遞 --skills-source 以固定不同的目錄。它絕不修改 GC 二進位檔、快取、公式、角色或上遊套件。check 僅發出原生命令，不寫入任何轉接器檔案，並在模型花費之前，於該執行環境合約缺失或漂移時失敗。

prepare 也會在其執行時為每個存在的 session 目錄預先種子 Codex 信任——city 與 rig 根目錄、每個 .gc/agents/** session home，以及每個 rig worktree 根目錄——因此這些目錄中的 Codex session 不會被互動式信任對話框阻擋。兩種持久化層級都在 $CODEX_HOME/config.toml 中種子：工作區信任（[projects."<dir>"] trust_level = "trusted"），缺少此設定時 Codex 會靜默回報該目錄完全沒有 hooks；以及每個 hook 的信任（[hooks.state."<hooks.json>:<event>:<m>:<h>"] trusted_hash = "sha256:..."），這正是套件中每個提供者的 .codex/hooks.json 否則會提示的內容。Hook 摘要從 Codex 自身的 hooks/list 中讀回，絕不重新計算。

信任是根據值來判斷，而非根據表的存在與否。prepare 僅附加缺少的條目，並在條目存在但不授予信任時拒絕（並指出該條目名稱）——例如明確的 trust_level = "untrusted"、Codex 回報自信任後已變更的 hook、Codex 仍拒絕的已記錄 hook，或記錄為 enabled = false 的 hook（已停用的 hook 不是可運作的信任 hook）。它絕不覆寫操作者決定，且重新執行是無操作的。如果 Codex 回傳空白或無法辨識的 hook 列表，它也會失敗而非繼續。信任儲存本身絕不就地編輯：合併後的內容先在記憶體中解析，然後使用 CLI 的持久原子寫入器安裝，因此沒有任何失敗路徑會留下部分寫入的 Codex 配置。

ao gc check 僅從本地狀態驗證相同的預先種子——它不執行 Codex 子行程，也不寫入任何內容，從目錄自身的 hooks.json 推導每個預期的 hook 金鑰——並使用 prepare 種子時所用的相同規則指出特定的缺失目錄或 hook。

兩個已命名的限制。

1. check 無法偵測到陳舊的雜湊值。 因為它從不詢問 Codex，一個已記錄的 trusted_hash 若不再符合 hook 的當前內容，仍會被視為已滿足，並在真實的 session 中引發信任對話框。只有 prepare 能看到這一點——Codex 回報 hook 已變更，而 prepare 會拒絕。因此，綠色的 check 意味著「信任已被記錄」，而非「信任是最新的」。
2. prepare 後建立的 home 不受覆蓋。 發現是透過檔案系統標記進行，因此保證涵蓋 prepare 時存在的 session 目錄。Gas City 之後 才具體化的 session home 在首次啟動時仍會帶有未受信任的 hooks；prepare 會指出那些尚無 home 的已配置代理。

從兩者得出的操作規則：執行 prepare，啟動 city，然後在調度前再次執行 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 建置套件，該工作流程家族可見於公開的 Maintainer City 工廠。目前接受的參考版本為 gascity 0.1.6，commit 3b3b89f2011e06d84459aa7bea1552382f13930a：

• 儀表板：https://factory.gascity.com;
• 工作流程：build-basic、build-from-*、implement、review、issue 與 PR 流程;
• stock rig 角色：gc.run-operator、gc.implementation-worker、規劃者、審查者與發布者;
• 範圍局部公式控制：core.control-dispatcher;
• 引導式協調：上遊的 gc.mayor 技能。

在 city 範圍安裝工作流程套件，並在其執行工作的每個 rig 上安裝其配套角色套件，遵循 gc pack registry show main:gascity 回傳的精確命令。保留 stock 的 gc.* 命名空間；不要將角色巢狀化或重新命名到 AgentOps 套件後面。

工作透過市長進入 city。呼叫者撰寫一個帶有驗收條件的來源意圖珠子，然後將該珠子的 id 交給 Mayor——Mayor 會分解、撰寫工作流程珠子並進行調度。呼叫者絕不自行執行 gc sling；由操作者 sling 的執行會繞過擁有該工作流程重試、重新調度與維護責任的協調器。

gc bd create "Add a --json flag to the export command"
gc mail send mayor -s "Build ago-XXXX" \
  -m "Decompose and launch build-basic for bead ago-XXXX with push=true open_pr=true." --notify

或者，在互動式的 Mayor session 中：

Use skill gc.mayor

直接的 gc sling 仍然是針對沒有 live Mayor 的 city 的除錯工具；以這種方式啟動的執行沒有協調器，操作者需承擔其維護責任。

AgentOps 技能是提供給那些工廠代理的工具，而非替代工作流程。當需要其行為時，請在珠子或提示中明確指定技能名稱。當前的上遊分解不會自動將呼叫者擁有的來源珠子中的自由格式 Required Skills 部分傳播到每個產生的工項中。在實施之前檢查分解；當技能的使用是驗收條件時，請將所需的技能名稱放在實際的工項或 worker 提示中。技能存在與技能調用是不同的概念。

將現有 city 升級至 1.4

在啟動其編排器之前，請為每個 city 執行一次：

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS 上，當舊的直接監督者仍在時
gc start

然後確認：

• gc version 從預期路徑報告 1.4.0;
• gc doctor 沒有阻塞性失敗;
• 每個擁有圖形的 rig 都有一個未暫停的 core.control-dispatcher;
• imports 與 packs.lock 解析成功;
• ao gc check 接受包含的 maintainer 執行環境與 AgentOps 技能連結;
• 在 macOS 上，監督者 LaunchAgent 解析至與所選 gc 二進位檔相同的可執行檔;
• 移除舊的獨立儀表板書籤或反向代理。

一個過時的已註冊 city 可能會阻止每一次啟動。使用 gc doctor --fix 修復該 city，或者如果它已被有意退役，則明確取消註冊。

按精確的註冊名稱或路徑退役舊的 HQ/canary，無需停止其替代品所需的機器級監督者：

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

unregister 在遇到未知目標時會失敗，而非靜默接受。保留 city 目錄，直到其 Beads 狀態被備份或確認可丟棄。從上遊 Gas City 模板建立替代品，安裝其鎖定的 imports，並使用 gc cities --json、gc --city <new-city> status 以及 gc --city <new-city> doctor --json 進行驗證。

透過市長編排：維護迴圈

將意圖交給 Mayor 後，編排器執行五個動詞。每個動詞有一個擁有者；跨越擁有者是本節旨在阻止的反覆失敗類別。

動詞	擁有者	接觸面
監控 (Monitor)	編排器	以固定節奏查詢 $API/runs/census 和 $API/runs/<run-id>，加上透過 gc mail inbox 收取 Mayor 回覆。census 中的 failed > 0、處於 failed/canceled 狀態的執行，或未讀的 Mayor 郵件即為行動信號；其他情況皆為一次 tick。
觀察 (Observe)	編排器	接到行動信號後，按順序遍歷可見性層級——census、run detail、bead graph、session roster、pane truth——並停在第一個能解釋問題的層級。不要從 pane truth 開始。
輕推 (Nudge)	編排器，僅一次	一個 ready 的珠子：對其 gc.run_target 調度一次。一個已路由且存在 live session 的珠子：執行 gc session wake <run_target> 一次。對同一個主體進行第二次輕推表示診斷錯誤——應改為郵件通知 Mayor。
重新導向 (Redirect)	Mayor	優先級、範圍、取消或模型/提供者變更透過包含 bead/run id 的郵件傳遞。編排器絕不重新 sling、編輯工作流程珠子或修補正在進行的執行。
補救 (Rework)	先 GC，再 Mayor	失敗的審查結果透過其原生的修正迴圈（review_fix_formula，預設為 fix-loop-base）重新進入執行；有界限的閘控重試是 gc converge 迴圈。只有 TERMINAL 狀態的 failed/canceled 執行——或一個已完成但其結果不符合呼叫者驗收條件的執行——才需要回饋：將執行 id 與失敗證據郵件給 Mayor，以便重新分解並重新啟動。

編排器手動執行的補救（編輯失敗執行的工目錄、重新 sling 其公式、關閉其珠子）會為同一個意圖建立第二個未協調的作者；Mayor 的重新啟動會與之競爭。

停滯協定

首先分類珠子。

• 仍為 ready：對其 gc.run_target 調度一次，然後停止並檢查。

• 已路由/進行中：重新 sling 是 無操作 (NO-OP)。喚醒其擁有的 worker 一次：

  gc session wake <run_target>
  

然後捕獲 session 狀態所指名的確切 tmux 面板並執行 gc doctor。絕不要從該 city 內部修復 city。

絕不要手動建立由套件擁有的 sessions。為單例或擴展代理（core.control-dispatcher、角色 workers）執行 gc session new 會建立一個範圍錯誤的 session，該 session 會佔用 start-pending 中的規範名稱，並阻止協調器產生真實的 session——從而延長正在修復的確切停滯。Session 生命週期屬於協調器與需求擴展。當 city 本身需要維護時（協調器停滯、從不離開 draining 狀態的 sessions、模型或提供者重新佈線），請將請求發送給 Mayor：

gc mail send mayor -s "<subject>" -m "<request with bead ids>" --notify

上遊套件可能會將一個未來的親和力綁定步驟分配給一個已經 drain-ack 的 session。僅從 city 外部診斷此問題：

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

預設為試運行。如果每個列出的分配都是正確的，請使用 --apply 重複執行。此有限制的修復僅會清除目前處於 ready 狀態、其 gc.session_affinity=require 的 session 已不再 live 的公式珠子上的受指派者。它不會 sling、重試、關閉、重新啟動或選擇工作。

可見性：四個層級

1. 監督者/執行狀態 — gc dashboard、執行詳細資訊、gc status 以及 gc session list --json。執行詳細資訊統一了階段階梯、結構化記錄、令牌速率與估計燃燒速率。當提供者卡住時，roster 仍可能報告為 active。

   程式化執行狀態來自監督者的類型化執行 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, ...}}
   

   路由的執行會在 census 中出現。尚未路由的執行不會出現。將執行狀態讀取為 gc status --json 加上監督者 API 的組合。

2. Session 狀態 — gc session list --json 或 gc session show <target>。一個 session 維持 active 直到其 worker 正式 drain 並關閉其側車。一個 terminating 或 draining 的 session 仍然是 session——不要假設它已消失。

3. 產品狀態 — 公式的 bead inspect，這是被路由的工作單元。產品層級是唯一可以看到 ready（可調度）、running（已路由）、completed 或 failed 的地方。監督者 API 不攜帶珠子；監督者只知道執行範圍與會話關係。

4. 面板真相 — 如果 session 處於 active，gc session show <target> 會列出其擁有的面板。面板輸出是唯一一個代理實際上可能正在推理但尚未產生產品或執行工件的地方。面板輸出中的 「done」 或 「complete」 字樣並不代表完成——只有產品的 completed 狀態才算數。在監督者 API 中有可觀察狀態之前，先不要讀取面板。

重新連線至正在進行的執行

當會話重疊中斷時，監督者會繼續運行。使用驅動器圖形名稱或執行目標重新連接：

gc session attach <target>         # 選擇第一個活動會話

當一個會話在連接之前完成時，面板輸出仍然可以透過執行工件取得：

gc artifact list --run <run-id>
gc artifact show <artifact-path>

執行重新啟動與初始化的紀元

將 gc start 後的監督者紀元視為一個全新的可觀察性紀元。在 gc start 之前開始的執行的收件匣郵件可能仍然存在，因為收件匣儲存在 city 自身的狀態中，而不是監督者記憶體中，但新的監督者將已完成的執行報告為 terminated。沒有 gc sling 或 gc converge 能夠在重新啟動的 city 中與一個紀元前的執行互動。

在 City 外部停止

監督者不會回應 SIGTERM 或 SIGINT。Gas City 提供一個本地埠。從 city 外部停止 gc supervisor：

gc stop                                                    # 優雅停止
kill "$(cat /path/to/city/.gc/supervisor.pid)"            # 強制停止

優雅停止會讓已路由的會話有機會將其工件寫入 Beads 狀態。強制停止不會。在同一個 city 目錄上重複執行 gc start 會導致監督者拒絕啟動，並出現一個指示綁定埠或 PID 檔案衝突的錯誤。使用 gc stop 或明確的 kill 配合正確的 PID 檔案。

角色與圖形：操作者與 Worker

角色	範圍	目的
gc.run-operator	rig	協調此 rig 上所有工作。持有 core.control-dispatcher。一個 rig 只應有一個執行的操作者。
gc.implementation-worker	rig	接收來自操作者的路由工作。該 worker 會話在 pam 或 tmux 中執行公式。

這兩者都來自 main:gascity 套件，而不是 AgentOps。AgentOps 提供 skill 產品——plan、implement、test、validate——供這些角色在其提示中使用。

已棄用：AO 特定擴展

在 Gas City 1.0 中，AgentOps 引入了下列特定於廠商的概念。1.4 將它們全部棄用：

• AO 套件：GC 現在有自己的 main 註冊表。使用 gc pack registry 而不是 AO_PACK_REGISTRY。
• AO 工作流程：GC 1.4 擁有原生的 build-basic 與 build-from-*。AO 不應包裹它們。
• AO gc.sling：由 GC 的 gc sling 取代。AO 不應包裹它。
• AO gc.converge：由 GC 的 gc converge 取代。AO 不應包裹它。