Skip to content

Commit 81de69b

Browse files
leozejia泽加武
andauthored
feat(1688): add browser adapter and docs (#650)
* feat(1688): add browser adapter and docs * fix(1688): retry alternate store seed offers * feat(1688): harden adapter contracts and search pagination --------- Co-authored-by: 泽加武 <zejiawu@zejiawudeMac-mini.local>
1 parent a39a858 commit 81de69b

15 files changed

Lines changed: 1957 additions & 0 deletions

File tree

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && n
129129
| **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
130130
| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `user` `user-posts` `user-comments` `read` `save` `saved` `subscribe` `upvote` `upvoted` `comment` |
131131
| **amazon** | `bestsellers` `search` `product` `offer` `discussion` |
132+
| **1688** | `search` `item` `store` |
132133
| **gemini** | `new` `ask` `image` |
133134
| **yuanbao** | `new` `ask` |
134135
| **notebooklm** | `status` `list` `open` `select` `current` `get` `metadata` `source-list` `source-get` `source-fulltext` `source-guide` `history` `note-list` `notes-list` `notes-get` `summary` |

README.zh-CN.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@ npx skills add jackwener/opencli --skill opencli-oneshot # 快速命令参
181181
| **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 浏览器 |
182182
| **google** | `news` `search` `suggest` `trends` | 公开 |
183183
| **amazon** | `bestsellers` `search` `product` `offer` `discussion` | 浏览器 |
184+
| **1688** | `search` `item` `store` | 浏览器 |
184185
| **gemini** | `new` `ask` `image` | 浏览器 |
185186
| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | OAuth API |
186187
| **notebooklm** | `status` `list` `open` `select` `current` `get` `metadata` `source-list` `source-get` `source-fulltext` `source-guide` `history` `note-list` `notes-list` `notes-get` `summary` | 浏览器 |

docs/.vitepress/config.mts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ export default defineConfig({
7373
{ text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
7474
{ text: 'Grok', link: '/adapters/browser/grok' },
7575
{ text: 'Amazon', link: '/adapters/browser/amazon' },
76+
{ text: '1688', link: '/adapters/browser/1688' },
7677
{ text: 'Gemini', link: '/adapters/browser/gemini' },
7778
{ text: 'Yuanbao', link: '/adapters/browser/yuanbao' },
7879
{ text: 'NotebookLM', link: '/adapters/browser/notebooklm' },

docs/adapters/browser/1688.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# 1688
2+
3+
**Mode**: 🔐 Browser · **Domain**: `1688.com`
4+
5+
## Commands
6+
7+
| Command | Description |
8+
|---------|-------------|
9+
| `opencli 1688 search "<query>" --limit <n>` | Search public product candidates with price, MOQ, seller link, and visible badges |
10+
| `opencli 1688 item <url-or-offer-id>` | Read a public product detail page with price tiers, MOQ, delivery text, and seller basics |
11+
| `opencli 1688 store <url-or-member-id>` | Read a public supplier/store page with company info, years on platform, categories, and visible service signals |
12+
13+
## Usage Examples
14+
15+
```bash
16+
# Search products
17+
opencli 1688 search "桌面置物架 宿舍 收纳" --limit 10
18+
19+
# JSON output
20+
opencli 1688 search "桌面置物架 宿舍 收纳" --limit 10 -f json
21+
22+
# Read an item by offer id
23+
opencli 1688 item 841141931191 -f json
24+
25+
# Read an item by URL
26+
opencli 1688 item https://detail.1688.com/offer/841141931191.html -f json
27+
28+
# Read a supplier store
29+
opencli 1688 store https://shop52908bfw19166.1688.com/ -f json
30+
31+
# Read a supplier by member id
32+
opencli 1688 store b2b-22154705262941f196 -f json
33+
```
34+
35+
## Prerequisites
36+
37+
- Chrome running and **logged into** `1688.com`
38+
- [Browser Bridge extension](/guide/browser-bridge) installed
39+
40+
## Notes
41+
42+
- This adapter only returns fields visible on public pages. It does not send inquiries, place orders, or access seller back office data.
43+
- Prefer stable identifiers such as `offer_id`, `member_id`, and `shop_id` for follow-up workflows.
44+
- `search --limit` defaults to `20` and is capped at `100`.
45+
- `search` deduplicates with key priority: `offer_id` first, then canonical `item_url`.
46+
- `item` can be more sensitive to the active browser target than `search` or `store`.
47+
48+
## Troubleshooting
49+
50+
- If `opencli 1688 item` reports `did not expose product context`, first make sure the open page is a real `detail.1688.com` item page.
51+
- If the browser target is too broad, retry with `OPENCLI_CDP_TARGET=detail.1688.com`.
52+
- If you hit a slider or verification page, refresh the real page in Chrome and retry.

docs/adapters/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ Run `opencli list` for the live registry.
4646
| **[google](./browser/google)** | `news` `search` `suggest` `trends` | 🌐 / 🔐 |
4747
| **[jd](./browser/jd)** | `item` | 🔐 Browser |
4848
| **[amazon](./browser/amazon)** | `bestsellers` `search` `product` `offer` `discussion` | 🔐 Browser |
49+
| **[1688](./browser/1688)** | `search` `item` `store` | 🔐 Browser |
4950
| **[web](./browser/web)** | `read` | 🔐 Browser |
5051
| **[weixin](./browser/weixin)** | `download` | 🔐 Browser |
5152
| **[36kr](./browser/36kr)** | `news` `hot` `search` `article` | 🌐 / 🔐 |

docs/developer/testing.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,8 @@ npx vitest src/
131131
- `browser-public.test.ts` 使用 `tryBrowserCommand()`,站点反爬或地域限制导致空数据时会 warn + pass
132132
- `browser-auth.test.ts` 验证 **graceful failure**,重点是不 crash、不 hang、错误信息可控
133133
- 如需测试完整登录态,保持 Chrome 登录态并安装 Browser Bridge 扩展,再手动运行对应测试
134+
- 对依赖具体 host 页面上下文的 browser adapter,除了单测外,还应手动验证真实命令,并把必要的 target host 约束写进 adapter docs / troubleshooting
135+
- 对会主动导航页面的 browser commands,手动验证时优先串行执行;多个 CLI 进程同时连到同一个 CDP target 可能互相覆盖导航,制造假的 adapter 故障
134136

135137
---
136138

docs/guide/troubleshooting.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,17 @@
1212
- Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page.
1313
- Some sites have geographic restrictions (e.g., Bilibili, Zhihu from outside China).
1414

15+
### Browser command opens the page but still cannot read context
16+
17+
- A healthy Browser Bridge connection does not guarantee that the current page target exposes the data your adapter expects.
18+
- Some browser adapters are sensitive to the active host or page context.
19+
- Example: `opencli 1688 item` may fail with `did not expose product context` if the target is too broad.
20+
- Retry on a real item page, refresh the page in Chrome, and if needed narrow the target, for example:
21+
22+
```bash
23+
OPENCLI_CDP_TARGET=detail.1688.com opencli 1688 item 841141931191 -f json
24+
```
25+
1526
### Node API errors
1627

1728
- Make sure you are using **Node.js >= 20**. Some dependencies require modern Node APIs.

src/clis/1688/item.test.ts

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
import { describe, expect, it } from 'vitest';
2+
import { __test__ } from './item.js';
3+
4+
describe('1688 item normalization', () => {
5+
it('normalizes public item payload into contract fields', () => {
6+
const result = __test__.normalizeItemPayload({
7+
href: 'https://detail.1688.com/offer/887904326744.html',
8+
title: '法式春季长袖开衫连衣裙女新款大码女装碎花吊带裙套装142077 - 阿里巴巴',
9+
bodyText: `
10+
青岛沁澜衣品服装有限公司
11+
入驻13年
12+
主营:大码女装
13+
店铺回头率
14+
87%
15+
山东青岛
16+
3套起批
17+
已售1600+套
18+
支持定制logo
19+
`,
20+
offerTitle: '法式春季长袖开衫连衣裙女新款大码女装碎花吊带裙套装142077',
21+
offerId: 887904326744,
22+
seller: {
23+
companyName: '青岛沁澜衣品服装有限公司',
24+
memberId: 'b2b-1641351767',
25+
winportUrl: 'https://yinuoweierfushi.1688.com/page/index.html?spm=a1',
26+
},
27+
trade: {
28+
beginAmount: 3,
29+
priceDisplay: '96.00-98.00',
30+
unit: '套',
31+
saleCount: 1655,
32+
offerIDatacenterSellInfo: {
33+
面料名称: '莫代尔',
34+
主面料成分: '莫代尔纤维',
35+
sellPointModel: '{"ignore":true}',
36+
},
37+
offerPriceModel: {
38+
currentPrices: [
39+
{ beginAmount: 3, price: '98.00' },
40+
{ beginAmount: 50, price: '97.00' },
41+
],
42+
},
43+
},
44+
gallery: {
45+
mainImage: ['https://example.com/1.jpg'],
46+
offerImgList: ['https://example.com/2.jpg'],
47+
wlImageInfos: [{ fullPathImageURI: 'https://example.com/3.jpg' }],
48+
},
49+
services: [
50+
{ serviceName: '延期必赔', agreeDeliveryHours: 360 },
51+
{ serviceName: '品质保障' },
52+
],
53+
});
54+
55+
expect(result.offer_id).toBe('887904326744');
56+
expect(result.member_id).toBe('b2b-1641351767');
57+
expect(result.shop_id).toBe('yinuoweierfushi');
58+
expect(result.seller_url).toBe('https://yinuoweierfushi.1688.com');
59+
expect(result.price_text).toBe('¥96.00-98.00');
60+
expect(result.moq_text).toBe('3套起批');
61+
expect(result.origin_place).toBe('山东青岛');
62+
expect(result.delivery_days_text).toBe('360小时内发货');
63+
expect(result.private_label_text).toBe('支持定制logo');
64+
expect(result.visible_attributes).toEqual([
65+
{ key: '面料名称', value: '莫代尔' },
66+
{ key: '主面料成分', value: '莫代尔纤维' },
67+
]);
68+
});
69+
});

0 commit comments

Comments
 (0)