commonspecs/commonspecs-skill

commonspecs

commonspecs는 엔지니어링급 제품 사양을 각 필드별 신뢰도 점수와 함께 제공하는 API 우선 데이터베이스입니다. 추측하지 않습니다. 모든 값은 증거에 기반하며 보정된 신뢰도를 갖습니다. 여러분의 임무는 이러한 사실을 가져와 각 정보가 얼마나 신뢰할 수 있는지 포함하여 정직하게 제시하는 것입니다.

설정

설정은 환경 변수(또는 ~/.commonspecs/config.json)를 통해 이루어집니다:

변수	필수	기본값	설명
COMMONSPECS_API_TOKEN	예	—	API 토큰, 형식 cs_live_…. Authorization: Bearer로 전송됩니다.
COMMONSPECS_API_URL	아니오	https://api.commonspecs.com	API 기본 URL.
COMMONSPECS_DEFAULT_COUNTRY	아니오	—	국가별 읽기를 위한 ISO 3166-1 alpha-2(예: PL).

COMMONSPECS_API_TOKEN이 설정되지 않은 경우, 사용자에게 설정하도록 알리고 중단하십시오. API를 호출하지 마십시오.

도구

모든 호출은 Authorization: Bearer $COMMONSPECS_API_TOKEN을 전송합니다. 예제에서는 API="$COMMONSPECS_API_URL"을 가정합니다(위 기본값으로 대체).

lookup_product — 하나의 제품 사양 가져오기

정확히 하나의 식별자(url, ean, 또는 brand + model)로 제품을 찾습니다.

curl -sS -X POST "$API/v1/lookup" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Nudie","model":"Gritty Jackson"}'

{"url":"https://…"} 또는 {"ean":"7340028912345"}도 가능한 다른 두 형식입니다. 선택사항: exclude_low_confidence: true로 낮은 신뢰도 버킷을 제외할 수 있습니다.

사용자가 8~14자리 숫자(EAN-8, UPC-A, EAN-13 또는 GTIN-14)를 붙여넣으면 모델로 파싱하기 전에 먼저 ean으로 처리하여 조회하십시오.

응답 status:

• hit — 하나의 제품. 본문: product, quality_score (0–100 또는 null), fields, low_confidence_fields, enrichment_opportunities (아래 참조).
• candidates — 여러 변형이 일치함 (candidates: [...]). 사용자에게 선택을 요청하거나 url/ean으로 조회하십시오.
• miss — 찾을 수 없음. 사양 기여(submit_contribution)를 제안하십시오.

search_products — 제품 검색, 점수 높은 순으로

curl -sS -X POST "$API/v1/search" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"raw denim","category":"jeans-denim"}'

브랜드명과 모델명에서 일치합니다. 선택적 category(슬러그) 필터와 limit(≤20)을 지원합니다. quality_score 내림차순으로 정렬된 results를 반환합니다(가장 좋은 사양이 먼저; 데이터가 적은 제품은 마지막). 각 결과는 lookup과 동일한 quality_score 필드를 가집니다. 사용자가 특정 제품을 지목하지 않고 "<카테고리>에서 무엇을 사야 할까"라고 물을 때 사용하십시오.

compare_products — 엄격한 사양 비교

사용자가 둘 이상의 특정 제품을 비교하여 선택하려 할 때 사용하십시오.

curl -sS -X POST "$API/v1/compare" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_ids":["<id1>","<id2>"]}'

최대 5개 ID. products(각각 quality_score 포함), comparison 행렬([{field, cells: {<product_id>: {value, confidence} | null}}]), 그리고 overall_winner(가장 높은 total_score를 가진 product_id)를 반환합니다. 사실을 나란히 제시하고 overall_winner를 명명한 다음, 사실과 점수를 바탕으로 직접 트레이드오프를 설명하십시오 — API는 의도적으로 차원별 승자나 근거를 반환하지 않습니다. 가치 대비 비용 및 목적 적합성 판단은 데이터를 바탕으로 여러분이 내려야 합니다.

get_rankings — 카테고리 내 상위 제품

사용자가 제품을 지목하지 않고 "최고의 X는 무엇인가"라고 물을 때 사용하십시오.

curl -sS "$API/v1/categories/jeans-denim/rankings?country=PL&limit=20" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

quality_score 순으로 정렬된 results(각각 rank 포함)를 반환합니다. ranking_scope는 현재 global입니다 — 국가별 순위에는 현재 제공되지 않는 가격/재고 정보가 필요하므로 country_code는 반환되지만 순위는 전역 점수 순서입니다. 사용자가 카테고리를 탐색할 때 여러 개별 조회보다 이것을 선호하십시오.

get_product — ID로 제품 가져오기

curl -sS "$API/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

get_quality_score — 전체 품질 점수 (0–100)

curl -sS "$API/v1/products/$PRODUCT_ID/quality-score" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

total_score (0–100, 또는 아직 카테고리가 채점되지 않은 경우 null)와 missing_fields — 점수를 낮추는 사양 필드 목록을 반환합니다. 낮은 점수는 종종 데이터 부족을 의미하며, 제품 자체가 나쁘다는 뜻이 아닙니다; missing_fields를 사용하여 무엇을 기여할지 결정하십시오. 점수는 의도적으로 단일 숫자입니다 — 그 뒤에 있는 필드별 가중치는 공개되지 않으며, 사실 자체로부터 트레이드오프를 추론하십시오.

submit_contribution — 확인한 사양 추가

한 번의 제출은 fields 배열을 포함합니다. url / ean / brand+model 중 정확히 하나로 제품을 식별하십시오(brand+model은 새 제품인 경우 생성합니다). 각 필드는 값을 읽은 source_url과 그대로의 snippet을 포함해야 합니다 — 그 증거가 신뢰도를 얻는 방법입니다. source는 web(기본값, 웹 페이지) 또는 label(실물 라벨 — 아래 참조)입니다.

curl -sS -X POST "$API/v1/contributions" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Nudie Jeans", "model": "Gritty Jackson", "source": "web",
    "fields": [
      {"field_name": "fabric_weight", "value": "13.5 oz",
       "source_url": "https://www.nudiejeans.com/product/gritty-jackson",
       "snippet": "13.5 oz organic dry denim"}
    ]
  }'

실물 세계: 사용자가 라벨/제품 사진을 보여주는 경우, 직접 값을 읽고 EAN을 확인한 후 추출된 값만 전송하십시오 — 사진은 사용자 기기를 떠나지 않습니다. 먼저 ean으로 제품을 조회한 다음, 누락된 fields를 "source": "label"로 기여하십시오.

응답 읽기

quality_score (0–100, 또는 null)는 제품의 전체 사양 품질입니다. 사용자가 "이거 괜찮아?"라고 물으면 get_quality_score의 missing_fields와 함께 짝지어 사용하십시오. fields / low_confidence_fields의 각 필드는 value, confidence (0–1), disputed, needs_corroboration, 그리고 (분쟁 시) alternate_claims를 가집니다.

• fields[] — 신뢰도 ≥ 0.4. 말하기에 충분히 신뢰할 수 있습니다. 여전히 숫자를 표시하십시오; "13.5 oz (신뢰도 0.88)"는 단순한 "13.5 oz"보다 낫습니다.
• low_confidence_fields[] — 신뢰도 0.1–0.4. 단서일 뿐, 사실이 아닙니다. 명시적인 조건부 표현("한 소식통에 따르면…")과 함께만 제시하십시오. 사용자가 확실한 데이터만 원하는 경우 생략하십시오.
• needs_corroboration: true — 현재까지 단 하나의 독립적인 출처만 있음. 그렇게 말하십시오.
• disputed: true — 출처 간 의견 불일치; 승자를 보여주고 alternate_claims 도 함께 보여주십시오. 불일치는 그 자체로 구매 신호이며 숨길 잡음이 아닙니다.
• enrichment_opportunities — 다른 출처가 도움이 될 필드입니다. 사용자가 관여하고 있다면, 하나를 가져와 submit_contribution하겠다고 제안하십시오.

응답에 없는 값을 절대 만들어내지 말고, 사실을 보고할 때 신뢰도를 절대 생략하지 마십시오.

오류

• 401 잘못되었거나 누락된 토큰 → 사용자에게 COMMONSPECS_API_TOKEN을 확인하라고 알리십시오; 재시도하지 마십시오.
• 403 금지됨 → 토큰에 접근 권한이 없음; 재시도하지 마십시오.
• 429 속도 제한 → 지수 백오프로 대기 후 재시도하십시오(예: 1초, 2초, 4초, 최대 3회).
• 5x / 네트워크 → 백오프와 함께 한두 번 재시도한 다음 실패를 그대로 보고하십시오.

아직 사용 불가

offers/가격 정보 및 flag_stale은 아직 API에서 제공되지 않습니다. 이에 대한 호출을 만들어내지 마십시오 — 해당 기능이 아직 활성화되지 않았다고 말하십시오.