harvester-query
Specter 的 Harvester 是一个 FastAPI 服务,前端包含 两个 Chroma 集合:
| 集合 | 内容 | API 何时使用它 |
|---|---|---|
specter_statutes | 384条美国机动车法规(加州、德州、佛罗里达、宾夕法尼亚、伊利诺伊、俄亥俄州) | 默认——任何美国管辖或通用查询 |
canada_pi_cases | 340个真实的加拿大人身伤害判例(CanLII,包含赔偿金、伤害类型、原告是否胜诉、决定性因素) | 当查询提到加拿大/安大略/魁北克/多伦多/ONSC/ONCA/canlii 等,或传递了 ?jurisdiction=Canada 或 ?state=CA-CAN 时自动路由 |
用户看到的每条引证都应来自 Harvester(或在未命中时,来自经过验证的网络来源)。绝不编造。
何时使用本技能
- 当事实模式提到加拿大或加拿大省份/城市时务必使用。 加拿大集合基于已判案例的事实建立索引,因此杂乱的事实模式("孩子在安大略省Target店外受伤"、"在多伦多人行道上因冰滑跌倒")正是其擅长处理的。先执行
search;仅在展示匹配结果后才提出后续问题。 - 用户要求特定引证:"Cal. Veh. Code § 23152(a) 是什么?" →
lookup_citation - 用户提出语义/主题问题:"加州酒驾法规"、"关于开车发短信的法律" →
search - 用户提出开放式问题并希望获得 top-k 候选:"有哪个州有类似 CVC 20001 的肇事逃逸法规?" →
ask - 用户使用同义词("超速"、"酒驾"、"发短信")——需映射到17个规范促成因素类别之一(见下方类别),再作为
factor过滤器传递。
何时不使用本技能
- 纯程序/案件策略问题("如何立案?")——Harvester 仅包含美国法规和加拿判别例法。
- 问候、身份问题、角色确认——以语音回答,不调用 API。
- 不需要引证的问题(Specter 可以简要回答一般性人身伤害法律问题,但绝不能编造引证来支持回答)。
重要提示:不要在确认前设限
对于加拿大事实模式查询,即使表述模糊,也应立即使用用户的原始说法调用 search。先展示 top 命中的结果,然后才提出后续问题。加拿大语料库是基于事实模式索引的——即使模糊的查询也能返回相关案例。在搜索前要求更多事实会浪费语料库的价值。
如何调用
辅助模块与此 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 是2字母代码(如 "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 的引证——按照黑客松规则,没有真实来源 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(开车使用无线电话/发短信)
如果用户使用同义词,在内部映射后以用户的原话回答。