@agentearth.ai/cli 0.1.0-beta.0

package/dist/storage/telemetryQueue.js

@@ -0,0 +1,252 @@
+/**
+ * 本地埋点队列模块。
+ *
+ * CLI 埋点不能影响主命令，所以事件会先写入本地 events.jsonl。
+ * 上传成功后，再从文件头部删除已经上传的事件。jsonl 的意思是：
+ * 一行一个 JSON 对象，适合追加写入，也适合按行读取前 N 条。
+ */
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { EXECUTE_PATH, RECOMMEND_PATH, TELEMETRY_QUEUE_MAX_BYTES, TELEMETRY_QUEUE_MAX_LINES, TOOL_DETAIL_PATH, TOOLS_LIST_PATH } from "../constants.js";
+import { TELEMETRY_LOG_TYPE, TELEMETRY_MSG } from "../telemetry/events.js";
+import { pathExists, protectSensitiveFile } from "./fileProtection.js";
+import { ensureAgentEarthDir, getTelemetryQueuePath } from "./paths.js";
+export async function enqueueTelemetry(event, options = {}) {
+    // 写队列前确保本地数据目录存在。
+    await ensureAgentEarthDir();
+    // 每条事件单独一行，后续读取时可以按换行切分。
+    const queuePath = getTelemetryQueuePath();
+    // events.jsonl 高频追加写入；已存在时复用首次创建时收紧的权限。
+    const queueFileExists = await pathExists(queuePath);
+    await appendFile(queuePath, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+    // 入队后立即裁剪，避免埋点后端长期不可用时本地队列无限增长。
+    await trimTelemetryQueue(queuePath, options.fileProtection);
+    // events.jsonl 可能包含 query/params，和 credentials 一样按敏感文件保护。
+    if (!queueFileExists) {
+        await protectTelemetryQueueFile(queuePath, options.fileProtection);
+    }
+}
+async function trimTelemetryQueue(queuePath, fileProtection) {
+    try {
+        const raw = await readFile(queuePath, "utf8");
+        const lines = raw.split(/\r?\n/).filter(Boolean);
+        const trimmedLines = keepLatestTelemetryLines(lines);
+        if (trimmedLines.length === lines.length && Buffer.byteLength(raw, "utf8") <= TELEMETRY_QUEUE_MAX_BYTES) {
+            return;
+        }
+        await writeTelemetryQueueLines(queuePath, trimmedLines, fileProtection);
+    }
+    catch {
+        // 裁剪失败也不能影响主命令；后续上传或下一次入队会再尝试处理。
+    }
+}
+function keepLatestTelemetryLines(lines) {
+    // 先按行数保留最新队尾，旧事件可丢，因为埋点是 best-effort 数据。
+    let latestLines = lines.slice(-TELEMETRY_QUEUE_MAX_LINES);
+    // 再按字节数裁剪；如果单条最新事件本身超过上限，仍保留这一条，避免本次事件被静默丢弃。
+    while (latestLines.length > 1 && telemetryLinesByteLength(latestLines) > TELEMETRY_QUEUE_MAX_BYTES) {
+        latestLines = latestLines.slice(1);
+    }
+    return latestLines;
+}
+function telemetryLinesByteLength(lines) {
+    return Buffer.byteLength(lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
+}
+async function writeTelemetryQueueLines(queuePath, lines, fileProtection) {
+    // 如果裁剪重写时文件被外部删除，重建后仍需要补一次保护。
+    const queueFileExists = await pathExists(queuePath);
+    await writeFile(queuePath, lines.length > 0 ? `${lines.join("\n")}\n` : "", { encoding: "utf8", mode: 0o600 });
+    if (!queueFileExists) {
+        await protectTelemetryQueueFile(queuePath, fileProtection);
+    }
+}
+export async function protectTelemetryQueueFile(queuePath, options) {
+    // 统一复用敏感文件保护逻辑：Windows 收紧 ACL，macOS/Linux chmod 600。
+    await protectSensitiveFile(queuePath, options);
+}
+export async function readTelemetryQueue(limit = 20) {
+    return (await readTelemetryQueueBatch(limit)).events;
+}
+export async function readTelemetryQueueBatch(limit = 20) {
+    try {
+        // 一次最多读取前 limit 条，避免单次上传过大。
+        const raw = await readFile(getTelemetryQueuePath(), "utf8");
+        const lines = raw
+            // 同时兼容 Windows 的 CRLF 和 macOS/Linux 的 LF。
+            .split(/\r?\n/)
+            // 文件末尾通常会有空行，这里去掉空行。
+            .filter(Boolean);
+        const events = [];
+        let consumedLineCount = 0;
+        for (const line of lines) {
+            if (events.length >= limit) {
+                break;
+            }
+            consumedLineCount += 1;
+            try {
+                // 每一行都应该是一个 TelemetryEvent JSON；结构不对的本地坏数据也要跳过。
+                const event = JSON.parse(line);
+                if (isTelemetryEvent(event)) {
+                    events.push(event);
+                }
+            }
+            catch {
+                // 损坏行不能上传，但要计入 consumedLineCount，上传成功后一起从队头清理。
+            }
+        }
+        return { events, consumedLineCount };
+    }
+    catch {
+        // 队列文件不存在、不可读或内容损坏时，都返回空队列，避免影响主命令。
+        return { events: [], consumedLineCount: 0 };
+    }
+}
+export async function dropTelemetryQueueHead(count) {
+    // count<=0 没有删除意义，直接返回。
+    if (count <= 0) {
+        return;
+    }
+    await ensureAgentEarthDir();
+    try {
+        // 重新读取完整文件，然后删掉前 count 行。
+        const raw = await readFile(getTelemetryQueuePath(), "utf8");
+        const lines = raw.split(/\r?\n/).filter(Boolean);
+        // 上传成功删除队头后也要继续执行容量保护，避免历史超限队列只靠下一次入队才被修复。
+        const remaining = keepLatestTelemetryLines(lines.slice(count));
+        // 如果还有剩余事件，保留换行；如果没有，写成空文件。
+        const queuePath = getTelemetryQueuePath();
+        // 重写队列文件后继续保持私有权限。
+        await writeTelemetryQueueLines(queuePath, remaining);
+    }
+    catch {
+        // 删除队头失败时静默处理；下次上传可能会重复发送，但不会影响用户命令。
+    }
+}
+function isTelemetryEvent(value) {
+    // events.jsonl 是本地可变文件，不能只相信 JSON.parse 成功；字段结构也要符合日志规范。
+    if (!isRecord(value)) {
+        return false;
+    }
+    return value.log_type === TELEMETRY_LOG_TYPE
+        && (value.level === "info" || value.level === "error")
+        && typeof value.request_id === "string"
+        && typeof value.path === "string"
+        && typeof value.param === "string"
+        // param 在日志规范中是 JSON string；本地队列被篡改或损坏时，非法 param 不能上传到后端。
+        && isTelemetryParamString(value.param)
+        && isTelemetryMethod(value.method)
+        && (value.status_code === 0 || value.status_code === 1)
+        // duration_ms 必须符合日志规范的 int 语义：非负整数。
+        && typeof value.duration_ms === "number"
+        && Number.isInteger(value.duration_ms)
+        && value.duration_ms >= 0
+        && value.msg === TELEMETRY_MSG
+        && typeof value.error_msg === "string"
+        && isIsoDateTimeString(value.occurred_at)
+        && typeof value.cli_version === "string"
+        && isTelemetryPlatform(value.platform)
+        && isTelemetryShellFamily(value.shell_family)
+        && isTelemetryErrorCode(value.error_code)
+        && hasExpectedTelemetryPath(value)
+        && hasConsistentTelemetryStatus(value);
+}
+function hasExpectedTelemetryPath(value) {
+    // method/path 必须符合日志规范表，避免本地队列坏数据把命令和后端路径错配。
+    if (value.method === "login" || value.method === "recommend") {
+        return value.path === RECOMMEND_PATH;
+    }
+    if (value.method === "list")
+        return value.path === TOOLS_LIST_PATH;
+    if (value.method === "detail")
+        return value.path === TOOL_DETAIL_PATH;
+    if (value.method === "execute")
+        return value.path === EXECUTE_PATH;
+    if (value.method === "update")
+        return value.path === "";
+    return false;
+}
+function hasConsistentTelemetryStatus(value) {
+    if (value.error_code === "") {
+        // 成功或无本地错误时，状态字段必须全部落在成功语义上。
+        return value.level === "info"
+            && value.status_code === 0
+            && value.error_msg === "";
+    }
+    // 失败事件必须同时具备 error 级别、失败状态码、非空错误码和安全错误文案。
+    return value.level === "error"
+        && value.status_code === 1
+        && typeof value.error_code === "string"
+        && value.error_code.length > 0
+        && typeof value.error_msg === "string"
+        && value.error_msg.length > 0;
+}
+function isTelemetryMethod(value) {
+    return value === "login"
+        || value === "recommend"
+        || value === "list"
+        || value === "detail"
+        || value === "execute"
+        || value === "update";
+}
+function isTelemetryPlatform(value) {
+    return value === "windows"
+        || value === "macos"
+        || value === "linux"
+        || value === "unknown";
+}
+function isTelemetryShellFamily(value) {
+    return value === "powershell"
+        || value === "cmd"
+        || value === "bash"
+        || value === "zsh"
+        || value === "unknown";
+}
+function isTelemetryErrorCode(value) {
+    // 成功或无本地错误时 error_code 必须为空字符串；失败时必须是日志规范允许值。
+    return value === ""
+        || value === "usage_error"
+        || value === "network_error"
+        || value === "timeout"
+        || value === "credentials_write_failed"
+        || value === "session_write_failed"
+        || value === "tool_name_parse_failed"
+        || value === "schema_missing"
+        || value === "tool_name_invalid"
+        || value === "params_invalid"
+        || value === "backend_response_invalid"
+        || value === "version_check_failed"
+        || value === "update_failed"
+        || value === "update_verify_failed"
+        || value === "update_not_applied"
+        // unknown 是 CLI 本地兜底错误码，合法事件不能在上传前被当作坏数据丢弃。
+        || value === "unknown";
+}
+function isIsoDateTimeString(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    // createTelemetryEvent 使用 Date.toISOString()，格式固定为 YYYY-MM-DDTHH:mm:ss.sssZ。
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+        return false;
+    }
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
+function isTelemetryParamString(value) {
+    try {
+        // param 反序列化后必须符合日志规范里的内部字段类型，避免本地坏数据进入后端。
+        const parsed = JSON.parse(value);
+        return isRecord(parsed)
+            && typeof parsed.query === "string"
+            && typeof parsed.tool_name === "string"
+            && isRecord(parsed.params)
+            && typeof parsed.update_result === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    // object 会包含数组，所以这里排除 Array，避免数组被当成事件对象。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=telemetryQueue.js.map

package/dist/storage/telemetryQueue.js.map

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

package/dist/storage/updateCache.d.ts

@@ -0,0 +1,19 @@
+import { type ProtectSensitiveFileOptions } from "./fileProtection.js";
+export declare const UPDATE_CACHE_TTL_MS: number;
+export interface UpdateCache {
+    last_checked_at: string;
+    current_version: string;
+    latest_version: string;
+    has_update: boolean;
+    message?: string;
+    update_command?: string;
+    release_notes?: unknown[];
+}
+export type WritableUpdateCache = Omit<UpdateCache, "last_checked_at">;
+export interface WriteUpdateCacheOptions {
+    fileProtection?: ProtectSensitiveFileOptions;
+}
+export declare function readUpdateCache(now?: Date): Promise<UpdateCache | null>;
+export declare function writeUpdateCache(value: WritableUpdateCache, checkedAt?: Date, options?: WriteUpdateCacheOptions): Promise<UpdateCache>;
+export declare function protectUpdateCacheFile(filePath: string, options?: ProtectSensitiveFileOptions): Promise<void>;
+export declare function isUpdateCacheFresh(cache: UpdateCache, now?: Date): boolean;

package/dist/storage/updateCache.js

@@ -0,0 +1,80 @@
+/**
+ * 更新检查缓存模块。
+ *
+ * list/recommend 会读取这个文件展示 fresh 更新提示。
+ * 缓存失效时，CLI 通过 npm view 查询 npm registry，并把检查结果写回这里，
+ * 避免每次工具发现都请求 registry。
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { pathExists, protectSensitiveFile } from "./fileProtection.js";
+import { ensureAgentEarthDir, getUpdateCachePath } from "./paths.js";
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export async function readUpdateCache(now = new Date()) {
+    try {
+        // update-cache 不可信，读取后必须做结构校验和过期判断。
+        const raw = await readFile(getUpdateCachePath(), "utf8");
+        const cache = normalizeUpdateCache(JSON.parse(raw));
+        if (!cache || !isUpdateCacheFresh(cache, now)) {
+            return null;
+        }
+        return cache;
+    }
+    catch {
+        // 文件不存在、JSON 损坏或权限异常，都视为没有可用缓存。
+        return null;
+    }
+}
+export async function writeUpdateCache(value, checkedAt = new Date(), options = {}) {
+    // 写缓存前先确保 AgentEarth 本地数据目录存在。
+    await ensureAgentEarthDir();
+    const cache = {
+        ...value,
+        last_checked_at: checkedAt.toISOString()
+    };
+    const cachePath = getUpdateCachePath();
+    // 已存在的 update-cache.json 复用首次创建时的文件权限，避免每次缓存刷新都跑 ACL 命令。
+    const cacheFileExists = await pathExists(cachePath);
+    // update-cache 不保存 API key，但会影响更新提示，也按当前用户私有文件处理。
+    await writeFile(cachePath, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+    if (!cacheFileExists) {
+        await protectUpdateCacheFile(cachePath, options.fileProtection);
+    }
+    return cache;
+}
+export async function protectUpdateCacheFile(filePath, options) {
+    // update-cache 会影响更新提示和本地更新流程，按当前用户私有文件处理。
+    await protectSensitiveFile(filePath, options);
+}
+export function isUpdateCacheFresh(cache, now = new Date()) {
+    const checkedAt = Date.parse(cache.last_checked_at);
+    if (!Number.isFinite(checkedAt)) {
+        return false;
+    }
+    const ageMs = now.getTime() - checkedAt;
+    // last_checked_at 晚于当前时间时，说明本地时间或缓存内容异常，不能长期跳过版本检查。
+    return ageMs >= 0 && ageMs < UPDATE_CACHE_TTL_MS;
+}
+function normalizeUpdateCache(value) {
+    // 只接受后续更新流程必须依赖的核心字段，其它字段做保守透传。
+    if (!isRecord(value)
+        || typeof value.last_checked_at !== "string"
+        || typeof value.current_version !== "string"
+        || typeof value.latest_version !== "string"
+        || typeof value.has_update !== "boolean") {
+        return null;
+    }
+    return {
+        last_checked_at: value.last_checked_at,
+        current_version: value.current_version,
+        latest_version: value.latest_version,
+        has_update: value.has_update,
+        message: typeof value.message === "string" ? value.message : undefined,
+        update_command: typeof value.update_command === "string" ? value.update_command : undefined,
+        release_notes: Array.isArray(value.release_notes) ? value.release_notes : undefined
+    };
+}
+function isRecord(value) {
+    // object 会包含数组，所以这里排除 Array。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=updateCache.js.map

package/dist/storage/updateCache.js.map

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

package/dist/telemetry/events.d.ts

@@ -0,0 +1,42 @@
+export declare const TELEMETRY_LOG_TYPE = "agentearth_cli_telemetry";
+export declare const TELEMETRY_MSG = "cli telemetry event";
+export type TelemetryMethod = "login" | "recommend" | "list" | "detail" | "execute" | "update";
+export type TelemetryLevel = "info" | "error";
+export type TelemetryPlatform = "windows" | "macos" | "linux" | "unknown";
+export type TelemetryShellFamily = "powershell" | "cmd" | "bash" | "zsh" | "unknown";
+export interface TelemetryEvent {
+    log_type: typeof TELEMETRY_LOG_TYPE;
+    level: TelemetryLevel;
+    request_id: string;
+    path: string;
+    param: string;
+    method: TelemetryMethod;
+    status_code: 0 | 1;
+    duration_ms: number;
+    msg: typeof TELEMETRY_MSG;
+    error_msg: string;
+    occurred_at: string;
+    cli_version: string;
+    platform: TelemetryPlatform;
+    shell_family: TelemetryShellFamily;
+    error_code: string;
+}
+export interface TelemetryParamFields {
+    query?: string;
+    toolName?: string;
+    params?: unknown;
+    updateResult?: string;
+}
+export interface CreateTelemetryEventFields {
+    level?: TelemetryLevel;
+    request_id?: string;
+    param?: string;
+    status_code?: 0 | 1;
+    duration_ms?: number;
+    error_msg?: string;
+    error_code?: string;
+    platform?: TelemetryPlatform;
+    shell_family?: TelemetryShellFamily;
+}
+export declare function buildTelemetryParam(fields?: TelemetryParamFields): string;
+export declare function createTelemetryEvent(method: TelemetryMethod, path: string, fields?: CreateTelemetryEventFields): TelemetryEvent;

package/dist/telemetry/events.js

@@ -0,0 +1,80 @@
+/**
+ * CLI 埋点日志构造模块。
+ *
+ * 这里把 CLI 内部信息整理成后端日志接口要求的字段。注意当前模型不是旧的
+ * “event_name + 二级状态字段”事件模型，而是飞书日志规范风格：
+ * log_type、level、request_id、path、param、method、status_code、error_code 等。
+ *
+ * main.ts 只调用这里的函数生成事件，不应该自己拼字段，避免口径分散。
+ */
+import { randomUUID } from "node:crypto";
+import { CLI_VERSION } from "../constants.js";
+// log_type 是固定值，用于后端区分 CLI 埋点日志。
+export const TELEMETRY_LOG_TYPE = "agentearth_cli_telemetry";
+// msg 是固定摘要，不写具体错误原因；具体失败原因放 error_code/error_msg。
+export const TELEMETRY_MSG = "cli telemetry event";
+export function buildTelemetryParam(fields = {}) {
+    // 后端要求 param 是 string，所以这里把内部对象 JSON.stringify。
+    return JSON.stringify({
+        // 没有值的 string 字段必须是空字符串，不使用 null。
+        query: fields.query ?? "",
+        tool_name: fields.toolName ?? "",
+        // params 必须是对象；如果传入字符串/数组/null，就按空对象处理。
+        params: isRecord(fields.params) ? fields.params : {},
+        update_result: fields.updateResult ?? ""
+    });
+}
+export function createTelemetryEvent(method, path, fields = {}) {
+    // error_code 为空字符串表示本地成功或无本地错误。
+    const errorCode = fields.error_code ?? "";
+    return {
+        log_type: TELEMETRY_LOG_TYPE,
+        // 如果有 error_code，默认 level=error；否则默认 info。
+        level: fields.level ?? (errorCode ? "error" : "info"),
+        // request_id 用于后端去重；同一条本地事件重试上传时不会重新生成。
+        request_id: fields.request_id ?? `req_${randomUUID()}`,
+        path,
+        param: fields.param ?? buildTelemetryParam(),
+        method,
+        status_code: fields.status_code ?? (errorCode ? 1 : 0),
+        // duration_ms 要求是非负整数。
+        duration_ms: Math.max(0, Math.trunc(fields.duration_ms ?? 0)),
+        msg: TELEMETRY_MSG,
+        error_msg: fields.error_msg ?? "",
+        occurred_at: new Date().toISOString(),
+        cli_version: CLI_VERSION,
+        platform: fields.platform ?? detectPlatform(),
+        shell_family: fields.shell_family ?? detectShellFamily(),
+        error_code: errorCode
+    };
+}
+function detectPlatform() {
+    // Node.js 在 Windows 上的 process.platform 是 win32。
+    if (process.platform === "win32")
+        return "windows";
+    // macOS 对应 darwin。
+    if (process.platform === "darwin")
+        return "macos";
+    // Linux 对应 linux。
+    if (process.platform === "linux")
+        return "linux";
+    return "unknown";
+}
+function detectShellFamily() {
+    // 不同系统把 shell 信息放在不同环境变量里，所以拼成一个字符串做粗略判断。
+    const shell = `${process.env.SHELL ?? ""} ${process.env.ComSpec ?? ""} ${process.env.PSModulePath ?? ""}`.toLowerCase();
+    if (shell.includes("powershell"))
+        return "powershell";
+    if (shell.includes("cmd.exe"))
+        return "cmd";
+    if (shell.includes("zsh"))
+        return "zsh";
+    if (shell.includes("bash"))
+        return "bash";
+    return "unknown";
+}
+function isRecord(value) {
+    // param.params 只接受普通对象；数组虽然也是 object，但业务语义不是对象参数。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=events.js.map

package/dist/telemetry/events.js.map

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

package/dist/telemetry/uploader.d.ts

@@ -0,0 +1,2 @@
+import type { GlobalOptions } from "../types/cli.js";
+export declare function flushTelemetry(options: GlobalOptions): Promise<void>;

package/dist/telemetry/uploader.js

@@ -0,0 +1,46 @@
+/**
+ * CLI 埋点上传模块。
+ *
+ * 本模块从本地 events.jsonl 读取待上传日志，调用后端 CLI 埋点接口。
+ * 上传成功只以 HTTP 200 为准，不解析响应体。上传失败时保留本地队列，
+ * 等下一次 CLI 命令结束后再尝试。
+ *
+ * 重要原则：埋点失败绝不能改变当前业务命令的输出和退出码。
+ */
+import { TELEMETRY_PATH } from "../constants.js";
+import { postJsonNoResponse } from "../core/http.js";
+import { resolveApiKey } from "../storage/credentials.js";
+import { dropTelemetryQueueHead, readTelemetryQueueBatch } from "../storage/telemetryQueue.js";
+export async function flushTelemetry(options) {
+    // 用户或测试可以关闭埋点。
+    if (options.noTelemetry) {
+        return;
+    }
+    // 默认最多读取队头 20 条，具体限制在 readTelemetryQueueBatch 内部。
+    const batch = await readTelemetryQueueBatch();
+    const events = batch.events;
+    if (events.length === 0) {
+        if (batch.consumedLineCount > 0) {
+            // 队头只有损坏行时，不请求后端，直接清理这些无法上传的本地坏数据。
+            await dropTelemetryQueueHead(batch.consumedLineCount);
+        }
+        // 没有待上传事件时不请求后端。
+        return;
+    }
+    try {
+        // 埋点接口也需要 API key，后端用它识别用户。
+        const apiKey = await resolveApiKey(options);
+        // 后端契约是 POST { events }，成功只要求 HTTP 200。
+        await postJsonNoResponse(TELEMETRY_PATH, { events }, {
+            apiKey,
+            baseUrl: options.baseUrl,
+            timeoutMs: options.timeoutMs
+        });
+        // 上传成功后，删除本次实际消费过的队头原始行；其中可能包含被跳过的损坏行。
+        await dropTelemetryQueueHead(batch.consumedLineCount);
+    }
+    catch {
+        // 任何上传失败都静默处理，队列保留，等待后续重试。
+    }
+}
+//# sourceMappingURL=uploader.js.map

package/dist/telemetry/uploader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploader.js","sourceRoot":"","sources":["../../src/telemetry/uploader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAG/F,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAsB;IACzD,eAAe;IACf,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO;IACT,CAAC;IAED,kDAAkD;IAClD,MAAM,KAAK,GAAG,MAAM,uBAAuB,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;YAChC,mCAAmC;YACnC,MAAM,sBAAsB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACxD,CAAC;QACD,iBAAiB;QACjB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,4BAA4B;QAC5B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;QAE5C,wCAAwC;QACxC,MAAM,kBAAkB,CACtB,cAAc,EACd,EAAE,MAAM,EAAE,EACV;YACE,MAAM;YACN,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CACF,CAAC;QAEF,uCAAuC;QACvC,MAAM,sBAAsB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;AACH,CAAC"}

package/dist/types/api.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 后端 AgentAPI 契约类型。
+ *
+ * 这些 interface 描述 CLI 和后端之间传输的数据形状。它们只提供 TypeScript
+ * 编译期提示，不能证明运行时数据一定正确，所以命令模块里仍会做必要的空值
+ * 和字段检查。
+ */
+export interface RecommendRequest {
+    query: string;
+    limit?: number;
+}
+export interface ApiTool {
+    tool_url?: string;
+    description?: string;
+    when_to_use?: string;
+    input_schema?: unknown;
+    credit?: number;
+}
+export interface RecommendResponse {
+    error_no: number;
+    error_msg: string;
+    total?: number;
+    tools?: ApiTool[];
+}
+export interface ToolListResponse {
+    error_no: number;
+    error_msg: string;
+    total?: number;
+    page?: number;
+    page_size?: number;
+    tools?: ApiTool[];
+}
+export interface ToolDetailResponse {
+    error_no: number;
+    error_msg: string;
+    total?: number;
+    tools?: ApiTool[];
+}
+export interface ExecuteRequest {
+    params: unknown;
+}
+export interface ExecuteResponse {
+    error_no: number;
+    error_msg: string;
+    result: unknown;
+    agentearth_suggestion?: string;
+}

package/dist/types/api.js

@@ -0,0 +1,9 @@
+/**
+ * 后端 AgentAPI 契约类型。
+ *
+ * 这些 interface 描述 CLI 和后端之间传输的数据形状。它们只提供 TypeScript
+ * 编译期提示，不能证明运行时数据一定正确，所以命令模块里仍会做必要的空值
+ * 和字段检查。
+ */
+export {};
+//# sourceMappingURL=api.js.map

package/dist/types/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/types/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}