优惠折扣购物（淘宝联盟 / 淘宝客 · 官方为主）
Overview
帮用户在淘宝/天猫生态里"搜商品 → 找优惠券 → 生成淘口令 → 引导下单"的优惠折扣导购技能。
底层数据来自 scripts/alimama_api.py，默认走 官方淘宝客（淘宝开放平台 TOP 网关）；
另保留 折淘客第三方 作为 27939 长期未批时的可选后备（非默认）。
| provider | 数据源 | 关键词搜索 | 淘口令 | 详情/转链 | 说明 |
|---|---|---|---|---|---|
official（默认） |
淘宝开放平台 TOP 网关 | ✅ 已通（27939 已获得，用升级版接口） | ✅ 已通 | ✅ 已通 | 正规淘宝客，闭环靠转链/淘口令 |
zhetaoke（后备） |
折淘客第三方 | ✅ 注册即有（仅 appkey） | ✅ 需 sid | ✅ 需 sid+pid | 仅当 official 不可用时的可选后备 |
> 推荐用 official：这是你要的"淘宝客官方方式"，最规范、数据最全。关键词搜索、淘口令、选品库、商品详情均已验证可用。
> 注意：27939 包授权的是升级版接口（material.optional.upgrade / material.recommend），脚本已自动使用；若你看到旧名 material.optional 会报 scope 11，属正常。
本技能不内置任何凭证，必须由使用方提供自己的阿里妈妈凭证。
When to use
- 用户要"在淘宝/天猫搜某个商品""比价""找优惠券""有没有便宜的"
- 用户要"生成淘口令/推广链接""做返利/佣金"
- 用户提到"淘宝""天猫""阿里妈妈""淘宝联盟""淘宝客""选品""优惠折扣""省钱"
Quick Start：官方凭证配置
配置文件：~/.workbuddy/skills/alimama-shopping/config.json
{
"provider": "official",
"official": { "app_key": "你的appkey", "app_secret": "你的appsecret", "adzone_id": "mm_xxx_xxx_xxx" }
}
app_key/app_secret：阿里妈妈开放平台「应用管理」里创建应用后获得。adzone_id：推广位 PID 的末段数字，也可直接填完整 PID（mm_123_456_789会自动取 789）。- 也可用环境变量覆盖：
ALIMAMA_PROVIDER、ALIMAMA_APP_KEY、ALIMAMA_APP_SECRET、ALIMAMA_ADZONE_ID。
获取官方凭证（详见 references/api_docs.md 第 0~1 节）：
1. 登录 https://pub.alimama.com 完成实名 + 媒体备案。
2. 开放平台 → 应用管理 → 创建应用，类目选「联盟合作」，先点「申请资质」再创建 → 拿到 AppKey/AppSecret。
3. 推广管理 → 推广位管理 → 新建推广位 → 拿到 PID。
4. 申请 API 权限：勾选「物料信息查询 16189」「淘口令生成 11655」「商品物料获取 27939」（均已获得）。
Capabilities（能力）
> 以下命令默认 provider=official，全部已验证可用。
1. 搜商品 + 找优惠/比价（关键词搜索，27939 已获得）
python <skill_dir>/scripts/alimama_api.py --action search --q "无线耳机" --page-size 20 --sort price_asc
# 只看有券：加 --has-coupon；只看天猫：加 --tmall
返回每条含 title、zk_final_price、reserve_price、coupon_amount、commission_rate、volume、item_url、is_tmall 等。向用户突出券后价、券面额、销量。
2. 生成淘口令（分享/返利闭环，已通）
先 search/item-info 拿到商品 url，再 tpwd 生成可分享口令：
python <skill_dir>/scripts/alimama_api.py --action tpwd --text "好物推荐" --url "https://uland.taobao.com/..."
password（形如 ￥xxxx￥）即用户复制去淘宝 App 打开下单的口令；返回同时带 url 字段（生成口令用的源链接），务必一并展示。
3. 商品详情（已通）
python <skill_dir>/scripts/alimama_api.py --action item-info --num-iids 123456
4. 订单 / 返利（需 27939 + 用户 session）
python <skill_dir>/scripts/alimama_api.py --action order --start-time "2026-08-01 00:00:00" --end-time "2026-08-15 00:00:00"
需 ALIMAMA_SESSION（用户 OAuth 授权），详见 references/api_docs.md。
Workflow（优惠折扣导购串联）
- 用户给关键词/品类 →
search找商品与券。 - 用
--sort price_asc或--has-coupon帮用户筛出最便宜/最值得的。 - 对目标商品
tpwd生成淘口令，发给用户 → 用户去淘宝 App 打开下单，佣金走联盟结算。 - （可选）核对收益：
order拉取返利。
输出规范（强制）：每条结果必须带「可点击直达链接」
本技能的核心目标是让用户直接点链接就能跳淘宝下单，口令只是备选（手机淘宝里粘贴用）。因此向用户呈现时，禁止只给淘口令：
-
search / material 结果：每条商品必须同时给出
- 直达链接：取归一化字段click_url（即s.click.taobao.com/...联盟推广链接，已补https:），以可点击 URL 形式展示；
- 券后价、券面额、销量等要点；
- （可选）淘口令password。
>item_url与click_url等价，click_url优先；二者都是可直接点击跳转的联盟链接。 -
tpwd 结果：返回
{"password": "￥...￥", "url": "https://s.click..."}，口令与 url 一起展示，不要只贴口令。 -
推荐以表格呈现（商品 / 券后价 / 看点 / 淘口令 / 直达链接 五列），链接做成可点击 URL，用户点一下即可跳转。
Notes
- 所有脚本输出均为 JSON（stdout），便于解析后向用户呈现；错误以退出码 1 + stderr 返回。
- 淘宝客没有"代用户直接下单"的 API，本技能通过"淘口令/链接引导用户自行下单 + 联盟结算"实现购物闭环。
- 搜索依赖「商品物料获取 27939」权限（已获得）：淘宝客官方关键词搜索用的是升级版接口
taobao.tbk.dg.material.optional.upgrade（选品库用taobao.tbk.dg.material.recommend），二者均属 27939 包授权。旧的material.optional/optimus.material不在授权范围内（调用会 scope 11）。脚本已自动使用正确的升级版方法名与嵌套返回结构的归一化。 - 凭证属私密信息，明文存于
config.json，切勿提交 git 或外发。 - 签名算法、字段含义、权限申请理由模板见
references/api_docs.md。
后备：折淘客（仅在 27939 长期未批时启用，非推荐）
若你不想等官方 27939、想立刻拿到关键词搜索，可临时切换：
1. 注册 https://www.zhetaoke.com → 右上角「对接秘钥」查看 appkey。
2. 后台「新增授权」绑定淘宝联盟账号 → 拿 sid；淘宝联盟后台建推广位 → 拿 PID。
3. 在 config.json 把 provider 改为 "zhetaoke" 并填 zhetaoke.appkey/sid/pid。
4. 端点与返回结构见 references/api_docs.md 第 7 节。
