@helixlife-ai/xiantao 0.1.15 → 0.1.16

package/README.md

@@ -54,6 +54,13 @@ For agent workflows, do not use `xt tool run`. Treat `xt tool run` as the human-
 - `xt logout`
 - `xt tool login`
 
+### History
+
+- `xt history list`
+- `xt history download`
+- `xt history rename`
+- `xt history delete`
+
 ### Tool Run
 
 - `xt tool search`
@@ -80,6 +87,8 @@ The CLI also loads a project-root `.env` file on startup. You can set `XIANTAO_B
 
 `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.
 
+`xt history list` lists the current profile's history records and shows the latest `fuid`, status, module, and time for each record. `xt history download <fuid> --device pdf` downloads an existing history artifact by `fuid`; when a record exposes multiple files, pass `--device` or use an `--output` path with a target extension. `xt history rename <fuid> <name>` renames a record, and `xt history delete <fuid>` deletes it.
+
 ## Development
 
 ```bash

package/dist/commands/history/delete.js

@@ -0,0 +1,38 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { getAuthContext } from '../../lib/auth.js';
+import { deleteXiantaoHistoryRecord, findXiantaoHistoryRecordByFuid } from '../../lib/history.js';
+import { globalFlags } from '../../lib/flags.js';
+export default class HistoryDelete extends XtzCommand {
+    static description = 'Delete a Xiantao history record';
+    static args = {
+        fuid: Args.string({
+            description: 'History record fuid',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for agent.helixlife.cn xiantao APIs; falls back to the stored agent token',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(HistoryDelete);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getAuthContext(agent, flags.token);
+        const before = await findXiantaoHistoryRecordByFuid(auth, args.fuid);
+        await deleteXiantaoHistoryRecord(auth, { fuid: args.fuid });
+        const output = {
+            agent,
+            fuid: args.fuid,
+            module_id: before?.module_id?.trim() ?? '',
+            module_name: before?.module_name?.trim() ?? '',
+            name: before?.name?.trim() ?? '',
+        };
+        this.print(flags, output, args.fuid, {
+            command: 'history delete',
+            profile: agent,
+        });
+    }
+}

package/dist/commands/history/download.js

@@ -0,0 +1,99 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { getAuthContext } from '../../lib/auth.js';
+import { XIANTAO_HISTORY_UUID } from '../../lib/constants.js';
+import { downloadToPath } from '../../lib/download.js';
+import { XtzError } from '../../lib/errors.js';
+import { fetchXiantaoHistoryDownloadButtons, findXiantaoHistoryRecordByFuid } from '../../lib/history.js';
+import { globalFlags } from '../../lib/flags.js';
+import { resolveXiantaoDownload } from '../../lib/xiantao-plot.js';
+export default class HistoryDownload extends XtzCommand {
+    static description = 'Download a file from a Xiantao history record';
+    static args = {
+        fuid: Args.string({
+            description: 'History record fuid',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        device: Flags.string({
+            description: 'Preferred device/format, e.g. pdf, xlsx, zip',
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Destination path; defaults to ~/Downloads/<file name>',
+        }),
+        token: Flags.string({
+            description: 'Bearer token for agent.helixlife.cn xiantao APIs; falls back to the stored agent token',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(HistoryDownload);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getAuthContext(agent, flags.token);
+        const record = await findXiantaoHistoryRecordByFuid(auth, args.fuid);
+        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);
+        if (!item) {
+            throw new XtzError('当前历史记录返回多个可下载结果，请传入 `--device`，或将 `--output` 改为带目标扩展名的文件名。');
+        }
+        const resolved = await resolveXiantaoDownload(auth, {
+            item,
+            moduleId: record.module_id.trim(),
+            uuid: XIANTAO_HISTORY_UUID,
+        });
+        const filePath = await downloadToPath(resolved.url, flags.output);
+        const output = {
+            agent,
+            device: item.device,
+            endpoint: item.endpoint,
+            file_name: resolved.fileName ?? item.label,
+            fuid: args.fuid,
+            module_id: record.module_id.trim(),
+            output: filePath,
+            url: resolved.url,
+        };
+        this.print(flags, output, filePath, {
+            command: 'history download',
+            profile: agent,
+        });
+    }
+    pickDownloadItem(downloads, expectedDevice, outputPath) {
+        const normalizedExpectedDevice = this.normalizeDevice(expectedDevice ?? this.inferDeviceFromOutputPath(outputPath));
+        if (normalizedExpectedDevice) {
+            const matched = downloads.filter((item) => this.normalizeDevice(item.device) === normalizedExpectedDevice);
+            if (matched.length === 1) {
+                return matched[0];
+            }
+        }
+        const results = downloads.filter((item) => item.endpoint === 'public.output.download-result');
+        if (results.length === 1) {
+            return results[0];
+        }
+        if (downloads.length === 1) {
+            return downloads[0];
+        }
+        return undefined;
+    }
+    inferDeviceFromOutputPath(outputPath) {
+        const extension = outputPath?.trim().split('.').pop()?.toLowerCase();
+        return extension ? this.normalizeDevice(extension) : undefined;
+    }
+    normalizeDevice(device) {
+        const normalized = device?.trim().toLowerCase();
+        if (!normalized) {
+            return undefined;
+        }
+        if (normalized === 'tif') {
+            return 'tiff';
+        }
+        if (normalized === 'jpg') {
+            return 'jpeg';
+        }
+        return normalized;
+    }
+}

package/dist/commands/history/list.js

@@ -0,0 +1,72 @@
+import { Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { getAuthContext } from '../../lib/auth.js';
+import { fetchXiantaoHistoryRecords, getXiantaoHistoryRecordStatus } from '../../lib/history.js';
+import { globalFlags } from '../../lib/flags.js';
+export default class HistoryList extends XtzCommand {
+    static description = 'List Xiantao history records';
+    static flags = {
+        ...globalFlags,
+        page: Flags.integer({
+            default: 1,
+            description: 'History page number',
+            min: 1,
+        }),
+        token: Flags.string({
+            description: 'Bearer token for agent.helixlife.cn xiantao APIs; falls back to the stored agent token',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(HistoryList);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getAuthContext(agent, flags.token);
+        const page = await fetchXiantaoHistoryRecords(auth, { currentPage: flags.page });
+        const records = page.records.map((record) => ({
+            fuid: record.fuid?.trim() ?? '',
+            id: typeof record.id === 'number' ? record.id : null,
+            module_id: record.module_id?.trim() ?? '',
+            module_name: record.module_name?.trim() ?? '',
+            name: record.name?.trim() ?? '',
+            status: getXiantaoHistoryRecordStatus(record),
+            time: record.time?.trim() ?? '',
+            type: record.type?.trim() ?? '',
+        }));
+        const output = {
+            agent,
+            current_page: page.currentPage,
+            info: page.info,
+            last_page: page.lastPage,
+            per_page: page.perPage,
+            records,
+            total: page.total,
+        };
+        this.print(flags, output, this.formatHistoryText(page.currentPage, page.lastPage, page.total, records, page.info), {
+            command: 'history list',
+            profile: agent,
+        });
+    }
+    formatHistoryText(currentPage, lastPage, total, records, info) {
+        const lines = [`历史记录 ${total} 条，第 ${currentPage}/${lastPage} 页`];
+        if (records.length === 0) {
+            lines.push('');
+            lines.push('暂无历史记录');
+            return lines.join('\n');
+        }
+        for (const record of records) {
+            lines.push('');
+            lines.push(`${record.module_id || '-'}  ${record.module_name || '-'}`);
+            lines.push(`  status: ${record.status}`);
+            lines.push(`  time: ${record.time || '-'}`);
+            lines.push(`  type: ${record.type || '-'}`);
+            lines.push(`  fuid: ${record.fuid || '-'}`);
+            if (record.name) {
+                lines.push(`  name: ${record.name}`);
+            }
+        }
+        if (info) {
+            lines.push('');
+            lines.push(info);
+        }
+        return lines.join('\n');
+    }
+}

package/dist/commands/history/rename.js

@@ -0,0 +1,45 @@
+import { Args, Flags } from '@oclif/core';
+import { XtzCommand } from '../../base-command.js';
+import { getAuthContext } from '../../lib/auth.js';
+import { findXiantaoHistoryRecordByFuid, renameXiantaoHistoryRecord } from '../../lib/history.js';
+import { globalFlags } from '../../lib/flags.js';
+export default class HistoryRename extends XtzCommand {
+    static description = 'Rename a Xiantao history record';
+    static args = {
+        fuid: Args.string({
+            description: 'History record fuid',
+            required: true,
+        }),
+        name: Args.string({
+            description: 'New history record name',
+            required: true,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        token: Flags.string({
+            description: 'Bearer token for agent.helixlife.cn xiantao APIs; falls back to the stored agent token',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(HistoryRename);
+        const agent = await this.getProfile(flags.profile);
+        const auth = await getAuthContext(agent, flags.token);
+        const before = await findXiantaoHistoryRecordByFuid(auth, args.fuid);
+        await renameXiantaoHistoryRecord(auth, {
+            fuid: args.fuid,
+            newName: args.name,
+        });
+        const output = {
+            agent,
+            fuid: args.fuid,
+            module_id: before?.module_id?.trim() ?? '',
+            module_name: before?.module_name?.trim() ?? '',
+            name: args.name,
+        };
+        this.print(flags, output, `${args.fuid} -> ${args.name}`, {
+            command: 'history rename',
+            profile: agent,
+        });
+    }
+}

package/dist/commands/plot/run.js

@@ -1,9 +1,11 @@
 import { Args, Flags } from '@oclif/core';
 import { XtzCommand } from '../../base-command.js';
 import { getAuthContext } from '../../lib/auth.js';
+import { XIANTAO_HISTORY_UUID } from '../../lib/constants.js';
 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 { confirmPlotArgsMain, promptPlotArgsMain, promptPlotFilePath, promptPlotInputSource, promptPlotMenuSelection, promptPlotResultSelection, } from '../../lib/plot-interactive.js';
 import { uploadFile } from '../../lib/plot.js';
@@ -61,6 +63,7 @@ export class ToolRunCommandBase extends XtzCommand {
             argsMain = await promptPlotArgsMain(prepared.schema ?? [], argsMain);
             await confirmPlotArgsMain(argsMain);
         }
+        const submittedAtMs = Date.now();
         const result = await submitXiantaoPlot(prepared.auth, {
             argsMain,
             duid: prepared.duid,
@@ -69,6 +72,9 @@ export class ToolRunCommandBase extends XtzCommand {
             upload: prepared.upload,
             uuid: prepared.uuid,
         });
+        if (result.asyncSubmission) {
+            return this.resolveAsyncToolRun(prepared, argsMain, flags, submittedAtMs, result.message);
+        }
         const downloadedPaths = flags.download
             ? await this.downloadResult(prepared.auth, {
                 downloadPath: flags.download,
@@ -102,16 +108,177 @@ export class ToolRunCommandBase extends XtzCommand {
                 file_name: prepared.upload.fileName,
                 file_oss: prepared.upload.fileOss,
                 file_size: prepared.upload.fileSize,
+                history: null,
+                history_hint: null,
                 mode: prepared.inputMode,
                 module_id: prepared.moduleId,
                 notice: prepared.notice,
+                result_source: 'direct',
                 route: prepared.route,
+                submission_message: result.message,
                 tool_product_uuid: prepared.toolProductUuid,
                 uuid: prepared.uuid,
             },
             text: this.formatResultText(result, downloadedPaths, flags.interactive && !flags.download),
         };
     }
+    async resolveAsyncToolRun(prepared, argsMain, flags, submittedAtMs, submissionMessage) {
+        const historyRecord = await waitForLatestXiantaoHistoryRecord(prepared.auth, {
+            intervalMs: 3000,
+            moduleId: prepared.moduleId,
+            submittedAtMs,
+            timeoutMs: flags.download ? 60_000 : 12_000,
+        });
+        const recordedHistory = historyRecord ? this.toHistorySummary(historyRecord, prepared.moduleId) : null;
+        if (!flags.download) {
+            return {
+                data: {
+                    agent: prepared.agent,
+                    args_main: argsMain,
+                    body: '',
+                    download_path: undefined,
+                    download_paths: [],
+                    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),
+                    mode: prepared.inputMode,
+                    module_id: prepared.moduleId,
+                    notice: prepared.notice,
+                    result_source: 'history',
+                    route: prepared.route,
+                    submission_message: submissionMessage,
+                    tool_product_uuid: prepared.toolProductUuid,
+                    uuid: prepared.uuid,
+                },
+                text: this.formatAsyncHistoryText(recordedHistory, submissionMessage),
+            };
+        }
+        if (!historyRecord?.fuid?.trim()) {
+            return {
+                data: {
+                    agent: prepared.agent,
+                    args_main: argsMain,
+                    body: '',
+                    download_path: undefined,
+                    download_paths: [],
+                    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),
+                    mode: prepared.inputMode,
+                    module_id: prepared.moduleId,
+                    notice: prepared.notice,
+                    result_source: 'history',
+                    route: prepared.route,
+                    submission_message: submissionMessage,
+                    tool_product_uuid: prepared.toolProductUuid,
+                    uuid: prepared.uuid,
+                },
+                text: this.formatAsyncHistoryText(recordedHistory, `${submissionMessage}，但暂未定位到历史记录。`),
+            };
+        }
+        const completedRecord = await waitForXiantaoHistoryRecordCompletion(prepared.auth, {
+            fuid: historyRecord.fuid.trim(),
+            intervalMs: 3000,
+            timeoutMs: 60_000,
+        });
+        const finalHistory = completedRecord ? this.toHistorySummary(completedRecord, prepared.moduleId) : recordedHistory;
+        if (!completedRecord?.fuid?.trim()) {
+            return {
+                data: {
+                    agent: prepared.agent,
+                    args_main: argsMain,
+                    body: '',
+                    download_path: undefined,
+                    download_paths: [],
+                    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),
+                    mode: prepared.inputMode,
+                    module_id: prepared.moduleId,
+                    notice: prepared.notice,
+                    result_source: 'history',
+                    route: prepared.route,
+                    submission_message: `${submissionMessage}，但等待历史记录完成超时。`,
+                    tool_product_uuid: prepared.toolProductUuid,
+                    uuid: prepared.uuid,
+                },
+                text: this.formatAsyncHistoryText(finalHistory, `${submissionMessage}，但等待历史记录完成超时。`),
+            };
+        }
+        const { body, downloads, paths: downloadedPaths } = await this.downloadAsyncHistoryResult(prepared.auth, {
+            downloadPath: flags.download,
+            fuid: completedRecord.fuid.trim(),
+            moduleId: prepared.moduleId,
+        });
+        return {
+            data: {
+                agent: prepared.agent,
+                args_main: argsMain,
+                body,
+                download_path: downloadedPaths[0],
+                download_paths: downloadedPaths,
+                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),
+                mode: prepared.inputMode,
+                module_id: prepared.moduleId,
+                notice: prepared.notice,
+                result_source: 'history',
+                route: prepared.route,
+                submission_message: submissionMessage,
+                tool_product_uuid: prepared.toolProductUuid,
+                uuid: prepared.uuid,
+            },
+            text: this.formatAsyncHistoryDownloadText(finalHistory, downloadedPaths),
+        };
+    }
+    async downloadAsyncHistoryResult(auth, input) {
+        let lastError;
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            const historyResult = await fetchXiantaoHistoryDownloadButtons(auth, { fuid: input.fuid });
+            try {
+                const paths = await this.downloadResult(auth, {
+                    downloadPath: input.downloadPath,
+                    downloads: historyResult.downloads,
+                    moduleId: input.moduleId,
+                    uuid: XIANTAO_HISTORY_UUID,
+                });
+                return {
+                    body: historyResult.body,
+                    downloads: historyResult.downloads,
+                    paths,
+                };
+            }
+            catch (error) {
+                if (!(error instanceof XtzError) || !this.isRetryableAsyncDownloadError(error) || attempt === 3) {
+                    throw error;
+                }
+                lastError = error;
+                await this.sleep(3000);
+            }
+        }
+        throw lastError ?? new XtzError('下载失败，请稍后重试');
+    }
     formatResultText(result, downloadPaths, promptedResultSelection) {
         const lines = [];
         if (result.file) {
@@ -133,6 +300,24 @@ export class ToolRunCommandBase extends XtzCommand {
         }
         return lines.join('\n');
     }
+    formatAsyncHistoryText(history, message) {
+        const lines = [message];
+        if (history) {
+            lines.push(`历史记录: ${history.fuid} (${history.status})`);
+        }
+        lines.push(this.buildHistoryHint(history));
+        return lines.join('\n');
+    }
+    formatAsyncHistoryDownloadText(history, downloadPaths) {
+        const lines = [];
+        if (history) {
+            lines.push(`历史记录: ${history.fuid} (${history.status})`);
+        }
+        for (const item of downloadPaths) {
+            lines.push(item);
+        }
+        return lines.join('\n');
+    }
     async downloadResult(auth, input) {
         if (input.downloads.length > 0) {
             const item = this.pickDownloadItem(input.downloads, input.downloadPath);
@@ -188,6 +373,28 @@ export class ToolRunCommandBase extends XtzCommand {
         }
         return normalized;
     }
+    toHistorySummary(record, fallbackModuleId) {
+        const fuid = record.fuid?.trim();
+        if (!fuid) {
+            return null;
+        }
+        return {
+            fuid,
+            id: typeof record.id === 'number' ? record.id : null,
+            module_id: record.module_id?.trim() || fallbackModuleId,
+            module_name: record.module_name?.trim() || '',
+            name: record.name?.trim() || '',
+            status: getXiantaoHistoryRecordStatus(record),
+            time: record.time?.trim() || '',
+            type: record.type?.trim() || '',
+        };
+    }
+    buildHistoryHint(history) {
+        if (!history) {
+            return '可使用 `xt history list` 查看任务进度';
+        }
+        return `可使用 \`xt history download ${history.fuid} --device pdf\` 或 \`xt history list\` 查看结果`;
+    }
     async downloadSelectedResults(auth, input) {
         const paths = [];
         for (const item of input.downloads) {
@@ -214,6 +421,12 @@ export class ToolRunCommandBase extends XtzCommand {
         }
         return paths;
     }
+    isRetryableAsyncDownloadError(error) {
+        return error.message.includes('下载失败') || error.message.includes('未获取到下载链接');
+    }
+    async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
     async resolveInputMode(fetchAllResult, input) {
         if (input.demo) {
             return { mode: 'demo' };

package/dist/lib/constants.js

@@ -6,6 +6,7 @@ export const AUTH_URL_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/skills/auth-u
 export const XIANTAO_BIO_API_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/bio-api`;
 export const XIANTAO_TOOL_MENUS_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/tool/menus`;
 export const DEFAULT_XIANTAO_TOOL_PRODUCT_UUID = 'c0b6febb-52dd-4525-970a-61bbe9e263ff';
+export const XIANTAO_HISTORY_UUID = '2d491694-8c8d-11ee-9409-00163e118c99';
 export const CHECK_TOKEN_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/skills/check-token`;
 export const UPLOAD_CONFIG_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/upload/config?type=bio&oss_type=bio`;
 export const BIO_API_ENDPOINT = `${XIANTAO_BASE_URL}/api/v1/agent/bio-api`;

package/dist/lib/history.js

@@ -0,0 +1,200 @@
+import { XIANTAO_BIO_API_ENDPOINT, XIANTAO_HISTORY_UUID } from './constants.js';
+import { XtzError } from './errors.js';
+import { requestJson } from './http.js';
+import { buildXiantaoHeaders } from './xiantao.js';
+export async function fetchXiantaoHistoryRecords(auth, input = {}) {
+    const response = await requestJson(XIANTAO_BIO_API_ENDPOINT, {
+        body: JSON.stringify({
+            version: 'v3',
+            name: 'public.records.fetch',
+            args: {
+                id: {
+                    uuid: XIANTAO_HISTORY_UUID,
+                },
+                current_page: input.currentPage ?? 1,
+            },
+        }),
+        headers: buildXiantaoHeaders(auth, true),
+        method: 'POST',
+    }, { agent: auth.agent });
+    return {
+        currentPage: response.data.current_page ?? input.currentPage ?? 1,
+        info: response.data.info?.trim() ?? '',
+        lastPage: response.data.last_page ?? 1,
+        perPage: response.data.per_page ?? 10,
+        records: response.data.data_records ?? [],
+        total: response.data.total ?? 0,
+    };
+}
+export async function fetchXiantaoHistoryDownloadButtons(auth, input) {
+    const response = await requestJson(XIANTAO_BIO_API_ENDPOINT, {
+        body: JSON.stringify({
+            version: 'v3',
+            name: 'public.records.download-buttons',
+            args: {
+                id: {
+                    fuid: input.fuid,
+                    uuid: XIANTAO_HISTORY_UUID,
+                },
+            },
+        }),
+        headers: buildXiantaoHeaders(auth, true),
+        method: 'POST',
+    }, { agent: auth.agent });
+    return {
+        body: response.data.body ?? '',
+        downloads: collectHistoryDownloadItems(response.data.data ?? []),
+    };
+}
+export async function renameXiantaoHistoryRecord(auth, input) {
+    await requestJson(XIANTAO_BIO_API_ENDPOINT, {
+        body: JSON.stringify({
+            version: 'v3',
+            name: 'public.records.rename',
+            args: {
+                id: {
+                    fuid: input.fuid,
+                    uuid: XIANTAO_HISTORY_UUID,
+                },
+                new_name: input.newName,
+            },
+        }),
+        headers: buildXiantaoHeaders(auth, true),
+        method: 'POST',
+    }, { agent: auth.agent });
+}
+export async function deleteXiantaoHistoryRecord(auth, input) {
+    await requestJson(XIANTAO_BIO_API_ENDPOINT, {
+        body: JSON.stringify({
+            version: 'v3',
+            name: 'public.records.delete',
+            args: {
+                id: {
+                    fuid: input.fuid,
+                    uuid: XIANTAO_HISTORY_UUID,
+                },
+            },
+        }),
+        headers: buildXiantaoHeaders(auth, true),
+        method: 'POST',
+    }, { agent: auth.agent });
+}
+export async function fetchXiantaoHistoryModify(auth, input) {
+    const response = await requestJson(XIANTAO_BIO_API_ENDPOINT, {
+        body: JSON.stringify({
+            version: 'v3',
+            name: 'public.records.modify-fetch',
+            args: {
+                id: {
+                    fuid: input.fuid,
+                    uuid: XIANTAO_HISTORY_UUID,
+                },
+            },
+        }),
+        headers: buildXiantaoHeaders(auth, true),
+        method: 'POST',
+    }, { agent: auth.agent });
+    return response.data;
+}
+export async function waitForLatestXiantaoHistoryRecord(auth, input) {
+    const deadline = Date.now() + input.timeoutMs;
+    while (Date.now() <= deadline) {
+        const page = await fetchXiantaoHistoryRecords(auth);
+        const record = findLatestHistoryRecord(page.records, input.moduleId, input.submittedAtMs);
+        if (record) {
+            return record;
+        }
+        await sleep(input.intervalMs);
+    }
+    return null;
+}
+export async function findXiantaoHistoryRecordByFuid(auth, fuid) {
+    const normalizedFuid = fuid.trim();
+    if (!normalizedFuid) {
+        return null;
+    }
+    let currentPage = 1;
+    let lastPage = 1;
+    do {
+        const page = await fetchXiantaoHistoryRecords(auth, { currentPage });
+        const record = page.records.find((item) => item.fuid?.trim() === normalizedFuid);
+        if (record) {
+            return record;
+        }
+        currentPage += 1;
+        lastPage = page.lastPage;
+    } while (currentPage <= lastPage);
+    return null;
+}
+export async function waitForXiantaoHistoryRecordCompletion(auth, input) {
+    const deadline = Date.now() + input.timeoutMs;
+    while (Date.now() <= deadline) {
+        const page = await fetchXiantaoHistoryRecords(auth);
+        const record = page.records.find((item) => item.fuid?.trim() === input.fuid);
+        if (!record) {
+            await sleep(input.intervalMs);
+            continue;
+        }
+        const statusText = getXiantaoHistoryRecordStatus(record);
+        if (isCompletedHistoryStatus(statusText)) {
+            return record;
+        }
+        if (isFailedHistoryStatus(statusText)) {
+            throw new XtzError(`历史记录任务执行失败：${statusText}`);
+        }
+        await sleep(input.intervalMs);
+    }
+    return null;
+}
+export function getXiantaoHistoryRecordStatus(record) {
+    return stripHtml(record.status ?? '').trim() || '未知';
+}
+function findLatestHistoryRecord(records, moduleId, submittedAtMs) {
+    const normalizedModuleId = moduleId.trim();
+    const threshold = submittedAtMs - 120_000;
+    const candidates = records
+        .filter((record) => record.module_id?.trim() === normalizedModuleId)
+        .sort((left, right) => parseHistoryTime(right.time) - parseHistoryTime(left.time));
+    return candidates.find((record) => parseHistoryTime(record.time) >= threshold);
+}
+function collectHistoryDownloadItems(items) {
+    return items.flatMap((item) => {
+        if (item.tag !== 'download'
+            || !item.device
+            || !item.endpoint
+            || !item.fuid
+            || !item.label) {
+            return [];
+        }
+        return [{
+                device: item.device,
+                endpoint: item.endpoint,
+                fuid: item.fuid,
+                index: item.index,
+                info: item.info,
+                label: item.label,
+                pos: item.pos,
+                sign: item.sign,
+            }];
+    });
+}
+function parseHistoryTime(value) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        return 0;
+    }
+    const parsed = Date.parse(normalized.replace(' ', 'T'));
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function stripHtml(value) {
+    return value.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ');
+}
+function isCompletedHistoryStatus(status) {
+    return status.includes('完成');
+}
+function isFailedHistoryStatus(status) {
+    return ['失败', '异常', '取消', '终止'].some((keyword) => status.includes(keyword));
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/http.js

@@ -9,6 +9,9 @@ export async function requestJson(url, init = {}, options = {}) {
     }
     const body = await response.text();
     const payload = parseEnvelope(response, body);
+    if (options.allowErrorPayload?.(payload, response)) {
+        return payload;
+    }
     if (!response.ok || payload.success === false) {
         await raiseApiError(payload, options);
     }

package/dist/lib/plot-interactive.js

@@ -3,6 +3,7 @@ import { stdin as input, stdout as output } from 'node:process';
 import { XtzError } from './errors.js';
 import { isJsonObject } from './json.js';
 import { formatSetOverrides } from './plot-options.js';
+import { getBrowsableToolMenuChildren, isRunnableToolMenu } from './xiantao.js';
 export async function promptPlotArgsMain(schema, seed) {
     ensureInteractiveSession();
     const rl = readline.createInterface({ input, output });
@@ -109,7 +110,7 @@ export async function promptPlotMenuSelection(menus) {
             output.write(`\n[${currentTitle}]\n`);
             currentMenus.forEach((menu, index) => {
                 const label = formatMenuLabel(menu);
-                const suffix = isMenuDirectory(menu) ? ' >' : ` (${menu.code?.trim() ?? '-'})`;
+                const suffix = getBrowsableToolMenuChildren(menu).length > 0 ? ' >' : ` (${menu.code?.trim() ?? '-'})`;
                 output.write(`  ${index + 1}. ${label}${suffix}\n`);
             });
             const hint = stack.length > 0 ? '输入编号，< 返回上一级，回车取消: ' : '输入编号，回车取消: ';
@@ -133,16 +134,16 @@ export async function promptPlotMenuSelection(menus) {
                     throw new XtzError(`无效选项: ${answer}`);
                 }
                 const selected = currentMenus[index - 1];
-                const children = (selected.children ?? []).filter((menu) => hasMenuLabel(menu));
-                if (children.length > 0 || isMenuDirectory(selected)) {
-                    if (children.length === 0) {
-                        throw new XtzError(`${formatMenuLabel(selected)} 下没有可选工具。`);
-                    }
+                const children = getBrowsableToolMenuChildren(selected);
+                if (children.length > 0) {
                     stack.push({ menus: currentMenus, title: currentTitle });
                     currentMenus = children;
                     currentTitle = formatMenuLabel(selected);
                     continue;
                 }
+                if (!isRunnableToolMenu(selected)) {
+                    throw new XtzError(`${formatMenuLabel(selected)} 缺少可执行信息，请改用显式 module_id/uuid。`);
+                }
                 return resolveInteractiveToolMenu(selected);
             }
             catch (error) {
@@ -562,9 +563,6 @@ function hasMenuLabel(menu) {
 function formatMenuLabel(menu) {
     return menu.title?.trim() || menu.code?.trim() || '未命名';
 }
-function isMenuDirectory(menu) {
-    return menu.is_directory === true;
-}
 function resolveInteractiveToolMenu(menu) {
     const code = menu.code?.trim();
     const route = menu.route?.trim();

package/dist/lib/xiantao-plot.js

@@ -68,19 +68,34 @@ export async function submitXiantaoPlot(auth, input) {
         }),
         headers: buildXiantaoHeaders(auth, true),
         method: 'POST',
-    }, { agent: auth.agent });
+    }, {
+        agent: auth.agent,
+        allowErrorPayload: (payload) => isAsyncSubmissionMessage(payload.message),
+    });
     const downloads = collectDownloadItems(response.data.data);
     const file = typeof response.data.file === 'string' && response.data.file.trim()
         ? response.data.file.trim()
         : undefined;
     const body = response.data.body ?? '';
+    const message = response.message ?? '';
     if (!file && !body && downloads.length === 0) {
-        throw new XtzError(response.message ?? '未获取到可用结果');
+        if (isAsyncSubmissionMessage(message)) {
+            return {
+                asyncSubmission: true,
+                body,
+                downloads,
+                file,
+                message,
+            };
+        }
+        throw new XtzError(message || '未获取到可用结果');
     }
     return {
+        asyncSubmission: false,
         body,
         downloads,
         file,
+        message,
     };
 }
 export async function resolveXiantaoDownload(auth, input) {
@@ -148,3 +163,6 @@ function getXiantaoFileOss(upload) {
 function getXiantaoFileSize(upload) {
     return upload.fileSizeForXiantao ?? upload.fileSize;
 }
+function isAsyncSubmissionMessage(message) {
+    return Boolean(message?.includes('任务提交成功'));
+}

package/dist/lib/xiantao.js

@@ -79,11 +79,17 @@ export async function fetchAllPlotArgs(auth, input) {
     }, { agent: auth.agent });
     return response.data;
 }
+export function getBrowsableToolMenuChildren(menu) {
+    return (menu.children ?? []).filter((item) => Boolean(item.title?.trim() || item.code?.trim()));
+}
+export function isRunnableToolMenu(menu) {
+    return Boolean(menu.code?.trim() && menu.route?.trim() && menu.title?.trim() && menu.uuid?.trim());
+}
 function collectToolMenuMatches(menus, code) {
     const matches = [];
     for (const menu of menus) {
         const menuCode = menu.code?.trim();
-        if ((!code || menuCode === code) && !menu.is_directory) {
+        if ((!code || menuCode === code) && isRunnableToolMenu(menu)) {
             const route = menu.route?.trim();
             const title = menu.title?.trim();
             const uuid = menu.uuid?.trim();
@@ -97,8 +103,9 @@ function collectToolMenuMatches(menus, code) {
                 });
             }
         }
-        if (menu.children?.length) {
-            matches.push(...collectToolMenuMatches(menu.children, code));
+        const children = getBrowsableToolMenuChildren(menu);
+        if (children.length > 0) {
+            matches.push(...collectToolMenuMatches(children, code));
         }
     }
     return matches;
@@ -109,8 +116,9 @@ function findToolMenu(menus, target) {
         if (menu.uuid?.trim() === normalizedTarget || String(menu.id ?? '').trim() === normalizedTarget) {
             return menu;
         }
-        if (menu.children?.length) {
-            const nested = findToolMenu(menu.children, normalizedTarget);
+        const children = getBrowsableToolMenuChildren(menu);
+        if (children.length > 0) {
+            const nested = findToolMenu(children, normalizedTarget);
             if (nested) {
                 return nested;
             }

package/dist/xtz-help.js

@@ -22,6 +22,22 @@ export default class XtzHelp extends Help {
                 description: 'Delete the stored token for the current profile',
                 id: 'logout',
             },
+            {
+                description: 'List history records for the current profile',
+                id: 'history:list',
+            },
+            {
+                description: 'Download a file from a history record',
+                id: 'history:download',
+            },
+            {
+                description: 'Rename a history record',
+                id: 'history:rename',
+            },
+            {
+                description: 'Delete a history record',
+                id: 'history:delete',
+            },
             {
                 description: 'Alias of xt login under the tool topic',
                 id: 'tool:login',
@@ -54,6 +70,7 @@ export default class XtzHelp extends Help {
         this.log('');
         this.log(this.section('LOW-LEVEL AND COMPATIBILITY', [
             ['xt tool --help', 'Show the full tool command set'],
+            ['xt history --help', 'Show the history command set'],
             ['xt tool resolve', 'Resolve a tool id to UUID and route'],
             ['xt tool menu', 'Fetch one raw tool menu by UUID'],
             ['xt tool menus', 'Fetch all raw tool menus for a product'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helixlife-ai/xiantao",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "CLI for Xiantao bioinformatics tools",
   "type": "module",
   "main": "dist/index.js",
@@ -49,6 +49,9 @@
       "tool": {
         "description": "Xiantao bioinformatics tool commands"
       },
+      "history": {
+        "description": "Xiantao history record commands"
+      },
       "plot": {
         "description": "Compatibility commands for the legacy plot topic"
       }