@optima-chat/optima-agent 0.8.94 → 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

package/.claude/skills/browser/SKILL.md

@@ -23,60 +23,75 @@ description: "Browser automation for web interactions. Use when user needs to op
 
 1. `browser-cli scripts` — 查看已有脚本（显示名称、描述、步骤）
 2. 如果有匹配的脚本 → 直接用 `browser-cli runscript <name> --param ...`
-3. 如果没有 → 手动探索完成任务，然后生成脚本并提交
+3. 如果没有 → 手动用 browser-cli 命令完成任务
 
 脚本执行零 token 消耗，比手动操作快 10 倍以上。
 
 ## 命令
 
-### 基础命令
+### 会话管理
 
 ```bash
-# 会话管理
 browser-cli launch [--url <url>] [--force]  # 启动浏览器（--force 先关闭已有会话）
 browser-cli close                            # 关闭浏览器并释放资源
 browser-cli status                           # 查看当前会话状态
+```
+
+### 导航
 
-# 导航
+```bash
 browser-cli navigate <url>            # 跳转到 URL
 browser-cli back                      # 后退
 browser-cli refresh                   # 刷新页面
+```
+
+### 交互
 
-# 交互
+```bash
 browser-cli click <index>             # 按索引点击元素
 browser-cli input <index> <text> [--no-clear]  # 输入文本（--no-clear 追加而非替换）
 browser-cli select <index> <option>   # 选择下拉选项
 browser-cli scroll <up|down> [--pages <n>]     # 滚动页面（默认 1 页）
 browser-cli keys <key>                # 键盘操作（Enter、Tab 等）
-browser-cli upload <index> <file...> # 上传文件到 file input（路径自动转换）
+browser-cli upload <index> <file...>  # 上传文件到 file input（路径自动转换）
+```
 
-# 页面检查
+### 页面检查
+
+```bash
 browser-cli dom                       # 获取当前 DOM 状态
 browser-cli screenshot [file]         # 截图（默认：/tmp/screenshot.png）
 browser-cli search <pattern>          # 搜索页面文本
 browser-cli find <css_selector>       # 通过 CSS 选择器查询
+```
+
+### 标签页管理
 
-# 标签页管理
+```bash
 browser-cli tabs                      # 列出所有标签页
 browser-cli switch <tab_id>           # 切换标签页
 browser-cli close-tab <tab_id>        # 关闭标签页
 ```
 
-### 脚本命令
+### 脚本
 
 ```bash
-# 查看与管理
 browser-cli scripts                                        # 列出所有脚本（含描述和步骤）
 browser-cli script-code <name>                             # 查看脚本源码
-browser-cli delete-script <name>                           # 删除脚本
-
-# 提交
-browser-cli submit-script --name <name> --code-file <path> # 提交脚本（新建或覆盖）
-
-# 执行
 browser-cli runscript <name> --param key=value [...]       # 执行脚本（自动轮询到完成）
 browser-cli runscript <name> --param key=value --no-poll   # 执行但不等待
 browser-cli script-task <task-id>                          # 查询执行状态
+browser-cli submit-script --name <name> --code-file <path> # 提交新脚本（新建或覆盖）
+browser-cli delete-script <name>                           # 删除脚本
+```
+
+### Profile 管理
+
+```bash
+browser-cli profiles                   # 列出浏览器 profile
+browser-cli delete-profile <id>        # 删除 profile
+browser-cli launch --profile <id>      # 用指定 profile 启动
+browser-cli runscript <name> --profile <id> --param ...  # 用指定 profile 执行脚本
 ```
 
 ## DOM 索引格式
@@ -92,38 +107,6 @@ browser-cli script-task <task-id>                          # 查询执行状态
 - 每次操作后索引会**重新分配** — 务必使用最新的索引
 - 使用这些索引来执行 `click`、`input` 和 `select` 命令
 
-## 登录与 Profile
-
-浏览器支持命名 Profile，用于隔离不同账号的登录态（cookies、session）。
-
-**当有明确的账号身份时（如多账号运营），必须使用 `--profile`。** 省略 `--profile` 会使用默认 Profile，导致不同账号登录态互相覆盖。
-
-- **命名 Profile**：`--profile <id>` 隔离不同账号的登录态，`launch` 和 `runscript` 都支持
-- **登录态自动持久化**：Profile 数据在浏览器运行时实时保存到磁盘，不依赖 close
-- **首次登录**：需要用户提供账号和验证码
-- **后续使用**：自动恢复登录态，无需重新登录
-- **login_required 处理**：如果 `runscript` 报此错误，用 `browser-cli launch --profile <id> --url <平台URL>` 引导用户重新登录
-
-```bash
-# 登录到指定 Profile
-browser-cli launch --profile xhs-tech --url https://creator.xiaohongshu.com
-
-# 用指定 Profile 执行脚本
-browser-cli runscript xiaohongshu-image-note --profile xhs-tech --param title="..."
-```
-
-## 文件路径
-
-浏览器后端可以直接读取用户工作空间的文件（通过共享 EFS）。传文件路径时直接使用你看到的路径即可，后端会自动转换：
-
-```
-~/images/photo.jpg              → 自动转换 ✓
-/home/aiuser/images/photo.jpg   → 自动转换 ✓
-/mnt/efs/{userId}/images/...    → 自动转换 ✓
-```
-
-不需要上传文件，不需要手动转换路径。
-
 ## 操作流程
 
 ### 流程一：有脚本（常见）
@@ -131,12 +114,6 @@ browser-cli runscript xiaohongshu-image-note --profile xhs-tech --param title=".
 ```bash
 # 1. 检查脚本
 browser-cli scripts
-# 输出:
-# xiaohongshu-image-note — 在小红书创作者平台发布图文笔记
-#   [1] navigate — 打开小红书发布页
-#   [2] switch_tab — 切换到上传图文模式
-#   [3] upload — 上传图片 {images}
-#   ...
 
 # 2. 直接执行
 browser-cli runscript xiaohongshu-image-note \
@@ -145,52 +122,35 @@ browser-cli runscript xiaohongshu-image-note \
   --param 'images=["~/images/photo1.jpg", "~/images/photo2.jpg"]'
 # 输出: ✓ Script completed
 
-# 另一个例子：小红书评论
+# 小红书评论
 browser-cli runscript xiaohongshu-comment \
   --param search_keyword="辞职做跨境电商" \
   --param comment="写得好！"
-# 输出: ✓ Script completed
-# 脚本会搜索帖子 → 打开 → 激活评论框 → 输入 → 发送
+
+# 小红书数据采集
+browser-cli runscript xiaohongshu-data-collect
+
+# Instagram 发帖
+browser-cli runscript instagram-image-post \
+  --param 'images=["~/images/photo.jpg"]' \
+  --param body="Morning vibes ☕"
 ```
 
-### 流程二：无脚本（首次）
+### 流程二：无脚本（手动操作）
 
 ```bash
-# 1. 检查脚本 — 没有匹配的
-browser-cli scripts
-# 输出: No scripts registered.
-
-# 2. 手动探索
-browser-cli launch --url https://creator.xiaohongshu.com
-# → 如果需要登录，向用户询问手机号和验证码
-browser-cli input 11 "18500400810"
-browser-cli click 33   # 发送验证码
-# (用户提供验证码)
-browser-cli input 12 "123456"
-browser-cli click 38   # 登录
-# → 登录成功，继续操作...
-browser-cli dom                           # 分析页面
-browser-cli click 1880                    # 点击"上传图文"
-browser-cli dom                           # 找到 file input
-browser-cli upload 1092 ~/images/photo.jpg  # 上传图片
-browser-cli input 2905 "标题"              # 填写标题
-browser-cli input 3432 "正文内容"          # 填写正文
-browser-cli click 2814                    # 点击发布
-# → 任务完成
-
-# 3. 生成 Python 脚本
-# 根据上面的探索轨迹，生成脚本文件，必须包含：
-# - DESCRIPTION: 脚本描述
-# - STEPS: 语义步骤列表（StepDef）
-# - run(ctx): 异步执行函数
-# 写到本地文件
-
-# 4. 提交脚本
-browser-cli submit-script \
-  --name xiaohongshu-image-note \
-  --code-file /tmp/xiaohongshu_image_note.py
-
-# 5. 关闭浏览器
+# 1. 启动浏览器
+browser-cli launch --url https://example.com
+
+# 2. 查看 DOM，找到要操作的元素
+browser-cli dom
+
+# 3. 操作元素（用 DOM 返回的索引）
+browser-cli click 15
+browser-cli input 22 "内容"
+browser-cli keys Enter
+
+# 4. 完成后关闭
 browser-cli close
 ```
 
@@ -199,228 +159,35 @@ browser-cli close
 ```bash
 # 1. 执行脚本
 browser-cli runscript xiaohongshu-image-note --param ...
-# 输出:
-# ⚠ Script needs fallback
-#
-# ✓ Completed:
-#   [1] navigate — 打开小红书发布页
-#   [2] switch_tab — 切换到上传图文模式
-#
-# ✗ Failed at step [3] upload: file input not found
-#
-# → Remaining steps:
-#   [3] upload — 上传图片 ["~/photo.jpg"]
-#   [4] fill_title — 填写标题'测试'
-#   [5] fill_body — 填写正文'内容'
-#   [6] publish — 点击发布按钮
-#   [7] verify — 确认发布成功
-#
-# Session is still open — use browser-cli dom/click/input to continue
-
-# 2. 接管完成剩余步骤（Session 仍然打开，不需要重新 launch）
-browser-cli dom                    # 查看当前页面
-browser-cli click 15               # 继续操作
-browser-cli input 22 "测试"
-browser-cli click 30
-# → 任务完成
-
-# 3. (可选) 更新脚本以修复问题
-# 重新生成脚本，覆盖旧版本
-browser-cli submit-script \
-  --name xiaohongshu-image-note \
-  --code-file /tmp/xiaohongshu_image_note_v2.py
-
-# 4. 关闭浏览器
-browser-cli close
-```
-
-## 脚本代码规范
-
-### 基本结构
-
-每个脚本必须包含 `DESCRIPTION`、`STEPS` 和 `async def run(ctx)`:
-
-```python
-"""脚本描述。"""
-from __future__ import annotations
-import asyncio
-import json
-from app.scripts.base import ScriptContext, ScriptResult, StepDef, render_steps
-
-DESCRIPTION = "一句话描述脚本功能"
-
-STEPS = [
-    StepDef(id="step_id", description="步骤描述，支持 {param} 占位符"),
-]
-
-PAGE_SETTLE = 2  # 页面操作后等待秒数
-
-async def run(ctx: ScriptContext) -> ScriptResult:
-    bs = ctx.browser_session
-    steps = render_steps(STEPS, ctx.params)
-    completed: list[StepDef] = []
-
-    try:
-        # 逐步执行，每完成一步 append
-        # ...
-        return ScriptResult(status="completed", output={...}, completed_steps=completed)
-    except Exception as e:
-        remaining = [s for s in steps if s not in completed]
-        snapshot = await _capture_snapshot(bs)
-        return ScriptResult(
-            status="needs_fallback",
-            completed_steps=completed,
-            remaining_steps=remaining,
-            error=str(e),
-            snapshot=snapshot,
-        )
-
-async def _capture_snapshot(bs) -> dict:
-    try:
-        state = await bs.get_browser_state_summary(include_screenshot=False)
-        dom = state.dom_state.llm_representation() if state and state.dom_state else ""
-    except Exception:
-        dom = ""
-    return {"dom": dom}
-```
-
-### 浏览器操作 API
-
-```python
-# 导航
-action = ctx.action_model(navigate={"url": "https://example.com"})
-await ctx.controller.act(action, bs)
-await asyncio.sleep(PAGE_SETTLE)
+# 输出: ⚠ Script needs fallback
+# → 显示已完成和剩余步骤
 
-# 点击（通过 DOM index）
-action = ctx.action_model(click={"index": idx})
-await ctx.controller.act(action, bs)
+# 2. Session 仍然打开 — 用手动命令继续完成剩余步骤
+browser-cli dom
+browser-cli click 15
+browser-cli input 22 "内容"
 
-# 输入文本
-action = ctx.action_model(input={"index": idx, "text": "内容"})
-await ctx.controller.act(action, bs)
-
-# 获取当前 DOM（每步操作前刷新）
-state = await bs.get_browser_state_summary(include_screenshot=False, cached=False)
-sm = state.dom_state.selector_map or {}
-
-# 获取当前 URL
-page = await bs.get_current_page()
-url = await page.get_url()
-```
-
-### 元素查找（语义匹配，不要硬编码 index）
-
-DOM index 每次页面变化后会重新分配，脚本中**不能硬编码 index**。
-必须通过语义属性动态查找：
-
-```python
-# 按文字内容查找（如按钮、标签页）
-def _find_by_text(sm, text, tag=None):
-    for idx, node in sm.items():
-        node_tag = (getattr(node, "tag_name", "") or "").lower()
-        if tag and node_tag != tag:
-            continue
-        try:
-            node_text = node.get_all_children_text().strip() if hasattr(node, "get_all_children_text") else ""
-        except Exception:
-            node_text = ""
-        if text in node_text:
-            return idx
-    return None
-
-# 按 placeholder 查找（如输入框，支持 shadow DOM）
-def _find_by_placeholder(sm, placeholder_contains):
-    for idx, node in sm.items():
-        attrs = getattr(node, "attributes", {}) or {}
-        if placeholder_contains in attrs.get("placeholder", ""):
-            return idx
-        # Shadow DOM fallback
-        if not attrs:
-            try:
-                llm = node.llm_representation() if hasattr(node, "llm_representation") else ""
-                if placeholder_contains in llm:
-                    return idx
-            except Exception:
-                pass
-    return None
-
-# 按 role 查找（如 contenteditable 编辑器）
-def _find_by_role(sm, role, tag=None):
-    for idx, node in sm.items():
-        node_tag = (getattr(node, "tag_name", "") or "").lower()
-        if tag and node_tag != tag:
-            continue
-        attrs = getattr(node, "attributes", {}) or {}
-        if attrs.get("role") == role:
-            return idx
-        if attrs.get("contenteditable") and role == "textbox":
-            return idx
-    return None
-
-# 按文件类型查找 file input（如图片上传）
-def _find_image_file_input(bs, sm):
-    for idx, node in sm.items():
-        if not bs.is_file_input(node):
-            continue
-        attrs = getattr(node, "attributes", {}) or {}
-        accept = attrs.get("accept", "")
-        if any(ext in accept for ext in [".jpg", ".jpeg", ".png", ".webp"]):
-            return idx
-    for idx, node in sm.items():
-        if bs.is_file_input(node):
-            return idx
-    return None
+# 3. 完成后关闭
+browser-cli close
 ```
 
-### 文件上传
-
-上传文件需要 `FileSystem` 和 `available_file_paths`：
-
-```python
-from browser_use.filesystem.file_system import FileSystem
-from app.services.file_upload import UPLOAD_TEMP_BASE
-import secrets as _secrets
+## 文件路径
 
-# 创建临时目录
-fs_dir = UPLOAD_TEMP_BASE / f"script_{_secrets.token_hex(4)}"
-fs_dir.mkdir(parents=True, exist_ok=True)
-file_system = FileSystem(base_dir=str(fs_dir), create_default_files=False)
+浏览器后端可以直接读取用户工作空间的文件。传文件路径时直接使用你看到的路径即可，后端会自动转换：
 
-# 上传每个文件
-images = json.loads(ctx.params.get("images", "[]"))
-file_idx = _find_image_file_input(bs, sm)
-for img_path in images:
-    action = ctx.action_model(upload_file={"index": file_idx, "path": img_path})
-    await ctx.controller.act(action, bs, available_file_paths=images, file_system=file_system)
+```
+~/images/photo.jpg              → 自动转换 ✓
+/home/aiuser/images/photo.jpg   → 自动转换 ✓
+/mnt/efs/{userId}/images/...    → 自动转换 ✓
 ```
 
-文件路径由引擎自动转换（~/xxx → /mnt/workspaces/{userId}/xxx），脚本直接用 `ctx.params` 中的路径即可。
-
-### 等待页面变化
-
-页面操作后（导航、上传、点击）需要等待，用轮询模式：
-
-```python
-# 简单等待
-await asyncio.sleep(PAGE_SETTLE)
+## 需要用户登录态的任务
 
-# 轮询等待某个元素出现（如上传后等编辑模式）
-target_idx = None
-for attempt in range(10):
-    await asyncio.sleep(PAGE_SETTLE)
-    state = await bs.get_browser_state_summary(include_screenshot=False, cached=False)
-    sm = state.dom_state.selector_map or {}
-    target_idx = _find_by_placeholder(sm, "填写标题")
-    if target_idx is not None:
-        break
-if target_idx is None:
-    raise RuntimeError("等待超时：目标元素未出现")
-```
+当用户要求操作需要登录的平台（小红书、Instagram、微博、淘宝等社交/电商平台），在开始执行前先引导用户安装扩展：
 
-### 完整示例
+"这个任务需要用到你在 [平台名] 的登录态。请安装 Optima Browser Operator Chrome 扩展，这样我可以直接用你已登录的浏览器来操作，不需要你提供密码。"
 
-参考系统内置脚本 `xiaohongshu-image-note`（通过 `browser-cli script-code xiaohongshu-image-note` 查看完整源码）。
+安装后用户回到聊天页面，扩展自动连接，直接执行任务。如果用户在该平台未登录，提示用户先在自己的 Chrome 里登录。
 
 ## 注意事项
 
@@ -428,9 +195,7 @@ if target_idx is None:
 - **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
 - **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
 - **5 分钟超时**：无操作 5 分钟后会话自动关闭
-- **登录自动保持**：登录一次后自动持久化，无需重复登录
-- **文件路径自动转换**：直接传你看到的路径（~/xxx），后端自动处理
 - **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
-- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。先 `browser-cli launch --url <平台URL>` 手动登录（问用户要验证码），登录后 `browser-cli close` 保存登录态，再重新 `runscript`
+- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。如果用户已安装 Extension 且 Extension 已连接，用户的 Chrome 通常已经登录了——让用户在自己的 Chrome 里手动登录该平台，然后重新 `runscript`。如果没有 Extension（走 Chromium），用 `browser-cli launch --url <平台URL>` 引导用户登录
 - **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
 - **Extension 模式**：标记了 `REQUIRES_USER_SESSION=True` 的脚本会自动使用用户的真实 Chrome（通过 Optima Browser Operator 扩展），未标记的脚本走 Chromium。这由后端自动判断，无需手动指定

package/.claude/skills/i18n/SKILL.md

@@ -177,6 +177,26 @@ commerce i18n homepage set \
 commerce i18n homepage list --section-id section_123
 ```
 
+### 场景7: 店铺政策翻译
+
+```bash
+# 翻译退货政策
+commerce i18n shop-policy set --policy-type returns --lang zh-CN --title "退货政策" --content "# 退货政策\n\n..."
+
+# 翻译隐私政策
+commerce i18n shop-policy set --policy-type privacy --lang ja-JP --title "プライバシーポリシー" --content "# ..."
+```
+
+### 场景8: 店铺关于页面翻译
+
+```bash
+# 翻译关于页面
+commerce i18n shop-about set --lang zh-CN --about-content "# 我们的故事\n\n..."
+
+# 翻译联系页面补充内容
+commerce i18n shop-about set --lang ja-JP --contact-content "# お問い合わせ\n\n..."
+```
+
 ## 卓越标准 (Excellence Standards)
 
 ### 翻译质量维度
@@ -354,6 +374,8 @@ commerce i18n variant create --variant-id var_2 --lang ja-JP \
 - "翻译集合信息" → `commerce i18n collection create --collection-id XX --lang YY`
 - "设置商户多语言信息" → `commerce i18n merchant create --lang XX`
 - "翻译首页区块" → `commerce i18n homepage set --section-id XX --lang YY`
+- "翻译店铺政策" → `commerce i18n shop-policy set --policy-type XX --lang YY`
+- "翻译关于页面" → `commerce i18n shop-about set --lang XX`
 
 ### 商品翻译
 
@@ -390,6 +412,14 @@ commerce i18n variant create --variant-id var_2 --lang ja-JP \
 - `commerce i18n homepage list` - 查看首页翻译
 - `commerce i18n homepage delete` - 删除首页翻译
 
+### 店铺政策翻译
+
+- `commerce i18n shop-policy set` - 设置店铺政策翻译
+
+### 店铺关于页面翻译
+
+- `commerce i18n shop-about set` - 设置店铺关于页面翻译
+
 ## 详细示例 (Detailed Examples)
 
 ### 商品翻译示例
@@ -477,7 +507,7 @@ commerce i18n product create --product-id prod_2 --lang ja-JP --name "..."
 
 ## 重要提示 (Important Notes)
 
-- **支持的语言**：en-US, es-ES, ja-JP, vi-VN, zh-CN
+- **支持的语言**：en-US, es-ES, ja-JP, vi-VN, zh-CN, zh-HK, zh-TW
 - **语言代码格式**：必须使用BCP 47格式（如 en-US），不能使用短代码（如 en）
 - **变体翻译参数**：使用 `--variant-id`（不是 `--product-id`）
 - **变体规格翻译**：`variant-attributes-translations` 格式需要同时翻译规格键和值

package/.claude/skills/shop-content/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: shop-content
+description: "店铺内容管理。使用场景：更新关于我们、设置联系信息、管理退货/隐私/条款/配送政策、设置社交链接。注意：翻译用 i18n skill。"
+---
+
+# 店铺内容管理
+
+## 典型场景
+
+| 用户说 | 命令 |
+|--------|------|
+| "更新关于我们" / "写关于页面" | `commerce shop-about update --about-content "# Our Story..."` |
+| "设置联系方式" | `commerce shop-about update --contact-email "..." --contact-phone "..."` |
+| "添加联系页面内容" | `commerce shop-about update --contact-content "# Contact..."` |
+| "查看关于信息" | `commerce shop-about get` |
+| "设置 Instagram" / "添加社交链接" | `commerce shop-about update --social-instagram "https://..."` |
+| "设置退货政策" / "更新退货政策" | `commerce shop-policy set --type returns --title "退货政策" --content "# ..."` |
+| "设置隐私政策" | `commerce shop-policy set --type privacy --title "隐私政策" --content "# ..."` |
+| "设置服务条款" | `commerce shop-policy set --type terms --title "服务条款" --content "# ..."` |
+| "设置配送政策" | `commerce shop-policy set --type shipping --title "配送政策" --content "# ..."` |
+| "查看所有政策" | `commerce shop-policy list` |
+| "查看退货政策" | `commerce shop-policy get --type returns` |
+
+## 不在此模块（重要）
+
+| 用户说 | 正确位置 |
+|--------|----------|
+| "翻译退货政策" / "政策日语版" | **i18n skill**：`commerce i18n shop-policy set` |
+| "翻译关于我们" | **i18n skill**：`commerce i18n shop-about set` |
+| "首页设置" / "首页区块" | **homepage skill** |
+| "修改品牌色" / "主题色" | **merchant skill**：`commerce merchant update --primary-color` |
+
+---
+
+## 关于页面内容
+
+```bash
+# 查看当前内容
+commerce shop-about get
+
+# 更新关于页面（Markdown 格式）
+commerce shop-about update --about-content "# Our Story\n\nWe started in 2020..."
+
+# 更新联系页面补充内容
+commerce shop-about update --contact-content "## 批发合作\n\n请联系..."
+```
+
+## 联系信息
+
+```bash
+commerce shop-about update \
+  --contact-email "hello@store.com" \
+  --contact-phone "+86 138xxxx" \
+  --business-address "深圳市南山区..." \
+  --business-hours "Mon-Fri 9:00-18:00"
+```
+
+## 社交链接
+
+```bash
+# 设置单个
+commerce shop-about update --social-instagram "https://instagram.com/mystore"
+
+# 设置多个
+commerce shop-about update \
+  --social-instagram "https://instagram.com/mystore" \
+  --social-tiktok "https://tiktok.com/@mystore" \
+  --social-youtube "https://youtube.com/@mystore"
+```
+
+支持：`--social-instagram`, `--social-facebook`, `--social-twitter`, `--social-tiktok`, `--social-youtube`
+
+## 店铺政策
+
+```bash
+# 查看所有政策
+commerce shop-policy list
+
+# 查看特定政策
+commerce shop-policy get --type returns
+
+# 设置/更新政策（Markdown 格式）
+commerce shop-policy set --type returns --title "退货政策" --content "# 退货政策\n\n..."
+commerce shop-policy set --type privacy --title "隐私政策" --content "# 隐私政策\n\n..."
+commerce shop-policy set --type terms --title "服务条款" --content "# 服务条款\n\n..."
+commerce shop-policy set --type shipping --title "配送政策" --content "# 配送政策\n\n..."
+```
+
+**注意**：政策类型只能是 `terms`、`privacy`、`returns`、`shipping`。
+
+## 内容格式
+
+所有内容字段（about_content、contact_content、policy content）使用 **Markdown 格式**，支持标题、列表、粗体、链接等。
+
+## 命令参考
+
+- `commerce shop-about get` - 查看关于/联系信息
+- `commerce shop-about update` - 更新关于/联系/社交链接
+- `commerce shop-policy list` - 查看所有政策
+- `commerce shop-policy get --type <type>` - 查看特定政策
+- `commerce shop-policy set --type <type> --title <title> --content <content>` - 设置政策

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.8.94",
+  "version": "0.8.95",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",