杂货价格簿

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install grocery-price-book
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 grocery-price-book。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

杂货价格簿是 Openclaw Skills 中一款本地、注重隐私的价格跟踪工具，可通过杂货收据或手动输入建立个人数据库。它会将包装大小标准化为可比较的单位价格，跟踪价格变化，并根据你实际购物篮中的商品而不是笼统的节省宣传来排列商店。
该技能还提供实用的杂货购物财务分析：识别涨价和缩水式通胀，在货架上比较包装选项，根据消费量和保质期计算批量购买节省，并判断仓储店会员资格是否能够回本。数据保存在本地 JSON 文件中，无需账户或上传收据。

应用场景

找出导致每月账单上涨的具体杂货商品。
根据常购购物篮的成本比较超市和仓储店。
立即比较不同包装的每克、每升或每件价格。
当包装变小而价格不变或上涨时检测缩水式通胀。
跟踪历史最低价，并围绕周期性低价安排囤货。
在考虑月度消费量和保质期后，判断批量购买是否值得。
计算会员资格带来的实际节省是否超过年费。
确认解析出的商品行、规格、日期、商店和价格后导入收据文本。
不要将此工具用作完整的家庭预算或餐厅及一般零售支出跟踪器。

工作原理

手动记录收据数据，或在检查解析行后导入收据文件。
为每次购买记录商店、日期、商品名称、包装大小和价格。
使用公制和美国惯用单位启发式解析 500g、2L、12ct、1lb 和 24x330ml 等包装规格。
将每次购买追加到本地 pricebook.json 文件，并使用模糊商品名称匹配归并重复条目。
将可比较产品标准化为每 100g、每升或每件的单位价格。
运行 report 按重叠购物篮成本排列商店，显示单位价格比较，识别涨价并标记疑似缩水式通胀。
运行 unit，立即比较两个或更多包装选项的货架价格。
使用实际消费量和保质期数据运行 bulk，计算可实现的节省和回本时间。
运行 membership，将重叠产品的实际节省与年度会员费进行比较。
根据结果为特定商品更换商店、在历史低价附近购买、调整囤货数量，或拒绝不经济的会员资格。

配置指南

Python 3 和技能的 scripts/price_book.py 脚本。
仅使用 Python 标准库；无需外部包、账户或托管服务。
可写入 pricebook.json 的本地目录。
安装和首次录入
将技能文件放入代理的技能目录，然后从该目录运行 CLI：
python3 scripts/price_book.py add --store lidl --item "Oat milk" --size 1L --price 1.29
需要时使用明确日期添加历史或当前购买：
python3 scripts/price_book.py add --store costco --item "Oat milk" --size 6x1L --price 7.49 --date 2026-09-10
使用文档规定的收据格式导入完整收据，并在依赖结果前确认解析行：
python3 scripts/price_book.py import --store kroger references/receipt-example.txt
核心命令
python3 scripts/price_book.py unit --opts "2L@3.49" "6x1L@7.49" "1L@1.29"
python3 scripts/price_book.py report
python3 scripts/price_book.py bulk --size 15kg --price 19.90 --use 2kg/month --shelf 12months
python3 scripts/price_book.py membership --store costco --fee 60
为确保比较可靠，请使用一致的商品名称，包含包装大小，核实解析出的单位，并在提出强有力的节省结论前为每家商店收集至少两个日期。

数据架构

所有数据均存储在本地 pricebook.json 中。该技能不会上传收据，也不要求远程账户。
逻辑购买条目字段
字段 用途
store 购买商品的商店或零售商
date 用于历史比较的购买日期
item 用于分组和模糊匹配的一致商品名称
size 包装数量，例如 500g、2L、12ct 或 6x1L
price 记录的购买价格
unit 解析出的比较基础，例如克、毫升或件
unit_price 标准化的每 100g、每升或每件价格
派生元数据和报告
商店级购物篮总价只根据被比较商店共有的商品计算。
商品历史按商店形成时间序列，可进行价格变化和历史低价分析。
单位价格表会找出每种可比较商品观察到的最佳优惠。
在历史数据充足时，通胀标记会识别单位价格上涨超过 10% 的情况。
缩水式通胀标记会将新旧包装大小及其价格进行比较。
批量分析整理包装大小、价格、月度消费量、保质期、可用数量和每月保质期节省。
会员分析记录所选商店、年费、重叠商品比较基础、实际节省和回本结果。
收据导入应在提交数据前保留或确认来源商店、日期、商品行、规格和价格。

高级特性

本地优先运行将杂货价格历史和收据数据保存在用户设备上。
纯标准库实现无需安装依赖或配置外部服务。
模糊商品名称匹配有助于将重复购买合并为商品历史，同时仍要求名称保持一致。
公制和美国惯用规格解析支持重量、体积、件数和多包装表达式。
基于购物篮的商店排名反映用户真实购物模式，而非宽泛平均值或营销宣传。
历史单位价格跟踪可发现普通涨价和隐性缩水式通胀。
历史低价支持基于证据的囤货时机和季节性购买规划。
批量购买计算结合实际消费量和保质期，而不是假定更大包装一定省钱。
会员回本分析将年费分摊到重叠产品的实际节省上。
报告可作为人类可读输出或 JSON 供下游代理工作流使用。
代理工作流可将收据 OCR 或文本提取与导入条目前的确认检查点结合起来。
面向验证的运行方式会标记不确定的规格或价格解析，而不是默默信任错误单位。

name: grocery-price-book description: "Use when grocery bills keep creeping up, when you want to know which store actually has the best prices on what YOU buy, or when deciding whether a bulk-club membership pays off — builds a personal price book from receipts (manual entry or receipt-file parsing), computes unit prices across package sizes and stores, tracks price history per item to expose shrinkflation and stealth increases, ranks stores by your-basket cost instead of generic averages, and answers bulk-buy and stock-up questions with real math (cost per serving, shelf-life breakeven, membership breakeven)." version: 1.0.0
author: Denis Voronin
license: MIT
tags: [groceries, price-tracking, unit-price, shrinkflation, budgeting, household]

Grocery Price Book

Overview

Grocery prices rose sharply in recent years and never came back down — but the increases are deliberately uneven. The cereal box quietly shrinks from 500g to 440g at the same price. Your usual store raises the price of the 12 items you actually buy while advertising "everyday low prices." A bulk club looks cheap but 30% of what you buy there is more expensive per unit than the supermarket across the street.

The old-school fix is a price book: a small notebook where frugal households recorded what each item costs at each store, per unit, over time. It's proven (it's how our grandparents shopped) but nobody maintains it because manual tracking is tedious.

This skill modernizes it:

Log purchases — one line per item from a receipt: store, date, item, size, price. Or import a whole receipt file and confirm the parse.
Unit-price engine — normalizes everything to price-per-100g / per-liter / per-count, with a unit-guessing heuristic (metric and US customary), so a 440g box and a 1kg bag become comparable.
Store ranking by YOUR basket — ranks stores by the total cost of the items you actually buy there, not by average savings claims.
Price history & shrinkflation detector — flags items whose unit price jumped >10% since you started tracking, and items whose package size shrank while price held.
Bulk-buy advisor — answers "should I buy the 15kg bag?" with shelf-life breakeven math: how much do you consume per month, when does it expire, what's the actual savings per month of shelf life.
Membership breakeven — is the $60/year club card worth it given what you'd actually save?

All data stays in a local JSON file. Pure stdlib. No accounts, no receipts uploaded anywhere.

When to Use

"Why is my grocery bill higher every month?" — find the specific items driving it, with numbers.
Choosing where to shop — rank stores by the cost of YOUR top items, not marketing.
At the shelf, deciding between sizes — unit command: instant price-per-unit comparison of 2-3 options.
Suspecting shrinkflation — "didn't this box used to be bigger?" — history proves or disproves it.
Bulk-club decision — "will the membership pay for itself?"
Stock-up decisions — "turkey is $0.99/lb this week; how much should I freeze?"
Don't use for: restaurant spending, non-grocery retail (different seasonality), or as a full budgeting system — it's a price-intelligence tool, not an expense tracker (use receipt-raccoon-style skills for full spend categorization).

How It Works

Add entries — add --store costco --date 2026-09-18 --item "Flour AP" --qty 10 --size 10kg --price 8.99. Size parsing understands 500g, 2L, 12ct, 1lb, 24x330ml, and combinations.
Build history — each entry appends to pricebook.json; multiple entries of the same item (fuzzy name match) form a time series per store.
Analyze:
report — basket cost per store (items common to compared stores), unit-price table, top shrinkflation suspects.
unit A B C — quick shelf-side comparison of specific options.
bulk — consumption rate (from your own history or stated) vs shelf life vs size.
membership — observed savings rate on overlapping items vs annual fee.
Act — switch stores for specific items, time stock-ups around your own historical price floors, and drop the bulk membership if the math says so.

Commands

# Log an item (size optional but needed for unit prices)
python3 scripts/price_book.py add --store lidl --item "Oat milk" --size 1L --price 1.29
python3 scripts/price_book.py add --store costco --item "Oat milk" --size 6x1L --price 7.49 --date 2026-09-10

# Import a whole receipt (see references/receipt-example.txt for format)
python3 scripts/price_book.py import --store kroger references/receipt-example.txt

# Compare options at the shelf right now
python3 scripts/price_book.py unit --opts "2L@3.49" "6x1L@7.49" "1L@1.29"

# Full report: store ranking by your basket, unit-price table, inflation flags
python3 scripts/price_book.py report

# Shrinkflation suspects only
python3 scripts/price_book.py report | grep -A3 SHRINK # or read the JSON via --json

# Bulk-buy math: consume 2kg/month, shelf life 12 months, 15kg bag at $19.90?
python3 scripts/price_book.py bulk --size 15kg --price 19.90 --use 2kg/month --shelf 12months

# Is the $60/yr membership worth it? (compares overlapping items in your book)
python3 scripts/price_book.py membership --store costco --fee 60

Example Session

$ python3 scripts/price_book.py report

=== PRICE BOOK: 23 items, 3 stores, 61 entries ===

STORE RANKING by overlapping-basket cost (lower = better):

1. lidl $42.10 (11 common items)
2. costco $44.85 (9 common items; membership not counted)
3. kroger $49.30 (11 common items) → Buying the common basket at lidl instead of kroger saves ~$7.20/trip
   (~$374/yr at weekly trips)

UNIT-PRICE TABLE (best deal per item flagged):

Item Size Store Price Unit

Flour AP 10kg costco $8.99 $0.090/100g ★
Flour AP 2.5kg lidl $3.29 $0.132/100g
Oat milk 6x1L costco $7.49 $1.25/L ★
Oat milk 1L lidl $1.29 $1.29/L

PRICE INCREASES (>10% unit-price jump, tracked items):
Olive oil EVOO @ kroger: $0.62/100ml (Aug) → $0.78/100ml (Sep) +26%
→ Consider: switch store, stock up if shelf-stable, or substitute.

SHRINKFLATION SUSPECTS (size down, price same/up):
Cereal O's @ kroger: 500g → 440g at $4.99 → unit price +13.6% silently

BULK/STOCK-UP FLOORS (your historical lows — buy when at/below):
Butter: $2.49 (lidl, Jun) — current best $3.19 → wait
Turkey (seasonal): $1.10/lb (Nov) vs $2.89/lb now → Nov stock-up

Workflow for an Agent

Ask for the latest receipt (photo → OCR, or text paste). Confirm item lines before importing.
add or import entries; flag any line where size or price parsing looks wrong — never silently guess wrong units.
After ~2-3 weeks of entries, run report; present store ranking and top 5 opportunities with dollar impact per month.
Watch price-increase and shrinkflation sections — these are the "aha" outputs users care about most.
For bulk/membership questions use bulk and membership with the user's real consumption numbers, not defaults.

Common Pitfalls

Comparing items with wrong units. 500g vs 1lb vs 12ct only compare if the unit guess is right. Always show the interpreted unit (g, ml, ct) in output; correct it with --size on the next entry if wrong.
Name drift. "Milk 2%" and "milk 2% carton" become two items. Keep names short and consistent (store brand + type + variant); the fuzzy matcher helps but isn't clairvoyant.
Judging stores on one trip. Sales distort single trips; require ≥2 dates per store before quoting savings.
Forgetting membership fees. Costco's basket price means nothing until the fee is amortized — always run membership too.
Bulk-buying perishables. The bulk math must include shelf life; a 15kg bag of flour for a 1kg/month household is mouse food, not savings.
Treating the price book as a budget. It tracks PRICES, not spending totals. Different tool.

Verification Checklist

Entries have store + date + item + price (+ size for unit math)
Unit interpretation shown for every compared item (and corrected where wrong)

Store ranking only quotes items present at both stores

Shrinkflation/increase claims cite both observations (old and new)
Bulk advice includes consumption rate, shelf life, and monthly savings
Membership verdict states observed savings vs fee, with item count basis
jev-email
票务收入结算检查（免费）