內建工具
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> 重新啟用。