13|Harness 的工具箱:代理人常用的 CLI

🎯 一句話:harness 裡有 13 個命令列工具,分三類(機密與漏洞、資料與文件、媒體),讓代理人把「掃描、轉檔、查詢」這類有標準答案的事交給程式,自己只做判斷。
為什麼是 CLI:模型擅長判斷與組裝,不擅長逐位元精確的事(掃出每一個外洩的金鑰、把 PDF 轉成逐頁圖、把簡體字全部換成繁體)。這類事有現成的工具、輸出可重跑驗證,所以寫進 harness 的做法是「讓代理人呼叫工具,再讀結果」。這與 Skills 總覽 歸納的第 2 點一致:確定性的部分寫成腳本。Harness 本身是什麼,見 12|Agent Harness Engineering。
下表的 Homebrew 套件名可直接 brew install。
一、機密與漏洞:提交前、發布前掃一遍
| 工具 | 做什麼 | 在 harness 裡的用途 | 安裝 |
|---|---|---|---|
| gitleaks | 掃 git 內容與檔案裡的機密(金鑰、token、密碼) | commit 前掃暫存區:gitleaks git --staged -v | brew install gitleaks |
| trufflehog | 同樣掃機密,並可實際驗證金鑰是否仍有效 | push 前掃將要推出的 commit:trufflehog git file://. --since-commit origin/main --only-verified --fail | brew install trufflehog |
| trivy | 掃容器映像、相依套件、基礎設施即程式碼(IaC)的已知漏洞與錯誤設定 | trivy fs . 掃專案、trivy image <映像> 掃映像、trivy config . 掃設定檔 | brew install trivy |
兩個機密掃描器並用,是因為偵測方式不同:gitleaks 靠規則與熵值,快、適合每次 commit;trufflehog 能向服務端驗證,適合 push 前少誤報。掃到東西時,代理人要先撤掉機密再繼續,不是把它忽略。
二、資料與文件:查詢與轉換
| 工具 | 做什麼 | 在 harness 裡的用途 | 安裝 |
|---|---|---|---|
| jq | 用查詢語法處理 JSON | 從 API 回應或日誌取出欄位:jq '.items[].name' | brew install jq |
| yq | jq 的 YAML 版(也處理 JSON、XML) | 讀改 Kubernetes、CI 設定:yq '.spec.replicas' deploy.yaml | brew install yq |
| duckdb | 直接對 CSV、Parquet、JSON 下 SQL,不必先匯入資料庫 | 大檔案先查再讀,不把整份塞進 context:duckdb -c "select count(*) from 'data.csv'" | brew install duckdb |
| pandoc | 文件格式互轉(Markdown、HTML、docx…) | 當中間轉換,例如把 Markdown 轉成 HTML 片段。要交付的 Word 不直接用 pandoc 產出,另走 html2docx skill 處理封面、字型與頁首頁尾 | brew install pandoc |
| poppler | 一組 PDF 工具:pdftotext 轉文字、pdftoppm 轉成逐頁圖片 | 讀 PDF 內容、把某幾頁轉成圖給模型看:pdftoppm -png -r 150 in.pdf out | brew install poppler |
| opencc | 簡體與繁體轉換(含用語差異) | 把簡體來源資料轉成臺灣用語:opencc -c s2twp -i in.txt -o out.txt | brew install opencc |
| graphviz | 用 dot 描述檔產生圖 | 把關係、流程描述成 .dot,輸出 PNG 或 SVG:dot -Tpng in.dot -o out.png | brew install graphviz |
duckdb 與 jq 在 harness 裡的價值是「省 context」:讓程式先篩出需要的幾列,代理人只讀結果。
三、媒體:下載與轉文字
| 工具 | 做什麼 | 在 harness 裡的用途 | 安裝 |
|---|---|---|---|
| yt-dlp | 下載線上影音與其中繼資料 | 取得影片或音檔,供後續轉文字與整理 | brew install yt-dlp |
| openai-whisper | OpenAI 開源的語音轉文字(Python 版) | 逐字稿:whisper audio.mp3 --language zh --model small | brew install openai-whisper |
| whisper.cpp | 同一模型的 C/C++ 版,本機執行快、依賴少 | whisper-cli -m <模型檔> -f audio.wav(輸入建議用 16 kHz wav,可先用 ffmpeg 轉檔) | brew install whisper-cpp |
兩個 whisper 擇一即可:Python 版安裝簡單,C++ 版速度與資源占用較好。yt-dlp 只下載你有權使用的內容。
怎麼把工具交給代理人
- 先確認裝了:
which gitleaks trufflehog trivy jq yq duckdb pandoc pdftotext opencc dot yt-dlp whisper-cli,缺哪個補哪個 - 在規則檔寫「什麼時機用哪個」:例如「commit 前跑 gitleaks」,工具才會被穩定使用
- 能強制就用 hook 強制:例如 push 前自動掃機密,不靠代理人記得
- 有副作用的(下載)要先講範圍:只下載有權使用的內容