skills/swads-daily-report/README.md

SW Ads Daily Report

手动调用的 Codex skill，用 SW Ads MCP 读取当前广告账户，生成每日投放分析、Wise 风格 HTML 和一张可直接分享的 PNG 长图。

报告内容

• 账户整体状态：Spend、CTR、CPI、ROI、ROAS。
• 异常 Campaign 与相对优质 Campaign。
• 素材表现、发布账号贡献及归因线索。
• 三条基于数据的优化建议。
• 需要人工确认的预算、状态、ROI 目标和素材操作。

技能只执行查询和本地渲染，不会修改线上投放。

安装

本地需要 Python 3.9 或更高版本。生成 PNG 还需要 Google Chrome 或 Chromium；浏览器不可用时仍可输出 HTML。

在本仓库根目录执行：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/swads-daily-report "${CODEX_HOME:-$HOME/.codex}/skills/swads-daily-report"

如果目标目录已经存在，请先备份旧版本，避免两个版本的文件混在一起。安装后重新打开 Codex 会话。

也可以把下面这段话直接发送给 LLM，让它代为安装：

请把当前仓库的 skills/swads-daily-report 安装到
${CODEX_HOME:-$HOME/.codex}/skills/swads-daily-report。
如果存在旧版本，请先备份；安装完成后检查 SW Ads MCP 是否可用，
只验证只读的 swads_whoami，不要修改任何广告账户或投放配置。
如果缺少 swads MCP，请提示我向内部管理员申请 Token，并给出
使用 bearer-token-env-var 的 codex mcp add 安装命令；不要让我在聊天中发送 Token。

SW Ads MCP 依赖

本 Skill 依赖名为 swads 的 SW Ads MCP，服务地址为 https://ads.mincode.cn/mcp。Skill 每次运行都会先检查 MCP 工具与身份；未安装、未连接或鉴权失败时会停止生成报告，并提示用户完成配置，不会伪造投放数据。

首次配置时，先向公司内部管理员申请 SW Ads MCP Token，然后在终端执行：

export SWADS_MCP_TOKEN='<向内部管理员申请的 Token>'
codex mcp add swads \
  --url https://ads.mincode.cn/mcp \
  --bearer-token-env-var SWADS_MCP_TOKEN

请确保 Codex 启动时仍能读取 SWADS_MCP_TOKEN，且不要把 Token 写入本仓库。重新打开 Codex 后，可以发送以下指令验证连接：

使用 swads MCP 调用 swads_whoami，确认当前身份和可见账户；不要执行任何写操作。

连接成功后，在 Codex 中输入：

$swads-daily-report

也可以附加范围：

$swads-daily-report 使用当前账户，生成昨天完整业务日的报告
$swads-daily-report 使用指定账户 123456789，生成 2026-08-01 的报告

输出

默认写入 ~/swads-reports/YYYY-MM-DD/：

report-data.json
swads-daily-report.html
swads-daily-report.png

JSON 是 MCP 数据的归一化快照；HTML 适合浏览和二次编辑；PNG 适合直接发送。字段规范见 references/report-data-schema.md。

安全边界

• 以最近一个完整业务日作为决策依据；当天未完整数据只作为监控提示。
• 缺少分母的 CTR/CPI 显示 N/A，不会解释为真实的零。
• 平台原生归因只作为相关性线索，不宣称增量因果。
• 暂停、恢复、调预算、改 ROI 目标、钉选/移除素材及发布操作必须人工确认。

效果图的数据为脱敏演示数据。复现方式见 examples/README.md。