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（slug）篩選條件和 limit（≤20）。傳回按 quality_score 降序排序的 results（分數最高的規格優先；資料較少的產品排在後面），每個結果都附有與查詢相同的 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 公開。不要偽造對它們的呼叫——請說明該功能尚未上線。