@helixlife-ai/xiantao 0.1.11 → 0.1.13

package/README.md

@@ -34,10 +34,16 @@ This starts a menu-driven path for choosing a tool, selecting demo data or a loc
 ### Agent Automation
 
 ```bash
+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
 ```
 
-For machine callers, use `xt tool exec`, keep `--json`, pass an explicit profile with `--profile`, and avoid interactive-only flows.
+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 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.
+
+`xt login --json` now returns the authorization link immediately and defaults to `authorized: false` until the browser step completes. Use `xt login --json --wait` when you explicitly want the command to block until authorization is confirmed. `xt status` is a probe-style check and returns `authorized: true` or `authorized: false` together with a reason such as `missing_token` or `expired_token`.
 
 ## Command Groups
 
@@ -52,6 +58,7 @@ For machine callers, use `xt tool exec`, keep `--json`, pass an explicit profile
 
 - `xt tool search`
 - `xt tool inspect`
+- `xt tool prepare`
 - `xt tool run`
 - `xt tool exec`
 - `xt tool download`
@@ -67,7 +74,7 @@ For machine callers, use `xt tool exec`, keep `--json`, pass an explicit profile
 
 For the common Xiantao tool product, `tool search`, `tool inspect`, `tool run`, `tool resolve`, and `tool menu` default `toolProductUuid` to `c0b6febb-52dd-4525-970a-61bbe9e263ff`. You can override it with `--toolProductUuid`, `XIANTAO_TOOL_PRODUCT_UUID`, or `~/.config/xtz/config.json` under `xiantao.toolProductUuid`.
 
-`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. `xt tool resolve <tool_id>` remains available as the low-level UUID and route lookup. `--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 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. `--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 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/base-command.js

@@ -1,4 +1,5 @@
 import { Command } from '@oclif/core';
+import { createErrorEnvelope, createSuccessEnvelope } from './lib/envelope.js';
 import { XtzError } from './lib/errors.js';
 import { resolveAgent } from './lib/storage.js';
 import { getUpdateReminder } from './lib/update.js';
@@ -13,14 +14,23 @@ export class XtzCommand extends Command {
     async getAgent(agentFlag) {
         return this.getProfile(agentFlag);
     }
-    print(flags, data, text) {
+    print(flags, data, text, context) {
         if (flags.json) {
+            if (context) {
+                this.log(JSON.stringify(createSuccessEnvelope(context.profile, context.command ?? this.getCommandName(), data), null, 2));
+                return;
+            }
             this.log(JSON.stringify(data, null, 2));
             return;
         }
         this.log(text);
     }
     async catch(error) {
+        if (this.isJsonOutputRequested()) {
+            const profile = await this.getProfile(this.readProfileFlagFromArgv());
+            this.log(JSON.stringify(createErrorEnvelope(profile, this.getCommandName(), error), null, 2));
+            this.exit(1);
+        }
         if (error instanceof XtzError) {
             this.error(error.message, { exit: 1 });
         }
@@ -43,7 +53,7 @@ export class XtzCommand extends Command {
         this.warn(`\`xt ${command}\` 已兼容保留，建议改用 \`xt ${replacement}\``);
     }
     async warnIfUpdateAvailable() {
-        if (this.argv.includes('--json') || !process.stdout.isTTY) {
+        if (this.argv.includes('--json') || !process.stdout.isTTY || this.shouldSkipUpdateReminder()) {
             return;
         }
         const reminder = await getUpdateReminder(this.config.version);
@@ -52,4 +62,42 @@ export class XtzCommand extends Command {
         }
         this.warn(reminder);
     }
+    getCommandName() {
+        return this.id?.replaceAll(':', ' ') ?? 'unknown';
+    }
+    isJsonOutputRequested() {
+        return this.argv.includes('--json');
+    }
+    readProfileFlagFromArgv() {
+        for (let index = 0; index < this.argv.length; index += 1) {
+            const token = this.argv[index];
+            if ((token === '--profile' || token === '--agent') && this.argv[index + 1]) {
+                return this.argv[index + 1];
+            }
+            if (token.startsWith('--profile=')) {
+                return token.slice('--profile='.length);
+            }
+            if (token.startsWith('--agent=')) {
+                return token.slice('--agent='.length);
+            }
+        }
+        return undefined;
+    }
+    shouldSkipUpdateReminder() {
+        const commandId = this.id ?? '';
+        return [
+            'login',
+            'logout',
+            'status',
+            'auth:login',
+            'auth:logout',
+            'auth:status',
+            'plot:login',
+            'plot:run',
+            'tool:exec',
+            'tool:login',
+            'tool:prepare',
+            'tool:run',
+        ].includes(commandId);
+    }
 }

package/dist/commands/auth/login.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core';
 import { XtzCommand } from '../../base-command.js';
 import { globalFlags } from '../../lib/flags.js';
+import { loginAuth } from '../../lib/auth.js';
 import { loginAll } from '../../lib/login-flow.js';
 import { getTokenPath } from '../../lib/storage.js';
 export default class AuthLogin extends XtzCommand {
@@ -12,32 +13,64 @@ export default class AuthLogin extends XtzCommand {
             default: true,
             description: 'Open the authorization link in the browser',
         }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Wait until the browser authorization is confirmed before exiting',
+        }),
     };
     async run() {
         this.warnIfLegacyAuthCommand();
         const { flags } = await this.parse(AuthLogin);
         const agent = await this.getProfile(flags.profile);
-        const result = await loginAll(agent, flags.open, ({ auth, phase }) => {
-            if (flags.json) {
-                return;
-            }
-            if (phase === 'auth_started') {
-                this.log(auth.browserOpened ? '浏览器已打开授权链接，等待授权完成...' : `请先在浏览器中打开授权链接: ${auth.linkUrl}`);
-                return;
-            }
-            this.log('授权已确认。');
-        });
+        const waitForAuthorization = this.shouldWait(flags);
+        const result = waitForAuthorization
+            ? await loginAll(agent, flags.open, ({ auth, phase }) => {
+                if (flags.json) {
+                    return;
+                }
+                if (phase === 'auth_started') {
+                    this.log(auth.browserOpened ? '浏览器已打开授权链接，等待授权完成...' : `请先在浏览器中打开授权链接: ${auth.linkUrl}`);
+                    return;
+                }
+                this.log('授权已确认。');
+            })
+            : { auth: await loginAuth(agent, flags.open) };
+        const authorized = waitForAuthorization;
         this.print(flags, {
             agent,
+            authorization_pending: !authorized,
+            authorized,
             browser_opened: result.auth.browserOpened,
             link_url: result.auth.linkUrl,
             token_path: result.auth.tokenPath,
-        }, [
-            `profile: ${agent}`,
-            `token: ${getTokenPath(agent)}`,
-            result.auth.browserOpened
-                ? '浏览器已打开授权链接，请完成授权后运行 `xt status`。'
-                : `请在浏览器中打开: ${result.auth.linkUrl}`,
-        ].join('\n'));
+            wait: waitForAuthorization,
+        }, this.formatLoginText({
+            agent,
+            authorized,
+            browserOpened: result.auth.browserOpened,
+            linkUrl: result.auth.linkUrl,
+        }), { profile: agent });
+    }
+    shouldWait(flags) {
+        if (!this.hasExplicitWaitFlag()) {
+            return !flags.json;
+        }
+        return flags.wait;
+    }
+    hasExplicitWaitFlag() {
+        return this.argv.includes('--wait') || this.argv.includes('--no-wait');
+    }
+    formatLoginText(input) {
+        const lines = [
+            `profile: ${input.agent}`,
+            `token: ${getTokenPath(input.agent)}`,
+            `authorized: ${input.authorized}`,
+        ];
+        if (input.authorized) {
+            return lines.join('\n');
+        }
+        lines.push(input.browserOpened ? '浏览器已打开授权链接，请完成授权后运行 `xt status`。' : `请在浏览器中打开: ${input.linkUrl}`);
+        return lines.join('\n');
     }
 }

package/dist/commands/auth/logout.js

@@ -15,6 +15,6 @@ export default class AuthLogout extends XtzCommand {
             agent,
             removed,
             token_path: getTokenPath(agent),
-        }, removed ? `已删除 token: ${getTokenPath(agent)}` : `未找到 token: ${getTokenPath(agent)}`);
+        }, removed ? `已删除 token: ${getTokenPath(agent)}` : `未找到 token: ${getTokenPath(agent)}`, { profile: agent });
     }
 }

package/dist/commands/auth/status.js

@@ -1,9 +1,10 @@
 import { XtzCommand } from '../../base-command.js';
+import { XtzError } from '../../lib/errors.js';
 import { checkToken } from '../../lib/auth.js';
 import { globalFlags } from '../../lib/flags.js';
-import { getTokenPath, requireToken } from '../../lib/storage.js';
+import { getTokenPath, loadToken } from '../../lib/storage.js';
 export default class AuthStatus extends XtzCommand {
-    static description = 'Check whether the current profile token is authorized';
+    static description = 'Show token auth status for the current profile';
     static flags = {
         ...globalFlags,
     };
@@ -11,12 +12,49 @@ export default class AuthStatus extends XtzCommand {
         this.warnIfLegacyAuthCommand();
         const { flags } = await this.parse(AuthStatus);
         const agent = await this.getProfile(flags.profile);
-        const token = await requireToken(agent);
-        await checkToken(agent, token);
+        const tokenPath = getTokenPath(agent);
+        const token = await loadToken(agent);
+        const status = !token
+            ? {
+                authorized: false,
+                reason: 'missing_token',
+            }
+            : await this.resolveAuthorization(agent, token);
         this.print(flags, {
             agent,
-            authorized: true,
-            token_path: getTokenPath(agent),
-        }, `profile: ${agent}\nauthorized: true\ntoken: ${getTokenPath(agent)}`);
+            authorized: status.authorized,
+            reason: status.reason,
+            token_path: tokenPath,
+        }, this.formatStatusText(agent, tokenPath, status), { profile: agent });
+    }
+    async resolveAuthorization(agent, token) {
+        try {
+            await checkToken(agent, token);
+            return {
+                authorized: true,
+                reason: null,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof XtzError) || !error.message.includes('授权已过期')) {
+                throw error;
+            }
+            return {
+                authorized: false,
+                reason: 'expired_token',
+            };
+        }
+    }
+    formatStatusText(agent, tokenPath, status) {
+        const lines = [
+            `profile: ${agent}`,
+            `authorized: ${status.authorized}`,
+            `token: ${tokenPath}`,
+        ];
+        if (!status.authorized && status.reason) {
+            lines.push(`reason: ${status.reason}`);
+            lines.push(`run: xt login --profile ${agent}`);
+        }
+        return lines.join('\n');
     }
 }

package/dist/commands/plot/fetch-all.js

@@ -42,6 +42,6 @@ export default class PlotFetchAll extends XtzCommand {
             notice: result.notice ?? '',
             uuid: flags.uuid,
         };
-        this.print(flags, output, JSON.stringify(output, null, 2));
+        this.print(flags, output, JSON.stringify(output, null, 2), { profile: agent });
     }
 }

package/dist/commands/plot/login.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import { XtzCommand } from '../../base-command.js';
+import { loginAuth } from '../../lib/auth.js';
 import { globalFlags } from '../../lib/flags.js';
 import { loginAll } from '../../lib/login-flow.js';
 import { getTokenPath } from '../../lib/storage.js';
@@ -12,32 +13,64 @@ export default class PlotLogin extends XtzCommand {
             default: true,
             description: 'Open the authorization link in the browser',
         }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Wait until the browser authorization is confirmed before exiting',
+        }),
     };
     async run() {
         this.warnIfLegacyPlotCommand();
         const { flags } = await this.parse(PlotLogin);
         const agent = await this.getProfile(flags.profile);
-        const result = await loginAll(agent, flags.open, ({ auth, phase }) => {
-            if (flags.json) {
-                return;
-            }
-            if (phase === 'auth_started') {
-                this.log(auth.browserOpened ? '浏览器已打开授权链接，等待授权完成...' : `请先在浏览器中打开授权链接: ${auth.linkUrl}`);
-                return;
-            }
-            this.log('授权已确认。');
-        });
+        const waitForAuthorization = this.shouldWait(flags);
+        const result = waitForAuthorization
+            ? await loginAll(agent, flags.open, ({ auth, phase }) => {
+                if (flags.json) {
+                    return;
+                }
+                if (phase === 'auth_started') {
+                    this.log(auth.browserOpened ? '浏览器已打开授权链接，等待授权完成...' : `请先在浏览器中打开授权链接: ${auth.linkUrl}`);
+                    return;
+                }
+                this.log('授权已确认。');
+            })
+            : { auth: await loginAuth(agent, flags.open) };
+        const authorized = waitForAuthorization;
         this.print(flags, {
             agent,
+            authorization_pending: !authorized,
+            authorized,
             browser_opened: result.auth.browserOpened,
             link_url: result.auth.linkUrl,
             token_path: result.auth.tokenPath,
-        }, [
-            `profile: ${agent}`,
-            `token: ${getTokenPath(agent)}`,
-            result.auth.browserOpened
-                ? '浏览器已打开授权链接，请完成授权后运行 `xt status`。'
-                : `请在浏览器中打开: ${result.auth.linkUrl}`,
-        ].join('\n'));
+            wait: waitForAuthorization,
+        }, this.formatLoginText({
+            agent,
+            authorized,
+            browserOpened: result.auth.browserOpened,
+            linkUrl: result.auth.linkUrl,
+        }), { profile: agent });
+    }
+    shouldWait(flags) {
+        if (!this.hasExplicitWaitFlag()) {
+            return !flags.json;
+        }
+        return flags.wait;
+    }
+    hasExplicitWaitFlag() {
+        return this.argv.includes('--wait') || this.argv.includes('--no-wait');
+    }
+    formatLoginText(input) {
+        const lines = [
+            `profile: ${input.agent}`,
+            `token: ${getTokenPath(input.agent)}`,
+            `authorized: ${input.authorized}`,
+        ];
+        if (input.authorized) {
+            return lines.join('\n');
+        }
+        lines.push(input.browserOpened ? '浏览器已打开授权链接，请完成授权后运行 `xt status`。' : `请在浏览器中打开: ${input.linkUrl}`);
+        return lines.join('\n');
     }
 }

package/dist/commands/plot/menu.js

@@ -32,6 +32,6 @@ export default class PlotMenu extends XtzCommand {
             agent,
             menu,
             tool_product_uuid: toolProductUuid,
-        }, JSON.stringify(menu, null, 2));
+        }, JSON.stringify(menu, null, 2), { profile: agent });
     }
 }

package/dist/commands/plot/menus.js

@@ -26,6 +26,6 @@ export default class PlotMenus extends XtzCommand {
             agent,
             menus,
             tool_product_uuid: toolProductUuid,
-        }, JSON.stringify(menus, null, 2));
+        }, JSON.stringify(menus, null, 2), { profile: agent });
     }
 }

package/dist/commands/plot/resolve.js

@@ -43,6 +43,6 @@ export default class PlotResolve extends XtzCommand {
             title: resolved.title,
             tool_product_uuid: toolProductUuid,
             uuid: resolved.uuid,
-        }, null, 2));
+        }, null, 2), { profile: agent });
     }
 }

package/dist/commands/plot/run.js

@@ -427,6 +427,6 @@ export default class PlotRun extends ToolRunCommandBase {
             throw new XtzError('FILE 与 `--file` 不能同时使用。');
         }
         const result = await this.executeToolRun(args.tool, args.file ?? flags.file, flags);
-        this.print(flags, result.data, result.text);
+        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';
+    static usage = 'tool exec <tool> (--file <value> | --demo) --json [--download <path>]';
     static args = {
         tool: Args.string({
             description: 'Tool id, e.g. violin_flat',
@@ -24,7 +24,7 @@ export default class ToolExec extends ToolRunCommandBase {
             description: 'Use the module demo data returned by fetch-all instead of uploading a local file',
         }),
         download: Flags.string({
-            hidden: true,
+            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',
@@ -71,7 +71,6 @@ export default class ToolExec extends ToolRunCommandBase {
         }
         const result = await this.executeToolRun(args.tool, filePath, {
             ...flags,
-            download: undefined,
             interactive: false,
         });
         const profile = await this.getProfile(flags.profile);

package/dist/commands/tool/inspect.js

@@ -51,7 +51,7 @@ export default class ToolInspect extends XtzCommand {
             tool_product_uuid: toolProductUuid,
             uuid: resolved.uuid,
         };
-        this.print(flags, output, this.formatInspectText(output.module_id, output.title, output.path, output.route, output.uuid, output.notice, inputs, summary, schema));
+        this.print(flags, output, this.formatInspectText(output.module_id, output.title, output.path, output.route, output.uuid, output.notice, inputs, summary, schema), { profile: agent });
     }
     formatInspectText(moduleId, title, path, route, uuid, notice, inputs, summary, schema) {
         const lines = [

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',

package/dist/commands/tool/search.js

@@ -34,7 +34,7 @@ export default class ToolSearch extends XtzCommand {
             tools,
             total: tools.length,
         };
-        this.print(flags, output, this.formatSearchText(args.keyword, tools));
+        this.print(flags, output, this.formatSearchText(args.keyword, tools), { profile: agent });
     }
     formatSearchText(keyword, tools) {
         if (tools.length === 0) {

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'],
         ]));
         this.log('');
         this.log(this.section('COMMON COMMANDS', this.renderCommandItems([
@@ -35,11 +35,11 @@ export default class XtzHelp extends Help {
                 id: 'tool:inspect',
             },
             {
-                description: 'Run a tool in human-first mode',
+                description: 'Run a tool in human-first mode; avoid this in agent workflows',
                 id: 'tool:run',
             },
             {
-                description: 'Execute a tool in agent mode with JSON envelope output',
+                description: 'Execute a tool in agent mode with JSON envelope output; supports --download',
                 id: 'tool:exec',
             },
             {
@@ -58,7 +58,7 @@ export default class XtzHelp extends Help {
             ['xt tool menu', 'Fetch one raw tool menu by UUID'],
             ['xt tool menus', 'Fetch all raw tool menus for a product'],
             ['xt tool fetch-all', 'Fetch raw dynamic args for a tool'],
-            ['xt tool:prepare', 'Resolve upload-dependent dynamic schema for agent workflows'],
+            ['xt tool prepare', 'Resolve upload-dependent dynamic schema for agent workflows'],
             ['xt auth ...', 'Legacy auth topic kept for compatibility'],
             ['xt plot ...', 'Legacy plot topic kept for compatibility'],
         ]));

package/package.json

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