back
loading skill details...
搜索国内主流电商平台（淘宝/天猫、京东、拼多多、苏宁、唯品会、考拉、抖音、快手、1688）的实时价格，自动找到最合适的可信购买点并给出'值不值得买'建议 + 直接可点击的购买链接；本地积累历史价数据，能识别当前价是历史低位还是高位。Keywords: 比价, 值不值得买, 哪里买最便宜, 历史价, 价格监控, X...
---
name: price-check
description: "搜索国内主流电商平台（淘宝/天猫、京东、拼多多、苏宁、唯品会、考拉、抖音、快手、1688）的实时价格，自动找到最合适的可信购买点并给出'值不值得买'建议 + 直接可点击的购买链接；本地积累历史价数据，能识别当前价是历史低位还是高位。Keywords: 比价, 值不值得买, 哪里买最便宜, 历史价, 价格监控, X 现在合适入手吗, X 多少钱合适, 哪个平台最便宜, 套路价, 购买链接, 淘口令, price compare"
homepage: https://github.com/yuxiaoyang2007-prog/price-check
metadata:
openclaw:
emoji: "💰"
requires:
bins: ["python3", "uv"]
---
# 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 自动拉购买链接** | 不再追问"哪里买"，淘宝/天猫给淘口令、京东给短链 URL |
| **B. 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 三层过滤）
```
用户问"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](https://clawhub.ai/skills/shopmind-price-compare)（作者 [xiaohaook](https://clawhub.ai/users/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 警觉。
don't have the plugin yet? install it then click "run inline in claude" again.