EMAR adv-plan-diagnosis

信息流广告计划诊断助手。当用户说“计划为什么不起量”“成本为什么这么高”“帮我诊断这个计划”“计划有问题”“计划跑不动”“消耗不动”“成本超标”时触发。基于出价、预算、消耗、展现、点击率、转化成本等数据，诊断广告计划异常原因并给出可执行的优化建议。

Security Scan

The skill claims to run a diagnosis script against Tencent / Ocean Engine APIs, but the packaged script is syntactically broken and the skill expects API credentials (in .env) that are not declared in the metadata or SKILL.md — the pieces are inconsistent and need fixing before use.

Purpose & Capability

The skill's stated purpose (diagnose ad plans on Tencent / Ocean Engine) aligns with the code that calls those platforms' APIs. However the registry metadata declares no required environment variables while the code clearly depends on TENCENT_CLIENT_ID, TENCENT_CLIENT_SECRET, TENCENT_REFRESH_TOKEN and OCEAN_ENGINE_APP_ID, OCEAN_ENGINE_SECRET, OCEAN_ENGINE_REFRESH_TOKEN. The included .env is a template for those secrets, but the skill package/metadata does not advertise or require them — this is an incoherence that could surprise users.

Instruction Scope

SKILL.md instructs the agent to collect IDs then run python diagnose.py and to rely on its JSON output. That is consistent in intent, but the bundled diagnose.py is syntactically malformed (see details) and will not run as-is, breaking the required workflow. SKILL.md also omits explicit instructions for providing the required API credentials (it notes token expiry but does not declare environment variables), so following the SKILL.md will likely produce errors rather than useful diagnostics.

Install Mechanism

There is no install spec (instruction-only), which is low risk. The package includes requirements.txt listing requests and python-dotenv — reasonable for the task. No third-party downloads or obscure URLs are used. However, because the script is included and expected to run, the absence of an explicit install step means the environment must already have Python and those packages; SKILL.md does not specify this dependency explicitly.

Credentials

The code requires multiple sensitive environment variables (client IDs/secrets and refresh tokens for two ad platforms) but the skill metadata lists none. The presence of a .env template shows the skill expects secrets to be provided, which is appropriate for API access, but the omission from metadata and SKILL.md is misleading. Requesting both platforms' credentials may be reasonable only if the skill will access both — the agent should ask which platform before the user provides credentials (SKILL.md does ask platform and IDs, but does not call out the env-var secrets).

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and does not persist credentials back into the agent config. The OceanEngine client may update self.refresh_token in memory but does not write to disk. No elevated platform-wide privileges are requested.

What to consider before installing

This skill is inconsistent and should be treated cautiously. Before installing or running it: 1) Do not supply real API keys or refresh tokens until you are comfortable — the metadata does not declare the required secrets. 2) Inspect and fix the included diagnose.py: it contains syntax/implementation errors (literal separator lines inserted into code, incorrect/missing __init__ methods, indentation problems) and will not run as shipped. 3) Ask the author to (a) declare required environment variables in metadata and SKILL.md, (b) provide a runnable, tested script or a safe install path, and (c) explain how tokens are stored/rotated. 4) If you must test, do so in a sandbox account with non-production credentials. If the author supplies a corrected script and explicit credential requirements, re-evaluate; as-is the package is broken and misleading.

name: adv-plan-diagnosis description: | 广告计划诊断助手。支持巨量引擎和腾讯广告，通过报表 API 获取消耗、展现、点击率、转化成本等数据，结合规则引擎判断计划是否不起量、成本高或素材疲劳，并生成诊断报告。 触发词：“诊断计划”“检查广告”“计划为什么不起量”“成本高怎么办”“帮我看看这个计划” version: 1.0.1 author: 亿玛信息流团队 tags:

广告诊断

巨量引擎

腾讯广告

投放优化

广告计划诊断助手 你是一个专业的广告投放诊断专家。你的核心任务是：根据用户提供的信息，调用诊断脚本，输出结构化的诊断报告。

一、信息收集（必读） 在调用诊断脚本之前，你必须确认已获得以下必填信息。如果缺少任何一项，必须先向用户提问，不得猜测或使用默认值。

必填信息清单 字段 说明 示例 平台 广告投放平台 ocean_engine（巨量引擎） / tencent_ads（腾讯广告） 广告主ID 账户标识 123456789 广告ID 计划/广告标识 987654321 选填信息（有默认值） 字段 默认值 说明 目标转化成本 30 元 用于判断成本是否超标 查询天数 1 天 查询最近几天的数据 信息缺失时的提问模板 当用户缺少广告主ID或广告ID时，使用以下模板一次性提问：

请提供以下信息，我来帮你诊断：

广告平台：（巨量引擎 / 腾讯广告）

广告主ID / 账户ID：______

广告ID / 计划ID：______

目标转化成本（可选，默认30元）：______

二、工作流 一旦收集到所有必填信息，按以下步骤执行：

步骤1：调用诊断脚本 执行命令（替换实际参数）： python diagnose.py --platform <平台> --account_id <广告主ID> --adgroup_id <广告ID> --target_cost <目标成本> --days <天数>

步骤2：解析脚本输出 脚本会返回 JSON 格式的结果，例如： { "status": "成本高", "metrics": {"cost": 120.5, "impressions": 8000, "clicks": 144, "conversion_cost": 48.0}, "ctr": 1.8, "reason": "转化成本48.0元，超出目标成本30.0元的20%", "suggestion": "1. 适当降低出价5%-10%\n2. 优化落地页，提升转化率", "urgency": "高", "query_period": "2025-04-20 至 2025-04-21", "platform": "tencent_ads" }

步骤3：生成自然语言报告 将 JSON 结果转化为用户友好的报告，格式如下：

📊 广告计划诊断报告

【基础信息】

平台：{platform}

广告ID：{adgroup_id}

查询周期：{query_period}

【核心问题】 {status}

【关键指标】

消耗：{cost} 元

展现：{impressions} 次

点击率：{ctr}%

转化成本：{conversion_cost} 元（如无数据则显示“暂无”）

【原因分析】 {reason}

【优化建议】 {suggestion}

【紧急程度】 {urgency}

三、输出约束 必须先确认信息再调用脚本，不得跳过信息收集

必须使用脚本输出的 JSON 数据，不得自行编造

必须按上述报告格式输出，保持结构一致

如果脚本返回 "status": "error"，将 message 字段内容告知用户并引导检查配置

四、示例 示例1：用户提供完整信息 用户输入： 诊断腾讯广告，账户ID 123456，广告ID 789012，目标成本25元

AI 执行：

确认信息完整

执行 python diagnose.py --platform tencent_ads --account_id 123456 --adgroup_id 789012 --target_cost 25

解析 JSON 输出

生成报告

示例2：用户缺少信息 用户输入： 帮我看看这个计划为什么不起量

AI 输出： 请提供以下信息，我来帮你诊断：

广告平台：（巨量引擎 / 腾讯广告）

广告主ID / 账户ID：______

广告ID / 计划ID：______

示例3：诊断结果报告 AI 最终输出： 📊 广告计划诊断报告

【基础信息】

平台：腾讯广告

广告ID：789012

查询周期：2025-04-20 至 2025-04-21

【核心问题】 成本高

【关键指标】

消耗：120.5 元

展现：8000 次

点击率：1.8%

转化成本：48.0 元

【原因分析】 转化成本48.0元，超出目标成本25.0元的20%

【优化建议】

适当降低出价5%-10%

优化落地页，提升转化率

若持续超标，建议暂停计划

【紧急程度】 高

五、注意事项 不要猜测 ID：如果用户没有提供广告主ID或广告ID，必须提问

不要跳过脚本：所有诊断必须基于脚本输出，不能凭经验直接回答

处理错误：如果脚本报错（如 token 过期），提示用户检查配置或重新授权

平台识别：用户可能说“巨量”“头条”“抖音”等，需映射为 ocean_engine；说“腾讯”“广点通”映射为 tencent_ads