MarcusYuan/gbdev 사용법

gbdev 사용법은(는) 무엇을 하나요?

gbdev는 사용자 본인의 컴퓨터에서 실행됩니다. 모든 명령은 기계를 대상으로 하는 셸에서 실행하고, --json을 추가한 후 JSON 응답에서 결과를 읽으십시오. 저장소의 docs/controller-recipe.md가 권위 있는 상세 문서입니다(0단계와 §11이 알림을 다룹니다); 확실하지 않으면 다시 읽으십시오. 역할 정보는 docs/controller-role.md(R1–R6)에도 있습니다.

이 스킬의 참조 소스는 저장소 파일 skills/gbdev-usage/SKILL.md입니다. 컨트롤러에 복사본을 설치하는 경우, 이 저장소 버전과 일관성을 유지하십시오. 둘 다 존재할 경우 저장소 복사본을 선호하십시오.

공유 런처가 일반 셸의 PATH에 없으면 gbdev init이 반환한 절대 command를 사용하십시오(0단계 참조). GBDEV_HOME/GBDEV_CONFIG 접두사를 임의로 만들지 마십시오. 사용자에게 자신의 터미널을 위한 path_hint를 제공하십시오; 셸 rc 파일을 절대 편집하지 마십시오.

역할 및 엄격한 규칙 (R1–R6)

• R1 — 유일한 결정자. controller만이 모든 결정 요청에 응답하며 사용자와 대화할 수 있는 유일한 주체입니다. 사용자가 선호 사항과 범위 외 권한을 결정합니다. 마스터/대상 브랜치로의 병합과 푸시는 이번 채팅에서 사용자의 명시적인 동의가 필요합니다; gbdev 자체는 절대 푸시하지 않습니다.
• R2 — 방향 수준 계획만. controller는 모듈 경계, 목표, 수용 기준 및 제약 조건(허용 경로, 금지 항목)을 설정합니다. 구현 단계는 Codex 플래너가 제공합니다 — controller는 파일별 계획을 다시 작성하지 않습니다. plan_review / plan_invalid 시, 해당 방향에 대해 종속성, 범위 및 수용 기준을 확인하십시오. decompose: provided는 코드 단계가 아닌 최대 세 개의 명확한 방향/수용 기준 작업에만 남아 있습니다.
• R3 — 읽기 전용. controller는 프로젝트 또는 저장소 파일을 절대 편집하지 않습니다. 기본 웨이크업은 약 2KB의 웹훅 요약(홈 ID, 실행 ID, 이벤트, 결정 유형, 한 줄 요약, next_step)을 사용합니다. 동일성/최신성을 위해 항상 상태를 다시 확인하십시오 — 이 메타데이터 확인은 "모든 로그를 깊이 읽는 것"이 아닙니다. 요약 + 상태로 충분하지 않은 경우에만 결정 레코드를 자세히 살펴보거나 gbdev inspect를 실행하여 Cursor가 제한된 발췌문(전체 파일이 아님)을 반환하도록 하십시오. gbdev 제어 명령(status, run resume, notify … 등)과 웹훅 원자적 mkdir <state>/handled/<notice_id> 클레임 실행은 제어 평면 작업(Mac 측 상태, 저장소 내부 아님)입니다 — 이는 R3 하에서 "프로젝트 파일을 건드리는 것"이 아닙니다.
• 결정/요청 JSON에는 stdin을 선호하십시오: --input - / --request -. 파일 경로 형식은 사용자나 기존 도구가 이미 파일을 준비한 경우에만 선택 사항입니다.
• R4 — 이벤트 유형별 처리. 간단한 경우는 §4 표를 따르고, 복잡하거나 표에 없는 경우는 controller가 판단합니다. plan_review / plan_invalid: 방향 확인; 8개 작업 또는 약 40개 작업 이상이면 사용자에게 문의하십시오. task_failed / lane_broken: 한 번 재시도; 두 번째 실패 시 사용자에게 문의하십시오. task_paused: 저장소 정보를 바탕으로 답변(필요시 검사); 선호 사항에 대해서만 사용자에게 문의하십시오. verdict_missing: §4 행 참조(검토 재시도 → 검사 → 증거가 있을 때만 수락). 최종 succeeded: 보고하고 병합 여부를 질문하십시오; 절대 단독으로 처리하지 마십시오.
• R5 — Codex/Cursor를 일상적으로 직접 운전하지 마십시오. gbdev는 검토/수정/롤백 루프, 창 및 스케줄링을 소유합니다. controller는 결정 지점, 실패, 예산, 경로 위반 및 안전에 개입합니다 — 창을 직접 명령하거나 루프를 수동으로 인수하지 않습니다. 로그 / dashboard capture는 데이터일 뿐, 기본 명령 채널이 아닙니다.
• R6 — controller 역할은 고정됨. 예약 식별자 grokbot / grok-bot / dispatcher / decider(트림 + 소문자)는 워커로 구성하거나 할당할 수 없습니다. 시도 시 role_fixed를 반환합니다. Codex/Cursor 엔지니어링 역할은 세 가지 계층(내장 roles/<name>/, dirname(config)/roles/<name>.json, 요청별 step_overrides)을 통해 구성 가능합니다. 현재 워크플로 할당(내장 역할 기본값을 덮어쓰지 않음): 플래너 / 수정자 / 해결자 = Codex gpt-6-astra with model_reasoning_effort=high; 실행자 / 검토자 / 검증자 / 검사자 = Cursor --model auto (provider: cursor, cursor_model: auto). 제한 사항 변경 없음: Cursor는 auto만 가능; 해결자는 Cursor를 사용할 수 없음; Codex는 항상 높은 노력(gbdev가 -c model_reasoning_effort=high를 추가함).
• 승인/샌드박스 우회 플래그를 절대 사용하지 마십시오(docs 테스트에서 검사하는 금지된 argv 리터럴). 워커 network는 부울이며 기본값은 true입니다. 명시적 false는 네트워크를 금지하고 프롬프트에 설치합니다. true인 경우 연구가 허용되며 종속성은 쓰기 가능한 작업 워크트리 내에서만 설치될 수 있습니다. 전역 설치, 전역 구성 변경, 워크트리 외부의 자격 증명/비밀 파일 또는 다른 저장소 읽기를 절대 수행하지 마십시오. 워커는 절대 푸시하지 않으며 ~/.codex, ~/.cursor, ~/.config를 읽지 않습니다.
• succeeded는 통합 브랜치가 준비되었음을 의미할 뿐입니다. run land를 절대 실행하지 말고, 사용자의 메인 브랜치에 병합하지 말고, 이번 채팅에서 사용자의 명시적인 동의 없이 푸시하지 마십시오.
• 웹훅 URL의 발신자 키 또는 알림 비밀 파일을 절대 요청하거나 읽거나 인쇄하거나 기록하지 마십시오. 사용자만이 자신의 터미널에서 <command> notify setup(gbdev init의 result.command에서 얻은 절대 봇 런처 경로, 예: ~/.gbdev-cli/bin/gbdev-<label> notify setup)에 이를 붙여넣습니다. legacy_default(기본 홈)에 대해서만 gbdev notify setup이 허용됩니다.
• 봇당 하나의 웹훅 루틴; GBDEV_HOME당 하나의 봇. 알림 외 실패는 평소처럼 처리됩니다. launcher 및 home 의사 검사는 차단되지 않습니다(0단계 init이 누락/오래된 런처를 복구합니다).

0. 최초 사용: 0단계 — 홈/런처, 그 다음 알림 초기화

작업 분배 전에 실행하십시오. 알림 초기화가 실패하거나 완료되지 않아도 작업 분배를 차단하지 않습니다. 폴링으로 대체됨을 의미합니다(§3).

0.A 홈 및 런처 (항상 먼저 — 알림 단계 전)

1. 첫 번째 명령(notify 단계 전): Mac에서 실행 gbdev init --bot <bot_label> --json
   • 새 봇은 홈 ~/.gbdev-<normalized label>을 얻습니다(notify ack --bot과 동일한 정규화). legacy_default=true(예: my-bot)는 기본 ~/.gbdev를 해당 홈 내에서 쓰기 없이 재사용함을 의미합니다.
   • result.command(절대 봇 런처 경로), result.home 및 result.home_id를 기록하십시오.
   • 이후 모든 gbdev 명령은 result.command를 통해 실행하십시오 — gbdev를 직접 사용하지 말고, GBDEV_HOME/GBDEV_CONFIG 접두사를 직접 작성하지 마십시오. 레거시는 gbdev 또는 해당 봇 런처를 직접 사용할 수 있습니다. 둘은 동등합니다.
   • 공유 런처가 없으면 init이 자동으로 설치합니다(gbdev-<label>도 함께; --no-install로 비활성화 가능; 런처 복구를 위해 gbdev init를 다시 실행하십시오 — 독립 실행형 gbdev install은 봇 런처를 생성하지 않습니다).
   • 이후 start / run start / pipeline start(그리고 이를 포함하는 모든 init/run JSON)가 반환한 실제 attach_hint를 선호하십시오. tmux attach -t gbdev는 기본 홈에만 적용됩니다. 기본이 아닌 홈은 세션 gbdev-<h6>를 사용합니다 — 항상 attach_hint를 그대로 인용하고 추측하지 마십시오. 패널, 창 또는 터미널을 닫거나 다시 열어도 실행 중인 작업에는 영향을 미치지 않습니다.
   • home_conflict / launcher_conflict: 중단하고 사용자에게 보고하십시오; 자동 삭제 또는 이름 변경하지 마십시오.
   • path_hint는 사용자에게만 전달됩니다; 셸 rc를 절대 수정하지 마십시오.

0.B 알림 초기화 (M5 — 0.A 이후에만)

아래의 모든 알림 호출에는 0.A의 command를 사용하십시오.

1. <command> doctor --json 및 <command> notify status --json. 알림 외 의사 실패는 평소처럼 처리하십시오.
2. result.init.state=verified이고, init.verified_by_bot이 이 봇의 레이블과 같고, 이 봇의 메모리에 해당 home_id가 기록된 경우에만 완료, 침묵 유지. enabled=true 또는 HTTP 2xx만으로는 완료가 아닙니다.
3. verified_by_bot가 다른 봇의 레이블이면, 다시 바인딩하거나 다시 초기화하지 마십시오. 폴링으로 평소처럼 작업을 분배하고 사용자에게 이 홈을 소유한 봇 레이블을 알려주십시오. 규칙: 봇당 하나의 웹훅 루틴, GBDEV_HOME당 하나의 봇; 자체 웨이크업이 필요한 두 번째 봇은 자체 GBDEV_HOME을 사용합니다.
4. 그 외의 경우 init.missing_step을 따라 진행하십시오:
   • 아직 웹훅 루틴 없음: 루틴 프롬프트(아래, 봇 레이블과 신뢰하는 홈 입력)를 사용하여 트리거 webhook으로 이 봇의 자체 루틴을 생성하십시오. 기존 루틴을 재사용하십시오; 중복을 절대 생성하지 마십시오. 사용자에게 루틴 상태의 루틴 패널 필드 링크(웹훅 URL, 웹훅 키, 인증 헤더)를 보내십시오.
   • setup_secret(사용자의 유일한 수동 단계): 사용자에게 패널에서 URL과 키를 복사하여 터미널에서 <command> notify setup을 실행하도록 요청하십시오 — <command>는 init의 result.command에서 얻은 절대 봇 런처 경로입니다(예: ~/.gbdev-cli/bin/gbdev-<label> notify setup). legacy_default(기본 홈)인 경우에만 gbdev notify setup을 직접 사용하십시오. 입력이 에코되지 않습니다. 그런 다음 완료되었다고 알리십시오. 봇은 직접 setup을 실행하지 않으며 키를 요청하거나 보지 않습니다.
   • enable / key name: <command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json은 컨트롤러 웹훅 패널의 인증 헤더와 일치합니다. 패널에 다른 내용이 표시되면 패널을 따르십시오; 추측하지 마십시오.
   • run_test: <command> notify test --json. delivered=true이고 http_status가 2xx이면 플랫폼이 수락했음을 의미합니다. awaiting_ack=true는 깨어난 루틴이 아직 확인해야 함을 의미합니다. 실패는 오류 notify_unavailable입니다. error.details.class를 읽으십시오(예: secret = 아직 구성되지 않았거나 활성화되지 않음).
   • await_ack: 깨어난 루틴이 <command> notify ack <notice_id> --bot <bot_label> --json을 실행합니다; 발신자는 대신 확인하지 않습니다. 최대 2분 동안 15초마다 notify status를 확인하십시오. 시간 초과 시 사용자에게 플랫폼이 테스트를 수락했지만 루틴이 확인하지 않았다고 알리고 루틴이 활성화되었는지 확인하십시오.
5. init.state=verified이고 이 봇에 바인딩되면 메모리에 home_id + 봇 레이블을 기록하고 사용자에게 한 번 알리십시오: 通知已接通. 새 setup(새 키)은 확인을 무효화합니다. 테스트를 다시 수행한 다음 확인하십시오.
6. 알림 초기화가 완료되지 않은 경우, 어쨌든 작업을 분배하고 폴링으로 대체하며 누락된 단계를 평이한 말로 설명하십시오.

1. 확인 및 시작

요청 JSON에는 stdin을 선호하십시오(--request -). 사용자나 도구가 이미 준비한 경우 파일 경로도 괜찮습니다.

<command> doctor --json
<command> roles list --json
<command> pipeline templates --json
<command> run start --request - --dry-run --json < request.json
<command> run start --request - --json < request.json
# 이미 준비된 경우 선택적 파일 형식:
# <command> run start --request request.json --json

먼저 ok:false인 의사 점검 결과를 보고하십시오. 사용자가 최대 세 개의 명확한 하위 작업을 제공한 경우 decompose: provided를 사용하고, 그렇지 않으면 플래너를 사용하십시오. result.run_id를 기록하고 사용자에게 레인, 예산 및 통합 브랜치를 알리십시오. 단일 작업(<command> start)과 파이프라인(<command> pipeline start)도 동일하게 작동합니다. 참고: --dry-run 결과도 ID와 queued를 출력합니다. 아무것도 시작하지 않았습니다.

모든 시작 결과는 result.notify={enabled, reason, endpoint_host}를 전달합니다. reason이 null이 아니면 일시 중지되었거나 중단되었음을 의미합니다. 초기화 정보가 없으므로 notify status로 확인하십시오.

2. 항상 사용자에게 시청 방법을 알리십시오

매번 성공적인 run start, pipeline start 또는 start 후에 result.dashboard를 읽으십시오. attach_hint, watch_hint 및 window를 그대로 가져오십시오. 명령을 직접 구성하지 마십시오.

watch_hint가 gbdev 로 시작하고 홈이 기본이 아닌 경우, 사용자에게 전달할 때 첫 번째 gbdev를 봇 런처 이름(예: gbdev-example-dev)으로 바꾸십시오. attach_hint를 그대로 전달하십시오(기본 홈 세션 gbdev; 기본이 아닌 경우 gbdev-<h6>).

enabled=true, reason=null이고 attach_hint가 비어 있지 않으면 (사용자 언어로) 말하십시오:

想实时看进度的话，在 Mac 终端执行 <attach_hint>，切到名为 <window> 的窗口即可（默认按 Ctrl-b 再按 d 退出观看）。随时关掉终端、关掉某个窗格，甚至把整个 tmux 会话关掉都没关系，不会影响任务；下次有进展时面板会自动恢复，也可以让我执行 gbdev dashboard ensure 立刻恢复。不用 tmux 的话，<watch_hint> 能看到同样的内容。

그렇지 않으면 말하십시오:

这台机器上的 tmux 观看面板没有开启（原因：<reason 的中文说明>），不影响任务。想看实时进度可以在终端执行 <watch_hint>。

이유 의미: disabled_by_config 구성이 꺼짐; disabled_by_env GBDEV_DASHBOARD=0; tmux_not_found tmux 없음; tmux_too_old tmux < 3.2; tmux_error / tmux_timeout 이번에 tmux 실패; unsafe_argv 경로에 지원되지 않는 문자; foreign_session gbdev가 생성하지 않은 동일 이름의 세션으로 gbdev가 절대 건드리지 않음; lock_busy 다른 프로세스가 대시보드를 업데이트 중입니다.

대시보드를 사용할 수 없기 때문에 작업 흐름을 재시도하거나 변경하지 마십시오.

3. 진행 상황 추적

읽기 전용 인벤토리의 경우 이 봇의 자체 홈에서 <command> run list --active, <command> pipeline list --active 또는 <command> list --active를 사용하십시오. 모두 --state <s>(반복 또는 쉼표로 구분), --limit <1..500>(기본값 20) 및 --json을 지원합니다. 파이프라인 목록은 --standalone도 지원합니다. 작업 목록은 기본적으로 대체된 이전 시도를 숨깁니다. --all은 작업 정보를 변경하지 않고 포함합니다. gbdev status --all은 ID 없이 텍스트 목록에만 사용됩니다. status는 --all을 --json 또는 ID와 결합할 수 없습니다. JSON 인벤토리의 경우 gbdev list --all --json을 사용하십시오. status JSON 배열 및 ID가 있는 단일 동작은 --all 없이 변경되지 않습니다. needs_input/blocked/failed/timeout/cancelled 작업은 동일한 파이프라인 단계 인스턴스의 이후 시도 또는 터미널 상위 파이프라인/소유 실행(파이프라인이 아직 터미널이 아닌 경우에도 터미널 실행으로 충분함)에 의해 대체됩니다. 손상된 시도 항목은 이후 시도 확인만 건너뛰고 터미널 상위 증거는 건너뛰지 않습니다. status는 상태를 조정하고 쓸 수 있으므로 최신성/복구를 확인할 때 특정 단위에 사용하고 읽기 전용 인벤토리에는 사용하지 마십시오. 목록의 오래된 플래그는 status 사용을 제안할 뿐입니다. 아무것도 복구하지 않습니다.

웹훅 경로(이 봇에 대해 0단계 확인됨, notify.reason=null): 10분 폴링 루틴을 생성하지 마십시오. 사용자에게 말하십시오: 完成或需要你决定时我会自动收到通知。 웹훅 루틴이 후속 작업을 수행합니다.

시간별 주중 폴백(선택 사항, 운영자가 구성한 정책; 레시피 §11.3과 동일한 수명 주기 규칙): 운영자가 구성한 주중, 시간대 및 근무 시간 내에서 시간당 한 번(선택적 예시 정책). 메모리에 활성 실행/파이프라인/작업 단위가 있는 동안에만 Mac 명령을 실행하십시오. 활성 단위가 없으면 자동으로 종료하십시오. 순서: <command> notify status --json → <command> notify flush --wait-ms 20000 --json → 각 활성 단위의 상태. 현재 주의 created_at이 1시간보다 오래된 경우 ...

[번역 잘림]