1688-cli 0.1.41 → 0.1.43

package/docs/specs/profile-daemon.md

@@ -0,0 +1,114 @@
+# Spec: Profile Daemon
+
+> Status: draft
+> Product: 1688-cli daemon/session runtime
+> Scope: profile-scoped daemon processes, browser contexts, locks, runtime artifacts, and diagnostics
+
+## 1. Summary
+
+`1688-cli` supports multiple local profiles, but the warm daemon runtime is
+currently global/default-oriented. This spec changes daemon ownership to one
+daemon per profile so commands run against the daemon for their selected
+profile, different profiles can operate in parallel, and default-profile
+behavior remains compatible for users who do not pass `--profile`.
+
+## 2. Goals
+
+- Resolve every command profile to `default` when no profile is supplied.
+- Support `1688 serve --profile <name>`.
+- Support `1688 daemon start|stop|status|reload --profile <name>`.
+- Route ordinary dispatched commands such as `search --profile acc-a` to the
+  daemon for `acc-a` when that daemon is reachable.
+- Keep headed mode and explicitly daemon-disabled runs inline.
+- Use one persistent browser context per daemon, bound to that daemon profile.
+- Use profile-scoped lock, socket or named pipe, pid, version, log, and state
+  artifacts.
+- Allow different profiles to run concurrently without sharing one process lock.
+- Surface profile names in daemon, lock, and diagnostic error messages.
+- Preserve default behavior for commands that omit `--profile`.
+
+## 3. Non-goals
+
+- Do not build one daemon that multiplexes multiple profiles.
+- Do not change checkout confirmation safety or route `checkout confirm`
+  through the daemon.
+- Do not run live 1688 login, search, or browser mutation checks as automated
+  verification.
+- Do not change command result contracts except for additive diagnostic fields
+  on daemon/profile/doctor surfaces.
+- Do not migrate or delete historical global daemon artifacts automatically
+  beyond normal stale-artifact cleanup for the selected profile.
+
+## 4. Behavior contract
+
+- `defaultProfileName(profile)` resolves missing, empty, or whitespace-only
+  profile input to `default`.
+- Runtime artifact helpers accept an optional profile argument and use the
+  resolved profile:
+  - `socketPath(profile)`
+  - `pidFile(profile)`
+  - `daemonVersionFile(profile)`
+  - `daemonLogFile(profile)`
+  - `lockFile(profile)`
+  - `stateFile(profile)`
+- Windows named pipe names include both the root hash and a profile-derived
+  segment so two profiles under the same `BB1688_HOME` do not collide.
+- Non-Windows daemon sockets are profile-scoped filesystem paths under the
+  selected profile/runtime area.
+- `acquireLock(profile)` locks only the selected profile.
+- Inline sessions use `profilePath(profile)` and `acquireLock(profile)`.
+- A daemon process is bound to exactly one profile at startup.
+- `getSharedContext(profile)` creates or reuses the browser context only for
+  the daemon-bound profile and stores cookies/session in that profile's
+  persistent context directory.
+- `runOnSharedCtx` serializes operations within one daemon process only.
+- `dispatch(name, args, { profile })` attempts the selected profile daemon
+  unless headed, no-daemon, or `BB1688_NO_DAEMON=1` is set.
+- If inline fallback is needed, dispatch pauses only the selected profile
+  daemon, not daemons for other profiles.
+- `login --profile <name>` writes identity state for that profile and, unless
+  `--no-daemon` is set, attempts to start that profile daemon after login or
+  after detecting an already-logged-in profile.
+- `doctor --profile <name>` checks the selected profile's directory, lock,
+  state, daemon, and live daemon socket status.
+- `profile status <name>` reports the selected profile's profile directory,
+  profile-scoped lock, profile-scoped state, recent event, and daemon status.
+- Error messages for daemon running, start timeout, lock busy, stale daemon, and
+  daemon pause identify the affected profile.
+
+## 5. Verification
+
+- Focused unit coverage for profile-scoped paths, including Windows pipe names.
+- Focused unit coverage for profile status using profile-scoped locks/states.
+- Focused unit coverage for doctor platform helpers and profile-aware daemon
+  checks where deterministic.
+- Typecheck with `pnpm typecheck`.
+- Deterministic tests with `pnpm test:unit`.
+- Regenerate generated docs with `pnpm agent-context` after command/source/test
+  changes.
+- Run `pnpm agent-verify` as the final local gate.
+
+## 6. Acceptance criteria
+
+- `1688 daemon start --profile acc-a` starts only the `acc-a` daemon.
+- `1688 daemon start --profile acc-b` can coexist with `acc-a`.
+- `1688 daemon status --profile acc-a` and `--profile acc-b` inspect different
+  artifacts and sockets.
+- `1688 serve --profile acc-a` binds a daemon to `acc-a`.
+- `1688 search "..." --profile acc-a` tries the `acc-a` daemon first.
+- `1688 search "..." --profile acc-b` tries the `acc-b` daemon first.
+- A lock held by `acc-a` does not make `acc-b` report `LOCK_BUSY`.
+- A daemon pause or risk-control state in one profile is represented in that
+  profile daemon status and does not stop another profile daemon.
+- Commands without `--profile` continue to use the `default` profile.
+
+## 7. Assumptions and open questions
+
+- [ASSUMED] Profile names used by real workflows are simple names such as
+  `default`, `acc-a`, or `work`, without path separators.
+- [ASSUMED] Moving default daemon artifacts behind profile-aware helpers is
+  compatible because all public commands use those helpers rather than fixed
+  artifact paths.
+- [ASSUMED] Historical global `state.json` does not need an automated migration
+  for this change; a profile-specific state file is authoritative once this
+  version runs.

package/docs/specs/seller-im.md

@@ -0,0 +1,28 @@
+# Seller IM
+
+Seller IM commands cover pre-sale inquiry and post-sale follow-up through
+Wangwang/1688 chat.
+
+## Commands
+
+```bash
+1688 seller inquire <offerId> <message>
+1688 seller chat <orderId|loginId> <message>
+1688 seller messages --offer <offerId>
+1688 seller messages <orderId|loginId>
+1688 seller messages ... --watch
+1688 inbox
+```
+
+## Safety
+
+Sending messages contacts real suppliers. Follow `docs/SAFETY.md` before
+sending agent-authored text.
+
+## Agent Requirements
+
+- Preserve line-delimited JSON in watch mode.
+- Deduplicate messages by server-side `messageId` when available.
+- Preserve `kind` and `card` fields so agents can distinguish text, offer
+  cards, order cards, images, and auto replies.
+- Keep order/offer scoped conversations attached to the right context.

package/docs/specs/sourcing-research.md

@@ -0,0 +1,186 @@
+# Sourcing Research
+
+This spec defines the first durable sourcing-research layer for `1688-cli`.
+It turns search results into procurement decisions while preserving the CLI's
+buyer-workflow identity: human-paced, logged-in, safe for a real account, and
+agent-friendly JSON.
+
+## Goal
+
+Help an agent or buyer answer:
+
+- Which offers have demand?
+- Which suppliers look trustworthy?
+- Which offers are cheap enough for the target range?
+- Which offers deserve detail-page enrichment?
+- Which offer IDs should be compared before inquiry/cart/checkout?
+
+## Non-Goals
+
+- Do not build a bulk scraping farm.
+- Do not bypass login, risk control, or slider verification.
+- Do not add multi-account orchestration.
+- Do not claim supplier scores, repurchase rate, or service guarantees unless
+  the current 1688 payload exposes them reliably.
+- Do not make ordinary `search` slow by fetching every detail page.
+
+## Commands
+
+### `search`
+
+Add research-oriented read-only controls to ordinary keyword search:
+
+```bash
+1688 search <keyword> \
+  --sort relevance|best-selling|price-asc|price-desc \
+  --price-min 1 \
+  --price-max 50 \
+  --province 广东 \
+  --city 深圳 \
+  --verified any|factory|business|super-factory \
+  --min-turnover 100 \
+  --exclude-ads
+```
+
+`search` remains fast. Filters and local sort apply to the collected result
+set. Remote sort parameters may be added to the search URL when known, but the
+command must still locally normalize output ordering for deterministic agent
+behavior.
+
+### `research`
+
+Add a multi-keyword research command:
+
+```bash
+1688 research <keyword...> \
+  --max-per-query 60 \
+  --sort best-selling \
+  --price-max 50 \
+  --verified super-factory \
+  --enrich top:10 \
+  --jsonl
+```
+
+`research` runs keyword searches one by one, applies the same filters, scores
+offers, deduplicates by `offerId`, and optionally enriches only the top N
+results by calling `offer`.
+
+Supported export modes:
+
+- default: human table
+- JSON: normal automatic JSON when stdout is piped or `--json` is used
+- `--jsonl`: one research item per line
+- `--csv`: comma-separated table
+- optional `--output <file>`: write export to a file
+
+### `compare`
+
+Add a read-only offer comparison command:
+
+```bash
+1688 compare <offerId...>
+```
+
+It fetches each offer detail, computes comparable fields and a sourcing score,
+and shows price, MOQ, sale count, SKU count, stock, supplier, freight/package
+hints, and detail fetch errors.
+
+### `supplier inspect`
+
+Supplier-level inspection now lives in
+[`supplier-inspect.md`](supplier-inspect.md). V1 supports offerId, offer URL,
+`b2b-*` memberId, and factory-card URL. Direct loginId lookup remains out of
+scope because live probing showed it can resolve to the wrong factory.
+
+### `supplier search` / `supplier research`
+
+Supplier discovery from 1688's company search is specified separately in
+[`supplier-search.md`](supplier-search.md). These commands must use company
+search payloads and must not build supplier lists by aggregating offer-search
+results.
+
+## Data Model
+
+### Search Item
+
+Each `search` offer may include the existing fields plus additive research
+signals:
+
+```ts
+{
+  offerId: string,
+  title: string,
+  price: { text: string, min: number | null, max: number | null },
+  supplier: { name: string | null, shopUrl: string | null, years: number | null },
+  verified: { factory: boolean, business: boolean, superFactory: boolean },
+  tags: string[],
+  isP4P: boolean,
+  turnover: string | null,
+  demand?: {
+    orderCountText: string | null,
+    orderCount: number | null,
+    repurchaseRateText: string | null,
+    repurchaseRate: number | null,
+  },
+  serviceTags?: string[],
+  productBadges?: string[],
+}
+```
+
+### Research Item
+
+```ts
+{
+  sourceKeyword: string,
+  sourceRank: number,
+  globalRank: number,
+  offer: Offer,
+  demand: {
+    turnoverText: string | null,
+    orderCount: number | null,
+    repurchaseRate: number | null,
+  },
+  supplier: {
+    years: number | null,
+    verified: Offer["verified"],
+    tags: string[],
+    isAd: boolean,
+  },
+  score: number,
+  scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+  enriched?: OfferDetailSummary,
+  error?: { code: string, message: string },
+}
+```
+
+## Sourcing Score V1
+
+The score is explainable and bounded to 100.
+
+- Price: up to 25 points for a valid low price.
+- Demand: up to 25 points from turnover/order count.
+- Supplier tenure: up to 15 points from shop years.
+- Verification: up to 15 points for super factory, factory, or business
+  verification.
+- Service tags: up to 10 points from tags/service badges.
+- Organic result: up to 10 points when the offer is not P4P/ad.
+
+The score is a ranking aid, not a truth claim.
+
+## Failure Semantics
+
+For `research` and `compare`, distinguish:
+
+- run-level failure: login expired, risk control, browser/network failure that
+  prevents the command from continuing.
+- item-level failure: one offer detail fails during enrichment or comparison.
+
+Item-level failures stay attached to the item and should not fail the whole
+run unless every item fails.
+
+## Verification
+
+- Unit tests cover sorting, filters, score calculation, export formatting, and
+  enrichment option parsing.
+- `pnpm agent-context` refreshes generated command and JSON-shape indexes.
+- `pnpm agent-verify` is the default gate.

package/docs/specs/supplier-inspect.md

@@ -0,0 +1,144 @@
+# Supplier Inspect
+
+This spec defines the first reliable supplier-level inspection command for
+`1688-cli`. It is read-only and aimed at sourcing decisions after a buyer or
+agent has found an offer or supplier `memberId`.
+
+## Goal
+
+Help an agent or buyer answer:
+
+- Who is the supplier behind this offer?
+- Does the supplier expose factory/trust/service signals?
+- What factory card data is available: location, years, authentication,
+  production scope, staff/scale hints, and available offer count?
+- Which fields are observed from 1688 payloads versus unavailable?
+
+## Non-Goals
+
+- Do not bypass login, risk control, or slider verification.
+- Do not bulk scrape supplier catalogs.
+- Do not claim loginId lookup is reliable when the current site cannot resolve
+  it deterministically.
+- Do not perform write actions such as inquiry, favorite, cart, or checkout.
+- Do not invent scores that are not backed by observed payload fields.
+
+## Probe Findings
+
+Live headed probe on 2026-05-31 found these useful sources:
+
+- Offer detail page:
+  - `window.context.result.global.globalData.model.sellerModel`
+  - `mtop.1688.moga.pc.shopcard`
+- Factory card page:
+  - `https://sale.1688.com/factory/card.html?memberId=<memberId>`
+  - `mtop.com.alibaba.china.factory.card.common.fn.mtop.tpp.faas`
+- Factory card DOM text can expose a visible available-offer count such as
+  `共34个商品`.
+
+Direct `loginId` factory-card lookup is not reliable. A probe with
+`loginId=<sellerLoginId>` returned a different factory, so V1 must reject
+loginId-only input with a clear error instead of returning possibly wrong data.
+
+## Command
+
+```bash
+1688 supplier inspect <offerId|memberId|offerUrl|factoryCardUrl>
+```
+
+Supported target forms:
+
+- numeric `offerId`
+- `https://detail.1688.com/offer/<offerId>.html`
+- `b2b-*` supplier `memberId`
+- factory-card URL with a `memberId` query parameter
+
+Unsupported in V1:
+
+- loginId-only input, because live probe showed it can misresolve
+
+Options:
+
+```bash
+--profile <name>
+--headed
+```
+
+## JSON Contract
+
+```ts
+{
+  target: {
+    input: string,
+    type: "offerId" | "memberId",
+    offerId: string | null,
+    memberId: string | null,
+  },
+  supplier: {
+    name: string | null,
+    loginId: string | null,
+    memberId: string | null,
+    userId: string | null,
+    companyId: string | null,
+    shopUrl: string | null,
+    shopUrls: Record<string, string>,
+    identity: string | null,
+    signs: Record<string, boolean>,
+  },
+  factory: {
+    isFactory: boolean,
+    superFactory: boolean,
+    tpYears: number | null,
+    medalLevel: string | null,
+    thirdPartyAuthProvider: string | null,
+    establishedAtText: string | null,
+    location: string | null,
+    address: string | null,
+    coordinates: { latitude: number | null, longitude: number | null },
+    productionService: string | null,
+    employeeScale: string | null,
+    workerCount: string | null,
+    profile: string | null,
+    tags: string[],
+  },
+  trust: {
+    companyLabel: string | null,
+    retentionRate: number | null,
+    companyIcons: Array<{ title: string; link: string | null }>,
+    shopTags: string[],
+    serviceScores: Array<{ key: string; label: string; score: number | null }>,
+  },
+  offers: {
+    availableCount: number | null,
+    source: "factory-card-dom" | null,
+  },
+  sources: {
+    offerUrl: string | null,
+    factoryCardUrl: string | null,
+    shopcardCaptured: boolean,
+    factoryCardCaptured: boolean,
+  },
+  warnings: string[],
+}
+```
+
+All fields are additive and nullable. Missing values mean the current page or
+payload did not expose the signal.
+
+## Failure Semantics
+
+- `BAD_INPUT`: target is empty, malformed, or loginId-only.
+- `NOT_LOGGED_IN`: session expired.
+- `RISK_CONTROL`: 1688 risk challenge appeared; retry with `--headed`.
+- `NETWORK_ERROR`: navigation failed.
+- `SUPPLIER_NOT_FOUND`: no supplier identity could be read from a supported
+  target.
+
+## Verification
+
+- Unit tests cover target normalization and payload assembly helpers.
+- A live smoke test should inspect a known offerId and confirm:
+  - supplier identity is present
+  - memberId is present
+  - factory-card capture succeeds when memberId exists
+  - `loginId` direct input fails with `BAD_INPUT`

package/docs/specs/supplier-search.md

@@ -0,0 +1,179 @@
+# Supplier Search And Research
+
+This spec defines supplier discovery that starts from 1688's company search,
+not product-offer aggregation.
+
+## Goal
+
+Help a buyer or agent answer:
+
+- Which suppliers match this category keyword?
+- Which matching suppliers expose factory/trust/service signals?
+- Which suppliers deserve deeper `supplier inspect` enrichment?
+- Which suppliers should be contacted or compared after product discovery?
+
+## Source Boundary
+
+`supplier search` and `supplier research` must use 1688 company search. The
+known durable business endpoint from live probing is:
+
+```text
+search.1688.com/service/companySearchBusinessService
+```
+
+The page entry URL is:
+
+```text
+https://s.1688.com/company/company_search.htm?keywords=<GBK-percent-keyword>
+```
+
+Important encoding rule: `s.1688.com` expects GBK percent-encoded keywords.
+UTF-8 percent-encoding can search for mojibake and return zero or irrelevant
+results.
+
+Do not implement supplier discovery by running offer search and grouping
+offers by supplier. That is a different signal and can hide suppliers that are
+available in company search.
+
+## Commands
+
+### `supplier search`
+
+```bash
+1688 supplier search <keyword...> \
+  --max 20 \
+  --factory-only \
+  --province 广东 \
+  --city 深圳 \
+  --min-years 3 \
+  --min-repeat-rate 0.4 \
+  --min-response-rate 0.6 \
+  --enrich 0
+```
+
+Default behavior is supplier discovery only. `--enrich` is optional and
+defaults to `0`.
+
+### `supplier research`
+
+```bash
+1688 supplier research <keyword...> \
+  --max 20 \
+  --factory-only \
+  --enrich top:10 \
+  --jsonl
+```
+
+`supplier research` uses the same company-search source and scoring, but
+defaults to `--enrich top:10`. Enrichment calls `supplier inspect` with the
+company-search `memberId` when present.
+
+Supported export modes:
+
+- default: human table
+- JSON: automatic when stdout is piped or `--json` is used
+- `--jsonl`: one supplier item per line
+- `--csv`: comma-separated table
+- `--output <file>`: write JSONL/CSV to a file
+
+## Data Model
+
+Each item records source keyword/rank, normalized company-search supplier
+signals, score, and optional inspect enrichment:
+
+```ts
+{
+  sourceKeyword: string,
+  sourceRank: number,
+  globalRank: number,
+  supplier: {
+    companyName: string,
+    loginId: string | null,
+    memberId: string | null,
+    enterpriseId: string | null,
+    realUserId: string | null,
+    companyId: string | null,
+    shopUrl: string | null,
+    factoryCardUrl: string | null,
+    location: { province: string | null, city: string | null, address: string | null },
+    productionService: string | null,
+    tp: { serviceYears: number | null, memberLevel: string | null },
+    factory: {
+      isFactory: boolean,
+      factoryTag: string | null,
+      factoryLevel: string | null,
+      superFactory: boolean,
+      businessInspection: boolean,
+      factoryInspection: boolean,
+    },
+    service: {
+      compositeScore: number | null,
+      wwResponseRate: number | null,
+      repeatRate: number | null,
+    },
+    demand: {
+      payOrderCount3m: number | null,
+      payAmount3m: number | null,
+      fuzzyPayAmount3m: string | null,
+      saleQuantity3m: number | null,
+    },
+    tags: string[],
+    offersPreview: SupplierOfferPreview[],
+  },
+  score: number,
+  scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+  inspect?: SupplierInspectResult,
+  error?: { code: string, message: string },
+}
+```
+
+The top-level result includes:
+
+```ts
+source: {
+  kind: "company-search",
+  endpoint: "companySearchBusinessService",
+  offerAggregation: false,
+}
+```
+
+## Score V1
+
+The supplier score is a ranking aid, not a truth claim.
+
+- Company-search demand: up to 25 points from 3-month pay order count.
+- Supplier tenure: up to 15 points from service years.
+- Factory/trust: up to 20 points from factory/super-factory/inspection flags.
+- Service rates: up to 15 points from repeat and Wangwang response rates.
+- Composite score: up to 10 points.
+- Offer preview depth: up to 10 points from company-search previews.
+
+## Failure Semantics
+
+- Run-level failure: login expired, risk control, browser/network failure that
+  prevents company search from loading.
+- Empty result: company search loads but returns no supplier payload.
+- Item-level enrichment failure: `supplier inspect` fails for one supplier;
+  keep the supplier item and attach `error`.
+
+If a command exits with risk-control code `4`, retry once with `--headed` and
+solve the slider manually.
+
+## V1 Boundaries
+
+Live probing on 2026-06-04 showed the company search page emits
+`companySearchBusinessService` with `companyWithOfferLists`. A typical first
+page async response used `startIndex=6&asyncCount=14`; this likely means some
+top-page suppliers may be server-rendered before the async service response.
+V1 uses the stable browser-emitted business response and keeps the largest
+captured company-search payload. A later V2 can add HTML/DOM extraction for
+server-rendered supplier cards if we need exact 20-per-page completeness.
+
+## Verification
+
+- Unit tests cover GBK company-search URL construction.
+- Unit tests cover `companySearchBusinessService` parsing and offer previews.
+- Unit tests cover capture `keep: "largest"` behavior.
+- Unit tests cover enrich option parsing and CSV escaping.
+- `pnpm agent-context` refreshes generated command and JSON-shape indexes.
+- `pnpm agent-verify` is the default gate.