Herramientas integradas
zqagent incluye 21 herramientas, agrupadas así (el nombre aparece en la tarjeta de aprobación):
| Categoría | Herramientas |
|---|---|
| Archivos | read_file, write_file, replace_in_file, list_files, grep |
| Shell | run_shell (ejecuta comandos seguidos en la misma sesión de shell; en modo Auto se permiten los comandos de la lista), shell_task_output, shell_task_kill (gestionan las tareas en segundo plano de run_shell) |
| Red | web_search, web_fetch |
| Git | git_log, git_status, git_diff (solo lectura) |
| Parches | apply_patch, apply_unified_diff |
| Colaboración | ask_user, propose_plan, request_directory |
| Tareas | todo_write (comparte el estado del progreso) |
| Subagente | explore (subagente de investigación de solo lectura) |
| Multimedia | media (envoltorio de ffmpeg / ffprobe: metadatos, recorte, transcodificación, extracción de audio, extracción de fotogramas, miniaturas, compresión) |
Archivos
read_file— leer el contenido de un archivowrite_file— escribir (crear o sobrescribir) un archivoreplace_in_file— sustitución exacta de texto, ideal para cambios localeslist_files— listar la estructura de directoriosgrep— buscar contenido con expresiones regulares
Shell
run_shell ejecuta comandos de forma consecutiva en la misma sesión de shell; la lista de comandos permitidos se autoriza automáticamente en modo Auto y en modo interactivo se puede permitir siempre un comando concreto con C (más seguro que autorizar toda la herramienta).
Los comandos largos pueden ir a segundo plano con run_in_background; con el task_id devuelto, shell_task_output muestra la salida acumulada y el estado, y shell_task_kill lo termina (incluido el árbol de procesos hijos).
El shell lo elige el entorno en tiempo de ejecución: macOS / Linux usan el /bin/sh predeterminado de Node (sin cambios); Windows prefiere un shell estilo POSIX (BusyBox-w32 del mismo directorio → Git Bash → PowerShell) y, si no hay ninguno, recurre a cmd.exe, anotando el shell elegido en la descripción de la herramienta para que el modelo adapte el estilo de los comandos. Se puede sobrescribir con ZQAGENT_SHELL (palabra clave o ruta del ejecutable) y ZQAGENT_BUSYBOX. Consulta «Distribución multiplataforma → shell y búsqueda en Windows» en el README.
La herramienta grep prefiere el ripgrep integrado o instalado y, si falta, recurre al escáner Node integrado (compatible con regex de JS completas), utilizable también en Windows sin más.
Cuando la consola tradicional de Windows (cmd.exe/conhost) no puede representar emoji ni bordes de tabla Unicode, la CLI cambia automáticamente a marcas ASCII (✅→[OK], ❌→[x], ⚠️→[!]…); terminales modernas como Windows Terminal o VS Code mantienen los emoji. Se puede forzar con ZQAGENT_EMOJI=1/0.
Red
web_search— búsqueda webweb_fetch— obtener el contenido de una página web
Git (solo lectura)
git_log / git_status / git_diff consultan el historial y el estado del repositorio en solo lectura.
Parches
apply_patch / apply_unified_diff aplican parches de código, adecuados para cambios masivos.
Colaboración
ask_user— preguntar al usuariopropose_plan— enviar una propuesta de planrequest_directory— solicitar un directorio de trabajo
Tareas y subagentes
todo_write— mantener el progreso compartido de tareasexplore— lanzar un subagente de investigación de solo lectura
Multimedia
media envuelve el ffmpeg / ffprobe local: una sola herramienta cubre metadatos (probe), recorte, transcodificación, extracción de audio, extracción de fotogramas, miniaturas y compresión, sin pasar por el shell.
ffmpeg se localiza en cuatro niveles: ① variables ZQAGENT_FFMPEG / ZQAGENT_FFPROBE → ② <workspace>/.agent/bin del espacio de trabajo → ③ recursos integrados en el binario / PATH → ④ si no se encuentra, devuelve una guía estructurada (con op="setup" para descargar la compilación estática oficial, comandos de instalación por run_shell, instalación manual y variables de entorno). Los comandos de instalación por plataforma y las notas de licencia están en install_commands / notes de la respuesta.
Consultar y desactivar
En la CLI, /tools lista todas las herramientas (origen, riesgo y estado de desactivación), /tool disable <name> desactiva temporalmente y /tool enable <name> vuelve a activar.