tiktok-scripts/tiktok-app/src/engine.js

/* ============================== src/engine.js ==============================
 * 执行引擎桥接：把界面收集的配置交给 tiktok-auto，再把它的进度读回来。
 *
 * ## 为什么走文件，不走内存
 * 界面与被唤起的引擎是**两个独立的 ScriptEngine**：各有各的全局作用域，
 * 界面里的对象传不过去（实测确认）。所以两边只通过约定好的四个文件说话：
 *
 *   run-config.json     界面 → 人/追溯：完整配置快照（人可读）
 *   engine-config.json  界面 → 引擎：映射后的引擎配置
 *   run-state.json      引擎 → 界面：进度与终态
 *   stop.flag           界面 → 引擎：停止请求（内容是本次运行的 runId）
 *
 * 文件通道是**异步**的，所以界面这边的规则是：**所有动作以状态文件的回报为准**，
 * 而不是"我点了就当我做了"。点「停止运行」后界面显示"正在收尾"、
 * 等到引擎真的上报 stopped 才切回未运行 —— 否则界面说"已停止"而 TikTok 还在自己动，
 * 用户不知道该信谁。
 *
 * ## 为什么不删 stop.flag
 * 停止靠**比内容**而不是靠"文件在不在"：只有内容等于本次 runId 才算数。
 * 于是不必删除它（删除既有竞态，`files.remove` 又命中 MCP 危险调用黑名单），
 * 上一轮残留的标志也不会误杀下一轮。
 *
 * ## 能力边界要如实说
 * tiktok-auto 目前实现的是「搜索 → 逐个看 → 评论」。界面「执行操作」里的
 * 关注 / 私信 / 点赞**尚未接入**，`buildConfig()` 会把它们逐条记进 notes，
 * 由调用方决定怎么告知用户 —— **绝不静默忽略**：
 * 用户勾了点赞却什么都没发生，比明确告知"尚未支持"糟得多。
 */

var Engine = {};

Engine.DIR = "/sdcard/tiktok_app";
Engine.CONFIG_PATH = Engine.DIR + "/engine-config.json";
Engine.STATE_PATH = Engine.DIR + "/run-state.json";
Engine.STOP_FLAG_PATH = Engine.DIR + "/stop.flag";

/**
 * 引擎的日志文件（jsonl，一行一条）。
 *
 * 2026-10-13 新增：D3 运行详情里的「执行日志」要看的就是它。
 * 为什么走文件而不是读 console：引擎是**另一个 ScriptEngine**，
 * 它的 stdout 界面根本读不到（见本文件头的通道说明）。
 * 引擎侧由 `logger.setSink` → `files.append` 落盘（tiktok-auto/src/bridge.js）。
 */
Engine.LOG_PATH = Engine.DIR + "/run-log.jsonl";

/** 一条记录最多带走多少行日志（记录要落盘，不能让日志把它撑爆）。 */
Engine.LOG_MAX_LINES = 200;

/** 引擎产物在项目里的相对位置（项目模式下从这个位置找） */
Engine.SCRIPT_RELATIVE = "tiktok-auto/dist/tiktok-auto.js";

/** 本次运行的标识。由界面生成并同时告诉引擎与停止标志，三方比对。 */
Engine.RUN_ID = "";

/** 上次定位到的引擎产物路径；null 表示还没找过 */
Engine.scriptPath = null;

/**
 * 是否**确实在引擎列表里见过**子引擎。
 *
 * 用途唯一：给"引擎没写终态就没了"的兜底判定加一道保险。
 * `engines.all()` 在不同运行时里的可见性不完全一致 —— 如果它从来就不报告子引擎，
 * 那"看不到子引擎"这件事毫无信息量，此时宁可不判定，也不要误把正在跑的运行结束掉。
 */
Engine.sawChild = false;

/* ------------------------------------------------------------ 运行标识 */

/**
 * 生成本次运行的标识。
 * 用「时间戳 + 随机串」：同一秒内连点两次也不会撞，
 * 而且人在日志里一眼能看出这是哪一次运行。
 */
Engine.newRunId = function () {
    return "run-" + Date.now() + "-" + Math.floor(Math.random() * 100000);
};

/* ------------------------------------------------------------ 定位引擎 */

/** 探测用的候选路径，按「最可能正确」排序。 */
Engine.candidates = function () {
    var list = [];

    /* ① 入口脚本同级 —— 项目模式下最准。
     *    用 myEngine().source 而不是 files.cwd()：后者依赖运行方式，
     *    前者永远是入口脚本的真实路径。 */
    try {
        var source = String(engines.myEngine().source || "");
        var cut = source.lastIndexOf("/");
        if (cut > 0) {
            list.push(source.substring(0, cut) + "/" + Engine.SCRIPT_RELATIVE);
        }
    } catch (e) {
        /* 取不到就靠后面的候选 */
    }

    /* ② 扫一层项目目录：产物可能来自另一个项目文件夹 */
    try {
        var names = files.listDir("/sdcard/Scripts");
        for (var i = 0; i < names.length; i += 1) {
            var dir = "/sdcard/Scripts/" + names[i];
            if (files.isDir(dir)) {
                list.push(dir + "/" + Engine.SCRIPT_RELATIVE);
            }
        }
    } catch (e) {
        /* 没这个目录就跳过 */
    }

    /* ③ 扁平部署：产物被单独拷到 Download（手工推送时的常见形态） */
    list.push("/sdcard/Download/tiktok-auto.js");
    list.push(Engine.DIR + "/tiktok-auto.js");

    return list;
};

/**
 * 找到引擎产物。
 * @returns 路径；找不到返回空串（调用方负责给出可操作的提示）
 */
Engine.locate = function () {
    var list = Engine.candidates();
    for (var i = 0; i < list.length; i += 1) {
        try {
            if (files.exists(list[i])) {
                Engine.scriptPath = list[i];
                return list[i];
            }
        } catch (e) {
            /* 单个候选探测失败不该中断整轮查找 */
        }
    }
    Engine.scriptPath = null;
    return "";
};

/* ------------------------------------------------------------ 配置映射 */

function trimAll(text) {
    return String(text).replace(/^\s+|\s+$/g, "");
}

/**
 * 读文本文件的行，跳过空行与 `#` 开头的注释行。
 * 读不到（文件不存在 / 权限问题）时返回空数组 —— 调用方按"没配"处理。
 */
function readLines(path) {
    var out = [];
    try {
        if (!path || !files.exists(path)) { return out; }
        var lines = String(files.read(path)).split(/\r?\n/);
        for (var i = 0; i < lines.length; i += 1) {
            var text = trimAll(lines[i]);
            if (text !== "" && text.charAt(0) !== "#") { out.push(text); }
        }
    } catch (e) {
        console.log("[engine] 读取文本失败 " + path + ": " + e);
    }
    return out;
}

function randomInt(min, max) {
    var low = Math.floor(min);
    var high = Math.floor(max);
    if (high < low) { high = low; }
    return low + Math.floor(Math.random() * (high - low + 1));
}

/** 秒 → 毫秒，并给一个下限：0 秒会让"观看"立刻返回，等于没看 */
function seconds(ms) {
    return Math.max(1000, Math.floor(ms) * 1000);
}

/**
 * 界面配置 → 引擎配置。
 *
 * @param task 当前要跑的任务（`App.startRun` 传进来的那个对象，含 `task` 字段）
 * @returns { config, notes }
 *   notes 是「用户表达了意图、但引擎这次做不到」的条目，逐条是人话。
 */
Engine.buildConfig = function (task, opts) {
    /* 两条链路的配置形状完全不同（视频链路是"搜索→看→评"，ID提取是"取材清单"），
     * 所以在这里分派，而不是往一个函数里塞两套 if —— 那样两边都会变得难读且易改错。 */
    if (task && task.task === "id") {
        return Engine.buildIdConfig(opts);
    }
    return Engine.buildVideoConfig();
};

/* ------------------------------------------------------------ ID 提取 */

/** ID 提取的产物目录（与其它通道文件同根，方便一起清理/查看） */
Engine.ID_DIR = "/sdcard/Download/tiktok_app";

/**
 * 断点文件（ID提取的"跑到哪了"）。
 *
 * 与产物同目录：用户清产物时看得见它；而且它引用的是 runFile 的绝对路径，
 * 放在一起语义最直白。引擎侧同一份路径由 `id.resume.path` 传下去。
 */
Engine.ID_PROGRESS_PATH = Engine.ID_DIR + "/id_progress.json";

/**
 * 界面 → 引擎（task = 'id'）。
 *
 * ## 取材清单几乎是原样透传
 * `Sources` 模块当初就是**照着引擎侧的契约**设计的（`kind` + 每种起点的参数 + `expand`），
 * 所以这里不需要再翻译一遍字段名。少一层翻译就少一处"路径拼错=静默丢值"的机会。
 *
 * ## 做不到的项一律进 notes
 * 这是项目一贯的规矩：用户勾了却什么都没发生，比明确告知"这次不生效"糟得多。
 */
Engine.buildIdConfig = function (opts) {
    var notes = [];
    var base = "tabs.id.features.";

    var sources = Sources.list();
    var engineSources = [];
    for (var i = 0; i < sources.length; i++) {
        var one = sources[i];
        /* `key` 就是界面的 `id`：断点按它认"哪条取材做完了"。
         * 以前刻意不带（引擎不需要），但续跑必须带 —— 否则断点里的条目和配置里的
         * 条目只能靠下标对齐，用户删一条就全错位。 */
        engineSources.push({
            key: one.id || "",
            kind: one.kind,
            anchors: one.anchors || "",
            lists: one.lists || [],
            searchType: one.searchType || "users",
            keyword: one.keyword || "",
            videoSource: one.videoSource || "screen",
            videoKeyword: one.videoKeyword || "",
            path: one.path || "",
            expand: one.expand || ""
        });
    }

    var config = {
        task: "id",
        id: {
            sources: engineSources,
            filter: {
                private: Store.getBool(base + "filterPrivate"),
                noAvatar: Store.getBool(base + "filterNoAvatar"),
                langRegion: Store.getEnum(base + "langRegion", "langRegion"),
                nicknameCheck: Store.getEnum(base + "nicknameCheck", "nicknameCheck"),
                /* 四组区间：界面是"最小值 / 最大值"两格，0 表示该侧不设限 */
                follow: { min: Store.getNumber(base + "followMin"), max: Store.getNumber(base + "followMax") },
                fans: { min: Store.getNumber(base + "fansMin"), max: Store.getNumber(base + "fansMax") },
                likes: { min: Store.getNumber(base + "likesMin"), max: Store.getNumber(base + "likesMax") },
                videos: { min: Store.getNumber(base + "videosMin"), max: Store.getNumber(base + "videosMax") }
            },
            output: {
                dir: Engine.ID_DIR,
                historyPath: Engine.ID_DIR + "/uid_extracted.txt",
                dedupeHistory: Store.getBool(base + "dedupeHistory"),
                dryRun: false,
                /* 0 = 不限。引擎另有「单次最长运行」与「解析 uid 独立预算」两道时长护栏 */
                limit: Store.getNumber(base + "extractLimit"),
                /* 抓完之后换数字 uid。默认开（数字 uid 在界面上读不到，不换就得事后另跑），
                 * 每个约多花 2.5 秒 —— 「输出」卡片上给了开关，用户可关。 */
                resolveUid: Store.getBool(base + "resolveUid")
            },
            guard: {
                /* 抓取阶段最长多久（分钟 → 毫秒）。到点收尾，已抓的不丢。 */
                maxRuntimeMs: Math.max(1, Store.getNumber(base + "maxRuntimeMin")) * 60 * 1000
            },
            /**
             * 断点续跑。**只有点「继续」时才为 true**。
             *
             * 引擎侧看到它才会去读断点文件；普通「开始运行」传 false，
             * 于是"想从头跑一次"永远是从头跑（不会被上一轮的断点悄悄接管）。
             */
            resume: {
                enabled: !!(opts && opts.resume),
                path: Engine.ID_PROGRESS_PATH
            }
        },
        runtime: {
            configPath: Engine.CONFIG_PATH,
            dryRun: false,
            maxRuntimeMs: 0
        }
    };

    notes = notes.concat(Engine.unsupportedNotes({ task: "id" }));

    /* 「本地去重」关掉时要说清楚后果：它不只是"少一道过滤"，
     * 而是同一个 ID 会在产物文件里重复出现，下游私信会重复发。 */
    if (!Store.getBool(base + "dedupeLocal")) {
        notes.push("\u672C\u5730\u53BB\u91CD\uFF1A\u5DF2\u5173\u95ED\uFF0C\u540C\u4E00\u4E2A ID \u53EF\u80FD\u91CD\u590D\u5199\u5165");
    }

    return { config: config, notes: notes };
};

/* ------------------------------------------------------------ 视频链路 */

Engine.buildVideoConfig = function () {
    var notes = [];

    var keyword = Store.getText("tabs.video.keyword");
    var stopMin = Store.getNumber("tabs.video.stopMin");
    var stopMax = Store.getNumber("tabs.video.stopMax");
    var intervalMin = Store.getNumber("tabs.video.intervalMin");
    var intervalMax = Store.getNumber("tabs.video.intervalMax");
    var doComment = Store.getBool("tabs.video.actions.comment");

    var pool = readLines(Store.getText("tabs.video.commentTextPath"));
    if (doComment && pool.length === 0) {
        notes.push("\u8BC4\u8BBA\u6587\u672C\u91CC\u6CA1\u6709\u53EF\u7528\u884C\uFF0C"
                   + "\u672C\u6B21\u4F1A\u7528\u5185\u7F6E\u9ED8\u8BA4\u8BC4\u8BBA");
    }

    var config = {
        target: {
            keyword: keyword,
            /* 「停止个数 最小值 ~ 最大值」= 每次运行在这个区间里随机停 ——
             * 固定不变会让每次运行的行为完全一样，反而更容易被看出是脚本。 */
            maxVideos: randomInt(stopMin, stopMax),
            resultTab: "Top",
            pickStrategy: "random"
        },
        /* 界面的「间隔时间（秒）」映射为**每个视频的观看时长**。
         * 引擎目前没有单独的"两个视频之间的停顿"配置，而"看 20 秒再操作"
         * 与"每 20 秒处理一个"在行为上是一回事。 */
        watch: {
            minMs: seconds(intervalMin),
            maxMs: seconds(intervalMax)
        },
        /* 点赞 / 关注：与评论同级的两个动作开关。
         * 界面上「执行操作」是四项多选，用户勾了才做 —— 没勾就一个都不点。 */
        likes: {
            enabled: Store.getBool("tabs.video.actions.like")
        },
        follows: {
            enabled: Store.getBool("tabs.video.actions.follow")
        },
        comments: {
            /* ★ 勾了「评论」才发评论。没勾就只是浏览 ——
             * 引擎侧据此跳过评论动作，而不是照默认值照发。
             * 用户的意图优先于引擎的默认行为。 */
            enabled: doComment,
            avoidRepeatWithinRun: true,
            verifyInList: true
        },
        runtime: {
            configPath: Engine.CONFIG_PATH,
            dryRun: false,
            maxRuntimeMs: 0
        }
    };

    if (pool.length > 0) {
        config.comments.pool = pool;
    }

    notes = notes.concat(Engine.unsupportedNotes({ task: "video" }));
    return { config: config, notes: notes };
};

/**
 * 引擎这次做不到、但用户可能勾了的项。
 *
 * 单独抽出来是因为它只跟「已实现的动作集合」有关，
 * 将来引擎接入了点赞，**只改这一个函数**就够。
 */
Engine.unsupportedNotes = function (task) {
    var notes = [];
    if (task && task.task === "id") {
        return Engine.unsupportedIdNotes();
    }
    /* 点赞与关注已由引擎实现（src/interact.js），不再报"尚未实现"。
     * 只剩私信一项还在等（见 UID私信 任务）。 */
    if (Store.getBool("tabs.video.actions.dm")) {
        notes.push("\u79C1\u4FE1\u52A8\u4F5C\uFF1A\u5F15\u64CE\u5C1A\u672A\u5B9E\u73B0");
    }
    return notes;
};

/**
 * ID 提取里"用户可能配了、但这次不生效"的项。
 *
 * 判据是**偏离默认值**，而不是"有值" —— 这一条很关键：
 * 功能设置里有好几项的默认值本身就是非空的（`regionCodes = "JP#TW#US"`、
 * `aiAgeMax = 20`、`videosMax = 500000`）。若按"有值就报"，
 * 每次运行都会冒出一串"未生效"，把真正需要注意的那条淹没 ——
 * 而 note 的本意是"你表达了意图，这次做不到"，默认值并不代表任何意图。
 */
Engine.unsupportedIdNotes = function () {
    var notes = [];
    var base = "tabs.id.features.";

    /** 这一项被用户改过吗（与默认值不同） */
    function changed(path) {
        return String(Store.get(path)) !== String(Store.defaultOf(path));
    }

    /* AI 三项：需要模型，本次不做。界面上是灰行，理论上改不动；
     * 老配置里可能残留过值，所以仍然按"改过才报"来处理。 */
    if (changed(base + "aiAvatar") && Store.getBool(base + "aiAvatar")) {
        notes.push("AI \u5934\u50CF\u8BC6\u522B\uFF1A\u5C1A\u672A\u63A5\u5165");
    }
    if (changed(base + "aiGender") && Store.getBool(base + "aiGender")) {
        notes.push("AI \u6027\u522B\u8BC6\u522B\uFF1A\u5C1A\u672A\u63A5\u5165");
    }
    if (changed(base + "aiAgeMax") && Store.getNumber(base + "aiAgeMax") > 0) {
        notes.push("AI \u5E74\u9F84\u8BC6\u522B\uFF1A\u5C1A\u672A\u63A5\u5165");
    }

    /* 云端去重：契约已定但服务端没接。降级为本地去重并**说出来**，绝不静默。 */
    if (Store.getBool(base + "cloudDedupe")) {
        notes.push("\u4E91\u7AEF\u53BB\u91CD\uFF1A\u670D\u52A1\u672A\u63A5\u5165\uFF0C\u672C\u6B21\u53EA\u7528\u672C\u5730\u53BB\u91CD");
    }

    /* 视频量门槛：真机实测用户页**只显示 关注/粉丝/获赞 三组数字，没有视频数**。
     * 引擎侧对这条的处理是"放行 + 告知"（见 tiktok-auto/src/filters.js 文件头）。
     * 默认上限 500000 在语义上等于"不限"，所以只有用户真的收窄了才报。 */
    if (changed(base + "videosMin") || changed(base + "videosMax")) {
        notes.push("\u89C6\u9891\u91CF\u95E8\u69DB\uFF1A\u7528\u6237\u9875\u4E0D\u663E\u793A\u8BE5\u6570\u5B57\uFF0C\u672C\u6B21\u4E0D\u53C2\u4E0E\u8FC7\u6EE4");
    }

    /* 无头像靠像素判定，纯黑白照片会被误判 —— 用户勾了就得先知道这个局限。 */
    if (Store.getBool(base + "filterNoAvatar")) {
        notes.push("\u65E0\u5934\u50CF\u68C0\u6D4B\uFF1A\u6309\u50CF\u7D20\u8272\u5F69\u5224\u5B9A\uFF0C\u7EAF\u9ED1\u767D\u7167\u7247\u4F1A\u88AB\u8BEF\u5224");
    }

    /* 「提取区域」刻意**不进 notes**：它在界面上是一行灰字 + 「暂不支持」胶囊，
     * 用户已经看得到；每次运行再报一次只会变成噪音。它的值仍保留在配置里，
     * 将来接上数据源时直接生效。 */

    return notes;
};

/**
 * notes → 一句能放在 toast 里的话（没有就返回空串）。
 *
 * 只取每条的**短名**（中文冒号前的部分）拼起来：三条完整说明拼起来有四十多个字，
 * 那种长度的 toast 用户根本来不及读。完整内容在 run-config.json 里，随时可查。
 */
Engine.summarizeNotes = function (notes) {
    if (!notes || notes.length === 0) { return ""; }
    var names = [];
    for (var i = 0; i < notes.length; i += 1) {
        names.push(String(notes[i]).split("\uFF1A")[0]);
    }
    return names.join("/") + " \u672C\u6B21\u4E0D\u4F1A\u751F\u6548";
};

/* ------------------------------------------------------------ 启动 */

/**
 * 准备一次运行：定位产物 + 构建配置。
 *
 * @param task 当前要跑的任务（含 `task` 字段）；不传按视频链路处理（向后兼容）
 * @returns { ok, scriptPath, config, notes, error }
 *   error 是给用户看的（说清楚"缺什么、放哪"），不是技术异常串。
 */
Engine.prepare = function (task, opts) {
    var path = Engine.locate();
    if (!path) {
        return {
            ok: false,
            error: "\u627E\u4E0D\u5230\u6267\u884C\u5F15\u64CE\u4EA7\u7269\uFF08" + Engine.SCRIPT_RELATIVE + "\uFF09\u3002\n\n"
                 + "\u8BF7\u5728 PC \u4E0A\u6267\u884C node tiktok-auto/tools/build.js \u540E\uFF0C"
                 + "\u5C06 tiktok-auto/dist/tiktok-auto.js \u653E\u5230 \u9879\u76EE\u6839\u76EE\u5F55\u4E0B,\n"
                 + "\u6216\u76F4\u63A5\u63A8\u5230 /sdcard/Download/tiktok-auto.js\u3002"
        };
    }

    var built = Engine.buildConfig(task, opts);

    /* 「关键词为空」是**视频链路**的硬前提（空关键词搜索必失败）。
     * ID 提取不需要关键词 —— 它可以只从粉丝列表或文本文件取材，
     * 所以这条拦截必须按任务分支，否则 ID 提取第一次点运行就会被无理由挡下。 */
    if (task && task.task === "id") {
        if (!built.config.id.sources || built.config.id.sources.length === 0) {
            return {
                ok: false,
                scriptPath: path,
                error: "\u8BF7\u5148\u5728\u300CID\u63D0\u53D6\u300D\u9875\u6DFB\u52A0\u81F3\u5C11\u4E00\u6761\u53D6\u6750\u3002"
            };
        }
        return {
            ok: true,
            scriptPath: path,
            config: built.config,
            notes: built.notes
        };
    }

    if (trimAll(built.config.target.keyword) === "") {
        return {
            ok: false,
            scriptPath: path,
            error: "\u5173\u952E\u8BCD\u4E3A\u7A7A\uFF0C\u8BF7\u5148\u5728\u300C\u89C6\u9891\u529F\u80FD\u300D\u9875\u586B\u5199\u8981\u641C\u7D22\u7684\u5173\u952E\u8BCD\u3002"
        };
    }

    return {
        ok: true,
        scriptPath: path,
        config: built.config,
        notes: built.notes
    };
};

/** 把引擎配置落盘。返回是否成功。 */
Engine.writeConfig = function (config) {
    try {
        files.ensureDir(Engine.DIR + "/");
        files.write(Engine.CONFIG_PATH, JSON.stringify(config, null, 2));
        return true;
    } catch (e) {
        console.log("[engine] 引擎配置落盘失败: " + e);
        return false;
    }
};

/**
 * 唤起引擎（另一个 ScriptEngine，不是当前脚本的线程）。
 *
 * 参数用 `--key value` 的平铺形式传：Rhino 会把数组包装成 {"0":..,"1":..}，
 * 桥那边按数字下标取，两边约定越简单越不容易出错。
 */
Engine.launch = function (runId, scriptPath, opts) {
    try {
        var argv = [
            "--config", Engine.CONFIG_PATH,
            "--state", Engine.STATE_PATH,
            "--stop-flag", Engine.STOP_FLAG_PATH,
            "--log", Engine.LOG_PATH,
            "--run-id", runId
        ];
        /* 只有点「继续」才带这两个参数。普通「开始运行」绝不能带 ——
         * 不然用户想从头跑一次，结果它接着上次跑。 */
        if (opts && opts.resume) {
            argv.push("--resume");
            argv.push("--checkpoint");
            argv.push(Engine.ID_PROGRESS_PATH);
        }
        var handle = engines.execScriptFile(scriptPath || Engine.scriptPath, {
            arguments: argv
        });
        if (!handle) {
            return { ok: false, error: "\u5F15\u64CE\u542F\u52A8\u8FD4\u56DE\u7A7A\uFF08\u53EF\u80FD\u88AB\u7CFB\u7EDF\u62E6\u622A\uFF09" };
        }
        return { ok: true };
    } catch (e) {
        console.log("[engine] 唤起失败: " + e);
        return { ok: false, error: String(e) };
    }
};

/* ------------------------------------------------------------ 日志回读 */

/**
 * 读引擎这次运行写下的日志（D3 的「执行日志」）。
 *
 * 三条原则：
 *   · **一行坏了只丢一行**：jsonl 逐行 parse，坏行跳过 —— 进程被杀时最后一行
 *     常常是半截的，整份 JSON.parse 会直接全丢；
 *   · 只取**最近** LOG_MAX_LINES 行：记录要落盘，日志不能把它撑到几百 KB；
 *   · 读不到就返回空数组，由页面如实说明「本次没有回传日志」，
 *     绝不编一行"看起来像日志"的东西。
 */
Engine.readLog = function () {
    var out = [];
    try {
        if (!files.exists(Engine.LOG_PATH)) { return out; }
        var lines = String(files.read(Engine.LOG_PATH)).split("\n");
        var start = Math.max(0, lines.length - 1 - Engine.LOG_MAX_LINES);
        for (var i = start; i < lines.length; i++) {
            var text = String(lines[i]).replace(/^\s+|\s+$/g, "");
            if (text === "") { continue; }
            try {
                var one = JSON.parse(text);
                if (one && one.text) { out.push(one); }
            } catch (e) {
                /* 半截行：跳过这一行，其余照收 */
            }
        }
    } catch (e2) {
        console.log("[engine] 读取运行日志失败: " + e2);
    }
    return out;
};

/* ------------------------------------------------------------ 状态回读 */

/** 读引擎上报的状态。没有 / 读坏了都返回 null。 */
Engine.readState = function () {
    try {
        if (!files.exists(Engine.STATE_PATH)) { return null; }
        var parsed = JSON.parse(String(files.read(Engine.STATE_PATH)));
        return parsed && typeof parsed === "object" ? parsed : null;
    } catch (e) {
        return null;
    }
};

/** 运行中（含正在收尾）—— 界面据此继续显示状态条 */
Engine.isActiveStatus = function (status) {
    return status === "starting" || status === "running" || status === "stopping";
};

/** 终态 —— 界面据此结束运行态并告知结果 */
Engine.isTerminalStatus = function (status) {
    return status === "finished" || status === "stopped" || status === "failed";
};

/** 请求停止：写停止标志（内容 = runId，引擎比对通过才会停） */
Engine.requestStop = function (runId) {
    try {
        files.ensureDir(Engine.DIR + "/");
        files.write(Engine.STOP_FLAG_PATH, String(runId));
        return true;
    } catch (e) {
        console.log("[engine] 写停止标志失败: " + e);
        return false;
    }
};

/**
 * 引擎是否还活着。
 *
 * 用途只有一个：**兜底判定"引擎没写终态就没了"**（被系统杀掉、被手工停掉）。
 * 查不出来时返回 true（当作还活着）—— 宁可多显示一会儿"运行中"，
 * 也不要误判成"已结束"而把运行态清掉、让用户以为跑完了。
 */
Engine.childAlive = function () {
    try {
        var mine = engines.myEngine();
        var all = engines.all() || [];
        for (var i = 0; i < all.length; i += 1) {
            var one = all[i];
            if (one && String(one.id) !== String(mine.id)) {
                return true;
            }
        }
        return false;
    } catch (e) {
        return true;
    }
};

/** 复位内存态。**不删文件**：状态靠 runId 比对，残留自然失效。 */
Engine.reset = function () {
    Engine.RUN_ID = "";
};