내장 도구
zqagent에는 21개 도구가 내장되어 있으며 다음과 같이 분류됩니다(도구 이름은 승인 카드에 표시됩니다):
| 분류 | 도구 |
|---|---|
| 파일 | read_file, write_file, replace_in_file, list_files, grep |
| Shell | run_shell(같은 shell 세션에서 연속 실행. Auto 모드에서는 허용 목록 명령 자동 허용), shell_task_output, shell_task_kill(run_shell의 백그라운드 작업 관리) |
| 네트워크 | web_search, web_fetch |
| Git | git_log, git_status, git_diff(읽기 전용) |
| 패치 | apply_patch, apply_unified_diff |
| 협업 | ask_user, propose_plan, request_directory |
| 작업 | todo_write(진행 상태 공유) |
| 서브에이전트 | explore(읽기 전용 조사 서브에이전트) |
| 미디어 | media(ffmpeg / ffprobe 래퍼: 메타데이터 조회, 자르기, 트랜스코딩, 오디오 추출, 프레임 추출, 썸네일, 압축) |
파일
read_file— 파일 내용 읽기write_file— 파일 쓰기(새로 만들거나 덮어쓰기)replace_in_file— 정확한 문자열 치환. 부분 수정에 적합list_files— 디렉터리 구조 나열grep— 정규식으로 파일 내용 검색
Shell
run_shell은 같은 shell 세션에서 명령을 연속 실행합니다. 명령 허용 목록은 Auto 모드에서 자동 허용되며 대화형 모드에서는 특정 명령에 C로 항상 허용할 수 있습니다(도구 전체를 허용하는 것보다 안전).
긴 명령은 run_in_background로 백그라운드에 보낼 수 있습니다. 반환된 task_id로 shell_task_output을 사용해 누적 출력과 실행 상태를 확인하고 shell_task_kill로 종료할 수 있습니다(자식 프로세스 트리 포함).
어떤 shell을 쓸지는 실행 시 자동 선택됩니다: macOS / Linux는 Node 기본 /bin/sh(동작 동일). Windows는 POSIX 스타일 shell을 우선하고(같은 디렉터리의 BusyBox-w32 → Git Bash → PowerShell), 없으면 cmd.exe로 폴백하며 선택한 shell을 도구 설명에 적어 모델이 명령 스타일을 조정하도록 합니다. ZQAGENT_SHELL(키워드 또는 실행 파일 경로)과 ZQAGENT_BUSYBOX로 재정의할 수 있습니다. 자세히는 README의 '멀티 플랫폼 패키지 배포 → Windows의 shell과 검색'을 참고하세요.
grep 도구는 내장 / 설치된 ripgrep을 우선 사용하고 없으면 내장 순수 Node 스캐너로 폴백합니다 (완전한 JS 정규식 지원). Windows 단독 환경에서도 바로 사용할 수 있습니다.
Windows 전통 콘솔(cmd.exe/conhost)이 emoji와 Unicode 표 테두리를 렌더링하지 못하면 CLI는 자동으로 ASCII 표기로 전환합니다(✅→[OK], ❌→[x], ⚠️→[!] …). Windows Terminal / VS Code 같은 최신 터미널에서는 emoji를 유지합니다. ZQAGENT_EMOJI=1/0으로 강제할 수 있습니다.
네트워크
web_search— 웹 검색web_fetch— 웹 페이지 내용 가져오기
Git(읽기 전용)
git_log / git_status / git_diff는 저장소 기록과 상태를 읽기 전용으로 확인합니다.
패치
apply_patch / apply_unified_diff는 코드 패치를 적용하며 일괄 수정에 적합합니다.
협업
ask_user— 사용자에게 질문propose_plan— 계획 제안 제출request_directory— 작업 디렉터리 요청
작업과 서브에이전트
todo_write— 공유 작업 진행 관리explore— 읽기 전용 조사 서브에이전트 시작
미디어
media는 로컬 ffmpeg / ffprobe를 래핑해 하나의 도구로 메타데이터 조회(probe), 자르기, 트랜스코딩, 오디오 추출, 프레임 추출, 썸네일, 압축을 처리합니다. shell을 거칠 필요가 없습니다.
ffmpeg는 네 단계로 찾습니다: ① 환경 변수 ZQAGENT_FFMPEG / ZQAGENT_FFPROBE → ② 워크스페이스 <workspace>/.agent/bin → ③ 단일 파일 내장 리소스 / PATH → ④ 찾지 못하면 구조화된 안내를 반환 (op="setup"으로 공식 정적 빌드 자동 다운로드, run_shell 설치 명령, 수동 설치와 환경 변수 작성법 포함). 각 플랫폼의 설치 명령과 라이선스 안내는 반환값의 install_commands / notes에 있습니다.
확인과 비활성화
CLI에서 /tools를 입력하면 모든 도구(출처, 위험, 비활성 상태 포함)를 나열합니다. /tool disable <name>으로 일시 비활성화하고 /tool enable <name>으로 다시 활성화할 수 있습니다.