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 — 1つの製品の仕様を取得する

次のいずれか1つで製品を特定します: 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"} も他の2つの形式です。オプション: exclude_low_confidence: true で低信頼度のバケットを除外します。

ユーザーが8～14桁の数字（EAN-8、UPC-A、EAN-13、GTIN-14）を貼り付けた場合は、モデルとして解析しようとする前に、まず ean として扱いルックアップします。

レスポンスの status:

• hit — 1件の製品。ボディ: 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）があります。results を quality_score の降順（良い仕様順。データが薄い製品は最後に並ぶ）で返します。各結果にはルックアップと同じ quality_score フィールドがあります。ユーザーが特定の製品名ではなく「<カテゴリ>で何を買うべきか」と尋ねた場合に使用します。

compare_products — ハードな仕様を並べて比較

ユーザーが2つ以上の特定の製品を指定して比較を求めた場合に使用します。

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 — 確認済みの仕様を追加

1回の送信で fields 配列を渡します。url / ean / brand+model のいずれか1つで製品を特定します（brand+model は製品が新規であれば作成します）。各フィールドには source_url と、値を読み取った原文のままの snippet を含める必要があります。この証拠が信頼度を得るための根拠です。source は web（デフォルト、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 で製品をルックアップし、次に欠落している 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 — これまでに独立した情報源が1つだけです。その旨を伝えてください。
• disputed: true — 情報源が一致しません。勝者 と alternate_claims を表示します。不一致自体が購買シグナルであり、隠すべきノイズではありません。
• enrichment_opportunities — 別の情報源から恩恵を受けるであろうフィールドです。ユーザーが関与している場合は、1つ取得して submit_contribution することを提案します。

レスポンスにない値を決して捏造してはいけません。また、事実を報告する際に信頼度を決して省略してはいけません。

エラー

• 401 無効/トークンなし → ユーザーに COMMONSPECS_API_TOKEN を確認するよう伝えます。再試行しません。
• 403 禁止 → トークンにアクセス権がありません。再試行しません。
• 429 レート制限 → バックオフして指数関数的遅延（例: 1秒、2秒、4秒、最大3回）で再試行します。
• 5x / ネットワーク → 1〜2回バックオフして再試行し、それでも失敗した場合は単純に障害を報告します。

未提供

offers/価格情報および flag_stale は、まだAPIで公開されていません。それらに対する呼び出しをでっち上げてはいけません。機能が稼働していないと伝えてください。