{"_id":"1688-claw","_rev":"2-ecccc88ceff6cece682c837be418ce7c","name":"1688-claw","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"1688-claw","version":"0.1.0","license":"MIT","_id":"1688-claw@0.1.0","maintainers":[{"name":"yifan4243","email":"yifan4243@gmail.com"}],"bin":{"1688-claw":"dist/cli.js"},"dist":{"shasum":"59527a59eeb0254b205565405fdb8c89fb19ce35","tarball":"https://registry.npmjs.org/1688-claw/-/1688-claw-0.1.0.tgz","fileCount":6,"integrity":"sha512-ed6Ch4JKUeST3yFk7cw1+eV09ytbqCNp7ansn+QnNsrCpUu+lj6caUg5SSHb2PhOJAaHkQ0N6KziMJRM6BIF+Q==","signatures":[{"sig":"MEYCIQCTCUxEpGLaWh/KpxHjTDFRxMFNCPimUNrg4G+t1mLTFQIhAPQ+8IcHZr93Fs35ybyFUICkjdlxL88Xh5qlrtXB+Y+1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":506473},"type":"module","_from":"file:1688-claw-0.1.0.tgz","engines":{"node":">=20"},"scripts":{"1688":"node dist/cli.js","dev":"pnpm --filter @standalone-1688/cli dev","build":"pnpm -r build && node scripts/build.mjs","typecheck":"pnpm -r typecheck","postinstall":"node scripts/postinstall.mjs"},"_npmUser":{"name":"yifan4243","email":"yifan4243@gmail.com"},"_resolved":"C:\\Users\\ADMINI~1\\AppData\\Local\\Temp\\47057abcedc14d3ad712e14f2aef5890\\1688-claw-0.1.0.tgz","_integrity":"sha512-ed6Ch4JKUeST3yFk7cw1+eV09ytbqCNp7ansn+QnNsrCpUu+lj6caUg5SSHb2PhOJAaHkQ0N6KziMJRM6BIF+Q==","_npmVersion":"11.12.1","description":"Standalone read-only 1688 product collection CLI for keyword, image, offer, and official similar searches.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"qrcode":"^1.5.4","commander":"^12.1.0","iconv-lite":"^0.7.2","playwright":"^1.48.0","proper-lockfile":"^4.1.2","playwright-extra":"^4.3.6","puppeteer-extra-plugin-stealth":"^2.11.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.28.1","typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/1688-claw_0.1.0_1784122796633_0.5775324456135442","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"1688-claw","version":"0.1.1","description":"Standalone read-only 1688 product collection CLI for keyword, image, offer, and official similar searches.","license":"MIT","bin":{"1688-claw":"dist/cli.js"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"type":"module","dependencies":{"commander":"^12.1.0","iconv-lite":"^0.7.2","playwright":"^1.48.0","playwright-extra":"^4.3.6","proper-lockfile":"^4.1.2","puppeteer-extra-plugin-stealth":"^2.11.2","qrcode":"^1.5.4"},"devDependencies":{"esbuild":"^0.28.1","typescript":"^5.6.0"},"scripts":{"1688":"node dist/cli.js","build":"pnpm -r build && node scripts/build.mjs","dev":"pnpm --filter @standalone-1688/cli dev","typecheck":"pnpm -r typecheck","postinstall":"node scripts/postinstall.mjs"},"_id":"1688-claw@0.1.1","_integrity":"sha512-9aZRMIxt2pFyZwsH2NnzFFZOvApt7CIgSUH3066PQG5bhJB1p9ARXJ4qY3NsyIiocEDamedZfBCA10rvqTxj1A==","_resolved":"C:\\Users\\ADMINI~1\\AppData\\Local\\Temp\\ddab2ea54c26f87f989e86f29c3b3d28\\1688-claw-0.1.1.tgz","_from":"file:1688-claw-0.1.1.tgz","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-9aZRMIxt2pFyZwsH2NnzFFZOvApt7CIgSUH3066PQG5bhJB1p9ARXJ4qY3NsyIiocEDamedZfBCA10rvqTxj1A==","shasum":"0a5224bdc421274b54b893b96507ea1c0d4d4cf1","tarball":"https://registry.npmjs.org/1688-claw/-/1688-claw-0.1.1.tgz","fileCount":7,"unpackedSize":700690,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCaapiSHyIW3D0ShHGURi5E0DoRAwv0uN5Vbzg6XdfNhwIgK2HNzKW81N0YIJcxlEfyrl8DU4ccyp3uJGPEAidqzcA="}]},"_npmUser":{"name":"yifan4243","email":"yifan4243@gmail.com"},"directories":{},"maintainers":[{"name":"yifan4243","email":"yifan4243@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/1688-claw_0.1.1_1784124948698_0.8288805496507154"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-15T13:39:56.548Z","modified":"2026-07-15T14:15:48.997Z","0.1.0":"2026-07-15T13:39:56.778Z","0.1.1":"2026-07-15T14:15:48.893Z"},"license":"MIT","description":"Standalone read-only 1688 product collection CLI for keyword, image, offer, and official similar searches.","maintainers":[{"name":"yifan4243","email":"yifan4243@gmail.com"}],"readme":"# 1688 Claw\n\n<p>\n  <a href=\"https://www.npmjs.com/package/1688-claw\"><img src=\"https://img.shields.io/npm/v/1688-claw?style=flat-square\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/1688-claw\"><img src=\"https://img.shields.io/npm/dm/1688-claw?style=flat-square\" alt=\"npm downloads\"></a>\n  <img src=\"https://img.shields.io/npm/l/1688-claw?style=flat-square\" alt=\"MIT license\">\n  <img src=\"https://img.shields.io/badge/运行时-Node.js%2020%2B-339933?style=flat-square&logo=node.js&logoColor=white\" alt=\"Node.js 20+\">\n  <img src=\"https://img.shields.io/badge/语言-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white\" alt=\"TypeScript\">\n  <img src=\"https://img.shields.io/badge/包管理器-pnpm-F69220?style=flat-square&logo=pnpm&logoColor=white\" alt=\"pnpm\">\n  <img src=\"https://img.shields.io/badge/浏览器-Playwright-2EAD33?style=flat-square&logo=playwright&logoColor=white\" alt=\"Playwright\">\n  <img src=\"https://img.shields.io/badge/采集范围-1688%20只读采集-1677FF?style=flat-square\" alt=\"1688 only\">\n  <img src=\"https://img.shields.io/badge/命令-关键词%20%7C%20图片%20%7C%20详情%20%7C%20相似款-0A7BDE?style=flat-square\" alt=\"Commands\">\n</p>\n\n一个只负责 **1688 商品采集** 的独立命令行工具。它将关键词搜索、图片搜索、指定商品详情深采和官方相似商品入口统一为可供程序或 Agent 调用的命令。\n\n> 只采集，不采购。本项目不包含购物车、下单、支付、供应商聊天、自动采购、后台守护或绕过验证码的功能。\n\n---\n\n## 开源与交流\n\n本仓库完全开源，欢迎自由使用、学习、二次开发和提出改进建议。\n\n如果这个项目恰好帮你节省了一点时间，欢迎在 GitHub 仓库点亮一颗 Star ⭐。每一个 Star，都是持续维护和完善这个项目的动力。\n\n也欢迎对 AI、Agent、1688 采集或跨境电商工具感兴趣的朋友一起交流。可以添加本人微信：`longbang_ozon`。\n\n<p align=\"center\">\n  <img src=\"./assets/wechat-longbang-ozon.jpg\" alt=\"微信：longbang_ozon\" width=\"280\">\n</p>\n\n---\n\n## 能做什么\n\n| 功能 | 说明 |\n| --- | --- |\n| 关键词搜索 | 在 1688 搜索商品，并自动进入每个候选商品页深采详情。 |\n| 图片搜索 | 使用本地图片寻找相似商品，再深采候选详情。 |\n| 商品详情深采 | 输入一个或多个 `offer_id`，采集标题、价格、图片、SKU、规格和包装相关原始信息。 |\n| 官方相似商品 | 只使用 1688 官方“找相似”入口获取候选，再深采；不会回退成关键词或图片搜索。 |\n| SKU 数量筛选 | 关键词搜索时可只保留 SKU 数量不超过指定值的商品。 |\n| 多账号 Profile | 不同账号以独立 profile 保存会话、锁和调试记录，可手动切换。 |\n| 调试与诊断 | 查看浏览器、登录状态、请求事件、失败原因和本地采集产物。 |\n\n## 环境要求\n\n- Node.js `20+`\n- npm、pnpm 或其他兼容的 Node.js 包管理器\n- 可正常登录的 1688 账号\n\n## 安装\n\n推荐全局安装。安装时会优先使用本机 Google Chrome；未检测到 Chrome 时，`postinstall` 会自动下载 Playwright 内置 Chromium（约 150 MB）。中国时区默认使用 `npmmirror` 镜像；下载失败不会中断安装，可稍后手动重试。\n\n```powershell\npnpm add -g 1688-claw\n```\n\n检查环境：\n\n```powershell\n1688-claw doctor\n```\n\n查看全部命令：\n\n```powershell\n1688-claw --help\n1688-claw source --help\n```\n\n如果 Chromium 自动下载失败，请先安装 Google Chrome（推荐），或手动执行：\n\n```powershell\n$env:PLAYWRIGHT_DOWNLOAD_HOST=\"https://npmmirror.com/mirrors/playwright\"\nnpx playwright install chromium\n```\n\n从 Git 源码开发时才需要运行 `pnpm install`、`pnpm build`；普通使用者不需要下载仓库或执行构建。\n\n## 账号与稳定运行建议\n\n建议至少配置 **两个你有权使用的 1688 账号**，每个账号使用独立 profile。商品详情采集统一遵循：账号 1 最多尝试 3 次；仍失败时切换账号 2，最多再尝试 3 次；仍失败则记录该商品为跳过并继续下一个商品。若本次所有待采商品都失败，命令会以失败状态结束。\n\n账号 2 可用 `--fallback-profile account-b` 显式指定；未指定时，工具只会从本机其他**已登录** profile 中挑选一个。不会共享 Cookie。验证码、风控、登录失效和限流属于安全例外：工具不会靠换号规避这些限制，而是记录失败并要求人工处理。\n\n```powershell\n# 登录第一个账号\n1688-claw login --profile account-a --headed\n\n# 登录第二个账号\n1688-claw login --profile account-b --headed\n\n# 查看 profile 状态\n1688-claw profile list\n1688-claw profile status account-a\n\n# 采集时手动指定使用哪个账号\n1688-claw source keyword \"一次性杯子\" --profile account-a --fallback-profile account-b --max 5\n1688-claw source keyword \"硅胶锅铲\" --profile account-b --max 5\n```\n\n## 命令行说明\n\n### 登录、退出与账号状态\n\n```powershell\n# 终端二维码登录\n1688-claw login\n\n# 打开浏览器窗口登录或人工处理验证\n1688-claw login --headed\n\n# 强制重新登录，最长等待 300 秒\n1688-claw login --force --timeout 300 --profile account-a\n\n# 查看当前账号；--verify 会在线验证会话\n1688-claw whoami --profile account-a\n1688-claw whoami --verify --profile account-a\n\n# 退出并清除指定 profile 的本地会话\n1688-claw logout --profile account-a --yes\n```\n\n### 关键词搜索与深采\n\n关键词搜索不是只返回列表：工具会搜索候选后进入商品详情页，采集可用的商品、图片、价格和 SKU 原始事实。\n\n```powershell\n# 搜索并深采，默认最多 20 个商品\n1688-claw source keyword \"一次性杯子\"\n\n# 最多保留 5 个商品\n1688-claw source keyword \"一次性杯子\" --max 5\n\n# 指定排序与价格区间\n1688-claw source keyword \"一次性杯子\" --sort price-asc --price-min 2 --price-max 20\n\n# 只保留 SKU 数不超过 5 的商品\n1688-claw source keyword \"一次性杯子\" --sku-max 5\n\n# 发生验证时打开浏览器，由人工处理\n1688-claw source keyword \"一次性杯子\" --headed --profile account-a\n```\n\n`--sort` 可选值：`relevance`、`price-asc`、`price-desc`。\n\n### 图片搜索与深采\n\n```powershell\n1688-claw source image \"D:\\\\images\\\\product.jpg\"\n1688-claw source image \"D:\\\\images\\\\product.jpg\" --max 5 --headed --profile account-a\n```\n\n### 指定商品详情深采\n\n`offer_id` 是 1688 商品链接中的数字 ID。例如：\n`https://detail.1688.com/offer/993473951995.html` 中的 ID 是 `993473951995`。\n\n```powershell\n# 深采一个商品\n1688-claw source offers 993473951995\n\n# 一次深采多个商品\n1688-claw source offers 993473951995 123456789012 --profile account-a\n```\n\n### 官方相似商品\n\n```powershell\n# 只走 1688 官方相似商品入口，再对候选商品深采\n1688-claw source similar 993473951995\n1688-claw source similar 993473951995 --max 10 --headed --profile account-b\n```\n\n### 诊断、Profile 与调试\n\n```powershell\n# 检查 Node、Chromium、登录态、锁和本地目录\n1688-claw doctor\n\n# 不启动 Chromium 的快速检查\n1688-claw doctor --no-launch\n\n# 列出 profile 与指定 profile 状态\n1688-claw profile list\n1688-claw profile status account-a\n\n# 查看最近采集请求和失败记录\n1688-claw debug list\n1688-claw debug list --limit 50\n1688-claw debug list --failed\n1688-claw debug last --failed\n1688-claw debug show <requestId>\n```\n\n## 给 Agent 的 JSON 输出\n\n普通命令输出人类可读 JSON。若由 Agent 调用，建议启用 JSON 信封：\n\n```powershell\n1688-claw --json-v2 source keyword \"硅胶锅铲\" --max 3\n1688-claw --pretty source offers 993473951995\n1688-claw --json whoami --profile account-a\n```\n\n全局输出参数：\n\n| 参数 | 用途 |\n| --- | --- |\n| `--json` | 强制 JSON 输出。 |\n| `--json-v2` | 输出包含 `ok`、命令名、耗时和错误结构的 Agent 信封。 |\n| `--pretty` | 格式化 JSON。 |\n| `--get <path>` | 输出 JSON 内一个路径的值。 |\n| `--pick <paths>` | 输出多个逗号分隔的 JSON 路径。 |\n\n## 数据与安全边界\n\n- 登录会话和调试产物保存在用户本机的 1688 本地目录，不写入仓库。\n- 不要提交 profile、Cookie、截图或采集产物到 Git。\n- 工具不会尝试破解滑块、验证码或其他 1688 风控机制。\n- 出现 `RISK_CONTROL`、登录失效或验证页面时，使用 `--headed` 并由人工处理后再重试。\n\n## 开发命令\n\n```powershell\n# 直接运行 TypeScript 源码\npnpm dev -- source keyword \"一次性杯子\" --max 3\n\n# 编译全部 workspace 包\npnpm build\n\n# 类型检查\npnpm typecheck\n```\n","readmeFilename":"README.md"}