boshu2/using-gc

GC 사용하기

호출자가 명시적으로 Gas City를 선택한 경우에만 사용하십시오. 이 스킬은 교체 가능한 실행 어댑터로 취급해야 하며, 정확성 또는 완료 경계로 간주하지 마십시오. 어댑터는 AgentOps 의미론을 선택하거나, 바인딩 판결을 내리거나, 공장 완료를 전달 또는 검증 증명으로 전환할 수 없습니다.

공장을 먼저 선택하세요

AgentOps는 외부 소프트웨어 공장 런타임으로 Gas City와 Agentic Coding Flywheel을 모두 지원합니다. 이 스킬은 Gas City에만 사용하십시오. 호출자가 Flywheel을 선택한 경우, using-flywheel 및 해당 네이티브 워크플로우로 전환하고 Gas City로 래핑하지 마십시오.

AgentOps는 두 공장 모두에 스킬과 증거 계약을 제공합니다. 자체 Gas City 공식(formula)이나 역할 팩이 필요하지 않습니다. 작업자를 시작하기 전에 AgentOps 스킬을 제공자 런타임에 설치하거나 링크하십시오. 그러면 상위 시장(Mayor), 코디네이터 및 작업자가 정상적으로 plan, implement, test, validate 및 기타 AgentOps 스킬을 검색하고 선택할 수 있습니다.

Gas City 1.4 운영 모델

Gas City 1.4는 실행(run) 중심입니다. 수퍼바이저는 대시보드와 유형화된 페이지네이트 세션/실행 API를 제공합니다. 모든 그래프를 소유한 도시(city) 또는 리그(rig) 범위에는 자체 core.control-dispatcher가 필요합니다. 이 결정론적 작업자는 공식 제어 비드(formula control bead)를 진행시킵니다. 에이전트 작업자는 라우팅된 작업을 요청합니다. 상위 gc.mayor 스킬은 안내된 코디네이터 역할을 합니다. gc.run-operator는 공식을 시작하고 감독합니다.

일반적인 AgentOps 경로는 다음과 같습니다.

1. 상위 gascity 워크플로우 및 리그 역할 가져오기를 설치하고 고정(pin)합니다.
2. 프로젝트를 리그로 추가하고, 스톡 유지보수자 런타임을 준비한 다음, AgentOps 스킬을 제공자 세션에서 볼 수 있도록 만듭니다.
3. 호출자가 소유한 소스 의도 비드(source intent bead)를 생성하고 그 ID를 시장(Mayor)에게 전달합니다. 시장은 워크플로우 비드를 작성하고 사용 가능한 아티팩트와 일치하는 상위 build-basic, 연속, 검토 또는 구현 공식을 디스패치합니다.
4. 실행, 세션, 비드, 아티팩트 및 판결 상태를 읽습니다. 완료는 채팅 또는 창(pane) 텍스트에서 추론되지 않습니다.

첫 번째 빌드 전에 제공된 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 신뢰를 사전 시딩(pre-seed)합니다. 따라서 해당 디렉토리 중 하나에 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가 시딩하는 것과 동일한 규칙을 사용하여 특정 결함 디렉토리 또는 후크를 명명합니다.

두 가지 명명된 제한 사항.

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는 릴리스 출처와 정확한 가져오기 명령을 보고합니다. gc import add는 소스/버전을 선언하고, gc import install은 이를 packs.lock으로 해결합니다. 재현 가능한 도시를 위해 정확한 승인된 릴리스를 선호하십시오.

AgentOps는 공식 gascity 빌드 팩, 공개 유지보수자 도시 공장에서 볼 수 있는 워크플로우 제품군을 선호합니다. 현재 승인된 참조는 커밋 3b3b89f2011e06d84459aa7bea1552382f13930a의 gascity 0.1.6입니다.

• 대시보드: https://factory.gascity.com;
• 워크플로우: build-basic, build-from-*, implement, 검토, 이슈 및 PR 흐름;
• 스톡 리그 역할: gc.run-operator, gc.implementation-worker, 플래너, 검토자 및 게시자;
• 범위-로컬 공식 제어: core.control-dispatcher;
• 안내된 조정: 상위 gc.mayor 스킬.

gc pack registry show main:gascity가 반환하는 정확한 명령에 따라 도시 범위에 워크플로우 팩을 설치하고 작업을 실행하는 모든 리그에 형제 역할 팩을 설치하십시오. 스톡 gc.* 네임스페이스를 유지하십시오. AgentOps 팩 뒤에 역할을 중첩하거나 이름을 바꾸지 마십시오.

작업은 시장(Mayor)을 통해 도시로 들어갑니다. 호출자는 승인과 함께 하나의 소스 의도 비드(source intent bead)를 작성한 다음 시장에게 해당 ID를 전달합니다. 시장은 분해하고, 워크플로우 비드를 작성한 다음 디스패치합니다. 호출자는 절대 gc sling을 직접 실행하지 않습니다. 운영자가 슬링한 실행은 해당 워크플로우에 대한 재시도, 재디스패치 및 관리를 소유하는 코디네이터를 우회합니다.

gc bd create "export 명령에 --json 플래그 추가"
gc mail send mayor -s "ago-XXXX 빌드" \
  -m "비드 ago-XXXX에 대해 push=true open_pr=true로 build-basic을 분해하고 시작하십시오." --notify

또는 대화형 시장 세션에서:

gc.mayor 스킬 사용

직접 gc sling은 라이브 시장이 없는 도시의 디버깅 도구로 남아 있습니다. 이러한 방식으로 시작된 실행에는 코디네이터가 없으며 운영자가 해당 관리를 상속합니다.

AgentOps 스킬은 해당 공장 에이전트가 사용할 수 있는 도구이며, 워크플로우를 대체하지 않습니다. 해당 동작이 필요할 때 비드 또는 프롬프트에 스킬 이름을 명시적으로 지정하십시오. 현재 상위 분해는 호출자가 소유한 소스 비드의 자유 형식 필수 스킬 섹션을 생성된 모든 작업 항목에 자동으로 전파하지 않습니다. 구현 전에 분해를 검사하십시오. 스킬 사용이 승인 조건인 경우 실제 작업 항목 또는 작업자 프롬프트에 필수 스킬 이름을 넣으십시오. 스킬 존재와 스킬 호출은 다른 사실입니다.

기존 도시를 1.4로 업그레이드

오케스트레이터를 시작하기 전에 도시당 한 번 실행하십시오.

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으로 확인하십시오.

시장(Mayor)을 통한 오케스트레이션: 텐딩 루프(tending loop)

의도를 시장에 전달한 후 오케스트레이터는 다섯 가지 동사를 실행합니다. 각 동사에는 한 명의 소유자가 있습니다. 소유자를 교차하는 것은 이 섹션이 중지하기 위해 존재하는 반복적인 실패 클래스입니다.

동사	소유자	표면
모니터링(Monitor)	오케스트레이터	고정된 주기로 $API/runs/census 및 $API/runs/<run-id>, 그리고 시장 답장을 위한 gc mail inbox. 인구 조사에서 failed > 0, failed/canceled 상태의 실행, 또는 읽지 않은 시장 메일이 동작 신호입니다. 그 외의 모든 것은 틱(tick)입니다.
관찰(Observe)	오케스트레이터	동작 신호 시 인구 조사, 실행 세부 정보, 비드 그래프, 세션 명단, 창(pane) 진실 순서로 가시성 계층을 탐색하고 설명하는 첫 번째 계층에서 중지합니다. 창 진실부터 시작하지 마십시오.
넛지(Nudge)	오케스트레이터, 한 번	ready 비드: gc.run_target으로 한 번 디스패치합니다. 라이브 세션이 있는 라우팅된 비드: gc session wake <run_target>을 한 번 실행합니다. 동일한 주제에 대한 두 번째 넛지는 진단이 잘못되었음을 의미합니다. 대신 시장에게 메일을 보내십시오.
리디렉션(Redirect)	시장	우선 순위, 범위, 취소 또는 모델/제공자 변경은 비드/실행 ID와 함께 메일로 전달됩니다. 오케스트레이터는 절대 다시 슬링하거나, 워크플로우 비드를 편집하거나, 라이브 실행에 패치하지 않습니다.
재작업(Rework)	GC 먼저, 그 다음 시장	실패한 검토 결과는 네이티브 수정 루프(review_fix_formula, 기본값 fix-loop-base)를 통해 실행에 다시 들어갑니다. 제한된 게이트 재시도는 gc converge 루프입니다. failed/canceled 상태의 TERMINAL 실행(또는 완료되었지만 결과가 호출자 승인을 놓친 실행)만 다시 전달됩니다. 실행 ID와 실패 증거를 시장에게 메일로 보내 재분해 및 재실행을 요청하십시오.

오케스트레이터가 수동으로 수행하는 재작업(실패한 실행의 작업 트리 편집, 공식 다시 슬링, 비드 닫기)은 동일한 의도에 대해 두 번째 조정되지 않은 작성자를 생성합니다. 시장의 재실행이 이를 경합합니다.

중단 프로토콜

먼저 비드를 분류하십시오.

• 여전히 ready: gc.run_target으로 한 번 디스패치한 다음 중지하고 검사하십시오.

• 이미 라우팅/진행 중: 다시 슬링하는 것은 NO-OP입니다. 소유 작업자를 한 번 깨우십시오.

  gc session wake <run_target>
  

그런 다음 세션 상태로 명명된 정확한 tmux 창을 캡처하고 gc doctor를 실행하십시오. 해당 도시 내에서 도시를 복구하지 마십시오.

팩 소유 세션을 수동으로 생성하지 마십시오. 단일 또는 확장된 에이전트(core.control-dispatcher, 역할 작업자)에 대한 gc session new는 잘못된 범위의 세션을 만들어 start-pending에서 표준 이름을 점유하고 조정자가 실제 세션을 생성하는 것을 차단하여 정확히 복구 중인 중단을 연장합니다. 세션 수명 주기는 조정자 및 수요 확장에 속합니다. 도시 자체에 관리가 필요한 경우(중단된 조정자, 드레이닝을 벗어나지 않는 세션, 모델 또는 제공자 재연결), 요청을 시장(Mayor)에게 보내십시오.

gc mail send mayor -s "<제목>" -m "<비드 ID가 포함된 요청>" --notify

상위 팩은 미래의 선호도 결합 단계를 이미 드레인 승인된 세션에 할당할 수 있습니다. 도시 외부에서만 진단하십시오.

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

기본값은 드라이 런(dry run)입니다. 나열된 모든 할당이 올바른 경우 --apply를 사용하여 반복하십시오. 제한된 복구는 gc.session_affinity=require 세션이 더 이상 활성화되지 않은 현재 준비된 공식 비드의 담당자만 지웁니다. 슬링, 재시도, 종료, 재시작 또는 작업 선택을 수행하지 않습니다.

가시성: 네 가지 계층

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. 비드 그래프 — gc bd graph <run-target>. 각 비드는 타입, 상태 및 할당을 보여줍니다. 할당된 비드는 소유 세션을 가리킵니다. ready 비드가 라우팅을 기다리고 있는지, 아니면 비드가 잘못된 세션에 붙어 있는지 알려줍니다.

3. 세션 명단 — gc session list --json은 탐색에 tmux select-window가 필요할 수 있는 tmux 창 번호 없이도 각 세션에 대한 타입, 상태, 라우팅 키 및 포트를 보여줍니다. 오케스트레이터는 plan, implement, review 등과 같은 타입으로 작업자를 식별합니다. 두 개의 동일한 타입은 하나의 공유 라우트된 요청을 경합하는 개별 작업자 인스턴스입니다.

4. 창 진실(Pane truth) — tmux 창 내용. 재생 및 상태 덤프가 여기에 나타납니다. 이것은 네 가지 계층 중 네 번째입니다. 여기서 시작하지 마십시오.

사전 시딩 요약

ao gc prepare는 이러한 신뢰 항목을 설정합니다.

위치	신뢰 유형	예시 섹션
도시 루트	워크스페이스	[projects."/Users/me/cities/my-city"]
도시 루트	후크	[hooks.state."hooks.json:pre-commit:m:hash"]
리그 루트	워크스페이스	[projects."/Users/me/work/my-project"]
리그 루트	후크	[hooks.state."hooks.json:pre-commit:m:hash"]
각 .gc/agents/** 세션 홈	워크스페이스	해당 디렉토리에 대해 설정
각 리그 작업 트리 루트	워크스페이스	worktrees/의 각 항목에 대해 설정

일반적인 명령 참조

# 준비 및 검증
ao gc prepare --city /path/to/city --rig /path/to/rig
ao gc check --city /path/to/city --rig /path/to/rig

# 비드 및 시장
gc bd create "<의도>"
gc mail send mayor -s "<제목>" -m "<본문>" --notify

# 세션
gc session list --json
gc session wake <run_target>

# 상태
gc status [--city <city>]
gc doctor [--fix]

# 실행 (읽기 전용)
gc runs list --city <city> [--status active]

# 팩 및 레지스트리
gc pack registry list
gc pack registry show main:gascity
gc pack registry search --all

# 도시 관리
gc cities --json
gc stop /path/to/city --timeout 45s
gc unregister /path/to/city
gc start

# 복구
ao gc recover-affinity --city /path/to/city --rig /path/to/rig [--apply]