feat(1688): add browser adapter and docs

docs/adapters/browser/1688.md

@@ -0,0 +1,50 @@
+# 1688
+
+**Mode**: 🔐 Browser · **Domain**: `1688.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli 1688 search "<query>"` | Search public product candidates with price, MOQ, seller link, and visible badges |
+| `opencli 1688 item <url-or-offer-id>` | Read a public product detail page with price tiers, MOQ, delivery text, and seller basics |
+| `opencli 1688 store <url-or-member-id>` | Read a public supplier/store page with company info, years on platform, categories, and visible service signals |
+
+## Usage Examples
+
+```bash
+# Search products
+opencli 1688 search "桌面置物架 宿舍 收纳" --limit 10
+
+# JSON output
+opencli 1688 search "桌面置物架 宿舍 收纳" --limit 10 -f json
+
+# Read an item by offer id
+opencli 1688 item 841141931191 -f json
+
+# Read an item by URL
+opencli 1688 item https://detail.1688.com/offer/841141931191.html -f json
+
+# Read a supplier store
+opencli 1688 store https://shop52908bfw19166.1688.com/ -f json
+
+# Read a supplier by member id
+opencli 1688 store b2b-22154705262941f196 -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** `1688.com`
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Notes
+
+- This adapter only returns fields visible on public pages. It does not send inquiries, place orders, or access seller back office data.
+- Prefer stable identifiers such as `offer_id`, `member_id`, and `shop_id` for follow-up workflows.
+- `item` can be more sensitive to the active browser target than `search` or `store`.
+
+## Troubleshooting
+
+- If `opencli 1688 item` reports `did not expose product context`, first make sure the open page is a real `detail.1688.com` item page.
+- If the browser target is too broad, retry with `OPENCLI_CDP_TARGET=detail.1688.com`.
+- If you hit a slider or verification page, refresh the real page in Chrome and retry.

docs/adapters/index.md

@@ -42,6 +42,7 @@ Run `opencli list` for the live registry.
 | **[tiktok](/adapters/browser/tiktok)** | `explore` `search` `profile` `user` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `live` `notifications` `friends` | 🔐 Browser |
 | **[google](/adapters/browser/google)** | `news` `search` `suggest` `trends` | 🌐 / 🔐 |
 | **[jd](/adapters/browser/jd)** | `item` | 🔐 Browser |
+| **[1688](/adapters/browser/1688)** | `search` `item` `store` | 🔐 Browser |
 | **[web](/adapters/browser/web)** | `read` | 🔐 Browser |
 | **[weixin](/adapters/browser/weixin)** | `download` | 🔐 Browser |
 | **[36kr](/adapters/browser/36kr)** | `news` `hot` `search` `article` | 🌐 / 🔐 |

docs/developer/testing.md

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

docs/guide/troubleshooting.md

@@ -12,6 +12,17 @@
 - 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.
 - Some sites have geographic restrictions (e.g., Bilibili, Zhihu from outside China).
 
+### Browser command opens the page but still cannot read context
+
+- A healthy Browser Bridge connection does not guarantee that the current page target exposes the data your adapter expects.
+- Some browser adapters are sensitive to the active host or page context.
+- Example: `opencli 1688 item` may fail with `did not expose product context` if the target is too broad.
+- Retry on a real item page, refresh the page in Chrome, and if needed narrow the target, for example:
+
+```bash
+OPENCLI_CDP_TARGET=detail.1688.com opencli 1688 item 841141931191 -f json
+```
+
 ### Node API errors
 
 - Make sure you are using **Node.js >= 20**. Some dependencies require modern Node APIs.

src/clis/1688/item.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './item.js';
+
+describe('1688 item normalization', () => {
+  it('normalizes public item payload into reportable fields', () => {
+    const result = __test__.normalizeItemPayload({
+      href: 'https://detail.1688.com/offer/887904326744.html',
+      title: '法式春季长袖开衫连衣裙女新款大码女装碎花吊带裙套装142077 - 阿里巴巴',
+      bodyText: `
+        青岛沁澜衣品服装有限公司
+        入驻13年
+        主营：大码女装
+        店铺回头率
+        87%
+        山东青岛
+        3套起批
+        已售1600+套
+        支持定制logo
+      `,
+      offerTitle: '法式春季长袖开衫连衣裙女新款大码女装碎花吊带裙套装142077',
+      offerId: 887904326744,
+      seller: {
+        companyName: '青岛沁澜衣品服装有限公司',
+        memberId: 'b2b-1641351767',
+        winportUrl: 'https://yinuoweierfushi.1688.com',
+      },
+      trade: {
+        beginAmount: 3,
+        priceDisplay: '96.00-98.00',
+        unit: '套',
+        saleCount: 1655,
+        offerIDatacenterSellInfo: {
+          面料名称: '莫代尔',
+          主面料成分: '莫代尔纤维',
+          sellPointModel: '{"ignore":true}',
+        },
+        offerPriceModel: {
+          currentPrices: [
+            { beginAmount: 3, price: '98.00' },
+            { beginAmount: 50, price: '97.00' },
+          ],
+        },
+      },
+      gallery: {
+        mainImage: ['https://example.com/1.jpg'],
+        offerImgList: ['https://example.com/2.jpg'],
+        wlImageInfos: [{ fullPathImageURI: 'https://example.com/3.jpg' }],
+      },
+      services: [
+        { serviceName: '延期必赔', agreeDeliveryHours: 360 },
+        { serviceName: '品质保障' },
+      ],
+    });
+
+    expect(result.offer_id).toBe('887904326744');
+    expect(result.member_id).toBe('b2b-1641351767');
+    expect(result.shop_id).toBe('yinuoweierfushi');
+    expect(result.price_text).toBe('¥96.00-98.00');
+    expect(result.moq_text).toBe('3套起批');
+    expect(result.origin_place).toBe('山东青岛');
+    expect(result.delivery_days_text).toBe('360小时内发货');
+    expect(result.private_label_text).toBe('支持定制logo');
+    expect(result.visible_attributes).toEqual({
+      面料名称: '莫代尔',
+      主面料成分: '莫代尔纤维',
+    });
+  });
+});