harvester-query
Specter의 Harvester는 두 개의 Chroma 컬렉션을 제공하는 FastAPI 서비스입니다:
| 컬렉션 | 내용 | API가 사용하는 경우 |
|---|---|---|
specter_statutes | 384개의 미국 자동차 법령 (CA, TX, FL, PA, IL, OH) | 기본값 — 미국 관할 또는 일반 질문 |
canada_pi_cases | 340개의 실제 캐나다 PI 판례 (CanLII, 손해배상, 부상 유형, 원고 승소, 결정 요인 포함) | 질문에 Canada / Ontario / Quebec / Toronto / ONSC / ONCA / canlii 등이 언급되거나 ?jurisdiction=Canada 또는 ?state=CA-CAN이 전달될 때 자동 라우팅 |
사용자에게 보여주는 모든 인용은 Harvester에서 가져와야 합니다 (또는 Harvester에 없을 경우 검증된 웹 출처에서 가져와야 합니다). 절대 조작하지 마세요.
이 스킬을 사용해야 하는 경우
- 캐나다 또는 캐나다의 주/도시를 언급하는 사실 패턴에 대해 항상 사용하세요. 캐나다 컬렉션은 기존 판례의 사실을 기준으로 색인되어 있으므로, 복잡한 사실 패턴("온타리오주 Target 밖에서 다친 아이", "토론토 빙판길 미끄러짐 사고")에 특히 적합합니다. 먼저
search를 실행하고, 결과를 보여준 후에 추가 질문을 하세요. - 사용자가 특정 인용을 요청하는 경우: "Cal. Veh. Code § 23152(a)가 뭐예요?" →
lookup_citation - 사용자가 의미론적/주제별 질문을 하는 경우: "캘리포니아의 음주운전 법령", "운전 중 문자보내기에 관한 법" →
search - 사용자가 개방형 질문을 하고 상위 후보를 원하는 경우: "CVC 20001과 유사한 뺑소니 법이 있는 주는?" →
ask - 사용자가 동의어("과속", "음주운전", "문자보내기")를 사용하는 경우 — 필터로 전달하기 전에 17개의 표준 기여 요인 카테고리 중 하나로 매핑하세요 (아래 카테고리 참조).
사용하지 말아야 할 경우
- 순수 절차적/사례 전략 질문("어떻게 접수하나요?") — Harvester는 미국 법령과 캐나다 판례만 보유합니다.
- 인사말, 신원 확인 질문, 페르소나 체크 — API를 호출하지 않고 음성으로 답변하세요.
- 인용이 필요하지 않은 질문 (Specter는 일반적인 PI 법률 개요 질문에 대해 간략히 인용 없이 답변할 수 있지만, 답변을 뒷받침하기 위해 인용을 조작해서는 안 됩니다).
중요: 명확화를 위해 질문을 미루지 마세요
캐나다 사실 패턴 질문의 경우, 특히 사용자가 모호하게 말하더라도 먼저 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는 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이 없는 레코드는 해커톤 기본 규칙에 따라 인정되지 않습니다.
누락 처리
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 (운전 중 무선전화 사용/문자보내기)
사용자가 동의어를 사용하는 경우, 내부적으로 매핑하고 사용자의 언어로 답변하세요.