# nz-supermarket-scraper
`nzgrocery` scrapes fresh produce and fresh meat prices from three New Zealand supermarket chains. It does not log in, add anything to a cart, or send personal data. Each run appends a new snapshot; older rows are left as they are.
The catalogues are the same guest APIs the websites call after a store is selected. Department names, aisle slugs, and skip lists were read from those APIs.
## Chains
| Chain | Also known as | How prices are read |
| --- | --- | --- |
| PAK'nSAVE | Foodstuffs | Playwright opens the homepage and reads the guest catalogue. It does not solve the Turnstile challenge. |
| New World | Foodstuffs | Same guest catalogue as PAK'nSAVE, on `newworld.co.nz`. |
| Woolworths NZ | formerly Countdown | `curl_cffi` impersonates Chrome's TLS/HTTP2 fingerprint. Akamai rejects non-browser clients. |
## Install
Python 3.10+ is required. The package on PyPI is `nz-supermarket-scraper`; it installs two identical commands, `nzgrocery` and `nz-supermarket-scraper`. No clone needed.
**pipx** (installs the command once, in its own environment):
```bash
pipx install nz-supermarket-scraper
nzgrocery install-browser # Chromium for PAK'nSAVE / New World (one-off, ~150 MB)
nzgrocery stores --chain woolworths
```
**uvx** (runs without a permanent install):
```bash
uvx nz-supermarket-scraper stores --chain woolworths
uvx nz-supermarket-scraper install-browser
uvx nz-supermarket-scraper scrape --chain woolworths --store "Browns Bay" --dry-run
```
To keep it around with uv: `uv tool install nz-supermarket-scraper`. Plain `pip install nz-supermarket-scraper` in a virtualenv works too.
Before the first PyPI release is out, install straight from GitHub instead:
```bash
pipx install "git+https://github.com/maxazure/nz-supermarket-scraper"
uvx --from "git+https://github.com/maxazure/nz-supermarket-scraper" nzgrocery --help
```
**Browser.** Woolworths needs no browser. PAK'nSAVE and New World use Playwright's headless Chromium, which pip/pipx/uvx do not download. Run `nzgrocery install-browser` once (it calls `python -m playwright install chromium` inside the tool's own environment, so it works under pipx and uvx where a bare `playwright` command is not on your PATH). Add `--with-deps` on a bare Linux server to also install Chromium's system libraries (may need sudo). `nzgrocery install-browser --check` reports whether Chromium is present. If you forget, a PAK'nSAVE or New World scrape exits with code 3 and tells you to run it.
Upgrade with `pipx upgrade nz-supermarket-scraper` or `uv tool upgrade nz-supermarket-scraper` (`uvx` picks up new releases by itself; force it with `uvx nz-supermarket-scraper@latest`). If Playwright was upgraded, run `install-browser` again.
**From source** (development):
```bash
git clone https://github.com/maxazure/nz-supermarket-scraper.git
cd nz-supermarket-scraper
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
nzgrocery install-browser
pytest -q
```
Maintainers: releases go to PyPI through `.github/workflows/publish.yml` (Trusted Publishing on a `v*` tag). See [CONTRIBUTING.md](https://github.com/maxazure/nz-supermarket-scraper/blob/main/CONTRIBUTING.md#releasing-to-pypi).
## Usage
List the bundled New Zealand stores. With no `--region`, this is the whole country, offline:
```bash
nzgrocery stores
nzgrocery stores --chain paknsave
nzgrocery stores --region auckland
nzgrocery stores --region canterbury --search Riccarton
nzgrocery stores --regions
nzgrocery stores --json
```
`--live` reads the cached live catalogue (7 days) and fetches it only when that cache is missing or expired. `--region` filters a region name, case-insensitively (`auckland`, `waikato`, `canterbury`, or `all`).
```bash
nzgrocery stores --live --chain paknsave
nzgrocery stores --live --region auckland --chain woolworths --json
```
Scrape. `--store` is resolved from the bundled nationwide list and the local cache before any network call. If today's snapshot is already stored, the command does not contact the supermarket. The live store list is fetched only when the store is not known locally or that cache has expired.
```bash
# Woolworths Browns Bay, fresh produce. Writes the local cache; no network if today is already stored.
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce
# New World Browns Bay meat, CSV
nzgrocery scrape --chain newworld --store "Browns Bay" --department meat \
--format csv --output browns-bay-meat.csv
# PAK'nSAVE Albany, produce and meat, SQLite
nzgrocery scrape --chain paknsave --store Albany --department all \
--format sqlite --output prices.sqlite
# Fetch and parse, do not write
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce --dry-run -v
```
`--format` is `sqlite` (default), `csv`, `json`, or `jsonl`. `--output -` writes CSV, JSON, or JSONL to stdout. If you omit `--output` for those formats, the file is dated and stored beside the cache database, for example `~/.local/share/nzgrocery/woolworths-woolworths-browns-bay-produce-2026-10-12.csv`.
A daily cron entry, spaced by the scraper's own 2–4 second delay. A second run the same day is a cache hit and does not scrape again:
```cron
0 7 * * * $HOME/.local/bin/nzgrocery scrape --chain paknsave --store Albany --department all
```
`python -m nzgrocery` runs the same CLI.
## Local cache
From 0.2.0 the tool is local-first. Prices are fetched once into a shared SQLite file, and later questions are answered from that file. A scrape contacts the supermarket only when that chain, store, and department has no snapshot for today's Pacific/Auckland date.
Default database:
| Platform | Path |
| --- | --- |
| Linux and other | `$XDG_DATA_HOME/nzgrocery/prices.sqlite`, or `~/.local/share/nzgrocery/prices.sqlite` |
| macOS | `~/Library/Application Support/nzgrocery/prices.sqlite` |
| Windows | `%LOCALAPPDATA%\nzgrocery\prices.sqlite` |
`NZGROCERY_DB` is a full file path and wins over everything else. `NZGROCERY_DATA` is a directory; the file is `prices.sqlite` inside it. `--db PATH` overrides both for one command. In 0.1.0 the default SQLite file was `./prices.sqlite` in the current directory.
```bash
nzgrocery status # what is already saved
nzgrocery status --json
nzgrocery prices --chain woolworths --store "Browns Bay" --search banana
nzgrocery prices --chain woolworths --store "Browns Bay" --department produce --format json
nzgrocery compare --search broccoli --store "Browns Bay"
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce
```
`prices` (alias `query`) and `compare` read the cache only. They do not open a network connection unless you pass `--fetch-if-missing`, which requires `--chain` and `--store` and scrapes only the departments still missing today. `status` (alias `cache`) lists snapshots, newest first, for the last 7 New Zealand days (`--days 0` shows all). A missing database prints an empty list and exits 0.
CSV, JSON, and JSONL default to `<cache dir>/<chain>-<store-slug>-<department>-<YYYY-MM-DD>.<ext>`. If that file already exists, or today's rows are in the database, the command reuses them and does not scrape. Pass `--output` to choose a path (`--output -` writes to stdout). For `--format sqlite`, `--output` is the database and replaces `--db`.
`--no-cache` (alias `--force`) refreshes today's snapshot and overwrites today's file. If the newest snapshot for that store and department is younger than `NZGROCERY_MIN_INTERVAL_MINUTES` (default 10 minutes; set `0` to disable), the refresh is refused: a warning goes to stderr, the cached summary is printed with `"force_refused": true` and `"retry_after_minutes"`, and the exit code is 0.
Exit code `5` means `prices` or `compare` found no local snapshot for that store, department, and date. stderr includes the `nzgrocery scrape` command that fetches it. If some requested stores have a snapshot and others do not, the command exits 0 and stdout is only the rows that exist. stderr prints one `note:` per missing target (`prices --department all` notes each of produce and meat; `compare` notes each chain and store) with the `scrape` command. If snapshots exist but the product search matches nothing, the command prints `no matching products` and exits 0.
### Store switching
`--store` accepts a store id or a name fragment, case-insensitive.
- An exact id wins, including a Foodstuffs UUID.
- Otherwise the fragment must occur in the store name. `Browns Bay` matches `Woolworths Browns Bay` on the Woolworths list and `New World Browns Bay` on the New World list.
- `Albany` inside PAK'nSAVE matches `PAK'nSAVE Albany` only. The same word on a mixed list also matches `New World Albany`, and the command asks you to be more specific.
- If several names contain the fragment, an exact name wins (`Woolworths Ashburton` rather than `Woolworths Ashburton South`). A query that is still tied, such as `Ashburton` on Woolworths, exits with code 2 and lists the candidates with their region.
- `PAK'nSAVE` and `PAKnSAVE` compare equal, so `PAK'nSAVE Wairau Road` matches the store named `PAKnSAVE Wairau Road`.
Nothing is written unless the site confirms the store. Foodstuffs requires the chosen name to contain the query, unless you passed the store id. Woolworths requires `GET /api/v1/shell` to report `method=Pickup`, the same pickup address id and name, and every product page's `fulfilmentStoreId` must stay on that store.
### Bundled New Zealand list
`src/nzgrocery/stores/nz.json` ships with the package, so `nzgrocery stores` works offline for the whole country.
Generated on 2026-10-12 from the live store APIs: **396 stores** — PAK'nSAVE 58, New World 149, Woolworths 189. Auckland is a filter on that file, not a separate list. `nzgrocery stores --region auckland` is **108 stores** (PAK'nSAVE 19, New World 31, Woolworths 58, including Waiheke Island).
Every store has a `region`, a suburb or city, a postcode, and latitude/longitude when the chain publishes them. Foodstuffs `region` is `physicalAddress.regionName`, and `suburb` is the suburb when the site sends one, otherwise the city (`extra.city` keeps the city name). Woolworths `region` is the store-area name with a trailing parenthesis removed, so `Auckland (North)` becomes `Auckland`. Combined areas use the Foodstuffs region names: `Manawatu/Wanganui` becomes `Manawatu-Wanganui`; `Otago/Southland` is `Southland` when the suburb, city, address, or name mentions Invercargill, Waikiwi, Gore, Winton, or Te Anau, otherwise `Otago`; `Nelson/Malborough` is `Marlborough` for Blenheim, Picton, Redwoodtown, or Springlands, otherwise `Nelson`. The raw area stays in `extra.area`. Waiheke Island is region Auckland. Woolworths does not publish coordinates. Pickup stores whose fulfilment id has been resolved also carry `extra.fulfilment_store_id` (Woolworths Browns Bay: pickup id `2683184`, store id `9254`).
```bash
nzgrocery stores --region auckland --chain woolworths
nzgrocery stores --region waikato --search Hamilton
nzgrocery stores --city Riccarton
nzgrocery stores --regions
```
`nzgrocery stores --regions` prints each region name with a store count. `--city` and `--search` filter the name, suburb, city, or address.
Regenerate the file from the live APIs. Run it from the repo root. Store-list responses are cached for 7 days; pass `--no-cache` to refresh them:
```bash
nzgrocery update-stores
nzgrocery update-stores --resolve-woolworths-ids
```
`--resolve-woolworths-ids` selects each Woolworths pickup address that is not already in the fulfilment-id cache and stores `extra.fulfilment_store_id` from `/api/v1/shell`. Progress is written after every store to `<data dir>/reference/woolworths-fulfilment-ids.json` (kept for 30 days), so an interrupted run continues instead of starting again. Requests stay 2–4 seconds apart.
### Reference data
Store lists, category trees, and Woolworths fulfilment ids follow the same rule as prices: fetch once, then reuse the local file. They live in `<data dir>/reference/`, the directory of the default price database (`default_db_path()`), not next to a one-off `--db` file.
| File | Contents | TTL |
| --- | --- | --- |
| `stores-<chain>.json` | Live store list for `paknsave`, `newworld`, or `woolworths` | 7 days |
| `<chain>-categories.json` | Department, aisle, or facet tree from the guest catalogue | 7 days |
| `woolworths-fulfilment-ids.json` | Pickup address id to `fulfilmentStoreId`, including a partial run | 30 days |
`nzgrocery stores --live` and `nzgrocery update-stores` read those files until the TTL passes. `--no-cache` (alias `--force`) on that command refreshes them. A scrape resolves the store from `nz.json` plus a fresh cached live list, and downloads the live list only when the store is not there or that cache has expired. The guest session still confirms the store (Foodstuffs name check, Woolworths PUT and `/shell`). Session tokens and cookies are not saved.
`NZGROCERY_REFERENCE_TTL_DAYS` is an integer that overrides every TTL. `0` always refreshes. `nzgrocery status` lists the reference files. In `--json` the key is `reference`, and each item has `file`, `fetched_at`, `age` (seconds), `ttl` (days), and `expired`.
### Output schema
SQLite table `prices` (also the CSV header and the JSON objects). Rows are inserted, never updated.
| Column | Meaning |
| --- | --- |
| id | Autoincrement primary key (SQLite only) |
| scraped_at | ISO timestamp in Pacific/Auckland |
| chain | `paknsave`, `newworld`, or `woolworths` |
| store_id | Foodstuffs store UUID, or Woolworths pickup address id |
| store | Store name confirmed for this run |
| department | `produce` or `meat` |
| category | Foodstuffs category tree, or Woolworths `Department / aisle` |
| name | Product name |
| price_nzd | Shelf price in NZD. Woolworths club prices stay in `raw_price_text` |
| unit_or_size | `each`, `kg`, or the pack size |
| price_per | Comparative or cup price, such as `$3.99 / 1kg` |
| product_url | Product page on the chain's site |
| raw_price_text | Shelf price plus promo, club, or multibuy notes |
| product_id | Foodstuffs `productId` or Woolworths SKU |
Indexes: `(chain, store_id, scraped_at)`, `(chain, store_id, department, scraped_at)`, and `product_id`.
A snapshot is the rows that share one `chain`, `store_id`, `store`, `department`, and `scraped_at`. The New Zealand date is `scraped_at` converted to Pacific/Auckland. Naive timestamps are already New Zealand local time.
Exit codes: `0` saved, served from cache, or a dry run with rows, `2` store selection or verification failed, `3` blocked or other HTTP error (Akamai 403, Cloudflare, non-200), `4` no rows, `5` a read command found no local snapshot. A failed scrape does not write a file.
### How it works
**Foodstuffs (PAK'nSAVE and New World).** The HTML shop is often a Cloudflare Turnstile page. Playwright Chromium opens the homepage and does not click the challenge. From that browser context the scraper calls the guest catalogue the site uses:
1. `POST /api/user/get-current-user` with `fingerprintUser` `nz-supermarket-scraper` and the browser user agent, for a short-lived anonymous token.
2. `GET https://api-prod.paknsave.co.nz/v1/edge/store` or `GET https://api-prod.newworld.co.nz/v1/edge/store`, unless the store was already resolved from the bundled list or a fresh reference cache.
3. `POST …/search/paginated/products` filtered to `category0NI:"Fruit & Vegetables"` or `category0NI:"Meat, Poultry & Seafood"` at the chosen store. Facet data in that response is saved as reference data when the category cache is stale.
Shelf price is `singlePrice.price` in cents, converted to NZD. Requests are spaced 2–4 seconds apart.
**Woolworths NZ.** Akamai blocks Playwright and plain Python clients by TLS fingerprint, so this uses `curl_cffi` with `impersonate="chrome"` and the guest calls the website makes:
1. `GET https://www.woolworths.co.nz/` for the guest session.
2. `GET /api/v1/addresses/pickup-addresses`, unless the store was already resolved locally.
3. `PUT /api/v1/fulfilment/my/pickup-addresses` with `{"addressId": <id>}` on that guest session. The department tree in this response is cached when `woolworths-categories.json` is stale. The PUT itself still runs.
4. `GET /api/v1/shell` must report pickup for that address id and name.
5. `GET /api/v1/products?target=browse&dasFilter=Department;;<dept>;false` (and aisle or shelf filters), with header `x-requested-with: OnlineShopping.WebApp`.
The same 2–4 second delay sits between requests. The first request of a session is not delayed.
### Departments
**Produce**
- Foodstuffs root `Fruit & Vegetables`. `Salad Toppers & Dressings` is skipped. Pet food and frozen food sit under other roots, so they are already out.
- Woolworths department `fruit-veg` (Fruit & Veg). Aisles: Fruit, Vegetables, Fresh Salad & Herbs, Prepared Fruit & Veg. The Floral aisle is excluded, and so are the Salad Toppers and In Season Floral shelves.
**Meat**
- Foodstuffs root `Meat, Poultry & Seafood`, keeping fresh beef, pork, lamb, chicken, mince, offal, game, and seafood. Skipped level-1 labels: `Deli Meats`, `Deli Meats & Smoked Fish`, `Plant Based Alternatives`, `Makeaways`, `Dairy Free & Meat Free`. Skipped level-2 labels include `Ham & Pork Slices`, `Salami & Cured Meats`, `Smoked Salmon & Fish`, `Pre-Cooked Sausages`, ready-to-eat counter items (`Breakfast Bacon and Egg Muffin`, `Chicken Burger Bacon Stack`, `Cheesy Taco Wrap`, `Meatball Sub Sandwich`), and the plant-based labels `Vegetarian Meat & Falafel`, `Chicken & Mince Alternatives`, `Plant Based Sausages & Patties`, plus `Fridge, Deli & Eggs`.
- Woolworths `meat-poultry` (Beef, Chicken & Poultry, Lamb, Pork, Venison & Game, Mince & Patties, Sausages, Offal & Bones; Plant Based Alternatives excluded) plus `fish-seafood` (Fish, Salmon, Prawns & Seafood).
Woolworths rows are the union of the aisle listings and the department listing, de-duplicated by SKU. `category` is `Department / first matching aisle`, or just the department when the product only showed up in a promo aisle such as In Season. `price_nzd` is the non-member shelf price. A club price is recorded as `$5.99; Club price $4.50`. A special is `special, was $X`. Multibuy is `2 for $8.00`. `unit_or_size` is `kg` for by-weight items, otherwise the pack size. `price_per` is the site's cup price.
### Limitations
These are undocumented APIs. Field names, category labels, and anti-bot rules change without notice. Prices are online prices and can differ from the shelf in the shop. Woolworths pricing appears to be national once a pickup store is selected; the store check is still required so a response from the wrong fulfilment store is never saved. Club and member prices are not written into `price_nzd`; they are noted in `raw_price_text`.
### Responsible use
Respect each site's terms of use and robots rules. Keep request rates low (the tool already waits 2–4 seconds between requests). This is for personal, research, and non-commercial use. Do not redistribute the scraped data in bulk.
This project is not affiliated with or endorsed by Foodstuffs North Island, Foodstuffs South Island, or Woolworths New Zealand. PAK'nSAVE, New World, and Woolworths are trademarks of their owners. Use at your own risk.
## Use as an AI agent skill
The repo ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents how to install and run `nzgrocery`: finding stores, switching store with `--chain`/`--store`, scraping produce and meat, output formats, exit codes, querying the SQLite results, refreshing the store list, polite-use rules, and troubleshooting (Playwright Chromium, Akamai and Cloudflare blocks).
The source of truth is [`skills/nz-supermarket-scraper/`](https://github.com/maxazure/nz-supermarket-scraper/tree/main/skills/nz-supermarket-scraper) (`SKILL.md`, `references/`, `scripts/latest_prices.py`). Each agent's project folder holds a real copy, not a symlink, so Windows checkouts work too:
| Agent | Project skill (already in this repo) | User-level (all projects) |
| --- | --- | --- |
| Claude Code | `.claude/skills/nz-supermarket-scraper/` | `~/.claude/skills/nz-supermarket-scraper/`, or the plugin below |
| OpenAI Codex | `.agents/skills/nz-supermarket-scraper/` | `~/.agents/skills/nz-supermarket-scraper/` |
| Tencent WorkBuddy | `.workbuddy/skills/nz-supermarket-scraper/` | Upload the zip in the app, or `~/.workbuddy/skills/nz-supermarket-scraper/` |
`AGENTS.md` (read by Codex and other agents) and `CLAUDE.md` (imports `AGENTS.md`) point agents to the skill.
**Project level.** Clone the repo and open it in Claude Code, Codex, or WorkBuddy. The skill is discovered automatically. Ask something like "get Woolworths Browns Bay fruit and veg prices", or invoke it directly: `/nz-supermarket-scraper` in Claude Code, `$nz-supermarket-scraper` (or `/skills`) in Codex.
**User level, from a clone:**
```bash
git clone https://github.com/maxazure/nz-supermarket-scraper.git
cd nz-supermarket-scraper
# Claude Code
mkdir -p ~/.claude/skills && cp -R skills/nz-supermarket-scraper ~/.claude/skills/
# OpenAI Codex
mkdir -p ~/.agents/skills && cp -R skills/nz-supermarket-scraper ~/.agents/skills/
# WorkBuddy
mkdir -p ~/.workbuddy/skills && cp -R skills/nz-supermarket-scraper ~/.workbuddy/skills/
```
On macOS and Linux you can use `ln -s "$PWD/skills/nz-supermarket-scraper" ~/.claude/skills/` instead of `cp` so a `git pull` updates the skill. Claude Code and Codex both document following symlinked skill folders. For WorkBuddy, prefer a copy.
**Claude Code plugin.** The repo root is also a Claude Code plugin marketplace:
```text
/plugin marketplace add maxazure/nz-supermarket-scraper
/plugin install nz-supermarket-scraper@nz-supermarket-scraper
```
The skill then runs as `/nz-supermarket-scraper:nz-supermarket-scraper`.
**Codex skill installer.** In Codex, run `$skill-installer` and ask it to install `https://github.com/maxazure/nz-supermarket-scraper/tree/main/skills/nz-supermarket-scraper`.
**WorkBuddy upload.** Download [`nz-supermarket-scraper-skill.zip`](https://github.com/maxazure/nz-supermarket-scraper/releases/latest/download/nz-supermarket-scraper-skill.zip). `SKILL.md` sits at the root of the zip. In WorkBuddy open **Experts · Skills · Connectors → Skills → Add Skill → Upload Skill** and select the zip. WorkBuddy runs a security check and saves uploaded skills in your user configuration directory, so they work in every project.
The skill tells the agent to install the CLI itself (`pipx install nz-supermarket-scraper` or `uvx nz-supermarket-scraper`, plus `nzgrocery install-browser`) when `nzgrocery` is missing.
**Editing the skill.** Change only `skills/nz-supermarket-scraper/`, then run:
```bash
python3 scripts/sync_skills.py # refresh the .claude / .agents / .workbuddy copies
python3 scripts/sync_skills.py --zip # also rebuild dist/nz-supermarket-scraper-skill.zip
```
`pytest` (`tests/test_skill.py`) fails if a copy drifts, if the frontmatter leaves the portable Agent Skills fields (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`), or if the helper script breaks.
Sources: Claude Code [skills](https://code.claude.com/docs/en/skills) and [plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces). Codex [skills](https://developers.openai.com/codex/skills) and [AGENTS.md](https://developers.openai.com/codex/guides/agents-md). WorkBuddy [skills (中文)](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) and [Tencent Cloud](https://www.tencentcloud.com/document/product/1316/84503). WorkBuddy's official pages describe zip upload and say a skill can live in a "project skills directory" or the user configuration directory, but they do not name the folders. The `.workbuddy/skills` and `~/.workbuddy/skills` paths come from community projects and the [vercel-labs/skills WorkBuddy entry](https://github.com/vercel-labs/skills/issues/1353). If your WorkBuddy build doesn't pick up the folder, use the zip upload.
---
# nz-supermarket-scraper(简体中文)
`nzgrocery` 从新西兰三家超市抓取新鲜果蔬和新鲜肉类的价格。它不登录、不加购物车、也不提交任何个人数据。每次运行只追加一份新的价格快照,已有记录保持原样。
价格来自这些网站在选定门店之后自己调用的访客目录接口。部门名称、货架 slug 和跳过列表都是从这些接口里读到的,不是凭空编的。
## 支持的连锁
| 连锁 | 说明 | 读取方式 |
| --- | --- | --- |
| PAK'nSAVE | Foodstuffs | Playwright 打开首页,再读访客目录。不破解、不点击 Turnstile 人机验证。 |
| New World | Foodstuffs | 与 PAK'nSAVE 相同的访客目录,站点是 `newworld.co.nz`。 |
| Woolworths NZ | 前身为 Countdown | `curl_cffi` 模拟 Chrome 的 TLS/HTTP2 指纹。Akamai 会拒绝非浏览器客户端。 |
## 安装
需要 Python 3.10 以上。PyPI 上的包名是 `nz-supermarket-scraper`,装好后有两个完全一样的命令:`nzgrocery` 和 `nz-supermarket-scraper`。不用下载源代码。
**pipx**(装一次,独立环境,命令一直可用):
```bash
pipx install nz-supermarket-scraper
nzgrocery install-browser # 给 PAK'nSAVE / New World 下载 Chromium(只需一次,约 150 MB)
nzgrocery stores --chain woolworths
```
**uvx**(不用正式安装,直接运行):
```bash
uvx nz-supermarket-scraper stores --chain woolworths
uvx nz-supermarket-scraper install-browser
uvx nz-supermarket-scraper scrape --chain woolworths --store "Browns Bay" --dry-run
```
想用 uv 长期安装:`uv tool install nz-supermarket-scraper`。在虚拟环境里直接 `pip install nz-supermarket-scraper` 也可以。
在第一个 PyPI 版本发布之前,可以直接从 GitHub 安装:
```bash
pipx install "git+https://github.com/maxazure/nz-supermarket-scraper"
uvx --from "git+https://github.com/maxazure/nz-supermarket-scraper" nzgrocery --help
```
**浏览器。** Woolworths 不需要浏览器。PAK'nSAVE 和 New World 要用 Playwright 的无头 Chromium,pip/pipx/uvx 安装时不会自动下载。装好后运行一次 `nzgrocery install-browser` 即可(它在工具自己的环境里执行 `python -m playwright install chromium`,所以在 pipx 和 uvx 下也能用,这时 PATH 上并没有单独的 `playwright` 命令)。在全新的 Linux 服务器上加 `--with-deps`,顺便装 Chromium 需要的系统库(可能要 sudo)。`nzgrocery install-browser --check` 可以检查 Chromium 是否已装好。如果忘了装,抓 PAK'nSAVE 或 New World 时会以退出码 3 结束,并提示你运行这个命令。
升级:`pipx upgrade nz-supermarket-scraper` 或 `uv tool upgrade nz-supermarket-scraper`(`uvx` 会自己用新版本,想强制更新就用 `uvx nz-supermarket-scraper@latest`)。如果 Playwright 也升级了,再运行一次 `install-browser`。
**从源码安装**(开发用):
```bash
git clone https://github.com/maxazure/nz-supermarket-scraper.git
cd nz-supermarket-scraper
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
nzgrocery install-browser
pytest -q
```
维护者:发布到 PyPI 走 `.github/workflows/publish.yml`(推送 `v*` 标签后通过 Trusted Publishing 自动上传,不需要在 GitHub 存 token)。详见 [CONTRIBUTING.md](https://github.com/maxazure/nz-supermarket-scraper/blob/main/CONTRIBUTING.md#releasing-to-pypi)。
## 用法
列出随包附带的新西兰全国门店。不加 `--region` 时是全国,并且离线:
```bash
nzgrocery stores
nzgrocery stores --chain paknsave
nzgrocery stores --region auckland
nzgrocery stores --region canterbury --search Riccarton
nzgrocery stores --regions
nzgrocery stores --json
```
`--live` 读取缓存的线上门店目录(7 天),只有缓存缺失或过期时才重新拉取。`--region` 按地区名过滤,不区分大小写(`auckland`、`waikato`、`canterbury`,或 `all`)。
```bash
nzgrocery stores --live --chain paknsave
nzgrocery stores --live --region auckland --chain woolworths --json
```
抓取价格。`--store` 会先在附带的全国清单和本地缓存里解析。能对上并且今天已经有快照时,不会访问超市网站。只有本地不认识这家店,或者线上门店缓存已经过期时,才去拉线上门店列表。
```bash
# Woolworths Browns Bay,新鲜果蔬。写入本地缓存;如果今天已经抓过,就不再上网。
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce
# New World Browns Bay 肉类,CSV
nzgrocery scrape --chain newworld --store "Browns Bay" --department meat \
--format csv --output browns-bay-meat.csv
# PAK'nSAVE Albany,果蔬和肉类都抓,SQLite
nzgrocery scrape --chain paknsave --store Albany --department all \
--format sqlite --output prices.sqlite
# 只抓取和解析,不写文件
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce --dry-run -v
```
`--format` 可以是 `sqlite`(默认)、`csv`、`json` 或 `jsonl`。`--output -` 把 CSV、JSON 或 JSONL 打到标准输出。这三种格式如果省略 `--output`,文件会按日期写在缓存目录旁边,例如 `~/.local/share/nzgrocery/woolworths-woolworths-browns-bay-produce-2026-10-12.csv`。
每天跑一次的 cron 示例。请求间隔由程序自己控制在 2–4 秒。同一天再跑一次会命中缓存,不会重复抓取:
```cron
0 7 * * * $HOME/.local/bin/nzgrocery scrape --chain paknsave --store Albany --department all
```
`python -m nzgrocery` 是同一套命令。
## 本地缓存
从 0.2.0 起,这个工具以本地数据为先。价格只抓一次,写进一份共享的 SQLite 文件,之后的问题都从这份文件回答。只有当这家连锁、这家店、这个部门在今天(Pacific/Auckland 的日历日)还没有快照时,才会去访问超市网站。
默认数据库:
| 系统 | 路径 |
| --- | --- |
| Linux 及其他 | `$XDG_DATA_HOME/nzgrocery/prices.sqlite`,否则 `~/.local/share/nzgrocery/prices.sqlite` |
| macOS | `~/Library/Application Support/nzgrocery/prices.sqlite` |
| Windows | `%LOCALAPPDATA%\nzgrocery\prices.sqlite` |
`NZGROCERY_DB` 是完整文件路径,优先级最高。`NZGROCERY_DATA` 是目录,文件名固定为里面的 `prices.sqlite`。单次命令可以用 `--db PATH` 覆盖。0.1.0 的默认 SQLite 文件是当前目录下的 `./prices.sqlite`。
```bash
nzgrocery status # 本地已经存了什么
nzgrocery status --json
nzgrocery prices --chain woolworths --store "Browns Bay" --search banana
nzgrocery prices --chain woolworths --store "Browns Bay" --department produce --format json
nzgrocery compare --search broccoli --store "Browns Bay"
nzgrocery scrape --chain woolworths --store "Browns Bay" --department produce
```
`prices`(别名 `query`)和 `compare` 只读本地缓存。除非加上 `--fetch-if-missing`,否则不会联网。这个参数需要 `--chain` 和 `--store`,并且只抓今天还缺的部门。`status`(别名 `cache`)列出快照,新的在前,默认是最近 7 个新西兰日(`--days 0` 表示全部)。数据库文件不存在时打印空列表,退出码 0。
CSV、JSON、JSONL 的默认文件名是 `<缓存目录>/<chain>-<店名 slug>-<department>-<YYYY-MM-DD>.<ext>`。这个文件已经存在,或者数据库里已有今天的记录时,命令直接复用,不再抓取。用 `--output` 指定路径(`--output -` 打到标准输出)。`--format sqlite` 时,`--output` 就是数据库本身,并取代 `--db`。
`--no-cache`(别名 `--force`)会刷新今天的快照,并覆盖今天的导出文件。如果这家店这个部门最新一份快照比 `NZGROCERY_MIN_INTERVAL_MINUTES`(默认 10 分钟;设为 `0` 表示不限制)还新,刷新会被拒绝:警告打到 stderr,缓存摘要里带 `"force_refused": true` 和 `"retry_after_minutes"`,退出码仍是 0。
退出码 `5` 表示 `prices` 或 `compare` 在本地找不到该门店、部门和日期的快照。stderr 里会给出对应的 `nzgrocery scrape` 命令。如果请求的门店里只有一部分有快照,命令退出码仍是 0,stdout 只包含有数据的那些行。stderr 对每个缺失目标打印一行 `note:`(`prices --department all` 会把 produce 和 meat 分开记;`compare` 按连锁和门店各记一行),并给出对应的 `scrape` 命令。如果快照存在,只是商品搜索没有命中,命令打印 `no matching products`,退出码 0。
### 切换门店
`--store` 可以是门店 id,也可以是名称片段,不区分大小写。
- 精确的 id 优先,包括 Foodstuffs 的 UUID。
- 否则片段必须出现在店名里。在 Woolworths 列表上,`Browns Bay` 对应 `Woolworths Browns Bay`;在 New World 列表上对应 `New World Browns Bay`。
- 只在 PAK'nSAVE 里搜 `Albany`,只会命中 `PAK'nSAVE Albany`。混在一起搜时,`New World Albany` 也会命中,命令会要求你写得更具体。
- 多个店名都包含该片段时,完整店名优先(例如 `Woolworths Ashburton`,而不是 `Woolworths Ashburton South`)。仍然分不清的查询,比如 Woolworths 里的 `Ashburton`,以退出码 2 结束,并列出候选店及其地区。
- `PAK'nSAVE` 和 `PAKnSAVE` 视为相同,因此 `PAK'nSAVE Wairau Road` 能匹配店名 `PAKnSAVE Wairau Road`。
站点没有确认门店之前,不会写任何文件。Foodstuffs:除非你给的是门店 id,否则选中的店名必须包含查询词。Woolworths:`GET /api/v1/shell` 必须返回 `method=Pickup`、同一个自提地址 id 和店名,并且每一页商品的 `fulfilmentStoreId` 都必须仍是这家店。
### 附带的全国门店清单
`src/nzgrocery/stores/nz.json` 随包发布,所以 `nzgrocery stores` 可以离线列出新西兰全国门店。
清单于 2026-10-12 从各家线上门店接口生成:**共 396 家** —— PAK'nSAVE 58 家、New World 149 家、Woolworths 189 家。奥克兰只是这份清单上的一个过滤条件。`nzgrocery stores --region auckland` 是 **108 家**(PAK'nSAVE 19 家、New World 31 家、Woolworths 58 家,含 Waiheke 岛)。
每家店都有 `region`、市郊或城市、邮编,以及连锁网站提供时的经纬度。Foodstuffs 的 `region` 来自 `physicalAddress.regionName`;`suburb` 有市郊时用市郊,否则用城市(`extra.city` 保留城市名)。Woolworths 的 `region` 是门店区域名去掉括号后的部分,例如 `Auckland (North)` 变成 `Auckland`。合并区域改成和 Foodstuffs 一样的地区名:`Manawatu/Wanganui` 变成 `Manawatu-Wanganui`;`Otago/Southland` 在市郊、城市、地址或店名里出现 Invercargill、Waikiwi、Gore、Winton、Te Anau 时归 `Southland`,否则归 `Otago`;`Nelson/Malborough` 在出现 Blenheim、Picton、Redwoodtown 或 Springlands 时归 `Marlborough`,否则归 `Nelson`。原始区域留在 `extra.area`。Waiheke 岛的地区是 Auckland。Woolworths 不提供坐标。已经解析过的自提门店还带 `extra.fulfilment_store_id`(例如 Woolworths Browns Bay:自提 id `2683184`,门店 id `9254`)。
```bash
nzgrocery stores --region auckland --chain woolworths
nzgrocery stores --region waikato --search Hamilton
nzgrocery stores --city Riccarton
nzgrocery stores --regions
```
`nzgrocery stores --regions` 列出每个地区名和门店数量。`--city` 和 `--search` 按店名、市郊、城市或地址过滤。
在仓库根目录用线上接口重新生成。门店列表会缓存 7 天;要刷新就加 `--no-cache`:
```bash
nzgrocery update-stores
nzgrocery update-stores --resolve-woolworths-ids
```
`--resolve-woolworths-ids` 只对履行门店 id 缓存里还没有的 Woolworths 自提地址发请求,并从 `/api/v1/shell` 记下 `extra.fulfilment_store_id`。每成功一家就写入 `<数据目录>/reference/woolworths-fulfilment-ids.json`(保留 30 天),所以中断后可以接着跑,不必从头再来。请求之间仍然等待 2–4 秒。
### 参考数据
门店列表、分类树和 Woolworths 履行门店 id 与价格一样:拉取一次,之后用本地文件。它们在 `<数据目录>/reference/`,也就是默认价格数据库所在的目录(`default_db_path()` 的父目录),不是某次 `--db` 旁边。
| 文件 | 内容 | 有效期 |
| --- | --- | --- |
| `stores-<chain>.json` | `paknsave`、`newworld` 或 `woolworths` 的线上门店列表 | 7 天 |
| `<chain>-categories.json` | 访客目录里的部门、货架或 facet 树 | 7 天 |
| `woolworths-fulfilment-ids.json` | 自提地址 id 到 `fulfilmentStoreId`,包括只跑完一部分的进度 | 30 天 |
`nzgrocery stores --live` 和 `nzgrocery update-stores` 在有效期内直接读这些文件。在这两条命令上加 `--no-cache`(别名 `--force`)会刷新。抓取价格时,门店先从 `nz.json` 和未过期的线上列表缓存里解析;只有本地没有这家店,或者那份缓存过期了,才下载线上列表。访客会话仍然会确认门店(Foodstuffs 的店名检查,Woolworths 的 PUT 和 `/shell`)。会话 token 和 cookie 不会保存。
`NZGROCERY_REFERENCE_TTL_DAYS` 设成整数时,会同时覆盖上面三个有效期。`0` 表示每次都刷新。`nzgrocery status` 会列出这些参考文件。`--json` 里的键是 `reference`,每一项包含 `file`、`fetched_at`、`age`(秒)、`ttl`(天)和 `expired`。
### 输出字段
SQLite 表 `prices`(CSV 表头和 JSON 对象用同一套字段)。只插入,不更新。
| 字段 | 含义 |
| --- | --- |
| id | 自增主键(仅 SQLite) |
| scraped_at | Pacific/Auckland 时区的 ISO 时间 |
| chain | `paknsave`、`newworld` 或 `woolworths` |
| store_id | Foodstuffs 门店 UUID,或 Woolworths 自提地址 id |
| store | 本次确认下来的店名 |
| department | `produce`(果蔬)或 `meat`(肉类) |
| category | Foodstuffs 分类树,或 Woolworths 的 `部门 / 货架` |
| name | 商品名 |
| price_nzd | 货架价,新西兰元。Woolworths 会员价写在 `raw_price_text` |
| unit_or_size | `each`、`kg`,或包装规格 |
| price_per | 对比价或杯价,例如 `$3.99 / 1kg` |
| product_url | 该连锁网站上的商品页 |
| raw_price_text | 货架价,以及促销、会员价、多件价备注 |
| product_id | Foodstuffs 的 `productId`,或 Woolworths SKU |
索引:`(chain, store_id, scraped_at)`、`(chain, store_id, department, scraped_at)` 和 `product_id`。
一份快照是 `chain`、`store_id`、`store`、`department`、`scraped_at` 都相同的那些行。新西兰日期是把 `scraped_at` 换算到 Pacific/Auckland。没有时区的时间戳视为已经是新西兰本地时间。
退出码:`0` 已保存、从缓存返回,或演练运行且解析出了行;`2` 门店选择或校验失败;`3` 被拦截或其他 HTTP 错误(Akamai 403、Cloudflare、非 200);`4` 没有商品行;`5` 读取命令在本地找不到快照。抓取失败时不写文件。
### 工作原理
**Foodstuffs(PAK'nSAVE 和 New World)。** 商店 HTML 经常是 Cloudflare Turnstile 页面。Playwright Chromium 打开首页,不点击验证。随后在这个浏览器上下文里调用网站自己的访客目录:
1. `POST /api/user/get-current-user`,`fingerprintUser` 为 `nz-supermarket-scraper`,`fingerprintGuest` 为浏览器 UA,用来换一个短时匿名 token。
2. `GET https://api-prod.paknsave.co.nz/v1/edge/store` 或 `GET https://api-prod.newworld.co.nz/v1/edge/store`。如果门店已经能从附带清单或未过期的参考缓存里解析出来,就跳过这一步。
3. `POST …/search/paginated/products`,按所选门店过滤 `category0NI:"Fruit & Vegetables"` 或 `category0NI:"Meat, Poultry & Seafood"`。分类缓存过期时,响应里的 facet 会记入参考数据。
货架价是 `singlePrice.price`,单位是分,再换成新西兰元。请求之间间隔 2–4 秒。
**Woolworths NZ。** Akamai 会按 TLS 指纹拦截 Playwright 和普通 Python 客户端,因此这里用 `curl_cffi` 的 `impersonate="chrome"`,并走网站自己的访客调用:
1. `GET https://www.woolworths.co.nz/`,拿到访客会话。
2. `GET /api/v1/addresses/pickup-addresses`。门店已经在本地解析出来时跳过。
3. 在该访客会话上 `PUT /api/v1/fulfilment/my/pickup-addresses`,正文为 `{"addressId": <id>}`。`woolworths-categories.json` 过期时,这次响应里的部门树会写入缓存。PUT 本身每次都会执行。
4. `GET /api/v1/shell` 必须确认该地址 id 和店名的自提方式。
5. `GET /api/v1/products?target=browse&dasFilter=Department;;<dept>;false`(可再加货架或层架过滤),请求头带 `x-requested-with: OnlineShopping.WebApp`。
请求之间同样间隔 2–4 秒。一次会话的第一个请求不等待。
### 部门范围
**果蔬(produce)**
- Foodstuffs 根分类 `Fruit & Vegetables`。跳过 `Salad Toppers & Dressings`。宠物食品和冷冻食品属于别的根分类,本来就不会进来。
- Woolworths 部门 `fruit-veg`(Fruit & Veg)。货架:Fruit、Vegetables、Fresh Salad & Herbs、Prepared Fruit & Veg。排除 Floral 货架,以及 Salad Toppers 和 In Season Floral 层架。
**肉类(meat)**
- Foodstuffs 根分类 `Meat, Poultry & Seafood`,保留新鲜牛肉、猪肉、羊肉、鸡肉、肉末、内脏、野味和海鲜。跳过的一级分类:`Deli Meats`、`Deli Meats & Smoked Fish`、`Plant Based Alternatives`、`Makeaways`、`Dairy Free & Meat Free`。跳过的二级分类包括 `Ham & Pork Slices`、`Salami & Cured Meats`、`Smoked Salmon & Fish`、`Pre-Cooked Sausages`,热食柜台的 `Breakfast Bacon and Egg Muffin`、`Chicken Burger Bacon Stack`、`Cheesy Taco Wrap`、`Meatball Sub Sandwich`,以及植物基的 `Vegetarian Meat & Falafel`、`Chicken & Mince Alternatives`、`Plant Based Sausages & Patties`,还有 `Fridge, Deli & Eggs`。
- Woolworths 的 `meat-poultry`(Beef、Chicken & Poultry、Lamb、Pork、Venison & Game、Mince & Patties、Sausages、Offal & Bones;排除 Plant Based Alternatives)加上 `fish-seafood`(Fish、Salmon、Prawns & Seafood)。
Woolworths 的结果是各货架列表和整个部门列表的并集,按 SKU 去重。`category` 写成 `部门 / 第一个匹配的货架`;如果商品只出现在 In Season 这类促销货架里,则只写部门名。`price_nzd` 是非会员货架价。会员价记成 `$5.99; Club price $4.50`。特价记成 `special, was $X`。多件价记成 `2 for $8.00`。按重量卖的商品 `unit_or_size` 为 `kg`,否则是包装规格。`price_per` 是网站给出的杯价。
### 局限
这些接口没有公开文档。字段名、分类标签和反爬规则都可能在不通知的情况下改变。抓到的是线上价格,可能和店内货架价不同。Woolworths 在选定自提门店之后,价格看起来是全国统一的;尽管如此,仍然要核对门店,避免把别的履约门店的响应存下来。会员价不会写入 `price_nzd`,只出现在 `raw_price_text`。
### 使用时请守规矩
请遵守各网站的使用条款和 robots 规则。把请求频率压低(这个工具已经在每次请求之间等待 2–4 秒)。仅供个人、研究和非商业使用。不要批量转发抓到的数据。
本项目与 Foodstuffs North Island、Foodstuffs South Island、Woolworths New Zealand 没有关联,也未获其认可。PAK'nSAVE、New World 和 Woolworths 是各自权利人的商标。使用风险由你自己承担。
## 作为 AI 智能体技能(Agent Skill)使用
仓库里带了一个 [Agent Skill](https://agentskills.io),教 AI 编程助手安装和使用 `nzgrocery`。内容包括:查找门店,用 `--chain`/`--store` 切换门店,抓取果蔬和肉类,输出格式,退出码,查询 SQLite 结果,刷新门店清单,礼貌使用规则,以及排错(Playwright Chromium、Akamai 和 Cloudflare 拦截)。
唯一的源文件在 [`skills/nz-supermarket-scraper/`](https://github.com/maxazure/nz-supermarket-scraper/tree/main/skills/nz-supermarket-scraper)(`SKILL.md`、`references/`、`scripts/latest_prices.py`)。各个智能体的项目目录里放的是真实副本,不是软链接,所以 Windows 上也能用:
| 智能体 | 项目级(本仓库已自带) | 用户级(所有项目可用) |
| --- | --- | --- |
| Claude Code | `.claude/skills/nz-supermarket-scraper/` | `~/.claude/skills/nz-supermarket-scraper/`,或者用下面的插件 |
| OpenAI Codex | `.agents/skills/nz-supermarket-scraper/` | `~/.agents/skills/nz-supermarket-scraper/` |
| 腾讯 WorkBuddy | `.workbuddy/skills/nz-supermarket-scraper/` | 在应用里上传 zip,或者放到 `~/.workbuddy/skills/nz-supermarket-scraper/` |
`AGENTS.md`(Codex 等智能体会读)和 `CLAUDE.md`(导入 `AGENTS.md`)会把智能体指到这个技能。
**项目级。** 克隆仓库,用 Claude Code、Codex 或 WorkBuddy 打开,技能会被自动发现。直接说“帮我抓 Woolworths Browns Bay 的果蔬价格”就行。也可以手动调用:Claude Code 输入 `/nz-supermarket-scraper`,Codex 输入 `$nz-supermarket-scraper`(或用 `/skills` 选)。
**用户级,从克隆的仓库复制:**
```bash
git clone https://github.com/maxazure/nz-supermarket-scraper.git
cd nz-supermarket-scraper
# Claude Code
mkdir -p ~/.claude/skills && cp -R skills/nz-supermarket-scraper ~/.claude/skills/
# OpenAI Codex
mkdir -p ~/.agents/skills && cp -R skills/nz-supermarket-scraper ~/.agents/skills/
# WorkBuddy
mkdir -p ~/.workbuddy/skills && cp -R skills/nz-supermarket-scraper ~/.workbuddy/skills/
```
在 macOS 和 Linux 上,也可以用 `ln -s "$PWD/skills/nz-supermarket-scraper" ~/.claude/skills/` 代替 `cp`,这样 `git pull` 之后技能会跟着更新。Claude Code 和 Codex 的文档都写明支持软链接的技能目录。WorkBuddy 建议用复制。
**Claude Code 插件。** 仓库根目录同时也是一个 Claude Code 插件市场:
```text
/plugin marketplace add maxazure/nz-supermarket-scraper
/plugin install nz-supermarket-scraper@nz-supermarket-scraper
```
装好后用 `/nz-supermarket-scraper:nz-supermarket-scraper` 调用。
**Codex 技能安装器。** 在 Codex 里运行 `$skill-installer`,让它安装 `https://github.com/maxazure/nz-supermarket-scraper/tree/main/skills/nz-supermarket-scraper`。
**WorkBuddy 上传。** 下载 [`nz-supermarket-scraper-skill.zip`](https://github.com/maxazure/nz-supermarket-scraper/releases/latest/download/nz-supermarket-scraper-skill.zip),`SKILL.md` 就在 zip 的根目录。在 WorkBuddy 里打开 **专家·技能·连接器 → 技能 → 添加技能 → 上传技能**,选中这个 zip。WorkBuddy 会先做安全检查,上传的技能保存在用户配置目录里,所有项目都能用。
如果机器上还没有 `nzgrocery`,技能会让智能体自己安装(`pipx install nz-supermarket-scraper` 或 `uvx nz-supermarket-scraper`,再加 `nzgrocery install-browser`)。
**修改技能。** 只改 `skills/nz-supermarket-scraper/`,改完运行:
```bash
python3 scripts/sync_skills.py # 同步 .claude / .agents / .workbuddy 三份副本
python3 scripts/sync_skills.py --zip # 同时重新生成 dist/nz-supermarket-scraper-skill.zip
```
以下几种情况 `pytest`(`tests/test_skill.py`)会失败:副本和源文件不一致;frontmatter 用了 Agent Skills 通用字段(`name`、`description`、`license`、`compatibility`、`metadata`、`allowed-tools`)以外的字段;辅助脚本出错。
资料来源:Claude Code 的 [skills](https://code.claude.com/docs/en/skills) 和 [插件市场](https://code.claude.com/docs/en/plugin-marketplaces) 文档。Codex 的 [skills](https://developers.openai.com/codex/skills) 和 [AGENTS.md](https://developers.openai.com/codex/guides/agents-md) 文档。WorkBuddy 的 [技能文档](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) 和 [腾讯云文档](https://www.tencentcloud.com/document/product/1316/84503)。WorkBuddy 官方页面讲了 zip 上传,也说技能可以放在“项目技能目录”或用户配置目录,但没有写出具体文件夹名。`.workbuddy/skills` 和 `~/.workbuddy/skills` 这两个路径来自社区项目和 [vercel-labs/skills 的 WorkBuddy 条目](https://github.com/vercel-labs/skills/issues/1353)。如果你的 WorkBuddy 版本没有识别这个文件夹,就用 zip 上传。