1688-cli 0.1.41 → 0.1.42

package/docs/generated/json-shapes.md

@@ -0,0 +1,111 @@
+# JSON Shapes
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+This is a heuristic index of exported TypeScript interfaces that are likely to matter for agent-facing JSON.
+
+| Interface | File | Notable Fields |
+|---|---|---|
+| `CartAddArgs` | `src/commands/cart-add.ts` | `offerId: string;`<br>`skuId: string;`<br>`quantity: number;`<br>`headed?: boolean;` |
+| `CartAddOpts` | `src/commands/cart-add.ts` | `offerId: string;`<br>`sku?: string;`<br>`qty?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CartAddResult` | `src/commands/cart-add.ts` | `ok: boolean;`<br>`confirmationStatus: 'confirmed';`<br>`added: CartItem;`<br>`/** True when a brand-new cart row was created. False when the SKU was`<br>`isNewRow: boolean;`<br>`/** Actual quantity added by this call. For a new row it equals`<br>`addedQuantity: number;` |
+| `CartItem` | `src/commands/cart-list.ts` | `cartId: string;`<br>`offerId: string;`<br>`skuId: string \| null;`<br>`productTitle: string;`<br>`skuTitle: string \| null;`<br>`unit: string \| null;`<br>`quantity: number;`<br>`unitPrice: number;`<br>`amount: number;`<br>`minQuantity: number \| null;`<br>`maxQuantity: number \| null;`<br>`image: string \| null;`<br>`checked: boolean;`<br>`effective: boolean;` |
+| `CartListArgs` | `src/commands/cart-list.ts` | `headed?: boolean;` |
+| `CartListOpts` | `src/commands/cart-list.ts` | `profile?: string;`<br>`headed?: boolean;` |
+| `CartListResult` | `src/commands/cart-list.ts` | `total: number;`<br>`selectedCount: number;`<br>`items: CartItem[];` |
+| `CartRemoveArgs` | `src/commands/cart-remove.ts` | `cartId: string;`<br>`headed?: boolean;` |
+| `CartRemoveOpts` | `src/commands/cart-remove.ts` | `cartId: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CartRemoveResult` | `src/commands/cart-remove.ts` | `ok: boolean;`<br>`removed: CartItem;` |
+| `CheckoutConfirmArgs` | `src/commands/checkout-confirm.ts` | `cartIds: string[];`<br>`headed?: boolean;` |
+| `CheckoutConfirmOpts` | `src/commands/checkout-confirm.ts` | `cartIds: string[];`<br>`yes?: boolean;`<br>`agent?: boolean;`<br>`profile?: string;` |
+| `CheckoutConfirmResult` | `src/commands/checkout-confirm.ts` | `ok: boolean;`<br>`placed: boolean;`<br>`finalUrl: string;`<br>`orderId: string \| null;`<br>`message: string;`<br>`preview: CheckoutPrepareResult;` |
+| `CheckoutPrepareArgs` | `src/commands/checkout-prepare.ts` | `cartIds: string[];`<br>`headed?: boolean;` |
+| `CheckoutPrepareOpts` | `src/commands/checkout-prepare.ts` | `cartIds: string[];`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CheckoutPrepareResult` | `src/commands/checkout-prepare.ts` | `ok: boolean;`<br>`url: string;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shippingAmount: number;`<br>`taxAmount: number;`<br>`receiveAddress: {`<br>`fullName: string \| null;`<br>`mobile: string \| null;`<br>`address: string \| null;`<br>`region: string \| null;`<br>`orders: PrepareOrder[];` |
+| `PrepareOrder` | `src/commands/checkout-prepare.ts` | `seller: {`<br>`memberId: string \| null;`<br>`loginId: string \| null;`<br>`companyName: string \| null;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shippingAmount: number;`<br>`items: PrepareItem[];` |
+| `CompareOpts` | `src/commands/compare.ts` | `offerIds: string[];`<br>`csv?: boolean;`<br>`output?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CompareResult` | `src/commands/compare.ts` | `total: number;`<br>`ok: number;`<br>`failed: number;`<br>`items: CompareItem[];` |
+| `DebugLastOpts` | `src/commands/debug.ts` | `failed?: boolean;` |
+| `DebugListOpts` | `src/commands/debug.ts` | `limit?: string;`<br>`failed?: boolean;` |
+| `DebugShowOpts` | `src/commands/debug.ts` | `requestId: string;` |
+| `DoctorOpts` | `src/commands/doctor.ts` | `launch?: boolean;`<br>`live?: boolean;`<br>`profile?: string;` |
+| `FeedbackOpts` | `src/commands/feedback.ts` | `message?: string;`<br>`bug?: boolean;`<br>`open?: boolean;`<br>`submit?: boolean;` |
+| `FeedbackResult` | `src/commands/feedback.ts` | `url: string;`<br>`title: string;`<br>`bodyPreview: string;`<br>`submitted: boolean;` |
+| `ImageSearchArgs` | `src/commands/image-search.ts` | `imagePath: string;`<br>`max: number;`<br>`headed?: boolean;` |
+| `ImageSearchOpts` | `src/commands/image-search.ts` | `imagePath: string;`<br>`max?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `ImageSearchResult` | `src/commands/image-search.ts` | `imageId: string;`<br>`total: number;`<br>`offers: Offer[];` |
+| `InboxArgs` | `src/commands/inbox.ts` | `limit: number;`<br>`unreadOnly: boolean;`<br>`myLoginId: string;`<br>`myMemberId: string;`<br>`headed?: boolean;` |
+| `InboxOpts` | `src/commands/inbox.ts` | `limit?: string;`<br>`unread?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `InboxResult` | `src/commands/inbox.ts` | `myLoginId: string;`<br>`myMemberId: string;`<br>`conversations: Conversation[];`<br>`nextCursor: number \| null;`<br>`truncated: boolean;` |
+| `LoginOpts` | `src/commands/login.ts` | `force?: boolean;`<br>`timeout?: string;`<br>`profile?: string;`<br>`headed?: boolean;`<br>`noDaemon?: boolean;` |
+| `LogoutOpts` | `src/commands/logout.ts` | `yes?: boolean;`<br>`profile?: string;` |
+| `OfferArgs` | `src/commands/offer.ts` | `offerId: string;`<br>`headed?: boolean;` |
+| `OfferOpts` | `src/commands/offer.ts` | `offerId: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OfferResult` | `src/commands/offer.ts` | `offerId: string;`<br>`title: string;`<br>`url: string;`<br>`priceRange: string \| null;`<br>`priceMin: number \| null;`<br>`priceMax: number \| null;`<br>`/** Display unit ("件" / "个" / "米" ...) */`<br>`unitName: string \| null;`<br>`/** 起订量 — minimum order quantity for a single SKU buy. */`<br>`minOrderQty: number \| null;`<br>`/** 混批起订量 — minimum quantity when mixing SKUs in one order. */`<br>`mixOrderQty: number \| null;`<br>`/** Bulk-discount tiers, e.g. [{minQty: 1, price: 4.16}, {minQty: 100, price: 3.50}]. */`<br>`priceTiers: PriceTier[];` |
+| `PriceTier` | `src/commands/offer.ts` | `minQty: number;`<br>`price: number;` |
+| `ProductAttribute` | `src/commands/offer.ts` | `name: string;`<br>`value: string;` |
+| `SkuOption` | `src/commands/offer.ts` | `prop: string;`<br>`values: { name: string; imageUrl: string \| null }[];` |
+| `SkuPackage` | `src/commands/offer.ts` | `skuId: string;`<br>`spec: string;`<br>`/** cm */`<br>`length: number \| null;`<br>`width: number \| null;`<br>`height: number \| null;`<br>`/** Stated weight (raw value — 1688 sometimes uses grams or kg per offer). */`<br>`weight: number \| null;`<br>`/** Volume (cm³). */`<br>`volume: number \| null;` |
+| `SkuVariant` | `src/commands/offer.ts` | `skuId: string;`<br>`specs: string;`<br>`price: number \| null;`<br>`/** Bulk-tier price when 1688 surfaces a separate multi-piece price. */`<br>`multiPrice: number \| null;`<br>`stock: number \| null;`<br>`saleCount: number;`<br>`/** Best-effort image URL derived from the first option (颜色/款式) match. */`<br>`image: string \| null;` |
+| `OrderGetArgs` | `src/commands/order-get.ts` | `orderId: string;`<br>`maxScanPages: number;`<br>`/** Narrow scan to a specific tradeStatus when known — much faster for`<br>`statusHint?: string;`<br>`headed?: boolean;` |
+| `OrderGetOpts` | `src/commands/order-get.ts` | `orderId: string;`<br>`maxScanPages?: string;`<br>`status?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `Order` | `src/commands/order-list.ts` | `orderId: string;`<br>`status: string;`<br>`statusLabel: string;`<br>`bizType: string \| null; // "cb" / "pc" / ...`<br>`createdAt: string;`<br>`paidAt: string \| null;`<br>`shippedAt: string \| null;`<br>`confirmGoodsTime: string \| null;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shipping: number;`<br>`originalAmount: number; // before any promotions`<br>`discountAmount: number; // sum of all promotions applied`<br>`adjustment: number; // seller manual price adjustment (改价)` |
+| `OrderAction` | `src/commands/order-list.ts` | `key: string; // permissionKey, e.g. "canBuyerRefund"`<br>`name: string; // display name, e.g. "申请退款"`<br>`url: string \| null;`<br>`highlight: boolean;` |
+| `OrderItem` | `src/commands/order-list.ts` | `entryId: string;`<br>`productName: string;`<br>`spec: string;`<br>`quantity: number;`<br>`unitPrice: number;`<br>`amount: number;`<br>`image: string \| null;`<br>`productNumber: string \| null;` |
+| `OrderListArgs` | `src/commands/order-list.ts` | `status: string;`<br>`page: number;`<br>`pageSize: number;`<br>`headed?: boolean;` |
+| `OrderListOpts` | `src/commands/order-list.ts` | `status?: string;`<br>`page?: string;`<br>`pageSize?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OrderListResult` | `src/commands/order-list.ts` | `status: string;`<br>`page: number;`<br>`pageSize: number;`<br>`totalPages: number;`<br>`totalOrders: number;`<br>`orders: Order[];` |
+| `OrderService` | `src/commands/order-list.ts` | `productName: string;`<br>`category: string; // "insurance" / "refund" / ...`<br>`payer: string; // "seller" / "buyer"`<br>`detailLink: string \| null;` |
+| `OrderStep` | `src/commands/order-list.ts` | `status: string;`<br>`name: string;`<br>`paid: number;`<br>`goods: number;`<br>`postage: number;` |
+| `OrderLogisticsArgs` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`maxScanPages: number;`<br>`/** Narrow the scan to one tradeStatus (e.g. "waitbuyerreceive") when known —`<br>`statusHint?: string;`<br>`headed?: boolean;` |
+| `OrderLogisticsOpts` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`maxScanPages?: string;`<br>`status?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OrderLogisticsResult` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`found: boolean;`<br>`trace: LogisticsTrace[];` |
+| `ResearchOpts` | `src/commands/research.ts` | `keywords: string[];`<br>`maxPerQuery?: string;`<br>`sort?: string;`<br>`priceMin?: string;`<br>`priceMax?: string;`<br>`province?: string;`<br>`city?: string;`<br>`verified?: string;`<br>`minTurnover?: string;`<br>`excludeAds?: boolean;`<br>`enrich?: string;`<br>`jsonl?: boolean;`<br>`csv?: boolean;`<br>`output?: string;` |
+| `ResearchResult` | `src/commands/research.ts` | `queries: string[];`<br>`sort: SearchSort;`<br>`filters: SearchFilterSummary;`<br>`maxPerQuery: number;`<br>`enrichTop: number;`<br>`total: number;`<br>`enrichedCount: number;`<br>`items: ResearchItem[];` |
+| `SearchArgs` | `src/commands/search.ts` | `keyword: string;`<br>`max: number;`<br>`sort?: SearchSort;`<br>`filters?: SearchFilterSummary;`<br>`headed?: boolean;` |
+| `SearchOpts` | `src/commands/search.ts` | `max?: string;`<br>`sort?: string;`<br>`priceMin?: string;`<br>`priceMax?: string;`<br>`province?: string;`<br>`city?: string;`<br>`verified?: string;`<br>`minTurnover?: string;`<br>`excludeAds?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SearchResult` | `src/commands/search.ts` | `keyword: string;`<br>`sort: SearchSort;`<br>`filters: SearchFilterSummary;`<br>`totalBeforeFilter: number;`<br>`total: number;`<br>`offers: Offer[];` |
+| `SellerChatArgs` | `src/commands/seller-chat.ts` | `/** Display name(s) to find seller in 旺旺 sidebar — try in order */`<br>`searchNames: string[];`<br>`/** Seller loginId (raw, no cnalichn prefix) for order/offer-context URL */`<br>`sellerLoginId?: string;`<br>`/** Order ID — passed in URL to trigger order-scoped conversation */`<br>`orderId?: string;`<br>`/** Offer ID — passed in URL to trigger pre-sale (offer-scoped) conversation */`<br>`offerId?: string;`<br>`myLoginId: string;`<br>`message: string;`<br>`headed?: boolean;` |
+| `SellerChatOpts` | `src/commands/seller-chat.ts` | `target?: string;`<br>`message: string;`<br>`prefix?: boolean;`<br>`/** Skip sending order card link before message (use for follow-up replies) */`<br>`noCard?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SellerChatResult` | `src/commands/seller-chat.ts` | `ok: boolean;`<br>`sentTo: string;`<br>`message: string;`<br>`sentAt: string;` |
+| `SellerInquireOpts` | `src/commands/seller-inquire.ts` | `offerId: string;`<br>`message: string;`<br>`to?: string; // explicit seller loginId`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `Message` | `src/commands/seller-messages.ts` | `sender: string;`<br>`time: string \| null;`<br>`isMine: boolean;`<br>`content: string;`<br>`read: boolean;`<br>`/** Type of message — auto-detected from DOM. */`<br>`kind: MessageKind;`<br>`/** Populated when kind === 'offerCard' or 'orderCard'. */`<br>`card?: {`<br>`title: string \| null;`<br>`price: string \| null;`<br>`image: string \| null;`<br>`url: string \| null;`<br>`/** Server-side message ID (only present when sourced from WS). Used for` |
+| `SellerMessagesArgs` | `src/commands/seller-messages.ts` | `searchNames: string[];`<br>`sellerLoginId?: string;`<br>`orderId?: string;`<br>`offerId?: string;`<br>`myLoginId: string;`<br>`limit: number;`<br>`headed?: boolean;` |
+| `SellerMessagesOpts` | `src/commands/seller-messages.ts` | `target?: string;`<br>`offer?: string;`<br>`limit?: string;`<br>`since?: string;`<br>`watch?: boolean;`<br>`interval?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SellerMessagesResult` | `src/commands/seller-messages.ts` | `conversation: string;`<br>`total: number;`<br>`messages: Message[];` |
+| `SimilarArgs` | `src/commands/similar.ts` | `offerId: string;`<br>`max: number;`<br>`headed?: boolean;` |
+| `SimilarOpts` | `src/commands/similar.ts` | `offerId: string;`<br>`max?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SimilarResult` | `src/commands/similar.ts` | `offerId: string;`<br>`total: number;`<br>`offers: Offer[];` |
+| `OfferDetailSummary` | `src/commands/sourcing-utils.ts` | `offerId: string;`<br>`title: string;`<br>`url: string;`<br>`priceMin: number \| null;`<br>`priceMax: number \| null;`<br>`unitName: string \| null;`<br>`minOrderQty: number \| null;`<br>`mixOrderQty: number \| null;`<br>`priceTiers: PriceTier[];`<br>`saledCount: number \| null;`<br>`categoryId: string \| null;`<br>`supplier: OfferResult['supplier'];`<br>`skuCount: number;`<br>`totalStock: number \| null;` |
+| `SupplierInspectArgs` | `src/commands/supplier-inspect.ts` | `target: string;`<br>`headed?: boolean;` |
+| `SupplierInspectOpts` | `src/commands/supplier-inspect.ts` | `target: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SupplierInspectResult` | `src/commands/supplier-inspect.ts` | `target: SupplierTarget;`<br>`supplier: {`<br>`name: string \| null;`<br>`loginId: string \| null;`<br>`memberId: string \| null;`<br>`userId: string \| null;`<br>`companyId: string \| null;`<br>`shopUrl: string \| null;`<br>`shopUrls: Record<string, string>;`<br>`identity: string \| null;`<br>`signs: Record<string, boolean>;`<br>`factory: {`<br>`isFactory: boolean;`<br>`superFactory: boolean;` |
+| `SupplierResearchOpts` | `src/commands/supplier-search.ts` | - |
+| `SupplierSearchArgs` | `src/commands/supplier-search.ts` | `keywords: string[];`<br>`maxPerQuery: number;`<br>`enrichTop?: number;`<br>`filters?: SupplierFilters;`<br>`headed?: boolean;` |
+| `SupplierSearchOpts` | `src/commands/supplier-search.ts` | `keywords: string[];`<br>`max?: string;`<br>`enrich?: string;`<br>`factoryOnly?: boolean;`<br>`province?: string;`<br>`city?: string;`<br>`minYears?: string;`<br>`minRepeatRate?: string;`<br>`minResponseRate?: string;`<br>`jsonl?: boolean;`<br>`csv?: boolean;`<br>`output?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SupplierSearchResult` | `src/commands/supplier-search.ts` | `queries: string[];`<br>`source: {`<br>`kind: 'company-search';`<br>`endpoint: 'companySearchBusinessService';`<br>`offerAggregation: false;`<br>`filters: SupplierFilters;`<br>`maxPerQuery: number;`<br>`enrichTop: number;`<br>`totalBeforeFilter: number;`<br>`total: number;`<br>`enrichedCount: number;`<br>`items: SupplierSearchItem[];` |
+| `WhoamiArgs` | `src/commands/whoami.ts` | `verify?: boolean;` |
+| `WhoamiOpts` | `src/commands/whoami.ts` | `verify?: boolean;`<br>`profile?: string;` |
+| `WhoamiResult` | `src/commands/whoami.ts` | `loggedIn: boolean;`<br>`memberId?: string;`<br>`nick?: string \| null;`<br>`lastVerifiedAt?: string \| null;` |
+| `FakeShippedOpts` | `src/commands/workflows.ts` | `days?: string;`<br>`limit?: string;`<br>`maxPages?: string;`<br>`maxCheck?: string;`<br>`debug?: boolean;` |
+| `SellerHistoryOpts` | `src/commands/workflows.ts` | `seller: string;`<br>`maxPages?: string;` |
+| `ShippedOpts` | `src/commands/workflows.ts` | `orderId: string;` |
+| `StuckOpts` | `src/commands/workflows.ts` | `days?: string;`<br>`limit?: string;` |
+| `SessionOpts` | `src/session/context.ts` | `headless: boolean;`<br>`profile?: string;` |
+| `DispatchOpts` | `src/session/dispatch.ts` | `headed?: boolean;`<br>`profile?: string;`<br>`noDaemon?: boolean;` |
+| `DecodedMessage` | `src/session/im-cards.ts` | `kind: MessageKind;`<br>`preview: string;`<br>`/** Set when `kind === 'card'`. Semantic name when known, `'unknown'` otherwise. */`<br>`cardTemplate?: CardTemplate;`<br>`/** Raw 6-digit template code (`170002`, `467001`, …). Always present for cards. */`<br>`cardCode?: string;`<br>`/** Populated only when at least one field resolved — keep JSON output compact. */`<br>`extras?: MessageExtras;` |
+| `MessageExtras` | `src/session/im-cards.ts` | `/** Trade order id parsed from card link, if any. */`<br>`orderId?: string;`<br>`/** Offer (product) id parsed from card link, if any. */`<br>`offerId?: string;`<br>`/** Refund / 退货 id, if any. */`<br>`refundId?: string;`<br>`/** Product / order thumbnail URL. */`<br>`imgUrl?: string;`<br>`/** Clickthrough URL embedded in the card. */`<br>`linkUrl?: string;`<br>`/** Display string such as "订单金额：￥4.90" or "¥0.04". */`<br>`amount?: string;` |
+| `RawImMessage` | `src/session/im-cards.ts` | `content?: {`<br>`contentType?: number;`<br>`text?: { content?: string };`<br>`custom?: {`<br>`summary?: string;`<br>`data?: string;`<br>`title?: string;`<br>`extension?: {`<br>`biMsgType?: string;`<br>`dynamic_msg_content?: string;` |
+| `StableLocatorResult` | `src/session/locator.ts` | `strategy: string;`<br>`description: string;` |
+| `ResponseCaptureActionResult` | `src/session/response-capture.ts` | `actionResult: TResult;`<br>`response: T \| null;`<br>`diagnostics: ResponseCaptureDiagnostics;` |
+| `ResponseCaptureEmptyResult` | `src/session/response-capture.ts` | `at: string;`<br>`url: string;` |
+| `SearchOfferCaptureDiagnostics` | `src/session/search-capture.ts` | `startedAt: string;`<br>`endedAt?: string;`<br>`disposed: boolean;`<br>`finalStatus?: SearchOfferCaptureWaitStatus;`<br>`timedOut: boolean;`<br>`seenCount: number;`<br>`matchedCount: number;`<br>`parsedCount: number;`<br>`failureCount: number;`<br>`lastSeenUrl?: string;`<br>`lastMatchedUrl?: string;`<br>`lastParsedUrl?: string;`<br>`lastError?: { name?: string; message: string };`<br>`failures: SearchOfferCaptureFailure[];` |
+| `SearchOfferCaptureFailure` | `src/session/search-capture.ts` | `at: string;`<br>`url: string;`<br>`name?: string;`<br>`message: string;` |
+| `SearchOfferCaptureOptions` | `src/session/search-capture.ts` | `page: Page;`<br>`requireMethod?: string;`<br>`targetPage?: () => number;`<br>`keep?: 'first' \| 'largest';` |
+| `SearchOfferCaptureResult` | `src/session/search-capture.ts` | `actionResult: TResult;`<br>`status: SearchOfferCaptureWaitStatus;`<br>`offers: Offer[];`<br>`diagnostics: SearchOfferCaptureDiagnostics;` |
+| `SearchOfferCaptureWaitOptions` | `src/session/search-capture.ts` | `timeoutMs: number;`<br>`intervalMs?: number;`<br>`isBlocked?: () => boolean \| Promise<boolean>;`<br>`isClosed?: () => boolean;` |
+| `SearchOfferCaptureWaitResult` | `src/session/search-capture.ts` | `status: SearchOfferCaptureWaitStatus;`<br>`offers: Offer[];`<br>`diagnostics: SearchOfferCaptureDiagnostics;` |
+| `Offer` | `src/session/search-mtop.ts` | `offerId: string;`<br>`title: string;`<br>`price: { text: string; min: number \| null; max: number \| null };`<br>`supplier: {`<br>`name: string \| null;`<br>`shopUrl: string \| null;`<br>`years: number \| null;`<br>`location: { province: string \| null; city: string \| null };`<br>`bizType: string \| null;`<br>`verified: { factory: boolean; business: boolean; superFactory: boolean };`<br>`tags: string[];`<br>`serviceTags?: string[];`<br>`productBadges?: string[];`<br>`demand?: {` |
+| `RawOfferItem` | `src/session/search-mtop.ts` | `cellType?: string;`<br>`data?: {`<br>`offerId?: string;`<br>`title?: string;`<br>`priceInfo?: { price?: string };`<br>`offerPicUrl?: string;`<br>`loginId?: string;`<br>`memberId?: string;`<br>`province?: string;`<br>`city?: string;`<br>`bookedCount?: string;`<br>`repurchaseRate?: string;`<br>`repurchaseRateText?: string;`<br>`orderCount?: string \| number;` |
+| `SupplierOfferPreview` | `src/session/supplier-search.ts` | `offerId: string \| null;`<br>`title: string;`<br>`url: string \| null;`<br>`price: { text: string \| null; value: number \| null };`<br>`unit: string \| null;`<br>`image: string \| null;`<br>`bookedCount: number \| null;`<br>`saleQuantity: number \| null;`<br>`quantitySumMonth: number \| null;`<br>`brief: string \| null;` |
+| `SupplierSearchCaptureWaitResult` | `src/session/supplier-search.ts` | `status: SupplierSearchCaptureWaitStatus;`<br>`data: SupplierSearchServiceData \| null;`<br>`diagnostics: SupplierSearchCaptureDiagnostics;` |

package/docs/generated/module-map.md

@@ -0,0 +1,13 @@
+# Module Map
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Directory | Source Files | Related Tests | Notes |
+|---|---:|---:|---|
+| `src` | 1 | 0 | - |
+| `src/auth` | 2 | 1 | login/session/cookie helpers |
+| `src/commands` | 29 | 5 | command executors and renderers |
+| `src/daemon` | 5 | 0 | background daemon client/server/protocol |
+| `src/io` | 3 | 10 | output, prompts, and errors |
+| `src/session` | 27 | 11 | browser/session automation helpers |
+| `src/util` | 3 | 0 | shared utilities |

package/docs/generated/test-index.md

@@ -0,0 +1,34 @@
+# Test Index
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Test File | Focus | Risk Notes |
+|---|---|---|
+| `tests/artifacts.test.ts` | artifacts | live/session-sensitive, browser/page-state, fixture/parser |
+| `tests/config.test.ts` | config | live/session-sensitive, fixture/parser |
+| `tests/cookies.test.ts` | cookies | live/session-sensitive, browser/page-state |
+| `tests/debug.test.ts` | debug | live/session-sensitive |
+| `tests/doctor-live.test.ts` | doctor-live | live/session-sensitive |
+| `tests/doctor.test.ts` | doctor | live/session-sensitive |
+| `tests/events.test.ts` | events | live/session-sensitive, browser/page-state |
+| `tests/fix-bin-mode.test.ts` | fix-bin-mode | - |
+| `tests/im-cards.test.ts` | im-cards | live/session-sensitive, fixture/parser |
+| `tests/inbox.test.ts` | inbox | live/session-sensitive |
+| `tests/locator.test.ts` | locator | browser/page-state |
+| `tests/mtop.test.ts` | mtop | fixture/parser |
+| `tests/navigation-guard.test.ts` | navigation-guard | live/session-sensitive |
+| `tests/output.test.ts` | output | - |
+| `tests/page-state.test.ts` | page-state | live/session-sensitive, browser/page-state |
+| `tests/paths.test.ts` | paths | - |
+| `tests/profile.test.ts` | profile | live/session-sensitive |
+| `tests/recovery.test.ts` | recovery | browser/page-state |
+| `tests/replay-fixtures.test.ts` | replay-fixtures | browser/page-state, fixture/parser |
+| `tests/response-capture.test.ts` | response-capture | browser/page-state, fixture/parser |
+| `tests/search-capture.test.ts` | search-capture | browser/page-state, fixture/parser |
+| `tests/search-mtop.test.ts` | search-mtop | browser/page-state, fixture/parser |
+| `tests/search-options.test.ts` | search-options | - |
+| `tests/sourcing-utils.test.ts` | sourcing-utils | fixture/parser |
+| `tests/state.test.ts` | state | live/session-sensitive |
+| `tests/supplier-inspect.test.ts` | supplier-inspect | browser/page-state, fixture/parser |
+| `tests/supplier-search.test.ts` | supplier-search | browser/page-state, fixture/parser |
+| `tests/wait.test.ts` | wait | - |

package/docs/playbooks/add-command.md

@@ -0,0 +1,15 @@
+# Playbook: Add A Command
+
+1. Add the Commander surface in `src/cli.ts`.
+2. Create or update the owning module in `src/commands`.
+3. Keep CLI parsing in `run(opts)` and browser/session work in
+   `execute(ctx, args)` when daemon dispatch is needed.
+4. Wire daemon dispatch in `src/session/dispatch.ts` if the command should run
+   through the daemon.
+5. Use `emit({ human, data })` so JSON/text dual mode stays consistent.
+6. Add deterministic tests for parsing, output, mtop payload parsing, or helper
+   behavior.
+7. Update `docs/COMMANDS.md` and `docs/JSON_CONTRACTS.md` when behavior or
+   output shape changes.
+8. Run `pnpm agent-context` and the focused verification command.
+

package/docs/playbooks/add-mtop-capture.md

@@ -0,0 +1,13 @@
+# Playbook: Add Mtop Capture
+
+1. Probe the browser flow manually only when needed and safe.
+2. Capture the smallest stable endpoint/method/appId signal.
+3. Add parsing logic under `src/session` when it is shared, or in the command
+   module when it is command-specific.
+4. Save representative payloads as tests fixtures when they do not contain
+   sensitive account data.
+5. Return structured `CliError` failures for timeout, login redirect,
+   risk-control, and parse failure.
+6. Update `docs/JSON_CONTRACTS.md` if the capture changes agent-facing output.
+7. Run focused parser/capture tests, then `pnpm agent-context`.
+

package/docs/playbooks/change-json-output.md

@@ -0,0 +1,11 @@
+# Playbook: Change JSON Output
+
+1. Identify the stable result interface in `src/commands/*`.
+2. Prefer additive fields. Do not rename or remove fields unless the user
+   approved a breaking change.
+3. Update human rendering only after preserving machine output.
+4. Add or update tests for the JSON shape or parser feeding it.
+5. Update `docs/JSON_CONTRACTS.md`.
+6. Run `pnpm agent-context`.
+7. Run `pnpm test` or a focused test plus `pnpm docs-check`.
+

package/docs/playbooks/debug-risk-control.md

@@ -0,0 +1,12 @@
+# Playbook: Debug Risk Control
+
+1. Confirm whether the failure is login redirect, risk-control URL, empty mtop
+   capture, network error, or browser closure.
+2. Check structured exit code behavior. Exit `3` should point to `1688 login`;
+   exit `4` should point to rerunning once with `--headed`.
+3. Use `--headed` only when manual slider solving is expected.
+4. Inspect `src/session/page-state.ts`, `src/session/recovery.ts`, and the
+   relevant command's capture logic.
+5. Add fixture-backed tests for page-state or parser changes.
+6. Do not add silent retry loops around risk-control failures.
+

package/docs/playbooks/update-cli-release.md

@@ -0,0 +1,11 @@
+# Playbook: Update CLI Release Behavior
+
+1. Check `package.json`, `CHANGELOG.md`, `README.md`, and update-notifier
+   behavior in `src/cli.ts`.
+2. Preserve the update protocol in `docs/SAFETY.md`: never run a global install
+   command without explicit current-turn user approval.
+3. If daemon behavior changes after upgrade, document whether
+   `1688 daemon reload` is required.
+4. Run `pnpm build`, `pnpm test`, and `pnpm agent-context`.
+5. Update docs when install, postinstall, or release packaging behavior changes.
+

package/docs/specs/checkout-and-orders.md

@@ -0,0 +1,30 @@
+# Checkout And Orders
+
+Checkout and order tracking commands operate real buyer state.
+
+## Commands
+
+```bash
+1688 checkout prepare <cartIds...>
+1688 checkout confirm <cartIds...>
+1688 order list [--status <status>]
+1688 order get <orderId>
+1688 order logistics <orderId>
+1688 shipped <orderId>
+1688 stuck [--days N]
+1688 fake-shipped [--days N]
+1688 seller-history <sellerName>
+```
+
+## Checkout Boundary
+
+`checkout prepare` is read-only. `checkout confirm` places a real order and
+must follow the protocol in `docs/SAFETY.md`.
+
+## Agent Requirements
+
+- Preserve order IDs, seller identity, totals, line items, services, badges,
+  actions, and logistics trace fields.
+- Keep overdue/fake-shipped workflows explainable: include thresholds and the
+  evidence used to flag each order.
+- Never hide partial scans; report scan limits and blockers.

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`