妙手ERP-TikTok产品编辑

概述

妙手ERP TikTok采集箱

在发布前查询和编辑 TikTok 采集箱商品。此技能负责商品数据就绪性，不负责最终发布。

典型用户请求

• "查询 TikTok 采集箱商品 12345"
• "帮我补全这个 TK 商品的标题和描述"
• "把商品 12345 的类目和属性改成推荐结果"
• "检查这个 TikTok 商品能不能发布"
• "把 US 站点这个商品的 SKU 重量补齐"
• "给这个商品设置店铺维度信息"
• "这个商品为什么发布不了，帮我诊断"

适用范围

此技能用于：

• 查询 TikTok 采集箱列表和详情。
• 在发布前编辑商品字段。
• 诊断缺失的类目、属性、SKU、价格、库存、重量、包裹尺寸、仓库和合规字段。
• 应用来自 miaoshou-erp-tiktok-category-recommend 的已确认类目推荐。
• 为 miaoshou-erp-tiktok-product-publish 准备商品。

不要使用此技能执行最终发布。发布属于 miaoshou-erp-tiktok-product-publish 的职责。

安全分级

核心安全规则

• 未经用户明确确认，不得保存任何AI生成的标题、描述、类目或属性。
• 不得编造合规值、认证信息、制造商、责任人、仓库或受监管的产品数据。
• 保留未有意修改的现有字段。
• 不得提交可能擦除现有数据的部分载荷。
• 保存前验证必填字段。
• 编辑失败时停止；保存失败后不得继续发布。
• 不得要求用户在对话中粘贴密钥。

店铺模式与站点模式

重要区别：

• collectBoxDetailShopList 存在于站点模式中，存储店铺专属的覆盖数据。
• 除非用户明确要求修改店铺级差异，否则不要覆盖店铺专属配置。
• 若用户有多个店铺，优先使用站点模式编辑共享基础数据，使用店铺模式处理单店铺例外。

API 鉴权（必需）

调用妙手ERP开放平台 API 前，请确保客户已授权通过审核的开放平台应用。

1. 请客户登录妙手ERP，打开「开放平台」，创建应用，提交审核，审核通过后方可使用。
2. 获取应用凭证：AppKey 和 AppSecret。客户可通过本地配置或安全主机连接器提供。不要要求客户在对话中直接粘贴 AppSecret。
3. 通过以下方式之一配置凭证：
   • 将 resources/config.json.example 复制为 resources/config.json 并填写 app_key 和 app_secret。
   • 或设置环境变量 MIAOSHOU_APP_KEY 和 MIAOSHOU_APP_SECRET。可选：设置 MIAOSHOU_BASE_URL，否则使用 https://openapi-erp.91miaoshou.com。
4. 若客户已开启账号级 IP 白名单，确认运行此技能的机器或主机在该白名单中。白名单由同一妙手账号下所有应用共享。
5. 每个 API 请求必须为 POST 方法，包含 Content-Type: application/json 和签名请求头：x-app-key、x-timestamp、x-sign。

开放平台快速入门中的签名规则：

base_url = https://openapi-erp.91miaoshou.com
sign = HmacSHA256(appSecret, appSecret + path + timestamp + appKey + bodyJson + appSecret)

重要细节：

• path 仅为 API 路径，例如 /open/v1/order/create。签名内容中不要包含域名或查询字符串。
• timestamp 为秒级 Unix 时间戳。请求在 300 秒时钟偏移后过期。
• bodyJson 必须是 POST 请求体中实际发送的 JSON 字符串；仅在无请求体时使用空字符串。
• x-sign 为小写十六进制 HmacSHA256 输出。
• 切勿在最终回复或日志中打印 AppSecret、签名请求头或包含凭证的完整请求。

若鉴权失败，请明确处理以下快速入门错误码：signMissing 表示缺少请求头，signExpired 表示本地时钟或秒级时间戳问题，signInvalid 表示签名/请求体/路径/密钥不匹配，appNotFound 表示 App Key 错误、被禁用或未通过审核，appNoPermission 表示应用缺少接口权限，ipNotInWhitelist 表示调用方 IP 不被允许。

标准工作流

1. 确定 detailId、mode、site 和 shop IDs。
2. 查询当前商品详情。
3. 诊断缺失或无效的字段。
4. 若类目或属性缺失，使用 miaoshou-erp-tiktok-category-recommend 获取推荐。
5. 构建修改计划，包含：
   • 当前值。
   • 建议值。
   • 受影响的模式和店铺。
   • 必填字段验证状态。
   • 风险和有意保留不变的字段。
6. 请求明确确认。
7. 确认后保存。
8. 重新查询或报告保存结果。
9. 告知用户商品是否已准备好发布。

发布就绪检查清单

在判断商品可发布前，检查以下项：

• 商品已有目标店铺数据或已认领到目标店铺。
• 类目是目标站点的有效叶子类目。
• 必填商品属性已填写。
• 必填销售属性已填写。
• SKU 值有效。
• 价格和库存有效。
• 所有启用 SKU 的重量大于 0。
• 需要时包裹尺寸已填写。
• 需要时已选择仓库。
• 元数据要求时，制造商、认证、责任人或其他合规字段已填写。

确认模板

请确认 TikTok 采集箱修改计划：
- 商品ID：12345
- 模式：site
- 站点/店铺：US / 1001
- 修改字段：title, category, required attributes
- 不修改字段：price, stock, images, SKU, warehouse
- 风险检查：必填属性已填，SKU weight > 0，库存未超限

确认后才会保存。请回复"确认保存"或"取消"。

场景处理

CLI 命令行工具

若内置脚本可用：

python {base_dir}/scripts/tiktok_collectbox.py list --page 1 --size 20
python {base_dir}/scripts/tiktok_collectbox.py detail --detail-id 12345 --mode site --site US --shop-ids 1001
python {base_dir}/scripts/tiktok_collectbox.py save --detail-id 12345 --mode site --site US --shop-ids 1001 --payload payload.json
python {base_dir}/scripts/tiktok_collectbox.py --help

若脚本不可用，通过主机 HTTP 客户端或连接器调用文档中记录的接口。

API 参考

详细的请求载荷、字段定义、模式行为和接口名称见 references/api-spec.md。在执行保存操作或复杂字段编辑前请先加载该文件。

失败处理

• 必填字段缺失：报告字段并推荐下一步操作。
• 元数据不匹配：重新查询类目元数据，避免保存过期的属性值。
• 保存失败：展示上游错误信息，不执行发布。
• 部分店铺更新问题：在响应中区分站点级和店铺级数据。
• 签名/鉴权错误：检查本地配置或连接器；不暴露密钥。

相关技能

配置

使用 resources/config.json.example 作为本地配置模板。不要分发真实的 resources/config.json。

脚本使用说明

• 脚本名: tiktok_collectbox.py
• site 模式必须传 --site，shop 模式必须传 --shop-id
• 需要明确指定 --mode site 或 --mode shop，不能省略 --mode

LLM 常见错误：

• 常用命令:
  • tiktok_collectbox.py detail <id> --mode site --site <site>
  • tiktok_collectbox.py diagnose <id> --mode site --site <site>

正确调用示例：

tiktok_collectbox.py detail 3134788019 --mode site --site MX
tiktok_collectbox.py diagnose 3134788019 --mode site --site MX