1688-cli 0.1.40 → 0.1.42

package/docs/JSON_CONTRACTS.md

@@ -0,0 +1,390 @@
+# JSON Contracts
+
+The CLI auto-switches to JSON when stdout is piped. Stable JSON output is part
+of the agent contract. Prefer additive changes; do not rename or remove fields
+without an explicit breaking-change decision.
+
+## Output Rules
+
+- `--json` forces JSON in a TTY.
+- `--pretty` indents JSON by two spaces.
+- `--get <path>` prints one dot-path. Scalars are raw lines; objects and arrays
+  remain JSON.
+- `--pick <paths>` emits a JSON object with each requested path as a key.
+- Watch commands emit line-delimited JSON, one object per new event/message.
+
+## `whoami`
+
+```ts
+{ loggedIn: true, memberId: string, nick: string, lastVerifiedAt: string }
+{ loggedIn: false }
+```
+
+## `search`, `similar`, `image-search`
+
+```ts
+{
+  keyword?: string,
+  imageId?: string,
+  offerId?: string,
+  sort?: "relevance" | "best-selling" | "price-asc" | "price-desc",
+  filters?: object,
+  totalBeforeFilter?: number,
+  total: number,
+  offers: Array<{
+    offerId: string,
+    title: string,
+    price: { text: string, min: number | null, max: number | null },
+    supplier: { name: string | null, shopUrl: string | null, years: number | null },
+    location: { province: string | null, city: string | null },
+    bizType: string | null,
+    verified: { factory: boolean, business: boolean, superFactory: boolean },
+    tags: string[],
+    serviceTags?: string[],
+    productBadges?: string[],
+    demand?: {
+      orderCountText: string | null,
+      orderCount: number | null,
+      repurchaseRateText: string | null,
+      repurchaseRate: number | null,
+    },
+    isP4P: boolean,
+    turnover: string | null,
+    url: string,
+    image: string | null,
+  }>
+}
+```
+
+## `research`
+
+Normal JSON result:
+
+```ts
+{
+  queries: string[],
+  sort: "relevance" | "best-selling" | "price-asc" | "price-desc",
+  filters: object,
+  maxPerQuery: number,
+  enrichTop: number,
+  total: number,
+  enrichedCount: number,
+  items: Array<{
+    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 },
+  }>,
+}
+```
+
+`--jsonl` emits one research item per line. `--csv` emits a CSV table.
+
+## `compare`
+
+```ts
+{
+  total: number,
+  ok: number,
+  failed: number,
+  items: Array<{
+    offerId: string,
+    ok: boolean,
+    score: number | null,
+    scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+    summary: OfferDetailSummary | null,
+    error?: { code: string, message: string },
+  }>,
+}
+```
+
+## `supplier inspect`
+
+```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[],
+}
+```
+
+V1 supports offerId, offer URL, `b2b-*` memberId, and factory-card URL.
+loginId-only input is rejected because live probing showed it can resolve to
+the wrong supplier.
+
+## `supplier search`, `supplier research`
+
+Supplier discovery uses 1688 company search
+(`companySearchBusinessService`). It must not be treated as offer-search
+supplier aggregation.
+
+```ts
+{
+  queries: string[],
+  source: {
+    kind: "company-search",
+    endpoint: "companySearchBusinessService",
+    offerAggregation: false,
+  },
+  filters: {
+    factoryOnly: boolean,
+    province: string | null,
+    city: string | null,
+    minYears: number | null,
+    minRepeatRate: number | null,
+    minResponseRate: number | null,
+  },
+  maxPerQuery: number,
+  enrichTop: number,
+  totalBeforeFilter: number,
+  total: number,
+  enrichedCount: number,
+  items: Array<{
+    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,
+      domainUri: string | null,
+      location: {
+        province: string | null,
+        city: string | null,
+        address: string | null,
+        latitude: number | null,
+        longitude: number | null,
+      },
+      productionService: string | null,
+      businessMode: string | null,
+      tp: {
+        memberLevel: string | null,
+        serviceYears: number | null,
+        tpNum: number | null,
+      },
+      factory: {
+        isFactory: boolean,
+        factoryTag: string | null,
+        factoryLevel: string | null,
+        shiliFactory: boolean,
+        shiliCompany: boolean,
+        superFactory: boolean,
+        businessInspection: boolean,
+        factoryInspection: boolean,
+        qiJianCompany: boolean,
+        safePurchase: boolean,
+        trust: boolean,
+      },
+      service: {
+        compositeScore: number | null,
+        wwResponseRate: number | null,
+        repeatRate: number | null,
+        complianceRate: number | null,
+      },
+      demand: {
+        payOrderCount3m: number | null,
+        payAmount3m: number | null,
+        fuzzyPayAmount3m: string | null,
+        saleQuantity3m: number | null,
+        memberBookedCount: number | null,
+      },
+      tags: string[],
+      offersPreview: Array<{
+        offerId: string | null,
+        title: string,
+        url: string | null,
+        price: { text: string | null, value: number | null },
+        unit: string | null,
+        image: string | null,
+        bookedCount: number | null,
+        saleQuantity: number | null,
+        quantitySumMonth: number | null,
+        brief: string | null,
+      }>,
+    },
+    score: number,
+    scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+    inspect?: SupplierInspectResult,
+    error?: { code: string, message: string },
+  }>,
+}
+```
+
+`supplier search` defaults to `--enrich 0`; `supplier research` defaults to
+`--enrich top:10`. `--jsonl` emits one supplier item per line. `--csv` emits a
+CSV table.
+
+## `offer`
+
+```ts
+{
+  offerId: string,
+  title: string,
+  url: string,
+  priceRange: string | null,
+  priceMin: number | null,
+  priceMax: number | null,
+  unitName: string | null,
+  minOrderQty: number | null,
+  mixOrderQty: number | null,
+  priceTiers: Array<{ minQty: number, price: number }>,
+  detailUrl: string | null,
+  attributes: Array<{ name: string, value: string }>,
+  packageInfo: Array<{
+    skuId: string,
+    spec: string,
+    length: number | null,
+    width: number | null,
+    height: number | null,
+    weight: number | null,
+    volume: number | null,
+  }>,
+  supplier: {
+    name: string | null,
+    loginId: string | null,
+    memberId: string | null,
+    userId: string | null,
+  },
+  freight: {
+    receiveAddress: string | null,
+    sendArea: string | null,
+    province: string | null,
+    city: string | null,
+    unitWeight: number | null,
+  },
+  saledCount: number | null,
+  categoryId: string | null,
+  options: Array<{ prop: string, values: Array<{ name: string, imageUrl: string | null }> }>,
+  skus: Array<{
+    skuId: string,
+    specs: string,
+    price: number | null,
+    multiPrice: number | null,
+    stock: number | null,
+    saleCount: number,
+    image: string | null,
+  }>,
+  mainImage: string | null,
+  images: string[],
+}
+```
+
+## `seller messages`
+
+One-shot result:
+
+```ts
+{
+  conversation: string,
+  total: number,
+  messages: Array<{
+    sender: string,
+    time: string | null,
+    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,
+  }>,
+}
+```
+
+Watch mode emits one object per new message:
+
+```ts
+{ conversation: string, message: Message }
+```
+
+## `cart add`
+
+```ts
+{
+  ok: boolean,
+  added: CartItem,
+  isNewRow: boolean,
+  addedQuantity: number,
+}
+```
+
+## `order list`
+
+Orders include buyer actions, service entries, and display badges. Preserve
+`actions[]`, `services[]`, and `badges[]` because downstream agents use them to
+decide what follow-up is possible.
+
+## Generated Shape Index
+
+Run `pnpm agent-context` to refresh `docs/generated/json-shapes.md`, which
+indexes exported TypeScript interfaces from command modules.

package/docs/QUALITY_SCORE.md

@@ -0,0 +1,60 @@
+# Quality Score
+
+This file tracks agent-readiness and known quality gaps. Keep it blunt and
+mechanical; it is a map for improvement, not a blame document.
+
+## Current Score
+
+Overall: 6 / 10
+
+## Strengths
+
+- Clear buyer-journey command surface exists: sourcing, inquiry, cart,
+  checkout, tracking, and post-sale chat.
+- Commands expose JSON automatically when piped and support `--json`,
+  `--pretty`, `--get`, and `--pick`.
+- Real browser/session behavior is centralized under `src/session`.
+- The daemon gives agents a warm, shared browser context.
+- Checkout and feedback write actions already have explicit safety protocols.
+- Deterministic Vitest coverage exists for output, mtop parsing, recovery,
+  page-state, inbox cards, and fixtures through `pnpm test:unit`.
+- Agent map docs and generated indexes now exist.
+
+## Gaps Blocking Higher Agent Autonomy
+
+- `AGENTS.md` was historically long; future work should keep it short and keep
+  durable detail in `docs/`.
+- Generated context is heuristic and should improve as command/result types
+  evolve.
+- Browser/live verification is not part of the default gate and needs explicit
+  manual/probe checks.
+- Sourcing research fields such as repurchase rate, supplier scores, and
+  service badges are not yet normalized.
+- Some probe scripts are exploratory and not documented as stable workflows.
+- JSON compatibility policy exists in docs but is not yet enforced by schema
+  tests.
+
+## Last Known Verification Snapshot
+
+On 2026-05-28, `pnpm agent-verify` passed:
+
+- `pnpm typecheck`
+- `pnpm test:unit` (22 files, 151 tests)
+- `pnpm docs-check`
+- `pnpm agent-map-check`
+
+On 2026-05-28, full `pnpm test` failed in `tests/doctor-live.test.ts` because
+the live doctor checks returned `DOCTOR_FAILED` in the current local
+environment. The default agent gate uses `pnpm test:unit` to keep live checks
+explicit.
+
+## Quality Targets
+
+- 6 / 10: short map, docs map, generated indexes, and default verification
+  gate exist.
+- 7 / 10: JSON contract tests cover all stable command outputs and docs-check
+  runs in CI.
+- 8 / 10: browser/live verification playbooks are repeatable and key mtop
+  payloads have fixture-backed parsers.
+- 9 / 10: sourcing research scoring, supplier-quality extraction, and
+  autonomous inbox workflows have deterministic harness tests.

package/docs/README.md

@@ -0,0 +1,35 @@
+# Documentation Map
+
+This directory is the canonical knowledge base for agents and humans working on
+`1688-cli`. Keep `AGENTS.md` short and put durable context here.
+
+## Start Here
+
+- Agent working principles: [`AGENT_WORKING_PRINCIPLES.md`](AGENT_WORKING_PRINCIPLES.md)
+- Repository architecture: [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
+- Default workflow: [`WORKFLOW.md`](WORKFLOW.md)
+- Command catalog: [`COMMANDS.md`](COMMANDS.md)
+- JSON contracts: [`JSON_CONTRACTS.md`](JSON_CONTRACTS.md)
+- Safety rules: [`SAFETY.md`](SAFETY.md)
+- Reliability notes: [`RELIABILITY.md`](RELIABILITY.md)
+- Quality score: [`QUALITY_SCORE.md`](QUALITY_SCORE.md)
+- Feature backlog: [`FEATURES.md`](FEATURES.md)
+- Agent maps plan: [`AGENT_MAPS_PLAN.md`](AGENT_MAPS_PLAN.md)
+
+## Domain Knowledge
+
+- Specs: [`specs/`](specs/)
+- Repeatable playbooks: [`playbooks/`](playbooks/)
+- Generated repository indexes: [`generated/`](generated/)
+- Long-running plans: [`exec-plans/`](exec-plans/)
+
+## Maintenance Rules
+
+- Update command docs when command names, flags, behavior, or examples change.
+- Update JSON contracts when agent-facing output shape changes.
+- Update safety docs when a write action, approval boundary, login flow, or
+  checkout behavior changes.
+- Add or update a playbook when an agent repeats the same workflow twice.
+- Run `pnpm agent-context` after changing commands, exported result
+  interfaces, source layout, or tests.
+- Run `pnpm agent-verify` before handoff, or record the exact blocker.

package/docs/RELIABILITY.md

@@ -0,0 +1,61 @@
+# Reliability
+
+`1688-cli` depends on a live website, browser automation, mtop responses, and a
+real logged-in buyer session. Reliability work should make failures explicit
+and recoverable for agents.
+
+## Daemon
+
+The daemon routes commands through one persistent Chromium context.
+
+Benefits:
+
+- Saves Chrome cold-start time.
+- Keeps one continuous logged-in session.
+- Adds inter-command jitter.
+
+Use `1688 daemon start` near the beginning of a session with multiple 1688
+commands. The daemon auto-stops after inactivity. Run `1688 daemon reload`
+after package updates.
+
+`login`, `logout`, and `doctor` stay inline because they need interactive UI,
+browser windows, or environment checks.
+
+## Watch Mode
+
+`1688 seller messages ... --watch` is designed to stay alive.
+
+- It prints a baseline line to stderr.
+- It emits one JSON object to stdout for each newly-arrived message.
+- History is not re-emitted.
+- Deduplication uses server-side `messageId` when present.
+- It exits cleanly on SIGINT.
+
+Agent loops should parse stdout line by line and should not assume the process
+will exit by itself.
+
+## Browser Recovery
+
+Commands should detect and report:
+
+- login redirects
+- risk-control / slider pages
+- closed browser windows
+- empty mtop captures
+- network failures
+
+Use structured `CliError` exit codes so agents can choose the next safe step.
+
+## Probes And Fixtures
+
+Probe scripts under `scripts/probe-*.mjs` are useful for discovering page
+behavior, selectors, and mtop payloads. They are not stable automated tests.
+
+Stable behavior belongs in `tests/` with fixtures where possible.
+
+## Live-Service Boundaries
+
+`pnpm test:unit` is the deterministic default. `pnpm test` also runs live
+doctor checks and may depend on local browser/session state. Browser or
+account-mutating checks should be explicit, bounded, and documented in the
+final response when they cannot be run.

package/docs/SAFETY.md

@@ -0,0 +1,100 @@
+# Safety
+
+This tool operates a real 1688 buyer account. Some commands read public or
+account data; others contact sellers, mutate cart state, submit feedback, or
+place orders. Treat write actions as explicit user-authorized operations.
+
+## Exit Codes
+
+| Code | Meaning | Agent behavior |
+|---:|---|---|
+| 0 | Success | Continue. |
+| 2 | Bad invocation | Fix arguments or report the bad input. |
+| 3 | Not logged in / session expired | Tell the user to run `1688 login`; do not loop. |
+| 4 | Risk control / slider verification | Tell the user to rerun once with `--headed`; do not silently retry. |
+| 5 | Another 1688 command is running | Wait only if the task naturally allows it; otherwise report lock busy. |
+| 6 | Chromium missing | Report dependency issue. |
+| 7 | Login wait timeout | Report timeout. |
+| 8 | Login finished but cookies missing | Report login cookie issue. |
+| 9 | Network error | Report or retry only when safe and bounded. |
+| 130 | User canceled | Stop. |
+
+## Login And Logout
+
+- `1688 login` opens a user-interactive QR/browser flow. Only run it when the
+  user explicitly asks to log in.
+- In non-interactive sessions, `1688 login` saves a QR PNG to
+  `~/.1688/login-qr.png` and prints `QR saved as PNG: <path>` on stderr.
+  Surface that file/path to the user and wait for the command to exit.
+- Do not open the raw QR URL in a browser.
+- `1688 logout --yes` destroys the cached session. Do not pass `--yes` without
+  explicit current-turn confirmation.
+
+## Risk Control
+
+- If exit code `4` appears, tell the user to rerun the same command once with
+  `--headed`.
+- The user must solve the slider manually.
+- Do not silently retry the same blocked command.
+
+## Seller Contact
+
+These commands contact real sellers:
+
+```bash
+1688 seller inquire <offerId> <message>
+1688 seller chat <orderId|loginId> <message>
+```
+
+Before sending, show the message and target context unless the user has already
+given an explicit current-turn send instruction.
+
+## Cart Mutations
+
+These commands mutate buyer cart state:
+
+```bash
+1688 cart add <offerId> --sku <skuId> --qty N
+1688 cart remove <cartId>
+```
+
+For agent use, show the offer/SKU/quantity or cart row being changed and run
+only after the user approves that action.
+
+## Checkout Protocol
+
+`1688 checkout confirm` places a real order. It does not pay automatically, but
+it commits the buyer to the seller.
+
+Agent protocol:
+
+1. Run `1688 checkout prepare <cartIds...>`.
+2. Show the full preview: total, items, address, seller, and cart IDs.
+3. Wait for explicit current-turn approval such as "yes, place it" or
+   "下单吧".
+4. Run `1688 checkout confirm <cartIds...> --agent`.
+5. Report the final order ID and URL.
+
+Never run `--agent` without this prepare plus approval cycle. Never infer
+authorization from older messages.
+
+## Feedback Submission
+
+`1688 feedback "<message>"` prepares a GitHub issue URL. That is safe by
+default.
+
+`1688 feedback "<message>" --submit` posts publicly through `gh`. Do not add
+`--submit` unless the user explicitly asks to submit/post the issue.
+
+## Update Awareness
+
+`1688 doctor --no-launch --json` reports version information. Any JSON-mode
+command may also emit an update notice on stderr.
+
+Rules:
+
+- In an interactive session, ask once before running the printed global install
+  command.
+- In non-interactive loops, do not upgrade automatically.
+- After an approved package update, run `1688 daemon reload`.
+