@optima-chat/optima-agent 0.8.91 → 0.8.93

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

@@ -144,6 +144,13 @@ browser-cli runscript xiaohongshu-image-note \
   --param body="内容..." \
   --param 'images=["~/images/photo1.jpg", "~/images/photo2.jpg"]'
 # 输出: ✓ Script completed
+
+# 另一个例子：小红书评论
+browser-cli runscript xiaohongshu-comment \
+  --param search_keyword="辞职做跨境电商" \
+  --param comment="写得好！"
+# 输出: ✓ Script completed
+# 脚本会搜索帖子 → 打开 → 激活评论框 → 输入 → 发送
 ```
 
 ### 流程二：无脚本（首次）
@@ -426,3 +433,4 @@ if target_idx is None:
 - **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
 - **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。先 `browser-cli launch --url <平台URL>` 手动登录（问用户要验证码），登录后 `browser-cli close` 保存登录态，再重新 `runscript`
 - **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
+- **Extension 模式**：标记了 `REQUIRES_USER_SESSION=True` 的脚本会自动使用用户的真实 Chrome（通过 Optima Browser Operator 扩展），未标记的脚本走 Chromium。这由后端自动判断，无需手动指定

package/.claude/skills/homepage/SKILL.md

@@ -52,8 +52,8 @@ description: 店铺首页配置。管理首页区块（Banner、集合列表、
 
 | 用户说 | 命令 |
 |-------|------|
-| 设置首页背景图 | `commerce homepage update-page-settings --background-image "https://..." --background-mode repeat-y` |
-| 设置固定背景（照片） | `commerce homepage update-page-settings --background-image "https://..." --background-mode fixed` |
+| 设置首页背景图 | 先 `commerce upload --file bg.png` 拿到 media_id，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode repeat-y` |
+| 设置固定背景（照片） | 先上传，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode fixed` |
 | 调整背景叠加透明度 | `commerce homepage update-page-settings --overlay-opacity 0.7` |
 | 调整背景叠加颜色 | `commerce homepage update-page-settings --overlay-color "#f5f5f5"` |
 | 移除背景图 | `commerce homepage update-page-settings --remove-background` |
@@ -116,7 +116,8 @@ description: 店铺首页配置。管理首页区块（Banner、集合列表、
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| background_image | string / null | 背景图片 URL（HTTPS），null 表示无背景 |
+| background_media_id | string / null | 背景图片 Media ID（通过 `commerce upload` 获取，推荐） |
+| background_image | string / null | 背景图片 URL（不推荐直接使用，应通过 media_id 设置） |
 | background_mode | string | `repeat-y`（横向填满纵向平铺，默认）/ `fixed`（固定视口） |
 | background_overlay_color | string | 叠加颜色（hex 格式，默认 `#ffffff`） |
 | background_overlay_opacity | number | 叠加透明度 0-1（默认 0.85，越大越不透明） |

package/.claude/skills/kol-outreach/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: kol-outreach
+description: "KOL 建联全自动化：从 TikTok 发现潜在 KOL、提取 bio email、发送个性化 outreach、自动谈判价格与条款。当用户说'帮我找 KOL'、'{产品} KOL 建联'、'KOL 进展如何'，或收到系统触发的 [KOL_INBOUND:...] 或 [KOL_INBOUND] 标记时，使用此 skill。"
+---
+
+# KOL Outreach Skill
+
+本 skill 帮助商家在 TikTok 上端到端完成 KOL 建联：发现 → 触达 → 谈判 →
+意向交付，运行时零打扰，所有决策参数在首次 onboarding 时固化。
+
+## 核心工作目录
+
+所有状态都在 `~/kol-outreach/`，整个目录是一个 git repo。结构：
+
+```
+~/kol-outreach/
+├── BRAND.md                # 商家品牌素材（跨 campaign）
+├── MERCHANT_LIMITS.md      # 跨 campaign 发信速率
+├── CAMPAIGNS.md            # campaign 索引
+├── PROGRESS.md             # 商家级里程碑日志
+└── campaigns/{campaignId}/
+    ├── CONFIG.md           # 本 campaign 的商品/预算/条款
+    ├── KOLS.md             # 本 campaign 的 KOL 索引
+    ├── TEMPLATES.md        # 邮件模板（4 类）
+    ├── PROGRESS.md         # 本 campaign 的事件日志
+    ├── CONVERSATIONS/{username}.md  # 每个 KOL 的对话历史
+    └── assets/             # 商品图/素材
+```
+
+## 每次 session 的启动流程
+
+按顺序执行这些检查，决定本次 session 的动作：
+
+1. **检测系统触发**：用户消息是否包含 `[KOL_INBOUND:{campaignId}]` 或 `[KOL_INBOUND]`（无 campaignId）标记？
+   - 是 → 走「KOL 回信处理」流程（见下）
+   - 否 → 继续步骤 2
+2. **检测首次使用**：`ls ~/kol-outreach/BRAND.md` 是否存在？
+   - 不存在 → 走「Merchant onboarding」→ 接着走「Campaign onboarding」
+   - 存在 → 继续步骤 3
+3. **根据用户意图**分流：
+   - 用户说"给 {新产品} 建联" → 走「Campaign onboarding」创建新 campaign
+   - 用户说"开始建联 {campaign}" / "发送 outreach" → 走「发现 + 首发 outreach」
+   - 用户说"KOL 进展" / "查看状态" → 走「查询进度」
+
+**单会话单任务原则**：每次 session 只执行一种操作，完成后 git commit 并
+更新 PROGRESS.md。出错时可以精准回滚。
+
+---
+
+## 流程 A：Merchant onboarding（只发生一次）
+
+1. 创建工作目录：
+
+   ```bash
+   mkdir -p ~/kol-outreach/campaigns
+   cp -r $CLAUDE_SKILL_DIR/template/merchant/. ~/kol-outreach/
+   cd ~/kol-outreach && git init && git add -A && git commit -m "init merchant workspace"
+   ```
+
+2. 会话式填 `BRAND.md`：
+   - 询问 brand_name
+   - 从 brand_name 生成 brand_slug 建议（kebab-case）
+   - 调 `scout outreach brand-slug check {slug}` 验证唯一性
+     - 可用 → 确认
+     - 被占用 → 使用 API 返回的 suggestions 让商家选或自己改
+   - 成功后调 `scout outreach brand-slug claim` 锁定
+   - 依次询问 brand_website / brand_social / default_contact_name / default_brand_pitch
+   - 给出默认的兜底话术模板，让商家确认或改
+   - 给出默认的双语 escalation_keywords，让商家确认或扩展
+   - Edit `BRAND.md`
+   - `git add BRAND.md && git commit -m "setup BRAND.md"`
+
+3. 会话式填 `MERCHANT_LIMITS.md`：
+   - 默认 `max_daily_sends: 50`，询问商家是否调整
+   - 初始化 `sent_today: 0`，`date_utc: $(date -u +%Y-%m-%d)`
+   - `git commit -m "setup MERCHANT_LIMITS.md"`
+
+4. 告诉商家：商家级配置完成，现在为第一个商品创建 campaign，进入流程 B。
+
+---
+
+## 流程 B：Campaign onboarding（每次新建 campaign）
+
+1. 确定 campaignId：
+   - 询问商家要为哪个商品建联（可列出他的 Optima 店铺商品作为选项）
+   - 从商品标题生成 kebab-case slug 建议（"Titanium Travel Tumbler" → "titanium-tumbler"）
+   - 校验：与 `CAMPAIGNS.md` 现有 campaign 不重复；匹配 `^[a-z0-9][a-z0-9-]{0,29}$`
+   - 告诉商家建议值，让他确认或改
+
+2. 创建 campaign 目录：
+
+   ```bash
+   mkdir -p ~/kol-outreach/campaigns/{campaignId}
+   cp -r $CLAUDE_SKILL_DIR/template/campaign/. ~/kol-outreach/campaigns/{campaignId}/
+   cd ~/kol-outreach && git add -A && git commit -m "init campaign {campaignId}"
+   ```
+
+3. 分段会话式填 campaign `CONFIG.md`：
+   - 3.1 Campaign 元信息（填 campaignId、创建时间、status=active）
+   - 3.2 商品段（ID/URL/标题/卖点/受众/样品）
+   - 3.3 目标 KOL 画像
+   - 3.4 预算与报价
+     - **校验**：`max_price >= target_price >= first_offer`、
+       `max_step <= max_price - first_offer`、`total_budget >= max_price`
+     - 任一不过 → 说明原因 + 建议调整 + 重新问，不要跳过
+   - 3.5 合作条款边界（保留时长/使用授权/付款节点/样品政策）
+   - 3.6 兜底话术覆写（默认留空继承 BRAND.md）+ 运行参数（max_rounds/max_days/max_concurrent_kols/覆写的 escalation_keywords/forbidden_phrases）
+   - 每段填完 → Edit CONFIG.md → `git commit -m "[{campaignId}] setup CONFIG section N"`
+
+4. 追加 `CAMPAIGNS.md`（新增一行，status=active）
+
+5. `git commit -m "[{campaignId}] campaign ready"`
+
+6. 告诉商家 campaign 已就绪，问他是否立即开始发现 KOL。
+
+---
+
+## 流程 C：发现 KOL + 首发 Outreach
+
+触发：用户说"给 {campaign} 开始建联" / "为 {campaign} 发送 outreach"。
+如果商家没指定 campaign，读 `CAMPAIGNS.md`：
+- 只有一个 active → 用它
+- 多个 active → 列出让商家选
+
+1. 读配置：
+   - `CONFIG.md`（目标画像/运行参数/预算）
+   - `KOLS.md`（已存在 KOL 列表）
+   - `BRAND.md`（后面生成 outreach 需要）
+   - `MERCHANT_LIMITS.md`（今日发信数）
+
+2. 并行上限预检：
+   - `in_flight = KOLS.md 中 status ∈ {awaiting_reply, in_progress} 的行数`
+   - `available_slots = max_concurrent_kols - in_flight`
+   - `available_slots <= 0` → 告诉商家"当前 {in_flight} 个 KOL 在谈，已达并行上限。等 KOL 进入终态后再继续。"退出
+   - `target_new = min(CONFIG.target_kols_this_round, available_slots)`
+
+3. 日发信上限预检（merchant 级）：
+   - 读 MERCHANT_LIMITS.md 的 sent_today 和 max_daily_sends
+   - 如果当前 UTC 日期 ≠ MERCHANT_LIMITS.md 的 date_utc：归档昨天计数到历史表，sent_today=0，写回
+   - `daily_budget = max_daily_sends - sent_today`
+   - `daily_budget <= 0` → 告诉商家"今日所有 campaign 合计发信配额已用完"，退出
+   - `本轮发送量 = min(target_new, daily_budget)`
+
+4. 调 `scout tiktok creators` 发现 KOL：
+
+   ```bash
+   scout tiktok creators \
+     --follower-count "<CONFIG.powder_count_range>" \
+     --country "<CONFIG.region>" \
+     --limit <本轮发送量 * 3> \
+     --format json
+   ```
+
+   （×3 给过滤留空间）
+
+5. 过滤：
+   - engagement_rate < 2% 丢弃
+   - 已在 KOLS.md 的 username 丢弃
+   - 粉丝量不在目标区间的丢弃
+
+6. 对每个候选 KOL：
+   - 调 `scout tiktok creator-products @username --limit 5` 获取最近视频（用于生成开场白）
+   - 如果 scout 的 creators 响应 **没有返回 bio**，也从这里拉（见 probe Task 0.2）
+   - 用正则从 bio 抠 email：
+
+     ```bash
+     python3 -c "import re, sys; print(re.findall(r'[\\w.+-]+@[\\w-]+\\.[\\w.-]+', sys.stdin.read())[0] if re.search(r'[\\w.+-]+@[\\w-]+\\.[\\w.-]+', sys.stdin.read()) else '')" <<< "$BIO"
+     ```
+
+   - 有 email → 追加到 KOLS.md，status=pending_outreach
+   - 没 email → 追加到 KOLS.md，status=no_contact
+   - `git commit -m "[{campaignId}] discovered N KOLs"`
+
+7. 对每个 status=pending_outreach 的 KOL（限制本轮发送量）：
+   - 读 `TEMPLATES.md` 的 first_outreach_v1 骨架
+   - **LLM 决策**（结构化 JSON 输出）：
+     - 输入：CONFIG 商品段 + BRAND.md（覆盖后） + KOL 最近视频 + template 变量列表
+     - 输出：
+       ```json
+       {
+         "kol_first_name": "...",
+         "opener_line": "...",
+         "fit_reason": "...",
+         "product_one_liner": "..."
+       }
+       ```
+     - 你只决定变量值，**不要直接写 email body**
+   - 模板渲染：把变量代入 first_outreach_v1 → 最终 body
+   - **Layer 4 内容终检**：
+     - body 不含 CONFIG.forbidden_phrases（fallback 到 BRAND.md default）
+     - body 长度 ≤ 2000 字符
+     - 任一不过 → 跳过这个 KOL，写 KOLS.md status=send_error，记 PROGRESS.md
+   - Edit `CONVERSATIONS/{username}.md` 追加 Round 1 (outreach sent) 段
+   - 调 `scout outreach send`：
+
+     ```bash
+     echo '{
+       "to": "kol_email",
+       "subject": "Collaboration opportunity with <brand_name>",
+       "body": "<rendered body>",
+       "from_merchant_id": "<merchantId>",
+       "from_campaign_id": "<campaignId>",
+       "from_brand_slug": "<BRAND.brand_slug>",
+       "from_brand_name": "<BRAND.brand_name>",
+       "from_contact_name": "<effective contact_name>"
+     }' | scout outreach send
+     ```
+
+   - 解析响应，拿 message_id 写回 CONVERSATIONS/{username}.md 的 Message-ID chain
+   - Edit KOLS.md：status: pending_outreach → awaiting_reply，offer=first_offer
+   - 读 MERCHANT_LIMITS.md，sent_today += 1，写回
+   - `git commit -m "[{campaignId}] outreach sent to @{username}"`
+
+8. 追加本 campaign 的 PROGRESS.md；重要事件同步追加 merchant PROGRESS.md
+
+9. 告诉商家本次发送结果。
+
+---
+
+## 流程 D：KOL 回信处理（由 `[KOL_INBOUND:{campaignId}]` 或 `[KOL_INBOUND]` 触发）
+
+1. 解析 prompt：
+   - 如果包含 `[KOL_INBOUND:{campaignId}]` → 直接知道 campaignId，同时抠 email metadata（From / Subject / Message-ID / In-Reply-To / References / Body）
+   - 如果包含 `[KOL_INBOUND]` + `merchant_id: {X}` → campaignId 未知，抠 merchant_id 和 email metadata；campaignId 在步骤 3 中搜索确定
+     （`merchant_id` 仅用于日志和审计。campaign 查找基于 `~/kol-outreach/campaigns/*/KOLS.md` 遍历，因为工作目录已隐含了 merchant 身份。）
+
+2. 校验 campaign 存在（仅 campaignId 已知时）：
+   - `ls ~/kol-outreach/campaigns/{campaignId}/CONFIG.md`
+   - 不存在 → 写 merchant PROGRESS.md 异常记录 + `sentinel report --condition-met false --summary "unknown campaign"` + 退出
+
+3. 按 from_email 查找 KOL：
+   - **campaignId 已知**（from step 1）：只读该 campaign 的 KOLS.md
+     - 找到 → 继续步骤 4
+     - 找不到 → orphan_inbound：写 campaign PROGRESS.md + sentinel report false + 退出
+   - **campaignId 未知**（fallback）：遍历 `~/kol-outreach/campaigns/*/KOLS.md`
+     - 唯一匹配 → 确定 campaignId，继续步骤 4
+     - 多个匹配 → 选 **KOLS.md 中该 email 对应条目的 `last_update` 字段**最新的那个 campaign
+     - 无匹配 → orphan_inbound：写 merchant PROGRESS.md + sentinel report false + 退出
+
+   ※ 同一 campaign 内如果同一 email 出现多条记录（例如 KOL 换 username 后被重新添加），取 status 非终态（非 rejected / expired / no_contact）的活跃记录。
+
+4. 读本 campaign 的 `CONFIG.md`、`BRAND.md`、`CONVERSATIONS/{username}.md`
+
+5. **Layer 2 预检**（收到回信后、调 LLM 前）：
+   - 当前 KOL `rounds >= CONFIG.max_rounds` → escalate
+   - 对话时长 `>= CONFIG.max_days` → expired
+   - KOL 最新回信 body 匹配 escalation_keywords（先查 CONFIG 覆写，再 fallback 到 BRAND 默认） → escalate
+   - Idempotency：最后一条 inbound round 的 message_id ≠ 本次 in_reply_to → escalate
+
+6. **如果 Layer 2 触发**：
+   - 用 `escalate_fallback_v1` 模板渲染一封兜底回复
+   - 调 `scout outreach send` 发出去（带 in_reply_to / references）
+   - 更新 KOLS.md：status → needs_merchant_followup
+   - git commit
+   - `sentinel report --condition-met true --summary "layer2 escalate" --action-taken "..."`
+   - 退出
+
+7. **LLM 结构化决策**（每一轮都重新调一次 LLM，全量对话历史放进上下文）：
+   输入：
+   - campaign CONFIG.md 全文
+   - BRAND.md 全文
+   - CONVERSATIONS/{username}.md 全文
+   - 最新 KOL 回信
+   - TEMPLATES.md 里 counter_offer_v1 / deal_confirmation_v1 / escalate_fallback_v1 的变量列表
+
+   输出（结构化 JSON）：
+   ```json
+   {
+     "action": "counter_offer | accept | decline | clarify | escalate",
+     "new_price": 200,
+     "final_price": 250,
+     "concessions": ["video_retention_90d"],
+     "template_id": "counter_offer_v1",
+     "template_vars": { },
+     "reasoning": "..."
+   }
+   ```
+
+8. **Layer 3 后验**（基于本 campaign CONFIG 的预算和条款，不跨 campaign）：
+   - `action ∈ {counter_offer, accept, decline, clarify, escalate}`
+   - 如果 `counter_offer`:
+     - `CONFIG.first_offer ≤ new_price ≤ CONFIG.max_price`
+     - `new_price - previous_offer ≤ CONFIG.max_step`
+   - 如果 `accept`:
+     - `CONFIG.first_offer ≤ final_price ≤ CONFIG.max_price`
+     - `committed_so_far (本 campaign KOLS.md 中 deal_reached 的 offer 总和) + final_price ≤ CONFIG.total_budget`
+   - `concessions ⊆ CONFIG.allowed_uses ∪ {'video_retention_N'}`
+   - `template_id ∈ 本 campaign TEMPLATES.md 的模板列表`
+   - 任一不过 → 降级为 escalate（走 Layer 2 失败分支）
+
+9. 模板渲染：套对应模板 + template_vars → 最终 body
+
+10. **Layer 4 终检**：
+    - body 不含 forbidden_phrases（CONFIG 覆写优先，fallback BRAND）
+    - body 长度 ≤ 2000 字符
+    - 不过 → 降级为 escalate
+
+11. Edit `CONVERSATIONS/{username}.md` 追加 Round N (response sent)，包括完整 LLM decision JSON 供审计
+
+12. 调 `scout outreach send`：
+    - 带 `in_reply_to = KOL 的 message_id`
+    - 带 `references = 原 references 追加 KOL 的 message_id`
+    - 拿到新 message_id 写回 CONVERSATIONS
+
+13. Edit `KOLS.md`：更新 rounds、current_offer、last_update、status
+    - 如果 action == accept：status → deal_reached
+    - 否则 status → awaiting_reply
+
+14. 读 `MERCHANT_LIMITS.md`，sent_today += 1，写回
+
+15. 如果 action == accept：
+    - 额外调 `scout outreach send` 发 deal_confirmation_v1 的 recap 给**商家注册邮箱**
+    - 在 merchant PROGRESS.md 记录 `[campaignId] DEAL REACHED with @username ($final_price)`
+
+16. `git commit -m "[{campaignId}] round N {action} with @{username}"`
+
+17. 追加 campaign PROGRESS.md
+
+18. `sentinel report --condition-met true --summary "..." --action-taken "..."`
+
+---
+
+## 流程 E：查询进度
+
+触发：商家说"KOL 进展如何" / "查看 {X} 状态"。
+
+1. 读 `CAMPAIGNS.md`
+2. 解析范围：
+   - 商家指定 campaign → 只汇报该 campaign
+   - 未指定 + 只有一个 active → 只汇报该 campaign
+   - 未指定 + 多个 active → 先汇报跨 campaign 摘要，再提示可说"查看 {X}"
+
+3. **跨 campaign 摘要**：
+   - 对每个 campaign 读 KOLS.md 统计 in_flight / deal_reached / needs_merchant_followup
+   - 读 CONFIG 的 total_budget，算已承诺预算
+   - 读 MERCHANT_LIMITS.md 今日 sent
+   - 汇报表格（markdown）
+
+4. **单 campaign 详情**：
+   - 读 KOLS.md 按 status 分桶统计
+   - 对每个 needs_merchant_followup：读 CONVERSATIONS/{username}.md 最后一轮，总结 KOL 的诉求
+   - 读 campaign PROGRESS.md 最近 5 条
+   - 汇报（markdown 表格 + 待办列表）
+
+---
+
+## 核心规则 / 必须遵守
+
+- **git commit 节奏**：每个原子操作后立即 commit（一个 KOL 的一次发送 / 一个 CONFIG 段 / 一次状态更新），不要批量 commit
+- **LLM 只填变量，不写 body**：所有对外邮件必须走模板渲染；直接生成 body 的 bypass 护栏
+- **运行时零打扰**：任何护栏不过都**不要**问商家，降级为发 escalate_fallback + 标记 needs_merchant_followup
+- **单会话单任务**：一次 session 只做一种动作（onboarding / 发 outreach / 处理回信 / 查询），完成后 git commit 并退出
+- **文件路径**：所有路径都在 `~/kol-outreach/` 之下；运行前先 `cd ~/kol-outreach`
+- **幂等性**：处理回信前检查 `in_reply_to` 是否等于最后一条 outbound 的 message_id；不等则 escalate（防止重复投递）
+
+## 错误处理要点
+
+| 故障 | 处理 |
+|---|---|
+| `scout outreach send` 返回 `ok: false` | Edit KOLS.md status=send_error，记 PROGRESS.md，不中断其他 KOL 的处理 |
+| LLM 结构化输出格式错误 | 重试 1 次；仍失败降级为 escalate |
+| git commit 失败 | 说明冲突原因，修复后重试；不要擅自 reset |
+| 当前 UTC 日期跨天 | 读 MERCHANT_LIMITS.md 时先归档昨天计数再继续 |
+
+## 相关工具
+
+- `scout tiktok creators` — 发现 KOL
+- `scout tiktok creator-products` — 获取 KOL 最近内容用于个性化
+- `scout outreach send` — 发送邮件（内部调 Resend）
+- `scout outreach brand-slug check|claim` — 验证/锁定 brand_slug
+- `sentinel report` — 回信处理结束时汇报结果（仅在 `[KOL_INBOUND]` 触发的会话里）

package/.claude/skills/kol-outreach/template/campaign/CONFIG.md

@@ -0,0 +1,60 @@
+# Campaign: {campaignId}
+
+<!-- 首次 campaign onboarding 时由 skill 对话式填入，之后可手动编辑 -->
+<!-- 品牌素材继承自 ../../BRAND.md，本文件只有覆写时才会重复 -->
+
+## Campaign 元信息
+- campaignId:
+- 创建时间:
+- 状态: active    <!-- active | paused | completed | archived -->
+
+## 商品
+- 商品 ID 或 URL:
+- 商品标题:
+- 核心卖点（3-5 条）:
+- 目标受众（年龄/性别/兴趣/地区）:
+- 样品可寄送地区:
+
+## 目标 KOL 画像
+- 地区（scout --country）:
+- 粉丝量区间（scout --follower-count）:
+- 品类关键词:
+- 本 campaign 目标合作 KOL 数量:
+
+## 预算与报价（per-campaign 独立）
+- max_price:
+- target_price:
+- first_offer:
+- max_step:
+- total_budget:
+
+## 合作条款边界
+- min_retention_days:
+- allowed_uses:
+  - [ ] 商家官方账号转发
+  - [ ] 二创
+  - [ ] 付费广告投放
+- payment_schedule:
+- 样品政策:
+
+## 兜底话术覆写（可选，留空则继承 BRAND.md）
+- commission_request:
+- contract_request:
+- invoice_request:
+- negative_tone:
+
+## 品牌素材覆写（可选，留空则继承 BRAND.md）
+- contact_name:
+- brand_pitch:
+
+## 运行参数（per-campaign 独立）
+- max_rounds: 5
+- max_days: 14
+- max_concurrent_kols: 30
+- escalation_keywords 覆写 (可选):
+  - English:
+  - 中文:
+- forbidden_phrases 覆写 (可选):
+- follow_up_enabled: false   <!-- v1.1 -->
+
+<!-- 注意: max_daily_sends 在 ../../MERCHANT_LIMITS.md，是 merchant 级配额 -->

package/.claude/skills/kol-outreach/template/campaign/KOLS.md

@@ -0,0 +1,6 @@
+# KOL 索引
+
+<!-- 本 campaign 下所有被 skill 接触过的 KOL -->
+
+| username | followers | engagement | email | status | offer | rounds | last_update | conversation |
+|---|---|---|---|---|---|---|---|---|

package/.claude/skills/kol-outreach/template/campaign/PROGRESS.md

@@ -0,0 +1,3 @@
+# KOL Outreach Progress Log — {campaignId}
+
+<!-- 每次 skill session 末尾追加一条，最新的在最上面 -->

package/.claude/skills/kol-outreach/template/campaign/TEMPLATES.md

@@ -0,0 +1,88 @@
+# Email Templates
+
+<!-- LLM 只填变量（{placeholder}），不写 body 。每个模板有固定的骨架。 -->
+
+## first_outreach_v1
+
+**Subject**: Collaboration opportunity with {brand_name}
+
+**Body**:
+Hi {kol_first_name},
+
+{opener_line}
+
+I'm {contact_name} from {brand_name} ({brand_website}). We make
+{product_one_liner} and your audience seems to be a great fit because
+{fit_reason}.
+
+We'd love to work with you on a TikTok video featuring our {product_name}.
+Here's what we're proposing:
+
+- Fee: ${first_offer}
+- Deliverable: 1 TikTok video, kept on your profile for at least
+  {min_retention_days} days
+- We'll ship you a free sample to get you started
+
+If this sounds interesting, just reply and we can work out the details.
+
+Best,
+{contact_name}
+{brand_name}
+
+---
+
+## counter_offer_v1
+
+**Body**:
+Hi {kol_first_name},
+
+Thanks for the quick reply!
+
+{acknowledge_line}
+
+We're a bit tighter on budget, but we can go up to **${new_price}** for
+the collaboration. {concession_line}
+
+Would that work for you?
+
+Best,
+{contact_name}
+
+---
+
+## escalate_fallback_v1
+
+<!-- 用于 Layer 2/3/4 任一护栏触发时的兜底回复 -->
+
+**Body**:
+Hi {kol_first_name},
+
+Thanks for your note. This is something I'd like to check with our team
+before confirming. I'll get back to you within 1-2 business days.
+
+Best,
+{contact_name}
+{brand_name}
+
+---
+
+## deal_confirmation_v1
+
+**Body**:
+Hi {kol_first_name},
+
+Great — we have a deal at **${final_price}**. Here's a summary for your
+records:
+
+- Fee: ${final_price}
+- Deliverable: 1 TikTok video
+- Video retention: at least {min_retention_days} days
+- Payment: {payment_schedule}
+- We'll ship the sample to {shipping_address_request}
+
+Please reply with your shipping address and any PayPal/bank info you
+prefer for payment. We'll take it from there.
+
+Thanks for working with us!
+{contact_name}
+{brand_name}

package/.claude/skills/kol-outreach/template/merchant/BRAND.md

@@ -0,0 +1,36 @@
+# 商家品牌素材
+
+<!-- 商家首次使用 skill 时 onboarding 一次，之后所有 campaign 复用 -->
+<!-- 单个 campaign 需要不同品牌身份时可在该 campaign 的 CONFIG.md 里覆写 -->
+
+## 品牌基础
+- brand_name:
+- brand_slug:                      <!-- 用作发件邮箱 local part，全局唯一 -->
+- brand_website:
+- brand_social:
+- default_contact_name:
+- default_brand_pitch:
+
+## 默认兜底话术（非白名单话题的预设回复，可被 campaign 覆写）
+- default_commission_request:
+- default_contract_request:
+- default_invoice_request:
+- default_negative_tone:
+
+## 默认升级关键词（可被 campaign 覆写，必须中英双语）
+- default_escalation_keywords_en:
+  - contract
+  - lawyer
+  - exclusive
+  - refund
+  - lawsuit
+  - NDA
+- default_escalation_keywords_zh:
+  - 合同
+  - 律师
+  - 独家
+  - 退款
+  - 投诉
+  - 骗子
+
+## 默认禁用词 (default_forbidden_phrases):

package/.claude/skills/kol-outreach/template/merchant/CAMPAIGNS.md

@@ -0,0 +1,6 @@
+# Campaigns Index
+
+<!-- 商家所有 campaign 一览。每次新建 campaign 时 skill 追加一行 -->
+
+| campaignId | product_title | status | kols_in_flight | deals_reached | budget_used | created_at |
+|---|---|---|---|---|---|---|

package/.claude/skills/kol-outreach/template/merchant/MERCHANT_LIMITS.md

@@ -0,0 +1,16 @@
+# Merchant-level Rate Limits
+
+<!-- 所有 campaign 共享的 sending 配额 -->
+<!-- skill 在每次发信前读/写这个文件，git commit -->
+
+## 配置
+- max_daily_sends: 50
+- tz: UTC
+
+## 今日发信计数
+- date_utc:
+- sent_today: 0
+
+## 最近 10 天统计（滚动，由 skill 自动追加）
+| date_utc | sent_count |
+|---|---|

package/.claude/skills/kol-outreach/template/merchant/PROGRESS.md

@@ -0,0 +1,4 @@
+# KOL Outreach Merchant Log
+
+<!-- 跨 campaign 的里程碑日志，最新的在最上面 -->
+<!-- 格式：YYYY-MM-DD HH:mm — [campaignId] 事件 -->

package/.claude/skills/kol-outreach/template/merchant/README.md

@@ -0,0 +1,20 @@
+# KOL Outreach Workspace
+
+This directory is your KOL 建联 workspace. Each file is markdown and git-tracked.
+
+## Layout
+
+- `BRAND.md` — your brand info, shared across all campaigns
+- `MERCHANT_LIMITS.md` — cross-campaign sending rate limit
+- `CAMPAIGNS.md` — index of all your campaigns
+- `PROGRESS.md` — merchant-level log (one line per milestone)
+- `campaigns/{campaignId}/` — one directory per campaign
+
+## What you can edit by hand
+
+Any markdown file. The skill will read your edits on the next invocation.
+
+## How to add a new campaign
+
+Say "帮我给 {product} 找 KOL" to the skill — it walks you through onboarding
+and creates a new `campaigns/{campaignId}/` directory from the template.