企业官网建设流程全解析

OpenCLI 1688 适配器实战指南：用已登录浏览器把 1688.com 变成可编程 CLI

【免费下载链接】OpenCLIMake Any Website into CLI & Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI

1688 是国内重要的 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 与各命令文件。
• 数据来源严格限定为公开页面可见内容：不发送询盘、不下单、不访问卖家后台，只提取商品页、搜索页、店铺页渲染出来的字段与素材。

五个子命令速查

环境准备：前置条件与登录态校验

运行任何 1688 命令前需要满足：

• Chrome 正在运行且已登录1688.com（浏览器命令复用你的 Chrome 登录会话，见 docs/guide/browser-bridge.md）；
• 已安装 Browser Bridge 扩展（可在仓库根目录extension/下以"加载已解压的扩展程序"方式载入，或用opencli doctor验证扩展与守护进程连通性）。

登录态校验并非只靠肉眼判断。在 auth.js 中，verify1688Identity会依次检查三个关键 Cookie：__cn_logon__=true表示已登录，unb作为用户 ID，lid解码后作为昵称；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

参数与约束

结果结构化与去重

normalizeSearchCandidate（search.js）把页面候选归一化为结构化行，关键点：

• 标识符提取：从规范化后的商品 URL 提取offer_id，从卖家 URL 提取member_id与shop_id（shop_id即店铺子域名，如yinuoweierfushi）；三者是后续流程推荐使用的稳定标识。
• 价格解析：parsePriceText支持¥、$、€及"元"，返回price_text、price_min、price_max、currency（含¥/元判定为 CNY）；normalizeInlineText会修正¥ 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 json

buildDetailUrl会从输入中提取 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, title, price_text, moq_text, seller_name, origin_place。normalizeItemPayload的完整映射在 item.test.js 中有覆盖度很高的断言（价格阶梯、产地、发货时效、贴牌文案、可见属性等）。

提取媒体素材：assets 子命令

# 列出可下载的媒体素材 opencli 1688 assets 841141931191 -f json

assets是全适配器技术含量最高的子命令，其实现（assets.js）揭示了 1688 商品页的三个现实：

1. 详情区在自定义元素v-detail-e的 shadow DOM 内懒渲染，普通 CSS 选择器无法穿透shadowRoot。脚本用queryAllDeep递归遍历所有 shadow root，并沿 host 链（inDetailContainer）判断元素是否归属详情容器（.de-description-detail、#detailContentContainer、.html-description、.desc-lazyload-container）。
2. 懒加载需要触发渲染：readAssetsPayload会先page.autoScroll({ times: 6, delayMs: 500 })滚动到底部，再把详情容器scrollIntoView，随后用waitForDetailImages轮询（最多 10 次、间隔 0.5s）直到详情图片计数连续两次稳定，避免固定等待浪费耗时。
3. 图片来源多样：主图（#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 ./media

download内部复用extractAssetsForInput拿到素材清单，再由toDownloadItems（download.js）按类型与分组生成文件名：图片为{offerId}_{main|sku|detail|other}_{序号两位补零}{扩展名}，视频为{offerId}_video_{序号}{.mp4}；扩展名由 URL path 推断，缺省图片.jpg、视频.mp4。下载时把浏览器 Cookie 通过formatCookieHeader与browserCookies一并传入downloadMedia（@jackwener/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 json

resolveStoreUrl（shared.js）支持三种输入形态：member id（b2b-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）实际是"三页聚合"：

1. 读取店铺主页bodyText与页内offerLinks、contactLinks；
2. 跳转.../page/contactinfo.html联系方式页，提取地址、电话、手机；
3. 若拿到任一 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_TARGET=detail.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