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，不得先执行任何接口调用。** 运行以下命令： ```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/` 下管理： ``` 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` 并注册即可。 ## 项目结构 ``` 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/ # 订单助手 ``` ## 语言要求 **⚠️ 重要：本技能的所有输出、提示、消息必须使用中文！**