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（评分最高的规格排在前；数据薄的产品排在最后），每个结果都带有与 look up 相同的 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 最高的产品 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 查询产品，然后使用 "source": "label" 贡献缺失的 fields。

读取响应

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 速率限制 → 退避并使用指数延迟重试（例如 1s、2s、4s，最多 3 次）。
• 5x / 网络错误 → 重试一到两次，采用退避策略，然后明确报告失败。

尚未支持的功能

offers/定价和 flag_stale 目前尚未通过 API 公开。不要伪造对这些功能的调用——请说明该功能尚未上线。