93 lines
3.4 KiB
Markdown
93 lines
3.4 KiB
Markdown
# 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。
|
||
|
||
在本仓库根目录执行：
|
||
|
||
```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)。
|