tt-help-cli-ycl 1.4.3 → 1.4.5

package/src/watch/tag-service.js

@@ -2,6 +2,7 @@
  * Tag 发现与打分服务
  * - LLM 调用与 prompt 组装
  * - 单国家标签发现（discoverTagsForCountry）
+ * - 自闭环：健康检查 → 数据清理 → niche 切换 → 生成 → 记录
  * - 标签打分（scoreTag / scoreTagBatch）
  */
 
@@ -31,7 +32,7 @@ export function getLang(country) {
 
 // ====== LLM 调用 ======
 
-export async function callLLM(prompt) {
+export async function callLLM(prompt, temperature = 0.7) {
   const apiKey = process.env.APIKEY || "";
   const { fetch } = await import("undici");
 
@@ -45,7 +46,7 @@ export async function callLLM(prompt) {
       model: LLM_MODEL,
       messages: [{ role: "user", content: prompt }],
       max_tokens: 1024,
-      temperature: 0.7,
+      temperature,
     }),
   });
 
@@ -86,28 +87,30 @@ export function parseTagsFromResponse(content) {
  */
 export function parseDiscoverResponse(content) {
   let strategy = null;
+  let niche = null;
   let tags = [];
 
   try {
     const parsed = JSON.parse(content);
 
-    // 新格式: { strategy, tags }
+    // 新格式: { strategy, niche, tags }
     if (parsed.strategy && Array.isArray(parsed.tags)) {
       strategy = parsed.strategy;
+      niche = parsed.niche || null;
       tags = parsed.tags.map(normalizeTag).filter((t) => t && t.length >= 2);
-      return { strategy, tags };
+      return { strategy, niche, tags };
     }
 
     // 旧格式: 纯数组
     if (Array.isArray(parsed)) {
       tags = parsed.map(normalizeTag).filter((t) => t && t.length >= 2);
-      return { strategy, tags };
+      return { strategy, niche, tags };
     }
 
     // 旧格式: { tags: [...] }
     if (Array.isArray(parsed.tags)) {
       tags = parsed.tags.map(normalizeTag).filter((t) => t && t.length >= 2);
-      return { strategy, tags };
+      return { strategy, niche, tags };
     }
   } catch {
     // JSON 解析失败，尝试从文本中提取
@@ -116,6 +119,10 @@ export function parseDiscoverResponse(content) {
     if (strategyMatch) {
       strategy = strategyMatch[1];
     }
+    const nicheMatch = content.match(/"niche"\s*:\s*"([^"]+)"/);
+    if (nicheMatch) {
+      niche = nicheMatch[1];
+    }
   }
 
   // 降级：从文本行中提取 tags
@@ -127,7 +134,7 @@ export function parseDiscoverResponse(content) {
     }
   }
 
-  return { strategy, tags };
+  return { strategy, niche, tags };
 }
 
 // ====== Prompt 组装 ======
@@ -138,6 +145,11 @@ export function buildDiscoverPrompt(
   history,
   userPrompt,
   pastStrategies,
+  health,
+  nicheRecommendation,
+  hardRules = [],
+  existingCount = 0,
+  forceNicheSwitch = null,
 ) {
   const lang = getLang(country);
   const langNames = {
@@ -166,13 +178,36 @@ export function buildDiscoverPrompt(
           )}. Use these as reference for the STYLE and TYPE of tag that works — prefer commonly used words like these.`
       : "";
 
-  // 负样本：该国 dead tag
+  // 负样本：该国 dead tag（只传最近50个，避免 prompt 过长）
   const dead = history.dead || [];
+  const recentDead = dead.slice(0, 50);
   const deadHint =
-    dead.length > 0
-      ? `\nTags that failed for ${country} (found no matching users): ${dead.map((t) => t.tag).join(", ")}. Avoid these and similar patterns.`
+    recentDead.length > 0
+      ? `\nTags that RECENTLY failed for ${country} (found no matching users): ${recentDead.map((t) => t.tag).join(", ")}. Avoid these EXACT tags and similar patterns.`
+      : "";
+
+  // 高频重复 dead 标签警告（这些是反复生成又反复失败的）
+  const deadTagNames = new Set(dead.map((t) => t.tag));
+  const recentGenerated = (history.recentGenerated || []).filter((t) =>
+    deadTagNames.has(t),
+  );
+  const repeatedDeadHint =
+    recentGenerated.length > 0
+      ? `\n⚠️ These tags have been generated MULTIPLE TIMES and always fail — NEVER generate them again: ${recentGenerated.join(", ")}`
       : "";
 
+  // 语言模式分析：统计 dead 标签的语言分布
+  const langPatternHint = (() => {
+    if (dead.length < 20) return "";
+    const englishDead = dead.filter((t) => /^[a-zA-Z]+$/.test(t.tag)).length;
+    const localDead = dead.filter((t) => !/^[a-zA-Z]+$/.test(t.tag)).length;
+    const englishRatio = Math.round((englishDead / dead.length) * 100);
+    if (englishRatio > 60 && lang !== "en") {
+      return `\n⚠️ LANGUAGE WARNING: ${englishRatio}% of dead tags for ${country} are English-only words — they DON'T work in a ${langName}-speaking country. You MUST generate tags in ${langName} or bilingual (like greekshop, ελληνικαπροιοντα).`;
+    }
+    return "";
+  })();
+
   // 死因分析
   const errorPatterns = [
     ...new Set(dead.filter((t) => t.last_error).map((t) => t.last_error)),
@@ -216,6 +251,57 @@ Use this analysis to decide your strategy for this round.`;
       ? `\n⚠️ WARNING: Currently ${deadRatio}% of our generated tags fail (no real TikTok posts). This is critically high. You MUST be more conservative — only suggest hashtags you have HIGH CONFIDENCE actually exist on TikTok.`
       : "";
 
+  // ====== 自闭环：健康指标 & niche 推荐 ======
+  let healthHint = "";
+  let nicheHint = "";
+
+  if (health && health.healthStatus !== "healthy") {
+    const issuesText = health.issues.map((i) => `  - ${i}`).join("\n");
+    healthHint = `
+=== 🏥 Country Health Analysis (${health.healthStatus}) ===
+Country: ${health.country}
+Total tags: ${health.total} | Productive: ${health.productive} (${health.productiveRatio}%) | Dead: ${health.dead} (${health.deadRatio}%) | Scored: ${health.scored}
+Recent effectiveness: productive ${health.recentProductiveRatio}% | dead ${health.recentDeadRatio}% | empty rounds ${health.recentEmptyRounds}
+Saturation: ${health.saturation}%
+
+Issues detected:
+${issuesText}
+
+⚠️ Based on this health analysis, you MUST adjust your strategy:
+${health.healthStatus === "critical" ? "- Be EXTREMELY conservative — only suggest the most common, well-established hashtags\n- Focus on niches that have proven to work (see productive tags above)\n- Avoid experimental or creative combinations" : "- Be more conservative than usual — prioritize proven tag patterns\n- Try different niche directions that haven't been explored yet"}
+`;
+  }
+
+  if (nicheRecommendation) {
+    const uncoveredText = nicheRecommendation.uncovered
+      .slice(0, 5)
+      .map((n) => `${n.niche} (current: ${n.currentCoverage} tags)`)
+      .join(", ");
+    const saturatedText = nicheRecommendation.saturated
+      .map((n) => `${n.niche} (${n.currentCoverage} tags)`)
+      .join(", ");
+
+    nicheHint = `
+=== 🎯 Niche Direction Recommendation ===
+Uncovered niches (EXPLORE these — few existing productive tags): ${uncoveredText || "none remaining"}
+Saturated niches (AVOID these — already well-covered): ${saturatedText || "none saturated"}
+
+${nicheRecommendation.uncovered.length > 0 ? `Focus your tags on the UNCOVERED niches above. Generate hashtags related to those product/service categories in ${langName}.` : "All major niches are covered. Try hyper-local or seasonal trends, or very specific sub-categories."}
+`;
+  }
+
+  // ====== 自闭环：强制方向切换提示 ======
+  let forceNicheSwitchHint = "";
+  if (forceNicheSwitch) {
+    forceNicheSwitchHint = `
+=== 🔄 MANDATORY DIRECTION SWITCH ===
+⚠️ CRITICAL: The previous direction "${forceNicheSwitch.from}" has been exhausted — ${forceNicheSwitch.reason}.
+You MUST NOT generate tags in the "${forceNicheSwitch.from}" direction anymore.
+You MUST switch to the "${forceNicheSwitch.to}" direction: ${forceNicheSwitch.description}.
+Generate ONLY tags related to this new niche. Do NOT fall back to old patterns.
+`;
+  }
+
   return `You are discovering TikTok hashtags used by people who sell things in ${country}.
 
 ⛔ CRITICAL RULE: ONLY suggest hashtags that you are CONFIDENT actually exist on TikTok with real posts.
@@ -237,7 +323,19 @@ Think about the MOST COMMON hashtags that real sellers in ${country} use on TikT
 - Common seller identities (shop, boutique, small business, creator...)
 - Well-known community tags (support local, marketplace, second round...)
 
-${qualityWarning}${productiveHint}${deadHint}${errorHint}${userHint}${strategyReview}
+${qualityWarning}
+
+${
+  hardRules.length > 0
+    ? `
+=== ⛔ HARD RULES (from self-reflection — MUST follow these) ===
+These rules were generated by analyzing past failures and successes. Violating them will produce dead tags.
+${hardRules.map((r) => `  ${r.ruleType === "hard" ? "⛔" : "💡"} ${r.ruleText}`).join("\n")}
+`
+    : ""
+}
+
+${productiveHint}${deadHint}${repeatedDeadHint}${langPatternHint}${errorHint}${userHint}${strategyReview}${healthHint}${nicheHint}${forceNicheSwitchHint}
 
 ## Quality check before responding
 
@@ -245,18 +343,20 @@ For each tag you consider, ask yourself: "Have I actually seen this hashtag used
 
 ## Output format
 
-Return ONLY a JSON object with two fields:
+Return ONLY a JSON object with three fields:
 {
-  "strategy": "Your analysis (2-3 sentences). Acknowledge what worked/failed before and explain why your chosen tags are likely real and commonly used.",
+  "strategy": "Your analysis (2-3 sentences). Acknowledge what worked/failed before, explain why your chosen tags are likely real and commonly used, and state which niche direction you're targeting.",
+  "niche": "The primary niche category you focused on (e.g. 'fashion', 'food', 'handmade_crafts', 'electronics_tech', 'pets_animals', 'services_professional', 'marketplace_local')",
   "tags": ["tag1", "tag2", "tag3", "tag4", "..."]
 }
 
 Rules:
-- Brainstorm broadly — generate 12-15 distinct, diverse tag ideas covering different categories (selling verbs, product types, community tags, marketplace terms, seasonal trends)
+- Brainstorm broadly — generate at least ${Math.max(count * 3, 20)} distinct, diverse tag ideas covering different categories (selling verbs, product types, community tags, marketplace terms, seasonal trends). We already have ${existingCount} existing tags in our database, so many of your suggestions will be filtered out as duplicates — generate MORE than you think we need to ensure enough survive filtering.
 - We will filter duplicates and existing tags on our end, so explore freely
 - QUALITY over creativity — 3 real, commonly used tags beat 4 invented ones
 - NEVER invent compound words or translate concepts into hashtags
 - Prefer simpler, more common tags over hyper-specific ones
+- If health analysis shows saturation in certain niches, EXPLICITLY pivot to uncovered niches
 - Look for tags with broad appeal (many potential posters)`;
 }
 
@@ -272,45 +372,217 @@ export async function discoverTagsForCountry(
     return { country, error: `不支持的国家代码: ${country}` };
   }
 
+  // ====== 自闭环 Step 1: 健康检查 & 数据清理 ======
+  const {
+    getDiscoverRound,
+    getDiscoverEffectiveness,
+    getCountryHealth,
+    cleanupLowScoredTags,
+    cleanupStaleScoringTags,
+    cleanupErrorTags,
+    getActiveRules,
+  } = await import("./db-tags.js");
+
+  const health = getCountryHealth(country);
+  console.error(
+    `[tag-service] 🏥 ${country} health: ${health?.healthStatus || "unknown"} | deadRatio=${health?.deadRatio || "?"}% | productiveRatio=${health?.productiveRatio || "?"}% | saturation=${health?.saturation || "?"}%`,
+  );
+
+  // 根据健康状态执行数据清理
+  const cleanupActions = {};
+  if (health) {
+    // 清理超时 scoring tag（始终执行）
+    const staleResult = cleanupStaleScoringTags();
+    cleanupActions.staleScoringReset = staleResult.reset;
+
+    // 清理 error tag（始终执行）
+    const errorResult = cleanupErrorTags();
+    cleanupActions.errorReset = errorResult.reset;
+
+    // 低分 scored tag 清理：当 lowScored > 2x productive 时执行
+    if (health.lowScored > health.productive * 2) {
+      const lowResult = cleanupLowScoredTags(20);
+      cleanupActions.lowScoredCleanup = lowResult.cleaned;
+    }
+  }
+
+  // ====== 自闭环 Step 2: 自动 niche 切换 ======
+  let autoNichePrompt = null;
+  let nicheRecommendation = null;
+
+  if (
+    health &&
+    health.healthStatus !== "healthy" &&
+    health.nicheRecommendation
+  ) {
+    nicheRecommendation = health.nicheRecommendation;
+
+    // 当健康状态为 warning/critical 且有未覆盖 niche 时，自动切换
+    if (nicheRecommendation.uncovered.length > 0) {
+      const targetNiche = nicheRecommendation.uncovered[0];
+      const nicheDescriptions = {
+        fashion:
+          "clothing, shoes, accessories, vintage fashion, secondhand clothes",
+        food: "bakery, food delivery, local food, restaurant, cooking supplies",
+        handmade_crafts:
+          "handmade items, DIY crafts, ceramics, candles, resin art",
+        home_living:
+          "home decoration, furniture, interior design, cleaning services",
+        electronics_tech:
+          "electronics, gadgets, phones, computers, tech accessories",
+        pets_animals: "pet supplies, dog accessories, cat food, animal care",
+        beauty_health:
+          "beauty products, cosmetics, skincare, hair care, wellness",
+        books_collectibles:
+          "books, collectibles, vinyl records, trading cards, antiques",
+        services_professional:
+          "professional services, repair, cleaning, photography, florist",
+        marketplace_local:
+          "local market, marketplace, shop, boutique, online store",
+      };
+      autoNichePrompt = `Focus on the "${targetNiche.niche}" niche: ${nicheDescriptions[targetNiche.niche] || targetNiche.niche}. We have only ${targetNiche.currentCoverage} productive tags in this category — explore more hashtags in this direction.`;
+      console.error(
+        `[tag-service] 🎯 ${country} auto niche switch → ${targetNiche.niche} (coverage: ${targetNiche.currentCoverage})`,
+      );
+    }
+  }
+
+  // ====== 自闭环 Step 2b: 连续低效轮强制方向切换 ======
+  // 商品分类方向定义（用于强制切换）
+  const NICHE_CATEGORIES = {
+    fashion:
+      "clothing, shoes, accessories, vintage, secondhand, thrift, sneakers, jewelry",
+    food: "bakery, food delivery, restaurant, cooking, local food, cafe, patisserie, boulangerie",
+    handmade_crafts:
+      "handmade, DIY, crafts, ceramics, candles, resin art, macrame, pottery, weaving",
+    home_living:
+      "home decoration, furniture, interior design, cleaning, moving, renovation",
+    electronics_tech:
+      "electronics, gadgets, phones, computers, audio, gaming, chargers, accessories",
+    pets_animals:
+      "pet supplies, dog accessories, cat food, animal care, grooming, veterinary",
+    beauty_health:
+      "beauty, cosmetics, skincare, hair care, wellness, perfume, makeup, spa",
+    books_collectibles:
+      "books, collectibles, vinyl records, trading cards, antiques, coins, stamps",
+    services_professional:
+      "repair, cleaning, photography, florist, tutoring, legal, consulting, moving",
+    marketplace_local:
+      "local market, marketplace, shop, boutique, online store, flea market, bazaar",
+  };
+
+  let forceNicheSwitch = null;
+  if (health && health.consecutiveLowProductiveRounds >= 2) {
+    // 连续 ≥2 轮 productive=0，强制切换方向
+    // 找出当前 productive tag 覆盖最多的 niche（即当前方向）
+    const currentNiche =
+      nicheRecommendation?.saturated?.[0]?.niche || "marketplace_local";
+    // 找出覆盖最少的 niche 作为新方向
+    const targetNiche = nicheRecommendation?.uncovered?.[0]?.niche || "food";
+    forceNicheSwitch = {
+      from: currentNiche,
+      to: targetNiche,
+      reason: `连续 ${health.consecutiveLowProductiveRounds} 轮无有效产出`,
+      description: NICHE_CATEGORIES[targetNiche] || targetNiche,
+    };
+    console.error(
+      `[tag-service] 🔄 ${country} 强制方向切换: ${currentNiche} → ${targetNiche} (原因: 连续${health.consecutiveLowProductiveRounds}轮低效)`,
+    );
+  }
+
+  // 合并用户 prompt、自动 niche prompt 和强制方向切换
+  let effectiveUserPrompt = userPrompt;
+  if (forceNicheSwitch) {
+    // 强制方向切换优先级最高，覆盖 autoNichePrompt
+    effectiveUserPrompt = `MANDATORY DIRECTION CHANGE: You MUST switch from "${forceNicheSwitch.from}" to "${forceNicheSwitch.to}" niche. ${forceNicheSwitch.reason}. Focus on: ${forceNicheSwitch.description}. Do NOT generate tags in the "${forceNicheSwitch.from}" direction anymore — it has been exhausted with no productive results.`;
+  } else if (autoNichePrompt) {
+    effectiveUserPrompt = autoNichePrompt;
+  }
+
+  // ====== 自闭环 Step 3: 动态温度调整 ======
+  let temperature = 0.7; // 默认
+  if (health) {
+    if (health.healthStatus === "critical") {
+      temperature = 0.3; // 极度保守
+    } else if (health.healthStatus === "warning") {
+      temperature = 0.5; // 较保守
+    }
+    // 连续低效轮时进一步降温，让 LLM 更保守
+    if (health.consecutiveLowProductiveRounds >= 2) {
+      temperature = Math.min(temperature, 0.3);
+    }
+  }
+
+  // ====== 原有 discover 流程 ======
   // 读取历史打分记录
   const productive = store.getTagsByCountry(country, 50);
   const dead = store.getDeadTags(country);
-  // 获取该国所有已存在的 tag 名（应用层去重用）
-  const allTags = store.getTagsByCountry(country, 0);
-  const allExisting = new Set(allTags.map((t) => t.tag));
-  const history = { productive, dead };
+  // 全局去重：获取所有已存在的 tag 名（不限国家、不限状态），避免跨国家重复入库
+  const { getAllExistingTagNames } = await import("./db-tags.js");
+  const allExisting = getAllExistingTagNames();
+  console.error(
+    `[tag-service] ${country} 全局去重集合: ${allExisting.size} 个已存在 tag`,
+  );
+
+  // 获取最近生成的标签（用于检测重复生成）
+  const { getRecentGeneratedTags } = await import("./db-tags.js");
+  const recentGenerated = getRecentGeneratedTags(country, 10);
+
+  const history = { productive, dead, recentGenerated };
 
   // 读取历史策略效果（自学习）
-  const { getDiscoverRound, getDiscoverEffectiveness } =
-    await import("./db-tags.js");
   const round = getDiscoverRound(country);
   const pastStrategies = getDiscoverEffectiveness(country);
 
-  // 组装 prompt 并调用 LLM（两阶段：先思考策略，再生成 tag）
+  // ====== 自闭环 Step 4: 注入硬规则（反思产出） ======
+  const hardRules = getActiveRules(country);
+  if (hardRules.length > 0) {
+    console.error(
+      `[tag-service] ⛔ ${country} 注入 ${hardRules.length} 条硬规则到 prompt`,
+    );
+  }
+
+  // 组装 prompt（加入健康指标、niche 推荐、硬规则）
   const prompt = buildDiscoverPrompt(
     country,
     count,
     history,
-    userPrompt,
+    effectiveUserPrompt,
     pastStrategies,
+    health,
+    nicheRecommendation,
+    hardRules,
+    allExisting.size,
+    forceNicheSwitch,
   );
   console.error(
-    `[tag-service] LLM discover ${country} round=${round} (lang=${getLang(country)}, count=${count})`,
+    `[tag-service] LLM discover ${country} round=${round} (lang=${getLang(country)}, count=${count}, temp=${temperature}, health=${health?.healthStatus || "unknown"})`,
   );
-  const content = await callLLM(prompt);
+  const content = await callLLM(prompt, temperature);
 
-  // 解析响应：提取 strategy 和 tags，筛选掉数据库中已存在的
-  const { strategy, tags } = parseDiscoverResponse(content);
-  const unique = [...new Set(tags)]
-    .filter((t) => !allExisting.has(t))
-    .slice(0, count);
+  // 解析响应：提取 strategy, niche, tags
+  const parsed = parseDiscoverResponse(content);
+  const { strategy, tags } = parsed;
+  const niche = parsed.niche || null;
+  const deduped = [...new Set(tags)]; // LLM 自身去重
+  const filtered = deduped.filter((t) => !allExisting.has(t)); // 全局去重
+  const unique = filtered.slice(0, count);
 
   console.error(
     `[tag-service] LLM strategy: ${strategy?.substring(0, 150) || "(none)"}`,
   );
+  if (niche) {
+    console.error(`[tag-service] LLM niche focus: ${niche}`);
+  }
   console.error(
-    `[tag-service] LLM generated ${unique.length} tags: ${unique.join(", ")}`,
+    `[tag-service] ${country} 生成链路: LLM原始=${tags.length} → 自去重=${deduped.length} → 全局去重=${filtered.length} → 截取=${unique.length}`,
   );
+  if (filtered.length < count) {
+    const dupCount = deduped.length - filtered.length;
+    console.error(
+      `[tag-service] ⚠️ ${country} 去重后仅剩 ${filtered.length} 个（${dupCount} 个与已有 ${allExisting.size} 个 tag 重复），不足目标 ${count} 个`,
+    );
+  }
 
   // 去重写入数据库
   const inserted = [];
@@ -319,7 +591,7 @@ export async function discoverTagsForCountry(
     if (result.inserted) inserted.push(result.tag);
   }
 
-  // 记录 discover log（策略 + 结果）
+  // 记录 discover log（策略 + 结果 + 健康状态 + niche）
   const { insertDiscoverLog } = await import("./db-tags.js");
   insertDiscoverLog({
     country,
@@ -337,13 +609,41 @@ export async function discoverTagsForCountry(
       dead.length > 0 ? dead.reduce((s, t) => s + t.score, 0) / dead.length : 0,
   });
 
+  // ====== 自闭环 Step 5: 反思触发（本轮结束后检查是否需要反思） ======
+  let reflectionResult = null;
+  try {
+    reflectionResult = await reflectAndLearn(store, country);
+    if (reflectionResult.reflected) {
+      console.error(
+        `[tag-service] 🔄 ${country} 反思完成: 新增 ${reflectionResult.rulesAdded} 条规则, 分析: ${reflectionResult.analysis?.substring(0, 100)}`,
+      );
+    }
+  } catch (e) {
+    console.error(`[tag-service] 反思异常: ${e.message}`);
+    reflectionResult = { reflected: false, error: e.message };
+  }
+
   return {
     country,
     round,
     strategy,
+    niche,
     added: inserted.length,
     tags: inserted,
     total: unique.length,
+    // 自闭环信息
+    health: {
+      status: health?.healthStatus || "unknown",
+      deadRatio: health?.deadRatio || "?",
+      productiveRatio: health?.productiveRatio || "?",
+      saturation: health?.saturation || "?",
+      issues: health?.issues || [],
+    },
+    cleanupActions,
+    autoNiche: autoNichePrompt ? nicheRecommendation.uncovered[0].niche : null,
+    temperature,
+    hardRulesInjected: hardRules.length,
+    reflection: reflectionResult,
   };
 }
 
@@ -503,3 +803,267 @@ export async function scoreTag(store, { tag, targetCountries, serverUrl }) {
 
   return result;
 }
+
+// ====== 反思闭环：自我学习与改进 ======
+
+/**
+ * 组装反思 prompt
+ * 输入：最近轮次数据、成功/失败模式、当前规则、健康指标
+ * 输出期望：JSON 格式的规则列表
+ */
+export function buildReflectionPrompt(data) {
+  const {
+    country,
+    langName,
+    recentLogs,
+    productiveTop,
+    deadFrequency,
+    errorStats,
+    activeRules,
+    health,
+  } = data;
+
+  // 最近轮次效果摘要
+  const roundsSummary = recentLogs
+    .slice(0, 10)
+    .map((log) => {
+      const tagsGen = JSON.parse(log.tags_generated || "[]");
+      return `Round ${log.round}: strategy="${log.strategy?.substring(0, 100) || "(none)"}", generated ${tagsGen.length} tags: ${tagsGen.slice(0, 8).join(", ")}${tagsGen.length > 8 ? "..." : ""}`;
+    })
+    .join("\n");
+
+  // 成功模式：productive 标签的特征
+  const successPatterns = productiveTop
+    .slice(0, 20)
+    .map(
+      (t) =>
+        `${t.tag} (score=${t.score}, authors=${t.matched_authors}, pushed=${t.pushed_users})`,
+    )
+    .join(", ");
+
+  // 失败模式：dead 标签的特征
+  const failurePatterns = deadFrequency
+    .slice(0, 30)
+    .map((t) => `${t.tag} (error: ${t.last_error || "no_match"})`)
+    .join(", ");
+
+  // Error 类型统计
+  const errorSummary = errorStats
+    .map((e) => `${e.error_type}: ${e.count} tags`)
+    .join(", ");
+
+  // 当前活跃规则
+  const currentRules =
+    activeRules.length > 0
+      ? activeRules.map((r) => `  - ${r.rule_text}`).join("\n")
+      : "  (none yet)";
+
+  // 健康指标
+  const healthInfo = health
+    ? `Health: ${health.healthStatus} | deadRatio=${health.deadRatio}% | productiveRatio=${health.productiveRatio}% | saturation=${health.saturation}%`
+    : "Health: unknown";
+
+  return `You are a self-reflection agent analyzing why TikTok hashtag discovery has been failing for ${country} (${langName}).
+
+Your goal: identify FAILURE PATTERNS and SUCCESS PATTERNS, then produce HARD RULES that will guide future tag generation to be more effective.
+
+## Recent discovery rounds (all failing)
+${roundsSummary}
+
+## Success patterns (productive tags that actually work)
+${successPatterns}
+
+## Failure patterns (dead tags that don't work)
+${failurePatterns}
+
+## Error type distribution
+${errorSummary}
+
+## Current health status
+${healthInfo}
+
+## Current hard rules already in effect
+${currentRules}
+
+## Analysis task
+
+Analyze the data above and answer:
+
+1. **What patterns do productive tags share?** (language, length, word type, structure)
+2. **What patterns do dead tags share?** (language, length, word type, structure)
+3. **What specific tags should NEVER be generated again?** (list the most frequently repeated dead tags)
+4. **What language strategy should be used?** (e.g. "only use ${langName} words", "avoid English-only tags")
+5. **What word structure works?** (e.g. "single industry words", "city+category combos", "avoid compound words")
+
+## Output format
+
+Return ONLY a JSON object:
+{
+  "analysis_summary": "2-3 sentence summary of what you learned",
+  "success_pattern": "description of what productive tags look like",
+  "failure_pattern": "description of what dead tags look like",
+  "rules": [
+    {
+      "rule_type": "hard",
+      "rule_text": "NEVER use English-only tags for ${country} — they have 0% match rate",
+      "trigger_reason": "dead_ratio > 60% with English tags"
+    },
+    {
+      "rule_type": "hard",
+      "rule_text": "NEVER generate these specific tags: hautpflege, bodycare, serum, creme, wellness",
+      "trigger_reason": "these tags confirmed dead 5+ times"
+    },
+    {
+      "rule_type": "soft",
+      "rule_text": "Prefer ${langName} industry/profession words (like handwerker, schreinerei pattern)",
+      "trigger_reason": "productive tags are mostly local-language industry words"
+    }
+  ]
+}
+
+Be specific and actionable. Each rule should be something that can be directly applied to future tag generation prompts.`;
+}
+
+/**
+ * 解析反思 LLM 的响应
+ */
+export function parseReflectionResponse(content) {
+  try {
+    const parsed = JSON.parse(content);
+    return {
+      analysisSummary: parsed.analysis_summary || "",
+      successPattern: parsed.success_pattern || "",
+      failurePattern: parsed.failure_pattern || "",
+      rules: (parsed.rules || [])
+        .map((r) => ({
+          ruleType: r.rule_type || "hard",
+          ruleText: r.rule_text || "",
+          triggerReason: r.trigger_reason || "",
+        }))
+        .filter((r) => r.ruleText.length > 10),
+    };
+  } catch {
+    // JSON 解析失败，尝试从文本提取
+    const rules = [];
+    const lines = content.split("\n");
+    for (const line of lines) {
+      const match = line.match(/"rule_text"\s*:\s*"([^"]+)"/);
+      if (match && match[1].length > 10) {
+        rules.push({
+          ruleType: line.includes("soft") ? "soft" : "hard",
+          ruleText: match[1],
+          triggerReason: "",
+        });
+      }
+    }
+    return {
+      analysisSummary: content.substring(0, 200),
+      successPattern: "",
+      failurePattern: "",
+      rules,
+    };
+  }
+}
+
+/**
+ * 执行一次反思：分析数据 → 调用 LLM → 写入规则
+ * @param {object} store - data-store 实例
+ * @param {string} country - 国家代码
+ * @returns {{ reflected: boolean, rulesAdded: number, analysis: string }}
+ */
+export async function reflectAndLearn(store, country) {
+  if (!COUNTRY_LANG[country]) {
+    return { reflected: false, error: `不支持的国家代码: ${country}` };
+  }
+
+  const {
+    shouldTriggerReflection,
+    getReflectionData,
+    insertReflectionRules,
+    supersedeRules,
+    getActiveRules,
+  } = await import("./db-tags.js");
+
+  // Step 1: 检查是否需要反思
+  const triggerCheck = shouldTriggerReflection(country);
+  if (!triggerCheck.shouldReflect) {
+    console.error(`[reflection] ${country} 不需要反思: ${triggerCheck.reason}`);
+    return { reflected: false, reason: triggerCheck.reason };
+  }
+
+  console.error(`[reflection] 🔄 ${country} 触发反思: ${triggerCheck.reason}`);
+
+  // Step 2: 收集反思数据
+  const data = getReflectionData(country);
+  if (!data) {
+    return { reflected: false, error: "无法获取反思数据" };
+  }
+
+  // Step 3: 组装反思 prompt
+  const prompt = buildReflectionPrompt(data);
+
+  // Step 4: 调用 LLM 进行反思（温度较低，确保分析质量）
+  console.error(`[reflection] 🧠 ${country} 正在调用 LLM 进行反思分析...`);
+  const content = await callLLM(prompt, 0.3);
+
+  // Step 5: 解析反思结果
+  const reflection = parseReflectionResponse(content);
+  if (reflection.rules.length === 0) {
+    console.error(
+      `[reflection] ${country} LLM 反思未产出有效规则，原始响应: ${content.substring(0, 200)}`,
+    );
+    return {
+      reflected: true,
+      rulesAdded: 0,
+      analysis: reflection.analysisSummary,
+      rawContent: content.substring(0, 500),
+    };
+  }
+
+  console.error(
+    `[reflection] ${country} LLM 分析: ${reflection.analysisSummary}`,
+  );
+  console.error(
+    `[reflection] ${country} 成功模式: ${reflection.successPattern}`,
+  );
+  console.error(
+    `[reflection] ${country} 失败模式: ${reflection.failurePattern}`,
+  );
+  console.error(
+    `[reflection] ${country} 产出 ${reflection.rules.length} 条规则:`,
+  );
+  for (const rule of reflection.rules) {
+    console.error(`  [${rule.ruleType}] ${rule.ruleText}`);
+  }
+
+  // Step 6: 废弃旧规则，写入新规则
+  const supersedeResult = supersedeRules(country, "new reflection round");
+  console.error(
+    `[reflection] ${country} 废弃 ${supersedeResult.superseded} 条旧规则`,
+  );
+
+  const rulesToInsert = reflection.rules.map((r) => ({
+    country,
+    ruleType: r.ruleType,
+    ruleText: r.ruleText,
+    triggerReason: r.triggerReason,
+    productiveSample: data.productiveTop.slice(0, 10).map((t) => t.tag),
+    deadSample: data.deadFrequency.slice(0, 20).map((t) => t.tag),
+    analysisSummary: reflection.analysisSummary,
+  }));
+
+  const insertResult = insertReflectionRules(rulesToInsert);
+  console.error(
+    `[reflection] ${country} 写入 ${insertResult.inserted} 条新规则`,
+  );
+
+  return {
+    reflected: true,
+    rulesAdded: insertResult.inserted,
+    analysis: reflection.analysisSummary,
+    successPattern: reflection.successPattern,
+    failurePattern: reflection.failurePattern,
+    rules: reflection.rules,
+    superseded: supersedeResult.superseded,
+  };
+}