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. 等待用户处理后重试

失败响应示例

{
  "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公司	广东中山	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 重新获取

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

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

成功输出格式：

{
  "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无需手动重试。

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