tt-help-cli-ycl 1.4.134 → 1.4.136

package/src/watch/server.js

@@ -7,6 +7,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { spawn } from "child_process";
 import { createStore } from "./data-store.js";
+import { getTagDb } from "./db-schema.js";
 import { DEFAULT_TARGET_LOCATIONS } from "../lib/target-locations.js";
 import { tryHandleWatchdogRoute } from "./watchdog-server.js";
 
@@ -26,96 +27,345 @@ function getLocalIP() {
 const __dirname = dirname(__filename);
 const publicDir = join(__dirname, "public");
 
-// Stats 缓存：避免每次请求都扫描百万行级大表数据
-let statsCache = null;
-let statsCacheTime = 0;
-// 5 分钟缓存：users 表 3116 万行，COUNT 全表扫约 3s；jobs 162 万行，聚合约 2s。
-// 原 15 秒 TTL 导致每 15 秒一次同步大查询，冻结事件循环 5~30s（成簇超时的根因）
-const STATS_CACHE_TTL = 300000; // 5 分钟
+// ===== Stats 分项缓存：快/中/慢 三档 TTL =====
+// 原来所有统计共用一个 5 分钟缓存，快项（任务队列聚合）被慢项（千万级大表 COUNT）拖累。
+// 现将统计拆为三组，各自独立缓存与刷新：
+//   fast   （30s）: task_queue + jobs 状态聚合 —— 仪表盘核心数字，接近实时
+//   medium （60s）: jobs_base 计数 + 按国家分布（jobs 表 GROUP BY，较重）
+//   slow   （300s）: raw_jobs / videos / tags 全表 COUNT —— 最重，低频
+// 每组过期后先返回旧数据，后台分片刷新（片间 setImmediate 让出事件循环，
+// 避免多个大查询连续执行冻结事件循环，此前成簇超时的直接原因）。
+// 另：任务领取/提交后主动使 fast 组失效，核心数字最快 10s（前端轮询周期）内更新。
+const FAST_STATS_TTL = 30000; // 30 秒
+const MEDIUM_STATS_TTL = 60000; // 60 秒
+const SLOW_STATS_TTL = 300000; // 5 分钟
 
 // 用户列表短缓存：同一参数组合 3 秒内复用，无论多少客户端同时查只算一次
 const usersCache = new Map(); // key -> { result, time }
 const USERS_CACHE_TTL = 3000; // 3 秒
 
-// 慢计数查询（分片执行）。
-// 注：dbTotalUsers（COUNT(*) FROM users）已移除 —— users 表 3116 万行全表扫约 3s，
-// 且该字段前端未使用；users 表为判重索引，数据不能删，只能从统计里去掉。
-const SLOW_COUNT_SQLS = {
-  rawJobs: "SELECT COUNT(*) as c FROM raw_jobs",
-  commentTaskCount:
-    "SELECT COUNT(*) as c FROM videos WHERE user_update_count IS NULL OR user_update_count <= 0",
-  tagCount: "SELECT COUNT(*) as c FROM tags",
-  tagHighScore: "SELECT COUNT(*) as c FROM tags WHERE score >= 70",
+// 目标国家占位符（jobs 表聚合需要 location_created IN (...)）
+const TARGET_PLACEHOLDERS = DEFAULT_TARGET_LOCATIONS.map(() => "?").join(", ");
+const TARGET_IN_SQL = DEFAULT_TARGET_LOCATIONS.length
+  ? `location_created IN (${TARGET_PLACEHOLDERS})`
+  : "1 = 0";
+
+// 统计分组定义：每组包含若干 SQL（分片执行）与一个聚合函数
+// sqls 项：{ key, sql, mode: 'one'|'all', params: 数组或返回数组的函数 }
+const STAT_GROUPS = {
+  fast: {
+    ttl: FAST_STATS_TTL,
+    sqls: [
+      {
+        key: "tqAgg",
+        mode: "one",
+        sql: `SELECT
+          COUNT(*) as tqTotal,
+          SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending,
+          SUM(CASE WHEN status = 'processing' THEN 1 ELSE 0 END) as processing,
+          SUM(CASE WHEN instr(COALESCE(sources, ''), '"video"') > 0 THEN 1 ELSE 0 END) as video,
+          SUM(CASE WHEN instr(COALESCE(sources, ''), '"comment"') > 0 THEN 1 ELSE 0 END) as comment,
+          SUM(CASE WHEN instr(COALESCE(sources, ''), '"guess"') > 0 THEN 1 ELSE 0 END) as guess,
+          SUM(CASE WHEN instr(COALESCE(sources, ''), '"following"') > 0 THEN 1 ELSE 0 END) as following,
+          SUM(CASE WHEN instr(COALESCE(sources, ''), '"follower"') > 0 THEN 1 ELSE 0 END) as follower,
+          SUM(CASE
+            WHEN instr(COALESCE(sources, ''), '"video"') = 0
+              AND instr(COALESCE(sources, ''), '"comment"') = 0
+              AND instr(COALESCE(sources, ''), '"guess"') = 0
+              AND instr(COALESCE(sources, ''), '"following"') = 0
+              AND instr(COALESCE(sources, ''), '"follower"') = 0
+            THEN 1 ELSE 0 END) as seed
+        FROM task_queue`,
+      },
+      {
+        key: "jobsAgg",
+        mode: "one",
+        params: DEFAULT_TARGET_LOCATIONS,
+        sql: `SELECT
+          SUM(jobsTotal) as jobsTotal,
+          SUM(done) as done,
+          SUM(error) as error,
+          SUM(restricted) as restricted,
+          SUM(targetUsers) as targetUsers,
+          SUM(noVideo) as noVideo
+        FROM (
+          SELECT
+            COUNT(*) as jobsTotal,
+            SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) as done,
+            SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error,
+            SUM(CASE WHEN status = 'restricted' THEN 1 ELSE 0 END) as restricted,
+            SUM(CASE WHEN tt_seller = 1 AND verified = 0 AND ${TARGET_IN_SQL} THEN 1 ELSE 0 END) as targetUsers,
+            SUM(CASE WHEN no_video = 1 THEN 1 ELSE 0 END) as noVideo
+          FROM jobs
+          UNION ALL
+          SELECT
+            COUNT(*) as jobsTotal,
+            COUNT(*) as done,
+            0 as error,
+            0 as restricted,
+            0 as targetUsers,
+            SUM(CASE WHEN no_video = 1 THEN 1 ELSE 0 END) as noVideo
+          FROM jobs_done
+        )`,
+      },
+    ],
+    combine(results) {
+      const tq = results.tqAgg || {};
+      const jb = results.jobsAgg || {};
+      const total = (tq.tqTotal || 0) + (jb.jobsTotal || 0);
+      return {
+        totalUsers: total,
+        jobsTotal: total,
+        jobsPending: tq.pending || 0,
+        pendingUsers: tq.pending || 0,
+        processingUsers: tq.processing || 0,
+        processedUsers: jb.done || 0,
+        restrictedUsers: jb.restricted || 0,
+        errorUsers: jb.error || 0,
+        targetUsers: jb.targetUsers || 0,
+        sourceStats: {
+          seed: tq.seed || 0,
+          video: tq.video || 0,
+          comment: tq.comment || 0,
+          guess: tq.guess || 0,
+          following: tq.following || 0,
+          follower: tq.follower || 0,
+          processed: jb.done || 0,
+          restricted: jb.restricted || 0,
+          error: jb.error || 0,
+          noVideo: jb.noVideo || 0,
+        },
+      };
+    },
+  },
+  medium: {
+    ttl: MEDIUM_STATS_TTL,
+    sqls: [
+      {
+        key: "jobsBaseCount",
+        mode: "one",
+        sql: "SELECT COUNT(*) as total FROM jobs_base",
+      },
+      {
+        key: "userUpdateTasks",
+        mode: "one",
+        sql: "SELECT COUNT(*) as userUpdateTasks FROM jobs_base WHERE COALESCE(user_update_count, 0) <= 0",
+      },
+      {
+        key: "countryStats",
+        mode: "all",
+        sql: `SELECT country, SUM(cnt) as count, SUM(targetCount) as targetCount
+        FROM (
+          SELECT
+            COALESCE(location_created, '未知') as country,
+            COUNT(*) as cnt,
+            SUM(CASE WHEN tt_seller = 1 AND verified = 0 THEN 1 ELSE 0 END) as targetCount
+          FROM jobs
+          WHERE status = 'done'
+          GROUP BY COALESCE(location_created, '未知')
+          UNION ALL
+          SELECT
+            COALESCE(location_created, '未知') as country,
+            COUNT(*) as cnt,
+            0 as targetCount
+          FROM jobs_done
+          GROUP BY COALESCE(location_created, '未知')
+        )
+        GROUP BY country
+        ORDER BY count DESC`,
+      },
+      {
+        key: "targetCountryStats",
+        mode: "all",
+        params: DEFAULT_TARGET_LOCATIONS,
+        sql: `SELECT location_created as country, COUNT(*) as count
+        FROM jobs
+        WHERE tt_seller = 1 AND verified = 0 AND ${TARGET_IN_SQL}
+        GROUP BY location_created
+        ORDER BY count DESC`,
+      },
+    ],
+    combine(results) {
+      return {
+        jobsBaseTotal: results.jobsBaseCount?.total || 0,
+        userUpdateTasks: results.userUpdateTasks?.userUpdateTasks || 0,
+        countryStats: results.countryStats || [],
+        targetCountryStats: results.targetCountryStats || [],
+      };
+    },
+  },
+  slow: {
+    ttl: SLOW_STATS_TTL,
+    // rawJobs 走 store.getRawJobsCount()（模块内部自带 60s 缓存），不进分片 SQL
+    sqls: [
+      {
+        key: "commentTaskCount",
+        mode: "one",
+        sql: "SELECT COUNT(*) as c FROM videos WHERE user_update_count IS NULL OR user_update_count <= 0",
+      },
+    ],
+    combine(results, st) {
+      // tagCount/tagHighScore 从独立 tags.db 读取（跨库）
+      let tagCount = 0;
+      let tagHighScore = 0;
+      const tagDb = getTagDb();
+      if (tagDb) {
+        try {
+          tagCount =
+            tagDb.prepare("SELECT COUNT(*) as c FROM tags").get().c || 0;
+          tagHighScore =
+            tagDb
+              .prepare("SELECT COUNT(*) as c FROM tags WHERE score >= 70")
+              .get().c || 0;
+        } catch (e) {
+          console.error(`[stats] tag 库统计失败: ${e.message}`);
+        }
+      }
+      return {
+        rawJobs: st.getRawJobsCount ? st.getRawJobsCount() : 0,
+        commentTaskCount: results.commentTaskCount?.c || 0,
+        tagCount,
+        tagHighScore,
+      };
+    },
+  },
 };
 
-let statsRefreshing = false; // 防止并发刷新
+// 每组独立缓存状态
+const groupState = {};
+for (const name of Object.keys(STAT_GROUPS)) {
+  groupState[name] = { cache: null, cacheTime: 0, refreshing: false };
+}
 
-// 分片执行统计刷新：每个 SQL 单独一片，片间 setImmediate 让出事件循环，
-// 避免多个大查询连续执行冻结事件循环 5~30 秒（此前成簇超时的直接原因）
-function refreshStatsInShards(st) {
-  const slowKeys = Object.keys(SLOW_COUNT_SQLS);
-  const slowCounts = {};
+// 首次请求时 fast 组同步计算（task_queue + jobs 聚合，约 2s），
+// medium/slow 先返回占位再后台补全，避免启动初期一个请求阻塞 5~30s
+const EMPTY_GROUP = {
+  fast: {
+    totalUsers: 0,
+    jobsTotal: 0,
+    jobsPending: 0,
+    pendingUsers: 0,
+    processingUsers: 0,
+    processedUsers: 0,
+    restrictedUsers: 0,
+    errorUsers: 0,
+    targetUsers: 0,
+    sourceStats: {
+      seed: 0,
+      video: 0,
+      comment: 0,
+      guess: 0,
+      following: 0,
+      follower: 0,
+      processed: 0,
+      restricted: 0,
+      error: 0,
+      noVideo: 0,
+    },
+  },
+  medium: {
+    jobsBaseTotal: 0,
+    userUpdateTasks: 0,
+    countryStats: [],
+    targetCountryStats: [],
+  },
+  slow: { rawJobs: 0, commentTaskCount: 0, tagCount: 0, tagHighScore: 0 },
+};
 
-  function runSlowShard(i) {
-    if (i < slowKeys.length) {
-      const key = slowKeys[i];
+// 分片执行某组统计刷新：每个 SQL 单独一片，片间 setImmediate 让出事件循环
+function refreshGroupInShards(st, name) {
+  const g = groupState[name];
+  const spec = STAT_GROUPS[name];
+  g.refreshing = true;
+  const results = {};
+  let idx = 0;
+
+  function runShard() {
+    if (idx < spec.sqls.length) {
+      const s = spec.sqls[idx++];
       try {
-        const r = st.rawQuery(SLOW_COUNT_SQLS[key]);
-        slowCounts[key] = r?.rows?.[0]?.c || 0;
+        const params =
+          typeof s.params === "function" ? s.params() : s.params || [];
+        const r = st.rawQuery(s.sql, params);
+        if (r?.error) {
+          console.error(`[stats] ${name}.${s.key} 查询失败: ${r.error}`);
+          results[s.key] = null;
+        } else {
+          results[s.key] =
+            s.mode === "all" ? r?.rows || [] : r?.rows?.[0] || null;
+        }
       } catch (e) {
-        console.error(`[stats] 慢计数 ${key} 查询失败: ${e.message}`);
-        slowCounts[key] = 0;
+        console.error(`[stats] ${name}.${s.key} 查询失败: ${e.message}`);
+        results[s.key] = null;
       }
-      setImmediate(() => runSlowShard(i + 1));
+      setImmediate(runShard);
       return;
     }
-    // 慢计数全部完成 → dashboard 聚合作为最后一片执行
+    // 该组 SQL 全部完成 → 聚合写入缓存
     setImmediate(() => {
       try {
-        const stats = st.getDashboardStats(DEFAULT_TARGET_LOCATIONS, {
-          skipSlowCounts: true,
-        });
-        stats.rawJobs = slowCounts.rawJobs || 0;
-        stats.commentTaskCount = slowCounts.commentTaskCount || 0;
-        stats.tagCount = slowCounts.tagCount || 0;
-        stats.tagHighScore = slowCounts.tagHighScore || 0;
-        statsCache = stats;
-        statsCacheTime = Date.now();
+        g.cache = spec.combine(results, st);
+        g.cacheTime = Date.now();
       } catch (e) {
-        console.error(`[stats] 后台刷新失败: ${e.message}`);
+        console.error(`[stats] ${name} 聚合失败: ${e.message}`);
       } finally {
-        statsRefreshing = false;
+        g.refreshing = false;
       }
     });
   }
 
-  setImmediate(() => runSlowShard(0));
+  setImmediate(runShard);
 }
 
-function computeStatsIncremental(st) {
+// 计算某组统计：缓存有效→直接返回；过期→先回旧数据后台刷新；
+// 首次→fast 同步计算，medium/slow 回占位并后台补全
+function computeGroupStats(st, name) {
+  const g = groupState[name];
   const now = Date.now();
-  // 缓存有效 → 直接返回
-  if (statsCache && now - statsCacheTime < STATS_CACHE_TTL) {
-    return statsCache;
+  if (g.cache && now - g.cacheTime < STAT_GROUPS[name].ttl) {
+    return g.cache;
   }
-  // 缓存过期但存在 → 先返回旧数据，后台分片刷新
-  if (statsCache && !statsRefreshing) {
-    statsRefreshing = true;
-    refreshStatsInShards(st);
-    return statsCache;
+  if (g.cache) {
+    if (!g.refreshing) refreshGroupInShards(st, name);
+    return g.cache;
   }
-  // 首次加载 → 同步计算 dashboard 基础统计（启动后仅一次），
-  // 慢计数随后台分片补全，不阻塞本次响应之外的请求
-  const stats = st.getDashboardStats(DEFAULT_TARGET_LOCATIONS, {
-    skipSlowCounts: true,
-  });
-  statsCache = stats;
-  statsCacheTime = now;
-  if (!statsRefreshing) {
-    statsRefreshing = true;
-    refreshStatsInShards(st);
+  if (name === "fast") {
+    // 首次同步计算 fast 组（约 2s），仅启动后首次请求发生
+    try {
+      const results = {};
+      for (const s of STAT_GROUPS[name].sqls) {
+        const params =
+          typeof s.params === "function" ? s.params() : s.params || [];
+        const r = st.rawQuery(s.sql, params);
+        results[s.key] =
+          s.mode === "all" ? r?.rows || [] : r?.rows?.[0] || null;
+      }
+      g.cache = STAT_GROUPS[name].combine(results, st);
+    } catch (e) {
+      console.error(`[stats] fast 首次同步计算失败: ${e.message}`);
+      g.cache = EMPTY_GROUP.fast;
+    }
+    g.cacheTime = now;
+  } else {
+    g.cache = EMPTY_GROUP[name];
+    g.cacheTime = now;
   }
-  return statsCache;
+  if (!g.refreshing) refreshGroupInShards(st, name);
+  return g.cache;
+}
+
+// 合并三组缓存，返回完整 stats（字段结构与旧 getDashboardStatsFromDb 返回一致）
+function computeStatsIncremental(st) {
+  return {
+    ...computeGroupStats(st, "fast"),
+    ...computeGroupStats(st, "medium"),
+    ...computeGroupStats(st, "slow"),
+  };
+}
+
+// 快项失效：任务领取/提交后调用，下一次 /api/stats 请求即触发 fast 组后台刷新
+function markFastStatsDirty() {
+  groupState.fast.cacheTime = 0;
 }
 
 function readBody(req) {
@@ -294,6 +544,30 @@ export function startWatchServer(
   return new Promise((_resolve, reject) => {
     const store = existingStore || createStore(dataAnchor, options);
 
+    // 在启动时确保关键索引存在，减少慢查询（CREATE INDEX IF NOT EXISTS 是幂等的）
+    try {
+      const ensureIdx = [
+        "CREATE INDEX IF NOT EXISTS idx_jobs_status ON jobs(status)",
+        "CREATE INDEX IF NOT EXISTS idx_jobs_loc ON jobs(location_created)",
+        "CREATE INDEX IF NOT EXISTS idx_jobs_seller_verified_loc ON jobs(tt_seller, verified, location_created)",
+        "CREATE INDEX IF NOT EXISTS idx_task_queue_status ON task_queue(status)",
+        "CREATE INDEX IF NOT EXISTS idx_jobs_done_list ON jobs_done(pinned, processed_at, follower_count, unique_id) WHERE status = 'done'",
+        "CREATE INDEX IF NOT EXISTS idx_jobs_done_loc ON jobs_done(location_created)",
+        "CREATE INDEX IF NOT EXISTS idx_videos_user_update ON videos(user_update_count)",
+        // product-fill 领任务查询的部分索引：只索引候选行，避免全表扫描 164 万行
+        "CREATE INDEX IF NOT EXISTS idx_jobs_product_fill ON jobs(claimed_at, updated_at) WHERE top_video_seo_url IS NOT NULL AND top_video_seo_url != '' AND (product_name IS NULL OR product_name = '') AND product_rating IS NULL AND product_sold_count IS NULL",
+      ];
+      for (const sql of ensureIdx) {
+        try {
+          if (store && store.rawQuery) store.rawQuery(sql);
+        } catch (e) {
+          console.error(`[startup] 创建索引失败: ${e.message}`);
+        }
+      }
+    } catch (e) {
+      console.error(`[startup] 索引初始化异常: ${e.message}`);
+    }
+
     // 初始化 LLM 动态配置（SQLite > 环境变量 > 默认值）
     import("./llm-config.js").then((m) => m.loadLlmConfig());
 
@@ -568,6 +842,7 @@ export function startWatchServer(
             clientId: userId,
             locations: locations,
           });
+          markFastStatsDirty();
           sendJSON(res, 200, { hasJob: true, user: job });
         } else {
           logJob("CLAIM", {
@@ -711,6 +986,7 @@ export function startWatchServer(
             newUsers: ret.newUsers?.length || 0,
           });
           if (ret.saved) {
+            markFastStatsDirty();
             sendJSON(res, 200, ret);
           } else {
             sendJSON(res, 404, ret);

package/src/watch/tag-selflearn.js

@@ -11,7 +11,8 @@
  * 本模块不修改现有 tag-service.js，而是在其基础上叠加新能力。
  */
 
-import { getDb } from "./db-schema.js";
+// 注意：tag 域数据已迁移到独立 tags.db，使用 tag 库连接（别名 getDb 保持调用点不变）
+import { getTagDb as getDb } from "./db-schema.js";
 import { callLLM, LLM_MODEL, getLang, COUNTRY_LANG } from "./tag-service.js";
 
 // ====== 通用词根表（L1 探索起点） ======

package/src/watch/watchdog-server.js

@@ -10,13 +10,27 @@
  * 3. 新增 POST /api/watchdog/clear-llm 端点，手动清除指定客户端的 LLM 提示
  */
 
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  statSync,
+} from "fs";
 import { join } from "path";
 import { homedir } from "os";
 
 const homeDir = homedir() || process.env.HOME || process.env.USERPROFILE || "";
 const WATCHDOG_CONFIG_PATH = join(homeDir, ".tt-help-watchdog.json");
 
+// ── 按需日志拉取（后台页面点击"日志"按钮 → 心跳下发 → 客户端回传 → 覆盖写盘） ──
+// 每个 (clientId, cmdId) 固定一个文件，永远只有最新一份，服务端内存零缓存。
+// 目录需在 watch(SYSTEM) 与 standalone(ZKJ) 间保持一致，部署时用 WATCHDOG_LOGS_DIR 统一。
+const LOGS_DIR =
+  process.env.WATCHDOG_LOGS_DIR || join(homeDir, ".tt-help-watchdog", "logs");
+const LOG_REQ_TTL_MS = 5 * 60 * 1000; // 请求排队 5 分钟未取走则作废（客户端离线）
+const logReqQueue = new Map(); // clientId -> [{cmdId, tail, requestedAt}]
+
 // ── 内存数据结构 ──
 const clients = new Map();
 const CLIENT_TIMEOUT_MS = 60 * 1000;
@@ -318,6 +332,18 @@ function getAllClientCountries() {
 
 // ── 工具函数 ──
 
+/** 校验文件路径段是否安全（不含路径分隔符/Windows 保留字符/穿越串） */
+function isSafeId(s) {
+  return (
+    typeof s === "string" &&
+    s.length > 0 &&
+    s.length <= 160 &&
+    !/[\/\\:*?"<>|]/.test(s) &&
+    !s.includes("..") &&
+    s !== "."
+  );
+}
+
 function readBody(req) {
   return new Promise((resolve, reject) => {
     let body = "";
@@ -394,6 +420,12 @@ async function handleHeartbeat(params, body, res) {
     clashCmdQueue.delete(userId);
   }
 
+  // 取出待下发的日志拉取请求（一次性，取走即清空；过期直接丢弃）
+  const pendingLogs = (logReqQueue.get(clientId) || []).filter(
+    (r) => Date.now() - r.requestedAt < LOG_REQ_TTL_MS,
+  );
+  if (logReqQueue.has(clientId)) logReqQueue.delete(clientId);
+
   const ts = new Date().toLocaleTimeString("zh-CN", { hour12: false });
   console.error(
     `[watchdog ${ts}] 心跳: ${clientId} (${body.hostname || "?"}, user=${userId || "?"}) ${body.processes?.length || 0}进程, 返回${commands.length}条命令${clashCommands.length ? ", " + clashCommands.length + "条Clash命令" : ""}`,
@@ -403,6 +435,7 @@ async function handleHeartbeat(params, body, res) {
     ok: true,
     commands,
     clashCommands: clashCommands.length > 0 ? clashCommands : undefined,
+    logRequests: pendingLogs.length > 0 ? pendingLogs : undefined,
     clientConfig: getClientConfigStored(userId),
     errorTrigger: getErrorTriggerStored(userId),
     loginPorts: getLoginPortsStored(userId),
@@ -424,6 +457,88 @@ async function handleGetClients(params, body, res) {
   });
 }
 
+// ── 按需日志拉取（点"日志"按钮 → 入队 → 心跳下发 → 客户端回传 → 覆盖写盘） ──
+
+/** 后台页面请求某客户端日志：请求入队，等该客户端下次心跳取走 */
+async function handleRequestLogs(params, body, res) {
+  const clientId = body.clientId ? String(body.clientId) : "";
+  const cmdId = body.cmdId ? String(body.cmdId) : "";
+  if (!isSafeId(clientId) || !isSafeId(cmdId)) {
+    sendJSON(res, 400, { ok: false, error: "clientId/cmdId 不合法" });
+    return;
+  }
+  const tail = Math.max(1, Math.min(Number(body.tail) || 500, 500));
+  // 同一 clientId 的同一 cmdId 只保留最新一条（重复点击不堆积）
+  let list = (logReqQueue.get(clientId) || []).filter(
+    (r) => r.cmdId !== cmdId && Date.now() - r.requestedAt < LOG_REQ_TTL_MS,
+  );
+  list.push({ clientId, cmdId, tail, requestedAt: Date.now() });
+  logReqQueue.set(clientId, list);
+  const ts = new Date().toLocaleTimeString("zh-CN", { hour12: false });
+  console.error(
+    `[watchdog ${ts}] 日志拉取请求: ${clientId}/${cmdId} (${tail}行)`,
+  );
+  sendJSON(res, 200, {
+    ok: true,
+    message: "已请求，等待客户端心跳回传",
+  });
+}
+
+/** 客户端回传日志 → 覆盖写约定文件（<LOGS_DIR>/<clientId>/<cmdId>.log） */
+async function handleReportLogs(params, body, res) {
+  const clientId = body.clientId ? String(body.clientId) : "";
+  const cmdId = body.cmdId ? String(body.cmdId) : "";
+  if (!isSafeId(clientId) || !isSafeId(cmdId)) {
+    sendJSON(res, 400, { ok: false, error: "clientId/cmdId 不合法" });
+    return;
+  }
+  if (!Array.isArray(body.logs)) {
+    sendJSON(res, 400, { ok: false, error: "logs 必须是数组" });
+    return;
+  }
+  try {
+    const dir = join(LOGS_DIR, clientId);
+    mkdirSync(dir, { recursive: true });
+    const text = body.logs.map((l) => String(l)).join("\n") + "\n";
+    writeFileSync(join(dir, cmdId + ".log"), text, "utf-8");
+    console.error(
+      `[watchdog] 日志落盘: ${clientId}/${cmdId} (${body.logs.length}行)`,
+    );
+    sendJSON(res, 200, { ok: true, lines: body.logs.length });
+  } catch (e) {
+    console.error(`[watchdog] 日志写盘失败: ${e.message}`);
+    sendJSON(res, 500, { ok: false, error: e.message });
+  }
+}
+
+/** 前端弹窗轮询读取日志文件（返回内容 + mtime，无文件返回 content:null） */
+async function handleGetLogsFile(params, body, res) {
+  const clientId = String(params.clientId || "");
+  const cmdId = String(params.cmdId || "");
+  if (!isSafeId(clientId) || !isSafeId(cmdId)) {
+    sendJSON(res, 400, { ok: false, error: "clientId/cmdId 不合法" });
+    return;
+  }
+  const file = join(LOGS_DIR, clientId, cmdId + ".log");
+  try {
+    if (!existsSync(file)) {
+      sendJSON(res, 200, { ok: false, content: null, mtimeMs: 0 });
+      return;
+    }
+    const stat = statSync(file);
+    const content = readFileSync(file, "utf-8");
+    sendJSON(res, 200, {
+      ok: true,
+      content,
+      mtimeMs: stat.mtimeMs,
+      size: content.length,
+    });
+  } catch (e) {
+    console.error(`[watchdog] 日志读取失败: ${e.message}`);
+    sendJSON(res, 500, { ok: false, error: e.message });
+  }
+}
+
 async function handleSetClientCommands(params, body, res) {
   const { userId, commands } = body;
   if (!userId) {
@@ -645,6 +760,7 @@ async function handleSetLoginPorts(params, body, res) {
 export function registerWatchdogRoutes(httpServer) {
   console.error("[watchdog] 看门狗服务端模块已加载");
   console.error(`[watchdog] 配置文件: ${WATCHDOG_CONFIG_PATH}`);
+  console.error(`[watchdog] 日志目录: ${LOGS_DIR}`);
   // 自动迁移：为已有命令补充唯一 ID
   migrateCommandIds();
 }
@@ -721,5 +837,17 @@ export async function tryHandleWatchdogRoute(
     await handleSetLoginPorts(params, body, res);
     return true;
   }
+  if (method === "POST" && routePath === "/api/watchdog/request-logs") {
+    await handleRequestLogs(params, body, res);
+    return true;
+  }
+  if (method === "POST" && routePath === "/api/watchdog/report-logs") {
+    await handleReportLogs(params, body, res);
+    return true;
+  }
+  if (method === "GET" && routePath === "/api/watchdog/logs-file") {
+    await handleGetLogsFile(params, body, res);
+    return true;
+  }
   return false;
 }