--- 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 签名算法 ```python 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分钟内有效 ### 参数校验 ```javascript 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秒后重试 | ### 重试机制 ```javascript 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; } ``` ### 日志规范 ```javascript 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)); } ``` ## 数据结构 ### 商品数据 ```typescript interface Product { item_id: string; title: string; pict_url: string; reserve_price: string; zk_final_price: string; commission_rate: string; shop_title: string; } ``` ### 订单数据 ```typescript interface Order { tid: number; status: string; buyer_nick: string; payment: string; title: string; price: string; num: number; created: string; pay_time: string; } ``` ### 物流数据 ```typescript interface Logistics { tid: number; company_name: string; out_sid: string; status: string; trace: LogisticsTrace[]; } ``` ## 使用示例 ### 初始化 ```javascript const TopClient = require('topapi').TopClient; const client = new TopClient({ appkey: 'your_appkey', appsecret: 'your_appsecret', restUrl: 'http://gw.api.taobao.com/router/rest' }); ``` ### 商品搜索 ```javascript async function searchProducts(keyword) { const result = await client.execute('taobao.item.list.get', { q: keyword, page_no: 1, page_size: 20 }); return result.items; } ``` ### 签名生成 (手动) ```javascript 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(); } ``` ### 订单查询 ```javascript async function getOrder(tid) { return withRetry(() => client.execute('taobao.trade.get', { tid, fields: 'tid,status,payment,created,pay_time' })); } ``` ### 错误处理示例 ```javascript 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 输出: ```json { "success": true, "data": [...], "count": 10, "timestamp": "2026-03-28T12:00:00Z" } ``` --- *本 Skill 适用于淘宝桌面客户端开发场景*