kaiwu-best-practices

name	kaiwu-best-practices
description	用開物 Kaiwu 建構正式整合的最佳實踐 — 額度管理、查詢技巧、繁簡策略、錯誤處理、何時用 search vs extract。要把開物接進 agent / 應用前先讀這個。Reference for production-ready Kaiwu integrations.

kaiwu best practices

把開物 Kaiwu 接進正式 agent / 應用的最佳實踐。要做整合，這是最快的入門。

1. 選對工具

你要做的事	用
找資訊、還沒有 URL	kw search
快速一般查詢	kw search --depth basic（預設，1 額度）
需要精確事實 / 原文摘要	kw search --depth advanced（2 額度）
要一段可引用的綜合答案	kw search --answer
已有 URL、要讀全文	kw extract
從多源只挑相關段落	kw extract --query "..."

省額度原則：先 basic 搜尋拿到候選 URL，真正需要全文時才對少數 URL 用 extract，比每次都 advanced 划算。

2. 查詢撰寫

• 用「搜尋關鍵詞」思維，不要寫一整段 prompt。控制在 400 字內。
• 複雜問題拆成子查詢，分別搜尋再彙整。
• 善用繁簡：開物會自動互查，但若目標是中國來源，明確 --lang zh-CN 效果更好；台灣在地議題用 --lang zh-TW。
• 時效性問題加 --time-range week（或 day/month/year），避免拿到過期資訊。

3. 額度管理

• 程式流程開始前先 kw credits --json 確認餘額。
• 預期成本：search basic=1、advanced=2、+answer=+1；extract=每成功 URL 1、+query=+1。
• 遇到 HTTP 429（額度不足），回應 body 會帶 credits_needed 與 credits_remaining，據此降級（例如改 basic、減少 max-results）。

4. 錯誤處理

狀態	意義	建議
401	金鑰無效 / 缺失	檢查 KAIWU_API_KEY
429	額度不足	降級或等重置
502	搜尋引擎暫時無法使用	退避重試
extract status: failed	該 URL 抓取失敗（反爬蟲 / 逾時）	該 URL 不計費；改用 search --depth advanced 取摘要

extract 是逐 URL 回報成功/失敗的，永遠檢查每筆 status，別假設全部成功。

5. agent 整合建議

• 解析輸出一律加 --json，不要 parse 人類可讀格式。
• 大量任務用環境變數 KAIWU_API_KEY，不要把金鑰寫進程式碼或 commit。
• 需要可重現時用 -o file.json 落地結果。
• 串接管線：search --json → 取 results[].url → extract --json --query。

6. 中文世界的特性

• 開物聚合 Google / DuckDuckGo / Brave，不經百度/搜狗，因此沒有來源端審查。
• 繁簡雙語原生，適合台灣、香港、星馬華語圈與兩岸議題。
• 資料路徑在台灣，對東亞/東南亞低延遲、對數據主權敏感的團隊友善。

參見

• kaiwu-cli — 安裝與認證
• kaiwu-search · kaiwu-extract · kaiwu-credits