1688-cli 0.1.24 → 0.1.26

package/AGENTS.md

@@ -4,59 +4,101 @@ When the user asks anything about 1688 sourcing, products, orders, or
 logistics, use the `1688` CLI. It outputs JSON automatically when stdout
 is piped, so `1688 <cmd> | jq` works.
 
-## Current commands (MVP)
+## Current commands
+
+Organized by buyer journey: sourcing → inquiry → cart → checkout → tracking → post-sale.
 
 ```
-1688 login                Show QR code in the terminal; user scans with phone.
-1688 login --headed       Use a real browser window instead (fallback).
-1688 login --force        Re-login even if a session exists.
-1688 search <keyword>     Search 1688 by keyword; --max N to limit.
-1688 search --headed      Open window (use once to pass slider; cached for hours).
-1688 image-search <path>  Search by image (.jpg/.png/.webp local file).
-1688 order list           List buyer orders; --status, --page, --page-size flags.
-1688 order list --status waitbuyerreceive    Filter to "awaiting delivery".
-1688 order get <orderId>  Fetch one order by ID (scans recent pages; --max-scan-pages N).
-1688 order logistics <orderId>  Shipping status + tracking number (mailNo, carrier, remark).
-1688 cart list                  List items in 1688 cart (采购车).
-1688 cart add <offerId> --sku <skuId> --qty N    Add SKU to cart (~15s, UI replay).
-1688 cart remove <cartId>       Remove one cart item (~12s, UI replay).
-1688 checkout prepare <cartId>... Preview total/address/items for checkout (NO order placement, ~12s).
-1688 checkout confirm <cartId>...            PLACE order — TTY+prompt by default.
-1688 checkout confirm <cartId>... --agent    Agent mode: no prompt, daemon-OK.
-                                                MUST be preceded by a `prepare` call shown to the user
-                                                AND explicit user authorization in the current turn.
-1688 offer <offerId>      Full product detail: title, price range, SKUs (with stock), supplier, freight.
-1688 whoami               Print current account, exit 3 if not logged in.
-1688 whoami --verify      Also verify online (slower, ~3s).
-1688 logout               Log out (prompts unless --yes).
-1688 logout --yes         Skip confirmation.
-1688 doctor               Diagnose environment + session state.
-1688 doctor --no-launch   Skip the actual Chromium launch test (faster).
-
-1688 daemon start         Start the background daemon (shared Chromium).
-1688 daemon stop          Stop the daemon.
-1688 daemon status        Show daemon state + stats.
-1688 serve                Run daemon in the foreground.
+# Sourcing
+1688 search <keyword>                       Keyword search; --max N to limit.
+1688 search --headed                        Open window once if a slider verification appears.
+1688 similar <offerId>                      "找同款" — similar offers from other suppliers, sorted by price.
+1688 image-search <pathOrUrl>               Search by image (local .jpg/.png/.webp file or http(s) URL).
+1688 offer <offerId>                        Full product detail: title, priceTiers, SKUs, attributes,
+                                            packageInfo, supplier (loginId/memberId/province/city).
+
+# Pre-sale inquiry (seller IM, scoped by offerId)
+1688 seller inquire <offerId> <message>     Send product link + question to the supplier.
+1688 seller messages --offer <offerId>      Read replies in this offer's conversation.
+1688 seller messages --offer <offerId> --watch [--interval N]
+                                            Live-tail new replies (line-delimited JSON when piped).
+                                            Long-running; min interval 10 s, default 30 s.
+
+# Cart
+1688 cart list                              List items in 1688 cart (采购车).
+1688 cart add <offerId> --sku <skuId> --qty N
+                                            Add SKU to cart (~6 s, mtop hijack). Returns
+                                            {added: CartItem, isNewRow, addedQuantity}.
+1688 cart remove <cartId>                   Remove one cart row (~12 s, UI replay).
+
+# Checkout
+1688 checkout prepare <cartId>...           Preview total/address/items (NO order placement).
+1688 checkout confirm <cartId>...           PLACE order — TTY+prompt by default.
+1688 checkout confirm <cartId>... --agent   Agent mode: no prompt, daemon-OK.
+                                            MUST be preceded by `prepare` shown to the user AND
+                                            explicit user authorization in the current turn.
+
+# Order tracking
+1688 order list                             List buyer orders; --status, --page, --page-size flags.
+                                            Each order has actions[] (buyer ops + URLs), services[]
+                                            (insurance/refund), badges[].
+1688 order list --status waitbuyerreceive   Filter to "awaiting delivery".
+1688 order get <orderId>                    One order by ID (--max-scan-pages N, --status hint).
+1688 order logistics <orderId>              Tracking number + trace (mailNo, carrier, remark).
+1688 shipped <orderId>                      Order detail + logistics merged into one call.
+1688 stuck [--days N]                       Paid but not shipped > N days (default 3).
+1688 fake-shipped [--days N] [--debug]      Marked shipped but courier never collected (虚假发货).
+1688 seller-history <sellerName>            All orders from a seller + avg ship days + on-time rate.
+
+# Post-sale chat (seller IM, scoped by orderId)
+1688 seller chat <orderId|loginId> <message>
+                                            Send to seller. With orderId, auto-attaches the order card.
+1688 seller chat <orderId> <message> --no-card
+                                            Follow-up reply, no card.
+1688 seller messages <orderId>              Read replies in this order's conversation.
+1688 seller messages <orderId> --watch      Live-tail (same as the --offer form above).
+
+# Account & daemon
+1688 login                                  Show QR code; user scans with phone.
+1688 login --headed                         Use a real browser window instead (fallback).
+1688 login --force                          Re-login even if a session exists.
+1688 logout [--yes]                         Log out (prompts unless --yes).
+1688 whoami [--verify]                      Print current account; exit 3 if not logged in.
+1688 doctor [--no-launch]                   Diagnose environment + session state.
+1688 daemon start | stop | status | reload  Manage the background daemon.
+1688 serve                                  Run the daemon in the foreground.
 ```
 
 ## Daemon (recommended for agent use)
 
-When the daemon is running, `search` and `whoami` route through it and share a
-single Chromium context. Benefits:
+When the daemon is running, commands route through it and share a single
+Chromium context. Benefits:
 - ~2-3 seconds saved per command (no Chrome cold start)
-- Looks like one continuous human user to 1688 risk control
-- Built-in inter-command throttle (1.2-3s jitter) keeps WAF score low
+- One continuous logged-in session across commands
+- Built-in inter-command jitter (1.2-3 s)
 
 The agent should call `1688 daemon start` once at the beginning of a session
 that involves multiple 1688 commands. The daemon auto-stops after 30 minutes
-of inactivity.
+of inactivity. Run `1688 daemon reload` after the package updates to pick up
+new code.
 
-`login`, `logout`, `doctor` stay inline; they require interactive UI or browser
+`login`, `logout`, `doctor` stay inline; they need interactive UI or browser
 windows. If the daemon is running and you need to `login --force`, stop the
 daemon first.
 
-```
-```
+## Watch mode (long-running streams)
+
+`1688 seller messages ... --watch` is a long-running command. It:
+- Prints `Baseline: <conversation> — N messages in history` to stderr on start
+- Emits one line of JSON to stdout per **newly-arrived** message (history is
+  not re-emitted)
+- Dedup is by server-side `messageId`
+- Default interval 30 s, minimum 10 s, override with `--interval <seconds>`
+- Exits cleanly on SIGINT (Ctrl+C)
+
+For agent loops, pipe stdout into a `while read line` and parse each line as
+its own JSON object. Do not assume the process will exit — it is meant to
+stay alive.
 
 ## Exit codes
 
@@ -113,6 +155,50 @@ daemon first.
   {"loggedIn": false}
   ```
 
+## Key JSON shapes
+
+### `seller messages` result
+
+```ts
+{
+  conversation: string,
+  total: number,
+  messages: Array<{
+    sender: string,
+    time: string | null,            // "YYYY-MM-DD HH:MM:SS" in +08:00
+    isMine: boolean,
+    content: string,
+    read: boolean,
+    kind: "text" | "offerCard" | "orderCard" | "autoReply"
+        | "assessment" | "image" | "other",
+    card?: { title: string|null, price: string|null,
+             image: string|null, url: string|null },
+    messageId?: string,             // present when sourced from WS
+  }>,
+}
+```
+
+`--watch` mode emits per-message instead:
+```ts
+{ conversation: string, message: <one item from messages[] above> }
+```
+
+### `cart add` result
+
+```ts
+{
+  ok: boolean,
+  added: CartItem,                  // see `cart list` JSON for full shape
+  isNewRow: boolean,                // true=new cartId, false=merged into existing row
+  addedQuantity: number,            // delta this call added (== args.quantity for new row)
+}
+```
+
+To get the cartId reliably in a pipeline:
+```bash
+id=$(1688 cart add <offerId> --sku <skuId> --qty 1 | jq -r '.added.cartId')
+```
+
 ## Discovery
 
 Run `1688 --help` and `1688 <command> --help` for the latest flags.

package/CHANGELOG.md

@@ -3,6 +3,67 @@
 All notable changes to this project are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.26] - 2026-05-13
+
+### Fixed
+- **Windows daemon never started** (`EACCES: permission denied` on
+  `daemon.sock`). Node's `net.listen()` can't bind a filesystem path on
+  Windows — it needs a named pipe (`\\.\pipe\...`). The daemon now uses
+  `\\.\pipe\1688-cli-daemon` on Windows and skips the `fs.unlink` of the
+  socket path (named pipes auto-clean). Unix behavior is unchanged.
+- `isDaemonReachable()` on Windows no longer fails the existence check
+  before connecting — named pipes don't appear in the filesystem.
+
+## [0.1.25] - 2026-05-13
+
+### Added
+- **`1688 similar <offerId>`** — find similar offers ("找同款") via the
+  shared search mtop endpoint. Sorted by price, useful for comparing
+  suppliers of the same product.
+- **`1688 seller messages --watch [--interval <s>]`** — live-tail a
+  conversation. Polls and emits only newly-arrived messages as
+  line-delimited JSON when stdout is piped. Dedup is by server-side
+  `messageId`. Default interval 30 s, minimum 10 s.
+- `seller messages` results now include richer `kind` subtypes:
+  `text` / `offerCard` / `orderCard` / `autoReply` / `assessment` /
+  `image` / `other`, plus a stable `messageId`. Offer/order cards expose
+  `card.url`, and offer cards are enriched with `card.title` / `.price` /
+  `.image` from the IM client's hydrated card.
+- `cart add` JSON response now includes `isNewRow` (bool) and
+  `addedQuantity` (number). Pipelines can pick up the new cartId reliably
+  even when the SKU is merged into an existing row.
+- `offer` returns a much richer payload: `priceTiers[]`, `attributes[]`,
+  `packageInfo[]`, `images[]`, `saleCount`, `categoryId`, and a fuller
+  `supplier` (loginId, memberId, province, city). SKU variants gain
+  `multiPrice`, `saleCount`, and `image`.
+- `order list` returns `actions[]` (buyer-side ops with jump URLs),
+  `services[]` (insurance / refund metadata with payer), `badges[]`,
+  `originalAmount`, `discountAmount`, `adjustment`, and `bizType`.
+
+### Changed
+- **`cart add` now uses mtop hijack (Route B)** instead of full UI replay.
+  Wall time is similar (~6 s) but works uniformly across single-attr and
+  multi-attr SKU layouts, including dropdown-style selectors and hidden
+  rows that previously broke the UI path.
+- **`seller messages` now uses WebSocket / LWP protocol interception
+  (Route C)** instead of DOM scraping. Server-truth timestamps
+  (millisecond `createAt`), stable `messageId`, and URL extraction from
+  offer/order cards. DOM scraping is retained as a fallback when no
+  WebSocket frames are captured.
+- `image-search` reuses the search mtop interception path; shared parser
+  helpers (`parseMtopJsonp`, `mapOffer`, `SEARCH_MTOP_API`) are now
+  exported from `search.ts` for `similar` to consume too.
+
+### Fixed
+- `cart list` returned `amount: 2` for items priced over ¥1,000 because
+  `parseFloat("2,094.00")` stops at the thousand-separator comma. Now
+  uses the integer-cent fields (`unitPriceCent`, `amountCent`) when
+  present, with a comma-stripping string parser as fallback.
+- `cart add` could return the wrong `cartId` when the same SKU was
+  already in the cart (the server merges into the existing row). Now
+  snapshots the cart before/after and diffs to find the affected row,
+  exposing whether it was a new row or a merge plus the delta quantity.
+
 ## [0.1.24] - 2026-05-13
 
 ### Fixed

package/README.md

@@ -1,19 +1,23 @@
-# 1688-cli
+# 1688-cli: Alibaba 1688.com CLI - Product Search, Inquiry, Cart, Checkout, Order Tracking & Seller Chat for AI Agents & Humans
 
 [![npm version](https://img.shields.io/npm/v/1688-cli.svg)](https://www.npmjs.com/package/1688-cli)
 [![npm downloads](https://img.shields.io/npm/dm/1688-cli.svg)](https://www.npmjs.com/package/1688-cli)
 [![license](https://img.shields.io/npm/l/1688-cli.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/1688-cli.svg)](https://nodejs.org/)
 
-**1688.com CLI for humans, Codex, and Claude Code.**
+Command-line tool for Alibaba 1688.com wholesale: keyword & image search,
+supplier inquiry, cart, checkout, order tracking, and seller chat. Outputs
+JSON when piped (for Codex / Claude Code / other AI agents) and pretty TTY
+text for humans.
 
-Two core flows from the terminal:
+The 6 things you can do from the terminal:
 
-- **Sourcing** — search / image-search / product detail / pre-sale inquiry
-- **Orders** — list / detail / logistics tracking / post-sale chat with sellers
-
-Outputs human text on a TTY and JSON when piped, so AI agents can drive it
-without parsing.
+1. **Sourcing** — search / similar / image-search / product detail
+2. **Pre-sale inquiry** — ask the supplier, watch replies live
+3. **Cart** — collect SKUs (with diff-based add confirmation)
+4. **Checkout** — preview + place the order
+5. **Order tracking** — list / detail / logistics / overdue detection
+6. **Post-sale chat** — chase shipment, read replies as JSON stream
 
 ```bash
 npm i -g 1688-cli
@@ -21,12 +25,16 @@ npm i -g 1688-cli
 
 # Sourcing
 1688 search "佛龛柜" --max 10                                 # keyword search
+1688 similar 628196518518 --max 10                            # find similar offers, sorted by price
 1688 image-search ./sample.jpg                                # search by image
 1688 offer 628196518518                                       # product detail
+
+# Pre-sale inquiry (with live watch for AI agents)
 1688 seller inquire 628196518518 "支持定制 logo 吗？"          # ask seller
-1688 seller messages --offer 628196518518                     # read seller's reply
+1688 seller messages --offer 628196518518                     # one-shot read
+1688 seller messages --offer 628196518518 --watch             # live-tail new replies (JSON when piped)
 
-# Orders
+# Order tracking & post-sale chat
 1688 order list --status waitsellersend                       # list orders
 1688 order get      <orderId>                                 # one order detail
 1688 order logistics <orderId>                                # tracking + trace
@@ -42,8 +50,8 @@ Existing 1688 automation options are heavy: Selenium glue you maintain, browser
 extensions you can't pipe into a shell, MCP servers that fight with your
 agent's tooling. `1688-cli` is a single command:
 
-- **Real Chrome under the hood** (`channel:'chrome'` + stealth). Reduced
-  risk-control hits compared to bundled Chromium.
+- **Real Chrome under the hood** (`channel:'chrome'`). Same browser you'd
+  use manually — your session is real, not a synthetic Chromium.
 - **Persistent profile** at `~/.1688/`. One login lasts for weeks.
 - **Long-running daemon** — first command warms the browser, subsequent
   commands reuse it (no relaunch per call).
@@ -77,90 +85,160 @@ npm i -g 1688-cli
 
 ## Commands
 
-### Account
+Organized by the buyer journey: discover → ask → decide → buy → track →
+follow up.
+
+### 1. Sourcing — find the right supplier
 
 ```bash
-1688 login                              # scan QR; auto-starts daemon
-1688 login --headed                     # open real window (fallback for risk control)
-1688 login --force                      # re-login even if cached
-1688 logout                             # clear cookies
-1688 whoami                             # current nick + memberId
-1688 doctor                             # environment check
+1688 search 机械键盘 --max 20                    # keyword search
+1688 similar 628196518518 --max 20               # "找同款" — same product, other suppliers, sorted by price
+1688 image-search ./shoe.jpg                     # search by local image
+1688 image-search https://.../img.png            # search by http(s) URL
+1688 offer 628196518518                          # product detail (priceTiers, attributes, packageInfo, SKUs)
 ```
 
-### Daemon
+### 2. Pre-sale inquiry — ask the supplier
+
+> Uses the same `seller messages` / `seller chat` tooling as §6, scoped by
+> `--offer <offerId>` instead of an orderId.
 
 ```bash
-1688 daemon start | stop | status | reload
+1688 seller inquire 628196518518 "支持定制 logo 吗？"               # send a product link + question
+1688 seller messages --offer 628196518518                          # read replies (one-shot)
+1688 seller messages --offer 628196518518 --since 2026-05-13T10:00:00+08:00
+1688 seller messages --offer 628196518518 --watch --interval 30    # live-tail new replies
 ```
 
-### Search & browse
+**Watch mode** prints only newly-arrived messages as line-delimited JSON
+when stdout is piped — pipe into any agent. Dedup is by server-side
+`messageId`. Min interval 10 s.
+
+### 3. Cart — collect SKUs
 
 ```bash
-1688 search 机械键盘 --max 20
-1688 image-search ./shoe.jpg            # local file
-1688 image-search https://.../img.png   # http(s) URL
-1688 offer 628196518518                 # product detail
+1688 cart list
+1688 cart add    <offerId> --sku <skuId> --qty 2
+1688 cart remove <cartId>
 ```
 
-### Orders
+`cart add` returns `{added: CartItem, isNewRow, addedQuantity}` so pipelines
+can pick up the new cartId reliably even when the same SKU is already in cart
+(server merges into the existing row in that case):
 
 ```bash
-1688 order list                                       # all statuses
-1688 order list --status waitsellersend               # paid, awaiting shipment
-1688 order list --status waitbuyerreceive             # shipped, awaiting delivery
-1688 order get   <orderId>
-1688 order logistics <orderId>                        # tracking number + trace
-1688 order get  <orderId> --status waitbuyerreceive   # speeds up scan on heavy accounts
+id=$(1688 cart add 628196518518 --sku 6070845665229 --qty 1 | jq -r '.added.cartId')
+1688 cart remove "$id"
 ```
 
-### Cart
+### 4. Checkout — place the order
 
 ```bash
-1688 cart list
-1688 cart add    <offerId> --sku <skuId> --qty 2
-1688 cart remove <cartId>
+1688 checkout prepare <cartIds...>           # preview total/address/items — safe, read-only
+1688 checkout confirm <cartIds...>           # default: TTY prompt y/N
+1688 checkout confirm <cartIds...> -y        # skip prompt (TTY still required)
+1688 checkout confirm <cartIds...> --agent   # AI-agent mode: no prompts (explicit autonomy opt-in)
 ```
 
-### Checkout (writes!)
+### 5. Order tracking — follow the shipment
 
 ```bash
-1688 checkout prepare <cartIds...>      # preview only — safe
-1688 checkout confirm <cartIds...>      # default: TTY prompt y/N
-1688 checkout confirm <cartIds...> -y   # skip prompt (TTY still required)
-1688 checkout confirm <cartIds...> --agent   # AI-agent mode: no prompts
+1688 order list                                       # all statuses (with actions, services, badges)
+1688 order list --status waitsellersend               # paid, awaiting shipment
+1688 order list --status waitbuyerreceive             # shipped, awaiting delivery
+1688 order get   <orderId>                            # one order detail
+1688 order logistics <orderId>                        # tracking number + trace
+1688 order get  <orderId> --status waitbuyerreceive   # narrow the scan on heavy accounts
+
+# Convenience views
+1688 shipped <orderId>                  # order detail + logistics merged
+1688 stuck --days 3                     # paid but not shipped > N days
+1688 fake-shipped --days 1              # marked shipped but courier never collected (虚假发货)
+1688 fake-shipped --debug               # show each candidate's status + remark
+1688 seller-history <sellerName>        # all orders + avg ship days + on-time rate
 ```
 
-### Seller IM (旺旺)
+### 6. Post-sale chat — chase delivery / claims
 
-Send + receive are symmetric — pre-sale is scoped by `offerId`, post-sale by
-`orderId`.
+> Same tooling as §2, scoped by `<orderId>` so messages auto-attach the
+> order card and replies thread under the right conversation.
 
 ```bash
-# Pre-sale
-1688 seller inquire 628196518518 "支持定制 logo 吗？"            # send
-1688 seller messages --offer 628196518518                       # read replies
-1688 seller messages --offer 628196518518 --since 2026-05-13T10:00:00+08:00
-
-# Post-sale
 1688 seller chat <orderId> "麻烦尽快发货谢谢"                     # send (auto-attaches order card)
 1688 seller chat <orderId> "请问什么时候发货" --no-card           # follow-up, no card
 1688 seller messages <orderId>                                  # read replies
 1688 seller messages <orderId> --limit 50 --since 2026-05-01T00:00:00+08:00
+1688 seller messages <orderId> --watch                          # live-tail
 ```
 
-### Workflow shortcuts
+### Account & daemon
 
 ```bash
-1688 shipped <orderId>                  # order detail + logistics merged
-1688 stuck --days 3                     # paid but not shipped > N days
-1688 fake-shipped --days 1              # marked shipped but courier never collected (虚假发货)
-1688 fake-shipped --debug               # show each candidate's status + remark
-1688 seller-history <sellerName>        # all orders + avg ship days + on-time rate
+1688 login                              # scan QR; auto-starts daemon
+1688 login --headed                     # open real window (fallback for risk control)
+1688 login --force                      # re-login even if cached
+1688 logout                             # clear cookies
+1688 whoami                             # current nick + memberId
+1688 doctor                             # environment check
+
+1688 daemon start | stop | status | reload
 ```
 
 ---
 
+## FAQ
+
+### Compared to alternatives
+
+#### How does 1688-cli compare to MCP servers and Selenium scripts?
+
+1688-cli runs as a regular shell command, not an MCP server. Agents call it
+via `child_process` or shell pipes instead of the MCP protocol — easier to
+compose with `jq`, `xargs`, and CI scripts. Compared to writing low-level
+browser automation directly, 1688-cli ships with structured JSON output,
+session persistence, and a daemon for warm context, so you don't reinvent
+that per project.
+
+#### Does 1688 have an official API I should use instead?
+
+Alibaba offers a 1688 Open API at `open.1688.com`, but it's gated to
+enterprise ISV partners with a sales contract and per-app authorization.
+Individual buyers, small businesses, and AI agents typically can't get
+access. 1688-cli uses your normal logged-in buyer account via a one-time
+QR scan, mirroring what you can do manually in a browser — no developer
+keys required.
+
+### Account & verification
+
+#### Does this tool require any 1688 developer account or API keys?
+
+No. Login is a one-time QR scan with your normal 1688 mobile app — the
+same flow as logging into 1688 on a fresh browser. The session is stored
+in your local profile (`~/.1688/profiles/default/`) and reused across
+commands, so you only re-scan when 1688 invalidates it.
+
+#### What happens if 1688 shows a verification challenge (滑块)?
+
+1688 occasionally shows a slider verification on unfamiliar sessions or
+after long inactivity — the same one you'd see when logging in from a new
+device manually. If a command fails because of this, run it once with
+`--headed` (e.g. `1688 search 雨伞 --headed`); a real window opens, you
+drag the slider yourself, and the verified session is reused for
+subsequent commands. There is no automated solver — it's the same manual
+step a person would take.
+
+#### Is it safe to use? Will my account get rate-limited?
+
+The tool drives your own logged-in browser session and only performs
+actions you'd do manually — search, read order details, send chat
+messages, place an order you confirmed. Use it at human pace (the default
+`--watch` interval is 30 seconds, minimum 10) for one of your own
+accounts. Aggressive automation, high-frequency scraping, or running it
+across many accounts is outside the tool's design and increases the
+chance of triggering 1688's risk controls.
+
+---
+
 ## JSON for agents
 
 Every command auto-switches to JSON when stdout is piped:
@@ -181,22 +259,21 @@ BB1688_JSON=1 1688 doctor
 
 ## Risk control
 
-1688's WAF triggers a slider challenge on suspicious traffic.
-`1688-cli` already uses real Chrome + stealth + a persistent profile, and the
-`search` command warms up `s.1688.com` before every request. If you still hit
-a slider, solve it once with `--headed`:
+If 1688 shows a slider verification (滑块), solve it once with `--headed`:
 
 ```bash
-1688 search 雨伞 --headed     # window opens; drag the slider once
-1688 search 雨伞              # subsequent headless calls work for hours
+1688 search 雨伞 --headed     # window opens; drag the slider yourself
+1688 search 雨伞              # subsequent calls reuse the verified session
 ```
 
+See also the FAQ entry on [verification challenges](#what-happens-if-1688-shows-a-verification-challenge-滑块).
+
 ---
 
 ## Files & directories
 
 ```
-~/.1688/profiles/default/   Chromium profile (cookies, IndexedDB, fingerprint)
+~/.1688/profiles/default/   Chromium profile (cookies, IndexedDB, session state)
 ~/.1688/state.json          cached identity (nick / memberId / timestamps)
 ~/.1688/daemon.sock         daemon Unix socket
 ~/.1688/daemon.pid          daemon PID

package/dist/cli.js

@@ -58,6 +58,17 @@ program
     const { run } = await import('./commands/offer.js');
     await run({ ...opts, offerId });
 });
+program
+    .command('similar')
+    .description('Find similar / 找同款 offers for a given offerId (compare suppliers, sorted by price)')
+    .argument('<offerId>', 'Offer ID (digits)')
+    .option('--max <n>', 'Maximum number of similar offers', '20')
+    .option('--profile <name>', 'Profile name (default: default)')
+    .option('--headed', 'Open a window (fallback for risk control)')
+    .action(async (offerId, opts) => {
+    const { run } = await import('./commands/similar.js');
+    await run({ ...opts, offerId });
+});
 const seller = program
     .command('seller')
     .description('Seller communication (旺旺 IM)');
@@ -80,6 +91,8 @@ seller
     .option('--offer <offerId>', 'Read pre-sale inquiry replies for this offerId')
     .option('--limit <n>', 'Max messages to return (default 20, max 200)', '20')
     .option('--since <iso>', 'Only show messages after this ISO timestamp (e.g. 2026-05-12T16:44:00+08:00)')
+    .option('--watch', 'Poll continuously and print new messages as they arrive')
+    .option('--interval <seconds>', 'Polling interval in seconds for --watch (default 30, min 10)', '30')
     .option('--profile <name>', 'Profile name (default: default)')
     .option('--headed', 'Open a window (debug visibility)')
     .action(async (target, opts) => {