@optima-chat/optima-agent 0.8.93 → 0.8.95

package/.claude/skills/ads/SKILL.md

@@ -1,285 +1,244 @@
 ---
 name: ads
-description: Google Ads campaign management. Create campaigns, ad groups, keywords, and ads. View performance metrics. Use when user needs to run ads (投放广告/打广告), manage Google Ads (广告系列/广告组), or analyze ad performance (广告效果/点击率/转化).
+description: |
+  Managed multi-channel ads. Only load when user explicitly asks to run paid ads
+  (e.g. "帮我投广告", "launch a campaign", "推广这款商品", "加广告预算", "查看广告效果",
+  "ads launch", "优化广告", "生成广告报告"). Do NOT load for general marketing
+  questions or organic growth — those go to the `growth` skill.
 ---
 
-# Google Ads CLI - 广告投放管理
+# Ads 托管广告投放
 
-CLI 命令: `google-ads`（或 `ads`）
+AI 广告官:通过 `~/ads/` 工作目录持续运营用户的付费广告投放。
 
-## 首次使用
+## 核心:`~/ads/` 工作目录
 
-```bash
-# 检查用户是否已授权 Google Ads 账号
-google-ads account check
-```
-
-**返回状态及处理**：
-| 状态 | 含义 | 处理方式 |
-|------|------|----------|
-| `active` | 已连接，可访问 | 继续操作 |
-| `pending` | 邀请已发送，等待接受 | 告知用户去 Google Ads 后台接受邀请 |
-| `refused` | 用户拒绝了邀请 | 输出：`[重新关联 Google Ads 账号](action://link-google-ads-account)` |
-| `canceled` | 邀请已取消 | 输出：`[关联 Google Ads 账号](action://link-google-ads-account)` |
-| `not_linked` | 未关联 | 输出：`[关联 Google Ads 账号](action://link-google-ads-account)` |
-
-## 典型场景
-
-### 场景1：从零开始投放广告
-
-**用户说**："我想投放 Google 广告推广我的产品"
-
-**流程**: 创建广告系列 → 创建广告组 → 添加关键词 → 创建广告 → 启用
-
-```bash
-# 1. 创建广告系列（每日预算 $50，默认 PAUSED）
-google-ads campaign create -n "产品推广" -b 50
-
-# 2. 创建广告组（CPC 出价 $2）
-google-ads ad-group create --campaign-id <campaign-id> -n "核心关键词组" --cpc-bid 2
-
-# 3. 添加关键词
-google-ads keyword add --ad-group-id <ad-group-id> -k "产品名称,品牌词,行业词"
-
-# 4. 创建广告
-google-ads ad create \
-  --ad-group-id <ad-group-id> \
-  --headlines "优质产品,限时优惠,免费配送" \
-  --descriptions "高品质产品限时优惠中,立即下单享受专属折扣" \
-  --final-url "https://shop.example.com"
-
-# 5. 确认无误后启用
-google-ads campaign update --campaign-id <campaign-id> --status ENABLED
-```
+所有操作基于用户 workspace 的 `~/ads/`,两层结构:
 
-### 场景2：查看广告效果
-
-**用户说**："看看我的广告效果怎么样"
-
-```bash
-# 快速查看所有广告系列状态
-google-ads campaign list
-
-# 查看详细效果数据（GAQL 查询）
-google-ads query -q "
-  SELECT
-    campaign.name,
-    metrics.impressions,
-    metrics.clicks,
-    metrics.ctr,
-    metrics.average_cpc,
-    metrics.cost_micros,
-    metrics.conversions
-  FROM campaign
-  WHERE segments.date DURING LAST_7_DAYS
-  ORDER BY metrics.cost_micros DESC
-"
-```
-
-### 场景3：暂停/启用广告
-
-**用户说**："暂停那个效果不好的广告系列"
+- **用户级根目录**: 跨 campaign 的整体策略和经验
+- **`campaigns/<slug>/` 子目录**: 每个 campaign 的专属文件
 
-```bash
-# 先查看列表确认 ID
-google-ads campaign list
-
-# 暂停广告系列
-google-ads campaign update --campaign-id <id> --status PAUSED
-
-# 重新启用
-google-ads campaign update --campaign-id <id> --status ENABLED
 ```
-
-### 场景4：调整预算和出价
-
-**用户说**："把预算提高到 100 美元"
-
-```bash
-# 更新广告系列预算
-google-ads campaign update --campaign-id <id> --budget 100
-
-# 更新广告组 CPC 出价
-google-ads ad-group update --ad-group-id <id> --cpc-bid 3
+~/ads/
+├── ADS.md              用户级整体策略
+├── LEARNINGS.md        跨 campaign 经验沉淀
+├── PROGRESS.md         全局工作日志 (每段标 campaign tag)
+├── REPORTS/            用户级周报/月报
+├── assets/             跨 campaign 共享素材 (.gitignore)
+├── campaigns/
+│   └── <slug>/
+│       ├── STRATEGY.md     campaign 专属策略
+│       ├── CREATIVES.md    campaign 变体表
+│       └── NOTES.md        campaign 运行观察
+└── .git/
 ```
 
-### 场景5：添加新关键词
-
-**用户说**："给广告添加一些新关键词"
-
-```bash
-# 先确认广告组 ID
-google-ads ad-group list
-
-# 添加关键词（默认广泛匹配）
-google-ads keyword add --ad-group-id <id> -k "新关键词1,新关键词2"
+## 启动 SOP(每次会话)
+
+1. `ls ~/ads/ADS.md` — 不存在 → 进入"初始化流程"(见下方)
+2. `cat ~/ads/PROGRESS.md | head -30` — 上次做了什么、异常、下次待办
+3. `git -C ~/ads log --oneline -5` — 最近变更
+4. `ls ~/ads/campaigns/` — 列出本地登记的 campaign
+5. `ads status --json` — 从后端拉事实: 在跑的 campaign 列表 + 7 天花费 + 钱包 + 月度 cap
+   - 如果钱包余额 < 阈值,第一时间告诉用户
+   - 如果月度 cap 使用率 > 80%,同样提示
+   - 如果后端 campaign 和本地目录对不齐,视为需要修复
+6. → 决定本次要做的**一个**动作
+   - 聚焦单 campaign 的 session 优先 `cat ~/ads/campaigns/<name>/*.md` 载入专属上下文
+
+## 初始化流程(第一次会话)
+
+1. Copy the template from this skill's directory: `cp -r $(dirname "$SKILL_PATH")/template/user/ ~/ads/`
+   (The template directory is at the same path as this SKILL.md file, under `template/user/`.)
+2. `cd ~/ads && git init && git add -A && git commit -m "init workspace"`
+3. **对话式引导填 ADS.md**(一次问一个,不要塞 10 个表单):
+   - "我们要推广什么?" → `commerce-cli product list` 列候选商品
+   - "默认目标受众是谁?(地域 / 年龄 / 设备 / 时段)"
+   - "月度总预算上限多少美元?"
+   - "有什么品牌禁忌或必须避开的词吗?"
+   每问完一段就写进 ADS.md,`git commit -m "fill ADS.md: <段落>"`
+4. `ads init --total-monthly-budget <X>` — 后端创建 user_ads 记录 + 确保 Google Ads label 存在 + 查 USD wallet
+5. 把后端返回的 ID 自动填进 ADS.md 的"后端登记"段,`git commit -m "register backend"`
+6. 提示用户:
+   - 钱包余额为 0 → "需要先充值. 说 'topup 100' 可充 $100"
+   - 有余额 → "可以现在 launch 第一个 campaign,或者下次会话再开始"
 
-# 添加精确匹配关键词
-google-ads keyword add --ad-group-id <id> -k "精确词" --match-type EXACT
+**不会自动 launch 任何 campaign.** 第一次 launch 必须由用户明确要求。
+
+## 单会话单任务
+
+每次会话只执行一种动作(launch / optimize / collect / report / budget / pause / diagnose / creative 的其中一个),完成后 commit 并更新 `PROGRESS.md`。出错时可以精准 `git revert`。
+
+**例外**: `collect` 在每个其它动作开头隐式跑(让 LLM 基于新鲜数据推理),不算独立 session 动作。
+
+## 8 个动作
+
+### 1. launch — 启动新 campaign
 
-# 添加词组匹配关键词
-google-ads keyword add --ad-group-id <id> -k "词组匹配" --match-type PHRASE
+**触发**: 用户说"推广 XX"、或 PROGRESS 里标记了下次 launch。
+
+**流程**:
+1. 读 ADS.md 拿整体策略,确认推什么产品、受众、预算
+2. 调 `gen image` 生成多个素材变体到 `~/ads/assets/`
+3. 构造 CampaignSpec JSON(参考下方"CampaignSpec 结构"),写到 `/tmp/spec.json`
+4. `ads launch --spec /tmp/spec.json --reason "..."` — 默认 PAUSED
+5. **必做**: 创建 `~/ads/campaigns/<slug>/` 子目录:
+   ```bash
+   slug=<campaign-slug>
+   mkdir -p ~/ads/campaigns/$slug
+   cp -r $(dirname "$SKILL_PATH")/template/campaign/. ~/ads/campaigns/$slug/
+   ```
+6. 填 `campaigns/<slug>/STRATEGY.md`(从 spec.json 拷贝产品、受众、关键词、日预算、差异化角度,加后端关联 ID)
+7. 填 `campaigns/<slug>/CREATIVES.md`(5 个变体的表格,CTR/CVR 留空)
+8. 检查 compliance_check 通过后 → `ads launch enable <id> --reason "compliance passed"`
+9. 追加到 `PROGRESS.md`(tag: `launch, campaign=<slug>`)
+10. `git -C ~/ads add -A && git -C ~/ads commit -m "launch: <slug>"`
+
+### 2. optimize — 优化一个 campaign
+
+**触发**: sentinel 定时或用户说"优化一下"。
+
+**流程**:
+1. `ads collect` 先拉最新数据(SOP 前置)
+2. 读 `~/ads/campaigns/<slug>/CREATIVES.md` 看变体表现
+3. 读 `~/ads/LEARNINGS.md` 看历史经验
+4. 决定要改什么(一个或多个):
+   - 淘汰低 CTR 素材: `ads optimize pause-creative <id> --reason "..."`
+   - 加新关键词: `ads optimize add-keywords <ad_group_id> --keywords "..." --reason "..."`
+   - 加否定词: `ads optimize add-negatives <ad_group_id> --keywords "..." --reason "..."`
+   - 调出价修正: `ads optimize change-bid-mod <criterion_id> --modifier 1.2 --reason "..."`
+   - 调预算: `ads budget set --campaign <id> --daily <usd> --reason "..."`
+5. 更新 `campaigns/<slug>/CREATIVES.md`(把被淘汰的变体移到"已淘汰"段)
+6. 追加一段到 `campaigns/<slug>/NOTES.md`(观察 + 推理 + 下次验证点)
+7. 如果这个洞察是可泛化的,也追加到 `~/ads/LEARNINGS.md`
+8. 追加到 `PROGRESS.md`
+9. commit
+
+### 3. collect — 拉最新数据
+
+**触发**: 定时(每天)或作为其它动作的前置。
+
+**流程**:
+1. `ads collect --days 7` → 后端从 Google Ads 拉 per-campaign 和 per-creative 的最新数据,返回 JSON
+2. 对返回的每个 `creative_perf` 项,找到对应 `campaigns/<slug>/CREATIVES.md`(通过 `campaign_id` 匹配——每个 `campaigns/<slug>/STRATEGY.md` 的"后端关联"段记录了 `campaign_id`),用新 CTR/CVR/花费重写"在投变体"表
+3. 如果是纯 collect session(不是被其它动作调用),追加一段到 PROGRESS.md 和 commit。
+   如果是嵌入在其它动作里,则跟那个动作的 commit 合并。
+
+### 4. report — 生成周/月报告
+
+**触发**: sentinel 定时或用户问"最近怎么样"。
+
+**流程**:
+1. `ads report --period week`(或 `--period month`)→ 后端返回结构化数据
+2. LLM 结合 `LEARNINGS.md` 和 `ADS.md` 的业务目标,组合出人话 markdown 报告
+3. 写到 `~/ads/REPORTS/2026-W14.md`(周报)或 `~/ads/REPORTS/2026-04.md`(月报)
+4. PROGRESS.md tag 一段 "generated report"
+5. commit
+
+### 5. budget — 调预算 / 钱包
+
+**触发**: 用户说"加预算"、"充钱"。
+
+**场景**:
+- "加到 $20/天" → `ads budget set --campaign <id> --daily 20 --reason "..."`
+- "月度上限改 $500" → `ads budget set --total-monthly 500 --reason "..."`
+- "充 $100" → `ads budget topup 100` → 把返回的 `checkout_url` 作为 markdown 链接输出给用户
+- "看下预算" → `ads budget show`
+
+改完之后相应更新 `ADS.md`(月度 cap 变化)或 `campaigns/<slug>/STRATEGY.md`(campaign 日预算变化),commit。
+
+### 6. pause — 紧急停投
+
+**触发**: 用户说"停掉"、"全停"。
+
+**流程**:
+- "停掉 XX campaign" → `ads pause campaign <id> --reason "..."`
+- "全停" → `ads pause all --reason "..."`
+- "停某个素材" → `ads pause creative <variant_id> --reason "..."`
+- "恢复" → `ads resume ...`(但钱包低余额或月度 cap 超出时会被后端拒)
+
+停掉之后在对应 `campaigns/<slug>/NOTES.md` 记一笔,commit。
+
+### 7. diagnose — 问题排查
+
+**触发**: 用户说"为啥没展示"、"怎么烧钱没单"。
+
+**流程**:
+1. `ads diagnose --scope all`(或 `--campaign <id>` 聚焦某个)
+2. 后端返回 issues 列表,每个带 `cli_hint`
+3. LLM 把问题翻译成人话解释给用户,并建议下一步
+4. 如果用户同意某个建议,执行对应的 `cli_hint`(这变成一个新的 optimize / pause / budget session,原则上 diagnose session 本身不改任何东西)
+5. 更新 `campaigns/<slug>/NOTES.md` 或 `PROGRESS.md`(记录诊断发现和建议,不改其它状态文件)
+6. commit(仅包含文档更新)
+
+### 8. creative — 素材迭代
+
+**触发**: 独立会话,聚焦素材质量。
+
+**流程**:
+1. `ads status --include-creatives` 看现状
+2. 读 `~/ads/campaigns/<slug>/CREATIVES.md` 和 `~/ads/LEARNINGS.md`
+3. 决定要生成什么新变体(几个 prompt、什么风格)
+4. `gen image "<prompt>" -o ~/ads/assets` 多次调用
+5. 写进对应 `campaigns/<slug>/CREATIVES.md`
+6. 如果要把新变体上线到现有 campaign: `ads optimize replace-creative <campaign_id> --new-spec /tmp/v.json --reason "..."`
+7. 如果只是建素材库待用,不上线,也 OK
+8. commit
+
+## CampaignSpec 结构(构造 spec.json 用)
+
+```json
+{
+  "userId": "<CLI 自动从 ~/.optima/token.json 的 JWT 提取, 不需要手动填>",
+  "name": "<slug-name-without-u-prefix>",
+  "objective": "conversions",
+  "productIds": ["12345"],
+  "audience": {
+    "geos": ["US", "CA"],
+    "ageRanges": ["AGE_RANGE_25_34", "AGE_RANGE_35_44"],
+    "genders": ["FEMALE"],
+    "devices": ["MOBILE", "DESKTOP"],
+    "intentSignals": ["夏季连衣裙", "summer dress"],
+    "excludeSignals": ["免费", "free"]
+  },
+  "budget": { "dailyLimitUsd": 10 },
+  "creatives": [
+    {
+      "variantId": "v_abc123",
+      "headlines": ["标题1 最多 30 字", "标题2", "标题3", "标题4", "标题5"],
+      "descriptions": ["描述1 最多 90 字", "描述2"],
+      "imageAssets": ["/home/user/ads/assets/image_abc.png"],
+      "finalUrl": "https://shop.example.com/p/12345"
+    }
+  ]
+}
 ```
 
-### 场景6：设置定向条件
+**Google Ads RSA 要求**: 至少 3 个 headlines(各 ≤30 字符),至少 2 个 descriptions(各 ≤90 字符)。后端会强制校验,违规会 fail compliance 预审。
 
-**用户说**："只投放给美国用户" / "针对年轻人投放"
+## 提交约定
 
-```bash
-# 查看当前定向条件
-google-ads campaign targeting list --campaign-id <id>
+- 每次会话结束必有**一个** commit
+- message: `<action>: <一句话>` 例: `launch: summer-promo`、`optimize: drop low-CTR creative`、`budget: topup $100`
+- PROGRESS.md 更新和动作产物**合并在同一个 commit**
+- 失败时,只更新 PROGRESS.md 记失败原因(其它状态文件不动)
+- `~/ads/.git/` 是本地 only,不推远程
 
-# 添加地理位置定向（美国）
-google-ads campaign targeting add --campaign-id <id> --type location --geo-target 2840
+## 归档
 
-# 添加设备定向（移动端，出价+20%）
-google-ads campaign targeting add --campaign-id <id> --type device --device MOBILE --bid-modifier 1.2
+某 campaign 被删除或生命周期结束时:`mv ~/ads/campaigns/<slug> ~/ads/archive/<slug>`,不要直接删(保留历史给 LEARNINGS 参考)。`ls ~/ads/campaigns/` 永远只反映当前活跃/暂停的 campaign。
 
-# 添加时间定向（周一至周五 9-18 点）
-google-ads campaign targeting add --campaign-id <id> --type schedule --day MONDAY --start-hour 9 --end-hour 18
+## Skill 之间的协作
 
-# 广告组级别：针对 25-34 岁用户出价+30%
-google-ads ad-group targeting add --ad-group-id <id> --type age_range --age-range AGE_RANGE_25_34 --bid-modifier 1.3
+按需加载其它 skill:
+- **`gen`** — image/video/tts 生成
+- **`scout`** / **`shein`** / **`tiktok`** 等 — 竞品研究、关键词发现(在 launch 或 optimize 的策略阶段)
+- **`sentinel`** — 定时调度 collect / optimize / report
+- **`browser`** — API 不支持时的兜底
 
-# 删除定向条件
-google-ads campaign targeting remove --campaign-id <id> --criterion-id <criterion-id>
-```
-
-**注意**：人口统计定向（年龄、性别）在 Campaign 级别只能排除，正向定向需在 Ad-Group 级别设置。
-
-## 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 新建广告投放 | 完整流程（场景1） | 按顺序：系列→组→关键词→广告 |
-| 查看效果 | `campaign list` 或 GAQL | GAQL 获取详细指标 |
-| 暂停/启用 | `campaign update --status` | PAUSED 或 ENABLED |
-| 调整预算 | `campaign update --budget` | 单位美元 |
-| 调整出价 | `ad-group update --cpc-bid` | 单位美元 |
-| 添加关键词 | `keyword add` | 注意匹配类型 |
-| 地理定向 | `campaign targeting add --type location` | geo-target ID |
-| 人群定向 | `ad-group targeting add` | Campaign 级别只能排除 |
-| 删除广告 | `campaign delete` / `ad delete` | 不可恢复，建议先暂停 |
-
-## 自然语言映射
-
-当用户说：
-- "投放广告" / "创建广告" → 引导完整流程（场景1）
-- "广告效果" / "看看数据" → `campaign list` + GAQL
-- "暂停广告" → `campaign update --status PAUSED`
-- "启用广告" → `campaign update --status ENABLED`
-- "调整预算到 XX" → `campaign update --budget XX`
-- "添加关键词 XX" → `keyword add -k "XX"`
-- "只投放美国/中国" → `campaign targeting add --type location`
-- "针对年轻人/男性" → `ad-group targeting add --type age_range/gender`
-- "移动端出价加 20%" → `campaign targeting add --type device --bid-modifier 1.2`
-- "删除广告" → 先确认，再执行删除
-
-## 关键概念
-
-### 广告层级结构
-
-```
-Account（账号）
-└── Campaign（广告系列）- 设置预算
-    └── Ad Group（广告组）- 设置出价
-        ├── Keywords（关键词）- 触发条件
-        └── Ads（广告）- 展示内容
-```
-
-### 状态说明
-
-| 状态 | 含义 |
-|------|------|
-| `ENABLED` | 正常投放中 |
-| `PAUSED` | 已暂停 |
-| `REMOVED` | 已删除 |
-
-### 关键词匹配类型
-
-| 类型 | 说明 |
-|------|------|
-| `BROAD` | 广泛匹配（默认） |
-| `PHRASE` | 词组匹配 |
-| `EXACT` | 精确匹配 |
-
-### RSA 广告要求
-
-- **标题**: 至少 3 个，最多 15 个（每个 ≤30 字符）
-- **描述**: 至少 2 个，最多 4 个（每个 ≤90 字符）
-
-## 常见问题
-
-### 广告创建后没有展示
-
-1. 检查状态是否 PAUSED → 启用它
-2. 账号是否设置账单信息 → 去 Google Ads 后台设置
-3. 关键词是否有搜索量 → 添加更多关键词
-
-### 不知道广告效果好不好
-
-用 GAQL 查询关键指标：
-```bash
-google-ads query -q "
-  SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.ctr, metrics.conversions, metrics.cost_micros
-  FROM campaign WHERE segments.date DURING LAST_7_DAYS
-"
-```
+## 依赖的 CLI
 
-**指标参考**：
-- CTR > 2% = 良好
-- CPC 看行业，一般 $0.5-2
-
-### 关键词出价设多少
-
-- 新广告先设 $1-2，观察效果
-- 效果好提高出价，效果差降低或暂停
-
-## 命令参考
-
-### 账号
-- `google-ads account check` - 检查 Google Ads 账号授权状态
-
-### 广告系列
-- `google-ads campaign list [--status ENABLED|PAUSED]` - 列出
-- `google-ads campaign info <id>` - 详情
-- `google-ads campaign create -n "名称" -b 预算` - 创建
-- `google-ads campaign update --campaign-id <id> [--status|--budget|--name]` - 更新
-- `google-ads campaign delete --campaign-id <id>` - 删除
-- `google-ads campaign targeting list --campaign-id <id>` - 列出定向条件
-- `google-ads campaign targeting add --campaign-id <id> --type <type> [options]` - 添加定向
-- `google-ads campaign targeting remove --campaign-id <id> --criterion-id <id>` - 删除定向
-
-### 广告组
-- `google-ads ad-group list [--campaign-id <id>]` - 列出
-- `google-ads ad-group info <id>` - 详情
-- `google-ads ad-group create --campaign-id <id> -n "名称" [--cpc-bid 出价]` - 创建
-- `google-ads ad-group update --ad-group-id <id> [--status|--cpc-bid|--name]` - 更新
-- `google-ads ad-group delete --ad-group-id <id>` - 删除
-- `google-ads ad-group targeting list --ad-group-id <id>` - 列出定向条件
-- `google-ads ad-group targeting add --ad-group-id <id> --type <type> [options]` - 添加定向
-- `google-ads ad-group targeting remove --ad-group-id <id> --criterion-id <id>` - 删除定向
-
-### 关键词
-- `google-ads keyword list [--campaign-id <id>]` - 列出
-- `google-ads keyword add --ad-group-id <id> -k "词1,词2" [--match-type BROAD|PHRASE|EXACT]` - 添加
-- `google-ads keyword update --ad-group-id <id> --criterion-id <id> --status` - 更新
-- `google-ads keyword delete --ad-group-id <id> --criterion-id <id>` - 删除
-
-### 广告
-- `google-ads ad list [--ad-group-id <id>]` - 列出
-- `google-ads ad info <id>` - 详情
-- `google-ads ad create --ad-group-id <id> --headlines "..." --descriptions "..." --final-url "..."` - 创建
-- `google-ads ad update --ad-group-id <id> --ad-id <id> --status` - 更新
-- `google-ads ad delete --ad-group-id <id> --ad-id <id>` - 删除
-
-### GAQL 查询
-- `google-ads query -q "SELECT ... FROM ..."` - 执行查询
-- `google-ads query -f query.gaql` - 从文件读取
-
-## 重要提示
-
-- **所有命令默认 JSON 输出**
-- **预算和出价单位**：美元
-- **新广告默认 PAUSED**：创建后需手动启用
-- **删除不可恢复**：建议先暂停
+- `ads`(`@optima-chat/ads-cli`)— 本 skill 的核心后端入口
+- `gen`(`@optima-chat/gen-cli`)— 素材生成
+- `commerce-cli`(`@optima-chat/commerce-cli`)— 查商家商品
+- `git`(系统)— workspace 版本管理

package/.claude/skills/ads/template/campaign/CREATIVES.md

@@ -0,0 +1,18 @@
+# Creatives: <name>
+
+## 在投变体
+| 变体ID | 类型 | 标题/描述 | CTR | CVR | 花费 | 状态 |
+|---|---|---|---|---|---|---|
+<!-- ads collect 后由 LLM 回填 CTR/CVR/花费 -->
+
+## 已淘汰变体
+<!-- optimize 淘汰的变体迁到这里, 保留作为反例 -->
+
+## Prompt 记录
+<!-- gen image 用过的 prompt, 方便复现和迭代
+
+示例:
+- v_abc (2026-04-11): "minimalist summer fashion banner, product 12345, 7折促销"
+  → ~/ads/assets/image_abc.png
+
+-->

package/.claude/skills/ads/template/campaign/NOTES.md

@@ -0,0 +1,10 @@
+# Notes: <name>
+> 这个 campaign 的运行观察、临时发现、踩过的坑.
+> 泛化到跨 campaign 的经验, 整理到 ~/ads/LEARNINGS.md.
+
+<!-- 示例:
+## 2026-04-15 14:30 (optimize session)
+- 观察: 周末 CTR 比工作日高 40%, 但 CVR 低 20%, 推测周末逛店多但下单少
+- 临时调整: 周六日 bid modifier -15%, 省钱给工作日
+- 下次验证: 7 天后看 CPA 是否改善
+-->

package/.claude/skills/ads/template/campaign/STRATEGY.md

@@ -0,0 +1,29 @@
+# Campaign: <name>
+> 这个 campaign 的专属策略. 用户级整体策略见 ~/ads/ADS.md.
+> 由 `ads launch` 之后 LLM 根据 ADS.md + 用户请求生成草稿, 后续可编辑.
+
+## 目标
+<!-- 这个 campaign 要达成什么? 例: "推新上的夏季系列裙装, 主打 25-35 女性" -->
+
+## 推广产品
+<!-- 具体 product_id 列表 -->
+
+## 目标受众 (campaign-specific)
+<!-- 相对 ADS.md 默认受众的调整. 没有调整就写 "same as ADS.md" -->
+
+## 关键词意图 (Google Ads)
+- 核心词:
+- 长尾词:
+- 否定词:
+
+## 日预算
+- 日预算: $___
+- 持续时长: ___天 / 无限期
+
+## 差异化角度
+<!-- 这个 campaign 跟其它 campaign 的区别, 为什么单独开? -->
+
+## 后端关联 (由 `ads launch` 自动填)
+- campaign_id:
+- platform_campaign_id:
+- platform_budget_id:

package/.claude/skills/ads/template/user/ADS.md

@@ -0,0 +1,29 @@
+# Ads 整体策略 (用户级)
+> 修改后 git commit. 单个 campaign 的专属策略在 campaigns/<name>/STRATEGY.md.
+
+## 业务目标
+<!-- 例: 提升店铺月销量 / 打响品牌认知 / 某类目拓新 -->
+
+## 候选产品
+<!-- 从 commerce-backend 拉的候选, 或手填. 具体哪个 campaign 推哪个产品由每个 STRATEGY.md 定 -->
+
+## 默认目标受众
+<!-- 可被 campaign 级 STRATEGY.md 覆盖 -->
+- 地域:
+- 年龄段:
+- 设备:
+- 时段偏好:
+
+## 月度总预算 (软性, 超出后所有 campaign 自动暂停到下月 1 日)
+- 月度上限: $___
+- 钱包余额低于 $___ 时自动暂停
+
+## 渠道偏好
+- [x] google_ads
+
+## 品牌禁忌
+<!-- 不能出现的词、不能投放的关键词、必须的免责声明 -->
+
+## 后端登记 (由 `ads init` 自动填, 不要手动改)
+- user_ad_account_id:
+- google_label_id:

package/.claude/skills/ads/template/user/LEARNINGS.md

@@ -0,0 +1,15 @@
+# 优化经验沉淀
+> 跨 campaign 的经验和洞察. 每次 optimize 之后, AI 把可泛化的发现追加到这里.
+> 单 campaign 特有的观察不放这里, 放对应 campaigns/<name>/NOTES.md.
+
+## 什么有效
+<!-- 每条都用一两句话说清楚: "发现了什么" + "在哪次 optimize 时得到的" -->
+
+## 什么无效
+<!-- 同上 -->
+
+## 受众洞察
+<!-- 哪些人群、哪些地域转化高 -->
+
+## 时段/季节规律
+<!-- 一周/一天的高转化时段, 季节性趋势 -->

package/.claude/skills/ads/template/user/PROGRESS.md

@@ -0,0 +1,20 @@
+# 工作日志
+> 每次会话结束前, 在最上方追加一段. 最新的在顶部.
+> 每段必须标注: 时间 + 动作 + 作用的 campaign (或 "all campaigns").
+
+<!-- 示例:
+
+## 2026-04-11 14:30 - launch (campaign: summer-promo)
+- 基于 ADS.md 推了产品 12345 (夏季连衣裙)
+- 生成 5 个素材变体 (minimalist / playful / elegant / beach / street)
+- 合规预审通过, 上线
+- 日预算 $10
+- 异常: 无
+- 下次待办: 7 天后 collect + optimize
+
+## 2026-04-10 10:00 - (init)
+- 初始化 workspace, 填 ADS.md
+- 月度预算 $300, 品牌禁忌: 不能用 "最便宜" "全网最低" 这类绝对化词语
+- 用户说下次会话再 launch
+
+-->

package/.claude/skills/ads/template/user/README.md

@@ -0,0 +1,25 @@
+# ~/ads/ 工作目录
+
+这是你的广告投放工作目录, 由 optima-agent 的 `ads` skill 维护.
+
+## 结构
+
+- `ADS.md` — 你的整体广告策略
+- `LEARNINGS.md` — AI 沉淀的跨 campaign 经验
+- `PROGRESS.md` — 每次 AI 会话的工作日志
+- `REPORTS/` — 周报和月报
+- `assets/` — AI 生成的广告素材 (不进 git)
+- `campaigns/<name>/` — 每个 campaign 的专属文件
+- `.git/` — 本地版本管理, 出错可回滚
+
+## 使用方法
+
+不要直接在这里修改文件. 在 optima.chat 聊天里告诉 AI 你想做什么, 它会替你管理这个目录.
+
+如果你想亲自改 `ADS.md` 的策略(例如加新产品、改预算上限), 也可以. 改完后 AI 下次会话会读到新版本.
+
+## 工作原则
+
+- **单会话单任务**: 每次 AI 会话只做一件事 (launch / optimize / pause / report / ...), 完成后 commit
+- **Git 是保险**: 所有变动都有 commit, 出错可以 `git revert`
+- **事实在后端**: 这里只有策略和 AI 的思考轨迹. 真实的 campaign 状态、花费、余额在后端, 用 `ads status` 查

package/.claude/skills/ads/template/user/assets/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore