1688 Source Suppliers

---
name: 1688-source-suppliers
description: 按品类查工厂，资质/产能/合作方式一目了然
title: 1688寻源
example: 帮我寻找浙江地区生产不锈钢保温杯、支持OEM贴牌且起订量在500个以内的源头工厂。
version: 1.0.0
---
# 1688-source-suppliers

统一入口：`python3 {baseDir}/cli.py <command> [options]`

所有命令输出 JSON：`{"success": bool, "markdown": str, "data": {...}}`

**展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。**

## ⚠️ 核心限制

**失败时直接告知用户，不编造！**

```
❌ 禁止：编造供应商信息、伪造工厂数据、臆测供应商资质...
✅ 仅允许：如实返回CLI工具结果，失败时告知用户原因
```

## 会话授权状态

**授权检查规则**：
- 同一会话内，首次查询时检查 AK 授权状态
- 若已授权：直接执行查询，无需重复验证
- 若未授权：**自动执行 `python3 cli.py get_ak` 通过浏览器获取 AK，不要询问用户**

**会话状态记忆**：
```
会话开始 → 检查AK → 未授权 → 自动执行 cli.py get_ak → 授权成功 → 记录状态
                                    ↓
                               已授权 → 直接执行查询（不重复验证）
```

### 重试机制

当服务返回失败时，自动进行最多3轮重试：

```
第1次失败 → 等待1秒 → 第2次重试
第2次失败 → 等待1秒 → 第3次重试
第3次失败 → 停止重试，告知用户
```

### 失败时处理规则

当3轮重试后依然失败时：

```
1. 立即停止后续一切操作
2. 直接告知用户失败原因（data.error 字段）和重试次数
3. 不要尝试其他方式获取数据
4. 不要使用搜索引擎补充
5. 不要编造信息填补
6. 等待用户处理后重试
```

### 失败响应示例

```json
{
  "success": false,
  "markdown": "❌ 查询失败（已重试3次）：xxx原因\n\n请稍后重试。\n\n> 📌 [在1688上搜索更多供应商](https://s.1688.com/company/company_search.htm)",
  "data": { "error": "具体错误信息", "retries": 3 }
}
```

**注意**：引导链接仅在查询失败时显示，成功时不显示。

**Agent 禁止行为**：
- ❌ 不要手动重试（CLI已自动重试3次）
- ❌ 不要使用搜索引擎补充
- ❌ 不要使用其他工具获取数据
- ❌ 不要编造信息填补空缺
- ❌ 不要访问外部网站
- ✅ 直接告知用户失败原因，等待用户指示

## 严格禁止（NEVER DO）

1. **🚫 禁止编造供应商信息**：所有数据必须来源于 CLI 工具返回结果，不得臆测或编造
2. **🚫 禁止编造信息填补**：查询失败或数据不完整时，不得编造信息，直接告知用户即可
3. **🚫 禁止在失败后继续操作**：服务失败时立即终止，直接告知用户，不要使用其他方式补充
4. **🚫 禁止使用搜索引擎**：不得使用 WebSearch、百度、Google、必应等获取供应商数据
5. **🚫 禁止访问外部网站**：不得访问任何第三方网站获取供应商数据
6. **🚫 禁止擅自改写关键字**：不得在未征得用户认可的情况下修改查询意图

**核心原则**：失败时直接告知用户，不编造、不臆测、不补充。

## 意图判断（快速匹配）

### 匹配优先级

**P0 - 核心触发词（命中即触发）**：
> 供应商、工厂、厂家、厂商、生产商、制造商、代工厂、源头工厂、工厂店

**P1 - 行为触发词（需搭配商品词）**：
> 找供应商、找工厂、找厂家、采购XX、筛选供应商、对比供应商

**P2 - 服务触发词（需搭配供应商场景）**：
> 贴牌、OEM、ODM、一件代发、定制logo、打样

### 触发规则

```
命中 P0 词 → ✅ 触发 → 调用CLI
命中 P1 词 + 商品词 → ✅ 触发 → 调用CLI
仅商品词 → ❌ 不触发 → 1688-product-find
```

## 关键字提取规则

### 提取公式

```
关键字 = 商品词 + 供应商词
```

| 用户输入 | 提取关键字 |
|---------|-----------|
| "帮我找做不锈钢保温杯的供应商" | `不锈钢保温杯供应商` |
| "我想找儿童书包厂家" | `儿童书包厂家` |
| "我需要采购宠物牵引绳" | `宠物牵引绳供应商` |

### 筛选条件处理

筛选条件**不加入关键字**，仅用于结果分析：

| 条件类型 | 关键词 | 处理方式 |
|---------|--------|---------|
| MOQ | 起订量、500以内 | 结果中筛选 |
| 定制能力 | 定制logo、贴牌 | 结果中筛选 |
| 工厂属性 | 工厂店、源头工厂 | 结果中筛选 |

## 执行流程

```
步骤1: 检查会话授权状态
       ├─ 已授权 → 继续
       └─ 未授权 → 自动执行 python3 cli.py get_ak → 授权成功 → 记录状态 → 继续

步骤2: 提取关键字 → 商品词 + 供应商词

步骤3: 调用CLI工具 → python3 cli.py ali_1688_source_suppliers -q "<关键字>"

步骤4: 处理响应
       ├─ success: true → 输出表格 + Agent分析
       └─ success: false → 返回失败原因 + 引导链接 → 终止

步骤5: Agent分析（可选）→ 根据用户需求提供筛选建议
```

## 输出格式

### 表格样式

返回数据以表格形式展示，**公司名称可点击跳转**：

| 序号 | 公司名称 | 所在地区 | 合作方式 | 服务 | 工厂信息 | 服务指标 |
|:----:|---------|---------|---------|------|---------|---------|
| 1 | [XX公司](url) | 广东中山 | OEM, ODM | 清加工 | 无牌工厂 | 高好评, 月38单 |

**点击公司名称即可跳转到供应商详情页**

### 必填字段

公司名称、合作方式、服务

### 输出顺序

表格 → Agent分析

**引导链接**：仅在查询失败时显示，供用户手动搜索。

## 风险识别

| 风险关键词 | 风险类型 | Agent 应对 |
|-----------|---------|-----------|
| 大牌同款、高仿、复刻 | 侵权风险 | 提示风险，给合规建议 |
| 儿童用品+低价 | 安全风险 | 提示安全资质要求 |
| 医用级、食品级 | 合规风险 | 提示证照核验 |
| 帮我找方向 | 意图模糊 | 先追问具体品类 |

## 命令速查

| 命令 | 说明 | 示例 |
|------|------|------|
| `ali_1688_source_suppliers` | 查询供应商信息 | `cli.py ali_1688_source_suppliers -q "灯具供应商"` |
| `get_ak` | 通过浏览器获取 AK | `cli.py get_ak` |
| `configure` | 配置 AK（设置/查看/清除/重置） | `cli.py configure YOUR_AK` |

### configure 子命令（别名）

| 子命令 | 别名 | 说明 | 示例 |
|--------|------|------|------|
| `<AK>` | `set_ak` | 设置 AK | `cli.py configure YOUR_AK` |
| `--status` | `status_ak` | 查看 AK 状态 | `cli.py configure --status` |
| `--reset <AK>` | `reset_ak` | 重置 AK（清除旧 Token + 配置新 AK） | `cli.py configure --reset YOUR_NEW_AK` |
| `--clear` | `clear_ak` | 清除 AK（同时清除关联 Token） | `cli.py configure --clear` |

## AK 安全说明

> ⚠️ **AK 是访问 1688 接口的唯一凭证，请妥善保管，避免泄漏。**

- AK 在本地以**设备绑定加密**方式存储（PBKDF2 派生密钥 + 流加密 + HMAC 校验），加密文件拷贝到其他机器后**无法解密**
- 不要将 AK 明文粘贴到聊天记录、截图、日志或版本控制中
- 不要将 `ak_store.json` 或 `.device_id` 上传到任何云端或共享目录
- 如怀疑 AK 已泄漏，立即执行 `cli.py configure --clear` 清除本地存储，并前往 [clawhub.1688.com](https://clawhub.1688.com/) 重新获取


## 授权链接处理（BrowserWorker 插件浏览器）

`get_ak` 和 `authorize` 命令会启动本地回调服务器，通过项目内 BrowserWorker daemon + Chrome 插件打开 1688 授权页，并同步等待授权回调（最长 300 秒）。

**成功输出格式**：
```json
{
  "success": true,
  "markdown": "AK 设置成功",
  "data": {"ak": "<AK值>"}
}
```

**BrowserWorker 要求**：
- 只使用项目内 BrowserWorker daemon + Chrome 插件打开授权页；daemon 未启动时脚本会尝试按当前工作区启动
- 不使用 `browser_use`、系统默认浏览器、`open` 命令、Playwright、Selenium、ChromeDriver 或 CDP 直连作为替代方案
- 授权页打开后会执行通用 `detect_page_state` 检测；如页面需要登录或验证码，Agent 应提示用户在已经打开的 Chrome 页面中完成，然后等待 CLI 返回
- BrowserWorker `/lock/release` 只释放并发锁，默认不关闭授权页；需要关闭时显式调用 `/session/close` 或 release 时传 `close_browser: true`

**Agent 处理流程**：
1. 执行 `python3 cli.py get_ak`。
2. 若 Chrome 页面需要登录/验证码，提示用户在已打开页面处理；不要自动重复发起 get_ak。
3. CLI 返回 `success: true` 后，调用 `python3 cli.py configure --status` 确认 AK 是否已保存成功。
4. 继续执行原始供应商查询。

**注意事项**：
- 授权回调目标是 `localhost` / `127.0.0.1`，端口为脚本动态分配的 8080–8089。
- 若 300 秒内未完成授权，CLI 会返回 `AUTHORIZATION_TIMEOUT`。
- 如果 BrowserWorker 或插件不可用，CLI 会返回 `BROWSERWORKER_OPEN_FAILED`，Agent 应提示用户检查 daemon/插件，不要改用网页搜索或系统浏览器补数据。
- 本技能无必装第三方 Python 包；`keyring` 为可选能力，未安装时自动使用文件加密存储。

## 异常处理

| 场景 | 响应字段 | Agent 动作 |
|------|---------|-----------|
| AK未授权 | `needAuth: true` | **自动执行 `python3 cli.py get_ak`**，不要询问用户 |
| AK格式无效 | `success: false` | 提示用户 AK 格式无效，请重新配置 |
| 服务失败（已重试3次） | `success: false`, `retries: 3` | 直接告知用户失败原因，不要使用其他方式补充 |
| 参数缺失 | `success: false` | 直接告知用户缺少参数 |
| 限流/429 | `success: false` | 直接告知用户请稍后重试 |
| 格式异常 | `success: false` | 直接告知用户服务异常，稍后重试 |

**重试机制**：CLI自动重试3次，Agent无需手动重试。

**核心原则**：失败时直接告知用户，不要尝试其他方式获取或补充数据。