1688 Distribution Procurement Newton

分销采购助手

背景说明

AK（Access Key）通过clawhub获取，通过命令(python3 scripts/capabilities/configure/cmd.py <提取到的AK>)来设置 ALI_1688_AK。AK 已绑定用户身份，无需任何额外的身份参数。

功能概述

• ✅ 店铺绑定 - 绑店状态查询、绑店引导
• ✅ 关联货源 - 将下游商品直接关联/替换到指定的1688商品（需已知目标货源ID，不走筛选）
• ✅ 供应链 - 自动换供（三层流水线：场景层→同款筛选层→货源替换层；自动找替代货源后执行替换）
• ✅ 订单管理 - 自动跟单、采购下单、订单查询、旺旺催发
• ✅ ISV 采购能力 - 通过内置 ISV Provider（张飞搬家，appKey=9018264）支持淘宝和抖音双平台的自动下单、售后、关联货源

前置检查：确认 AK 已配置

skill 触发前，第一步必须立即检查 AK，不得先执行任何接口调用。 运行以下命令：

python3 scripts/capabilities/configure/cmd.py

• 显示 "✅ AK 已配置"：直接进入后续步骤，不要向用户提及此检查。
• 显示 "❌ 尚未配置 AK"：输出下方 AK 引导话术，然后停止，等待用户回复，不要做任何其他操作。
  • 用户回复后，从消息中提取 AK 字符串，执行：

    python3 scripts/capabilities/configure/cmd.py <提取到的AK>
    

  • 配置完成后，直接继续执行用户最初的需求，无需额外说明。

AK 引导话术

需要先配置 AK，获取方式：
打开 [clawhub.1688.com](https://clawhub.1688.com) 点击右上角**钥匙🔑图标**获取 AK
获取后告诉我：「我的AK是 xxxxxx」

ISV Token（调用外部 ISV skill 时使用）

什么时候需要获取 ISV Token？

当业务需要调用 ISV（独立软件开发商）提供的外部 skill 进行通信时，必须先获取对应的 ISV Token 作为身份凭证。例如：调用第三方 ISV 的接口服务时，需要携带该 token 进行鉴权。

如果只调用 1688 内部接口（通过 api_post），则不需要 ISV Token。

如何获取 ISV Token

通过 cli.py 调用：

# 获取 token（自动缓存，24小时有效，未过期时直接返回本地缓存）
python3 scripts/cli.py isv_token fetch --app_key=你的AppKey

# 强制刷新 token（忽略本地缓存）
python3 scripts/cli.py isv_token fetch --app_key=你的AppKey --force_refresh=true

# 检查 token 状态
python3 scripts/cli.py isv_token status --app_key=你的AppKey

在 service.py 中直接调用：

from scripts.biz.isv_token.service import fetch_isv_token, check_token_status

token = fetch_isv_token(app_key="你的AppKey")
status = check_token_status(app_key="你的AppKey")
# 返回：{"exists": bool, "expired": bool, "token": str, "remainingHours": float}

Token 缓存机制

• Token 保存在 ~/.isv_tokens.json，按 appKey 索引，多个 skill 共享同一份缓存
• 默认有效期 24 小时，过期后自动重新获取
• 也支持通过环境变量 ISV_TOKEN_ 注入（视为永不过期）

---

使用流程

步骤 1：调用接口

通过 cli.py 统一入口调用业务接口：

# 基础调用
python3 scripts/cli.py <业务域> <动作> [--参数名=参数值]

# 店铺绑定
python3 scripts/cli.py shop_bind_helper query  # 查询绑定的店铺和工具信息
python3 scripts/cli.py shop_bind_helper app_keys  # 查询 ISV AppKey 信息

# ISV Token（用于调用外部 ISV skill）
python3 scripts/cli.py isv_token fetch --app_key=YOUR_APP_KEY
python3 scripts/cli.py isv_token status --app_key=YOUR_APP_KEY

# ISV Skill 调用
python3 scripts/cli.py isv_skill_helper find_skill --app_key=9018264
python3 scripts/cli.py isv_skill_helper find_skill --skill_name=zhangfei
python3 scripts/cli.py isv_skill_helper list_builtin
python3 scripts/cli.py isv_skill_helper link_supply \
  --skill_path=/path/to/skill --token=xxx \
  --shop_id=123 --shop_nick=店铺名 --local_item_id=456 \
  --source_offer_url=https://detail.1688.com/offer/xxx.html \
  --purchase_account=采购账号 --platform=taobao

# 关联货源（直接关联到指定货源，不走筛选）
python3 scripts/cli.py link_supply_helper link_supply --downstream_item_id=xxx --offer_id=xxx --isv_app_key=xxx --platform=douyin
python3 scripts/cli.py link_supply_helper link_supply --downstream_item_id=xxx --downstream_sku_id=xxx --offer_id=xxx --sku_id=xxx --isv_app_key=xxx --platform=taobao

# 供应链（自动换供 = 自动筛选同款 + 图搜fallback + 执行替换）
python3 scripts/cli.py supply_chain_helper auto_switch_supply --offer_ids=688001234,688005678 --downstream_item_id=xxx
python3 scripts/cli.py supply_chain_helper auto_switch_supply --offer_ids=688001234 --downstream_item_id=xxx --reason=亏损换供
python3 scripts/cli.py supply_chain_helper auto_switch_supply --offer_ids=688001234 --offer_image_url=https://xxx.jpg

# ISV 下游关联货源
python3 scripts/cli.py supply_chain_helper downstream_link \
  --app_key=9018264 --shop_id=12345 --shop_nick=店铺名 \
  --local_item_id=67890 --source_offer_url=https://detail.1688.com/offer/xxx.html \
  --purchase_account=采购账号 --platform=taobao

# 订单查询
python3 scripts/cli.py order_helper query
python3 scripts/cli.py order_helper query --order_id=xxx
python3 scripts/cli.py order_helper query --order_status=waitbuyerreceive

# 旺旺消息
python3 scripts/cli.py order_helper send --question="请尽快发货" --order_ids=xxx
python3 scripts/cli.py order_helper query_reply --task_id=xxx
python3 scripts/cli.py order_helper urge
python3 scripts/cli.py order_helper urge --template=urgent

步骤 2：处理返回结果

所有命令统一输出 JSON：

{
  "success": true,
  "markdown": "✅ 调用成功",
  "data": { ... }
}

• success=true：直接使用 markdown 展示给用户，data 包含结构化数据
• success=false：markdown 包含错误描述

错误处理

常见错误及处理：

依赖包

pip install requests

ISV Provider 架构

项目采用可插拔的 ISV Provider 架构（与 1688-distribution-distribute-offer-newton 目录分级一致），ISV 统一在 scripts/isv/ 下管理：

scripts/isv/
├── base.py                         # ISV Provider 基类 + 全局注册表
└── providers/
    ├── zhangfei/                    # 张飞搬家（appKey=9018264）
    │   ├── provider.py              # Provider 注册
    │   ├── cli.py                   # CLI 入口（淘宝+抖音）
    │   ├── SKILL.md                 # ISV 业务流程文档
    │   └── scripts/
    │       ├── _api.py              # 中台鉴权
    │       └── procurement.py       # 业务逻辑
    └── /                # 后续新增 ISV

新增 ISV：在 scripts/isv/providers/ 下创建目录，实现 provider.py 并注册即可。

项目结构

1688-distribution-procurement-newton/
├── SKILL.md                     # 技能说明文档（本文档）
├── README.md                    # 项目说明文档
├── examples/                    # 示例代码目录
│   ├── check_env.py            # 环境检查
│   ├── check_ak_exist.py       # 检查 AK 配置
│   └── set_ak.py               # 设置 AK
└── scripts/
    ├── cli.py                   # ⭐ 统一命令行入口
    ├── _sys/                    # 系统模块（不要修改）
    │   ├── _http.py             # HTTP 客户端
    │   ├── _auth.py             # 签名认证
    │   ├── _errors.py           # 错误类型
    │   ├── _const.py            # 全局常量
    │   ├── _output.py           # 输出格式化
    │   └── _skill_discovery.py  # ISV Skill 发现
    ├── capabilities/configure/  # AK 配置能力（不要修改）
    ├── isv/                     # ⭐ ISV Provider 架构
    │   ├── base.py              # Provider 基类 + 注册表
    │   └── providers/           # 各 ISV 实现
    │       └── zhangfei/        # 张飞搬家（appKey=9018264）
    └── biz/                     # ⭐ 业务逻辑（按业务域拆分）
        ├── const.py             # 业务常量配置（可修改）
        ├── isv_token/           # ISV Token 管理
        ├── isv_skill_helper/    # ISV Skill 调用助手
        ├── shop_bind_helper/    # 店铺绑定助手
        ├── link_supply_helper/  # 关联货源助手
        ├── supply_chain_helper/ # 供应链助手
        └── order_helper/        # 订单助手

语言要求

⚠️ 重要：本技能的所有输出、提示、消息必须使用中文！