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
关键要点:
- 参数按键名字母排序
- 拼接格式:
secret + param_str + secret - 使用 HMAC-MD5
- 结果转大写
- 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 频率超限
原因: 调用频率过高 解决: 添加限流控制,使用重试机制等待
合规要求
- 禁止逆向H5 API - 违反服务条款
- 控制调用频率 - 避免被限流
- 使用官方SDK - 避免签名问题
- 做好错误处理 - 特别是限流错误
交付物
返回结构化的 JSON 输出:
{
"success": true,
"data": [...],
"count": 10,
"timestamp": "2026-03-28T12:00:00Z"
}
本 Skill 适用于淘宝桌面客户端开发场景