1

server/config/cron_tasks.js

@@ -4,10 +4,10 @@
  */
 
 export const cron_task_list = [
-  // 任务流：先跑列表，再依赖列表 URL 跑详情+评论
+  // 任务流：先跑列表，再依赖列表 URL 跑“详情+评论（合并 action）”
   {
     name: 'amazon_search_detail_reviews_every_1h',
-    cron_expression: '* */1 * * *', //   1小时执行一次
+    cron_expression: '0 */1 * * *', //   1小时执行一次
     type: 'flow',
     flow_name: 'amazon_search_detail_reviews',
     flow_payload: {

server/services/flows/amazon/amazon_search_detail_reviews_flow.js

@@ -15,6 +15,11 @@ function pick_asin_from_url(url) {
   return m && m[1] ? m[1].toUpperCase() : null;
 }
 
+/**
+ * 以“自然日(本地时区)”为口径判断当天是否已抓取过详情。
+ * - 详情数据写入 `amazon_product`，会更新 `updated_at`
+ * - 当 `updated_at >= 今日 00:00` 时，后续同日任务将跳过详情提取（仅抓评论）
+ */
 function get_today_start() {
   const d = new Date();
   d.setHours(0, 0, 0, 0);
@@ -214,6 +219,11 @@ export async function run_amazon_search_detail_reviews_flow(flow_payload) {
     const asin = pick_asin_from_url(url);
     const skip_detail = asin ? await has_detail_fetched_today(asin) : false;
 
+    /**
+     * 合并 action：同一详情页 tab 内一次完成 detail + reviews（减少两次打开页面/两次桥接调用）
+     * - 当 skip_detail=true：插件只返回 reviews（detail 不执行/不返回）
+     * - 返回结构：{ result: { detail?: {...}, reviews: {...} } }
+     */
     const res = await execute_action_and_record({
       action_name: 'amazon_product_detail_reviews',
       action_payload: { product_url: url, limit: reviews_limit, skip_detail },

server/services/schedule_loader.js

@@ -5,6 +5,11 @@ import { get_flow_runner } from './flows/flow_registry.js';
 const cron_jobs = [];
 const running_task_name_set = new Set();
 
+/**
+ * 启动参数开关（用于本地调试/冷启动后立即跑一次 cron）
+ * - 通过 VSCode/Cursor 的 launch.json 传入：--run_cron_now
+ * - 目的：避免等待 cron 表达式下一次触发（尤其是小时级任务）
+ */
 function has_argv_flag(flag_name) {
   const name = String(flag_name || '').trim();
   if (!name) return false;
@@ -20,7 +25,7 @@ async function run_cron_task(task) {
     throw new Error('cron_task 缺少 type');
   }
 
-
+  // 当前项目 cron 只允许跑 flow：任务入口集中，便于统一治理
   if (task.type === 'flow') {
     const run_flow = get_flow_runner(task.flow_name);
     await run_flow(task.flow_payload || {});
@@ -30,6 +35,11 @@ async function run_cron_task(task) {
   throw new Error(`cron_task type 不支持: ${task.type}`);
 }
 
+/**
+ * 统一的“防重复运行 + 执行 + 错误兜底”入口
+ * - 防止同一任务执行时间过长时，被下一次 cron 触发叠加执行
+ * - run_now 与定时触发复用同一套 guard，保证行为一致
+ */
 async function run_cron_task_with_guard(task_name, task) {
   if (running_task_name_set.has(task_name)) {
     // eslint-disable-next-line no-console
@@ -52,19 +62,19 @@ export async function start_all_cron_tasks() {
   for (const task of cron_task_list) {
     const task_name = task && task.name ? String(task.name) : 'cron_task';
 
+    // 先注册 cron（无论是否 run_now，都需要后续按表达式持续执行）
+    const job = cron.schedule(task.cron_expression, async () => {
+      await run_cron_task_with_guard(task_name, task);
+    });
+    console.log('job', { task_name, });
+    cron_jobs.push(job);
+
     if (run_now) {
+      // 启动时额外立刻跑一次（仍走 guard，避免与 cron 触发撞车）
       // eslint-disable-next-line no-console
       console.log('[cron] run_now', { task_name });
       await run_cron_task_with_guard(task_name, task);
     }
-    else {
-      const job = cron.schedule(task.cron_expression, async () => {
-        await run_cron_task_with_guard(task_name, task);
-      });
-      console.log('job', { task_name, });
-      cron_jobs.push(job);
-
-    }
   }
 }