| name | zach-lingxing-openapi-client |
| description | 搭建并复用领星 ERP OpenAPI 接入底座，处理 token、sign、店铺/站点映射、文档缓存与基础烟测。
使用时机：准备接入领星接口、编写依赖领星数据的新 skill、或排查领星 OpenAPI 鉴权与请求问题。
触发词：/zach-lingxing-openapi-client
|
| benefits-from | [] |
| user-invocable | true |
| allowed-tools | Read, Glob, Bash, Write, Edit, Grep |
| risk-level | low |
本机直连停用 / 固定出口模式可用：领星 OpenAPI 因 IP 白名单限制，本地环境无法直接访问。
如已部署固定出口网关并将 EIP 加入白名单，可继续使用本 Skill。
未部署前，需要亚马逊经营数据时请优先改用 Amazon SP-API（MCP: amazon-api）。
本公开版 Skill 是自包含的，不依赖任何私有工作区文件、内部协议或团队手册。
领星 OpenAPI 客户端底座
核心功能
- 统一管理
access_token 获取与续约
- 按官方规则生成
sign
- 封装 GET/POST 业务请求
- 缓存关键官方文档到本地
- 运行最小烟测，确认
SellerLists -> StoreSales -> Orderlists -> promotionListingList 链路可用
- 给领星 MCP 和其他 skill 提供共享服务层
环境变量
| 变量名 | 必需 | 说明 |
|---|
LINGXING_APP_ID | 是 | 领星开放接口 App ID |
LINGXING_APP_SECRET | 是 | 领星开放接口 App Secret |
LINGXING_TOKEN_CACHE_FILE | 否 | token 缓存文件路径，默认 runtime/lingxing/token_cache.json |
LINGXING_DOC_ACCESS_KEY | 否 | 文档同步时使用的文档密钥 |
Script Directory
脚本位于 skills/zach-lingxing-openapi-client/scripts/：
lingxing_client.py：兼容入口，实际复用 lib/lingxing_openapi/client.pytimezone_map.py：兼容入口，实际复用 lib/lingxing_openapi/timezones.pysync_docs.py：从官方 _sidebar.md 自动发现并同步 Amazon 相关只读文档到 references/openapi_docs/smoke_check.py：最小链路烟测
共享代码位于 lib/lingxing_openapi/：
client.py：鉴权、续约、签名、统一请求封装services.py：店铺、销量、订单、促销等业务型封装promotions.py：促销标签与窗口归一化errors.py：统一错误与提示mcp.py：MCP 工具注册、stdio/HTTP 传输层
本地文档缓存
同步命令：
python3 skills/zach-lingxing-openapi-client/scripts/sync_docs.py
同步结果会写入：
skills/zach-lingxing-openapi-client/references/openapi_docs/
会保留现有 12 页兼容文件名，并自动扩展更多 Amazon 相关只读页面。兼容页包括：
- GetToken
- RefreshToken
- SellerLists
- AllMarketplace
- StoreSales
- AsinDailyLists
- Orderlists
- promotionListingList
- promotionalActivitiesSecKillList
- promotionalActivitiesManageList
- promotionalActivitiesVipDiscountList
- promotionalActivitiesCouponList
使用方法
场景 1：给其他 skill 复用
直接在 Python 脚本中导入：
from lib.lingxing_openapi import LingxingOpenAPIClient, LingxingOpenAPIService
场景 2：同步本地文档
export LINGXING_DOC_ACCESS_KEY="你的文档密钥"
python3 skills/zach-lingxing-openapi-client/scripts/sync_docs.py
场景 3：烟测
export LINGXING_APP_ID="ak_xxx"
export LINGXING_APP_SECRET="xxx"
python3 skills/zach-lingxing-openapi-client/scripts/smoke_check.py
公共规则
- 所有业务接口使用
https://openapi.lingxing.com
- 所有业务接口都要带
access_token / app_key / timestamp / sign
sign 生成规则严格按官方说明：
- 所有业务参数 + 3 个公共参数一起参与签名
- ASCII 排序
- 空字符串不参与，
null 参与
- 拼接后先做
MD5(32位大写)
- 再用
appId 做 AES/ECB/PKCS5PADDING
- 最终作为 Query 参数传输时 URL encode
输出
- 本地 references 文档缓存
- token 缓存文件
- 烟测 JSON 输出
依赖环境
- Python 3.11+
- 系统自带
openssl
风险与边界
- risk-level: low — 只做接口接入和鉴权配置，不写入业务数据
上游 / 下游
- 上游：无（基础底座 Skill，需要配置环境变量）
- 下游：
zach-lingxing-mcp（MCP 服务层）以及其他依赖领星数据的脚本或 Skill
完成后
报告完成状态：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
