
OpenCLI 1688 适配器实战指南用已登录浏览器把 1688.com 变成可编程 CLI【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI1688 是国内重要的 B2B 货源平台而 OpenCLI 的1688浏览器适配器让你可以直接复用 Chrome 中已登录的 1688 会话把商品搜索、详情读取、图文素材提取与批量下载、供应商店铺信息采集全部封装成一行命令供 AI Agent 与脚本调用。读完本文你将掌握search / item / assets / download / store五个子命令的完整用法、输出字段含义、底层实现原理与常见故障的排查方法。适配器概览定位与边界1688 适配器属于 OpenCLI 的 Browser浏览器模式域名限定为1688.com。它不是一个独立的爬虫服务而是借用你本机 Chrome 的登录态来完成数据读取的只读适配器。其核心设计原则体现在源码中所有子命令都通过cli()注册声明strategy: Strategy.COOKIE并依赖 Browser Bridge 扩展安装指南 建立的浏览器桥接通道见 auth.js 与各命令文件。数据来源严格限定为公开页面可见内容不发送询盘、不下单、不访问卖家后台只提取商品页、搜索页、店铺页渲染出来的字段与素材。五个子命令速查命令说明opencli 1688 search query --limit n搜索公开商品候选返回价格、起批 MOQ、卖家链接与可见徽章opencli 1688 item url-or-offer-id读取公开商品详情页价格阶梯、MOQ、发货文案与卖家基础信息opencli 1688 assets url-or-offer-id提取商品页可见的媒体素材主图、SKU 图、详情图、视频opencli 1688 download url-or-offer-id批量下载商品页可见的媒体素材opencli 1688 store url-or-member-id读取公开供应商/店铺页公司信息、入驻年限、类目与可见服务信号环境准备前置条件与登录态校验运行任何 1688 命令前需要满足Chrome 正在运行且已登录1688.com浏览器命令复用你的 Chrome 登录会话见 docs/guide/browser-bridge.md已安装 Browser Bridge 扩展可在仓库根目录extension/下以加载已解压的扩展程序方式载入或用opencli doctor验证扩展与守护进程连通性。登录态校验并非只靠肉眼判断。在 auth.js 中verify1688Identity会依次检查三个关键 Cookie__cn_logon__true表示已登录unb作为用户 IDlid解码后作为昵称registerSiteAuthCommands还提供了 1688 专属的 auth 命令loginUrl指向https://login.1688.com/member/signin.htm。同时shared.js 中的isCaptchaState/isLoginState会扫描页面标题与正文识别滑块验证页/_____tmd_____/punish标记、请拖动下方滑块完成验证等文案和登录页passport、login.taobao.com等 URL 与请先登录等文案一旦命中即抛出AuthRequiredError提示先到共享 Chrome 完成登录/验证再重试。搜索商品search 子命令深入解析基本用法# 搜索商品 opencli 1688 search 桌面置物架 宿舍 收纳 --limit 10 # JSON 输出 opencli 1688 search 桌面置物架 宿舍 收纳 --limit 10 -f json参数与约束参数说明query位置参数必填搜索关键词非空校验见buildSearchUrlURL 编码后拼接到https://s.1688.com/selloffer/offer_search.htm?charsetutf8keywords--limit整数可选结果数量上限默认 20上限 100常量SEARCH_LIMIT_DEFAULT/SEARCH_LIMIT_MAX非法值抛ArgumentError结果结构化与去重normalizeSearchCandidatesearch.js把页面候选归一化为结构化行关键点标识符提取从规范化后的商品 URL 提取offer_id从卖家 URL 提取member_id与shop_idshop_id即店铺子域名如yinuoweierfushi三者是后续流程推荐使用的稳定标识。价格解析parsePriceText支持¥、$、€及元返回price_text、price_min、price_max、currency含¥/元判定为 CNYnormalizeInlineText会修正¥ 56 .00、¥ 56.00这类排版噪音。MOQ 解析extractMoqText支持N件/个/套/箱/包/双/台/把/只 起批、≥N、N~M 起批三种形态同时输出moq_text原文与moq_value数值。徽章识别extractBadges从容器文本中匹配工厂徽章源头工厂、深度验厂、实力工厂、工厂档案、加工专区、验厂报告、厂家直销、生产厂家、工厂直供与服务徽章延期必赔、品质保障、破损包赔、退货包运费、晚发必赔、7*24小时响应、48小时发货、72小时发货、后天达、包邮、闪电拿样两组模式常量定义在 shared.js。销量与回头率extractSalesText识别已售/销量/售 300套等文本extractReturnRateText提取回头率52%。去重策略buildDedupeKey按offer_id优先、item_url兜底生成键collectSearchRows会沿搜索结果页下一页链接翻页采集最多 12 页MAX_SEARCH_PAGES跨页去重后截断到limit。对应行为有 search.test.js 的单元测试佐证含移动端detail.m.1688.com/page/index.html?offerId链接的 offer id 提取用例。默认输出列rank, offer_id, title, item_url, price_text, moq_text, seller_name, member_id, location可用-f json拿到完整字段含shop_id、seller_url、badges、sales_text、return_rate_text、source_url、fetched_at、strategy。读取商品详情item 子命令基本用法# 按 offer id 读取 opencli 1688 item 841141931191 -f json # 按 URL 读取 opencli 1688 item https://detail.1688.com/offer/841141931191.html -f jsonbuildDetailUrl会从输入中提取 offer id支持纯数字、/offer/{id}.html、?offerId三种形态并规范化为https://detail.1688.com/offer/{id}.html无法解析时抛出带示例提示的ArgumentError。页面数据来源readItemPayload通过page.evaluate读取window.context.result.global.globalData.model中的offerTitleModel、tradeModel、sellerModel以及window.context.result.data.gallery.fields与shippingServices.fields同时抓取页面innerText作为兜底。若解析不出offerId会报错1688 item page did not expose product context——这正是文档 Troubleshooting 第一条对应的问题。输出字段normalizeItemPayload字段说明offer_id/member_id/shop_id三个稳定标识符title优先取offerTitle其次去 - 阿里巴巴后缀再回退正文首行item_url规范化的详情页 URLbuildDetailUrlmain_images主图列表gallery.mainImage/offerImgList/wlImageInfos合并去重price_text/price_tiers/currency价格展示文本、价格阶梯normalizePriceTiers把currentPrices的beginAmountprice转成quantity_text/quantity_min/price_text/price、币种 CNYmoq_text/moq_value起批数量优先匹配N件 起批回退trade.beginAmount unitseller_name/seller_url/shop_name卖家信息winportUrl优先memberId兜底origin_place产地extractLocation依据 34 个省市自治区前缀与正则从正文定位delivery_days_text发货时效优先shipping.deliveryLimitText/logisticsText其次N小时/天内发货正文再次服务项中的agreeDeliveryHourscustomization_text/private_label_text定制来样定制/来图定制/可定制…与贴牌贴牌/贴标/定制logo/OEM/ODM…相关行visible_attributes可见属性键值对过滤sellPointModelsales_text/stock_quantity销量文本全网销量/已售与库存数量service_badges服务徽章含protectionInfos与buyerProtectionModel合并去重默认输出列offer_id, title, price_text, moq_text, seller_name, origin_place。normalizeItemPayload的完整映射在 item.test.js 中有覆盖度很高的断言价格阶梯、产地、发货时效、贴牌文案、可见属性等。提取媒体素材assets 子命令# 列出可下载的媒体素材 opencli 1688 assets 841141931191 -f jsonassets是全适配器技术含量最高的子命令其实现assets.js揭示了 1688 商品页的三个现实详情区在自定义元素v-detail-e的 shadow DOM 内懒渲染普通 CSS 选择器无法穿透shadowRoot。脚本用queryAllDeep递归遍历所有 shadow root并沿 host 链inDetailContainer判断元素是否归属详情容器.de-description-detail、#detailContentContainer、.html-description、.desc-lazyload-container。懒加载需要触发渲染readAssetsPayload会先page.autoScroll({ times: 6, delayMs: 500 })滚动到底部再把详情容器scrollIntoView随后用waitForDetailImages轮询最多 10 次、间隔 0.5s直到详情图片计数连续两次稳定避免固定等待浪费耗时。图片来源多样主图#dt-tab img等选择器、SKU 图背景图backgroundImage取 computed style、视频video[src]、video source[src]及脚本内联的.mp4/.m3u8URL 正则加上window.context页面状态中的gallery数据作为种子。输出结构为main_images/sku_images/detail_images/videos/other_images/raw_assets并附main_count、sku_count、detail_count、video_count计数。默认输出列offer_id, title, main_count, sku_count, detail_count, video_count。文档的 Notes 提醒assets/download以页面状态与渲染后的 DOM 为准可能与 1688 官方扩展工作流暴露的每一个文件并非完全一致。批量下载download 子命令# 批量下载页面可见的图片/视频 opencli 1688 download 841141931191 --output ./1688-downloads# 自定义输出目录 opencli 1688 download https://detail.1688.com/offer/841141931191.html --output ./mediadownload内部复用extractAssetsForInput拿到素材清单再由toDownloadItemsdownload.js按类型与分组生成文件名图片为{offerId}_{main|sku|detail|other}_{序号两位补零}{扩展名}视频为{offerId}_video_{序号}{.mp4}扩展名由 URL path 推断缺省图片.jpg、视频.mp4。下载时把浏览器 Cookie 通过formatCookieHeader与browserCookies一并传入downloadMediajackwener/opencli/download/media-download输出目录默认为./1688-downloads且会按offerId建子目录单文件超时 60 秒。默认输出列index, type, status, size。读取供应商店铺store 子命令基本用法# 按店铺 URL 读取 opencli 1688 store https://shop52908bfw19166.1688.com/ -f json # 按 member id 读取 opencli 1688 store b2b-22154705262941f196 -f jsonresolveStoreUrlshared.js支持三种输入形态member idb2b-xxx、完整店铺 URL、纯子域名统一解析后优先转成移动版店铺页https://winport.m.1688.com/page/index.html?memberId非 member id 的 URL 则规范化为主机名过滤www/detail/s/winport/work/air/dj等通用主机并剥离spm、tracelog、utm_*等跟踪参数——canonicalizeItemUrl/canonicalizeSellerUrl也遵循同样的 URL 净化逻辑。数据拼装流程store命令store.js实际是三页聚合读取店铺主页bodyText与页内offerLinks、contactLinks跳转.../page/contactinfo.html联系方式页提取地址、电话、手机若拿到任一 offer id则访问对应商品详情页从sellerModel取得companyName、memberId、winportUrl作为种子readItemSeed失败仅记录、不中断。最终输出member_id、shop_id、store_name/company_name、store_url、company_url、business_model_text经营模式/生产加工/主营产品、years_on_platform_text入驻N年、location、staff_size_text员工人数/员工总数、factory_badges、service_badges、response_rate_text响应率/回复率/响应速度、return_rate_text回头率、top_categories主营拆词、phone_text/mobile_text。默认输出列store_name, years_on_platform_text, location, return_rate_text。若三页均无可提取内容抛出EmptyResultError提示先在 Chrome 打开店铺页重试。常见问题排查item报did not expose product context先确认当前打开的确实是detail.1688.com商品页该命令对活动浏览器目标比search/store更敏感。浏览器目标过宽导致导航错乱用OPENCLI_CDP_TARGETdetail.1688.com或更具体的 1688 主机重试把 CDP 目标精确到 1688 站点/商品 tab。遇到滑块或验证页回到 Chrome 手动刷新真实页面并完成滑块验证后重试shared.js内置的验证/登录文案识别与buildCaptchaHint提示均围绕此场景设计。目标被导航或关闭gotoAndReadState会捕获Inspected target navigated or closed等错误并提示打开一个新的 1688 tab 重新指定OPENCLI_CDP_TARGET。使用建议与设计要点优先使用稳定标识后续工作流尽量使用offer_id、member_id、shop_id避免 URL 中的spm、tracelog等跟踪参数干扰去重与缓存这些参数会被stripTrackingParams剥离。只读边界适配器只返回/下载公开页面可见的字段与媒体不发送询盘、不下单、不接触卖家后台数据适合货源调研、比价、素材归档、供应商尽调等场景。源码参考命令实现见 clis/1688/search.js、item.js、assets.js、download.js、store.js公共解析与 URL 规范化集中在 clis/1688/shared.js登录态校验在 clis/1688/auth.js各命令均有对应的*.test.js单元测试如 search.test.js、item.test.js、assets.test.js可作为字段语义的权威参考。【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考