@helixlife-ai/xiantao 0.1.17 → 0.1.19

package/README.md

@@ -37,9 +37,27 @@ This starts a menu-driven path for choosing a tool, selecting demo data or a loc
 xt tool prepare violin_flat --file ./data.xlsx --profile opencode --json
 xt tool exec violin_flat --file ./data.xlsx --profile opencode --json
 xt tool exec violin_flat --file ./data.xlsx --profile opencode --json --download ./violin.pdf
+
+xt tool exec gsea_analysis --demo --profile opencode --json
+xt tool prepare gsea_plot --profile opencode --json
+xt tool exec gsea_plot --profile opencode --json --download ./gsea_plot.pdf
+xt tool exec gsea_customize --file gene_set=./gene_set.gmt --file data=./rank.xlsx --profile opencode --json
 ```
 
-For machine callers, use `xt tool prepare` to fetch the upload-dependent final schema, then `xt tool exec` to submit. Keep `--json`, pass an explicit profile with `--profile`, and avoid interactive-only flows.
+For machine callers, use `xt tool prepare` to fetch the final schema, then `xt tool exec` to submit. Keep `--json`, pass an explicit profile with `--profile`, and avoid interactive-only flows.
+The examples below illustrate command shapes, not a fixed allowlist of tools. Apply the same patterns to any tool with the same input mode.
+
+`xt tool prepare` and `xt tool exec` support three input patterns:
+- upload modules: pass `--file <xlsx>`
+- multi-upload modules: repeat `--file key=path`, for example `--file gene_set=./gene_set.gmt --file data=./rank.xlsx`
+- demo-capable upload modules: pass `--demo`
+- history-record modules such as `gsea_plot`: pass neither `--file` nor `--demo`; the CLI reuses the default `XTRecord` returned by `tool inspect` / `tool prepare`
+
+Current operational notes for agent-style callers:
+- serialize `xt tool exec` submits per profile; Xiantao may reject overlapping or too-frequent submits with `NETWORK_ERROR`
+- `tool inspect` now includes the full `args_data` payload in JSON output and summarizes every detected `XTUpload` field
+- for multi-upload modules, pass keyed uploads in the same field names returned by `tool inspect`
+- `gsea_customize` has been validated through `tool prepare` and `tool exec` with repeated `--file gene_set=... --file data=...`
 
 For agent workflows, do not use `xt tool run`. Treat `xt tool run` as the human-first path and `xt tool exec` as the machine path.
 
@@ -84,7 +102,9 @@ For the common Xiantao tool product, `tool search`, `tool inspect`, `tool run`,
 
 The CLI also loads a project-root `.env` file on startup. You can set `XIANTAO_BASE_URL=https://agent.helixlife.cn` there to switch the API base URL without prefixing each command manually.
 
-`xt tool search <keyword>` searches remote tool menus by tool id, title, path, and route. `xt tool inspect <tool_id>` prints resolved metadata together with the dynamic `args_main` schema used by the tool. `xt tool run <tool_id>` runs a Xiantao bioinformatics tool in the human-first path. `xt tool exec <tool_id>` is the agent-safe submit command and also supports `--download <path>` when a local artifact is needed. `xt tool resolve <tool_id>` remains available as the low-level UUID and route lookup. `xt tool menus` returns a concise catalog with each tool title, `module_id`, `path`, and `route`, which is useful when `tool search` finds nothing helpful or when you want to shortlist tools for recommendation. `--demo` reuses the demo file metadata returned by `tool fetch-all`; otherwise `tool run` uploads the local file first and therefore also needs token auth. Run `xt login` first to authorize the stored token. When a tool exposes multiple downloadable results, `--download <path>` uses the output file extension to select the matching artifact.
+`xt tool search <keyword>` searches remote tool menus by tool id, title, path, and route. `xt tool inspect <tool_id>` prints resolved metadata together with the dynamic `args_main` schema, the full `args_data` payload in JSON mode, and the detected input source summary, including per-field `XTUpload` defaults and `XTRecord` defaults. `xt tool run <tool_id>` runs a Xiantao bioinformatics tool in the human-first path. `xt tool exec <tool_id>` is the agent-safe submit command and also supports `--download <path>` when a local artifact is needed. `xt tool resolve <tool_id>` remains available as the low-level UUID and route lookup. `xt tool menus` returns a concise catalog with each tool title, `module_id`, `path`, and `route`, which is useful when `tool search` finds nothing helpful or when you want to shortlist tools for recommendation. `--demo` reuses the demo file metadata returned by `tool fetch-all`; `--file` uploads a local file first; multi-upload modules accept repeated `--file key=path`; for `XTRecord` modules the CLI can submit directly from the default history record returned by `fetch-all`. Run `xt login` first to authorize the stored token. When a tool exposes multiple downloadable results, `--download <path>` uses the output file extension to select the matching artifact.
+
+For the current GSEA tool family, `gsea_plot`, `gsea_plot2`, `gsea_bar`, `gsea_point`, `gsea_ridge`, `gsea_emapplot`, `gsea_tree`, and `gsea_path_cluster` are record-backed visual modules that reuse the default `gsea_analysis` history record. `gsea_analysis` itself is an upload/demo analysis module. `gsea_customize` is a custom gene-set upload module whose frontend expects two uploads, `gene_set` and `data`; submit it with `--file gene_set=... --file data=...`. A real CLI submit path has been verified with the sample files in [`docs/GSEA-基因集.csv`](/Users/chenyunjie/Desktop/xtz-cli/xiantao/docs/GSEA-基因集.csv) and [`docs/GSEA-分子.xlsx`](/Users/chenyunjie/Desktop/xtz-cli/xiantao/docs/GSEA-分子.xlsx).
 
 `xt tool run <tool_id> ... --interactive` prompts for dynamic `args_main` values before the final submit, prints reusable `--set` flags, and supports `<` for the previous item plus `/skip` for the current section.
 

package/dist/commands/history/download.js

@@ -20,6 +20,12 @@ export default class HistoryDownload extends XtzCommand {
         device: Flags.string({
             description: 'Preferred device/format, e.g. pdf, xlsx, zip',
         }),
+        item: Flags.integer({
+            description: 'Select a download item by its 1-based index from the listed results',
+        }),
+        label: Flags.string({
+            description: 'Select a download item by its label',
+        }),
         output: Flags.string({
             char: 'o',
             description: 'Destination path; defaults to ~/Downloads/<file name>',
@@ -33,13 +39,21 @@ export default class HistoryDownload extends XtzCommand {
         const agent = await this.getProfile(flags.profile);
         const auth = await getAuthContext(agent, flags.token);
         const record = await findXiantaoHistoryRecordByFuid(auth, args.fuid);
+        if (flags.item !== undefined && flags.label) {
+            throw new XtzError('`--item` 与 `--label` 不能同时使用。');
+        }
         if (!record?.module_id?.trim()) {
             throw new XtzError(`未找到 fuid 为 ${args.fuid} 的历史记录。`);
         }
         const result = await fetchXiantaoHistoryDownloadButtons(auth, { fuid: args.fuid });
-        const item = this.pickDownloadItem(result.downloads, flags.device, flags.output);
+        const item = this.pickDownloadItem(result.downloads, {
+            device: flags.device,
+            item: flags.item,
+            label: flags.label,
+            outputPath: flags.output,
+        });
         if (!item) {
-            throw new XtzError('当前历史记录返回多个可下载结果，请传入 `--device`，或将 `--output` 改为带目标扩展名的文件名。');
+            throw new XtzError(this.buildMultipleDownloadsMessage(result.downloads));
         }
         const resolved = await resolveXiantaoDownload(auth, {
             item,
@@ -62,8 +76,14 @@ export default class HistoryDownload extends XtzCommand {
             profile: agent,
         });
     }
-    pickDownloadItem(downloads, expectedDevice, outputPath) {
-        const normalizedExpectedDevice = this.normalizeDevice(expectedDevice ?? this.inferDeviceFromOutputPath(outputPath));
+    pickDownloadItem(downloads, input) {
+        if (input.item !== undefined) {
+            return this.pickDownloadItemByIndex(downloads, input.item);
+        }
+        if (input.label) {
+            return this.pickDownloadItemByLabel(downloads, input.label);
+        }
+        const normalizedExpectedDevice = this.normalizeDevice(input.device ?? this.inferDeviceFromOutputPath(input.outputPath));
         if (normalizedExpectedDevice) {
             const matched = downloads.filter((item) => this.normalizeDevice(item.device) === normalizedExpectedDevice);
             if (matched.length === 1) {
@@ -79,6 +99,26 @@ export default class HistoryDownload extends XtzCommand {
         }
         return undefined;
     }
+    pickDownloadItemByIndex(downloads, itemIndex) {
+        if (!Number.isInteger(itemIndex) || itemIndex < 1 || itemIndex > downloads.length) {
+            throw new XtzError(`下载项序号 ${itemIndex} 无效，可选范围为 1-${downloads.length}。\n${this.buildMultipleDownloadsMessage(downloads)}`);
+        }
+        return downloads[itemIndex - 1];
+    }
+    pickDownloadItemByLabel(downloads, expectedLabel) {
+        const normalizedExpectedLabel = expectedLabel.trim().toLowerCase();
+        if (!normalizedExpectedLabel) {
+            return undefined;
+        }
+        const matched = downloads.filter((item) => item.label.trim().toLowerCase() === normalizedExpectedLabel);
+        if (matched.length === 1) {
+            return matched[0];
+        }
+        if (matched.length > 1) {
+            throw new XtzError(`下载项名称 ${expectedLabel} 匹配到多个结果，请改用 \`--item\` 精确选择。\n${this.buildMultipleDownloadsMessage(downloads)}`);
+        }
+        return undefined;
+    }
     inferDeviceFromOutputPath(outputPath) {
         const extension = outputPath?.trim().split('.').pop()?.toLowerCase();
         return extension ? this.normalizeDevice(extension) : undefined;
@@ -96,4 +136,14 @@ export default class HistoryDownload extends XtzCommand {
         }
         return normalized;
     }
+    buildMultipleDownloadsMessage(downloads) {
+        const lines = [
+            '当前历史记录返回多个可下载结果，请传入 `--item`、`--label`、`--device`，或将 `--output` 改为带目标扩展名的文件名。',
+            '可选下载项：',
+        ];
+        downloads.forEach((item, index) => {
+            lines.push(`${index + 1}. ${item.label} (device=${item.device}, endpoint=${item.endpoint})`);
+        });
+        return lines.join('\n');
+    }
 }

package/dist/commands/plot/run.js

@@ -6,16 +6,26 @@ import { downloadToPath } from '../../lib/download.js';
 import { XtzError } from '../../lib/errors.js';
 import { globalFlags } from '../../lib/flags.js';
 import { fetchXiantaoHistoryDownloadButtons, getXiantaoHistoryRecordStatus, waitForLatestXiantaoHistoryRecord, waitForXiantaoHistoryRecordCompletion, } from '../../lib/history.js';
-import { deepMerge, isJsonObject } from '../../lib/json.js';
+import { deepMerge } from '../../lib/json.js';
 import { confirmPlotArgsMain, promptPlotArgsMain, promptPlotFilePath, promptPlotInputSource, promptPlotMenuSelection, promptPlotResultSelection, } from '../../lib/plot-interactive.js';
 import { uploadFile } from '../../lib/plot.js';
 import { parseSetOverrides, plotOverrideFlags } from '../../lib/plot-options.js';
 import { buildArgsMainFromSchema } from '../../lib/plot-schema.js';
 import { loadPlotArgsMainConfig, resolveXiantaoToolProductUuid } from '../../lib/storage.js';
-import { resolveXiantaoDownload, submitXiantaoPlot, verifyXiantaoPlotUpload } from '../../lib/xiantao-plot.js';
+import { findDefaultXiantaoRecord, listXiantaoUploadFields } from '../../lib/tool-inputs.js';
+import { resolveXiantaoDownload, submitXiantaoPlot, verifyXiantaoPlotUpload, } from '../../lib/xiantao-plot.js';
 import { fetchAllPlotArgs, fetchToolMenu, fetchToolMenus, resolveToolMenuByCode } from '../../lib/xiantao.js';
 export class ToolRunCommandBase extends XtzCommand {
-    async prepareToolRun(requestedModuleId, filePath, flags) {
+    resolveToolFileInputs(positionalFile, flagFiles) {
+        if (positionalFile && flagFiles && flagFiles.length > 0) {
+            throw new XtzError('FILE 与 `--file` 不能同时使用。');
+        }
+        if (positionalFile) {
+            return [positionalFile];
+        }
+        return flagFiles ?? [];
+    }
+    async prepareToolRun(requestedModuleId, fileInputs, flags) {
         const agent = await this.getProfile(flags.profile);
         const auth = await getAuthContext(agent, flags.token);
         const resolved = await this.resolveModule(requestedModuleId, flags, auth);
@@ -23,41 +33,45 @@ export class ToolRunCommandBase extends XtzCommand {
         const fetchAllResult = await fetchAllPlotArgs(auth, { moduleId, uuid });
         const inputMode = await this.resolveInputMode(fetchAllResult, {
             demo: flags.demo,
-            filePath,
+            fileInputs,
             interactive: flags.interactive,
         });
         const configArgsMain = await loadPlotArgsMainConfig(moduleId, flags.config);
         const overrides = deepMerge(configArgsMain, parseSetOverrides(flags.set));
         let schema = fetchAllResult.args_main ?? [];
         let argsMain = deepMerge(buildArgsMainFromSchema(schema), overrides);
-        const { duid, upload, schema: verifiedSchema } = inputMode.mode === 'demo'
+        const preparedInput = inputMode.mode === 'demo'
             ? this.resolveDemoInput(fetchAllResult, moduleId)
-            : await this.uploadAndVerify(agent, inputMode.filePath, {
-                argsMain,
-                moduleId,
-                uuid,
-            }, auth);
-        if (verifiedSchema.length) {
-            schema = verifiedSchema;
+            : inputMode.mode === 'record'
+                ? this.resolveRecordInput(fetchAllResult, moduleId)
+                : await this.uploadAndVerify(agent, inputMode.fileInputs ?? [], {
+                    argsMain,
+                    argsData: fetchAllResult.args_data ?? [],
+                    moduleId,
+                    uuid,
+                }, auth);
+        if (preparedInput.schema.length) {
+            schema = preparedInput.schema;
             argsMain = deepMerge(buildArgsMainFromSchema(schema), overrides);
         }
         return {
             agent,
             argsMain,
             auth,
-            duid,
+            duid: preparedInput.duid,
+            input: preparedInput.input,
             inputMode: inputMode.mode,
+            inputSummary: this.summarizePreparedInput(preparedInput.input),
             moduleId,
             notice: fetchAllResult.notice ?? '',
             route,
             schema,
             toolProductUuid,
-            upload,
             uuid,
         };
     }
-    async executeToolRun(requestedModuleId, filePath, flags) {
-        const prepared = await this.prepareToolRun(requestedModuleId, filePath, flags);
+    async executeToolRun(requestedModuleId, fileInputs, flags) {
+        const prepared = await this.prepareToolRun(requestedModuleId, fileInputs, flags);
         let argsMain = prepared.argsMain;
         if (flags.interactive) {
             argsMain = await promptPlotArgsMain(prepared.schema ?? [], argsMain);
@@ -67,9 +81,9 @@ export class ToolRunCommandBase extends XtzCommand {
         const result = await submitXiantaoPlot(prepared.auth, {
             argsMain,
             duid: prepared.duid,
+            input: prepared.input,
             moduleId: prepared.moduleId,
             route: prepared.route,
-            upload: prepared.upload,
             uuid: prepared.uuid,
         });
         if (result.asyncSubmission) {
@@ -105,11 +119,9 @@ export class ToolRunCommandBase extends XtzCommand {
                 downloads: result.downloads,
                 duid: prepared.duid,
                 file: result.file ?? null,
-                file_name: prepared.upload.fileName,
-                file_oss: prepared.upload.fileOss,
-                file_size: prepared.upload.fileSize,
                 history: null,
                 history_hint: null,
+                ...prepared.inputSummary,
                 mode: prepared.inputMode,
                 module_id: prepared.moduleId,
                 notice: prepared.notice,
@@ -141,11 +153,9 @@ export class ToolRunCommandBase extends XtzCommand {
                     downloads: [],
                     duid: prepared.duid,
                     file: null,
-                    file_name: prepared.upload.fileName,
-                    file_oss: prepared.upload.fileOss,
-                    file_size: prepared.upload.fileSize,
                     history: recordedHistory,
                     history_hint: this.buildHistoryHint(recordedHistory),
+                    ...prepared.inputSummary,
                     mode: prepared.inputMode,
                     module_id: prepared.moduleId,
                     notice: prepared.notice,
@@ -169,11 +179,9 @@ export class ToolRunCommandBase extends XtzCommand {
                     downloads: [],
                     duid: prepared.duid,
                     file: null,
-                    file_name: prepared.upload.fileName,
-                    file_oss: prepared.upload.fileOss,
-                    file_size: prepared.upload.fileSize,
                     history: recordedHistory,
                     history_hint: this.buildHistoryHint(recordedHistory),
+                    ...prepared.inputSummary,
                     mode: prepared.inputMode,
                     module_id: prepared.moduleId,
                     notice: prepared.notice,
@@ -203,11 +211,9 @@ export class ToolRunCommandBase extends XtzCommand {
                     downloads: [],
                     duid: prepared.duid,
                     file: null,
-                    file_name: prepared.upload.fileName,
-                    file_oss: prepared.upload.fileOss,
-                    file_size: prepared.upload.fileSize,
                     history: finalHistory,
                     history_hint: this.buildHistoryHint(finalHistory),
+                    ...prepared.inputSummary,
                     mode: prepared.inputMode,
                     module_id: prepared.moduleId,
                     notice: prepared.notice,
@@ -235,11 +241,9 @@ export class ToolRunCommandBase extends XtzCommand {
                 downloads,
                 duid: prepared.duid,
                 file: null,
-                file_name: prepared.upload.fileName,
-                file_oss: prepared.upload.fileOss,
-                file_size: prepared.upload.fileSize,
                 history: finalHistory,
                 history_hint: this.buildHistoryHint(finalHistory),
+                ...prepared.inputSummary,
                 mode: prepared.inputMode,
                 module_id: prepared.moduleId,
                 notice: prepared.notice,
@@ -431,18 +435,21 @@ export class ToolRunCommandBase extends XtzCommand {
         if (input.demo) {
             return { mode: 'demo' };
         }
-        if (input.filePath) {
+        if (input.fileInputs.length > 0) {
             return {
-                filePath: input.filePath,
+                fileInputs: input.fileInputs,
                 mode: 'upload',
             };
         }
+        if (this.hasRecordInput(fetchAllResult)) {
+            return { mode: 'record' };
+        }
         if (!input.interactive) {
             return { mode: 'upload' };
         }
         if (!this.hasDemoInput(fetchAllResult)) {
             return {
-                filePath: await promptPlotFilePath(),
+                fileInputs: [await promptPlotFilePath()],
                 mode: 'upload',
             };
         }
@@ -451,7 +458,7 @@ export class ToolRunCommandBase extends XtzCommand {
             return { mode };
         }
         return {
-            filePath: await promptPlotFilePath(),
+            fileInputs: [await promptPlotFilePath()],
             mode,
         };
     }
@@ -460,22 +467,25 @@ export class ToolRunCommandBase extends XtzCommand {
         if (!duid) {
             throw new XtzError(`模块 ${moduleId} 未返回 demo duid，无法使用 \`--demo\`。`);
         }
-        const uploadField = (fetchAllResult.args_data ?? []).find((item) => isJsonObject(item) && item.type === 'XTUpload');
-        const defaultValue = isJsonObject(uploadField) && isJsonObject(uploadField.default_value) ? uploadField.default_value : undefined;
-        const fileName = typeof defaultValue?.file_name === 'string' ? defaultValue.file_name.trim() : '';
-        const fileOss = typeof defaultValue?.file_oss === 'string' ? defaultValue.file_oss.trim() : '';
-        const fileSize = typeof defaultValue?.file_size === 'number' ? defaultValue.file_size : undefined;
-        if (!fileName || !fileOss || typeof fileSize !== 'number') {
+        const uploadFields = listXiantaoUploadFields(fetchAllResult.args_data ?? []);
+        if (!uploadFields.length || uploadFields.some((field) => !field.defaultUpload)) {
             throw new XtzError(`模块 ${moduleId} 未返回可用的 demo 文件信息，无法使用 \`--demo\`。`);
         }
         return {
             duid,
-            schema: [],
-            upload: {
-                fileName,
-                fileOss,
-                fileSize,
+            input: {
+                kind: 'upload',
+                uploads: uploadFields.map((field) => ({
+                    key: field.key,
+                    label: field.label,
+                    upload: {
+                        fileName: field.defaultUpload.fileName,
+                        fileOss: field.defaultUpload.fileOss,
+                        fileSize: field.defaultUpload.fileSize,
+                    },
+                })),
             },
+            schema: [],
         };
     }
     hasDemoInput(fetchAllResult) {
@@ -483,31 +493,180 @@ export class ToolRunCommandBase extends XtzCommand {
         if (!duid) {
             return false;
         }
-        const uploadField = (fetchAllResult.args_data ?? []).find((item) => isJsonObject(item) && item.type === 'XTUpload');
-        const defaultValue = isJsonObject(uploadField) && isJsonObject(uploadField.default_value) ? uploadField.default_value : undefined;
-        const fileName = typeof defaultValue?.file_name === 'string' ? defaultValue.file_name.trim() : '';
-        const fileOss = typeof defaultValue?.file_oss === 'string' ? defaultValue.file_oss.trim() : '';
-        const fileSize = typeof defaultValue?.file_size === 'number' ? defaultValue.file_size : undefined;
-        return Boolean(fileName && fileOss && typeof fileSize === 'number');
+        const uploadFields = listXiantaoUploadFields(fetchAllResult.args_data ?? []);
+        return uploadFields.length > 0 && uploadFields.every((field) => Boolean(field.defaultUpload));
     }
-    async uploadAndVerify(agent, filePath, input, auth) {
-        if (!filePath) {
-            throw new XtzError('通用模式请传入 FILE，或改用 `--demo`。');
+    resolveRecordInput(fetchAllResult, moduleId) {
+        const duid = fetchAllResult.id?.duid?.trim();
+        if (!duid) {
+            throw new XtzError(`模块 ${moduleId} 未返回 record duid，无法使用历史记录输入。`);
         }
-        const uploadAuth = await getAuthContext(agent);
-        const upload = await uploadFile(uploadAuth, filePath);
+        const record = findDefaultXiantaoRecord(fetchAllResult.args_data ?? []);
+        if (!record) {
+            throw new XtzError(`模块 ${moduleId} 未返回可用的数据记录，无法直接运行。`);
+        }
+        return {
+            duid,
+            input: {
+                kind: 'record',
+                record: {
+                    key: record.key,
+                    label: record.label,
+                    moduleId: record.moduleId,
+                    moduleName: record.moduleName,
+                    recordId: record.recordId,
+                    recordName: record.recordName,
+                    time: record.time,
+                },
+            },
+            schema: [],
+        };
+    }
+    hasRecordInput(fetchAllResult) {
+        return Boolean(fetchAllResult.id?.duid?.trim() && findDefaultXiantaoRecord(fetchAllResult.args_data ?? []));
+    }
+    async uploadAndVerify(agent, fileInputs, input, auth) {
+        const uploads = await this.uploadFiles(agent, fileInputs, input.argsData ?? [], input.moduleId);
         const verified = await verifyXiantaoPlotUpload(auth, {
             argsMain: input.argsMain,
             moduleId: input.moduleId,
-            upload,
+            uploads,
             uuid: input.uuid,
         });
         return {
             duid: verified.duid,
+            input: {
+                kind: 'upload',
+                uploads,
+            },
             schema: verified.schema,
-            upload,
         };
     }
+    summarizePreparedInput(input) {
+        if (input.kind === 'record') {
+            return {
+                file_name: null,
+                file_oss: null,
+                file_size: 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 inputUploads = 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 singularUpload = inputUploads.length === 1 ? inputUploads[0] : null;
+        return {
+            file_name: singularUpload?.file_name ?? null,
+            file_oss: singularUpload?.file_oss ?? null,
+            file_size: singularUpload?.file_size ?? null,
+            input_record: null,
+            input_uploads: inputUploads,
+        };
+    }
+    async uploadFiles(agent, fileInputs, argsData, moduleId) {
+        const uploadFields = listXiantaoUploadFields(argsData ?? []);
+        const uploadSpecs = this.resolveUploadInputs(fileInputs, uploadFields, moduleId);
+        const uploadAuth = await getAuthContext(agent);
+        const uploads = [];
+        for (const item of uploadSpecs) {
+            const upload = await uploadFile(uploadAuth, item.filePath);
+            uploads.push({
+                key: item.key,
+                label: item.label,
+                upload,
+            });
+        }
+        return uploads;
+    }
+    resolveUploadInputs(fileInputs, uploadFields, moduleId) {
+        if (!uploadFields.length) {
+            throw new XtzError(`模块 ${moduleId} 未检测到可上传输入，不能使用 \`--file\`。`);
+        }
+        if (!fileInputs.length) {
+            if (uploadFields.length === 1) {
+                throw new XtzError('通用模式请传入 FILE / `--file <xlsx>`，或改用 `--demo`。');
+            }
+            throw new XtzError(`模块 ${moduleId} 需要多个上传字段，请使用 \`--file key=path\`。可用字段: ${uploadFields.map((field) => field.key).join(', ')}`);
+        }
+        const [singleUploadField] = uploadFields;
+        if (uploadFields.length === 1 && fileInputs.length === 1) {
+            const parsed = this.parseUploadFileInput(fileInputs[0]);
+            if (parsed.key && parsed.key !== singleUploadField.key) {
+                throw new XtzError(`模块 ${moduleId} 仅支持上传字段 ${singleUploadField.key}，收到 ${parsed.key}。`);
+            }
+            return [{
+                    filePath: parsed.path,
+                    key: singleUploadField.key,
+                    label: singleUploadField.label,
+                }];
+        }
+        const fieldsByKey = new Map(uploadFields.map((field) => [field.key, field]));
+        const assignments = new Map();
+        for (const rawValue of fileInputs) {
+            const parsed = this.parseUploadFileInput(rawValue);
+            if (!parsed.key) {
+                if (uploadFields.length === 1) {
+                    if (assignments.has(singleUploadField.key)) {
+                        throw new XtzError(`模块 ${moduleId} 仅需要 1 个上传文件，收到重复输入。`);
+                    }
+                    assignments.set(singleUploadField.key, parsed.path);
+                    continue;
+                }
+                throw new XtzError(`模块 ${moduleId} 需要多个上传字段，请使用 \`--file key=path\`。可用字段: ${uploadFields.map((field) => field.key).join(', ')}`);
+            }
+            const field = fieldsByKey.get(parsed.key);
+            if (!field) {
+                throw new XtzError(`模块 ${moduleId} 不存在上传字段 ${parsed.key}。可用字段: ${uploadFields.map((item) => item.key).join(', ')}`);
+            }
+            if (assignments.has(field.key)) {
+                throw new XtzError(`上传字段 ${field.key} 重复传入。`);
+            }
+            assignments.set(field.key, parsed.path);
+        }
+        const missingFields = uploadFields.filter((field) => field.required && !assignments.has(field.key));
+        if (missingFields.length > 0) {
+            throw new XtzError(`模块 ${moduleId} 缺少必填上传字段: ${missingFields.map((field) => field.key).join(', ')}`);
+        }
+        return uploadFields.flatMap((field) => {
+            const filePath = assignments.get(field.key);
+            if (!filePath) {
+                return [];
+            }
+            return [{
+                    filePath,
+                    key: field.key,
+                    label: field.label,
+                }];
+        });
+    }
+    parseUploadFileInput(input) {
+        const normalized = input.trim();
+        if (!normalized) {
+            throw new XtzError('`--file` 不能为空。');
+        }
+        const separatorIndex = normalized.indexOf('=');
+        if (separatorIndex <= 0) {
+            return { path: normalized };
+        }
+        const key = normalized.slice(0, separatorIndex).trim();
+        const path = normalized.slice(separatorIndex + 1).trim();
+        if (!key || !path) {
+            throw new XtzError('多上传模块请使用 `--file key=path`。');
+        }
+        return { key, path };
+    }
     async resolveModule(requestedModuleId, flags, auth) {
         const moduleId = requestedModuleId?.trim();
         const explicitRoute = flags.route?.trim();
@@ -605,7 +764,8 @@ export default class PlotRun extends ToolRunCommandBase {
             description: 'Use the module demo data returned by fetch-all instead of uploading a local file',
         }),
         file: Flags.string({
-            description: 'Path to the local xlsx file; optional in --interactive mode',
+            description: 'Path to the local xlsx file; repeat or use KEY=PATH for named upload fields',
+            multiple: true,
         }),
         download: Flags.string({
             description: 'Download the generated file or preferred analysis result to this local path after submission',
@@ -636,10 +796,8 @@ export default class PlotRun extends ToolRunCommandBase {
         if (flags.interactive && flags.json) {
             throw new XtzError('`--interactive` 不能与 `--json` 同时使用。');
         }
-        if (args.file && flags.file) {
-            throw new XtzError('FILE 与 `--file` 不能同时使用。');
-        }
-        const result = await this.executeToolRun(args.tool, args.file ?? flags.file, flags);
+        const fileInputs = this.resolveToolFileInputs(args.file, flags.file);
+        const result = await this.executeToolRun(args.tool, fileInputs, flags);
         this.print(flags, result.data, result.text, { profile: result.data.agent });
     }
 }

package/dist/commands/tool/exec.js

@@ -6,7 +6,7 @@ import { plotOverrideFlags } from '../../lib/plot-options.js';
 import { ToolRunCommandBase } from '../plot/run.js';
 export default class ToolExec extends ToolRunCommandBase {
     static description = 'Execute a Xiantao bioinformatics tool in agent mode';
-    static usage = 'tool exec <tool> (--file <value> | --demo) --json [--download <path>]';
+    static usage = 'tool exec <tool> [--file <value> ... | --demo] --json [--download <path>]';
     static args = {
         tool: Args.string({
             description: 'Tool id, e.g. violin_flat',
@@ -27,7 +27,8 @@ export default class ToolExec extends ToolRunCommandBase {
             description: 'Download the generated file or preferred analysis result to this local path after submission',
         }),
         file: Flags.string({
-            description: 'Path to the local xlsx file',
+            description: 'Path to the local xlsx file; repeat or use KEY=PATH for named upload fields',
+            multiple: true,
         }),
         interactive: Flags.boolean({
             default: false,
@@ -59,17 +60,11 @@ export default class ToolExec extends ToolRunCommandBase {
         if (!flags.json) {
             throw new XtzError('`xt tool exec` 仅支持 `--json` 输出。');
         }
-        if (args.file && flags.file) {
-            throw new XtzError('FILE 与 `--file` 不能同时使用。');
-        }
-        if (flags.demo && flags.file) {
+        const fileInputs = this.resolveToolFileInputs(args.file, flags.file);
+        if (flags.demo && fileInputs.length > 0) {
             throw new XtzError('`--demo` 与 `--file` 不能同时使用。');
         }
-        const filePath = args.file ?? flags.file;
-        if (!flags.demo && !filePath) {
-            throw new XtzError('`xt tool exec` 需要 `--file`，或显式传入 `--demo`。');
-        }
-        const result = await this.executeToolRun(args.tool, filePath, {
+        const result = await this.executeToolRun(args.tool, fileInputs, {
             ...flags,
             interactive: false,
         });

package/dist/commands/tool/inspect.js

@@ -3,8 +3,8 @@ import { XtzCommand } from '../../base-command.js';
 import { getAuthContext } from '../../lib/auth.js';
 import { globalFlags } from '../../lib/flags.js';
 import { buildArgsMainFromSchema } from '../../lib/plot-schema.js';
-import { isJsonObject } from '../../lib/json.js';
 import { resolveXiantaoToolProductUuid } from '../../lib/storage.js';
+import { findDefaultXiantaoRecord, listXiantaoUploadFields } from '../../lib/tool-inputs.js';
 import { fetchAllPlotArgs, resolveToolMenuByCode } from '../../lib/xiantao.js';
 export default class ToolInspect extends XtzCommand {
     static description = 'Inspect a Xiantao tool and its dynamic inputs';
@@ -38,6 +38,7 @@ export default class ToolInspect extends XtzCommand {
         const summary = this.summarizeSchema(schema);
         const output = {
             agent,
+            args_data: fetchAllResult.args_data ?? [],
             args_main: schema,
             args_main_defaults: buildArgsMainFromSchema(schema),
             duid: fetchAllResult.id?.duid ?? '',
@@ -64,8 +65,17 @@ export default class ToolInspect extends XtzCommand {
             lines.push(`notice: ${notice}`);
         }
         lines.push('input:');
-        lines.push(`  upload: ${inputs.upload_available ? 'local xlsx' : 'not detected'}`);
-        lines.push(`  demo: ${inputs.demo_available ? this.formatDemoSummary(inputs.demo_upload) : 'unavailable'}`);
+        lines.push(`  upload: ${inputs.upload_available ? `${inputs.upload_fields.length} fields` : 'not detected'}`);
+        for (const field of inputs.upload_fields) {
+            const suffixes = [
+                field.label && field.label !== field.key ? field.label : undefined,
+                field.required ? 'required' : undefined,
+                field.demo_upload ? this.formatDemoSummary(field.demo_upload) : 'no demo default',
+            ].filter(Boolean);
+            lines.push(`    - ${field.key}${suffixes.length > 0 ? ` - ${suffixes.join(', ')}` : ''}`);
+        }
+        lines.push(`  demo: ${inputs.demo_available ? 'available' : 'unavailable'}`);
+        lines.push(`  record: ${inputs.record_available ? this.formatRecordSummary(inputs.record_default) : 'unavailable'}`);
         if (schema.length === 0) {
             lines.push('args_main: none');
             return lines.join('\n');
@@ -90,22 +100,40 @@ export default class ToolInspect extends XtzCommand {
         return lines.join('\n');
     }
     summarizeInputs(argsData, duid) {
-        const uploadField = argsData.find((item) => isJsonObject(item) && item.type === 'XTUpload');
-        const defaultValue = isJsonObject(uploadField) && isJsonObject(uploadField.default_value) ? uploadField.default_value : undefined;
-        const fileName = typeof defaultValue?.file_name === 'string' ? defaultValue.file_name.trim() : '';
-        const fileOss = typeof defaultValue?.file_oss === 'string' ? defaultValue.file_oss.trim() : '';
-        const fileSize = typeof defaultValue?.file_size === 'number' ? defaultValue.file_size : undefined;
-        const demoAvailable = Boolean(duid.trim() && fileName && fileOss && typeof fileSize === 'number');
+        const uploadFields = listXiantaoUploadFields(argsData);
+        const record = findDefaultXiantaoRecord(argsData);
+        const demoAvailable = Boolean(duid.trim() && uploadFields.length > 0 && uploadFields.every((field) => Boolean(field.defaultUpload)));
+        const recordAvailable = Boolean(duid.trim() && record);
+        const recordDefault = recordAvailable && record
+            ? {
+                key: record.key,
+                label: record.label,
+                module_id: record.moduleId,
+                module_name: record.moduleName,
+                record_id: record.recordId,
+                record_name: record.recordName,
+                time: record.time,
+            }
+            : null;
         return {
             demo_available: demoAvailable,
-            demo_upload: demoAvailable
-                ? {
-                    file_name: fileName,
-                    file_oss: fileOss,
-                    file_size: fileSize,
-                }
-                : null,
-            upload_available: Boolean(uploadField),
+            record_available: recordAvailable,
+            record_default: recordDefault,
+            upload_available: uploadFields.length > 0,
+            upload_fields: uploadFields.map((field) => ({
+                demo_upload: field.defaultUpload
+                    ? {
+                        file_name: field.defaultUpload.fileName,
+                        file_oss: field.defaultUpload.fileOss,
+                        file_size: field.defaultUpload.fileSize,
+                        key: field.key,
+                        label: field.label,
+                    }
+                    : null,
+                key: field.key,
+                label: field.label,
+                required: field.required,
+            })),
         };
     }
     summarizeSchema(schema) {
@@ -117,10 +145,13 @@ export default class ToolInspect extends XtzCommand {
         };
     }
     formatDemoSummary(demoUpload) {
-        if (!demoUpload) {
+        return `${demoUpload.file_name} (${this.formatFileSize(demoUpload.file_size)})`;
+    }
+    formatRecordSummary(record) {
+        if (!record) {
             return 'available';
         }
-        return `${demoUpload.file_name} (${this.formatFileSize(demoUpload.file_size)})`;
+        return `${record.module_id || '-'} ${record.record_id}${record.time ? ` (${record.time})` : ''}`;
     }
     formatFileSize(fileSize) {
         if (fileSize < 1024) {

package/dist/commands/tool/prepare.js

@@ -7,7 +7,7 @@ import { buildArgsMainFromSchema } from '../../lib/plot-schema.js';
 import { ToolRunCommandBase } from '../plot/run.js';
 export default class ToolPrepare extends ToolRunCommandBase {
     static description = 'Prepare a Xiantao bioinformatics tool in agent mode and return the final dynamic schema';
-    static usage = 'tool prepare <tool> (--file <value> | --demo) --json';
+    static usage = 'tool prepare <tool> [--file <value> ... | --demo] --json';
     static args = {
         tool: Args.string({
             description: 'Tool id, e.g. violin_flat',
@@ -25,7 +25,8 @@ export default class ToolPrepare extends ToolRunCommandBase {
             description: 'Use the module demo data returned by fetch-all instead of uploading a local file',
         }),
         file: Flags.string({
-            description: 'Path to the local xlsx file',
+            description: 'Path to the local xlsx file; repeat or use KEY=PATH for named upload fields',
+            multiple: true,
         }),
         interactive: Flags.boolean({
             default: false,
@@ -57,17 +58,11 @@ export default class ToolPrepare extends ToolRunCommandBase {
         if (!flags.json) {
             throw new XtzError('`xt tool prepare` 仅支持 `--json` 输出。');
         }
-        if (args.file && flags.file) {
-            throw new XtzError('FILE 与 `--file` 不能同时使用。');
-        }
-        if (flags.demo && flags.file) {
+        const fileInputs = this.resolveToolFileInputs(args.file, flags.file);
+        if (flags.demo && fileInputs.length > 0) {
             throw new XtzError('`--demo` 与 `--file` 不能同时使用。');
         }
-        const filePath = args.file ?? flags.file;
-        if (!flags.demo && !filePath) {
-            throw new XtzError('`xt tool prepare` 需要 `--file`，或显式传入 `--demo`。');
-        }
-        const prepared = await this.prepareToolRun(args.tool, filePath, {
+        const prepared = await this.prepareToolRun(args.tool, fileInputs, {
             ...flags,
             interactive: false,
         });
@@ -77,9 +72,11 @@ export default class ToolPrepare extends ToolRunCommandBase {
             args_main: prepared.schema ?? [],
             args_main_defaults: buildArgsMainFromSchema(prepared.schema),
             duid: prepared.duid,
-            file_name: prepared.upload.fileName,
-            file_oss: prepared.upload.fileOss,
-            file_size: prepared.upload.fileSize,
+            file_name: prepared.inputSummary.file_name,
+            file_oss: prepared.inputSummary.file_oss,
+            file_size: prepared.inputSummary.file_size,
+            input_record: prepared.inputSummary.input_record,
+            input_uploads: prepared.inputSummary.input_uploads,
             mode: prepared.inputMode,
             module_id: prepared.moduleId,
             notice: prepared.notice,

package/dist/lib/tool-inputs.js

@@ -0,0 +1,51 @@
+import { isJsonObject } from './json.js';
+export function listXiantaoUploadFields(argsData) {
+    return argsData.flatMap((item) => {
+        if (!isJsonObject(item) || item.type !== 'XTUpload') {
+            return [];
+        }
+        const key = typeof item.key === 'string' ? item.key.trim() : '';
+        if (!key) {
+            return [];
+        }
+        const defaultValue = isJsonObject(item.default_value) ? item.default_value : undefined;
+        const fileName = typeof defaultValue?.file_name === 'string' ? defaultValue.file_name.trim() : '';
+        const fileOss = typeof defaultValue?.file_oss === 'string' ? defaultValue.file_oss.trim() : '';
+        const fileSize = typeof defaultValue?.file_size === 'number' ? defaultValue.file_size : undefined;
+        return [{
+                defaultUpload: fileName && fileOss && typeof fileSize === 'number'
+                    ? {
+                        fileName,
+                        fileOss,
+                        fileSize,
+                    }
+                    : null,
+                key,
+                label: typeof item.label === 'string' ? item.label.trim() : '',
+                required: item.required === true,
+            }];
+    });
+}
+export function findDefaultXiantaoRecord(argsData) {
+    for (const item of argsData) {
+        if (!isJsonObject(item) || item.type !== 'XTRecord') {
+            continue;
+        }
+        const key = typeof item.key === 'string' ? item.key.trim() : '';
+        const defaultValue = isJsonObject(item.default_value) ? item.default_value : undefined;
+        const recordId = typeof defaultValue?.record_id === 'string' ? defaultValue.record_id.trim() : '';
+        if (!key || !recordId) {
+            continue;
+        }
+        return {
+            key,
+            label: typeof item.label === 'string' ? item.label.trim() : '',
+            moduleId: typeof defaultValue?.module_id === 'string' ? defaultValue.module_id.trim() : '',
+            moduleName: typeof defaultValue?.module_name === 'string' ? defaultValue.module_name.trim() : '',
+            recordId,
+            recordName: typeof defaultValue?.record_name === 'string' ? defaultValue.record_name.trim() : '',
+            time: typeof defaultValue?.time === 'string' ? defaultValue.time.trim() : '',
+        };
+    }
+    return null;
+}

package/dist/lib/xiantao-plot.js

@@ -14,14 +14,7 @@ export async function verifyXiantaoPlotUpload(auth, input) {
                 },
                 args_data: {
                     duid: '',
-                    info: {
-                        main: {
-                            file_oss: getXiantaoFileOss(input.upload),
-                            file_name: input.upload.fileName,
-                            file_size: getXiantaoFileSize(input.upload),
-                            type: 'upload',
-                        },
-                    },
+                    info: buildUploadInfo(input.uploads),
                 },
                 args_main: input.argsMain,
             },
@@ -52,17 +45,7 @@ export async function submitXiantaoPlot(auth, input) {
                     module_id: input.moduleId,
                     uuid: input.uuid,
                 },
-                args_data: {
-                    duid: input.duid,
-                    info: {
-                        main: {
-                            file_oss: getXiantaoFileOss(input.upload),
-                            file_name: input.upload.fileName,
-                            file_size: getXiantaoFileSize(input.upload),
-                            type: 'upload',
-                        },
-                    },
-                },
+                args_data: buildSubmitArgsData(input.duid, input.input),
                 args_main: input.argsMain,
             },
         }),
@@ -163,6 +146,39 @@ function getXiantaoFileOss(upload) {
 function getXiantaoFileSize(upload) {
     return upload.fileSizeForXiantao ?? upload.fileSize;
 }
+function buildSubmitArgsData(duid, input) {
+    if (input.kind === 'record') {
+        return {
+            duid,
+            info: {
+                [input.record.key]: {
+                    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,
+                    type: 'record',
+                },
+            },
+        };
+    }
+    return {
+        duid,
+        info: buildUploadInfo(input.uploads),
+    };
+}
+function buildUploadInfo(uploads) {
+    return Object.fromEntries(uploads.map((item) => [
+        item.key,
+        {
+            file_oss: getXiantaoFileOss(item.upload),
+            file_name: item.upload.fileName,
+            file_size: getXiantaoFileSize(item.upload),
+            type: 'upload',
+        },
+    ]));
+}
 function isAsyncSubmissionMessage(message) {
     return Boolean(message?.includes('任务提交成功'));
 }

package/dist/xtz-help.js

@@ -6,7 +6,7 @@ export default class XtzHelp extends Help {
         this.log(this.section('MAIN FLOWS', [
             ['First use', '$ xt login\n$ xt tool search violin\n$ xt tool inspect violin_flat\n$ xt tool run violin_flat ./data.xlsx'],
             ['Interactive tool run', '$ xt tool run --interactive'],
-            ['Agent automation', '$ xt tool prepare violin_flat --file ./data.xlsx --profile opencode --json\n$ xt tool exec violin_flat --file ./data.xlsx --profile opencode --json'],
+            ['Agent automation', '$ xt tool prepare violin_flat --file ./data.xlsx --profile opencode --json\n$ xt tool exec violin_flat --file ./data.xlsx --profile opencode --json\n$ xt tool exec gsea_customize --file gene_set=./gene_set.gmt --file data=./rank.xlsx --profile opencode --json'],
         ]));
         this.log('');
         this.log(this.section('COMMON COMMANDS', this.renderCommandItems([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helixlife-ai/xiantao",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "CLI for Xiantao bioinformatics tools",
   "type": "module",
   "main": "dist/index.js",