分销采购助手#

背景说明#

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，不得先执行任何接口调用。 运行以下命令：

bash

python3 scripts/capabilities/configure/cmd.py

• 显示 "✅ AK 已配置"：直接进入后续步骤，不要向用户提及此检查。

• 显示 "❌ 尚未配置 AK"：输出下方 AK 引导话术，然后 停止，等待用户回复，不要做任何其他操作。

  • 用户回复后，从消息中提取 AK 字符串，执行： bash

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

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

AK 引导话术#

text

需要先配置 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 调用：

bash

# 获取 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 中直接调用：

python

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_<APPKEY> 注入（视为永不过期）

---

使用流程#

步骤 1：调用接口#

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

bash

# 基础调用
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：

json

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

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

错误处理#

常见错误及处理：

错误信息原因处理方式AK 未配置未设置环境变量 ALI_1688_AK执行 AK 配置流程参数错误传入的参数不正确检查参数格式网络异常接口调用失败稍后重试

依赖包#

bash

pip install requests

ISV Provider 架构#

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

text

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

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

项目结构#

text

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/        # 订单助手

语言要求#

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