helixlife-expert-cli 0.3.2 → 0.4.0

package/cli/dist/modules/analysis/prepare.js

@@ -0,0 +1,941 @@
+import { readFile } from "node:fs/promises";
+import { ANALYSIS_AGENT_NAME, ANALYSIS_HISTORY_UUID } from "./constants.js";
+import { resolveToolProductUuid, uploadLocalFile } from "./api.js";
+import { fetchToolMenuOrFallback, resolveToolByCode, } from "./catalog.js";
+import { buildSubmitArgsData, fetchAllArgs, fetchCloudPage, fetchHistoryDownloads, fetchHistoryPage, findHistoryByFuid, historyStatus, isHistoryFailed, isHistoryFinished, resolveDownloadUrl, submitModule, updateArgs, verifyUpload, } from "./bio.js";
+import { AnalysisChoiceError, AnalysisError } from "./errors.js";
+import { downloadArtifact, downloadToPath } from "./files.js";
+import { findArgsDataType, findDefaultCloud, findDefaultRecord, findRecordField, listUploadFields, } from "./inputs.js";
+import { asObject, deepMerge, isJsonObject, textOf } from "./json.js";
+import { applySpecificOverrides, assertOverrideSides, loadArgsMainConfig, parseSetOverrides, } from "./overrides.js";
+import { resolveUserPath } from "../../core/paths.js";
+import { buildArgsMainFromSchema, buildArgsSpecificFromSchema } from "./schema.js";
+export async function prepareTool(tool, flags) {
+    validateInputFlags(flags);
+    const productUuid = resolveToolProductUuid(flags.toolProductUuid);
+    const module = await resolveModule(tool, flags, productUuid);
+    const fetched = await fetchAllArgs(module.moduleId, module.uuid);
+    const mode = resolveInputMode(fetched, flags);
+    const config = await loadArgsMainConfig(module.moduleId, flags.configPath);
+    const setOverrides = deepMerge(config, parseSetOverrides(flags.sets));
+    let schema = fetched.args_main;
+    let specificSchema = fetched.args_specific;
+    let argsMain = deepMerge(buildArgsMainFromSchema(schema), setOverrides);
+    let argsSpecific = applySpecificOverrides(buildArgsSpecificFromSchema(specificSchema), flags.specifics);
+    let prepared = await resolvePreparedInput(fetched, flags, module, mode, argsMain);
+    if (prepared.schema.length > 0) {
+        schema = prepared.schema;
+        argsMain = deepMerge(buildArgsMainFromSchema(schema), setOverrides);
+    }
+    if (prepared.input.kind === "cloud") {
+        const updated = await updateArgs({
+            argsData: buildSubmitArgsData(prepared.duid, prepared.input),
+            argsKey: prepared.input.cloud.key,
+            argsMain,
+            argsSpecific,
+            moduleId: module.moduleId,
+            uuid: module.uuid,
+        });
+        const cloud = findDefaultCloud(updated.args_data);
+        if (cloud) {
+            prepared = {
+                ...prepared,
+                input: {
+                    kind: "cloud",
+                    cloud: { key: cloud.key, label: cloud.label, record: normalizeCloudRecord(cloud.record) },
+                },
+            };
+        }
+        schema = updated.args_main.length > 0 ? updated.args_main : schema;
+        specificSchema = updated.args_specific;
+        argsMain = deepMerge(buildArgsMainFromSchema(schema), setOverrides);
+        argsSpecific = applySpecificOverrides(buildArgsSpecificFromSchema(specificSchema), flags.specifics);
+    }
+    assertOverrideSides({
+        sets: flags.sets,
+        specifics: flags.specifics,
+        mainSchema: schema,
+        specificSchema,
+    });
+    return {
+        agent: ANALYSIS_AGENT_NAME,
+        argsMain,
+        argsSpecific,
+        argsSpecificSchema: specificSchema,
+        duid: prepared.duid,
+        input: prepared.input,
+        inputMode: mode,
+        inputSummary: summarizeInput(prepared.input),
+        moduleId: module.moduleId,
+        notice: fetched.notice,
+        route: module.route,
+        schema,
+        toolProductUuid: module.toolProductUuid,
+        uuid: module.uuid,
+    };
+}
+export function preparedPayload(run) {
+    return {
+        agent: run.agent,
+        args_main: run.schema,
+        args_main_defaults: buildArgsMainFromSchema(run.schema),
+        args_main_prepared: run.argsMain,
+        args_specific: run.argsSpecificSchema,
+        args_specific_defaults: buildArgsSpecificFromSchema(run.argsSpecificSchema),
+        args_specific_prepared: run.argsSpecific,
+        duid: run.duid,
+        ...run.inputSummary,
+        mode: run.inputMode,
+        module_id: run.moduleId,
+        notice: run.notice,
+        route: run.route,
+        tool_product_uuid: run.toolProductUuid,
+        uuid: run.uuid,
+    };
+}
+export async function executeTool(tool, flags) {
+    validateDownloadFlags(flags);
+    const prepared = await prepareTool(tool, flags);
+    const submittedAt = Date.now();
+    const result = await submitModule({
+        moduleId: prepared.moduleId,
+        uuid: prepared.uuid,
+        route: prepared.route,
+        argsMain: prepared.argsMain,
+        argsSpecific: prepared.argsSpecific,
+        argsData: buildSubmitArgsData(prepared.duid, prepared.input),
+    });
+    if (result.asyncSubmission) {
+        return resolveAsyncRun(prepared, flags, submittedAt, result.message);
+    }
+    const paths = flags.download
+        ? await downloadResult({
+            moduleId: prepared.moduleId,
+            uuid: prepared.uuid,
+            downloads: result.downloads,
+            file: result.file,
+            downloadPath: flags.download,
+            downloadItem: flags.downloadItem,
+            downloadLabel: flags.downloadLabel,
+        })
+        : [];
+    return directPayload(prepared, result, paths);
+}
+async function resolveAsyncRun(prepared, flags, submittedAt, message) {
+    const timeout = flags.download ? 60_000 : 12_000;
+    const record = await waitForLatestHistory(prepared.moduleId, submittedAt, timeout);
+    const summary = record ? toHistorySummary(record, prepared.moduleId) : null;
+    if (!flags.download || !textOf(record?.fuid)) {
+        const note = flags.download && !textOf(record?.fuid) ? `${message}，但暂未定位到历史记录。` : message;
+        return historyPayload(prepared, summary, note, "", [], []);
+    }
+    const fuid = textOf(record?.fuid);
+    const finished = await waitForHistoryCompletion(fuid, 60_000);
+    const finishedSummary = finished ? toHistorySummary(finished, prepared.moduleId) : summary;
+    if (!textOf(finished?.fuid)) {
+        const note = `${message}，但等待历史记录完成超时。`;
+        return historyPayload(prepared, finishedSummary, note, "", [], []);
+    }
+    const downloaded = await downloadHistoryWithRetry(fuid, prepared.moduleId, flags);
+    return historyPayload(prepared, finishedSummary, message, downloaded.body, downloaded.downloads, downloaded.paths);
+}
+async function downloadHistoryWithRetry(fuid, moduleId, flags) {
+    let last;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const viewed = await fetchHistoryDownloads(fuid);
+        try {
+            const paths = await downloadResult({
+                moduleId,
+                uuid: ANALYSIS_HISTORY_UUID,
+                downloads: viewed.downloads,
+                downloadPath: flags.download,
+                downloadItem: flags.downloadItem,
+                downloadLabel: flags.downloadLabel,
+            });
+            return { body: viewed.body, downloads: viewed.downloads, paths };
+        }
+        catch (error) {
+            if (!(error instanceof AnalysisError) || !isRetryableDownload(error) || attempt === 3) {
+                throw error;
+            }
+            last = error;
+            await sleep(3000);
+        }
+    }
+    throw last ?? new AnalysisError("下载失败，请稍后重试");
+}
+function directPayload(prepared, result, paths) {
+    // 路径与下载项放在 args_main / body 之前：宿主会截断长 stdout
+    return {
+        artifact: downloadArtifact(paths[0]),
+        download_path: paths[0],
+        download_paths: paths,
+        downloads: result.downloads,
+        result_source: "direct",
+        module_id: prepared.moduleId,
+        route: prepared.route,
+        submission_message: result.message,
+        agent: prepared.agent,
+        duid: prepared.duid,
+        file: result.file ?? null,
+        history: null,
+        history_hint: null,
+        ...prepared.inputSummary,
+        mode: prepared.inputMode,
+        notice: prepared.notice,
+        tool_product_uuid: prepared.toolProductUuid,
+        uuid: prepared.uuid,
+        args_specific: prepared.argsSpecific,
+        args_main: prepared.argsMain,
+        body: result.body,
+    };
+}
+function historyPayload(prepared, history, message, body, downloads, paths) {
+    return {
+        artifact: downloadArtifact(paths[0]),
+        download_path: paths[0],
+        download_paths: paths,
+        downloads,
+        result_source: "history",
+        history,
+        history_hint: historyHint(history),
+        module_id: prepared.moduleId,
+        route: prepared.route,
+        submission_message: message,
+        agent: prepared.agent,
+        duid: prepared.duid,
+        file: null,
+        ...prepared.inputSummary,
+        mode: prepared.inputMode,
+        notice: prepared.notice,
+        tool_product_uuid: prepared.toolProductUuid,
+        uuid: prepared.uuid,
+        args_specific: prepared.argsSpecific,
+        args_main: prepared.argsMain,
+        body,
+    };
+}
+export function historyHint(history) {
+    const fuid = textOf(history?.fuid);
+    return fuid
+        ? `可使用 \`helixlife-expert analysis history download ${fuid} --device pdf\` 或 \`helixlife-expert analysis history list\` 查看结果`
+        : "可使用 `helixlife-expert analysis history list` 查看任务进度";
+}
+export async function downloadResult(input) {
+    if (input.downloads.length > 0) {
+        const item = pickDownloadItem(input.downloads, {
+            item: input.downloadItem,
+            label: input.downloadLabel,
+            outputPath: input.downloadPath,
+        });
+        if (!item) {
+            throw downloadChoiceError(input.downloads, "当前结果包含多个可下载文件。分析已经完成，请用 `--downloadLabel <名称>` 选择后再保存。第 1 项通常是整份报告 zip，不要用它代替图片或表格。");
+        }
+        let resolved;
+        try {
+            resolved = await resolveDownloadUrl({
+                item,
+                moduleId: input.moduleId,
+                uuid: input.uuid,
+            });
+        }
+        catch (error) {
+            if (error instanceof AnalysisError && error.message === "未获取到下载链接") {
+                throw downloadChoiceError(input.downloads, `未获取到「${item.label}」(${item.device}) 的下载链接。分析已经完成，请改用 --downloadLabel 选择 pdf、tiff 或表格。第 1 项整份报告 zip 经常没有链接。`);
+            }
+            throw error;
+        }
+        return [await downloadToPath(resolved.url, input.downloadPath)];
+    }
+    if (input.file) {
+        return [await downloadToPath(input.file, input.downloadPath)];
+    }
+    throw new AnalysisError("当前模块未返回可下载文件。");
+}
+export function pickDownloadItem(items, options) {
+    if (options.item !== undefined) {
+        return pickByIndex(items, options.item);
+    }
+    if (options.label) {
+        return pickByLabel(items, options.label);
+    }
+    const device = normalizeDevice(options.device ?? inferDevice(options.outputPath));
+    if (device) {
+        const matched = items.filter((item) => normalizeDevice(item.device) === device);
+        if (matched.length === 1)
+            return matched[0];
+        if (matched.length > 1) {
+            throw downloadChoiceError(items, `下载格式 ${device} 匹配到多个结果。分析已经完成，请用 \`--downloadItem <n>\` 或 \`--downloadLabel <名称>\` 选择后再保存，不要重新检索工具。`);
+        }
+        throw downloadChoiceError(items, `没有 ${device} 格式的产物。分析已经完成，请按下列名称用 \`--downloadItem <n>\` 或 \`--downloadLabel <名称>\` 保存，不要重新检索工具。`);
+    }
+    const preferred = items.filter((item) => item.endpoint === "public.output.download-result");
+    if (preferred.length === 1)
+        return preferred[0];
+    if (items.length === 1)
+        return items[0];
+    return undefined;
+}
+function resolveInputMode(fetched, flags) {
+    if (flags.demo) {
+        if (hasDemo(fetched))
+            return "demo";
+        if (hasRecord(fetched))
+            return "record";
+        if (hasCloud(fetched))
+            return "cloud";
+        return "demo";
+    }
+    if (flags.files.length > 0)
+        return "upload";
+    if (recordRequested(flags))
+        return "record";
+    if (cloudRequested(flags, fetched))
+        return "cloud";
+    if (hasRecord(fetched))
+        return "record";
+    if (hasCloud(fetched))
+        return "cloud";
+    if (listUploadFields(fetched.args_data).length > 0)
+        return "upload";
+    return "none";
+}
+async function resolvePreparedInput(fetched, flags, module, mode, argsMain) {
+    if (mode === "cloud") {
+        return resolveCloudInput(fetched, flags, module);
+    }
+    if (mode === "demo") {
+        return resolveDemoInput(fetched, module.moduleId);
+    }
+    if (mode === "record") {
+        return resolveRecordInput(fetched, flags, module.moduleId);
+    }
+    if (mode === "none") {
+        return { duid: textOf(fetched.id.duid), input: { kind: "none" }, schema: [] };
+    }
+    return uploadAndVerify(flags.files, fetched.args_data, module, argsMain);
+}
+function resolveDemoInput(fetched, moduleId) {
+    const duid = textOf(fetched.id.duid);
+    if (!duid) {
+        throw new AnalysisError(`模块 ${moduleId} 未返回 demo duid，无法使用 \`--demo\`。`);
+    }
+    const fields = listUploadFields(fetched.args_data);
+    if (!fields.length || fields.some((field) => !field.defaultUpload)) {
+        throw new AnalysisError(`模块 ${moduleId} 未返回可用的 demo 文件信息，无法使用 \`--demo\`。`);
+    }
+    return {
+        duid,
+        input: {
+            kind: "upload",
+            uploads: fields.map((field) => ({
+                key: field.key,
+                label: field.label,
+                upload: {
+                    fileName: field.defaultUpload.fileName,
+                    fileOss: field.defaultUpload.fileOss,
+                    fileSize: field.defaultUpload.fileSize,
+                },
+            })),
+        },
+        schema: [],
+    };
+}
+async function resolveCloudInput(fetched, flags, module) {
+    const cloud = findDefaultCloud(fetched.args_data);
+    const key = flags.cloudKey?.trim() || cloud?.key || "";
+    if (!key) {
+        throw new AnalysisError(`模块 ${module.moduleId} 未返回可用的云端数据参数，请显式传入 \`--cloudKey\`.`);
+    }
+    const record = await resolveCloudRecord(flags, {
+        argsKey: key,
+        defaultRecord: cloud?.record,
+        moduleId: module.moduleId,
+        uuid: module.uuid,
+    });
+    if (!record) {
+        throw new AnalysisError(`模块 ${module.moduleId} 未返回默认云端数据，请传入 \`--cloudRecordJson\` 或 \`--cloudRecordFile\`.`);
+    }
+    return {
+        duid: textOf(fetched.id.duid) || "cloud",
+        input: {
+            kind: "cloud",
+            cloud: { key, label: cloud?.label ?? "", record: normalizeCloudRecord(record) },
+        },
+        schema: [],
+    };
+}
+async function resolveRecordInput(fetched, flags, moduleId) {
+    const duid = textOf(fetched.id.duid);
+    if (!duid) {
+        throw new AnalysisError(`模块 ${moduleId} 未返回 record duid，无法使用历史记录输入。`);
+    }
+    const argsData = fetched.args_data;
+    const cloudKeyAsRecord = flags.cloudKey && findArgsDataType(argsData, flags.cloudKey) === "XTRecord"
+        ? flags.cloudKey
+        : "";
+    const fallback = findDefaultRecord(argsData);
+    const key = flags.recordKey?.trim() || cloudKeyAsRecord || fallback?.key || "";
+    if (!key) {
+        throw new AnalysisError(`模块 ${moduleId} 未识别到 XTRecord 字段，请显式传入 \`--recordKey\` 或改用其他输入方式。`);
+    }
+    const field = findRecordField(argsData, key);
+    if (!field) {
+        throw new AnalysisError(`模块 ${moduleId} 未找到 XTRecord 字段 ${key}。`);
+    }
+    const picked = await pickRecord(field.options, flags, {
+        moduleId,
+        recordKey: key,
+        defaultRecord: fallback?.key === key ? fallback : null,
+    });
+    return {
+        duid,
+        input: {
+            kind: "record",
+            record: {
+                key,
+                label: field.label || (fallback?.key === key ? fallback.label : ""),
+                ...picked,
+            },
+        },
+        schema: [],
+    };
+}
+async function uploadAndVerify(files, argsData, module, argsMain) {
+    const fields = listUploadFields(argsData);
+    const selected = resolveUploadInputs(files, fields, module.moduleId);
+    const uploads = [];
+    for (const item of selected) {
+        const uploaded = await uploadLocalFile(item.filePath);
+        uploads.push({ key: item.key, label: item.label, upload: uploaded });
+    }
+    const verified = await verifyUpload({
+        argsMain,
+        moduleId: module.moduleId,
+        uploads,
+        uuid: module.uuid,
+    });
+    return {
+        duid: verified.duid,
+        input: { kind: "upload", uploads },
+        schema: verified.schema,
+    };
+}
+export function resolveUploadInputs(files, fields, moduleId) {
+    if (!fields.length) {
+        throw new AnalysisError(`模块 ${moduleId} 未检测到可上传输入，不能使用 \`--file\`。`);
+    }
+    if (!files.length) {
+        throw new AnalysisError(fields.length === 1
+            ? "通用模式请传入 `--file <xlsx>`，或改用 `--demo`。"
+            : `模块 ${moduleId} 需要多个上传字段，请使用 \`--file key=path\`。可用字段: ${fields.map((field) => field.key).join(", ")}`);
+    }
+    const only = fields[0];
+    if (fields.length === 1 && files.length === 1) {
+        const parsed = parseFileInput(files[0]);
+        if (parsed.key && parsed.key !== only.key) {
+            throw new AnalysisError(`模块 ${moduleId} 仅支持上传字段 ${only.key}，收到 ${parsed.key}。`);
+        }
+        return [{ filePath: parsed.path, key: only.key, label: only.label }];
+    }
+    const byKey = new Map(fields.map((field) => [field.key, field]));
+    const chosen = new Map();
+    for (const raw of files) {
+        const parsed = parseFileInput(raw);
+        if (!parsed.key) {
+            if (fields.length === 1) {
+                if (chosen.has(only.key)) {
+                    throw new AnalysisError(`模块 ${moduleId} 仅需要 1 个上传文件，收到重复输入。`);
+                }
+                chosen.set(only.key, parsed.path);
+                continue;
+            }
+            throw new AnalysisError(`模块 ${moduleId} 需要多个上传字段，请使用 \`--file key=path\`。可用字段: ${fields.map((field) => field.key).join(", ")}`);
+        }
+        const field = byKey.get(parsed.key);
+        if (!field) {
+            throw new AnalysisError(`模块 ${moduleId} 不存在上传字段 ${parsed.key}。可用字段: ${fields.map((item) => item.key).join(", ")}`);
+        }
+        if (chosen.has(field.key)) {
+            throw new AnalysisError(`上传字段 ${field.key} 重复传入。`);
+        }
+        chosen.set(field.key, parsed.path);
+    }
+    const missing = fields.filter((field) => field.required && !chosen.has(field.key));
+    if (missing.length > 0) {
+        throw new AnalysisError(`模块 ${moduleId} 缺少必填上传字段: ${missing.map((field) => field.key).join(", ")}`);
+    }
+    return fields.flatMap((field) => {
+        const path = chosen.get(field.key);
+        return path ? [{ filePath: path, key: field.key, label: field.label }] : [];
+    });
+}
+async function resolveModule(tool, flags, toolProductUuid) {
+    const moduleId = tool?.trim() ?? "";
+    const route = flags.route?.trim();
+    const uuid = flags.uuid?.trim();
+    if (!moduleId) {
+        throw new AnalysisError("请传入 `module_id`。");
+    }
+    if (route && uuid) {
+        return { moduleId, route, toolProductUuid, uuid };
+    }
+    const menuUuid = flags.menuUuid?.trim();
+    if (menuUuid) {
+        const menu = await fetchToolMenuOrFallback(menuUuid, toolProductUuid);
+        const menuCode = textOf(menu.code);
+        if (menuCode && menuCode !== moduleId) {
+            throw new AnalysisError(`菜单模块 code 为 ${menuCode}，与传入的 module_id ${moduleId} 不一致。`);
+        }
+        return {
+            moduleId,
+            route: route || requireRoute(menu),
+            toolProductUuid,
+            uuid: uuid || menuUuid,
+        };
+    }
+    const resolved = await resolveToolByCode(toolProductUuid, moduleId);
+    return {
+        moduleId: resolved.code,
+        route: route || resolved.route,
+        toolProductUuid,
+        uuid: uuid || resolved.uuid,
+    };
+}
+async function resolveCloudRecord(flags, context) {
+    if (flags.cloudRecordJson) {
+        return parseJsonObject(flags.cloudRecordJson, "--cloudRecordJson");
+    }
+    if (flags.cloudRecordFile) {
+        const raw = await readFile(resolveUserPath(flags.cloudRecordFile), "utf8");
+        return parseJsonObject(raw, "--cloudRecordFile");
+    }
+    if (flags.cloudFilter?.trim() || flags.cloudDataId?.trim() || typeof flags.cloudIndex === "number") {
+        return resolveCloudByQuery(flags, context);
+    }
+    return context.defaultRecord;
+}
+async function resolveCloudByQuery(flags, context) {
+    const records = await fetchAllCloudRecords(flags, context);
+    if (records.length === 0) {
+        const filter = flags.cloudFilter?.trim();
+        throw new AnalysisError(filter ? `未找到匹配云端数据: ${filter}` : "当前模块没有可选的云端数据记录。");
+    }
+    const dataId = flags.cloudDataId?.trim();
+    if (dataId) {
+        const found = records.find((record) => textOf(record.data_id) === dataId);
+        if (!found) {
+            throw new AnalysisError(`未找到 data_id=${dataId} 对应的云端数据。`);
+        }
+        return found;
+    }
+    if (typeof flags.cloudIndex === "number") {
+        const found = records[flags.cloudIndex];
+        if (!found) {
+            throw new AnalysisError(`云端数据索引超出范围: ${flags.cloudIndex}，当前共有 ${records.length} 条。`);
+        }
+        return found;
+    }
+    if (records.length === 1)
+        return records[0];
+    throw new AnalysisChoiceError(cloudSelectionHint(records, flags.cloudFilter?.trim()), {
+        choices: records.map((record, index) => ({
+            data_id: textOf(record.data_id),
+            index,
+            label: textOf(record.label) || textOf(record.data_id),
+        })),
+        filter: flags.cloudFilter?.trim() ?? "",
+        selection_type: "cloud_record",
+    });
+}
+async function fetchAllCloudRecords(flags, context) {
+    const first = await fetchCloudPage({
+        argsKey: context.argsKey,
+        currentPage: 1,
+        filter: flags.cloudFilter?.trim() ?? "",
+        moduleId: context.moduleId,
+        selectedRecord: context.defaultRecord,
+        uuid: context.uuid,
+    });
+    const records = first.records.map(normalizeCloudRecord);
+    for (let page = first.currentPage + 1; page <= first.lastPage; page += 1) {
+        const next = await fetchCloudPage({
+            argsKey: context.argsKey,
+            currentPage: page,
+            filter: flags.cloudFilter?.trim() ?? "",
+            moduleId: context.moduleId,
+            selectedRecord: context.defaultRecord,
+            uuid: context.uuid,
+        });
+        records.push(...next.records.map(normalizeCloudRecord));
+    }
+    return records;
+}
+async function pickRecord(options, flags, context) {
+    if (flags.recordJson) {
+        return toRecordSelection(parseJsonObject(flags.recordJson, "--recordJson"));
+    }
+    if (flags.recordFile) {
+        return toRecordSelection(parseJsonObject(await readFile(resolveUserPath(flags.recordFile), "utf8"), "--recordFile"));
+    }
+    if (flags.cloudRecordJson && !flags.recordJson) {
+        return toRecordSelection(parseJsonObject(flags.cloudRecordJson, "--cloudRecordJson"));
+    }
+    if (flags.cloudRecordFile && !flags.recordFile) {
+        return toRecordSelection(parseJsonObject(await readFile(resolveUserPath(flags.cloudRecordFile), "utf8"), "--cloudRecordFile"));
+    }
+    const recordId = flags.recordId?.trim();
+    if (recordId) {
+        const found = options.find((item) => textOf(item.record_id) === recordId);
+        if (!found) {
+            throw new AnalysisError(`模块 ${context.moduleId} 未找到 record_id=${recordId} 的历史记录。${recordHint(options)}`);
+        }
+        return toRecordSelection(found);
+    }
+    if (options.length > 1) {
+        throw new AnalysisChoiceError(`模块 ${context.moduleId} 存在多个历史记录，请使用 \`--recordId\` 或 \`--recordJson\` 指定。\n${recordHint(options)}`, {
+            choices: options.map((item, index) => ({
+                index,
+                module_id: textOf(item.module_id),
+                module_name: textOf(item.module_name),
+                record_id: textOf(item.record_id),
+                record_name: textOf(item.record_name),
+                time: textOf(item.time),
+            })),
+            selection_type: "history_record",
+        });
+    }
+    if (options.length === 1)
+        return toRecordSelection(options[0]);
+    if (context.defaultRecord)
+        return context.defaultRecord;
+    throw new AnalysisError(`模块 ${context.moduleId} 的 XTRecord 字段 ${context.recordKey} 没有可用记录，请传入 \`--recordJson\`.`);
+}
+function toRecordSelection(record) {
+    const recordId = textOf(record.record_id);
+    if (!recordId) {
+        throw new AnalysisError("历史记录缺少 record_id，请检查传入的 JSON。");
+    }
+    return {
+        moduleId: textOf(record.module_id),
+        moduleName: textOf(record.module_name),
+        recordId,
+        recordName: textOf(record.record_name),
+        time: textOf(record.time),
+    };
+}
+function summarizeInput(input) {
+    if (input.kind === "cloud") {
+        return {
+            file_name: null,
+            file_oss: null,
+            file_size: null,
+            input_cloud: {
+                data_filter: readOptionValue(input.cloud.record.data_filter),
+                data_id: textOf(input.cloud.record.data_id),
+                data_process: readOptionValue(input.cloud.record.data_process),
+                key: input.cloud.key,
+                label: input.cloud.label,
+                record: structuredClone(input.cloud.record),
+                record_label: textOf(input.cloud.record.label),
+            },
+            input_record: null,
+            input_uploads: null,
+        };
+    }
+    if (input.kind === "none") {
+        return {
+            file_name: null,
+            file_oss: null,
+            file_size: null,
+            input_cloud: null,
+            input_record: null,
+            input_uploads: null,
+        };
+    }
+    if (input.kind === "record") {
+        return {
+            file_name: null,
+            file_oss: null,
+            file_size: null,
+            input_cloud: null,
+            input_record: {
+                label: input.record.label,
+                module_id: input.record.moduleId,
+                module_name: input.record.moduleName,
+                record_id: input.record.recordId,
+                record_name: input.record.recordName,
+                time: input.record.time,
+            },
+            input_uploads: null,
+        };
+    }
+    const uploads = input.uploads.map((item) => ({
+        file_name: item.upload.fileName,
+        file_oss: item.upload.fileOss,
+        file_size: item.upload.fileSize,
+        key: item.key,
+        label: item.label,
+    }));
+    const single = uploads.length === 1 ? uploads[0] : null;
+    return {
+        file_name: single?.file_name ?? null,
+        file_oss: single?.file_oss ?? null,
+        file_size: single?.file_size ?? null,
+        input_cloud: null,
+        input_record: null,
+        input_uploads: uploads,
+    };
+}
+function validateInputFlags(flags) {
+    const explicitCloud = !!(flags.cloudRecordJson || flags.cloudRecordFile);
+    const queriedCloud = !!(flags.cloudDataId?.trim() ||
+        flags.cloudFilter?.trim() ||
+        typeof flags.cloudIndex === "number");
+    const explicitRecord = !!(flags.recordJson || flags.recordFile);
+    const recordMode = explicitRecord || !!flags.recordKey?.trim() || !!flags.recordId?.trim();
+    if (flags.cloudRecordJson && flags.cloudRecordFile) {
+        throw new AnalysisError("`--cloudRecordJson` 与 `--cloudRecordFile` 不能同时使用。");
+    }
+    if (flags.recordJson && flags.recordFile) {
+        throw new AnalysisError("`--recordJson` 与 `--recordFile` 不能同时使用。");
+    }
+    if (explicitCloud && queriedCloud) {
+        throw new AnalysisError("显式云端记录参数不能与 `--cloudFilter` / `--cloudDataId` / `--cloudIndex` 同时使用。");
+    }
+    if (recordMode && queriedCloud) {
+        throw new AnalysisError("历史记录参数不能与 `--cloudFilter` / `--cloudDataId` / `--cloudIndex` 同时使用。");
+    }
+    if (explicitRecord && explicitCloud) {
+        throw new AnalysisError("`--recordJson` / `--recordFile` 不能与 `--cloudRecordJson` / `--cloudRecordFile` 同时使用。");
+    }
+    if (flags.demo && (explicitCloud || queriedCloud || recordMode)) {
+        throw new AnalysisError("`--demo` 不能与云端数据/历史记录参数同时使用。");
+    }
+    if (flags.files.length > 0 && (explicitCloud || queriedCloud || recordMode)) {
+        throw new AnalysisError("`--file` 不能与云端数据/历史记录参数同时使用。");
+    }
+    if (flags.demo && flags.files.length > 0) {
+        throw new AnalysisError("`--demo` 与 `--file` 不能同时使用。");
+    }
+}
+function validateDownloadFlags(flags) {
+    if (flags.downloadItem !== undefined && flags.downloadLabel) {
+        throw new AnalysisError("`--downloadItem` 与 `--downloadLabel` 不能同时使用。");
+    }
+    if ((flags.downloadItem !== undefined || flags.downloadLabel) && !flags.download) {
+        throw new AnalysisError("`--downloadItem` 和 `--downloadLabel` 仅可与 `--download` 一起使用。");
+    }
+}
+function cloudRequested(flags, fetched) {
+    const key = flags.cloudKey?.trim() || "";
+    const keyIsRecord = !!(key && findArgsDataType(fetched.args_data, key) === "XTRecord");
+    return !!(flags.cloudDataId?.trim() ||
+        flags.cloudFilter?.trim() ||
+        typeof flags.cloudIndex === "number" ||
+        (key && !keyIsRecord) ||
+        (flags.cloudRecordFile && !keyIsRecord) ||
+        (flags.cloudRecordJson && !keyIsRecord));
+}
+function recordRequested(flags) {
+    return !!(flags.recordKey?.trim() || flags.recordId?.trim() || flags.recordJson || flags.recordFile);
+}
+function hasDemo(fetched) {
+    if (!textOf(fetched.id.duid))
+        return false;
+    const fields = listUploadFields(fetched.args_data);
+    return fields.length > 0 && fields.every((field) => !!field.defaultUpload);
+}
+function hasRecord(fetched) {
+    return !!(textOf(fetched.id.duid) && findDefaultRecord(fetched.args_data));
+}
+function hasCloud(fetched) {
+    return !!findDefaultCloud(fetched.args_data);
+}
+function normalizeCloudRecord(record) {
+    const copy = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            copy[key] = structuredClone(value);
+    }
+    if (!textOf(copy.type))
+        copy.type = "cloud";
+    return copy;
+}
+function parseJsonObject(raw, flag) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new AnalysisError(`${flag} 不是合法 JSON。`);
+    }
+    if (!isJsonObject(parsed)) {
+        throw new AnalysisError(`${flag} 必须是 JSON 对象。`);
+    }
+    return parsed;
+}
+function parseFileInput(raw) {
+    const value = raw.trim();
+    if (!value)
+        throw new AnalysisError("`--file` 不能为空。");
+    const splitAt = value.indexOf("=");
+    if (splitAt <= 0)
+        return { path: value };
+    const key = value.slice(0, splitAt).trim();
+    const path = value.slice(splitAt + 1).trim();
+    if (!key || !path)
+        throw new AnalysisError("多上传模块请使用 `--file key=path`。");
+    return { key, path };
+}
+function requireRoute(menu) {
+    const route = textOf(menu.route);
+    if (!route) {
+        throw new AnalysisError("菜单未返回可用 route，请改用 `--route` 显式指定。");
+    }
+    return route;
+}
+function readOptionValue(value) {
+    const object = asObject(value);
+    const text = textOf(object?.value);
+    return text || null;
+}
+function pickByIndex(items, index) {
+    if (!Number.isInteger(index) || index < 1 || index > items.length) {
+        throw new AnalysisError(`下载项序号 ${index} 无效，可选范围为 1-${items.length}。\n${multipleDownloadsMessage(items)}`);
+    }
+    return items[index - 1];
+}
+function pickByLabel(items, label) {
+    const wanted = label.trim().toLowerCase();
+    if (!wanted)
+        return undefined;
+    const matched = items.filter((item) => item.label.trim().toLowerCase() === wanted);
+    if (matched.length === 1)
+        return matched[0];
+    if (matched.length > 1) {
+        throw downloadChoiceError(items, `下载项名称 ${label} 匹配到多个结果。分析已经完成，请改用 \`--downloadItem <n>\` 精确选择，不要重新检索工具。`);
+    }
+    return undefined;
+}
+function inferDevice(path) {
+    const ext = path?.trim().split(".").pop()?.toLowerCase();
+    return ext ? normalizeDevice(ext) : undefined;
+}
+function normalizeDevice(value) {
+    const device = value?.trim().toLowerCase();
+    if (!device)
+        return undefined;
+    if (device === "tif")
+        return "tiff";
+    if (device === "jpg")
+        return "jpeg";
+    return device;
+}
+function downloadChoiceError(items, lead) {
+    return new AnalysisChoiceError(`${lead}\n${multipleDownloadsMessage(items)}`, {
+        choices: items.map((item, index) => ({
+            device: item.device,
+            endpoint: item.endpoint,
+            fuid: item.fuid,
+            index: index + 1,
+            label: item.label,
+        })),
+        selection_type: "download",
+    });
+}
+function multipleDownloadsMessage(items) {
+    const lines = [
+        "当前结果包含多个可下载文件，请使用 `--downloadItem`、`--downloadLabel`、`--item`、`--label` 或带目标扩展名的路径明确选择。",
+        "可选下载项：",
+    ];
+    items.forEach((item, index) => {
+        lines.push(`${index + 1}. ${item.label} (device=${item.device}, endpoint=${item.endpoint})`);
+    });
+    return lines.join("\n");
+}
+function recordHint(options) {
+    if (options.length === 0)
+        return "";
+    const lines = ["可选历史记录："];
+    options.forEach((item, index) => {
+        const id = textOf(item.record_id);
+        const name = [textOf(item.record_name), textOf(item.time)].filter(Boolean).join(" ");
+        lines.push(`  [${index}] ${id}${name ? ` (${name})` : ""}`);
+    });
+    return lines.join("\n");
+}
+function cloudSelectionHint(records, filter) {
+    const lines = [
+        filter ? `匹配到多个云端数据: ${filter}` : "匹配到多个云端数据",
+        "请使用 `--cloudIndex` 或 `--cloudDataId` 指定其中一条：",
+    ];
+    records.forEach((record, index) => {
+        const id = textOf(record.data_id);
+        const label = textOf(record.label);
+        lines.push(`  [${index}] ${label || id}`);
+    });
+    return lines.join("\n");
+}
+function toHistorySummary(record, moduleId) {
+    const fuid = textOf(record.fuid);
+    if (!fuid)
+        return null;
+    return {
+        fuid,
+        id: typeof record.id === "number" ? record.id : null,
+        module_id: textOf(record.module_id) || moduleId,
+        module_name: textOf(record.module_name),
+        name: textOf(record.name),
+        status: historyStatus(record),
+        time: textOf(record.time),
+        type: textOf(record.type),
+    };
+}
+async function waitForLatestHistory(moduleId, submittedAt, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const earliest = submittedAt - 120_000;
+    while (Date.now() <= deadline) {
+        const page = await fetchHistoryPage(1);
+        const match = page.records
+            .filter((record) => textOf(record.module_id) === moduleId)
+            .sort((left, right) => parseTime(right.time) - parseTime(left.time))
+            .find((record) => parseTime(record.time) >= earliest);
+        if (match)
+            return match;
+        await sleep(3000);
+    }
+    return null;
+}
+async function waitForHistoryCompletion(fuid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const record = await findHistoryByFuid(fuid);
+        if (!record) {
+            await sleep(3000);
+            continue;
+        }
+        const status = historyStatus(record);
+        if (isHistoryFinished(status))
+            return record;
+        if (isHistoryFailed(status)) {
+            throw new AnalysisError(`历史记录任务执行失败：${status}`);
+        }
+        await sleep(3000);
+    }
+    return null;
+}
+function parseTime(value) {
+    const text = textOf(value);
+    if (!text)
+        return 0;
+    const parsed = Date.parse(text.replace(" ", "T"));
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function isRetryableDownload(error) {
+    return error.message.includes("下载失败") || error.message.includes("未获取到下载链接");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=prepare.js.map