@agentearth.ai/cli 0.1.0-beta.0

package/dist/commands/update.js

@@ -0,0 +1,67 @@
+/**
+ * `ae update` 命令入口。
+ *
+ * 本文件只编排 CLI 本地更新流程：
+ * 1. 读取 fresh update-cache；无缓存时执行 npm view 查询最新版本；
+ * 2. 无更新时直接输出 no-op；
+ * 3. 有更新时执行 npm install -g @agentearth.ai/cli@latest；
+ * 4. 更新后读取 ae --version 验证当前 PATH 下的 ae 是否真的变化。
+ */
+import { CLI_VERSION } from "../constants.js";
+import { CliError } from "../core/errors.js";
+import { readOrRefreshUpdateCache } from "./updateCheck.js";
+import { buildCliVersionCommand, buildNpmInstallLatestCommand, runProcess } from "./updateNpm.js";
+export async function runUpdate(context) {
+    // update 是用户确认后的显式动作；没有 fresh cache 时也要主动查 npm registry。
+    const cache = await readOrRefreshUpdateCache({ throwOnFailure: true });
+    if (!cache) {
+        context.telemetry.updateResult = "failed";
+        throw new CliError("version_check_failed", "npm registry version check failed.", "Retry later or check npm registry/network access.");
+    }
+    if (!cache.has_update) {
+        context.telemetry.updateResult = "no_update";
+        return {
+            updated: false,
+            current_version: cache.current_version,
+            latest_version: cache.latest_version,
+            message: cache.message ?? "AgentEarth CLI is already up to date."
+        };
+    }
+    const startedAt = Date.now();
+    // cache 已经来自 npm view；这里执行固定 npm install latest，不让 agent 拼包名或平台命令。
+    const npmCommand = buildNpmInstallLatestCommand();
+    const npmResult = await runProcess(npmCommand.command, npmCommand.args);
+    if (npmResult.exitCode !== 0) {
+        context.telemetry.updateResult = "failed";
+        throw new CliError("update_failed", "npm install latest failed.", "Retry later or check npm global package permissions.");
+    }
+    // npm 返回成功后必须重新读取 ae --version，确认当前 PATH 下的 ae 是否真的更新。
+    const versionCommand = buildCliVersionCommand();
+    const versionResult = await runProcess(versionCommand.command, versionCommand.args);
+    const updatedVersion = versionResult.stdout.trim();
+    if (versionResult.exitCode !== 0 || !updatedVersion) {
+        context.telemetry.updateResult = "failed";
+        throw new CliError("update_verify_failed", "Updated CLI version could not be verified.", "Run ae --version and check that the updated ae command is on PATH.");
+    }
+    if (updatedVersion === CLI_VERSION) {
+        context.telemetry.updateResult = "failed";
+        throw new CliError("update_not_applied", "Update command completed but CLI version did not change.", "There may be multiple ae installations. Check PATH and npm global prefix.");
+    }
+    if (updatedVersion !== cache.latest_version) {
+        context.telemetry.updateResult = "failed";
+        throw new CliError("update_verify_failed", "Updated CLI version does not match the expected latest version.", "Run ae update again after refreshing the version cache.");
+    }
+    context.telemetry.updateResult = "updated";
+    const result = {
+        updated: true,
+        from_version: CLI_VERSION,
+        to_version: updatedVersion,
+        duration_ms: Date.now() - startedAt
+    };
+    const releaseNotes = Array.isArray(cache.release_notes) ? cache.release_notes : [];
+    if (releaseNotes.length > 0) {
+        result.release_notes = releaseNotes;
+    }
+    return result;
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"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"}

package/dist/commands/updateCheck.d.ts

@@ -0,0 +1,10 @@
+import { type UpdateCache } from "../storage/updateCache.js";
+export interface ReadOrRefreshUpdateOptions {
+    env?: NodeJS.ProcessEnv;
+    throwOnFailure?: boolean;
+}
+export declare function readOrRefreshUpdateCache(options?: ReadOrRefreshUpdateOptions): Promise<UpdateCache | null>;
+export declare function refreshUpdateCacheFromNpm(env?: NodeJS.ProcessEnv): Promise<UpdateCache>;
+export declare function readLatestVersionFromNpm(env?: NodeJS.ProcessEnv): Promise<string>;
+export declare function parseNpmViewVersionOutput(stdout: string): string | null;
+export declare function compareVersions(left: string, right: string): number;

package/dist/commands/updateCheck.js

@@ -0,0 +1,98 @@
+/**
+ * npm registry 版本检查模块。
+ *
+ * list/recommend 成功后会走这里做轻量检查：先复用 fresh update-cache，
+ * 缓存不存在或过期时再执行 npm view。工具发现主流程不能被更新检查阻断，
+ * 但 ae update 会把检查失败映射成稳定 version_check_failed。
+ */
+import { CLI_VERSION, UPDATE_COMMAND_TEXT } from "../constants.js";
+import { CliError } from "../core/errors.js";
+import { readUpdateCache, writeUpdateCache } from "../storage/updateCache.js";
+import { buildNpmViewVersionCommand, runProcess } from "./updateNpm.js";
+export async function readOrRefreshUpdateCache(options = {}) {
+    const cache = await readUpdateCache();
+    if (cache) {
+        return cache;
+    }
+    const env = options.env ?? process.env;
+    if (isUpdateCheckSkipped(env) && !options.throwOnFailure) {
+        return null;
+    }
+    try {
+        return await refreshUpdateCacheFromNpm(env);
+    }
+    catch (error) {
+        if (options.throwOnFailure) {
+            throw error;
+        }
+        return null;
+    }
+}
+export async function refreshUpdateCacheFromNpm(env = process.env) {
+    const latestVersion = await readLatestVersionFromNpm(env);
+    const hasUpdate = compareVersions(latestVersion, CLI_VERSION) > 0;
+    return writeUpdateCache({
+        current_version: CLI_VERSION,
+        latest_version: latestVersion,
+        has_update: hasUpdate,
+        message: hasUpdate
+            ? `AgentEarth CLI ${latestVersion} is available.`
+            : "AgentEarth CLI is already up to date.",
+        update_command: UPDATE_COMMAND_TEXT
+    });
+}
+export async function readLatestVersionFromNpm(env = process.env) {
+    const command = buildNpmViewVersionCommand();
+    const result = await runProcess(command.command, command.args, env);
+    if (result.exitCode !== 0) {
+        throw versionCheckFailed();
+    }
+    const version = parseNpmViewVersionOutput(result.stdout);
+    if (!version) {
+        throw versionCheckFailed();
+    }
+    return version;
+}
+export function parseNpmViewVersionOutput(stdout) {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        if (typeof parsed === "string" && isVersionString(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function compareVersions(left, right) {
+    const leftParts = parseVersionParts(left);
+    const rightParts = parseVersionParts(right);
+    if (!leftParts || !rightParts) {
+        return 0;
+    }
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] > rightParts[index])
+            return 1;
+        if (leftParts[index] < rightParts[index])
+            return -1;
+    }
+    return 0;
+}
+function isUpdateCheckSkipped(env) {
+    return env.AE_SKIP_UPDATE_CHECK === "1" || env.AE_SKIP_UPDATE_CHECK === "true";
+}
+function isVersionString(value) {
+    return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(value);
+}
+function parseVersionParts(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(value);
+    if (!match) {
+        return null;
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function versionCheckFailed() {
+    return new CliError("version_check_failed", "npm registry version check failed.", "Retry later or check npm registry/network access.");
+}
+//# sourceMappingURL=updateCheck.js.map

package/dist/commands/updateCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateCheck.js","sourceRoot":"","sources":["../../src/commands/updateCheck.ts"],"names":[],"mappings":"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"}

package/dist/commands/updateHint.d.ts

@@ -0,0 +1,9 @@
+export interface UpdateHint {
+    has_update: true;
+    current_version: string;
+    latest_version: string;
+    message: string;
+    command: "ae update";
+    release_notes?: unknown[];
+}
+export declare function readUpdateHint(): Promise<UpdateHint | undefined>;

package/dist/commands/updateHint.js

@@ -0,0 +1,25 @@
+/**
+ * 工具发现阶段的更新提示 helper。
+ *
+ * 这里优先消费 fresh update-cache；缓存失效时尝试 npm view 刷新。
+ * npm registry 检查失败不会影响工具发现主流程，只是不输出 update 字段。
+ */
+import { readOrRefreshUpdateCache } from "./updateCheck.js";
+export async function readUpdateHint() {
+    const cache = await readOrRefreshUpdateCache();
+    if (!cache || !cache.has_update) {
+        return undefined;
+    }
+    const hint = {
+        has_update: true,
+        current_version: cache.current_version,
+        latest_version: cache.latest_version,
+        message: cache.message ?? "AgentEarth CLI update is available.",
+        command: "ae update"
+    };
+    if (Array.isArray(cache.release_notes) && cache.release_notes.length > 0) {
+        hint.release_notes = cache.release_notes;
+    }
+    return hint;
+}
+//# sourceMappingURL=updateHint.js.map

package/dist/commands/updateHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateHint.js","sourceRoot":"","sources":["../../src/commands/updateHint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAW5D,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,KAAK,GAAG,MAAM,wBAAwB,EAAE,CAAC;IAC/C,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,GAAe;QACvB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,qCAAqC;QAC/D,OAAO,EAAE,WAAW;KACrB,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzE,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/commands/updateNpm.d.ts

@@ -0,0 +1,13 @@
+export interface NpmCommand {
+    command: string;
+    args: string[];
+}
+export interface ProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function buildNpmViewVersionCommand(platform?: NodeJS.Platform): NpmCommand;
+export declare function buildNpmInstallLatestCommand(platform?: NodeJS.Platform): NpmCommand;
+export declare function buildCliVersionCommand(platform?: NodeJS.Platform): NpmCommand;
+export declare function runProcess(command: string, args: string[], env?: NodeJS.ProcessEnv): Promise<ProcessResult>;

package/dist/commands/updateNpm.js

@@ -0,0 +1,64 @@
+/**
+ * npm 更新命令执行模块。
+ *
+ * 这里集中处理平台命令选择和外部进程执行：
+ * Windows 使用 npm.cmd / ae.cmd，macOS 和 Linux 使用 npm / ae。
+ * npm 与 ae 的 stdout/stderr 不直接透传给 agent，避免污染 CLI JSON 输出。
+ */
+import { spawn } from "node:child_process";
+import { platform as currentPlatform } from "node:os";
+import { PACKAGE_NAME } from "../constants.js";
+export function buildNpmViewVersionCommand(platform = currentPlatform()) {
+    return {
+        command: platform === "win32" ? "npm.cmd" : "npm",
+        args: ["view", PACKAGE_NAME, "version", "--json"]
+    };
+}
+export function buildNpmInstallLatestCommand(platform = currentPlatform()) {
+    return {
+        command: platform === "win32" ? "npm.cmd" : "npm",
+        args: ["install", "-g", `${PACKAGE_NAME}@latest`]
+    };
+}
+export function buildCliVersionCommand(platform = currentPlatform()) {
+    return {
+        command: platform === "win32" ? "ae.cmd" : "ae",
+        args: ["--version"]
+    };
+}
+export async function runProcess(command, args, env = process.env) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        // Windows 通过 cmd.exe 执行 .cmd；不使用 shell:true，避免 Node DEP0190 警告污染 stderr。
+        const isWindows = currentPlatform() === "win32";
+        const child = spawn(isWindows ? (env.ComSpec ?? "cmd.exe") : command, isWindows ? ["/d", "/s", "/c", commandLine(command, args)] : args, {
+            env,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            resolve({ exitCode: -1, stdout, stderr: error.message });
+        });
+        child.on("close", (code) => {
+            resolve({ exitCode: code ?? -1, stdout, stderr });
+        });
+    });
+}
+function commandLine(command, args) {
+    // 命令和参数均由 CLI 固定生成；这里仍做最小 quoting，避免路径或参数里有空格时 cmd 解析错误。
+    return [command, ...args].map(quoteCmdArg).join(" ");
+}
+function quoteCmdArg(value) {
+    if (!/[\s"]/u.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/"/g, "\"\"")}"`;
+}
+//# sourceMappingURL=updateNpm.js.map

package/dist/commands/updateNpm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateNpm.js","sourceRoot":"","sources":["../../src/commands/updateNpm.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 全局常量集中定义文件。
+ *
+ * 这里保存 CLI 中会被多个模块复用的固定值，例如包名、版本号、默认后端地址、
+ * 后端 API 路径和本地缓存数量限制。把这些字符串集中放在这里，可以避免不同
+ * 文件里手写重复路径，后续接口调整时也更容易统一修改。
+ */
+export declare const PACKAGE_NAME = "@agentearth.ai/cli";
+export declare const UPDATE_COMMAND_TEXT = "npm install -g @agentearth.ai/cli@latest";
+export declare const CLI_VERSION = "0.1.0";
+export declare const DEFAULT_BASE_URL = "https://agentearth.ai";
+export declare const RECOMMEND_PATH = "/agent-api/v1/tool/recommend";
+export declare const TOOLS_LIST_PATH = "/agent-api/v1/tools/list";
+export declare const TOOL_DETAIL_PATH = "/agent-api/v1/tool/detail";
+export declare const EXECUTE_PATH = "/agent-api/v1/tool/execute";
+export declare const TELEMETRY_PATH = "/agent-api/v1/cli/events";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const TOOL_CACHE_LIMIT = 200;
+export declare const TELEMETRY_QUEUE_MAX_LINES = 1000;
+export declare const TELEMETRY_QUEUE_MAX_BYTES: number;

package/dist/constants.js

@@ -0,0 +1,34 @@
+/**
+ * 全局常量集中定义文件。
+ *
+ * 这里保存 CLI 中会被多个模块复用的固定值，例如包名、版本号、默认后端地址、
+ * 后端 API 路径和本地缓存数量限制。把这些字符串集中放在这里，可以避免不同
+ * 文件里手写重复路径，后续接口调整时也更容易统一修改。
+ */
+// npm 包名；发布前如果包名变更，优先改这里和 package.json。
+export const PACKAGE_NAME = "@agentearth.ai/cli";
+// 固定更新命令；ae update 实际执行也使用这个命令。
+export const UPDATE_COMMAND_TEXT = `npm install -g ${PACKAGE_NAME}@latest`;
+// CLI 自身版本号；login 输出、埋点字段和 --version 都会用到它。
+export const CLI_VERSION = "0.1.0";
+// 默认后端域名；调试时可以通过 --base-url 或 AGENT_EARTH_BASE_URL 覆盖。
+export const DEFAULT_BASE_URL = "https://agentearth.ai";
+// recommend 接口：agent 不确定工具类别时，用自然语言任务让后端推荐工具。
+export const RECOMMEND_PATH = "/agent-api/v1/tool/recommend";
+// list 接口：agent 已经知道大致工具类别时，读取工具市场/工具列表。
+export const TOOLS_LIST_PATH = "/agent-api/v1/tools/list";
+// detail 接口：agent 在 execute 前读取某个工具的参数契约和详情。
+export const TOOL_DETAIL_PATH = "/agent-api/v1/tool/detail";
+// execute 标准接口路径：实际请求使用后端返回的完整 tool_url，埋点只记录这个标准 path。
+export const EXECUTE_PATH = "/agent-api/v1/tool/execute";
+// CLI 埋点上传接口：只上传后端不知道的本地行为和本地错误。
+export const TELEMETRY_PATH = "/agent-api/v1/cli/events";
+// HTTP 默认超时时间，单位是毫秒；这里是 30 秒。
+export const DEFAULT_TIMEOUT_MS = 30_000;
+// 本地最多缓存 200 个工具，防止高频 recommend/list/detail 把磁盘撑大。
+export const TOOL_CACHE_LIMIT = 200;
+// 本地最多保留 1000 条待上传埋点，避免埋点后端长期不可用时无限增长。
+export const TELEMETRY_QUEUE_MAX_LINES = 1000;
+// 本地埋点队列最多保留 5MB；param 可能包含 query/params，所以需要字节上限。
+export const TELEMETRY_QUEUE_MAX_BYTES = 5 * 1024 * 1024;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wCAAwC;AACxC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAEjD,gCAAgC;AAChC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,YAAY,SAAS,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,uDAAuD;AACvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAExD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,cAAc,GAAG,8BAA8B,CAAC;AAE7D,yCAAyC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAE1D,6CAA6C;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAE5D,wDAAwD;AACxD,MAAM,CAAC,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAEzD,iCAAiC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,uCAAuC;AACvC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAE9C,mDAAmD;AACnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/core/args.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "../types/cli.js";
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/core/args.js

@@ -0,0 +1,110 @@
+/**
+ * 命令行参数解析模块。
+ *
+ * Node.js 传进来的参数只是字符串数组，本文件负责把它拆成两部分：
+ * 1. command 和 positionals：例如 `ae execute mock_tool "{}"` 里的 execute/mock_tool/{}。
+ * 2. options：例如 `--api-key`、`--base-url`、`--json` 这类全局选项。
+ *
+ * 当前项目没有引入第三方参数解析库，所以这里是一个小型手写解析器。
+ */
+import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from "../constants.js";
+import { usageError } from "./errors.js";
+export function parseArgs(argv) {
+    // positionals 收集不以 -- 开头的普通参数。
+    // 第一个普通参数稍后会被当成命令名。
+    const positionals = [];
+    // options 先填默认值；遇到命令行参数时再覆盖。
+    const options = {
+        apiKey: undefined,
+        apiKeyStdin: false,
+        // baseUrl 可由环境变量覆盖，方便本地联调或测试 mock server。
+        baseUrl: resolveBaseUrl(),
+        json: false,
+        noColor: process.env.NO_COLOR === "1",
+        noTelemetry: process.env.AE_NO_TELEMETRY === "1",
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        help: false,
+        version: false
+    };
+    // 用普通 for 循环，是因为 --api-key/--base-url/--timeout 会消耗下一个参数。
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            // 显式要求 JSON 输出。核心命令即使没有它，也会在 main.ts 默认 JSON。
+            options.json = true;
+        }
+        else if (arg === "--api-key") {
+            // ++index 表示读取 --api-key 后面的值，并跳过这个值。
+            options.apiKey = readOptionValue(argv, ++index, "--api-key");
+        }
+        else if (arg === "--api-key-stdin") {
+            // 从 stdin 读取 key，适合 agent/脚本，避免 key 出现在命令行参数中。
+            options.apiKeyStdin = true;
+        }
+        else if (arg === "--base-url") {
+            // 调试时可以把请求打到 mock server 或测试环境。
+            options.baseUrl = readNonBlankOptionValue(argv, ++index, "--base-url");
+        }
+        else if (arg === "--timeout") {
+            // 用户传入的是秒；内部统一换成毫秒。
+            const raw = readOptionValue(argv, ++index, "--timeout");
+            const seconds = Number(raw);
+            // timeout 必须是正数，否则 AbortController 的行为会不符合预期。
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                throw usageError("--timeout must be a positive number.");
+            }
+            // 正数秒转换成毫秒时向上取整，避免极小正数变成 0ms。
+            options.timeoutMs = Math.ceil(seconds * 1000);
+        }
+        else if (arg === "--no-color") {
+            options.noColor = true;
+        }
+        else if (arg === "--no-telemetry") {
+            options.noTelemetry = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            options.version = true;
+        }
+        else if (arg.startsWith("--")) {
+            // 未知 --xxx 必须报错，避免 agent 以为某个无效参数已经生效。
+            throw usageError(`Unknown option: ${arg}`);
+        }
+        else {
+            // 普通参数不在这里解释，交给具体命令处理。
+            positionals.push(arg);
+        }
+    }
+    return {
+        // 第一个普通参数就是命令名，例如 login/recommend/list。
+        command: positionals[0],
+        // 命令名后面的参数才是该命令自己的位置参数。
+        positionals: positionals.slice(1),
+        options
+    };
+}
+function readOptionValue(argv, index, optionName) {
+    // 读取需要值的选项，例如 --api-key abc 中的 abc。
+    const value = argv[index];
+    // 如果没有下一个参数，或者下一个参数仍是 --xxx，就说明用户漏传了值。
+    if (!value || value.startsWith("--")) {
+        throw usageError(`${optionName} requires a value.`);
+    }
+    return value;
+}
+function readNonBlankOptionValue(argv, index, optionName) {
+    const value = readOptionValue(argv, index, optionName).trim();
+    // 显式命令行参数为空白时代表 agent 传参错误，不能静默回退默认值。
+    if (!value) {
+        throw usageError(`${optionName} requires a non-empty value.`);
+    }
+    return value;
+}
+function resolveBaseUrl() {
+    // 空环境变量常见于 shell/CI 占位，不能覆盖默认线上地址。
+    const envBaseUrl = process.env.AGENT_EARTH_BASE_URL?.trim();
+    return envBaseUrl || DEFAULT_BASE_URL;
+}
+//# sourceMappingURL=args.js.map

package/dist/core/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/core/args.ts"],"names":[],"mappings":"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"}

package/dist/core/backendErrors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 后端错误映射模块。
+ *
+ * 当前 AgentAPI 的 error_msg 主要是自由文本。CLI 不能把这些文本直接暴露为
+ * agent 的控制依据，所以这里把后端文本统一映射成稳定的 CliError。
+ * 所有字符串匹配集中在本文件，避免每个命令模块都写一份重复判断。
+ */
+import { CliError } from "./errors.js";
+export type BackendOperation = "login" | "recommend" | "list" | "detail" | "execute";
+export declare function mapBackendError(operation: BackendOperation, errorMsg?: string): CliError;

package/dist/core/backendErrors.js

@@ -0,0 +1,69 @@
+/**
+ * 后端错误映射模块。
+ *
+ * 当前 AgentAPI 的 error_msg 主要是自由文本。CLI 不能把这些文本直接暴露为
+ * agent 的控制依据，所以这里把后端文本统一映射成稳定的 CliError。
+ * 所有字符串匹配集中在本文件，避免每个命令模块都写一份重复判断。
+ */
+import { CliError } from "./errors.js";
+export function mapBackendError(operation, errorMsg) {
+    // 后端错误文案可能为空，先兜底成空字符串，再统一转小写，方便 includes 判断。
+    const normalized = (errorMsg ?? "").toLowerCase();
+    // 鉴权错误在所有接口里含义一致：key 不可用，需要重新 login。
+    if (isAuthError(normalized)) {
+        return backendVisibleError("auth_invalid", "API key is invalid.", "Generate a valid API key and run ae login again.");
+    }
+    // detail 阶段的 tool not found 表示 agent 选择的 tool_name 不存在。
+    if (operation === "detail" && isToolNameError(normalized)) {
+        return backendVisibleError("tool_name_invalid", "Tool name is invalid.", "Run ae recommend or ae list and use a returned tool_name.");
+    }
+    // execute 阶段余额不足是明确业务归因，给出补余额建议。
+    if (operation === "execute" && isBalanceError(normalized)) {
+        return backendVisibleError("balance_insufficient", "Account balance is insufficient.", "Ask the owner to top up the AgentEarth account.");
+    }
+    // execute 参数错误说明 agent 传给工具的 params 不符合后端要求。
+    if (operation === "execute" && isExecuteParamsError(normalized)) {
+        return backendVisibleError("params_invalid", "Execute params are invalid.", "Run ae detail <tool_name> and provide params that match the schema.");
+    }
+    // execute 的工具不存在或工具执行失败，统一归为上游工具问题。
+    if (operation === "execute" && isUpstreamToolError(normalized)) {
+        return backendVisibleError("upstream_tool_error", "Tool execution failed.", "Try another recommended tool_name or retry later.");
+    }
+    // 其余后端业务错误都归为 backend_error，避免发散出未经确认的错误码。
+    return backendVisibleError("backend_error", "Backend returned an error.", "Retry later.");
+}
+function backendVisibleError(code, message, hint) {
+    // 这些错误来自后端 error_no/error_msg，后端业务日志已经可见，CLI 不重复上传。
+    return new CliError(code, message, hint, 1, { telemetryEligible: false });
+}
+function isAuthError(message) {
+    // 兼容后端可能返回的几种 key 无效/无权限表达。
+    return message.includes("invalid_api_key")
+        || message.includes("x-api-key has expired")
+        || message.includes("x-api-key has invalid")
+        || message.includes("api key is invalid")
+        || message.includes("api key invalid")
+        || message.includes("unauthorized")
+        || message.includes("forbidden");
+}
+function isBalanceError(message) {
+    // 当前后端余额不足文案里会包含 insufficient balance。
+    return message.includes("insufficient balance");
+}
+function isExecuteParamsError(message) {
+    // execute 参数错误通常会提示请求体必须是 JSON object，并且包含 params 字段。
+    return message.includes("invalid request body")
+        || message.includes("body is a valid json object with a 'params' field")
+        || message.includes("body is a valid json object with a \"params\" field");
+}
+function isToolNameError(message) {
+    // tool not found 和 tool_name is required 都说明工具名不可用。
+    return message.includes("tool not found")
+        || message.includes("tool_name is required");
+}
+function isUpstreamToolError(message) {
+    // execute 链路里，工具名错误和工具执行失败都属于上游工具侧问题。
+    return isToolNameError(message)
+        || message.includes("tool execution failed");
+}
+//# sourceMappingURL=backendErrors.js.map

package/dist/core/backendErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendErrors.js","sourceRoot":"","sources":["../../src/core/backendErrors.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI 稳定错误模型。
+ *
+ * 命令模块不要直接把原生 Error 抛给 main.ts，而是尽量抛 CliError。
+ * 这样 agent 可以稳定读取 error.code，埋点也可以直接使用同一层 error_code。
+ * message 和 hint 是给人或 agent 看的安全文案，不应该包含后端原始敏感信息。
+ */
+export type ErrorCode = "usage_error" | "auth_missing" | "auth_invalid" | "rate_limited" | "network_error" | "timeout" | "backend_error" | "credentials_write_failed" | "session_write_failed" | "tool_name_parse_failed" | "schema_missing" | "tool_name_invalid" | "params_invalid" | "backend_response_invalid" | "balance_insufficient" | "upstream_tool_error" | "version_check_failed" | "update_failed" | "update_verify_failed" | "update_not_applied" | "unknown";
+export interface CliErrorOptions {
+    telemetryEligible?: boolean;
+}
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly hint: string;
+    readonly exitCode: number;
+    readonly telemetryEligible: boolean;
+    constructor(code: ErrorCode, message: string, hint: string, exitCode?: number, options?: CliErrorOptions);
+}
+export declare function usageError(message: string, hint?: string): CliError;
+export declare function normalizeUnknownError(error: unknown): CliError;