Human 도구
Human 도구는 리뷰어가 리뷰하는 동안 실행하도록 미리 선언해 둔 도구입니다. 직접 선언한 명령일 수도 있고,
내장 도구(read, list, section, help, open, graph)일 수도 있습니다.
선언 예는 Human 리뷰에 있습니다. open과 graph는 프로그램을
실행하고, 나머지는 출력을 보여 줍니다. 이 아래에서는 명령 도구를 설명합니다.
리뷰어는 Agent 도구와 마찬가지로 명령 도구를 <operation>_<artifactId>라는 이름으로 씁니다. 이 이름은
eval 범위 안에서 겹치지 않아야 합니다. 예를 들어 Artifact b_c의 작업 a와 Artifact c의 작업 a_b는 둘 다
a_b_c가 됩니다. 이름이 겹치면 Artifact tool names collide: a_b_c 오류와 함께 리뷰의 도구를 쓸 수
없습니다. 작업이나 Artifact의 이름을 바꾸면 됩니다.
인자
인자는 고정된 목록입니다. 자리 표시자는 선언한 Artifact의 폴더나 파일을 가리키는
{artifactPath}와 다른 Artifact를 가리키는 {name}뿐입니다. 폴더 참조에는
{spec}/README.md처럼 경로를 붙일 수 있지만 파일 참조에는 붙일 수 없습니다. 둘 다 --flag=
형태 안에서도 쓸 수 있습니다. 그 밖의 중괄호 형태는 프로젝트를 읽을 때 오류가 됩니다.
도구는 eval의 리뷰 범위에 포함된 Artifact만 살펴봅니다. 의존성을 더하거나 eval 범위 밖의 Artifact에 접근할 수 없습니다. 범위 밖의 Artifact, 존재하지 않는 입력, 심볼릭 링크를 지정하면 호출할 때마다 명령을 실행하기 전에 도구 호출이 실패합니다.
실행
프로그램은 프로그램 찾기에서 설명한 대로 찾습니다. 셸을
거치지 않으며, 명령은 선언한 Artifact의 폴더(파일 Artifact라면 들어 있는 폴더)에서 실행됩니다.
명령에는 리뷰어의 환경 전체(HOME, 디스플레이, XDG 설정, ARTIFACTIZE_* 등)가 그대로 전달되며, 별도의 임시 폴더는
주어지지 않습니다. 리뷰어의 권한과 그 환경에 있는 자격 증명으로 실행되므로 신뢰하는 명령만
선언하세요.
명령 도구는 두 가지 방식 중 하나로 실행됩니다.
output방식에서는 명령이 끝난 뒤 결과가 나오며, 기본 제한 시간은 120000ms(timeout_ms)입니다. 각 줄은 출력되는 즉시 Tool log에 표시됩니다. 결과에는 stdout과 stderr가 각각 최대 64 KiB까지 담기며, 잘린 곳에는 표시가 붙습니다. 0이 아닌 종료 코드면 결과가 오류로 표시되고 종료 상태가 나옵니다.launch방식에서는 프로그램을 시작하자마자 호출이 끝납니다. 편집기나 뷰어를 열 때 씁니다. 리뷰 중에는 프로그램이 끝날 때까지 출력이 Tool log에 나옵니다. 프로그램은 리뷰를 닫거나 artifactize가 종료된 뒤에도 계속 실행되며,timeout_ms는 적용되지 않으니 리뷰어가 직접 닫아야 합니다.request tool과artifactize tools check는 그 출력을 보여 주지 않습니다. 프로그램을 시작했다고 판정이 내려지지는 않습니다.
Tool log
도구의 stdout과 stderr는 리뷰어의 Tool log에 실시간으로 나옵니다. 그래서 도구가 사용자의
선택 내용, 측정값, 저장한 파일 등의 정보를 출력하면 리뷰어가 이를 결과에 복사할 수 있습니다.
로그는 실행마다 ▶ HH:MM:SS · operation · Artifact를 보여 주고, 이어서 출력 줄(stderr는
빨간색), 마지막에 ■ exit CODE(또는 launched, done, cancelled, timed out,
error: …)를 보여 줍니다. 내장 도구의 텍스트는 끝날 때 나오고 ■ done으로 끝납니다. open은
파일을 기본 애플리케이션으로 열고 ■ launched로 끝납니다. graph는 뷰어가 끝날 때까지
그 출력을 기록합니다. 한 번 실행할 때 최대 1 MiB의 출력을 보여 주고, 나머지 출력은 생략했다고 알립니다. 4096바이트가 넘는 줄은 나눠서 보여 줍니다. 로그는 리뷰가 열려 있는 동안만 유지되며, 어디에도
저장되지 않습니다.
데스크톱 앱은 리뷰가 아니어도 Artifact의 Human 도구를 Detail에 보여 줍니다. 도구를 클릭하면 해당 브랜치 워크트리의 현재 상태를 기준으로 바로 실행합니다. 요청도, 담당 지정도, fingerprint 확인도 없고, 증거로 기록되는 것도 없습니다. 출력 줄은 그 Artifact의 Tool log에 기록되며, 이 로그는 앱이 실행되는 동안 남습니다.
리뷰 중에
요청을 맡은 리뷰어만 그 도구를 실행할 수 있습니다. Human 리뷰를 보세요.
도구는 요청과 함께 기록된 선언대로 실행됩니다. 그 뒤로 eval의 범위나 선언이 바뀌었으면 기록된 대로는
더 리뷰할 수 없으므로, 도구를 실행하지 않고 요청을 ERROR(INPUT_CHANGED)로 끝냅니다. 다음에 verify를
실행하면 새 선언으로 리뷰를 다시 요청합니다. 결과를 제출할 때, 그리고 Review나 데스크톱 앱에서 대기 중인
요청을 열 때도 똑같이 확인하고 같은 방식으로 끝냅니다. 도구 오류가 나면 문제를 고친 뒤 다시 시도하세요. 도구 오류는 판정이 아니며, 도구 실행은 결과와 함께 기록되지 않습니다. 도구를 실행하기 전에 eval이 리뷰하는
Artifact의 선언을 다시 읽습니다. 그중 파일 Artifact의 파일이 없는 경우처럼 선언을 읽을 수 없으면 도구를
실행하지 않으며, 요청은 대기 상태로 남으므로 파일을 되돌린 뒤 다시 시도하면 됩니다. 그 Artifact
eval이 읽지 않는 하위 부분이라도 선언을 읽을 수 없으면 도구를 실행하지 못할 수 있습니다.
프로젝트의 다른 곳에 설정 오류가 있어도 Human 작업을 진행하지 못할 수 있습니다. 보고된 선언을
고치고 다시 시도하세요. 그다음 리뷰한 파일을 확인합니다.
fingerprint가 바뀌었거나 계산할 수 없으면 도구를 실행하지 않고 요청을 ERROR(INPUT_CHANGED나
FINGERPRINT_RECHECK_FAILED)로 끝내며, 다음에 verify를 실행하면 리뷰를 다시 요청합니다.
request list는 저장된 요청을 모두(대기 중, 맡음, 확정됨) 보여 주며, --run으로 Run 하나만
볼 수도 있습니다. 요청, Run, eval ID와 상태, 리뷰어가 나옵니다. --json과 request show에는
저장된 이력, 현재 담당 정보, 재사용한 실행, eval 정의(정의를 기록하기 전에 저장된 Run이면 null)가
더해집니다. 이 명령은 저장소 없이도 동작하며 아무것도 실행하지 않습니다. run show와 verify --wait --json은
Run을 요약합니다. 상태별 개수, 종류별로 실행하고 재사용한 요청, 걸린 시간, 시도, 사용량이
나옵니다. provider가 보고하지 않은 사용량은 0으로 보여 주지 않습니다.