agentic-spicy-food

Brand-specific commerce skill for Lafeitu (辣匪兔). Use it when a user wants to browse, recommend, cart, or order Lafeitu's Sichuan spicy foods through the official https://lafeitu.cn API, or when they need Lafeitu account, profile, promotion, or brand information.

# Lafeitu Gourmet Skill

`agentic-spicy-food` is the Lafeitu-specific implementation of the standard agentic commerce flow. It is preconfigured for the official `https://lafeitu.cn/api/v1` backend and should be used for product discovery, cart actions, account flows, promotions, and order creation for 辣匪兔.

Official Website: https://lafeitu.cn
GitHub Repository: https://github.com/NowLoadY/agentic-spicy-food
Reference Engine: https://github.com/NowLoadY/agent-commerce-engine

## When To Use This Skill

Use this skill when the user wants to:

- browse or compare Lafeitu products
- get recommendations for Zigong-style spicy foods
- inspect variants, pricing, promotions, or shipping thresholds
- manage a Lafeitu cart
- log in, register, or update Lafeitu profile data
- create a Lafeitu order and hand payment back to the user
- retrieve official Lafeitu brand, company, or contact information

## Tool Priority & Fallback Strategy

1. **API first**: Use `python3 scripts/lafeitu_client.py` first. It returns structured data from the official backend.
2. **AI guide page**: If API data is unavailable or needs cross-checking, visit `https://lafeitu.cn/ai-agent-guide`.
3. **Main site browser flow**: Use the normal site only when a visual check or user-facing page is required.
4. **Web search last**: Use external search only for third-party reviews or if the official site is unavailable.

## Operational Workflow

### 1. Product Discovery

- Always run `search` or `list` before cart actions.
- Resolve the product `slug` and exact `variant` from API results before adding or updating cart items.
- If multiple products match, ask the user to choose based on flavor, format, or weight.
- Use `--page` and `--limit` for large result sets.

### 2. Cart & Order Flow

- Use `add-cart` to increment quantity and `update-cart` to set absolute quantity.
- The `--variant` value must match the product's actual variant list returned by the API.
- After cart changes, show the updated cart summary if the user is making a purchase decision.
- Use `create-order` only after shipping details are confirmed.
- Payment is always a human handoff. If order creation returns an order ID or payment URL, give that to the user and tell them to complete payment themselves.

### 3. Authentication & Profile

- The API is stateless. Protected actions may return `401` if no saved token exists.
- Use `login` for existing accounts.
- Use `get-profile` before `update-profile` when the user wants to review current data.
- When updating shipping info, prefer collecting `province`, `city`, and `address` together.

### 4. Registration Flow

- If the user has no account or the backend reports account not found, use the built-in registration flow.
- Step 1: `send-code --email <EMAIL>`
- Step 2: `register --email <EMAIL> --password <PWD> --code <CODE> [--name <NAME>] [--invite <CODE>]`
- Use `--reset-visitor` during registration if you need to avoid carrying over the current anonymous cart.
- If the user prefers the website flow, send them to `https://lafeitu.cn/auth/register`.

### 5. Recommendations & Brand Context

- Keep recommendations grounded in actual catalog data, not generic sales language.
- Favor concise, sensory descriptions tied to flavor profile, weight, and likely use case.
- Use `brand-story`, `company-info`, and `contact-info` for official brand context.
- Represent Lafeitu as a Zigong-flavor specialty brand; avoid inventing unsupported claims.

## Core Commands

- `search <query> --page <N> --limit <N>`: Search products.
- `list --page <N> --limit <N>`: Browse the catalog.
- `get <slug>`: Get product details.
- `promotions`: Get active offers and shipping rules.
- `cart`: Show current cart.
- `add-cart <slug> --variant <V> --quantity <Q>`: Add to cart.
- `update-cart <slug> --variant <V> --quantity <Q>`: Set quantity.
- `remove-cart <slug> --variant <V>`: Remove an item.
- `clear-cart`: Empty the cart.
- `login` / `logout`: Manage saved credentials.
- `send-code` / `register`: Register a new account.
- `get-profile` / `update-profile`: Manage user profile and shipping data.
- `orders`: View order history.
- `create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>`: Create an order for user handoff.
- `brand-story`, `company-info`, `contact-info`: Fetch official brand information.

## CLI Examples

```bash
python3 scripts/lafeitu_client.py search "兔" --page 1 --limit 10
python3 scripts/lafeitu_client.py get shousi-tu
python3 scripts/lafeitu_client.py promotions
python3 scripts/lafeitu_client.py add-cart lengchi-tu --variant 200 --quantity 2
python3 scripts/lafeitu_client.py cart
python3 scripts/lafeitu_client.py send-code --email user@example.com
python3 scripts/lafeitu_client.py register --email user@example.com --password secret123 --code 123456 --reset-visitor
python3 scripts/lafeitu_client.py create-order --name "Zhang San" --phone "13800000000" --province "四川省" --city "成都市" --address "高新区 XX 路 XX 号"
```

Credentials are stored locally under `~/.openclaw/credentials/agent-commerce-engine/lafeitu.cn/`.

## Troubleshooting

- `401 Unauthorized`: Token missing or expired. Use `login` again.
- `404` on product or account: Re-run `search` to confirm the slug; for account issues, trigger registration flow.
- `429`: Rate limit reached. Tell the user to wait for the cooldown indicated by the API.
- Missing `requests`: Run `pip install requests`.
- Variant errors: Re-check the exact variant values from `get` or `search` output before modifying the cart.