内置工具
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> 重新启用。