price-check v0.6.4#

⚠️ Agent 渲染硬规则（拿到 stdout JSON 时必读）#

第一步永远是把 human_report 字段原样发给用户。

• ❌ 不要省略 human_report
• ❌ 不要重新组织 / 翻译 / 简化 human_report 内容
• ❌ 不要把 human_report 拆开重组成你自己的格式
• ✅ 你 只能 在 human_report 完整发完之后追加一段「我的建议」（≤ 200 字，基于 verdict + SKU 不匹配警告 + 你的产品判断）
• 违反这些规则 = skill 输出无效

JSON 里 _meta.agent_must_render 字段也重复了同一条规则。

CLI 用法（绕过 LLM 直出 markdown）： uv run bin/price_check.py "X" --report

安装即用，飞书同步完全可选#

• 零配置即可用：装上 skill 直接 uv run bin/price_check.py "X" 就能跑，所有功能（横向比价 / verdict / 购买链接 / 本地 SQLite 历史价积累）开箱即得
• ~/.openclaw/data/price-check/ 是 skill 自己的数据目录，零依赖（仅用 Python stdlib sqlite3），跨平台无障碍
• 飞书多维表格同步是 OPT-IN：不需要它的人 什么都不用做，主流程不会触碰飞书 / 不会调 lark-cli / 不会因此报错。详见后面"飞书多维表格同步"章节
• lark-cli 也是 OPT-IN 依赖：仅启用飞书同步的人才需要装； metadata.openclaw.requires.bins 没声明它
• 完整可配置项参考 config.example.json（位于 skill 根目录）

这个 skill 能为你做什么#

三件事，对应你日常买东西的三个真实需求：

1. 搜全网最低价 — 一次查询，22+ 个国内电商平台横向对比（淘宝/天猫、京东、拼多多、苏宁、唯品会、考拉、抖音、快手、1688）。同关键词的配件、翻新机、套装、激活可疑、SKU 不匹配的混淆商品自动过滤掉，只留 真正可信的购买候选
2. 告诉你"该不该买" — 不只是给价格列表，而是给"强烈推荐 / 可以买 / 再等等 / 数据质量不足"的明确建议，附 具体依据（"可信最低价 ¥X 比 N 平台中位数 ¥Y 低 K%"），并自动拉取 直接可点击的购买链接（淘宝淘口令、京东短链）
3. 监控历史价 — 每次查询自动写入本地 SQLite， 多查几次同商品后 自动激活"该商品历史最低 ¥X / 最高 ¥Y / 当前处于低位/中位/高位"识别。能捕捉"先涨后降"假促销陷阱

可选叠加：把每次查询自动同步到飞书多维表格，方便手机/电脑跨设备刷历史 + 标记"已购"。

触发词#

比价、值不值得买、哪里买最便宜、历史价、X 现在合适入手吗、X 多少钱合适、哪个平台最便宜、套路价、是不是先涨后降、当前价合理吗、给我购买链接、价格监控、price compare

v0.4.1 升级亮点（vs v0.4）#

升级用户感知C 模式报告固定 6 段：⚠️ 警告 → 🏆 best_deal+链接 → 📊 Top 3 表 → 📈 历史价 → 🤖 我的建议 → ⚠️ 透明度。即使建议不买也完整展示，防止 agent 为简洁砍数据顶部警告区SKU 不匹配 / 无可信候选时，必须在标题正下方用 ⚠️ 块前置。防止用户被 best_deal 假象误推**"我的建议"段独立**Molty 综合判断单独成段（"工具 verdict X，但因 SKU 不匹配实际不建议"），跟 verdict 字段语义分离

v0.4 升级亮点（vs v0.3）#

升级用户感知F. LocalDBHistoryProvider用本地 SQLite price_snapshots 当历史价数据源（不依赖外部慢慢买）。同 query 跑 ≥3 次后，verdict 会引用"该商品历史 X-Y 元，当前处于历史低位/中位/高位"G. verdict 升降档当前价处于历史低位 + 比市场中位低 5-15% → 升档为"强烈推荐"（原本是"可以买"）；trap 命中（先涨后降）→ "别买"H. 商品稳定指纹shopmind goodsId 含 session token（每次返回都不同），改用 (shop + title 前 30 字符) 作为商品稳定指纹，跨次匹配同一商品的历史价I. 飞书表加历史字段（首次跑 setup_feishu.py 一次性建 31 个字段，含历史段：历史样本数 / 历史最低 / 历史最高 / 历史均价 / 当前位置 / 市场30日中位 / 当前/市场比）

v0.3 升级亮点（vs v0.2）#

升级用户感知A. best_deal 自动拉购买链接不再追问"哪里买"，淘宝/天猫给淘口令、京东给短链 URLB. Top 3 候选也自动拉链接飞书消息里就能多平台对比 + 直接点击下单C. 导购优先排版报告顶部不再是 verdict，而是"最划算 ¥X + 链接"和"Top 3 价格速览表"；verdict 退居中部作为决策建议D. SQLite 本地持久化每次查询写库，30min 缓存复用；本地积累历史价快照**E. 飞书多维表格同步（opt-in）**启用后查询历史进飞书表，手机/PC 飞书 App 直接刷历史 + 点击购买链接

v0.2 范围 vs v0.3 计划#

功能v0.2 已实现v0.3 计划全网横向比价（≈ 22-60 平台）✅✅价格分布底部 outlier 剔除（去配件/噪音）✅（ price < raw_median × 0.3 自动剔除）✅（叠加历史价交叉验证）condition 识别 7 档（accessory / bundle / refurbished / activation_questionable / parallel_import / trusted_domestic / unknown）✅（title 关键词词典）✅（叠加店铺评分）trusted_shop 识别（自营/旗舰店）✅（shopName 字面量 + 正则）✅（叠加京东开放平台 vender_type 字段，运营商京东自营单独一档）标题相关性 / SKU 精确匹配（"16 Pro 256G" vs "17 Pro 256G"）✅（token 命中率 ≥ 0.75 + 多型号堆砌检测）✅（叠加 fuzzy match + 同义词 / 大小写 / 容量等价）best_deal 选择按可信度 × 相关性 优先级✅（先过 condition + relevance，再三档优先级）✅（叠加历史价档"别买"）当前价 verdict（强烈推荐/可以买/再等等/数据质量不足/数据噪音过多/无数据）✅（基于 best_deal 价 vs 中位数 + relevance 标注）✅（叠加历史价精度更高 + "别买"档）trap_warning 透明化（剔除 + flagged + low_relevance + 低价非可信候选提示）✅✅（叠加"先涨后降"识别）历史价 history_summary❌（输出为 null）✅（HistoryProvider plugin 接入慢慢买自爬）详情页 URL（购买链接）❌（best_deal.url=null）✅（按需调 shopmind detail）

注意： history_summary 与"先涨后降"两类信号在 v0.2 仍为 null，下游不要假设它们存在。 bin/price_check.py 已留 HistoryProvider 抽象接口，v0.3 接入慢慢买/什么值得买/京东价保后只换 provider 即可，不动主流程。

工作流（v0.2 三层过滤）#

text

用户问"X 多少钱值得买" / 触发词命中
    ↓
price-check 调 fetch_items(query)
    ↓
shopmind._fetch_search_items()  ← 直接 import 上游 helper，拿 to-string 之前的原始 items
    ↓
_normalize_item(item, query)  ← 字段标准化 + 注入 condition / condition_hits /
                                  is_trusted_shop / relevance(score, matched, missing, ambiguous)
    ↓
原始 items[]（≈ 22-60 条，全字段已含 condition + relevance）
    ↓
[1] 价格层 _filter_outliers()  剔除 price < raw_median × 0.3 → removed_outliers
    ↓
若 clean_items < 5 → verdict = "数据噪音过多，无法判断"
    ↓
[2] 信任层 + [3] 相关性层（在 _select_best_deal 内一次完成）
    - condition ∈ {refurbished/bundle/accessory/activation_questionable} → flagged_items
    - relevance.score < 0.75 或 relevance.ambiguous=True              → low_relevance_items
    - 剩下进 candidates，按三档优先级选 best_deal:
        1. trusted_shop AND condition ∈ {trusted_domestic, unknown}
        2. trusted_shop AND condition == parallel_import
        3. NOT trusted_shop AND condition == trusted_domestic
    ↓
若所有档都没候选 → best_deal=null → verdict = "数据质量不足，无法可信推荐"
    ↓
compute_verdict()  ← 用 best_deal.price vs stats.median 跑阈值（含 ratio>1 时"高于中位数"路径）
compute_trap_warning()  ← 4 段拼接：剔除 / flagged / low_relevance / 低价非可信透明化
HistoryProvider.get_history()  ← v0.2 = NoOp，永远 null（v0.3 swap-in 点）
    ↓
JSON 输出（agent 用）+ references/report-template.md（agent 拿去做最终回复）

调用方式#

bash

uv run bin/price_check.py "iPhone 16 Pro 256G"
uv run bin/price_check.py "戴森 V12" --source 2     # 限制单平台（2=京东）
uv run bin/price_check.py "Switch 2" --page 2
uv run bin/price_check.py "AirPods Pro 3" --no-cache  # 忽略 30min 缓存，强制重打

stdout 是单个 JSON 对象（含 best_deal.buy_url + Top 候选 buy_url）。agent 拿到 JSON 后照 references/report-template.md 渲染 导购优先 人类回复。

飞书多维表格同步（opt-in，完全可选）#

不想用飞书的人请直接跳过这一节。skill 默认 feishu_sync.enabled = false，不会触碰飞书 / 不会调 lark-cli / 不会因此报错。完全 0 痕迹。

启用后，每次查询的 best_deal + Top 3 + verdict + 历史价 自动同步到飞书多维表格，方便在手机/PC 飞书 App 直接刷历史 + 点击购买链接。

启用步骤：

1. 装好 lark-cli（OPT-IN 依赖，未启用飞书的人不用装）

2. 创建飞书多维表格 —— 在飞书云空间里新建一个空多维表格（推荐命名 "价格监控"），位置随意

3. 授权要用的 bot 应用 —— 表格右上"协作" → 添加飞书 Bot 为可编辑（哪个应用看你 lark-cli 的默认 profile，OpenClaw 默认 Molty）

4. 跑配置脚本（一次性）： bash

   uv run bin/setup_feishu.py 'https://your-tenant.feishu.cn/base/<BASE_TOKEN>...?...'
   
   

   脚本会一次性自动建 31 个字段：查询词 / Verdict / Verdict依据 / best_deal 价格/平台/店铺/标题/链接/口令 / Top2链接 / Top3链接 / 匹配度 / Condition / 中位数 / 最低价 / 最高价 / 原始条数 / 剔除数 / 过滤数 / 不匹配数 / Trap提示 / 历史样本数 / 历史最低 / 历史最高 / 历史均价 / 当前位置 / 市场30日中位 / 当前/市场比 / 标记已购。

   字段建好后把 base_token / table_id / enabled=true 写到 ~/.openclaw/data/price-check/config.json。

5. 后续每次跑 price-check 自动同步，无需手动操作

如需关闭：编辑 ~/.openclaw/data/price-check/config.json 把 feishu_sync.enabled 改成 false。

如需切换 lark-cli profile（多飞书账号场景）：在 config.json 加 feishu_sync.lark_cli_profile = "<profile-name>"。

输出 schema#

jsonc

{
  "product": "<原始查询>",
  "verdict": "强烈推荐 | 可以买 | 再等等 | 别买 | 数据噪音过多，无法判断 | 数据质量不足，无法可信推荐 | 无数据",
  "verdict_reason": "可信最低价 ¥X（平台/店铺）比 N 平台中位数 ¥Y 低 K%；匹配度 100% (M/N token)，缺 [token]",
  "best_deal": {
    "platform": "京东",
    "shopName": "Apple产品京东自营旗舰店",
    "price": 5999.0,
    "title": "...",
    "condition": "unknown",
    "is_trusted_shop": true,
    "relevance": {                    // v0.2 新增
      "score": 0.75,
      "matched": ["iPhone", "Pro", "256G"],
      "missing": ["16"],
      "ambiguous": false
    },
    "goodsId": "...",
    "source": "2",
    "url": null
  },
  "history_summary": null,
  "all_platforms": [ /* 原始 items，每条含 condition / condition_hits / is_trusted_shop / relevance */ ],
  "removed_outliers":     [ /* [1] 价格层剔除：底部噪音 */ ],
  "flagged_items":        [ /* [2] 信任层过滤：refurbished/bundle/accessory/activation_questionable */ ],
  "low_relevance_items":  [ /* [3] 相关性层过滤：score < 0.75 或 ambiguous=true (v0.2 新增) */ ],
  "stats":     { "count": 17, "min": 5998, "max": 13998, "median": 8999, "stdev": ... },
  "stats_raw": { "count": 22, "min": 4.9,  "max": 13998, "median": 8999, "stdev": ... },
  "trap_warning": "⚠️ 已自动剔除 N 条… ⚠️ 已过滤 M 条… ⚠️ 已过滤 K 条标题不匹配… 💡 还有 P 条更低价候选未进 best_deal…" | null,
  "_meta": {
    "skill": "price-check",
    "version": "0.2.0",
    "history_provider": "noop",
    "data_source": "shopmind-price-compare._fetch_search_items()",
    "outlier_filter": "price < raw_median × 0.3",
    "min_clean_samples": 5,
    "relevance_threshold": 0.75,
    "ambiguous_model_count": 3,
    "condition_classifier": "title-keyword (v0.2)",
    "trusted_shop_classifier": "shopName-pattern (v0.2)",
    "suspicious_conditions": ["refurbished", "bundle", "activation_questionable", "accessory"]
  }
}

verdict 阈值（v0.2）#

完整规则详见 references/report-template.md。摘要：

• 原始 items 为空 → 无数据
• removed > 0 且 clean_count < 5 → 数据噪音过多，无法判断
• best_deal == null（信任层 × 相关性层全部过滤完没有候选）→ 数据质量不足，无法可信推荐
• best_deal.price ≤ clean_median × 0.85 → 强烈推荐
• best_deal.price ≤ clean_median × 0.95 → 可以买
• best_deal.price ≤ clean_median → 再等等（仅低 K%）
• best_deal.price > clean_median → 再等等（高 K%，常见于"全网真品 best_deal 比含个人店/翻新的中位数贵"场景）
• 历史价 v0.3 接入后会增加"别买"档（ history.trap 命中 / 当前价高于历史均价两档）

设计要点：verdict 用 best_deal.price（已过 condition + relevance + trust 三层筛选）而不是 stats.min。stats.min 可能是配件、翻新机、不相关 SKU；best_deal 才是"真正能买的可信全新国行/水货的最便宜款"。verdict_reason 末尾必带 匹配度 X%，提醒 SKU 接近度。

数据层#

v0.5 起数据层 自包含 在 bin/_data_layer.py，不再依赖外部 skill。该文件是 maishou88.com 公共 API 的薄客户端，HTTP endpoints / OPENID 种子 / items 构造逻辑 衍生自 shopmind-price-compare v2.2.0（作者 xiaohaook）—— 完整归属信息见 _data_layer.py 顶部 + README.md → Acknowledgements。

已知限制#

1. 历史价完全缺位（v0.3 接入慢慢买自爬 / 京东价保 API）：v0.2 verdict 仅基于"当下 N 平台分布"，碰到全网同步涨价的场景会判错。HistoryProvider 已留 swap-in 点。
2. best_deal.url 已自动 enrich（v0.3 起）；如果有日并发限流问题 v0.6 会改回按需拉取。
3. 剔除阈值 0.3 是定值：对 3C/家电正常工作，但极端价格分散（如收藏品/手办 ¥10–¥50000）可能误剔。v0.3 接入历史价后这个阈值可以放松或动态化。
4. condition 词典是启发式：会有偶发误判 —— "全新激活试用"误命中 activation_questionable；"宠物除螨仪"可能误命中 accessory（实际可能是带除螨头的吸尘器主机）。词典在 bin/price_check.py:CONDITION_RULES 可调。
5. 运营商京东自营当 trusted：中国联通 / 移动 / 电信京东自营旗舰店合约机风险偏高但当前算 trusted_shop。v0.3 计划单独给运营商专卖店一档。
6. 标题相关性是 substring 字符匹配 + token 命中率：query 必须用空格分词；只做 G/GB 等价，没有同义词 / 中英文别名映射。"V12s" 含 "V12" 子串会命中，但"V12 plus"和 query "V12 Pro" 不会互相识别。复杂场景待 v0.3 fuzzy match。
7. AMBIGUOUS_MODEL_COUNT = 3 是定值：title 出现 3+ 个不同型号 token 才算模糊堆砌。某些 title 写"V8/V10/V12 通用配件"恰好踩边界，但 condition=accessory 那道大概率会拦下。
8. shopmind keyword 召回有上限：单次最多 ~20-60 条结果，可能根本没召回到精确 SKU。verdict_reason 末尾的"匹配度"提醒会让用户/agent 警觉。