data-preheating-astro 0.1.1

package/dist/tools/httpTrace.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * HTTP 请求追踪工具（独立于业务逻辑）。
+ *
+ * 目标：
+ * - 记录：当前任务执行了哪些接口、语言、每个请求耗时、状态码等（可扩展字段）
+ * - 落盘：jsonl（每行一个 JSON，后续字段可随时追加）
+ * - 汇总：任务结束打印 table（按模块/语言聚合 + 慢请求 Top）
+ *
+ * 说明：
+ * - 该工具不依赖业务流程，只接收 “请求结束事件” 并进行记录/汇总
+ * - 为减少 IO，内部做简单缓冲，达到阈值再 append
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpTrace = createHttpTrace;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const monitorFormat_1 = require("./monitorFormat");
+/**
+ * 创建 HTTP 追踪实例。
+ */
+function createHttpTrace(init) {
+    const startedAt = Date.now();
+    const modules = (init.modules || [])
+        .filter((m) => Boolean(m && m.name && m.endpoint))
+        .slice()
+        // endpoint 长的优先匹配（避免 /api/products 先匹配到 /api）
+        .sort((a, b) => (b.endpoint.length || 0) - (a.endpoint.length || 0));
+    // 生成日志文件路径：<logDirAbs>/export-http.<timestamp>.jsonl
+    const stamp = (0, monitorFormat_1.makeStamp)();
+    const logDir = init.logDirAbs;
+    const logFile = node_path_1.default.join(logDir, `export-http.${stamp}.jsonl`);
+    const summaryFile = node_path_1.default.join(logDir, `export-http.${stamp}.summary.log`);
+    // mkdir 返回 string|undefined（递归创建时），这里统一转为 Promise<void>，便于队列串行。
+    let writeQueue = node_fs_1.promises.mkdir(logDir, { recursive: true }).then(() => void 0);
+    let buffer = [];
+    // 汇总：lang::module -> count/avg/max/errors
+    const agg = new Map();
+    const slowTop = [];
+    function parseLocale(pathWithQuery) {
+        // 只解析 locale=...（保持实现简单）
+        const idx = pathWithQuery.indexOf("locale=");
+        if (idx === -1)
+            return "";
+        const start = idx + "locale=".length;
+        const end = pathWithQuery.indexOf("&", start);
+        const raw = end === -1 ? pathWithQuery.slice(start) : pathWithQuery.slice(start, end);
+        try {
+            return decodeURIComponent(raw).trim();
+        }
+        catch {
+            return raw.trim();
+        }
+    }
+    function inferModuleName(pathWithQuery) {
+        for (const m of modules) {
+            if (pathWithQuery.startsWith(m.endpoint))
+                return m.name;
+        }
+        return "unknown";
+    }
+    function inferLangDir(pathWithQuery) {
+        const locale = parseLocale(pathWithQuery);
+        return locale || "shared";
+    }
+    function enqueueWrite(lines) {
+        const chunk = lines.join("");
+        if (!chunk)
+            return;
+        writeQueue = writeQueue.then(async () => {
+            await node_fs_1.promises.appendFile(logFile, chunk, "utf8");
+        });
+    }
+    function flush() {
+        if (buffer.length === 0)
+            return;
+        const lines = buffer;
+        buffer = [];
+        enqueueWrite(lines);
+    }
+    function addSlow(x) {
+        slowTop.push(x);
+        slowTop.sort((a, b) => b.ms - a.ms);
+        if (slowTop.length > 15)
+            slowTop.length = 15;
+    }
+    function buildSummaryText() {
+        const lines = [];
+        lines.push("[export] HTTP\n");
+        lines.push(`[export] httpLog=${logFile}\n`);
+        if (init.baseUrl)
+            lines.push(`[export] httpBaseUrl=${init.baseUrl}\n`);
+        const rows = Array.from(agg.entries())
+            .map(([k, v]) => {
+            const avg = v.count > 0 ? Math.round(v.totalMs / v.count) : 0;
+            return { k, count: v.count, avg, max: v.maxMs, errors: v.errors };
+        })
+            .sort((a, b) => b.max - a.max);
+        lines.push("[export] TABLE lang::module | count | avg_ms | max_ms | errors\n");
+        for (const r of rows) {
+            lines.push(`[export] TABLE ${(0, monitorFormat_1.fmtCell)(r.k, 22)} ${(0, monitorFormat_1.fmtCell)(String(r.count), 6)} ${(0, monitorFormat_1.fmtCell)(String(r.avg), 7)} ${(0, monitorFormat_1.fmtCell)(String(r.max), 7)} ${String(r.errors)}\n`);
+        }
+        if (slowTop.length > 0) {
+            lines.push("[export] TABLE slow_requests(ms | status | lang | module | path)\n");
+            for (const s of slowTop) {
+                lines.push(`[export] TABLE ${(0, monitorFormat_1.fmtCell)(String(s.ms), 6)} ${(0, monitorFormat_1.fmtCell)(String(s.status || ""), 6)} ${(0, monitorFormat_1.fmtCell)(s.lang || "", 8)} ${(0, monitorFormat_1.fmtCell)(s.module || "", 12)} ${s.path || ""}\n`);
+            }
+        }
+        lines.push(`[export] httpElapsedMs=${Math.max(0, Date.now() - startedAt)}\n`);
+        return lines.join("");
+    }
+    return {
+        onHttpLog(entry) {
+            const pathWithQuery = typeof entry.pathWithQuery === "string" ? entry.pathWithQuery : "";
+            const durationMs = typeof entry.durationMs === "number" ? Math.max(0, Math.round(entry.durationMs)) : 0;
+            const ok = typeof entry.ok === "boolean" ? entry.ok : true;
+            const status = typeof entry.status === "number" ? entry.status : undefined;
+            const moduleName = inferModuleName(pathWithQuery);
+            const locale = parseLocale(pathWithQuery);
+            const langDir = inferLangDir(pathWithQuery);
+            // 写 jsonl：保留原 entry 字段，并追加推导字段（后续扩展只需加字段）。
+            const lineObj = {
+                ...entry,
+                moduleName,
+                langDir,
+                locale
+            };
+            buffer.push(`${JSON.stringify(lineObj)}\n`);
+            if (buffer.length >= 200)
+                flush();
+            // 更新聚合
+            const k = `${langDir}::${moduleName}`;
+            const cur = agg.get(k) || { count: 0, totalMs: 0, maxMs: 0, errors: 0 };
+            cur.count += 1;
+            cur.totalMs += durationMs;
+            cur.maxMs = Math.max(cur.maxMs, durationMs);
+            if (!ok)
+                cur.errors += 1;
+            agg.set(k, cur);
+            addSlow({ ms: durationMs, status, lang: langDir, module: moduleName, path: pathWithQuery });
+        },
+        async close() {
+            flush();
+            await writeQueue;
+            // 汇总仅写入文件，不输出到控制台。
+            await node_fs_1.promises.writeFile(summaryFile, buildSummaryText(), "utf8");
+        },
+    };
+}

package/dist/tools/monitorFormat.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * 监控/日志通用格式化工具（最小集合）。
+ *
+ * 目标：
+ * - 复用时间戳、列对齐等重复逻辑
+ * - 不引入复杂依赖，保持实现最简
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pad2 = pad2;
+exports.makeStamp = makeStamp;
+exports.fmtCell = fmtCell;
+exports.formatElapsedMs = formatElapsedMs;
+/**
+ * 固定两位数字字符串（不足补 0）。
+ */
+function pad2(n) {
+    return String(n).padStart(2, "0");
+}
+/**
+ * 生成日志/文件名用时间戳：YYYYMMDD-HHMMSS
+ *
+ * 说明：
+ * - 该格式与项目现有日志保持一致
+ * - 默认使用当前时间
+ */
+function makeStamp(d = new Date()) {
+    return `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
+}
+/**
+ * 固定宽度字符串：用于输出 table 对齐。
+ */
+function fmtCell(v, n) {
+    const s = v ?? "";
+    return s.length >= n ? s.slice(0, n) : s.padEnd(n, " ");
+}
+/**
+ * 将毫秒转为 HH:MM:SS
+ */
+function formatElapsedMs(ms) {
+    const sec = Math.max(0, Math.floor(ms / 1000));
+    const h = Math.floor(sec / 3600);
+    const m = Math.floor((sec % 3600) / 60);
+    const s = sec % 60;
+    return `${pad2(h)}:${pad2(m)}:${pad2(s)}`;
+}

package/dist/tools/robotsTxt.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * robots.txt 生成工具。
+ *
+ * 需求：
+ * - 接口 `/api/robot` 返回 `is_open` 用于判断是否生成 robots.txt
+ * - 当 `is_open=true` 时，从 `robots` 字段取值写入 robots.txt
+ * - 生成 robots.txt 不走缓存：每次运行只要 `is_open=true` 都使用本次接口的最新结果
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncRobotsTxt = syncRobotsTxt;
+exports.readRobotConfigFromEntry = readRobotConfigFromEntry;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const output_1 = require("../write/output");
+/**
+ * 根据接口结果生成/删除 robots.txt。
+ *
+ * 说明：
+ * - robots.txt 固定写入到输出目录根：`${outputDirAbs}/robots.txt`
+ * - 当关闭开关（is_open=false）时，会删除 robots.txt（若存在），避免旧文件残留
+ */
+async function syncRobotsTxt(params) {
+    const robotsPath = node_path_1.default.join(params.outputDirAbs, "robots.txt");
+    // 关闭：删除文件（若存在），保持输出干净且不残留旧规则。
+    if (!params.isOpen) {
+        try {
+            await node_fs_1.promises.rm(robotsPath, { force: true });
+        }
+        catch {
+            // 删除失败不阻断导出（保持简单）。
+        }
+        return;
+    }
+    // 开启：写入 robots 内容。若为空，仍生成空文件（有效但不拦截）。
+    const raw = typeof params.robotsContent === "string" ? params.robotsContent : "";
+    const text = raw.endsWith("\n") ? raw : `${raw}\n`;
+    await (0, output_1.writeTextAtomic)(robotsPath, text);
+}
+/**
+ * 从导出条目中读取 robots 配置字段（兼容两种结构）。
+ *
+ * 说明：
+ * - 常见结构 A：字段在顶层（例如 `{ id, is_open, robots }`）
+ */
+function readRobotConfigFromEntry(entry) {
+    /**
+     * 字段读取规则（严格，不做字段兼容）：
+     * - 只读取 entry 顶层字段：`is_open`（boolean）与 `robots`（string）
+     * - 若字段缺失或类型不符：直接抛错，让调用方明确接口字段
+     */
+    const e = entry;
+    if (!e || typeof e !== "object") {
+        throw new Error("robot 接口返回为空：无法读取 is_open/robots");
+    }
+    const isOpenRaw = e.is_open;
+    const robotsRaw = e.robots;
+    if (typeof isOpenRaw !== "boolean") {
+        throw new Error(`robot 接口字段类型不符：is_open 期望 boolean，实际=${typeof isOpenRaw}`);
+    }
+    // 仅当开启时才强制要求 robots 为 string（符合“开关关闭时无需生成内容”的直觉）。
+    if (isOpenRaw && typeof robotsRaw !== "string") {
+        throw new Error(`robot 接口字段类型不符：robots 期望 string，实际=${typeof robotsRaw}`);
+    }
+    return { isOpen: isOpenRaw, robots: typeof robotsRaw === "string" ? robotsRaw : "" };
+}

package/dist/transform/images.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Strapi 媒体字段扁平化。
+ *
+ * 目标：
+ * - 将常见的媒体字段提取为稳定结构（统一为数组）：
+ *   [{ url, alt, name, width, height }]
+ *
+ * 说明：
+ * - Strapi 常见结构为：
+ *   { data: { attributes: { url, name, alternativeText, width, height } } }
+ * - 或数组：{ data: [ { attributes: ... } ] }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenStrapiMedia = flattenStrapiMedia;
+exports.normalizeImageFieldsInPlace = normalizeImageFieldsInPlace;
+/**
+ * 将 Strapi 媒体字段转换为统一图片数组结构。
+ */
+function flattenStrapiMedia(input) {
+    const images = toImages(input);
+    return images && images.length > 0 ? images : undefined;
+}
+/**
+ * 递归扫描对象中的“图片相关字段”，并将其就地替换为统一图片数组结构。
+ *
+ * 说明（保持简单）：
+ * - 仅在 key 名称看起来像图片字段时才尝试转换，避免误伤普通 relation。
+ * - 支持常见结构：
+ *   - Strapi media：{ data: ... }（由 flattenStrapiMedia 处理）
+ *   - 组件包裹：{ alt, media: { id,url,... } } 或 [{ alt, media: ... }]
+ *   - 直接对象：{ url, alt, name, width, height }
+ */
+function normalizeImageFieldsInPlace(node) {
+    if (Array.isArray(node)) {
+        for (const it of node)
+            normalizeImageFieldsInPlace(it);
+        return;
+    }
+    if (!node || typeof node !== "object")
+        return;
+    const obj = node;
+    for (const key of Object.keys(obj)) {
+        const v = obj[key];
+        normalizeImageFieldsInPlace(v);
+        // 只在 key “像图片字段”时才尝试替换（避免误伤普通字段）
+        if (!looksLikeImageKey(key))
+            continue;
+        const images = toImages(v);
+        if (images && images.length > 0)
+            obj[key] = images;
+    }
+}
+/**
+ * 判断字段名是否像图片字段（简单规则）。
+ */
+function looksLikeImageKey(key) {
+    return /image|img|picture|photo|icon|logo|banner|cover|media/i.test(key);
+}
+/**
+ * 从未知结构中提取统一图片数组（提取不到返回 undefined）。
+ *
+ * 说明（尽量少代码，但覆盖常见场景）：
+ * - Strapi media：{ data: ... }
+ * - 组件包裹：{ alt, media: ... } 或 [{ alt, media: ... }]
+ * - 直接对象：{ url, alt, name, width, height }
+ */
+function toImages(input) {
+    // 1) 数组：把每个元素的结果拼起来
+    if (Array.isArray(input)) {
+        const all = [];
+        for (const it of input) {
+            const sub = toImages(it);
+            if (sub && sub.length > 0)
+                all.push(...sub);
+        }
+        return all.length ? all : undefined;
+    }
+    // 2) 直接对象 / Strapi media / 组件包裹
+    if (!input || typeof input !== "object")
+        return undefined;
+    const obj = input;
+    // 2.1) 组件包裹：{ alt, media: ... }
+    if (obj.media) {
+        const images = toImages(obj.media);
+        if (!images || images.length === 0)
+            return undefined;
+        const wrapperAlt = typeof obj.alt === "string" ? obj.alt : "";
+        return wrapperAlt ? images.map((x) => (x.alt ? x : { ...x, alt: wrapperAlt })) : images;
+    }
+    // 2.2) Strapi media：{ data: ... }
+    if (obj.data) {
+        const data = obj.data;
+        if (Array.isArray(data)) {
+            const arr = data.map((x) => fromStrapiNode(x)).filter((x) => Boolean(x));
+            return arr.length ? arr : undefined;
+        }
+        const one = fromStrapiNode(data);
+        return one ? [one] : undefined;
+    }
+    // 2.3) 直接对象：{ url, alt, name, width, height }
+    const url = typeof obj.url === "string" ? obj.url : "";
+    if (!url)
+        return undefined;
+    const alt = pickString(obj.alt) || pickString(obj.alternativeText) || "";
+    const name = pickString(obj.name) || "";
+    const width = pickNumberString(obj.width);
+    const height = pickNumberString(obj.height);
+    return [{ url, alt, name, width, height }];
+}
+/**
+ * 从 Strapi media 节点中提取 attributes。
+ */
+function fromStrapiNode(node) {
+    if (!node || typeof node !== "object")
+        return null;
+    const attrs = node.attributes;
+    if (!attrs || typeof attrs !== "object")
+        return null;
+    const url = pickString(attrs.url) || "";
+    if (!url)
+        return null;
+    const name = pickString(attrs.name) || "";
+    const alt = pickString(attrs.alternativeText) || pickString(attrs.alt) || "";
+    const width = pickNumberString(attrs.width);
+    const height = pickNumberString(attrs.height);
+    return { url, alt, name, width, height };
+}
+/**
+ * 读取字符串（非字符串返回空）。
+ */
+function pickString(v) {
+    return typeof v === "string" ? v : "";
+}
+/**
+ * 读取宽高并统一转为字符串（缺失返回空字符串）。
+ */
+function pickNumberString(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return typeof v === "string" ? v : "";
+}

package/dist/transform/objectPath.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * 对象路径取值工具。
+ *
+ * 说明：
+ * - 用于从 Strapi 返回的记录中按路径读取字段（如 attributes.slug）。
+ * - 保持实现极简，不做复杂类型推断。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getByPath = getByPath;
+exports.setByPath = setByPath;
+exports.deleteByPath = deleteByPath;
+exports.deleteLeafFieldsInDeepTree = deleteLeafFieldsInDeepTree;
+exports.deleteByPathAllowArray = deleteByPathAllowArray;
+function getByPath(obj, path) {
+    if (!path)
+        return undefined;
+    const parts = path.split(".").filter(Boolean);
+    let cur = obj;
+    for (const p of parts) {
+        if (cur == null)
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function setByPath(obj, path, value) {
+    const parts = path.split(".").filter(Boolean);
+    if (parts.length === 0)
+        return;
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const k = parts[i];
+        if (cur[k] == null || typeof cur[k] !== "object") {
+            cur[k] = {};
+        }
+        cur = cur[k];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+/**
+ * 按路径删除字段（不存在则忽略）。
+ *
+ * 说明：
+ * - 用于“字段重命名/映射”时删除旧字段，避免 index.json 保留重复字段。
+ * - 实现保持极简：只支持对象层级，不处理数组下标语法（如 a.0.b）。
+ */
+function deleteByPath(obj, path) {
+    const parts = path.split(".").filter(Boolean);
+    if (parts.length === 0)
+        return;
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const k = parts[i];
+        if (cur == null || typeof cur !== "object")
+            return;
+        cur = cur[k];
+    }
+    if (cur == null || typeof cur !== "object")
+        return;
+    delete cur[parts[parts.length - 1]];
+}
+/**
+ * 在“树形同名 key”结构中删除多个叶子字段（一次遍历删除多个字段）。
+ *
+ * 使用场景：
+ * - categories 这种多级 children：希望一次遍历删掉 children 节点上的多个内部字段
+ *
+ * 规则（保持简单）：
+ * - 仅处理：treeKey.leafKey 这种“二段路径”的删除（leafKey 仅为字段名，不含点号）
+ * - 对所有层级递归生效（children -> children -> ...），并支持 children 为数组或对象
+ * - 遇到非对象元素会跳过；循环引用用 WeakSet 避免死循环
+ */
+function deleteLeafFieldsInDeepTree(obj, treeKey, leafKeys) {
+    if (!treeKey || !leafKeys || leafKeys.length === 0)
+        return;
+    const root = obj[treeKey];
+    if (typeof root === "undefined")
+        return;
+    const seen = new WeakSet();
+    const walk = (v) => {
+        if (v == null)
+            return;
+        if (Array.isArray(v)) {
+            for (const item of v) {
+                if (!item || typeof item !== "object")
+                    continue;
+                walk(item);
+            }
+            return;
+        }
+        if (typeof v !== "object")
+            return;
+        const o = v;
+        if (seen.has(o))
+            return;
+        seen.add(o);
+        // 当前节点：删除多个叶子字段
+        for (const k of leafKeys) {
+            if (!k)
+                continue;
+            delete v[k];
+        }
+        // 同名 key：继续向下遍历（不限深度）
+        walk(v[treeKey]);
+    };
+    walk(root);
+}
+/**
+ * 按路径删除字段（支持“数组中对象”的遍历删除）。
+ *
+ * 使用场景：
+ * - 用于导出前删除字段（removeFields），避免输出一些不需要的内部字段
+ *
+ * 规则（保持简单）：
+ * - 路径仍然是点号路径（例如 children.ts_status_txt）
+ * - 当路径中间节点为数组时：会遍历数组中每个“对象元素”，继续按剩余路径删除
+ * - 支持“树形同名 key”的自动深度删除：例如 children.ts_at 会对多级 children 节点递归生效（不限深度）
+ * - 不支持数组下标语法（如 a.0.b），也不支持通配符
+ * - 遇到非对象元素会直接跳过（不报错）
+ */
+function deleteByPathAllowArray(obj, path) {
+    const parts = path.split(".").filter(Boolean);
+    if (parts.length === 0)
+        return;
+    /**
+     * 递归保持极简：
+     * - 遇到数组就遍历
+     * - 遇到对象按路径向下
+     * - 对“树形同名 key”（例如 children）做无限深度遍历，并对每个节点应用剩余路径删除
+     */
+    const del = (cur, idx) => {
+        if (cur == null)
+            return;
+        // 数组：对每个对象元素继续处理（idx 不前进，因为数组不是路径的一段）
+        if (Array.isArray(cur)) {
+            for (const item of cur) {
+                if (!item || typeof item !== "object")
+                    continue;
+                del(item, idx);
+            }
+            return;
+        }
+        // 非对象：无法继续，直接结束
+        if (typeof cur !== "object")
+            return;
+        // 最后一段：删除字段
+        if (idx >= parts.length - 1) {
+            delete cur[parts[parts.length - 1]];
+            return;
+        }
+        const k = parts[idx];
+        const next = cur[k];
+        if (typeof next === "undefined")
+            return;
+        /**
+         * 自动深度遍历：
+         * - 对 next（cur[k]）做遍历
+         * - 对每个节点执行剩余路径删除（idx+1）
+         * - 若节点仍然包含同名 key（k），继续向下遍历（children -> children -> ...）
+         */
+        const seen = new WeakSet();
+        const walkDeep = (v) => {
+            if (v == null)
+                return;
+            if (Array.isArray(v)) {
+                for (const item of v) {
+                    if (!item || typeof item !== "object")
+                        continue;
+                    walkDeep(item);
+                }
+                return;
+            }
+            if (typeof v !== "object")
+                return;
+            const obj0 = v;
+            if (seen.has(obj0))
+                return;
+            seen.add(obj0);
+            // 对当前节点应用剩余路径删除（从 idx+1 开始）
+            del(v, idx + 1);
+            // 继续沿着相同 key 向下遍历（若存在）
+            walkDeep(v[k]);
+        };
+        walkDeep(next);
+    };
+    del(obj, 0);
+}

package/dist/transform/pathNormalize.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 路径类字段规范化工具。
+ *
+ * 说明：
+ * - 用于把接口返回的 url_slug/slug 这类字段统一去掉前后 `/`
+ * - 仅对“导出字段值”做处理，不影响富文本 html 文件名生成（文件名仍单独做安全化）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimSlashes = trimSlashes;
+exports.normalizePathLikeKeysInPlace = normalizePathLikeKeysInPlace;
+/**
+ * 去掉字符串前后连续的 `/`。
+ *
+ * 规则：
+ * - `/a/` -> `a`
+ * - `//a//` -> `a`
+ * - `/` -> ``（空串）
+ */
+function trimSlashes(input) {
+    const raw = typeof input === "string" ? input.trim() : "";
+    if (!raw)
+        return "";
+    return raw.replace(/^\/+|\/+$/g, "");
+}
+/**
+ * 递归处理对象/数组内的“路径类字符串字段”（例如 url_slug）。
+ *
+ * 规则：
+ * - 遍历对象/数组
+ * - 命中 keys 中的字段且值为 string：就地替换为 trimSlashes(v)
+ */
+function normalizePathLikeKeysInPlace(node, keys) {
+    if (!node)
+        return;
+    if (Array.isArray(node)) {
+        for (const it of node)
+            normalizePathLikeKeysInPlace(it, keys);
+        return;
+    }
+    if (typeof node !== "object")
+        return;
+    const obj = node;
+    for (const [k, v] of Object.entries(obj)) {
+        if (keys.has(k) && typeof v === "string") {
+            obj[k] = trimSlashes(v);
+            continue;
+        }
+        normalizePathLikeKeysInPlace(v, keys);
+    }
+}