# SW Ads Daily Report

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

![效果示意图](examples/swads-daily-report-preview.png)

## 报告内容

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

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

## 安装

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

在本仓库根目录执行：

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

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

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

```text
请把当前仓库的 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，然后在终端执行：

```bash
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 后，可以发送以下指令验证连接：

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

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

```text
$swads-daily-report
```

也可以附加范围：

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

## 输出

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

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

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

## 安全边界

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

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