@agentearth.ai/cli 0.1.0-beta.0

package/dist/core/errors.js

@@ -0,0 +1,44 @@
+/**
+ * CLI 稳定错误模型。
+ *
+ * 命令模块不要直接把原生 Error 抛给 main.ts，而是尽量抛 CliError。
+ * 这样 agent 可以稳定读取 error.code，埋点也可以直接使用同一层 error_code。
+ * message 和 hint 是给人或 agent 看的安全文案，不应该包含后端原始敏感信息。
+ */
+export class CliError extends Error {
+    // 稳定错误码，给 agent、测试和埋点使用。
+    code;
+    // 下一步建议，通常告诉 agent 或用户该怎么恢复。
+    hint;
+    // 进程退出码；usage_error 用 2，其余大多数失败用 1。
+    exitCode;
+    // 是否允许作为 CLI 本地埋点上传；后端已经可见的错误会显式置为 false。
+    telemetryEligible;
+    constructor(code, message, hint, exitCode = 1, options = {}) {
+        // 调用父类 Error，让错误对象拥有 message 和 stack。
+        super(message);
+        // 设置 name，方便调试时看出这是项目自定义错误。
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+        this.telemetryEligible = options.telemetryEligible ?? true;
+    }
+}
+export function usageError(message, hint = "Run ae --help.") {
+    // 命令行工具通常用退出码 2 表示“用法错误”。
+    return new CliError("usage_error", message, hint, 2);
+}
+export function normalizeUnknownError(error) {
+    // 如果本来就是 CliError，说明上游已经完成归因，直接返回即可。
+    if (error instanceof CliError) {
+        return error;
+    }
+    // 原生 Error 有 message，但没有稳定 code，所以统一归到 unknown。
+    if (error instanceof Error) {
+        return new CliError("unknown", error.message, "Retry or run ae --help.");
+    }
+    // JavaScript 允许抛字符串、数字等非 Error 值，这里兜底转成字符串。
+    return new CliError("unknown", String(error), "Retry or run ae --help.");
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkDH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,yBAAyB;IAChB,IAAI,CAAY;IACzB,6BAA6B;IACpB,IAAI,CAAS;IACtB,oCAAoC;IAC3B,QAAQ,CAAS;IAC1B,0CAA0C;IACjC,iBAAiB,CAAU;IAEpC,YAAY,IAAe,EAAE,OAAe,EAAE,IAAY,EAAE,QAAQ,GAAG,CAAC,EAAE,UAA2B,EAAE;QACrG,sCAAsC;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,4BAA4B;QAC5B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAC;IAC7D,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,IAAI,GAAG,gBAAgB;IACjE,0BAA0B;IAC1B,OAAO,IAAI,QAAQ,CAAC,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,qCAAqC;IACrC,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gDAAgD;IAChD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC;IAC3E,CAAC;IAED,4CAA4C;IAC5C,OAAO,IAAI,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,yBAAyB,CAAC,CAAC;AAC3E,CAAC"}

package/dist/core/hiddenInput.d.ts

@@ -0,0 +1,10 @@
+type HiddenInputStream = NodeJS.ReadStream & {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?: (enabled: boolean) => void;
+};
+type HiddenOutputStream = NodeJS.WriteStream & {
+    isTTY?: boolean;
+};
+export declare function readHiddenInput(promptText: string, input?: HiddenInputStream, output?: HiddenOutputStream): Promise<string>;
+export {};

package/dist/core/hiddenInput.js

@@ -0,0 +1,53 @@
+/**
+ * TTY 隐藏输入工具。
+ *
+ * 这个模块只服务 `ae login` 的人工兜底场景：当用户直接在终端运行 login，
+ * 且没有通过 stdin、命令行参数或环境变量提供 API key 时，CLI 可以提示用户输入。
+ * 输入过程不回显字符，避免 API key 出现在终端日志或截图里。
+ */
+import { emitKeypressEvents } from "node:readline";
+import { CliError } from "./errors.js";
+export async function readHiddenInput(promptText, input = process.stdin, output = process.stderr) {
+    // 非 TTY 场景通常是 agent/脚本调用，不能阻塞等待人工输入。
+    if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+        throw new CliError("auth_missing", "Interactive API key prompt requires a TTY.", "Pipe the API key into ae login --api-key-stdin.");
+    }
+    return new Promise((resolve, reject) => {
+        let value = "";
+        const previousRawMode = input.isRaw === true;
+        const cleanup = (writeNewline) => {
+            // 无论成功、取消还是异常，都恢复进入前的 raw mode。
+            input.off("keypress", onKeypress);
+            input.setRawMode?.(previousRawMode);
+            if (writeNewline) {
+                output.write("\n");
+            }
+        };
+        const onKeypress = (character, key = {}) => {
+            if (key.ctrl && key.name === "c") {
+                cleanup(true);
+                reject(new CliError("auth_missing", "API key input cancelled.", "Pipe the API key into ae login --api-key-stdin."));
+                return;
+            }
+            if (key.name === "return" || key.name === "enter") {
+                cleanup(true);
+                resolve(value);
+                return;
+            }
+            if (key.name === "backspace") {
+                value = value.slice(0, -1);
+                return;
+            }
+            // 只收集可见字符；控制键和方向键不进入 API key。
+            if (character && character >= " " && character !== "\u007f") {
+                value += character;
+            }
+        };
+        output.write(promptText);
+        emitKeypressEvents(input);
+        input.setRawMode(true);
+        input.resume();
+        input.on("keypress", onKeypress);
+    });
+}
+//# sourceMappingURL=hiddenInput.js.map

package/dist/core/hiddenInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hiddenInput.js","sourceRoot":"","sources":["../../src/core/hiddenInput.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAsBvC,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,QAAQ,OAAO,CAAC,KAA0B,EAC1C,SAAS,OAAO,CAAC,MAA4B;IAE7C,qCAAqC;IACrC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC5E,MAAM,IAAI,QAAQ,CAAC,cAAc,EAAE,4CAA4C,EAAE,iDAAiD,CAAC,CAAC;IACtI,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC;QAE7C,MAAM,OAAO,GAAG,CAAC,YAAqB,EAAQ,EAAE;YAC9C,gCAAgC;YAChC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YAClC,KAAK,CAAC,UAAU,EAAE,CAAC,eAAe,CAAC,CAAC;YACpC,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,UAAU,GAAG,CAAC,SAAiB,EAAE,MAAoB,EAAE,EAAQ,EAAE;YACrE,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,MAAM,CAAC,IAAI,QAAQ,CAAC,cAAc,EAAE,0BAA0B,EAAE,iDAAiD,CAAC,CAAC,CAAC;gBACpH,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAClD,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,CAAC,KAAK,CAAC,CAAC;gBACf,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC7B,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC3B,OAAO;YACT,CAAC;YAED,8BAA8B;YAC9B,IAAI,SAAS,IAAI,SAAS,IAAI,GAAG,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;gBAC5D,KAAK,IAAI,SAAS,CAAC;YACrB,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACzB,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/http.d.ts

@@ -0,0 +1,9 @@
+export interface HttpOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+}
+export type QueryValue = string | number | boolean;
+export declare function postJson<TResponse>(pathOrUrl: string, body: unknown, options: HttpOptions): Promise<TResponse>;
+export declare function postJsonNoResponse(pathOrUrl: string, body: unknown, options: HttpOptions): Promise<void>;
+export declare function getJson<TResponse>(pathOrUrl: string, query: Record<string, QueryValue>, options: HttpOptions): Promise<TResponse>;

package/dist/core/http.js

@@ -0,0 +1,144 @@
+/**
+ * HTTP 请求封装模块。
+ *
+ * 业务接口和埋点接口的响应规则不同：
+ * - recommend/list/detail/execute 这类业务接口需要返回 JSON，命令模块会读取 error_no。
+ * - CLI 埋点上传接口只要求 HTTP 200，不要求响应体。
+ *
+ * 因此这里提供两类 helper：`postJson/getJson` 用于业务接口，
+ * `postJsonNoResponse` 用于埋点上传。
+ */
+import { CliError } from "./errors.js";
+export async function postJson(pathOrUrl, body, options) {
+    // POST JSON 时固定 Content-Type，并把 body 序列化成字符串。
+    return requestJson(pathOrUrl, options, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+    });
+}
+export async function postJsonNoResponse(pathOrUrl, body, options) {
+    // 埋点上传只看 HTTP 状态码，不读取响应体。
+    await requestNoResponse(pathOrUrl, options, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+    });
+}
+export async function getJson(pathOrUrl, query, options) {
+    // GET 请求没有 body，参数统一拼到 URL 的 query string 上。
+    return requestJson(appendQuery(pathOrUrl, query, options.baseUrl), options, {
+        method: "GET"
+    });
+}
+async function requestJson(pathOrUrl, options, init) {
+    // 先发请求，再按 JSON 业务接口规则解析响应体。
+    const response = await request(pathOrUrl, options, init);
+    return parseJsonResponse(response);
+}
+async function requestNoResponse(pathOrUrl, options, init) {
+    // 先发请求，再只判断 HTTP 状态码。
+    const response = await request(pathOrUrl, options, init);
+    if (!response.ok) {
+        throw new CliError("backend_error", `Backend returned HTTP ${response.status}.`, "Retry later.", 1, { telemetryEligible: false });
+    }
+}
+async function request(pathOrUrl, options, init) {
+    // AbortController 用来在 timeoutMs 后主动取消 fetch。
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        // resolveUrl 支持两种输入：相对路径和完整 URL。
+        const response = await fetch(resolveUrl(pathOrUrl, options.baseUrl), {
+            ...init,
+            headers: {
+                ...init.headers,
+                "X-Api-Key": options.apiKey
+            },
+            signal: controller.signal
+        });
+        // 401/403 表示鉴权失败，直接映射成 auth_invalid。
+        if (response.status === 401 || response.status === 403) {
+            throw new CliError("auth_invalid", "API key is invalid.", "Generate a valid API key and run ae login again.", 1, { telemetryEligible: false });
+        }
+        // 429 表示限流，agent 可以稍后重试。
+        if (response.status === 429) {
+            throw new CliError("rate_limited", "Request was rate limited.", "Retry later.", 1, { telemetryEligible: false });
+        }
+        // 其他状态码先返回给上层。业务接口可能在 400 时仍带 JSON error_no。
+        return response;
+    }
+    catch (error) {
+        // 已经归一化的 CliError 不要二次包装。
+        if (error instanceof CliError) {
+            throw error;
+        }
+        // AbortController 触发的异常会叫 AbortError，归为 timeout。
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new CliError("timeout", "Request timed out.", "Retry later.");
+        }
+        // 其他 fetch 失败通常是 DNS、代理、断网、连接失败等网络问题。
+        throw new CliError("network_error", "Unable to connect to AgentEarth backend.", "Check network and retry.");
+    }
+    finally {
+        // 请求结束后清理定时器，避免 Node 进程被无意义的 timer 挂住。
+        clearTimeout(timeout);
+    }
+}
+async function parseJsonResponse(response) {
+    try {
+        // response.json() 会读取响应体并 JSON.parse。
+        const payload = await response.json();
+        // 业务接口的 HTTP 2xx 响应必须先符合 AgentAPI 顶层包络，后续命令模块再校验 tools/result 等业务字段。
+        if (response.ok && !isAgentApiEnvelope(payload)) {
+            throw new CliError("backend_response_invalid", "Backend response is missing AgentAPI envelope.", "Retry later.");
+        }
+        // HTTP 状态码不能被 body 里的成功标记覆盖；非 2xx 只有 error_no=-1 这类后端业务错误继续交给命令模块细分映射。
+        if (!response.ok && !isBackendBusinessError(payload)) {
+            throw new CliError("backend_error", `Backend returned HTTP ${response.status}.`, "Retry later.", 1, { telemetryEligible: false });
+        }
+        return payload;
+    }
+    catch (error) {
+        // 上面主动归一化出来的 CliError 需要原样透传，避免被误判为 JSON 解析失败。
+        if (error instanceof CliError) {
+            throw error;
+        }
+        // 如果 HTTP 本身失败且响应体不是 JSON，归为普通 backend_error。
+        if (!response.ok) {
+            throw new CliError("backend_error", `Backend returned HTTP ${response.status}.`, "Retry later.", 1, { telemetryEligible: false });
+        }
+        // HTTP 成功但不是 JSON，说明后端响应不符合 CLI 契约。
+        throw new CliError("backend_response_invalid", `Backend returned invalid JSON with HTTP ${response.status}.`, "Retry later.");
+    }
+}
+function isBackendBusinessError(value) {
+    // AgentAPI 的业务失败响应使用 error_no=-1；这种情况保留给 mapBackendError 做更细错误码映射。
+    return isRecord(value) && value.error_no === -1;
+}
+function isAgentApiEnvelope(value) {
+    // AgentAPI 业务响应至少要有 error_no/error_msg，缺失时说明后端响应无法被 CLI 按契约解析。
+    return isRecord(value) && typeof value.error_no === "number" && typeof value.error_msg === "string";
+}
+function appendQuery(pathOrUrl, query, baseUrl) {
+    // URL 对象可以安全处理已有 query、转义字符和相对路径。
+    const url = new URL(resolveUrl(pathOrUrl, baseUrl));
+    for (const [key, value] of Object.entries(query)) {
+        // set 会覆盖同名参数；list 当前只支持一层标量，所以直接转字符串。
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+function resolveUrl(pathOrUrl, baseUrl) {
+    // execute 使用后端返回的完整 tool_url，因此这里必须支持完整 URL。
+    if (/^https?:\/\//i.test(pathOrUrl)) {
+        return pathOrUrl;
+    }
+    // 其他接口通常传相对 path，这里和 baseUrl 拼起来，并处理多余斜杠。
+    return `${baseUrl.replace(/\/$/, "")}/${pathOrUrl.replace(/^\//, "")}`;
+}
+function isRecord(value) {
+    // object 会包含数组；响应 payload 的顶层必须是普通对象才可能有 error_no 字段。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=http.js.map

package/dist/core/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAcvC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAiB,EACjB,IAAa,EACb,OAAoB;IAEpB,8CAA8C;IAC9C,OAAO,WAAW,CAAY,SAAS,EAAE,OAAO,EAAE;QAChD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,IAAa,EACb,OAAoB;IAEpB,0BAA0B;IAC1B,MAAM,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE;QAC1C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,SAAiB,EACjB,KAAiC,EACjC,OAAoB;IAEpB,6CAA6C;IAC7C,OAAO,WAAW,CAAY,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE;QACrF,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,SAAiB,EACjB,OAAoB,EACpB,IAAiB;IAEjB,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACzD,OAAO,iBAAiB,CAAY,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,SAAiB,EACjB,OAAoB,EACpB,IAAiB;IAEjB,sBAAsB;IACtB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,yBAAyB,QAAQ,CAAC,MAAM,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;IACpI,CAAC;AACH,CAAC;AAED,KAAK,UAAU,OAAO,CACpB,SAAiB,EACjB,OAAoB,EACpB,IAAiB;IAEjB,6CAA6C;IAC7C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAExE,IAAI,CAAC;QACH,iCAAiC;QACjC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE;YACnE,GAAG,IAAI;YACP,OAAO,EAAE;gBACP,GAAG,IAAI,CAAC,OAAO;gBACf,WAAW,EAAE,OAAO,CAAC,MAAM;aAC5B;YACD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,qCAAqC;QACrC,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvD,MAAM,IAAI,QAAQ,CAAC,cAAc,EAAE,qBAAqB,EAAE,kDAAkD,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QACjJ,CAAC;QAED,yBAAyB;QACzB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,QAAQ,CAAC,cAAc,EAAE,2BAA2B,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QACnH,CAAC;QAED,6CAA6C;QAC7C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0BAA0B;QAC1B,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC;QACd,CAAC;QAED,iDAAiD;QACjD,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1D,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,oBAAoB,EAAE,cAAc,CAAC,CAAC;QACtE,CAAC;QAED,sCAAsC;QACtC,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC;IAC9G,CAAC;YAAS,CAAC;QACT,uCAAuC;QACvC,YAAY,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAY,QAAkB;IAC5D,IAAI,CAAC;QACH,sCAAsC;QACtC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAe,CAAC;QAEnD,qEAAqE;QACrE,IAAI,QAAQ,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,gDAAgD,EAAE,cAAc,CAAC,CAAC;QACnH,CAAC;QAED,uEAAuE;QACvE,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,yBAAyB,QAAQ,CAAC,MAAM,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QACpI,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+CAA+C;QAC/C,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC;QACd,CAAC;QAED,8CAA8C;QAC9C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,yBAAyB,QAAQ,CAAC,MAAM,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QACpI,CAAC;QAED,oCAAoC;QACpC,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,2CAA2C,QAAQ,CAAC,MAAM,GAAG,EAAE,cAAc,CAAC,CAAC;IAChI,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAc;IAC5C,mEAAmE;IACnE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,+DAA+D;IAC/D,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC;AACtG,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB,EAAE,KAAiC,EAAE,OAAe;IACxF,kCAAkC;IAClC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,uCAAuC;QACvC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED,SAAS,UAAU,CAAC,SAAiB,EAAE,OAAe;IACpD,6CAA6C;IAC7C,IAAI,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,0CAA0C;IAC1C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,sDAAsD;IACtD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/core/output.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI 输出模块。
+ *
+ * 这个文件只负责把命令结果写到 stdout 或 stderr，不做业务判断。
+ * 约定是：成功写 stdout，失败写 stderr；成功与失败主要靠进程退出码判断。
+ * 对 agent 来说，JSON 输出必须稳定，所以这里集中维护成功和失败的输出格式。
+ */
+import type { CommandSuccess } from "../types/cli.js";
+import { CliError } from "./errors.js";
+export declare function writeSuccess(result: CommandSuccess, json: boolean): void;
+export declare function writeError(error: CliError, json: boolean): void;

package/dist/core/output.js

@@ -0,0 +1,33 @@
+export function writeSuccess(result, json) {
+    // json=true 时，直接输出完整 JSON，方便 agent 解析字段。
+    if (json) {
+        // null, 2 表示格式化缩进 2 个空格；这不影响 JSON 可解析性。
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // 如果未来支持人类可读模式，带 message 的成功结果可以退化为一行短文本。
+    if (typeof result.message === "string") {
+        console.log(result.message);
+        return;
+    }
+    // 没有 message 的成功结果，仍然输出 JSON，避免丢字段。
+    console.log(JSON.stringify(result, null, 2));
+}
+export function writeError(error, json) {
+    // 失败结构固定为 { error: { code, message, hint } }。
+    // 不再输出布尔 success 字段，失败由非 0 exit code 表示。
+    const payload = {
+        error: {
+            code: error.code,
+            message: error.message,
+            hint: error.hint
+        }
+    };
+    // agent 模式输出 JSON；人类模式输出更短的两行文本。
+    const output = json
+        ? JSON.stringify(payload, null, 2)
+        : `${error.code}: ${error.message}\nHint: ${error.hint}`;
+    // 错误必须写 stderr，避免和 stdout 的业务结果混在一起。
+    console.error(output);
+}
+//# sourceMappingURL=output.js.map

package/dist/core/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/core/output.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,YAAY,CAAC,MAAsB,EAAE,IAAa;IAChE,yCAAyC;IACzC,IAAI,IAAI,EAAE,CAAC;QACT,wCAAwC;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,0CAA0C;IAC1C,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,oCAAoC;IACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAe,EAAE,IAAa;IACvD,8CAA8C;IAC9C,yCAAyC;IACzC,MAAM,OAAO,GAAmB;QAC9B,KAAK,EAAE;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB;KACF,CAAC;IAEF,iCAAiC;IACjC,MAAM,MAAM,GAAG,IAAI;QACjB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC;IAE3D,qCAAqC;IACrC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;

package/dist/main.js

@@ -0,0 +1,300 @@
+/**
+ * CLI 主调度模块。
+ *
+ * `bin/ae.mjs` 会把命令行参数交给这里的 main 函数。这个文件是阅读源码的主线：
+ * 1. 解析参数；
+ * 2. 判断 help/version；
+ * 3. 按命令名调用对应 command 模块；
+ * 4. 统一输出成功或失败；
+ * 5. 在命令结束后写入并尝试上传 CLI 埋点。
+ *
+ * 具体业务逻辑不写在这里，而是放在 commands 目录下，方便定位问题。
+ */
+import { CLI_VERSION, EXECUTE_PATH, RECOMMEND_PATH, TOOL_DETAIL_PATH, TOOLS_LIST_PATH } from "./constants.js";
+import { runDetail } from "./commands/detail.js";
+import { runExecute } from "./commands/execute.js";
+import { runList } from "./commands/list.js";
+import { runLogin } from "./commands/login.js";
+import { runRecommend } from "./commands/recommend.js";
+import { runUpdate } from "./commands/update.js";
+import { parseArgs } from "./core/args.js";
+import { normalizeUnknownError, usageError } from "./core/errors.js";
+import { writeError, writeSuccess } from "./core/output.js";
+import { enqueueTelemetry } from "./storage/telemetryQueue.js";
+import { buildTelemetryParam, createTelemetryEvent } from "./telemetry/events.js";
+import { flushTelemetry } from "./telemetry/uploader.js";
+export async function main(argv) {
+    // 第一步：把原始字符串参数解析成 command、positionals 和 options。
+    // 参数解析本身也可能抛 usage_error，必须在 main.ts 内归一化，不能掉到 bin 入口的 unknown 兜底。
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (error) {
+        const normalized = normalizeUnknownError(error);
+        writeError(normalized, true);
+        process.exitCode = normalized.exitCode;
+        return;
+    }
+    // --version 是最短路径：只打印版本号，不进入业务命令，也不写埋点。
+    if (parsed.options.version) {
+        console.log(CLI_VERSION);
+        return;
+    }
+    // --help 或没有命令时，打印帮助文本后退出。
+    if (parsed.options.help || !parsed.command) {
+        console.log(helpText());
+        return;
+    }
+    // 记录命令开始时间，用于计算埋点 duration_ms。
+    const startedAt = Date.now();
+    // context 是传给每个 command 的公共上下文，目前主要包含 options。
+    const context = { options: parsed.options, telemetry: {} };
+    // agent 调用的命令默认 JSON；--json 仅作为兼容开关保留。
+    const jsonOutput = shouldOutputJson(parsed.command, parsed.options.json);
+    // telemetryEvent 先置空；命令结束后根据成功/失败决定是否生成。
+    let telemetryEvent = null;
+    try {
+        // 全局选项有些只适用于特定命令，这里结合 command 做二次校验。
+        validateCommandOptions(parsed.command, parsed.options);
+        // 部分命令没有位置参数，不能静默忽略 agent 误传的内容。
+        validateCommandArguments(parsed.command, parsed.positionals);
+        // dispatch 根据命令名调用具体模块，例如 runRecommend 或 runExecute。
+        const result = await dispatch(parsed.command, context, parsed.positionals);
+        // 成功输出写 stdout。
+        writeSuccess(result, jsonOutput);
+        // 后端能看到的业务成功不重复上报；login 成功需要记录本地 credentials 是否写入。
+        telemetryEvent = createSuccessTelemetry(parsed.command, parsed.positionals, context, Date.now() - startedAt);
+    }
+    catch (error) {
+        // 所有未知异常都先归一化成 CliError，确保输出结构稳定。
+        const normalized = normalizeUnknownError(error);
+        // 失败输出写 stderr。
+        writeError(normalized, jsonOutput);
+        // 非 0 退出码表示命令失败；usage_error 通常是 2。
+        process.exitCode = normalized.exitCode;
+        // 只把后端看不到的本地错误写入 CLI 埋点。
+        telemetryEvent = createErrorTelemetry(parsed.command, parsed.positionals, context, normalized, Date.now() - startedAt);
+    }
+    finally {
+        // 埋点是 best-effort：写入或上传失败都不能影响主命令结果。
+        await recordAndFlushTelemetry(telemetryEvent, parsed.options);
+    }
+}
+function validateCommandOptions(command, options) {
+    // --api-key-stdin 是安装初始化时写入 credentials 的方式；业务命令不从 stdin 读取 API key。
+    if (options.apiKeyStdin && command !== "login") {
+        throw usageError("--api-key-stdin can only be used with ae login.", "Run ae login --api-key-stdin.");
+    }
+}
+function validateCommandArguments(command, args) {
+    // login/update 是零位置参数命令；多余参数通常说明 agent 误把业务内容拼进了命令。
+    if ((command === "login" || command === "update") && args.length > 0) {
+        throw usageError(`Unexpected arguments for ae ${command}.`, `Run ae ${command}.`);
+    }
+}
+async function dispatch(command, context, args) {
+    // 每个 if 都对应一个命令模块；这里不做业务逻辑，只转发参数。
+    if (command === "login") {
+        return runLogin(context);
+    }
+    if (command === "recommend") {
+        return runRecommend(context, args);
+    }
+    if (command === "list") {
+        return runList(context, args);
+    }
+    if (command === "detail") {
+        return runDetail(context, args);
+    }
+    if (command === "execute") {
+        return runExecute(context, args);
+    }
+    if (command === "update") {
+        return runUpdate(context);
+    }
+    // 未知命令属于用法错误，不请求后端。
+    throw usageError(`Unknown command: ${command}`);
+}
+function helpText() {
+    // 帮助文本只展示当前支持命令，不展示已经移除的 schema/config。
+    return `AgentEarth CLI ${CLI_VERSION}
+
+Usage:
+  ae login --api-key-stdin [--json]
+  ae login --api-key <key> [--json]
+  ae recommend "<query>"
+  ae list ['<json>']
+  ae detail <tool_name>
+  ae execute <tool_name> '<json>'
+  ae update
+
+Global options:
+  --api-key <key>       Temporarily override API key; not recommended for login secrets
+  --api-key-stdin       Read login API key from stdin
+  --base-url <url>      Override AgentEarth backend URL
+  --timeout <seconds>   Override request timeout
+  --json                Output JSON
+  --no-telemetry        Disable telemetry for this run
+  --version             Print version
+  --help                Print help
+`;
+}
+function shouldOutputJson(command, explicitJson) {
+    // 用户显式传 --json 时，所有命令都输出 JSON。
+    if (explicitJson) {
+        return true;
+    }
+    // 没有 command 的场景已经在前面输出 help 文本，这里保留 false 作为防御性默认值。
+    if (!command) {
+        return false;
+    }
+    // 只要进入命令分发阶段，就默认给 agent 可解析的 JSON。
+    // 这包括未知命令和已移除命令；它们会统一变成 usage_error，方便 agent 纠正调用。
+    return true;
+}
+function createSuccessTelemetry(command, args, context, durationMs) {
+    // recommend/list/detail/execute 的成功请求后端本来就能看到，不重复上传 CLI 埋点。
+    // login 成功不同：后端只看到验证探针，看不到本地 credentials 是否写成功。
+    // update 成功或无更新也发生在本机，后端默认看不到 npm/update 的真实结果。
+    if (command !== "login" && command !== "update") {
+        return null;
+    }
+    if (command === "update") {
+        return createTelemetryEvent("update", "", {
+            duration_ms: durationMs,
+            param: telemetryParamFor(command, args, context.telemetry)
+        });
+    }
+    // login 的后端 path 对应 recommend 探针，因为它复用了 recommend 接口验证 key。
+    return createTelemetryEvent("login", RECOMMEND_PATH, {
+        duration_ms: durationMs,
+        param: telemetryParamFor(command, args, context.telemetry)
+    });
+}
+function createErrorTelemetry(command, args, context, error, durationMs) {
+    // 没有命令名，或者错误码不属于 CLI 本地归因，就不写埋点。
+    if (!command || !error.telemetryEligible || !isTelemetryErrorCode(error.code)) {
+        return null;
+    }
+    // 只有当前支持的命令才有稳定 method；未知命令不上传，避免污染日志维度。
+    const method = telemetryMethodFor(command);
+    if (!method) {
+        return null;
+    }
+    return createTelemetryEvent(method, telemetryPathFor(command), {
+        duration_ms: durationMs,
+        param: telemetryParamFor(command, args, context.telemetry),
+        error_code: error.code,
+        error_msg: error.message
+    });
+}
+async function recordAndFlushTelemetry(event, options) {
+    // --no-telemetry 或 AE_NO_TELEMETRY=1 会完全跳过本次埋点。
+    if (options.noTelemetry) {
+        return;
+    }
+    try {
+        // 如果本次命令产生了需要上传的本地事件，先追加到本地 events.jsonl。
+        if (event) {
+            await enqueueTelemetry(event);
+        }
+    }
+    catch {
+        // 本地埋点写入失败不能影响用户命令，所以这里静默吞掉。
+    }
+    try {
+        // 每次命令结束后尝试冲刷历史队列；失败也会在 uploader 内部静默保留。
+        await flushTelemetry(options);
+    }
+    catch {
+        // 这里再做一层兜底，保证 uploader 未来改动后也不会影响主命令。
+    }
+}
+function telemetryMethodFor(command) {
+    // 只有这些命令能成为埋点 method。
+    if (command === "login"
+        || command === "recommend"
+        || command === "list"
+        || command === "detail"
+        || command === "execute"
+        || command === "update") {
+        return command;
+    }
+    return null;
+}
+function telemetryPathFor(command) {
+    // path 按对应后端 API 路径记录，不写 CLI 命令文本。
+    if (command === "login" || command === "recommend")
+        return RECOMMEND_PATH;
+    if (command === "list")
+        return TOOLS_LIST_PATH;
+    if (command === "detail")
+        return TOOL_DETAIL_PATH;
+    if (command === "execute")
+        return EXECUTE_PATH;
+    return "";
+}
+function telemetryParamFor(command, args, telemetry = {}) {
+    // recommend 的业务参数是自然语言 query。
+    if (command === "recommend") {
+        return buildTelemetryParam({ query: args.join(" ").trim() });
+    }
+    // list 的可选参数是一个 JSON filter，当前整体放进 query 字段。
+    if (command === "list") {
+        return buildTelemetryParam({ query: args[0] ?? "" });
+    }
+    // detail 的业务参数是 tool_name。
+    if (command === "detail") {
+        return buildTelemetryParam({ toolName: args[0] ?? "" });
+    }
+    // execute 的业务参数包括 tool_name 和 params。
+    if (command === "execute") {
+        return buildTelemetryParam({
+            toolName: args[0] ?? "",
+            // execute.ts 已经读取过 @file/stdin/inline 参数，失败埋点优先复用解析结果。
+            params: telemetry.executeParams ?? parseInlineJsonObject(args[1])
+        });
+    }
+    // update 的本地结果写入 param.update_result；异常路径没有显式结果时按 failed 兜底。
+    if (command === "update") {
+        return buildTelemetryParam({ updateResult: telemetry.updateResult ?? "failed" });
+    }
+    // login 当前不上传 key 相关内容，所以 param 使用空对象字段。
+    return buildTelemetryParam();
+}
+function parseInlineJsonObject(raw) {
+    // @file 和 stdin 形式不在 main.ts 读取，避免为了埋点再读一次用户文件或 stdin。
+    if (!raw || raw.startsWith("@") || raw === "-") {
+        return {};
+    }
+    try {
+        // 只有 inline JSON 能在这里安全解析进 param.params。
+        return JSON.parse(raw);
+    }
+    catch {
+        // 如果 JSON 本身坏了，具体错误由 execute.ts 抛 params_invalid。
+        // 埋点 param 里保留空对象，避免错误日志混入不可解析原文。
+        return {};
+    }
+}
+function isTelemetryErrorCode(code) {
+    // 这里列出的都是“后端不一定知道”的本地错误或后端响应契约错误。
+    return code === "usage_error"
+        || code === "network_error"
+        || code === "timeout"
+        || code === "credentials_write_failed"
+        || code === "session_write_failed"
+        || code === "tool_name_parse_failed"
+        || code === "schema_missing"
+        || code === "tool_name_invalid"
+        || code === "params_invalid"
+        || code === "backend_response_invalid"
+        || code === "version_check_failed"
+        || code === "update_failed"
+        || code === "update_verify_failed"
+        || code === "update_not_applied"
+        // unknown 表示 CLI 本地异常未被更细错误码覆盖，后端默认看不到，也需要进入本地埋点。
+        || code === "unknown";
+}
+//# sourceMappingURL=main.js.map