final_SKILL.md 7.65 KB

name: taobao-native description: > 淘宝桌面客户端 - 自动化淘宝购物交互的CLI工具,支持商品搜索、购物车管理、订单处理、旺旺聊天。

使用官方TOP API + blacktail/taobao SDK,遵循合规要求。

Skill: taobao-native 淘宝桌面客户端

概述

本技能提供淘宝购物自动化的完整解决方案,核心能力包括:

  • 商品搜索与信息获取
  • 购物车管理
  • 订单查询与处理
  • 物流跟踪

技术架构

API 选择

优先级 API类型 说明
推荐 TOP API 官方API,支持商品/订单/物流/会员全模块
备选 淘宝客API 门槛低,仅支持推广相关功能
禁用 H5逆向 违反服务条款,存在法律风险

推荐SDK

blacktail/taobao (Node.js) - 109 stars,最流行的Node.js SDK

  • 完整支持TOP API
  • MIT开源协议

模块化架构

src/
├── client.js      # SDK 客户端封装
├── auth.js        # 签名生成与Session管理
├── api/           # API 方法封装
│   ├── item.js    # 商品API
│   ├── trade.js   # 订单API
│   └── logistics.js # 物流API
├── error.js       # 错误处理与重试
└── index.js       # 统一导出

模块职责

模块 职责
client.js 初始化SDK、超时控制
auth.js 签名算法、Token管理
api/* 各业务线API封装
error.js 错误码映射、重试逻辑

认证与签名

TOP API 签名算法

import hmac
import hashlib

def generate_sign(secret, params):
    # 1. 参数按键名字母排序
    sorted_params = sorted(params.items())
    # 2. 拼接: secret + param_str + secret
    sign_str = ''.join([f'{k}{v}' for k, v in sorted_params])
    sign_str = secret + sign_str + secret
    # 3. HMAC-MD5 签名,结果转大写
    sign = hmac.new(secret.encode(), sign_str.encode(), hashlib.md5).hexdigest().upper()
    return sign

关键要点:

  1. 参数按键名字母排序
  2. 拼接格式: secret + param_str + secret
  3. 使用 HMAC-MD5
  4. 结果转大写
  5. timestamp 5分钟内有效

参数校验

function validateParams(params, required) {
  const missing = required.filter(field => !params[field]);
  if (missing.length > 0) {
    throw new Error(`Missing required params: ${missing.join(', ')}`);
  }
  return true;
}

// 使用示例
validateParams({ app_key: 'xxx', method: 'taobao.item.get' }, ['app_key', 'method']);

Session 管理

  • top_session 用于获取用户信息
  • 过期后需要重新授权
  • 建议缓存并定期刷新

API 覆盖

商品API

  • taobao.item.get - 单品查询
  • taobao.item.list.get - 列表查询

订单API

  • taobao.trade.get - 订单详情

物流API

  • taobao.logistics.trace.get - 物流轨迹

会员API

  • taobao.user.get - 用户信息

淘宝客API

  • tbk.item.get - 精选商品
  • tbk.item.convert - 链接转换
  • tbk.order.get - 订单查询
  • tbk.favorites.list.get - 选品库

错误处理

错误码映射

错误码 含义 处理方式
40 权限不足 检查 appKey/Session 授权
41 缺少参数 补充必要参数
50 系统错误 等待后重试
15 查询无结果 检查查询条件
7 频率超限 等待60秒后重试

重试机制

const ERROR_RETRY = {
  50: { strategy: 'exponential', delays: [1000, 2000, 4000, 8000] },
  7:  { strategy: 'fixed', delay: 60000 }
};

async function withRetry(fn, maxRetries = 3) {
  let lastError;
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      const code = error.code || error.sub_code;
      const retry = ERROR_RETRY[code];
      if (!retry) throw error;

      const delay = retry.strategy === 'exponential'
        ? retry.delays[i] || retry.delays[retry.delays.length - 1]
        : retry.delay;

      await sleep(delay);
    }
  }
  throw lastError;
}

日志规范

const LOG_LEVELS = {
  ERROR: { prefix: '[ERROR]', color: 'red' },
  WARN:  { prefix: '[WARN]',  color: 'yellow' },
  INFO:  { prefix: '[INFO]',  color: 'green' },
  DEBUG: { prefix: '[DEBUG]', color: 'gray' }
};

function log(level, message, context = {}) {
  const timestamp = new Date().toISOString();
  const prefix = LOG_LEVELS[level]?.prefix || '[INFO]';
  console.log(`${timestamp} ${prefix} ${message}`, JSON.stringify(context));
}

数据结构

商品数据

interface Product {
  item_id: string;
  title: string;
  pict_url: string;
  reserve_price: string;
  zk_final_price: string;
  commission_rate: string;
  shop_title: string;
}

订单数据

interface Order {
  tid: number;
  status: string;
  buyer_nick: string;
  payment: string;
  title: string;
  price: string;
  num: number;
  created: string;
  pay_time: string;
}

物流数据

interface Logistics {
  tid: number;
  company_name: string;
  out_sid: string;
  status: string;
  trace: LogisticsTrace[];
}

使用示例

初始化

const TopClient = require('topapi').TopClient;

const client = new TopClient({
  appkey: 'your_appkey',
  appsecret: 'your_appsecret',
  restUrl: 'http://gw.api.taobao.com/router/rest'
});

商品搜索

async function searchProducts(keyword) {
  const result = await client.execute('taobao.item.list.get', {
    q: keyword,
    page_no: 1,
    page_size: 20
  });
  return result.items;
}

签名生成 (手动)

function sign(secret, params) {
  const sorted = Object.keys(params).sort();
  const str = secret + sorted.map(k => k + params[k]).join('') + secret;
  return require('crypto').createHmac('md5', secret)
    .update(str).digest('hex').toUpperCase();
}

订单查询

async function getOrder(tid) {
  return withRetry(() => client.execute('taobao.trade.get', {
    tid,
    fields: 'tid,status,payment,created,pay_time'
  }));
}

错误处理示例

try {
  const order = await getOrder('123456789');
  log('INFO', 'Order fetched', { tid: order.tid, status: order.status });
} catch (error) {
  if (error.code === 7) {
    log('WARN', 'Rate limited, will retry');
  } else {
    log('ERROR', 'Failed to fetch order', { error: error.message });
    throw error;
  }
}

参数说明

参数 类型 必填 说明
appkey string 是 淘宝开放平台应用Key
appsecret string 是 淘宝开放平台应用密钥
session string 否 用户授权Session
method string 是 API方法名
timestamp string 是 请求时间戳
format string 否 返回格式 (json/xml)
v string 是 API版本
sign_method string 是 签名方式 (md5/hmac-sha256)

常见问题

Q1: 签名验证失败

原因: 参数未排序、secret 拼接顺序错误 解决: 检查签名算法实现,确保参数按键名排序

Q2: 错误码 15 查询无结果

原因: 查询条件过于严格 解决: 放宽查询条件,检查时间范围

Q3: 错误码 7 频率超限

原因: 调用频率过高 解决: 添加限流控制,使用重试机制等待

合规要求

  1. 禁止逆向H5 API - 违反服务条款
  2. 控制调用频率 - 避免被限流
  3. 使用官方SDK - 避免签名问题
  4. 做好错误处理 - 特别是限流错误

交付物

返回结构化的 JSON 输出:

{
  "success": true,
  "data": [...],
  "count": 10,
  "timestamp": "2026-03-28T12:00:00Z"
}

本 Skill 适用于淘宝桌面客户端开发场景