zach-lingxing-openapi-client

本机直连停用 / 固定出口模式可用：领星 OpenAPI 因 IP 白名单限制，本地环境无法直接访问。 如已部署固定出口网关并将 EIP 加入白名单，可继续使用本 Skill。 未部署前，需要亚马逊经营数据时请优先改用 Amazon SP-API（MCP: amazon-api）。

本公开版 Skill 是自包含的，不依赖任何私有工作区文件、内部协议或团队手册。

领星 OpenAPI 客户端底座

核心功能

1. 统一管理 access_token 获取与续约
2. 按官方规则生成 sign
3. 封装 GET/POST 业务请求
4. 缓存关键官方文档到本地
5. 运行最小烟测，确认 SellerLists -> StoreSales -> Orderlists -> promotionListingList 链路可用
6. 给领星 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.py
• timezone_map.py：兼容入口，实际复用 lib/lingxing_openapi/timezones.py
• sync_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