1688-cli 0.1.40 → 0.1.42

package/docs/WORKFLOW.md

@@ -0,0 +1,82 @@
+# Workflow
+
+This is the default workflow for AI agents and humans working in this
+repository. Keep it executable and linked to deeper docs.
+
+## Operating Model
+
+- Humans set intent, constraints, priorities, and approval boundaries.
+- Agents read the map, choose the smallest coherent slice, implement, verify,
+  and update durable docs.
+- `AGENTS.md` is the fast entry point; this file is the default operating loop.
+- Playbooks under `docs/playbooks/` hold repeatable task details.
+- ExecPlans under `docs/exec-plans/` hold long-running state that should
+  survive chat history loss.
+
+## Standard Task Brief
+
+Capture or infer these fields before changing code:
+
+```md
+Goal:
+Context:
+Constraints:
+Done when:
+```
+
+Ask the human only when the missing choice changes product behavior, checkout
+safety, data retention, account security, or external write actions.
+
+## New Feature Flow
+
+1. Read `AGENTS.md`, `ARCHITECTURE.md`, `docs/README.md`, and the relevant
+   product spec or playbook.
+2. Locate the owning command/session/daemon/io layer.
+3. For complex work, create or update an ExecPlan in
+   `docs/exec-plans/active/`.
+4. Implement one bounded slice that can be verified independently.
+5. Add or update deterministic tests near the changed code.
+6. Update durable docs when command behavior, JSON output, safety rules, or
+   recurring workflow guidance changes.
+7. Run the smallest verification ladder that proves the change, then climb if
+   risk increases.
+
+## Bugfix Flow
+
+1. Reproduce or narrow the failure with a test, probe, fixture, saved artifact,
+   or captured browser response.
+2. Locate the smallest owning layer: CLI, command, session, daemon, io, auth,
+   or util.
+3. Fix the root cause with minimal unrelated churn.
+4. Add a regression test or document why one is not practical.
+5. Run a focused test first, then `pnpm agent-verify` when the blast radius
+   warrants it.
+
+## Verification Ladder
+
+1. Focused checks: a single Vitest file, typecheck, or generated-context run.
+2. Deterministic test gate: `pnpm test:unit`.
+3. Agent gate: `pnpm agent-context`, then `pnpm agent-verify`.
+4. Browser/live checks: `pnpm test` or manual/probe-based verification only
+   when the task touches real 1688 browser behavior and the user/session state
+   allows it.
+
+## Human Approval Boundaries
+
+Ask before doing any of these:
+
+- Placing an order or using `checkout confirm --agent`.
+- Logging out or forcing a login reset.
+- Submitting a public GitHub issue with `feedback --submit`.
+- Sending a real seller chat/inquiry unless the user asked for that specific
+  message to be sent.
+- Running live/browser actions that can mutate cart, checkout, seller IM, or
+  account state.
+- Making a breaking JSON contract change.
+
+## Definition Of Done
+
+- The change is implemented in the owning layer.
+- Tests cover the behavior or the reason for no test is recorded.
+- Relevant docs/specs/playbooks/generated indexes are updated.
+- `pnpm agent-verify` passes, or the exact blocker is recorded.

package/docs/exec-plans/README.md

@@ -0,0 +1,9 @@
+# ExecPlans
+
+Use this directory for complex or long-running work that should survive chat
+history loss.
+
+- Active plans: `active/`
+- Completed plans: `completed/`
+- Non-blocking follow-up work: `tech-debt-tracker.md`
+

package/docs/exec-plans/active/README.md

@@ -0,0 +1,4 @@
+# Active ExecPlans
+
+Place in-progress complex work here.
+

package/docs/exec-plans/completed/2026-05-28-sourcing-research-v1.md

@@ -0,0 +1,125 @@
+# Plan: Sourcing Research V1
+
+## Goal
+
+Deliver a complete first version of sourcing research:
+
+- `search` supports research sort/filter flags.
+- `research` runs multi-keyword sourcing research with scoring, dedupe,
+  export, and optional top-N enrichment.
+- `compare` compares offer detail pages by sourcing-relevant fields.
+- Docs, JSON contracts, generated indexes, and tests are updated.
+
+## Context
+
+- Spec: `docs/specs/sourcing-research.md`
+- Backlog: `docs/FEATURES.md`
+- Existing search command: `src/commands/search.ts`
+- Search payload mapping: `src/session/search-mtop.ts`
+- Offer detail command: `src/commands/offer.ts`
+- CLI routing: `src/cli.ts`
+- Output behavior: `src/io/output.ts`
+- Agent rules: `docs/AGENT_WORKING_PRINCIPLES.md`
+
+## Non-Goals
+
+- Do not implement `supplier inspect` until reliable supplier-level payloads
+  are identified.
+- Do not scrape every search result detail page by default.
+- Do not change checkout/cart/seller-message behavior.
+- Do not introduce remote writes.
+
+## Design
+
+1. Extend `search` with:
+   - `--sort`
+   - `--price-min`
+   - `--price-max`
+   - `--province`
+   - `--city`
+   - `--verified`
+   - `--min-turnover`
+   - `--exclude-ads`
+
+   Search remains one fast read-only command. Filtering and deterministic sort
+   happen locally on the collected result set. The search URL may include known
+   remote sort values, but local sorting remains the contract.
+
+2. Add shared sourcing helpers:
+   - normalize sort/filter options
+   - parse turnover/order-count text
+   - score offers and offer details
+   - format JSONL/CSV exports
+
+3. Add `research`:
+   - runs searches sequentially through existing daemon dispatch
+   - dedupes by offerId
+   - computes score/breakdown
+   - optionally enriches top N items through `offer`
+   - emits normal JSON/human output or explicit JSONL/CSV
+
+4. Add `compare`:
+   - validates offer IDs
+   - fetches offer details sequentially
+   - returns item-level errors
+   - scores and sorts comparable summaries
+
+5. Update docs and generated context.
+
+## Self Review
+
+- Risk: `sortType` URL behavior may vary by 1688 page version.
+  - Mitigation: keep local deterministic sorting as the public contract.
+- Risk: supplier scores and repurchase rate may not exist in current payloads.
+  - Mitigation: include nullable fields and do not claim them as available.
+- Risk: enrichment can trigger more browser/detail-page work.
+  - Mitigation: default enrichment to 0; require `--enrich top:N`.
+- Risk: CSV/JSONL could bypass global output flags.
+  - Mitigation: explicit `--jsonl`/`--csv` modes only for `research`, with
+    validation against simultaneous use.
+- Risk: item-level offer failures could abort useful research output.
+  - Mitigation: attach item errors and keep run output when at least one item
+    succeeds.
+
+## Milestones
+
+- [x] Expand spec and plan.
+- [x] Implement search sort/filter helpers and flags.
+- [x] Implement sourcing helper/scoring/export module.
+- [x] Implement `research`.
+- [x] Implement `compare`.
+- [x] Add focused tests.
+- [x] Update docs/backlog.
+- [x] Run `pnpm agent-verify`.
+
+## Verification
+
+```bash
+pnpm test:unit
+pnpm agent-context
+pnpm agent-verify
+```
+
+## Decisions
+
+- 2026-05-28: Keep `supplier inspect` out of V1 because reliable supplier-level
+  payloads are not yet mapped.
+- 2026-05-28: Use local deterministic sorting/filtering as the contract even
+  when adding remote sort URL params.
+- 2026-05-28: Enrichment defaults to off; top-N enrichment is explicit.
+
+## Progress Log
+
+- 2026-05-28: Created spec and plan. Self-review identified remote sort,
+  supplier-score availability, enrichment cost, export-mode validation, and
+  item-level failure handling as the main risks.
+- 2026-05-28: Implemented `search` sort/filter controls, shared sourcing
+  scoring/export helpers, `research`, `compare`, and focused unit tests.
+- 2026-05-28: Verification passed: `pnpm test:unit` (22 files, 151 tests),
+  `pnpm agent-context`, `pnpm agent-verify`, and `pnpm build`.
+
+## Rollback
+
+- Remove `research` and `compare` CLI entries and command files.
+- Revert added `search` flags and helper usage.
+- Regenerate agent context.

package/docs/exec-plans/completed/2026-05-31-supplier-inspect-v1.md

@@ -0,0 +1,113 @@
+# Plan: Supplier Inspect V1
+
+## Goal
+
+Deliver a read-only supplier inspection command backed by real 1688 payloads:
+
+- `1688 supplier inspect <offerId|memberId|offerUrl|factoryCardUrl>`
+- offerId path resolves supplier identity from offer detail and shopcard
+- memberId path resolves factory-card data
+- JSON contract and human output are documented
+- loginId-only input is rejected until a deterministic resolver exists
+
+## Context
+
+- Spec: `docs/specs/supplier-inspect.md`
+- Existing offer detail extraction: `src/commands/offer.ts`
+- CLI routing: `src/cli.ts`
+- Session dispatch: `src/session/dispatch.ts`
+- Response parsing: `src/session/mtop.ts`
+- Recovery behavior: `src/session/recovery.ts`
+- Sourcing helpers/tests: `src/commands/sourcing-utils.ts`,
+  `tests/sourcing-utils.test.ts`
+
+## Non-Goals
+
+- Do not add write actions.
+- Do not bulk crawl a supplier catalog.
+- Do not silently resolve loginId by an unreliable URL.
+- Do not change checkout/cart/seller-message behavior.
+
+## Design
+
+1. Add `src/commands/supplier-inspect.ts`.
+   - Normalize target into offerId or memberId.
+   - Reject loginId-only targets with `BAD_INPUT`.
+   - Use `withRecovery` for page-level failures.
+
+2. OfferId path:
+   - Open `https://detail.1688.com/offer/<offerId>.html`.
+   - Capture `mtop.1688.moga.pc.shopcard`.
+   - Read `sellerModel` from `window.context`.
+   - If a memberId is found, enrich with factory card.
+
+3. MemberId path:
+   - Open `https://sale.1688.com/factory/card.html?memberId=<memberId>`.
+   - Capture `mtop.com.alibaba.china.factory.card.common.fn.mtop.tpp.faas`.
+   - Parse visible factory-card text for available offer count.
+
+4. Output:
+   - Normal human summary lists supplier identity, factory/authentication tags,
+     service scores, location, and offer count.
+   - JSON output follows the spec and remains nullable/additive.
+
+5. Verification:
+   - Add focused unit tests for target normalization and data assembly.
+   - Run `pnpm typecheck`, `pnpm test:unit`, `pnpm agent-context`, and
+     `pnpm agent-map-check`.
+   - Run one live smoke command if session and risk-control state allow.
+
+## Self Review
+
+- Risk: factory card endpoint can time out or not fire.
+  - Mitigation: return partial supplier identity with a warning when offerId
+    data exists but factory-card enrichment fails.
+- Risk: service score key names are not self-explanatory.
+  - Mitigation: keep raw keys and add best-effort labels.
+- Risk: loginId direct lookup may return the wrong supplier.
+  - Mitigation: reject loginId-only input and document the limitation.
+- Risk: available offer count only appears in rendered text.
+  - Mitigation: mark source as `factory-card-dom` and keep nullable.
+
+## Milestones
+
+- [x] Write spec and plan.
+- [x] Implement command, parser, and CLI routing.
+- [x] Add focused tests.
+- [x] Update README, command catalog, JSON contracts, and feature backlog.
+- [x] Regenerate agent context.
+- [x] Run verification.
+
+## Verification
+
+```bash
+pnpm typecheck
+pnpm test:unit
+pnpm agent-context
+pnpm agent-map-check
+pnpm dev supplier inspect 628196518518 --json --pretty
+```
+
+Passed on 2026-05-31:
+
+- `pnpm dev supplier inspect 628196518518 --json --pretty`
+- `pnpm typecheck`
+- `pnpm test:unit`
+- `pnpm docs-check`
+- `pnpm agent-map-check`
+- `pnpm agent-verify`
+
+## Progress Log
+
+- 2026-05-31: Live headed probe identified reliable offer `sellerModel`,
+  shopcard, and factory-card payloads. Direct loginId lookup was rejected after
+  probe showed it can resolve to the wrong factory.
+- 2026-05-31: Implemented `supplier inspect`, CLI routing, dispatch registry,
+  parser helpers, focused tests, docs, generated agent context, and live smoke
+  verification.
+
+## Rollback
+
+- Remove `supplier inspect` CLI entry and command file.
+- Remove tests and docs sections.
+- Regenerate agent context.

package/docs/exec-plans/completed/2026-06-04-supplier-search-v1.md

@@ -0,0 +1,81 @@
+# Supplier Search V1
+
+## Goal
+
+Deliver supplier discovery and research backed by real 1688 company search:
+
+- `1688 supplier search <keyword...>`
+- `1688 supplier research <keyword...>`
+- source must be `companySearchBusinessService`
+- source must not be offer-result supplier aggregation
+- optional top-N enrichment through `supplier inspect`
+
+## Context Read
+
+- Agent principles: `docs/AGENT_WORKING_PRINCIPLES.md`
+- Sourcing spec: `docs/specs/sourcing-research.md`
+- Supplier inspect spec: `docs/specs/supplier-inspect.md`
+- New spec: `docs/specs/supplier-search.md`
+- Existing search/capture patterns: `src/commands/search.ts`,
+  `src/session/search-capture.ts`
+
+## Live Probe Findings
+
+- Company search page:
+  `https://s.1688.com/company/company_search.htm?keywords=<GBK>`
+- `s.1688.com` keywords must be GBK percent-encoded. UTF-8 encoding produced
+  mojibake/zero-result behavior.
+- Business endpoint:
+  `search.1688.com/service/companySearchBusinessService`
+- Payload path:
+  `data.data.companyWithOfferLists`
+- Sample async response returned 14 suppliers with `pageCount=50` and
+  `docsReturn=14`.
+- The async URL used `startIndex=6&asyncCount=14`, so V1 records a known
+  completeness boundary: stable service parsing first, optional SSR/DOM card
+  parsing later if exact first-page completeness is needed.
+
+## Implementation
+
+1. Add shared GBK percent encoder in `src/util/encoding.ts`.
+2. Reuse the encoder in product search URL construction.
+3. Add `src/session/supplier-search.ts`:
+   - request meta reader for `companySearchBusinessService`
+   - service payload parser
+   - supplier/offer-preview mapper
+   - response capture with `keep: "largest"` and settle window
+4. Add `src/commands/supplier-search.ts`:
+   - `supplier search`
+   - `supplier research`
+   - scoring, filters, JSONL/CSV exports
+   - optional enrich through `supplier inspect`
+5. Add CLI and dispatch registry wiring.
+6. Add deterministic unit tests.
+7. Update README, command catalog, JSON contracts, feature backlog, and specs.
+8. Regenerate agent indexes.
+
+## Decisions
+
+- Keep source provenance explicit in JSON:
+  `source.offerAggregation=false`.
+- `supplier search` defaults to `--enrich 0`.
+- `supplier research` defaults to `--enrich top:10`.
+- Rate filters accept both fractions and percentages (`0.4` or `40`).
+- Enrichment requires `memberId`; missing memberId is an item-level error.
+- Do not use direct unauthenticated fetch for company service because it can
+  trigger `x5` interstitials; use browser-emitted responses.
+
+## Verification
+
+- `pnpm typecheck`
+- `pnpm test:unit`
+- `pnpm agent-context`
+- `pnpm agent-verify`
+
+## Rollback
+
+- Remove supplier search/research CLI entries.
+- Remove dispatch registry entry `supplier-search`.
+- Remove `src/commands/supplier-search.ts`.
+- Remove `src/session/supplier-search.ts`.
+- Revert README/docs/spec/test/index updates.

package/docs/exec-plans/completed/2026-06-07-windows-cli-compatibility.md

@@ -0,0 +1,138 @@
+# Plan: Windows CLI Compatibility
+
+## Goal
+
+Deliver the Windows compatibility baseline from
+`docs/specs/windows-cli-compatibility.md`: Windows-safe build/install scripts,
+daemon named pipe isolation, platform-aware diagnostics, Windows-ready docs,
+and deterministic verification.
+
+## Context
+
+- Source spec: `docs/specs/windows-cli-compatibility.md`
+- Agent map: `AGENTS.md`
+- Workflow: `docs/WORKFLOW.md`
+- CLI/package surfaces: `package.json`, `scripts/postinstall.mjs`, `src/cli.ts`
+- Path/daemon surfaces: `src/session/paths.ts`, `src/daemon/*`
+- Diagnostic surface: `src/commands/doctor.ts`
+- User docs: `README.md`, `docs/COMMANDS.md`
+- Generated indexes: `docs/generated/*`
+
+Existing behavior already has partial Windows support: daemon IPC uses a
+named pipe on `win32`, postinstall checks common Windows Chrome paths, and
+most runtime paths use `path.join`. Known gaps are shell `chmod` in
+`package.json`, a fixed global named pipe, Unix-only doctor hints, Unix-only
+README examples, and no deterministic Windows-specific tests.
+
+## Non-goals
+
+- Do not change 1688 login/risk-control behavior.
+- Do not add a native Windows service, installer, or packaged executable.
+- Do not add live Windows 1688 network checks to deterministic tests.
+- Do not change existing command JSON shapes except additive diagnostics if
+  needed.
+
+## Design
+
+- Replace shell `chmod` with a Node script that sets executable mode only on
+  Unix-like platforms.
+- Make Windows named pipe paths stable per root by hashing `root()`.
+- Keep Unix socket paths unchanged.
+- Centralize platform-specific diagnostic hint strings in `doctor`.
+- Make postinstall resolve its pid file through `BB1688_HOME` and run
+  `npx.cmd` on Windows.
+- Use `os.tmpdir()` for production debug/probe output helpers that currently
+  write hard-coded `/tmp` paths.
+- Update README and command docs with PowerShell-safe examples while keeping
+  Unix examples for shell users.
+- Add deterministic tests that simulate Windows behavior without requiring a
+  Windows host by exposing pure helper functions.
+
+## Checklist
+
+Spec and plan foundation:
+
+- [x] Create Windows CLI compatibility spec.
+- [x] Create active ExecPlan.
+
+Implementation:
+
+- [x] Add cross-platform bin-mode script and replace `chmod` build command.
+- [x] Make Windows daemon named pipe unique per `BB1688_HOME` root.
+- [x] Make postinstall daemon pid lookup, npx invocation, and retry hint
+  platform-aware.
+- [x] Make doctor fix hints platform-aware.
+- [x] Replace production hard-coded `/tmp` debug dump paths with `os.tmpdir()`.
+- [x] Add deterministic tests for Windows path/doctor/build helpers.
+
+Docs and maps:
+
+- [x] Update README Windows command-line guidance.
+- [x] Update `docs/COMMANDS.md` Windows examples.
+- [x] Run `pnpm agent-context` after command/doc/test layout changes.
+
+Verification:
+
+- [x] Run focused Windows compatibility tests.
+- [x] Run `pnpm build`.
+- [x] Run `pnpm test:unit`.
+- [x] Run `pnpm agent-verify`.
+- [x] Run `npm pack --dry-run`.
+
+## Verification
+
+Focused:
+
+```bash
+pnpm exec vitest run tests/paths.test.ts tests/doctor.test.ts tests/fix-bin-mode.test.ts
+```
+
+Package and project:
+
+```bash
+pnpm build
+pnpm test:unit
+pnpm agent-context
+pnpm agent-verify
+npm pack --dry-run
+```
+
+Manual Windows smoke when a Windows machine is available:
+
+```powershell
+npm i -g 1688-cli
+1688 --version
+1688 doctor --no-launch --json
+1688 daemon start
+1688 daemon status --json
+1688 daemon stop
+1688 search 雨伞 --max 1 --json
+1688 supplier search 键盘 --max 1 --json
+```
+
+## Decisions
+
+- 2026-06-07: Treat Windows support as a deterministic packaging/runtime
+  compatibility baseline, not a guarantee that live 1688 network calls pass in
+  CI without a logged-in account.
+- 2026-06-07: Use `BB1688_HOME` root hashing for Windows named pipes so
+  tests and users with different homes do not collide.
+
+## Progress Log
+
+- 2026-06-07: Created spec and active plan from user request.
+- 2026-06-07: Implemented the Windows compatibility baseline: Node-based bin
+  mode fixing, root-hashed Windows daemon named pipes, platform-aware
+  postinstall and doctor hints, `os.tmpdir()` debug paths, PowerShell docs, and
+  deterministic helper tests.
+- 2026-06-07: Verified with focused Windows compatibility tests, `pnpm build`,
+  `pnpm test:unit`, `pnpm agent-context`, `pnpm agent-verify`, and
+  `npm pack --dry-run`. Manual Windows smoke remains documented for a real
+  Windows session.
+
+## Rollback
+
+- Restore `package.json` build script to its previous `chmod` form.
+- Restore `socketPath()` to the fixed Windows pipe.
+- Revert postinstall, doctor, docs, and tests added by this plan.
+- Run `pnpm agent-context` after rollback if generated indexes changed.

package/docs/exec-plans/completed/README.md

@@ -0,0 +1,4 @@
+# Completed ExecPlans
+
+Move completed complex work here with final verification notes.
+

package/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,5 @@
+# Tech Debt Tracker
+
+Record non-blocking follow-up work here when it should not stay in an active
+ExecPlan.
+

package/docs/generated/command-index.md

@@ -0,0 +1,54 @@
+# Command Index
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Command | Source | Arguments | Options | Description |
+|---|---|---|---|---|
+| `login` | `src/commands/login.ts` | - | `--force`<br>`--timeout <seconds>`<br>`--profile <name>`<br>`--headed`<br>`--no-daemon` | Log in to 1688 by scanning a QR code (auto-starts daemon afterwards) |
+| `search` | `src/commands/search.ts` | `<keyword>` | `--max <n>`<br>`--sort <sort>`<br>`--price-min <n>`<br>`--price-max <n>`<br>`--province <name>`<br>`--city <name>`<br>`--verified <kind>`<br>`--min-turnover <n>`<br>`--exclude-ads`<br>`--profile <name>`<br>`--headed` | Search 1688 by keyword |
+| `research` | `src/commands/research.ts` | `<keywords...>` | `--max-per-query <n>`<br>`--sort <sort>`<br>`--price-min <n>`<br>`--price-max <n>`<br>`--province <name>`<br>`--city <name>`<br>`--verified <kind>`<br>`--min-turnover <n>`<br>`--exclude-ads`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Run multi-keyword sourcing research with scoring and optional enrichment |
+| `compare` | `src/commands/compare.ts` | `<offerIds...>` | `--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Compare multiple offer detail pages for sourcing decisions |
+| `supplier` | - | - | - | - |
+| `supplier inspect` | `src/commands/supplier-inspect.ts` | `<target>` | `--profile <name>`<br>`--headed` | Inspect supplier signals from an offerId or b2b-* memberId |
+| `supplier search` | `src/commands/supplier-search.ts` | `<keywords...>` | `--max <n>`<br>`--factory-only`<br>`--province <name>`<br>`--city <name>`<br>`--min-years <n>`<br>`--min-repeat-rate <n>`<br>`--min-response-rate <n>`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Search suppliers from 1688 company search |
+| `supplier research` | `src/commands/supplier-search.ts` | `<keywords...>` | `--max <n>`<br>`--factory-only`<br>`--province <name>`<br>`--city <name>`<br>`--min-years <n>`<br>`--min-repeat-rate <n>`<br>`--min-response-rate <n>`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Run supplier research from 1688 company search with scoring and inspect enrichment |
+| `image-search` | `src/commands/image-search.ts` | `<imagePathOrUrl>` | `--max <n>`<br>`--profile <name>`<br>`--headed` | Search 1688 by image (local file or http(s) URL) |
+| `offer` | `src/commands/offer.ts` | `<offerId>` | `--profile <name>`<br>`--headed` | Show details of a single 1688 offer |
+| `similar` | `src/commands/similar.ts` | `<offerId>` | `--max <n>`<br>`--profile <name>`<br>`--headed` | Find similar / 找同款 offers for a given offerId (compare suppliers, sorted by price), |
+| `inbox` | `src/commands/inbox.ts` | - | `--limit <n>`<br>`--unread`<br>`--profile <name>`<br>`--headed` | List recent 旺旺 IM conversations (newest first) |
+| `seller` | - | - | - | Seller communication (旺旺 IM |
+| `seller inquire` | `src/commands/seller-inquire.ts` | `<offerId>`<br>`<message>` | `--to <sellerLoginId>`<br>`--profile <name>`<br>`--headed` | Pre-sale inquiry: send a product link question to seller (requires prior chat or --to), |
+| `seller messages` | `src/commands/seller-messages.ts` | `[target]` | `--offer <offerId>`<br>`--limit <n>`<br>`--since <iso>`<br>`--watch`<br>`--interval <seconds>`<br>`--profile <name>`<br>`--headed` | Read recent messages from a seller conversation |
+| `seller chat` | `src/commands/seller-chat.ts` | `<target>`<br>`<message>` | `--no-card`<br>`--prefix`<br>`--profile <name>`<br>`--headed` | Send to seller. With orderId: sends order card link message (use --no-card for follow-ups |
+| `checkout` | - | - | - | - |
+| `checkout confirm` | `src/commands/checkout-confirm.ts` | `<cartIds...>` | `-y, --yes`<br>`--agent`<br>`--profile <name>` | Place an order for selected cart items. Default: TTY prompt. --agent: no prompt after external approval., |
+| `checkout prepare` | `src/commands/checkout-prepare.ts` | `<cartIds...>` | `--profile <name>`<br>`--headed` | Preview total/address/items for a checkout (does NOT place order) |
+| `cart` | - | - | - | - |
+| `cart add` | `src/commands/cart-add.ts` | `<offerId>` | `--sku <skuId>`<br>`--qty <n>`<br>`--profile <name>`<br>`--headed` | Add one item to cart (UI replay, ~15s) |
+| `cart remove` | `src/commands/cart-remove.ts` | `<cartId>` | `--profile <name>`<br>`--headed` | Remove one item from cart by cartId (UI replay, ~10s) |
+| `cart list` | `src/commands/cart-list.ts` | - | `--profile <name>`<br>`--headed` | List items in your cart |
+| `shipped` | `src/commands/workflows.ts` | `<orderId>` | `--profile <name>`<br>`--headed` | Combined order detail logistics for one orderId |
+| `stuck` | `src/commands/workflows.ts` | - | `--days <n>`<br>`--limit <n>`<br>`--profile <name>`<br>`--headed` | Orders paid but not shipped after N days (default 3) |
+| `fake-shipped` | `src/commands/workflows.ts` | - | `--days <n>`<br>`--max-pages <n>`<br>`--max-check <n>`<br>`--limit <n>`<br>`--debug`<br>`--profile <name>`<br>`--headed` | Orders marked shipped but logistics frozen at 等待揽收 (likely 虚假发货) |
+| `seller-history` | `src/commands/workflows.ts` | `<seller>` | `--max-pages <n>`<br>`--profile <name>`<br>`--headed` | All orders from a seller avg shipping days on-time rate |
+| `order` | - | - | - | - |
+| `order logistics` | `src/commands/order-logistics.ts` | `<orderId>` | `--max-scan-pages <n>`<br>`--status <s>`<br>`--profile <name>`<br>`--headed` | Show shipping status tracking number for an order |
+| `order get` | `src/commands/order-get.ts` | `<orderId>` | `--max-scan-pages <n>`<br>`--status <s>`<br>`--profile <name>`<br>`--headed` | Show one order by orderId (scans recent pages) |
+| `order list` | `src/commands/order-list.ts` | - | `--status <s>`<br>`--page <n>`<br>`--page-size <n>`<br>`--profile <name>`<br>`--headed` | List buyer orders |
+| `whoami` | `src/commands/whoami.ts` | - | `--verify`<br>`--profile <name>` | Show the current logged-in account |
+| `logout` | `src/commands/logout.ts` | - | `-y, --yes`<br>`--profile <name>` | Log out and clear local session |
+| `doctor` | `src/commands/doctor.ts` | - | `--no-launch`<br>`--live`<br>`--profile <name>` | Check environment, profile, Chromium, and session |
+| `serve` | - | - | `--idle-timeout <minutes>`<br>`--no-prewarm` | Run the 1688 daemon in the foreground |
+| `daemon` | - | - | - | - |
+| `daemon start` | - | - | - | Start the daemon as a background process |
+| `daemon stop` | - | - | - | Stop the running daemon |
+| `daemon reload` | - | - | - | Restart the daemon (stop start) to pick up new code |
+| `daemon status` | - | - | - | Show daemon status |
+| `profile` | - | - | - | - |
+| `profile list` | `src/commands/profile.ts` | - | - | List local profiles |
+| `profile status` | `src/commands/profile.ts` | `[name]` | - | Show profile status |
+| `debug` | - | - | - | - |
+| `debug list` | `src/commands/debug.ts` | - | `--limit <n>`<br>`--failed` | List recent command events |
+| `debug last` | `src/commands/debug.ts` | - | `--failed` | Show the most recent command event |
+| `debug show` | `src/commands/debug.ts` | `<requestId>` | - | Show events and artifact location for a request |
+| `feedback` | `src/commands/feedback.ts` | `<message...>` | `--bug`<br>`--submit`<br>`--no-open`<br>`--json`<br>`--json-v2`<br>`--pretty`<br>`--get <path>`<br>`--pick <paths>` | Submit feedback or a bug report. Default: opens a pre-filled GitHub issue. With --submit: posts directly via the gh CLI., |