tt-help-cli-ycl 1.4.150 → 1.4.152

package/src/lib/shop-scraper.mjs

@@ -97,6 +97,81 @@ function extractJsonByKey(html, keyPattern) {
   return null;
 }
 
+/**
+ * Extract a JSON array by its key name (counterpart of extractJsonByKey for `[`).
+ * 用于 PDP SSR HTML 中的 "skus":[...] 段。
+ */
+function extractJsonArrayByKey(html, keyPattern) {
+  const match = html.match(keyPattern);
+  if (!match) return null;
+
+  const bracketIdx = html.indexOf("[", match.index);
+  if (bracketIdx === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = bracketIdx; i < html.length; i++) {
+    const ch = html[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "[") depth++;
+    else if (ch === "]") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(html.substring(bracketIdx, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * 从 PDP SSR HTML 的 "skus":[...] 提取多 SKU 概要（原有商品级字段不动）。
+ * sku_id 为 19 位数字，必须按字符串保留（同 product_id 的精度坑）。
+ * @returns {Array<{skuId, specs, stock, stockStatus, warehouseId}>|null}
+ *   无 skus 段或解析失败返回 null（与现有字段缺失口径一致）
+ */
+function extractSkus(html) {
+  const skus = extractJsonArrayByKey(html, /"skus"\s*:/);
+  if (!Array.isArray(skus) || skus.length === 0) return null;
+  const out = [];
+  for (const s of skus) {
+    try {
+      out.push({
+        skuId: String(s.sku_id ?? ""),
+        specs: (s.property_pairs || [])
+          .map((p) => `${p.sku_property_name}: ${p.sku_property_value_name}`)
+          .join(" | "),
+        stock: s.sku_quantity?.available_quantity ?? null,
+        stockStatus: s.sku_stock_status ?? null,
+        warehouseId: s.sku_quantity?.warehouse_id
+          ? String(s.sku_quantity.warehouse_id)
+          : null,
+      });
+    } catch {
+      // 单条损坏跳过，不影响其余 SKU
+    }
+  }
+  return out.length > 0 ? out : null;
+}
+
 /**
  * Open a headed browser for manual captcha solving, extract cookies
  * so undici can reuse them for a while.
@@ -278,6 +353,7 @@ export function parseProductHtml(html) {
     ratingBreakdown: null,
     productId: null,
     sellerId: null,
+    skus: null, // 多 SKU 概要（无 skus 段或解析失败为 null，不影响原有字段）
   };
 
   // sold_count from product_model (string value, not shop-level integer)
@@ -308,6 +384,9 @@ export function parseProductHtml(html) {
     result.ratingBreakdown = ratings.rating_result ?? null;
   }
 
+  // skus（多规格概要：规格名/库存/仓库，sku_id 字符串保精度）
+  result.skus = extractSkus(html);
+
   // 壳页识别：有 product_id 骨架但 seller_id 为空且无任何销售/名称数据
   // → 商品已下架/店铺异常（200 空壳页），抛 delisted 供调用方标记放弃
   const hasSaleData =

package/src/scraper/auto-core.js

@@ -9,24 +9,25 @@ import {
   detectPageError,
   isLoggedIn,
   assertPageUrl,
-} from './modules/page-helpers.js';
-import { detectCaptcha } from './modules/captcha-handler.js';
+} from "./modules/page-helpers.js";
+import { detectCaptcha } from "./modules/captcha-handler.js";
 export { ensureBrowserReady };
-import {
-  getUserInfo,
-  collectVideos,
-} from '../videos/core.js';
-import { runScrape } from './core.js';
-import { extractFollowAndFollowers } from './modules/follow-extractor.js';
+import { getUserInfo, collectVideos } from "../videos/core.js";
+import { runScrape } from "./core.js";
+import { extractFollowAndFollowers } from "./modules/follow-extractor.js";
 
 function mergeUserInfo(existing, incoming, source) {
   const merged = { ...existing };
   for (const [key, value] of Object.entries(incoming)) {
-    if (key === '_sources') continue;
-    if (value === undefined || value === null || value === '') continue;
-    if (typeof value === 'number' && typeof merged[key] === 'number') {
+    if (key === "_sources") continue;
+    if (value === undefined || value === null || value === "") continue;
+    if (typeof value === "number" && typeof merged[key] === "number") {
       merged[key] = Math.max(merged[key], value);
-    } else if (merged[key] === undefined || merged[key] === null || merged[key] === '') {
+    } else if (
+      merged[key] === undefined ||
+      merged[key] === null ||
+      merged[key] === ""
+    ) {
       merged[key] = value;
     }
   }
@@ -43,7 +44,7 @@ async function processUser(page, username, options, log) {
     scrapeDepth = 50,
     maxComments = 200,
     maxGuess = 10,
-    preset = 'fast',
+    preset = "fast",
     switchMax = null,
     commentMax = null,
     enableFollow = false,
@@ -65,34 +66,43 @@ async function processUser(page, username, options, log) {
 
   try {
     log(`\n[processUser] 访问 @${username}...`);
-    await retryWithBackoff(async () => {
-      await page.goto(`https://www.tiktok.com/@${username}`, {
-        waitUntil: 'load', timeout: 30000,
-      });
-      assertPageUrl(page, `@${username}`);
-    }, { log });
-    await page.waitForSelector('[class*="DivVideoList"]', { timeout: 10000 }).catch(() => {});
+    await retryWithBackoff(
+      async () => {
+        await page.goto(`https://www.tiktok.com/@${username}`, {
+          waitUntil: "load",
+          timeout: 30000,
+        });
+        assertPageUrl(page, `@${username}`);
+      },
+      { log },
+    );
+    await page
+      .waitForSelector('[class*="DivVideoList"]', { timeout: 10000 })
+      .catch(() => {});
     await delay(1000, 2000);
 
     const info = await getUserInfo(page);
     result.userInfo = info;
     if (!info.uniqueId) info.uniqueId = username;
-    log(`  昵称: ${info.nickname || '-'} | 粉丝: ${info.followerCount || 0}`);
+    log(`  昵称: ${info.nickname || "-"} | 粉丝: ${info.followerCount || 0}`);
 
     if (options.enableFollow) {
       const loggedIn = await isLoggedIn(page);
       if (!loggedIn) {
-        log('  [跳过] 提取关注/粉丝：未登录，请先登录 TikTok');
+        log("  [跳过] 提取关注/粉丝：未登录，请先登录 TikTok");
         result.discoveredFollowing = [];
         result.discoveredFollowers = [];
       } else {
         try {
-          log('  提取关注/粉丝列表...');
-          const { following, followers } = await extractFollowAndFollowers(page, {
-            maxFollowing: options.maxFollowing || 200,
-            maxFollowers: options.maxFollowers || 200,
-            log,
-          });
+          log("  提取关注/粉丝列表...");
+          const { following, followers } = await extractFollowAndFollowers(
+            page,
+            {
+              maxFollowing: options.maxFollowing || 200,
+              maxFollowers: options.maxFollowers || 200,
+              log,
+            },
+          );
           result.discoveredFollowing = following;
           result.discoveredFollowers = followers;
           log(`  关注: ${following.length} | 粉丝: ${followers.length}`);
@@ -108,13 +118,13 @@ async function processUser(page, username, options, log) {
     if (captcha && captcha.visible) {
       log(`[验证码] @${username} 页面出现验证码`);
       result.captchaDetected = true;
-      result.captchaStage = result.captchaStage || 'video-page';
-      result.captchaMessage = result.captchaMessage || '视频页出现验证码';
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "视频页出现验证码";
     }
 
     const videos = await collectVideos(page, username, collectMax, log);
     const videoList = Array.from(videos.values()).slice(0, collectMax);
-    result.collectedVideos = videoList.map(v => ({
+    result.collectedVideos = videoList.map((v) => ({
       videoId: v.id,
       videoUrl: v.href,
     }));
@@ -126,10 +136,12 @@ async function processUser(page, username, options, log) {
 
       for (let i = 0; i < videoList.length; i++) {
         const video = videoList[i];
-        const videoUrl = video.href.startsWith('http')
+        const videoUrl = video.href.startsWith("http")
           ? video.href
           : `https://www.tiktok.com${video.href}`;
-        log(`  [${i + 1}/${videoList.length}] 开始 scrape: ${videoUrl} (深度 ${scrapeDepth})`);
+        log(
+          `  [${i + 1}/${videoList.length}] 开始 scrape: ${videoUrl} (深度 ${scrapeDepth})`,
+        );
 
         const scrapeResult = await runScrape({
           videoUrl,
@@ -146,8 +158,9 @@ async function processUser(page, username, options, log) {
 
         if (scrapeResult.captchaDetected) {
           result.captchaDetected = true;
-          result.captchaStage = scrapeResult.captchaStage || 'scrape';
-          result.captchaMessage = scrapeResult.captchaMessage || 'scrape阶段出现验证码';
+          result.captchaStage = scrapeResult.captchaStage || "scrape";
+          result.captchaMessage =
+            scrapeResult.captchaMessage || "scrape阶段出现验证码";
         }
 
         const scrapeOutput = scrapeResult.output;
@@ -181,7 +194,9 @@ async function processUser(page, username, options, log) {
       result.discoveredCommentAuthors = [...allCommentAuthors];
       result.discoveredGuessAuthors = [...allGuessAuthors];
 
-      log(`  发现: ${result.discoveredVideoAuthors.length} 个视频作者, ${result.discoveredCommentAuthors.length} 个评论作者, ${result.discoveredGuessAuthors.length} 个猜你喜欢作者`);
+      log(
+        `  发现: ${result.discoveredVideoAuthors.length} 个视频作者, ${result.discoveredCommentAuthors.length} 个评论作者, ${result.discoveredGuessAuthors.length} 个猜你喜欢作者`,
+      );
     } else {
       const pageError = await detectPageError(page);
       result.restricted = !!pageError;
@@ -192,8 +207,17 @@ async function processUser(page, username, options, log) {
       }
     }
   } catch (e) {
+    // 被判重试期间弹出验证码（api-interceptor 抛出 "验证码: username"）:
+    // 转验证码标记，由外层 captchaDetected 计数处理
+    if (e.message.startsWith("验证码:")) {
+      result.captchaDetected = true;
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "被判重试期间弹出验证码";
+      log(`  @${username} 被判期间弹出验证码，转验证码处理`);
+      return result;
+    }
     result.error = e.message;
-    result.errorStack = e.stack || '';
+    result.errorStack = e.stack || "";
     log(`  [错误] ${e.message}`);
   }
 

package/src/scraper/explore-core.js

@@ -181,19 +181,26 @@ async function processExplore(page, username, options, log) {
       return result;
     }
 
-    // 国家采样判断
+    // 国家采样判断（只用真视频：图文帖 /photo/ 链接查不到 locationCreated，
+    // 会浪费采样位并污染众数统计；图文 EC 帖仍在上方 EC 筛选中正常保留）
     // explore 模式：采样 5 个，优先命中目标国家，不匹配则回退众数 → 写 locationCreated
     // refresh 模式：采样 7 个，纯众数逻辑 → 写 confirmedLocation（二次确认）
     const SAMPLE_SIZE = locationMode === "refresh" ? 7 : 5;
     let locationCreated = null;
     let confirmedLocation = null;
     let locationDecision = null;
-    const sampleVideos = videoArray.slice(0, SAMPLE_SIZE);
+    const sampleVideos = videoArray
+      .filter((v) => !v.isPhoto)
+      .slice(0, SAMPLE_SIZE);
     if (sampleVideos.length > 0) {
       const sampleUrls = sampleVideos.map((v) =>
         v.href.startsWith("http") ? v.href : `https://www.tiktok.com${v.href}`,
       );
+      log(
+        `  国家采样(${sampleUrls.length}个, 已排除图文${videoArray.length - videoArray.filter((v) => !v.isPhoto).length}条): 开始查询`,
+      );
       let locations;
+      let sampleFailCount = 0; // 查询本身失败（网络/超时/CDN）计数，与"查成功但无数据"区分
       if (webserverUrl) {
         // 走集中式 webserver，不再启动本地 TikTokScraper
         locations = await Promise.all(
@@ -208,6 +215,7 @@ async function processExplore(page, username, options, log) {
               const data = await res.json();
               return data?.locationCreated || null;
             } catch (e) {
+              sampleFailCount++;
               log(`  [webserver] 视频查询失败: ${e.message}`);
               return null;
             }
@@ -215,12 +223,32 @@ async function processExplore(page, username, options, log) {
         );
       } else {
         locations = await Promise.all(
-          sampleUrls.map((url) => extractVideoLocation(url)),
+          sampleUrls.map(async (url) => {
+            try {
+              return await extractVideoLocation(url);
+            } catch (e) {
+              sampleFailCount++;
+              log(`  [采样] 视频查询失败: ${e.message}`);
+              return null;
+            }
+          }),
         );
       }
       log(
-        `  国家采样(${locations.length}个): [${locations.filter(Boolean).join(", ") || "无数据"}]`,
+        `  国家采样(${locations.length}个${sampleFailCount > 0 ? `, 查询失败${sampleFailCount}` : ""}): [${locations.filter(Boolean).join(", ") || "无数据"}]`,
       );
+
+      // 全部查询失败 ≠ 全部无数据：
+      // 通道故障（webserver 挂掉/超时、本地 Scraper 被封）时若按 done 无国家入库，
+      // 会陷入"无国家 → 2h 回炉 → 又全失败 → 又 done"的空转循环；
+      // 按 error 上报让任务回流重做，且面板可见
+      if (sampleUrls.length > 0 && sampleFailCount === sampleUrls.length) {
+        result.error = `国家采样全失败（${webserverUrl ? "webserver" : "本地Scraper"}通道 ${sampleFailCount}/${sampleUrls.length} 全失败）`;
+        result.errorStack = "";
+        result.processed = false;
+        log(`  [错误] ${result.error}，任务按错误回流`);
+        return result;
+      }
       // 直接标准化，不去重（保留重复值用于频率统计）
       const normalizedLocations = locations
         .map((loc) => normalizeLocation(loc))
@@ -347,6 +375,19 @@ async function processExplore(page, username, options, log) {
       log(`  @${username} CDN限流`);
     }
 
+    // 被判重试期间弹出验证码（api-interceptor 抛出 "验证码: username"）:
+    // 清掉 error 转验证码分支，让外层 CLI 走 captchaDetected 上报/等待人工解决流程
+    if (e.message.startsWith("验证码:")) {
+      result.error = null;
+      result.errorStack = "";
+      result.processed = false;
+      result.captchaDetected = true;
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "被判重试期间弹出验证码";
+      log(`  @${username} 被判期间弹出验证码，转验证码处理`);
+      return result;
+    }
+
     // 临时性错误：超时、执行上下文销毁、网络异常 — 标记为可重试
     const retryablePatterns = [
       "Timeout",

package/src/videos/core.js

@@ -87,6 +87,11 @@ async function collectVideos(page, username, maxVideos, log) {
     if (e.message.startsWith("被封:")) {
       throw e; // 向上抛出，由 explore-core 处理
     }
+    // 被判重试期间弹出验证码会抛出 "验证码: username"，同样原样上抛
+    // （不能被包装成 "API 拦截失败"，否则上层识别不到前缀）
+    if (e.message.startsWith("验证码:")) {
+      throw e; // 向上抛出，由 explore-core 处理
+    }
     // CDN 限流会抛出 "CDN限流..." 异常（HTTP 路径 CDNBlockedError / CDP 路径 api-interceptor）
     if (e.message.startsWith("CDN限流")) {
       throw e; // 向上抛出，由 explore-core 处理

package/src/watch/data-store.js

@@ -683,7 +683,13 @@ function getPreciseMerchantsFromDb(targetLocations = [], options = {}) {
       product_review_count,
       product_sold_count,
       product_name,
+      product_skus,
       recent_ec_videos,
+      (CASE WHEN json_valid(product_skus) THEN
+        (SELECT COUNT(*) FROM json_each(product_skus)) ELSE 0 END) AS skuCount,
+      (CASE WHEN json_valid(product_skus) THEN
+        (SELECT COALESCE(SUM(CAST(json_extract(value, '$.stock') AS INTEGER)), 0)
+          FROM json_each(product_skus)) ELSE 0 END) AS skuTotalStock,
       (SELECT COUNT(*) FROM json_each(recent_ec_videos)
         WHERE CAST(json_extract(value, '$.playCount') AS INTEGER) > 1000) AS ecOver1k,
       (SELECT MAX(CAST(json_extract(value, '$.playCount') AS INTEGER))
@@ -1388,7 +1394,11 @@ export function createStore(filePath, options = {}) {
           filter: `instr(COALESCE(sources, ''), '"seed"') > 0`,
           loggedInOnly: false,
         },
-        { filter: `tt_seller = 1 AND verified = 0`, loggedInOnly: true },
+        {
+          filter: `tt_seller = 1 AND verified = 0`,
+          loggedInOnly: true,
+          sellerAnyCountry: true,
+        },
         {
           filter: `(instr(COALESCE(sources, ''), '"following"') > 0 OR instr(COALESCE(sources, ''), '"follower"') > 0 OR instr(COALESCE(sources, ''), '"comment"') > 0)`,
           loggedInOnly: false,
@@ -1407,8 +1417,28 @@ export function createStore(filePath, options = {}) {
         );
         if (normalizedLocations.length === 0)
           locationBranches.push(locNotIn(orderedCountries));
+        // 商家级专用（sellerAnyCountry）：国家对商家放开——末尾追加"任意国家"分支。
+        // 传了国家子集时对应国家的商家仍优先，领完再兜任意国家（含空位置商家）；
+        // 未传国家时同理（配置内各国 → 配置外 → 任意）。其他来源级分支不受影响。
+        if (p.sellerAnyCountry) locationBranches.push(null); // null → 任意国家分支
         let subPrio = 0;
         for (const loc of locationBranches) {
+          // 商家任意国家分支：不限 guessed_location（含空位置的商家）
+          if (loc === null) {
+            // hasVideo
+            addBranch(
+              `status = 'pending' AND pinned = 0 AND ${p.filter} AND video_count > 0 AND ${statusCodeWhere} ${notSellerWhere}`,
+              [],
+            );
+            subPrio++;
+            // noVideoReq
+            addBranch(
+              `status = 'pending' AND pinned = 0 AND ${p.filter} AND ${statusCodeWhere} ${notSellerWhere}`,
+              [],
+            );
+            subPrio++;
+            continue;
+          }
           if (!loc) continue;
           // hasVideo
           addBranch(
@@ -2452,28 +2482,40 @@ export function createStore(filePath, options = {}) {
     const placeholders = targetLocations.map(() => "?").join(",");
 
     // SELECT 候选用户
-    const selected = getDb()
-      .prepare(
-        `
-        SELECT unique_id, nickname, video_count, COALESCE(refresh_time, ?) AS refresh_time
-        FROM jobs
+    // 性能三件套（76 万行实测 1~3s → ~80ms）：
+    // 1. WHERE/ORDER BY 不用 COALESCE(refresh_time, ?)（表达式挡索引）；
+    //    ASC 排序 NULL 天然最前，与 COALESCE 2016 默认值语义等价
+    // 2. INDEXED BY 强制走 idx_jobs_precheck 部分索引（优化器无统计时会
+    //    误选 idx_jobs_seller_verified_loc 走 TEMP B-TREE 全排序）
+    // 3. ORDER BY jobs.refresh_time 限定表名——裸列名会被 SELECT 输出别名
+    //    refresh_time（COALESCE 表达式）遮蔽，又退回表达式排序
+    // 索引不存在的环境（老库未重启）抛 "no such index"，自动回退普通查询。
+    const baseWhere = `
         WHERE tt_seller = 1
           AND verified = 0
           AND (pending_refresh IS NULL OR pending_refresh = 0)
           AND location_created IN (${placeholders})
-          AND COALESCE(refresh_time, ?) < ?
-        ORDER BY COALESCE(refresh_time, ?) ASC
-        LIMIT ?
-      `,
-      )
-      .all(
-        defaultTime,
-        ...targetLocations,
-        defaultTime,
-        threshold,
-        defaultTime,
-        limit,
-      );
+          AND (refresh_time IS NULL OR refresh_time < ?)`;
+    const orderLimit = `
+        ORDER BY jobs.refresh_time ASC
+        LIMIT ?`;
+    const selectSql = `SELECT unique_id, nickname, video_count, COALESCE(refresh_time, ?) AS refresh_time
+        FROM jobs`;
+    const args = [defaultTime, ...targetLocations, threshold, limit];
+
+    let selected;
+    try {
+      selected = getDb()
+        .prepare(
+          `${selectSql} INDEXED BY idx_jobs_precheck${baseWhere}${orderLimit}`,
+        )
+        .all(...args);
+    } catch (e) {
+      if (!/no such index/i.test(e.message)) throw e;
+      selected = getDb()
+        .prepare(`${selectSql}${baseWhere}${orderLimit}`)
+        .all(...args);
+    }
 
     // 立即更新 refresh_time 防重复领取（非事务，小概率并发重复可接受）
     if (selected.length > 0) {
@@ -2799,8 +2841,9 @@ export function createStore(filePath, options = {}) {
   /**
    * 回写商品详情到 jobs 表（product_* 列）
    * @param {string} uniqueId
-   * @param {{rating?:number, reviewCount?:number, soldCount?:number, productName?:string}} productDetail
+   * @param {{rating?:number, reviewCount?:number, soldCount?:number, productName?:string, skus?:Array}} productDetail
    *   rating = -1 为哨兵值：商品不可售/已下架，写入后任务移出候选（正常评分 0-5）
+   *   skus = 多 SKU 概要数组（skuId/specs/stock/stockStatus/warehouseId），存 product_skus JSON
    */
   function updateProductInfo(uniqueId, productDetail) {
     if (getDb()) {
@@ -2814,6 +2857,10 @@ export function createStore(filePath, options = {}) {
           productReviewCount: productDetail.reviewCount ?? null,
           productSoldCount: productDetail.soldCount ?? null,
           productName: productDetail.productName || null,
+          // 多 SKU 概要：数组经 normalizeJobValue 自动序列化为 JSON（无 skus 存 null）
+          productSkus: Array.isArray(productDetail.skus)
+            ? productDetail.skus
+            : null,
         },
         false, // 商品补全与用户刷新计数无关，不增加 user_update_count
         "jobs",

package/src/watch/db-columns.js

@@ -99,6 +99,7 @@ export const WRITABLE_JOB_COLUMNS = new Set([
   "product_review_count",
   "product_sold_count",
   "product_name",
+  "product_skus",
   "user_create_time",
   "recent_ec_videos",
   "pending_refresh",

package/src/watch/db-schema.js

@@ -173,6 +173,7 @@ export function initDb(filePath) {
     product_review_count: "INTEGER",
     product_sold_count: "INTEGER",
     product_name: "TEXT",
+    product_skus: "TEXT",
     user_create_time: "INTEGER",
     recent_ec_videos: "TEXT",
   });
@@ -209,6 +210,7 @@ export function initDb(filePath) {
     product_review_count: "INTEGER",
     product_sold_count: "INTEGER",
     product_name: "TEXT",
+    product_skus: "TEXT",
     user_create_time: "INTEGER",
     recent_ec_videos: "TEXT",
   });
@@ -246,6 +248,7 @@ export function initDb(filePath) {
     product_review_count: "INTEGER",
     product_sold_count: "INTEGER",
     product_name: "TEXT",
+    product_skus: "TEXT",
     user_create_time: "INTEGER",
     recent_ec_videos: "TEXT",
   });

package/src/watch/db-tags.js

@@ -375,15 +375,25 @@ export function getAllTags(
 }
 
 export function rawQuery(sql, params = []) {
-  // 通用查询器：默认查主库（stats/db-query 复用），勿切到 tag 库
+  // 通用查询器：默认查主库（stats/db-query 复用），勿切到 tag 库。
+  // 注意：原实现用 prepare().all() 跑一切语句，DDL（CREATE INDEX 等）会抛
+  // "This statement does not return data" 且被 catch 吞成 {error} 返回——
+  // server.js 启动清单 ensureIdx 曾因此静默失效（生产库从未建过启动索引）。
+  // 现按语句类型分流：DDL/写语句走 exec，查询走 all；失败时抛错让调用方感知。
   const db = getMainDb();
-  if (!db) return { error: "db not ready" };
-  try {
+  if (!db) throw new Error("db not ready");
+  const trimmed = sql.trim().toUpperCase();
+  const isQuery =
+    trimmed.startsWith("SELECT") ||
+    trimmed.startsWith("PRAGMA") ||
+    trimmed.startsWith("EXPLAIN") ||
+    trimmed.startsWith("WITH");
+  if (isQuery) {
     const rows = db.prepare(sql).all(...params);
     return { rows };
-  } catch (e) {
-    return { error: e.message };
   }
+  db.exec(sql);
+  return { rows: [] };
 }
 
 export function normalizeTags() {