Human 리뷰
Human eval은 사람에게 리뷰를 요청하고 GREEN이나 RED 판정을 받습니다. 리뷰어는 대기 중인 요청을 맡고,
선언한 Human 도구를 실행하고, artifactize request 명령이나 artifactize review 터미널 UI로
판정을 제출합니다.
사람은 Artifact의 자동 eval을 이미 통과한 것만 승인합니다. 상위 승인이 남아 있어
PROVISIONAL로 보이는 GREEN 판정도 통과한 것으로 칩니다. 자동 eval이 아직 실행 중이면
Human eval은 대기 상태(WAIT_DEPENDENCY)로 남고, 그중 하나가 RED나 ERROR면 BLOCKED가 되며 사유에 해당 eval이 표시됩니다. Human 승인을
보세요.
eval 준비가 끝나면 artifactize는 사람이 판정해야 하는 요청을 DEFERRED 상태로
기록합니다. 이 요청은 다른 작업을 막지 않습니다. 사람이 판정을 제출할 때까지는 Run의 --jobs 실행 자리도,
--max-executions 예산도 쓰지 않으며, 그 예산이 0이어도 마찬가지입니다. 그 승인에 의존하는 eval은 바로
실행하며, 그 eval의 GREEN 결과는 승인이 GREEN이 될 때까지 PROVISIONAL로 표시되고, eval 자체의 RED나 ERROR는
그대로 표시됩니다. 다른 작업이 아직 실행 중일 수 있으니, 최종 상태를
리뷰하려면 그 작업이 끝날 때까지 기다리세요. 모든 승인은 review, Monitor, 데스크톱, 요청 목록에 나오고, 담당
지정과 해제, 도구 실행, 판정 제출 때 Human 권한을 확인합니다. 막힌 승인은 사람에게 보여 주지 않습니다. 진행 상황을 지켜보거나 터미널을 닫아도 승인이나 거부가 제출되지는 않습니다. 제출, 지켜보기, 직접 취소는
Run 수명 주기에서 설명합니다.
요청을 맡은(claim) 리뷰어가 담당자가 됩니다. 이와 별개로, 승인이 필요한 다른 Run은
입력과 프로필이 같으면 체크아웃 위치와 관계없이 새 요청을 만들지 않고 이미 대기 중인 리뷰에
합류합니다. 이렇게 합류한 요청을 팔로워라고 합니다. 팔로워를 통해 Human 작업을 해도 결과는 원래 요청이 저장된 저장소의 해당 요청에 반영됩니다. --force는 합류하지 않고 새 승인을 요청하지만, 새 요청에서도 사람이 먼저
맡아야 도구를 실행하거나 판정을 제출할 수 있습니다.
리뷰한 입력이 그대로면 기존 승인 결과를 기본적으로 재사용합니다. 이후 verify는 제출된
결과를 재사용하고 그 결과를 쓰는 eval을 리뷰할 수 있습니다. 대상이나 포함한 의존성에
fingerprint = false가 있으면 승인은 현재 Run에만 적용되므로, 다음 Run에서는 사람이
다시 판정해야 합니다. Run의 검증 결과는 그 시점에 확보된 결과를 기준으로 확정되며, 나중에 승인을 제출해도 지난 Run의
판정은 바뀌지 않습니다.
아래 명령 표기에서 대괄호로 묶은 부분은 생략할 수 있으며, 입력할 때 대괄호는 빼세요. 대문자로 쓴
부분은 바꿔 넣을 값입니다. REQUEST_ID에는 request list가 출력한 실제 요청 ID를 넣고, NAME에는
리뷰어 이름을 넣으세요.
artifactize verify --all --wait
# In another terminal, using the same state directory:
artifactize request list [--run RUN_ID] [--json]
artifactize request show REQUEST_ID
artifactize request claim REQUEST_ID [--reviewer NAME]
artifactize request unclaim REQUEST_ID [--reviewer NAME] # release without a verdict
artifactize request tool REQUEST_ID inspect_child [--reviewer NAME]
artifactize request submit REQUEST_ID --verdict GREEN --fields '{"approved":true}'
# Alternatively: --fields-file /path/to/fields.json
# Or claim, run tools and submit in a terminal UI (see Review):
artifactize review [REQUEST_ID]
이 명령들의 옵션, 출력, 종료 코드는 모두 Human 요청에 있습니다.
Run의 종료 코드를 보면 지켜보기만 중단한 경우, Run을 직접 취소한 경우,
최종 검증 요건을 충족하지 못한 경우를 구분할 수 있습니다. verify --reuse-only human은 Human 요청을 기록하지 않으며 결과가 나올 때까지 대기하지도 않습니다. CI에서는
Human eval이 기존 승인을 재사용하고, 재사용할 승인이 없으면 실행되지 않습니다.
request list와 request show의 필드, Run 요약은 레퍼런스에
있습니다.
승인과 Run
진행 중인 Run은 제출되지 않은 승인이 하나라도 있는 동안 WAITING_HUMAN입니다. 남은 작업이 승인뿐이면
리뷰어가 그중 하나를 맡고 있는 동안, 그리고 승인 유예 시간(따로
바꾸지 않았다면 2분) 동안 Run은 종료되지 않습니다. 그 시간 안에 승인을 맡아 제출하면 Run은 그 결과에 따라 GREEN이나
RED로 끝납니다. 아무도 맡지 않으면 Run은 YELLOW(종료 코드 5)로 끝나며, 승인만 남았다는 뜻입니다. 그 뒤에도
승인을 제출할 수 있고, 다음 verify가 그 결과를 재사용합니다. 자세한 내용은
승인과 Run 종료에 있습니다. 이 재사용에는 fingerprint가 필요하므로
fingerprint = false면 재사용하지 않습니다.
같은 워크트리에서 같은 eval에 더 새로운 요청이 오면, 재사용 키가 다른 이전 DEFERRED 승인은 끝나고 Review에서 사라집니다. 이전 승인이 종료되는 조건과 리뷰 합류 방식, Run이 끝난 뒤 승인을 제출하는 방법은 Run 규칙을 보세요.
CI 설정은 대기 중인 승인을 병합 게이트에서 빼기를 보세요.
Human 도구
리뷰어가 쓸 도구는 views.human_tools 아래에 도구마다 이름을 붙여 적으세요. 도구는
리뷰어가 실행하며, 실행할 때 임의의 인자를 덧붙일 수는 없습니다. 내장 도구는 Linux, macOS, Windows에서
똑같이 동작합니다. open은 파일, 폴더, http(s) URL을 데스크톱의 기본 애플리케이션으로 열고,
graph는 현재 프로젝트 그래프 뷰어를 실행합니다. read, list, section, help는 터미널에
텍스트를 출력합니다.
[views.human_tools]
open = { description = "Open the review notes of {artifactName}.", builtin = "open", args = ["{artifactPath}/notes.md"] }
notes = { description = "Print the review notes of {artifactName}.", builtin = "read", args = ["{artifactPath}/notes.md"] }
내장 도구는 builtin과 args, 선택 항목인 description을 받습니다. 종류는 도구에 따라
정해집니다. open과 graph는 프로그램 실행용이고, 나머지는 출력 표시용입니다.
명령 도구는 고른 프로그램을 실행합니다. description, kind, command, args는
필수 항목이며, kind는 "launch"나 "output"입니다. timeout_ms(1–2147483647)는
선택 항목입니다. input_schema, 호출할 때 임의로 넘기는 인자, protocol, execution_paths,
metadata, script 래퍼는 받지 않습니다. 설명은 {artifactName}을 포함해 Agent 설명 규칙을
따릅니다.
[views.human_tools]
edit = { description = "Open {artifactName} in VS Code.", kind = "launch", command = "code", args = ["{artifactPath}"] }
도구가 출력하는 내용은 리뷰가 열려 있는 동안 리뷰어의 Tool log에 실시간으로 나오며, 리뷰어가 결과에 복사해 넣을 수 있습니다.
자리 표시자, 실행 파일 찾기, launch와 output 종류는 레퍼런스에
있습니다.
결과 양식
리뷰어는 eval의 pass_schema(GREEN)나 fail_schema(RED)로 만든 양식에 결과를 입력합니다.
텍스트, 숫자, true/false, 선택지, 텍스트 목록, 반복해서 추가할 수 있는 필드 그룹이 있으며, 상수는 미리 채워집니다. Human eval의 스키마에는 이런 형태만 쓸 수 있습니다.
선언 레퍼런스에 지원하는 형태의 목록과 화면 표시 방식이
정리되어 있습니다.