harvester-query
Specter 的 Harvester 是一個 FastAPI 服務,背後管理兩個 Chroma 集合:
| 集合 | 內容 | API 使用時機 |
|---|---|---|
specter_statutes | 384 條美國機動車輛法規(CA、TX、FL、PA、IL、OH) | 預設 — 任何美國管轄區或一般查詢 |
canada_pi_cases | 340 個真實加拿大個人傷害判例(CanLII,含損害賠償、傷害類型、原告是否勝訴、決定性因素) | 當查詢提及加拿大 / 安大略 / 魁北克 / 多倫多 / ONSC / ONCA / canlii 等,或傳入 ?jurisdiction=Canada 或 ?state=CA-CAN 時自動路由 |
使用者看到的每條引用都應來自 Harvester(若未命中,則來自經過驗證的網路來源)。絕不虛構。
何時使用此技能
- 每當事實模式提及加拿大或加拿大省份 / 城市時務必使用。 加拿大集合是根據判決案例的事實建立索引,因此模糊的事實模式(例如「孩子在安大略的 Target 受傷」、「在多倫多人行道冰上滑倒」)正是其強項。先執行
search;只有在顯示命中結果後才追問後續問題。 - 使用者要求特定引用:"Cal. Veh. Code § 23152(a) 是什麼?" →
lookup_citation - 使用者提出語義 / 主題問題:"加州的 DUI 法規","關於開車發簡訊的法律" →
search - 使用者提出開放式問題,需要取得前 K 個候選:"哪個州有類似 CVC 20001 的肇事逃逸條文?" →
ask - 使用者使用同義詞(例如「超速」、「酒駕」、「傳簡訊」)— 請先將其對應至 17 個標準肇事因素分類之一,再作為
factor過濾條件傳入(分類表如下)。
何時不使用此技能
- 純程序性 / 訴訟策略問題(例如「我要怎麼提告?」)— Harvester 僅收錄美國法規與加拿大判例。
- 打招呼、身份確認、個性測試 — 直接以適當語氣回答,無需呼叫 API。
- 不需要引用的問題(Specter 可在不引用法條的情況下簡短回答一般個人傷害法律問題,但絕不能為此虛構引用)。
重點:不要等使用者澄清再行動
特別是針對加拿大事實模式的查詢,即使使用者說得很模糊,也應先呼叫 search。顯示前幾筆命中結果後,再追問後續細節。加拿大語料庫是以事實模式建立索引的 — 即使模糊的查詢也能回傳相關案例。要求更多事實後才搜尋會浪費語料庫的價值。
如何呼叫
輔助模組位於此 SKILL.md 旁:
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent)) # 如為臨時執行
from client import lookup_citation, search, ask, healthz, list_factors
在 OpenClaw 中,建議透過 exec 執行:
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client lookup "Cal. Veh. Code § 23152(a)"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client search "drunk driving" --state CA --factor "DUI/DWI"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client ask "what statutes cover hit and run in CA"
或者從 Python 呼叫:
from openclaw.skills.harvester_query.client import lookup_citation, search, ask
lookup_citation(citation: str) -> dict | None
依 citation 字串進行完全比對。回傳完整記錄,若 Harvester 中無此資料則回傳 None。
search(q: str, *, state=None, factor=None, pi_only=False, k=10) -> list[dict]
語義搜尋。state 為兩字母代碼(例如 "CA"、"TX")。factor 必須是 17 個標準分類之一。
ask(question: str, *, state=None, factor=None, k=8) -> list[dict]
與 search 相同,但以問題形式傳入。當使用者以自然語言提問時使用此方法。
healthz() -> dict
輕量存活檢查。用於在回報未命中之前確認 API 正在運行。
list_factors() -> list[str]
回傳 17 個分類。在語音場景中進行同義詞對應時很有用。
如何格式化結果以適用於 WhatsApp
Specter 的語音規則(見 SOUL.md):預設最多 2-3 行。引用,不要直接引用全文。
正確:
Cal. Veh. Code § 22350. 基本速度法 — 行車速度不得超過在當時條件下合理的安全速度。 leginfo.legislature.ca.gov
錯誤:
當然!根據加州車輛法規第 22350 條,「任何人不得駕駛車輛……」(一大段文字)
務必包含記錄中的 source_url。切勿提供無來源的引用 — 根據黑客松基本規則,沒有真實來源 URL 的記錄不計入。
未命中的處理方式
如果 lookup_citation 回傳 None 或 search/ask 回傳 []:
- 檢查
healthz()— 如果 API 已關閉,請直接說明。 - 如果 API 正常運作但記錄不存在,請說明:"Harvester 中尚無此資料。" 然後:
- 提議從權威來源(僅限立法機關、法院、律師公會)進行網路抓取。
- 建議團隊將該管轄區導入。
切勿以猜測來掩蓋未命中的情況。
17 個肇事因素分類(標準分類,請勿自行發明)
DUI/DWI
Driving Too Fast For Conditions
Failure to Maintain Lane
Failure to Obey Traffic Control Device
Failure to Use/Activate Horn
Failure to Yield at a Yield Sign
Failure to Yield the Right-of-Way
Fleeing a Police Officer
Fleeing the Scene of a Collision
Following Too Closely
Improper Lane of Travel
Improper Passing
Improper Starting
Improper Stopping
Improper Turning
Reckless Driving
Using a Wireless Telephone/Texting While Driving
如果使用者使用同義詞,請在內部對應後,以使用者的用語回答。