zach22-1999 本机直连停用 / 固定出口模式可用：领星 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