跳至主要内容

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

Harness 的工具箱

🎯 一句話:harness 裡有 13 個命令列工具,分三類(機密與漏洞、資料與文件、媒體),讓代理人把「掃描、轉檔、查詢」這類有標準答案的事交給程式,自己只做判斷。

為什麼是 CLI:模型擅長判斷與組裝,不擅長逐位元精確的事(掃出每一個外洩的金鑰、把 PDF 轉成逐頁圖、把簡體字全部換成繁體)。這類事有現成的工具、輸出可重跑驗證,所以寫進 harness 的做法是「讓代理人呼叫工具,再讀結果」。這與 Skills 總覽 歸納的第 2 點一致:確定性的部分寫成腳本。Harness 本身是什麼,見 12|Agent Harness Engineering。

下表的 Homebrew 套件名可直接 brew install。


一、機密與漏洞:提交前、發布前掃一遍​

工具做什麼在 harness 裡的用途安裝
gitleaks掃 git 內容與檔案裡的機密(金鑰、token、密碼)commit 前掃暫存區:gitleaks git --staged -vbrew install gitleaks
trufflehog同樣掃機密,並可實際驗證金鑰是否仍有效push 前掃將要推出的 commit:trufflehog git file://. --since-commit origin/main --only-verified --failbrew 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
yqjq 的 YAML 版(也處理 JSON、XML)讀改 Kubernetes、CI 設定:yq '.spec.replicas' deploy.yamlbrew 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 outbrew install poppler
opencc簡體與繁體轉換(含用語差異)把簡體來源資料轉成臺灣用語:opencc -c s2twp -i in.txt -o out.txtbrew install opencc
graphviz用 dot 描述檔產生圖把關係、流程描述成 .dot,輸出 PNG 或 SVG:dot -Tpng in.dot -o out.pngbrew install graphviz

duckdb 與 jq 在 harness 裡的價值是「省 context」:讓程式先篩出需要的幾列,代理人只讀結果。

三、媒體:下載與轉文字​

工具做什麼在 harness 裡的用途安裝
yt-dlp下載線上影音與其中繼資料取得影片或音檔,供後續轉文字與整理brew install yt-dlp
openai-whisperOpenAI 開源的語音轉文字(Python 版)逐字稿:whisper audio.mp3 --language zh --model smallbrew 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 只下載你有權使用的內容。


怎麼把工具交給代理人​

  1. 先確認裝了:which gitleaks trufflehog trivy jq yq duckdb pandoc pdftotext opencc dot yt-dlp whisper-cli,缺哪個補哪個
  2. 在規則檔寫「什麼時機用哪個」:例如「commit 前跑 gitleaks」,工具才會被穩定使用
  3. 能強制就用 hook 強制:例如 push 前自動掃機密,不靠代理人記得
  4. 有副作用的(下載)要先講範圍:只下載有權使用的內容