linkfox-shopee-store-ads
管理已授权 Shopee(虾皮)店铺的站内广告,支持广告账户余额与开关查询、推广商品及关键词推荐、手动商品广告和 GMS 活动创建与编辑,以及 CPC、商品活动和 GMS 效果分析。适用于店铺推广维护、预算与 ROI 参考、广告表现查询;广告授权独立于 ERP 授权,不适用于商品刊登、联盟营销 AMS、自动商品广告或其他平台广告。
How do I install this agent skill?
npx skills add https://github.com/linkfox-ai/linkfox-skills --skill linkfox-shopee-store-adsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is used to manage Shopee store advertisements. It facilitates communication with a central gateway for advertisement balance, keyword recommendations, and campaign management. The skill follows secure practices by managing authentication through environment variables and isolating data storage to a local working directory. No malicious patterns such as data exfiltration to untrusted domains, prompt injection, or suspicious persistence mechanisms were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Shopee 店铺站内广告管理
适用范围
适用
查看和维护已授权 Shopee 店铺的站内广告。用户希望了解广告余额、商品推广、关键词、广告活动、CPC 效果或 ROI 时使用,无需明确提及 Ads。
场景速查
| 用户表达 | 查询场景 |
|---|---|
| 查广告余额和自动充值开关 | 账户状态:展示广告余额与开关。 |
| 哪些商品和关键词适合推广 | 推广准备:展示推荐商品、关键词、预算和 ROI 参考。 |
| 创建或调整手动商品广告 | 广告维护:创建活动或修改设置、关键词。 |
| 看广告每天或每小时的表现 | 效果报表:区分全部 CPC 与指定商品活动。 |
| 检查并维护 GMS 广告 | GMS:查询资格、创建或编辑活动、查看活动及商品效果。 |
边界
店铺授权由 linkfox-shopee-store-auth 处理,商品刊登使用 linkfox-shopee-store-product,联盟营销 AMS(module=127)使用 linkfox-shopee-store-ams;Amazon 广告使用相应 Amazon 广告技能。本站内广告范围不包含自动商品广告。
接口清单
| 接口 | 端点 | 接口文档 | 对应脚本 | 说明 |
|---|---|---|---|---|
检查 GMS 商品广告活动创建资格(check_create_gms_product_campaign_eligibility) | POST /shopee/developerProxy -> GET path:api/v2/ads/check_create_gms_product_campaign_eligibility | references/apis/check-create-gms-product-campaign-eligibility.md | scripts/check_create_gms_product_campaign_eligibility.py | 检查 GMS 商品广告活动创建资格。 |
创建 GMS 商品广告活动(create_gms_product_campaign) | POST /shopee/developerProxy -> POST path:api/v2/ads/create_gms_product_campaign | references/apis/create-gms-product-campaign.md | scripts/create_gms_product_campaign.py | 创建 GMS 商品广告活动。 |
创建手动选品商品广告(create_manual_product_ads) | POST /shopee/developerProxy -> POST path:api/v2/ads/create_manual_product_ads | references/apis/create-manual-product-ads.md | scripts/create_manual_product_ads.py | 创建手动选品商品广告。 |
编辑 GMS 商品活动(edit_gms_item_product_campaign) | POST /shopee/developerProxy -> POST path:api/v2/ads/edit_gms_item_product_campaign | references/apis/edit-gms-item-product-campaign.md | scripts/edit_gms_item_product_campaign.py | 编辑 GMS 商品活动。 |
编辑 GMS 商品广告活动(edit_gms_product_campaign) | POST /shopee/developerProxy -> POST path:api/v2/ads/edit_gms_product_campaign | references/apis/edit-gms-product-campaign.md | scripts/edit_gms_product_campaign.py | 编辑 GMS 商品广告活动。 |
编辑手动商品广告关键词(edit_manual_product_ad_keywords) | POST /shopee/developerProxy -> POST path:api/v2/ads/edit_manual_product_ad_keywords | references/apis/edit-manual-product-ad-keywords.md | scripts/edit_manual_product_ad_keywords.py | 编辑手动商品广告关键词。 |
编辑手动商品广告(edit_manual_product_ads) | POST /shopee/developerProxy -> POST path:api/v2/ads/edit_manual_product_ads | references/apis/edit-manual-product-ads.md | scripts/edit_manual_product_ads.py | 编辑手动商品广告。 |
查询 Ads Facil 计划店铺费率(get_ads_facil_shop_rate) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_ads_facil_shop_rate | references/apis/get-ads-facil-shop-rate.md | scripts/get_ads_facil_shop_rate.py | 查询 Ads Facil 计划店铺费率。 |
查询全部 CPC 广告每日效果(get_all_cpc_ads_daily_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_all_cpc_ads_daily_performance | references/apis/get-all-cpc-ads-daily-performance.md | scripts/get_all_cpc_ads_daily_performance.py | 查询全部 CPC 广告每日效果。 |
查询全部 CPC 广告小时效果(get_all_cpc_ads_hourly_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_all_cpc_ads_hourly_performance | references/apis/get-all-cpc-ads-hourly-performance.md | scripts/get_all_cpc_ads_hourly_performance.py | 查询全部 CPC 广告小时效果。 |
查询新建商品广告预算建议(get_create_product_ad_budget_suggestion) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_create_product_ad_budget_suggestion | references/apis/get-create-product-ad-budget-suggestion.md | scripts/get_create_product_ad_budget_suggestion.py | 查询新建商品广告预算建议。 |
查询 GMS 广告活动效果(get_gms_campaign_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_gms_campaign_performance | references/apis/get-gms-campaign-performance.md | scripts/get_gms_campaign_performance.py | 查询 GMS 广告活动效果。 |
查询 GMS 商品效果(get_gms_item_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_gms_item_performance | references/apis/get-gms-item-performance.md | scripts/get_gms_item_performance.py | 查询 GMS 商品效果。 |
查询商品广告活动每日效果(get_product_campaign_daily_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_campaign_daily_performance | references/apis/get-product-campaign-daily-performance.md | scripts/get_product_campaign_daily_performance.py | 查询商品广告活动每日效果。 |
查询商品广告活动小时效果(get_product_campaign_hourly_performance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_campaign_hourly_performance | references/apis/get-product-campaign-hourly-performance.md | scripts/get_product_campaign_hourly_performance.py | 查询商品广告活动小时效果。 |
查询商品级广告活动 ID 列表(get_product_level_campaign_id_list) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_level_campaign_id_list | references/apis/get-product-level-campaign-id-list.md | scripts/get_product_level_campaign_id_list.py | 查询商品级广告活动 ID 列表。 |
查询商品广告活动设置(get_product_level_campaign_setting_info) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_level_campaign_setting_info | references/apis/get-product-level-campaign-setting-info.md | scripts/get_product_level_campaign_setting_info.py | 查询商品广告活动设置。 |
查询推荐 ROI 目标(get_product_recommended_roi_target) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_recommended_roi_target | references/apis/get-product-recommended-roi-target.md | scripts/get_product_recommended_roi_target.py | 查询推荐 ROI 目标。 |
查询推荐推广商品(get_recommended_item_list) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_recommended_item_list | references/apis/get-recommended-item-list.md | scripts/get_recommended_item_list.py | 查询推荐推广商品。 |
查询推荐广告关键词(get_recommended_keyword_list) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_recommended_keyword_list | references/apis/get-recommended-keyword-list.md | scripts/get_recommended_keyword_list.py | 查询推荐广告关键词。 |
查询自动充值与 Campaign Surge 开关(get_shop_toggle_info) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_shop_toggle_info | references/apis/get-shop-toggle-info.md | scripts/get_shop_toggle_info.py | 查询自动充值与 Campaign Surge 开关。 |
查询广告账户实时余额(get_total_balance) | POST /shopee/developerProxy -> GET path:api/v2/ads/get_total_balance | references/apis/get-total-balance.md | scripts/get_total_balance.py | 查询广告账户实时余额。 |
查询 GMS 用户删除商品列表(list_gms_user_deleted_item) | POST /shopee/developerProxy -> GET path:api/v2/ads/list_gms_user_deleted_item | references/apis/list-gms-user-deleted-item.md | scripts/list_gms_user_deleted_item.py | 查询 GMS 用户删除商品列表。 |
前置条件
先完成广告授权并确定目标店铺:依赖 linkfox-shopee-store-auth;先运行 python scripts/check_auth_dependency.py 检查依赖。不要在本技能内实现授权或令牌逻辑。店铺还须在 Shopee 侧开通广告能力,并非所有站点、店铺均可用。依赖检查、授权识别和接口要求见 references/api.md。
业务执行流程
- 每次任务开头,通过认证技能的
authorized_stores.py检查目标店铺的广告授权。仅有 ERP 记录或历史空值不能视为广告已授权;缺失时使用该技能的authorize_url.py发起广告授权,完成后再执行本技能。用户只需广告时,无需先开通 ERP;授权链接有效期见 接口参考。 - 查余额与推荐:先查询账户余额,再按任务查询推荐商品或关键词。
- 创建手动商品广告:先查询预算建议,准备完整广告资料并创建,再按用户要求查询商品活动每日效果;维护现有活动时查询活动 ID 与设置后,编辑广告或关键词。
- GMS:先检查创建资格,再按任务创建或编辑活动、调整商品活动,查询用户删除的商品或活动及商品效果。
- 效果分析:按用户目标选择全部 CPC、商品活动或 GMS 的报表,明确每日与小时粒度。依据 各接口定义 判断网关、上游与业务结果后展示数据。
执行方式
- 直接调用接口:接口端点、完整参数、响应和错误码见
references/api.md。 - 脚本调用(推荐):
python <脚本路径> '<JSON 参数>' [--inline] [--no-cache]。 - 成本与调用约束:本工具不消耗算力 (限时)。同一会话、同一参数组合默认只调用一次,23 个业务脚本不读取或写入响应缓存。失败或空结果时,不得自动变更参数、翻页或连续试探;需要继续查询时,先说明查询范围与目的。
输出策略
- 始终保存完整响应,目标路径为
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-shopee-store-ads-<接口标识>-<timestamp>.json。<cwd>为脚本运行时的工作目录,<session>优先取环境变量SESSION_ID,用于聚合同一任务的数据。禁止写入/tmp,当前目录不可写时应报错。 - 响应体不超过 8 KB:保存后,将完整 JSON 打印到标准输出。
- 响应体超过 8 KB:保存后,标准输出仅展示摘要,包括顶层字段、响应中的顶层常见计数(如
total、costToken)、最大列表字段的长度和前 3 条样本。 - 添加
--inline可强制全量打印到标准输出,同时仍保存文件。
先通过摘要判断数据是否足够。需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。
执行规则
算力消耗预估
不消耗算力 (限时)。
声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。
解决认证和算力问题
出现以下情况时,按 references/onboarding.md 的指引处理:
- 未配置接口密钥:
LINKFOX_AGENT_API_KEY和LINKFOXAGENT_API_KEY均为空。 - HTTP 状态码为
401或402。 - 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。
约束与建议
- 本技能的缓存行为:23 个业务脚本始终禁用响应缓存;公共调用器仍可能创建空的
.cache目录。同一会话应避免重复请求。运行约定见 references/api.md。 - AD 与 ERP 分离:广告 Token 与 ERP Token 独立,店铺出现在授权列表中不等于已经取得广告授权。凭证和转发约定见 references/api.md。
- 识别产品范围:手动商品广告支持创建、编辑广告和关键词;GMS 支持活动、商品与效果查询。自动商品广告
create_auto_product_ads、edit_auto_product_ads因官方标注即将下线而未纳入。 - 清晰展示结果:注明目标店铺、时间范围与报表粒度,用表格呈现响应实际包含的余额、推荐或效果数据;币种、单位及空值按返回内容说明,不补造缺失指标。
- 区分查询和维护:创建与编辑会改变广告投放;依据用户已明确的目标准备内容,说明实际返回的操作结果。写入防重、错误处理及脚本兼容行为见 references/api.md。
- 核对字段定义:各操作的官方字段说明链接见对应接口文档及脚本,未定义的业务字段须核对后再使用。
使用示例
查看广告账户与推荐
用户:查这家店的广告余额,再看看推荐推广的商品。
检查广告授权后查询余额与推荐商品,展示目标店铺、余额和推荐结果。
创建或维护手动商品广告
用户:按这些推广资料创建广告,之后查看效果。
查询预算建议,按用户资料准备完整广告内容,提交创建并解释返回结果,再按用户指定范围查看商品活动效果。
查看 GMS 与 CPC 效果
用户:查看指定时间内 GMS 和 CPC 广告的表现。
根据用户需要分别查询 GMS 活动或商品效果、全部 CPC 或指定商品活动报表,区分时间粒度及统计范围。
使用反馈
当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。
更多优质、专业的跨境电商技能,请访问 LinkFox Skill。
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/linkfox-ai/linkfox-skills/linkfox-shopee-store-ads">View linkfox-shopee-store-ads on skillZs</a>