@optima-chat/optima-agent 0.8.98 → 0.8.99

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

@@ -1,55 +1,70 @@
 ---
 name: kol-outreach
-description: "KOL 建联全自动化：从 TikTok 发现潜在 KOL、提取 bio email、发送个性化 outreach、自动谈判价格与条款。当用户说'帮我找 KOL'、'{产品} KOL 建联'、'KOL 进展如何'，或收到系统触发的 [KOL_INBOUND:...] 或 [KOL_INBOUND] 标记时，使用此 skill。"
+description: "KOL 建联全自动化：从 TikTok 发现潜在 KOL、提取 bio email、发送个性化 outreach、自动处理 KOL 回信并维护本地状态。当用户说'帮我找 KOL'、'{产品} KOL 建联'、'KOL 进展如何'，或消息中出现 [KOL_INBOUND:{campaignId}] / [KOL_INBOUND] 时，使用此 skill。"
 ---
 
-# KOL Outreach Skill
+# KOL 建联
 
-本 skill 帮助商家在 TikTok 上端到端完成 KOL 建联：发现 → 触达 → 谈判 →
-意向交付，运行时零打扰，所有决策参数在首次 onboarding 时固化。
+## 概述
 
-## 核心工作目录
+本 skill 用于在 TikTok 上完成 KOL 建联的完整操作流程：发现、触达、回信处理、进度维护。
 
-所有状态都在 `~/kol-outreach/`，整个目录是一个 git repo。结构：
+- 所有业务状态都保存在 `~/kol-outreach/`
+- 运行时默认零打扰，优先按已固化配置执行
+- 本 skill 只负责操作，不解释系统实现
 
-```
-~/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 的启动流程
+- outbound 只用 `scout outreach send`
+- onboarding 时只用 `scout outreach brand-slug check|claim`
+- 所有业务状态只从 `~/kol-outreach/` 读取和写回
+- 单会话单任务：每次 session 只做一种动作
+- 每次关键状态变更后都要 `git add` + `git commit`
+- 所有对外邮件都必须走模板渲染；LLM 只能产出结构化变量或结构化决策
 
-按顺序执行这些检查，决定本次 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。出错时可以精准回滚。
+- merchant 级
+  - `~/kol-outreach/BRAND.md`
+  - `~/kol-outreach/MERCHANT_LIMITS.md`
+  - `~/kol-outreach/CAMPAIGNS.md`
+  - `~/kol-outreach/PROGRESS.md`
+- campaign 级
+  - `~/kol-outreach/campaigns/{campaignId}/CONFIG.md`
+  - `~/kol-outreach/campaigns/{campaignId}/KOLS.md`
+  - `~/kol-outreach/campaigns/{campaignId}/TEMPLATES.md`
+  - `~/kol-outreach/campaigns/{campaignId}/PROGRESS.md`
+  - `~/kol-outreach/campaigns/{campaignId}/CONVERSATIONS/{username}.md`
+
+## Session 分流
+
+每次 session 开始时，按这个顺序判断要走哪条流程：
+
+1. 如果用户消息包含 `[KOL_INBOUND:{campaignId}]` 或 `[KOL_INBOUND]`，走「流程 D：KOL 回信处理」
+2. 否则，检查 `~/kol-outreach/BRAND.md` 是否存在
+   - 不存在：先走「流程 A：Merchant onboarding」，再走「流程 B：Campaign onboarding」
+3. 如果 merchant 已存在，则按用户意图分流
+   - 用户要为新产品建联：走「流程 B：Campaign onboarding」
+   - 用户要开始建联或发送 outreach：走「流程 C：发现 KOL + 首发 Outreach」
+   - 用户要查看状态或进展：走「流程 E：查询进度」
+
+## Inbound 前置条件
+
+进入流程 D 前，先检查：
+
+1. `BRAND.md`
+2. 对应 campaign 目录
+3. 可匹配的 `KOLS.md` / `CONVERSATIONS/*.md`
+
+缺任何一项，都不要继续正常谈判；直接转状态恢复或人工跟进。
 
 ---
 
-## 流程 A：Merchant onboarding（只发生一次）
+## 流程 A：商家初始化
 
-1. 创建工作目录：
+1. 初始化工作目录：
 
    ```bash
    mkdir -p ~/kol-outreach/campaigns
@@ -57,37 +72,38 @@ description: "KOL 建联全自动化：从 TikTok 发现潜在 KOL、提取 bio
    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`
+2. 填 `BRAND.md`
+   - 询问：`brand_name`
+   - 从 `brand_name` 生成 kebab-case 的 `brand_slug` 建议
+   - 调 `scout outreach brand-slug check {slug}`
+   - 如果可用，让商家确认；如果被占用，让商家从建议里选或自己改
+   - 成功后调 `scout outreach brand-slug claim`
+   - 继续询问：`brand_website`、`brand_social`、`default_contact_name`、`default_brand_pitch`
+   - 提供默认兜底话术和默认双语 `escalation_keywords`，让商家确认或修改
+   - 写回 `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"`
+3. 填 `MERCHANT_LIMITS.md`
+   - 默认 `max_daily_sends: 50`
+   - 初始化 `sent_today: 0`
+   - 初始化 `date_utc: $(date -u +%Y-%m-%d)`
+   - 写回并 commit
 
-4. 告诉商家：商家级配置完成，现在为第一个商品创建 campaign，进入流程 B。
+4. 告诉商家：merchant 级配置已完成，继续创建第一个 campaign。
 
 ---
 
-## 流程 B：Campaign onboarding（每次新建 campaign）
+## 流程 B：创建 Campaign
 
-1. 确定 campaignId：
-   - 询问商家要为哪个商品建联（可列出他的 Optima 店铺商品作为选项）
-   - 从商品标题生成 kebab-case slug 建议（"Titanium Travel Tumbler" → "titanium-tumbler"）
-   - 校验：与 `CAMPAIGNS.md` 现有 campaign 不重复；匹配 `^[a-z0-9][a-z0-9-]{0,29}$`
-   - 告诉商家建议值，让他确认或改
+1. 确定 `campaignId`
+   - 询问商家要为哪个商品建联
+   - 从商品标题生成 kebab-case slug 建议
+   - 校验：
+     - 与 `CAMPAIGNS.md` 现有 campaign 不重复
+     - 匹配 `^[a-z0-9][a-z0-9-]{0,29}$`
+   - 让商家确认或修改
 
-2. 创建 campaign 目录：
+2. 创建 campaign 目录
 
    ```bash
    mkdir -p ~/kol-outreach/campaigns/{campaignId}
@@ -95,277 +111,340 @@ description: "KOL 建联全自动化：从 TikTok 发现潜在 KOL、提取 bio
    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）
+3. 分段填写 `CONFIG.md`
+   - 依次填写：
+     - campaign 元信息
+     - 商品
+     - 目标 KOL 画像
+     - 预算与报价
+     - 合作条款边界
+     - 兜底话术覆写
+     - 运行参数
+   - 严格校验：
+     - `max_price >= target_price >= first_offer`
+     - `max_step <= max_price - first_offer`
+     - `total_budget >= max_price`
+   - 任一不满足：说明原因，给出调整建议，重新问
+   - 每个大段写完后都要写文件并 commit
+
+4. 更新 `CAMPAIGNS.md`
+   - 追加一行新 campaign，`status=active`
 
 5. `git commit -m "[{campaignId}] campaign ready"`
 
-6. 告诉商家 campaign 已就绪，问他是否立即开始发现 KOL。
+6. 告诉商家 campaign 已就绪，并询问是否立即开始发现 KOL。
 
 ---
 
-## 流程 C：发现 KOL + 首发 Outreach
+## 流程 C：发现 KOL 与首发 Outreach
+
+先按这个顺序执行：
 
-触发：用户说"给 {campaign} 开始建联" / "为 {campaign} 发送 outreach"。
-如果商家没指定 campaign，读 `CAMPAIGNS.md`：
-- 只有一个 active → 用它
-- 多个 active → 列出让商家选
+- 先定 campaign
+- 再检查并行上限和 merchant 日配额
+- 先发现 KOL，再补拉 bio / email
+- LLM 只产出模板变量，不直接写邮件正文
+- 每发出一封邮件，都要立刻写回并 commit
 
-1. 读配置：
-   - `CONFIG.md`（目标画像/运行参数/预算）
-   - `KOLS.md`（已存在 KOL 列表）
-   - `BRAND.md`（后面生成 outreach 需要）
-   - `MERCHANT_LIMITS.md`（今日发信数）
+1. 确定 campaign
+   - 如果用户指定 campaign，用指定值
+   - 如果用户未指定，读 `CAMPAIGNS.md`
+     - 只有一个 active：用它
+     - 多个 active：列出让商家选
 
-2. 并行上限预检：
+2. 读取所需文件
+   - `CONFIG.md`
+   - `KOLS.md`
+   - `BRAND.md`
+   - `MERCHANT_LIMITS.md`
+   - `TEMPLATES.md`
+
+3. 检查并行上限
    - `in_flight = KOLS.md 中 status ∈ {awaiting_reply, in_progress} 的行数`
    - `available_slots = max_concurrent_kols - in_flight`
-   - `available_slots <= 0` → 告诉商家"当前 {in_flight} 个 KOL 在谈，已达并行上限。等 KOL 进入终态后再继续。"退出
+   - `available_slots <= 0`：告诉商家当前已达并行上限，退出
    - `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，写回
+4. 检查 merchant 日发信配额
+   - 读取 `MERCHANT_LIMITS.md`
+   - 如果 UTC 日期变了，先归档昨天计数，再把 `sent_today` 重置为 0
    - `daily_budget = max_daily_sends - sent_today`
-   - `daily_budget <= 0` → 告诉商家"今日所有 campaign 合计发信配额已用完"，退出
+   - `daily_budget <= 0`：告诉商家今日配额已用完，退出
    - `本轮发送量 = min(target_new, daily_budget)`
 
-4. 调 `scout tiktok creators` 发现 KOL：
+5. 调 `scout tiktok creators`
 
    ```bash
    scout tiktok creators \
-     --follower-count "<CONFIG.powder_count_range>" \
+     --follower-count "<CONFIG.follower_count_range>" \
      --country "<CONFIG.region>" \
      --limit <本轮发送量 * 3> \
      --format json
    ```
 
-   （×3 给过滤留空间）
-
-5. 过滤：
-   - engagement_rate < 2% 丢弃
-   - 已在 KOLS.md 的 username 丢弃
+6. 过滤候选人
+   - `engagement_rate < 2%` 丢弃
+   - 已在 `KOLS.md` 的 `username` 丢弃
    - 粉丝量不在目标区间的丢弃
 
-6. 对每个候选 KOL：
-   - 调 `scout tiktok creator-products @username --limit 5` 获取最近视频（用于生成开场白）
-   - 如果 scout 的 creators 响应 **没有返回 bio**，也从这里拉（见 probe Task 0.2）
-   - 用正则从 bio 抠 email：
+7. 补拉 bio / email 并写 `KOLS.md`
+   - 对每个候选 KOL 调 `scout tiktok creator-products @username --limit 5`
+   - 如果 creators 结果没带 bio，就从这里补拉
+   - 用正则从 bio 提取 email
+   - 有 email：
+     - 追加到 `KOLS.md`
+     - `status=pending_outreach`
+   - 没 email：
+     - 追加到 `KOLS.md`
+     - `status=no_contact`
+   - `git commit -m "[{campaignId}] discovered N KOLs"`
 
-     ```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"
+8. 发送首发 outreach
+   - 只处理 `status=pending_outreach`，并限制在本轮发送量内
+   - 读取 `TEMPLATES.md` 中的 `first_outreach_v1`
+   - 让 LLM 只输出模板变量 JSON，例如：
+
+     ```json
+     {
+       "kol_first_name": "...",
+       "opener_line": "...",
+       "fit_reason": "...",
+       "product_one_liner": "..."
+     }
      ```
 
-   - 有 email → 追加到 KOLS.md，status=pending_outreach
-   - 没 email → 追加到 KOLS.md，status=no_contact
-   - `git commit -m "[{campaignId}] discovered N KOLs"`
+   - 用模板渲染正文，不要直接自由写 body
+   - 终检：
+     - body 不含 `forbidden_phrases`
+     - body 长度 `<= 2000`
+   - 任一不过：
+     - 写 `KOLS.md` 为 `send_error`
+     - 记 `PROGRESS.md`
+     - 跳过该 KOL
 
-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
-     ```
+9. 调 `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}"`
+   ```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
+   ```
 
-8. 追加本 campaign 的 PROGRESS.md；重要事件同步追加 merchant PROGRESS.md
+10. 写回状态
+    - 在 `CONVERSATIONS/{username}.md` 追加 Round 1
+    - 把返回的 `message_id` 写入 conversation
+    - 更新 `KOLS.md`
+      - `pending_outreach -> awaiting_reply`
+      - `offer = first_offer`
+    - 更新 `MERCHANT_LIMITS.md`
+      - `sent_today += 1`
+    - 追加本 campaign 的 `PROGRESS.md`
+    - 重要事件同步追加 merchant `PROGRESS.md`
+    - `git commit -m "[{campaignId}] outreach sent to @{username}"`
 
-9. 告诉商家本次发送结果。
+11. 告诉商家本次发送结果。
 
 ---
 
-## 流程 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
+## 流程 D：处理 KOL 回信
+
+先按这个顺序执行：
+
+- 先确定 campaign 和 KOL
+- 先做预检，再决定是否调用 LLM
+- LLM 只输出结构化决策，不直接写邮件正文
+- 任何校验不过都降级为 `escalate`
+- 每轮处理完都要写回文件、commit，并调用 `sentinel report`
+
+1. 读取本次 inbound 的消息内容
+   - 从当前消息中读取：
+     - `From`
+     - `Subject`
+     - `Message-ID`
+     - `In-Reply-To`
+     - `References`
+     - `Body`
+
+2. 确定 campaign
+   - 如果消息包含 `[KOL_INBOUND:{campaignId}]`：只处理该 campaign
+   - 如果消息包含 `[KOL_INBOUND]`：稍后在步骤 3 通过 `from_email` 匹配 campaign
+
+3. 按 `from_email` 匹配 KOL
+   - `campaignId` 已知：只读该 campaign 的 `KOLS.md`
+   - `campaignId` 未知：遍历 `~/kol-outreach/campaigns/*/KOLS.md`
+   - 匹配结果：
+     - 唯一匹配：继续
+     - 多个匹配：选 `last_update` 最新的 campaign
+     - 无匹配：按 orphan inbound 处理并退出
+   - 同一 campaign 内同一 email 有多条记录时，取 `status` 非终态的活跃记录
+
+4. 读取所需文件
+   - `CONFIG.md`
+   - `BRAND.md`
+   - `CONVERSATIONS/{username}.md`
+
+5. 先做预检
+   - `rounds >= CONFIG.max_rounds`：`escalate`
+   - 对话时长 `>= CONFIG.max_days`：`expired`
+   - 最新回信 body 命中 `escalation_keywords`：`escalate`
+   - 最后一条 inbound round 的 `message_id` 与本次 `in_reply_to` 不一致：按幂等性异常处理
+
+6. 如果预检触发异常
+   - 用 `escalate_fallback_v1` 模板渲染兜底回复
+   - 调 `scout outreach send` 发出回复
+   - 更新 `KOLS.md` 为 `needs_merchant_followup`
+   - 写 `PROGRESS.md`
+   - `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": "..."
-   }
-   ```
+7. 调用 LLM 生成结构化决策
+   - 输入：`CONFIG.md`、`BRAND.md`、`CONVERSATIONS/{username}.md`、最新回信、模板变量列表
+   - 输出 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）：
+8. 校验 LLM 输出
    - `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 失败分支）
+   - 如果 `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 + final_price <= CONFIG.total_budget`
+   - `concessions` 只能来自允许集合
+   - `template_id` 必须存在于本 campaign 的 `TEMPLATES.md`
+   - 任一不通过：降级为 `escalate`
+
+9. 渲染模板并终检
+   - 用 `template_id + template_vars` 渲染最终 body
+   - 终检：
+     - body 不含 `forbidden_phrases`
+     - body 长度 `<= 2000`
+   - 不通过：降级为 `escalate`
+
+10. 发送回复
+    - 调 `scout outreach send`
+    - 带上：
+      - `in_reply_to = KOL 的 message_id`
+      - `references = 原 references + KOL 的 message_id`
+    - 拿到新 `message_id`
+
+11. 写回状态
+    - 在 `CONVERSATIONS/{username}.md` 追加新一轮，保留完整 LLM decision JSON
+    - 更新 `KOLS.md`
+      - 更新 `rounds`
+      - 更新 `current_offer`
+      - 更新 `last_update`
+      - `accept -> deal_reached`
+      - 其他正常回复 -> `awaiting_reply`
+    - 更新 `MERCHANT_LIMITS.md`
+      - `sent_today += 1`
+    - 如果 `action == accept`
+      - 给商家注册邮箱发送 `deal_confirmation_v1`
+      - 在 merchant `PROGRESS.md` 记录达成合作
+    - 追加 campaign `PROGRESS.md`
+    - `git commit -m "[{campaignId}] round N {action} with @{username}"`
+
+12. 调 `sentinel report`
 
-9. 模板渲染：套对应模板 + template_vars → 最终 body
-
-10. **Layer 4 终检**：
-    - body 不含 forbidden_phrases（CONFIG 覆写优先，fallback BRAND）
-    - body 长度 ≤ 2000 字符
-    - 不过 → 降级为 escalate
+   ```bash
+   sentinel report --condition-met true --summary "..." --action-taken "..."
+   ```
 
-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
+## 流程 E：查询进展
 
-13. Edit `KOLS.md`：更新 rounds、current_offer、last_update、status
-    - 如果 action == accept：status → deal_reached
-    - 否则 status → awaiting_reply
+1. 读 `CAMPAIGNS.md`
 
-14. 读 `MERCHANT_LIMITS.md`，sent_today += 1，写回
+2. 确定范围
+   - 用户指定 campaign：只汇报该 campaign
+   - 未指定且只有一个 active：只汇报该 campaign
+   - 未指定且有多个 active：先给跨 campaign 摘要，再提示用户可继续查看单个 campaign
+
+3. 跨 campaign 摘要
+   - 对每个 campaign 读 `KOLS.md`
+   - 统计：
+     - `in_flight`
+     - `deal_reached`
+     - `needs_merchant_followup`
+   - 读 `CONFIG.md` 的 `total_budget`，计算已承诺预算
+   - 读 `MERCHANT_LIMITS.md` 的今日 `sent_today`
+   - 以 markdown 表格汇报
+
+4. 单 campaign 详情
+   - 读 `KOLS.md` 按 `status` 分桶
+   - 对每个 `needs_merchant_followup`，读对应 `CONVERSATIONS/{username}.md`，总结 KOL 诉求
+   - 读 campaign `PROGRESS.md` 最近 5 条
+   - 输出：
+     - 关键统计
+     - 需要人工处理的事项
+     - 最近进展
 
-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
+- `scout outreach send` 返回 `ok: false`
+  - 更新 `KOLS.md` 为 `send_error`
+  - 记 `PROGRESS.md`
+  - 不要中断其他 KOL 的处理
 
-18. `sentinel report --condition-met true --summary "..." --action-taken "..."`
+- LLM 结构化输出格式错误
+  - 重试 1 次
+  - 仍失败：降级为 `escalate`
 
----
+- unknown campaign
+  - 写 merchant `PROGRESS.md`
+  - `sentinel report --condition-met false --summary "unknown campaign"`
+  - 退出
 
-## 流程 E：查询进度
+- orphan inbound / unknown KOL
+  - 写对应 `PROGRESS.md`
+  - `sentinel report --condition-met false`
+  - 退出
 
-触发：商家说"KOL 进展如何" / "查看 {X} 状态"。
+- git commit 失败
+  - 说明冲突原因
+  - 修复后重试
+  - 不要擅自 reset
 
-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 表格 + 待办列表）
+- UTC 日期跨天
+  - 读 `MERCHANT_LIMITS.md` 时先归档昨天计数，再继续
 
 ---
 
-## 核心规则 / 必须遵守
-
-- **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`
+- `scout tiktok creator-products`
+- `scout outreach send`
+- `scout outreach brand-slug check|claim`
+- `sentinel report`
 
-## 相关工具
+不要这样做：
 
-- `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]` 触发的会话里）
+- 不要绕过模板直接自由写外发邮件
+- 不要跳过本地 workspace 状态检查
+- 不要一次 session 混做多个流程
+- 不要修改不属于本次任务的 campaign 状态