@agentearth.ai/cli 0.1.0-beta.0

package/README.md

@@ -0,0 +1,89 @@
+# AgentEarth CLI
+
+AgentEarth CLI is an agent-first command line interface that helps AI agents discover, inspect, and execute AgentEarth tools from any shell.
+
+## Commands
+
+```text
+ae login
+ae recommend
+ae list
+ae detail
+ae execute
+ae update
+```
+
+`ae update` is already a stable command entry. Version discovery uses `npm view @agentearth.ai/cli version --json`; applying an update runs `npm install -g @agentearth.ai/cli@latest`, then verifies the active `ae --version`. If npm registry version discovery fails, the command returns `version_check_failed`.
+
+## Install And Login
+
+```text
+npm install -g @agentearth.ai/cli
+ae login --api-key-stdin
+```
+
+`ae login --api-key-stdin` verifies the API key and saves it to the CLI credentials file. After login, read the JSON `skill.source` field and install or reference that skill in the agent before calling tools.
+
+`--api-key` and `AGENT_EARTH_API_KEY` are supported for compatibility and debugging, but `--api-key-stdin` is the recommended install path because it avoids putting the key in command arguments.
+
+## Agent Workflows
+
+Use `ae list` when the task category is already clear:
+
+```text
+list -> detail -> execute
+```
+
+Use `ae recommend` when the agent is not sure which tool category fits the task:
+
+```text
+recommend -> detail -> execute
+```
+
+The agent should use `tool_name` from `ae list` or `ae recommend`, then call:
+
+```text
+ae detail <tool_name>
+ae execute <tool_name> '<json>'
+```
+
+## Output Contract
+
+Core commands default to JSON. Success is written to stdout, failure is written to stderr.
+
+Success and failure are determined by exit code:
+
+```text
+exit code = 0: success
+exit code != 0: failure
+```
+
+Failure JSON is stable:
+
+```json
+{
+  "error": {
+    "code": "params_invalid",
+    "message": "Params must be valid JSON and no larger than 1MB.",
+    "hint": "Run ae detail mock_tool and provide params that match the schema."
+  }
+}
+```
+
+See `docs/Agent输出格式.md` for the agent-facing stdout/stderr format.
+
+## Development
+
+```text
+npm install
+npm run typecheck
+npm run build
+npm test
+node bin/ae.mjs --help
+```
+
+Package name is set to `@agentearth.ai/cli` for publishing.
+
+## Documentation
+
+Project documentation lives in `docs/`.

package/bin/ae.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * 这是 npm 暴露给系统的真正可执行入口。
+ *
+ * 用户或 agent 在终端里输入 `ae ...` 时，npm 会把命令转到这个文件。
+ * 这个文件只做一件事：把命令行参数交给编译后的 `dist/main.js`。
+ * 业务逻辑全部放在 TypeScript 源码里，这样入口文件保持很薄，也方便排查问题。
+ */
+import { main } from "../dist/main.js";
+
+// `process.argv` 是 Node.js 提供的原始命令行参数数组。
+// 第 1 项是 node 可执行文件路径，第 2 项是当前脚本路径。
+// 从第 3 项开始，才是用户真正传给 `ae` 的参数。
+main(process.argv.slice(2)).catch((error) => {
+  // 正常业务错误会在 `main.ts` 中被转换成稳定的 CLI 错误对象。
+  // 能走到这里，说明启动阶段发生了意外错误，例如 dist 文件不存在。
+  const message = error instanceof Error ? error.message : String(error);
+
+  // 即使是兜底错误，也保持 JSON 结构，避免 agent 收到无法解析的纯文本。
+  console.error(JSON.stringify({
+    error: {
+      code: "unknown",
+      message,
+      hint: "Run ae --help."
+    }
+  }, null, 2));
+
+  // 非 0 退出码表示命令失败；调用方可以用退出码判断流程是否中断。
+  process.exitCode = 1;
+});

package/dist/commands/detail.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runDetail(context: CommandContext, args: string[]): Promise<CommandSuccess>;

package/dist/commands/detail.js

@@ -0,0 +1,71 @@
+/**
+ * `ae detail` 命令实现。
+ *
+ * detail 代替旧的 schema 命令。agent 通过 tool_name 请求某个工具的详细信息，
+ * CLI 调用后端 detail 接口，拿到最新工具元数据和 input_schema，然后输出给 agent。
+ * 同时，detail 返回的完整 tool_url 也会刷新本地缓存，方便后续 execute 使用。
+ */
+import { TOOL_DETAIL_PATH } from "../constants.js";
+import { mapBackendError } from "../core/backendErrors.js";
+import { CliError, usageError } from "../core/errors.js";
+import { getJson } from "../core/http.js";
+import { resolveApiKey } from "../storage/credentials.js";
+import { extractToolName, writeSession } from "../storage/session.js";
+export async function runDetail(context, args) {
+    // detail 只接受一个位置参数：tool_name。
+    // tool_name 来自 shell 文本，先 trim，避免前后空白污染后端查询参数。
+    const toolName = args[0]?.trim();
+    // 缺 tool_name 或多传参数都属于用法错误。
+    if (!toolName || args.length !== 1) {
+        throw usageError("Missing or invalid detail arguments.", "Run ae detail <tool_name>.");
+    }
+    // 读取 API key；如果本地没 login，会在这里抛 auth_missing。
+    const apiKey = await resolveApiKey(context.options);
+    // detail 是 GET 接口，tool_name 放到 query string。
+    const response = await getJson(TOOL_DETAIL_PATH, { tool_name: toolName }, {
+        apiKey,
+        baseUrl: context.options.baseUrl,
+        timeoutMs: context.options.timeoutMs
+    });
+    // 后端返回业务错误时，统一映射成 CLI 错误码。
+    if (response.error_no !== 0) {
+        throw mapBackendError("detail", response.error_msg);
+    }
+    // error_no=0 后仍要校验 tools 是数组，否则后续 find 会抛 unknown，agent 无法稳定处理。
+    if (!Array.isArray(response.tools)) {
+        throw new CliError("backend_response_invalid", "Detail response is missing tools array.", "Retry later.");
+    }
+    // detail 成功时必须至少返回一个工具。
+    const tools = response.tools;
+    if (tools.length === 0) {
+        throw new CliError("backend_response_invalid", "Detail response contains no tool.", "Retry later.");
+    }
+    // 先在写缓存前确认后端返回的是请求的工具，避免契约异常污染本地 session。
+    const parsedTools = tools.map((tool) => ({
+        tool,
+        parsedToolName: extractToolName(tool.tool_url)
+    }));
+    const targetTool = parsedTools.find((item) => item.parsedToolName === toolName)?.tool;
+    if (!targetTool) {
+        // 没找到目标工具时，要区分 tool_url 解析失败和可解析但 tool_name 不匹配。
+        if (parsedTools.some((item) => !item.parsedToolName)) {
+            throw new CliError("tool_name_parse_failed", "Tool response is missing tool_name or tool_url.", "Retry later.");
+        }
+        throw new CliError("backend_response_invalid", "Detail response does not match requested tool_name.", "Retry later.");
+    }
+    // detail 的核心价值是拿 schema；缺 schema 时 agent 无法正确拼 execute params。
+    if (targetTool.input_schema == null) {
+        throw new CliError("schema_missing", "Detail response is missing input_schema.", "Retry later.");
+    }
+    // 校验通过后只写入目标工具，避免无关工具进入本地缓存。
+    const [tool] = await writeSession([targetTool]);
+    // 输出给 agent 的字段不包含 tool_url，只包含选择和拼参需要的信息。
+    return {
+        tool_name: tool.tool_name,
+        description: tool.description,
+        when_to_use: tool.when_to_use,
+        credit: tool.credit,
+        schema: tool.input_schema
+    };
+}
+//# sourceMappingURL=detail.js.map

package/dist/commands/detail.js.map

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

package/dist/commands/execute.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runExecute(context: CommandContext, args: string[]): Promise<CommandSuccess>;

package/dist/commands/execute.js

@@ -0,0 +1,118 @@
+/**
+ * `ae execute` 命令实现。
+ *
+ * execute 是真正执行工具的命令。agent 只需要传 tool_name 和 params，
+ * CLI 会从本地缓存中找到该 tool_name 对应的完整 tool_url，然后向后端发送
+ * `{ params }`。这样 agent 不需要知道 tool_url、recommend_id 或其他内部细节。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { mapBackendError } from "../core/backendErrors.js";
+import { CliError, usageError } from "../core/errors.js";
+import { postJson } from "../core/http.js";
+import { resolveApiKey } from "../storage/credentials.js";
+import { readToolByName } from "../storage/session.js";
+// 文档规定 @file/stdin 的参数体最大 1MB，避免 agent 误把超大内容塞给 CLI。
+const MAX_PARAMS_BYTES = 1024 * 1024;
+export async function runExecute(context, args) {
+    // execute 只支持两个位置参数：tool_name 和 params。
+    // tool_name 来自 shell 文本，先 trim；params 原文不能 trim，否则可能改变 inline JSON 内容。
+    const toolName = args[0]?.trim();
+    const rawParams = args[1];
+    // 少参数或多参数都拒绝，避免继续兼容旧的 recommend_id + index 语法。
+    if (!toolName || args.length !== 2) {
+        throw usageError("Missing or invalid execute arguments.", "Run ae execute <tool_name> '<json>'.");
+    }
+    // 把 agent 传入的 params 来源解析成 JS 值，准备放进请求体。
+    const params = await readParams(rawParams, toolName);
+    // params 可能来自 @file 或 stdin，main.ts 不能为了埋点再读一次；这里把已解析结果暂存给失败埋点使用。
+    context.telemetry.executeParams = params;
+    // 从本地 cache 找到工具；找不到时返回 tool_name_invalid，不请求后端。
+    const tool = await readToolByName(toolName);
+    // 读取 API key；execute 请求必须鉴权。
+    const apiKey = await resolveApiKey(context.options);
+    // 注意这里用的是缓存中的完整 tool_url，不自己用 tool_name 拼 URL。
+    const response = await postJson(tool.tool_url, { params }, {
+        apiKey,
+        baseUrl: context.options.baseUrl,
+        timeoutMs: context.options.timeoutMs
+    });
+    // 后端业务失败时，根据 error_msg 映射成稳定 CLI 错误。
+    if (response.error_no !== 0) {
+        throw mapBackendError("execute", response.error_msg);
+    }
+    // error_no=0 只说明后端认为执行成功；result 字段仍必须存在，否则 agent 会收到不可用的空成功。
+    if (!Object.prototype.hasOwnProperty.call(response, "result")) {
+        throw new CliError("backend_response_invalid", "Execute response is missing result.", "Retry later.");
+    }
+    // execute 成功后只把 agent 需要处理的结果输出出去。
+    return {
+        tool_name: tool.tool_name,
+        result: response.result,
+        agentearth_suggestion: response.agentearth_suggestion
+    };
+}
+async function readParams(raw, toolName) {
+    try {
+        // 先按 inline/@file/stdin 三种形式取到 JSON 文本。
+        const jsonText = await readParamsText(raw, toolName);
+        // JSON.parse 可以得到 object、array、string、number 等 JS 值。
+        const value = JSON.parse(jsonText);
+        if (!isRecord(value)) {
+            throw paramsInvalidError(toolName);
+        }
+        return value;
+    }
+    catch (error) {
+        // 如果前面已经明确归因为 params_invalid，直接抛出，保留更准确 message。
+        if (error instanceof CliError) {
+            throw error;
+        }
+        // 文件读取失败、stdin 读取失败、JSON 解析失败都属于本地 params_invalid。
+        throw paramsInvalidError(toolName);
+    }
+}
+async function readParamsText(raw, toolName) {
+    // 以 @ 开头表示从文件读取 JSON，主要解决 shell 引号复杂的问题。
+    if (raw.startsWith("@")) {
+        return readParamsFile(raw.slice(1), toolName);
+    }
+    if (raw === "-") {
+        // 单独的 - 表示从 stdin 读取 JSON，适合管道调用。
+        return readStdin(toolName);
+    }
+    // 默认把 raw 当作 inline JSON，例如 '{"city":"110101"}'。
+    return raw;
+}
+async function readParamsFile(filePath, toolName) {
+    // 文件形式可以在读取前先看字节大小，避免把超大文件读入内存。
+    const fileStat = await stat(filePath);
+    if (fileStat.size > MAX_PARAMS_BYTES) {
+        throw paramsInvalidError(toolName);
+    }
+    return readFile(filePath, "utf8");
+}
+async function readStdin(toolName) {
+    // stdin 是流，可能分多块到达，所以先收集到数组。
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of process.stdin) {
+        // chunk 可能是 Buffer，也可能是字符串；统一转成 Buffer。
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += buffer.byteLength;
+        if (totalBytes > MAX_PARAMS_BYTES) {
+            throw paramsInvalidError(toolName);
+        }
+        chunks.push(buffer);
+    }
+    // 所有块拼接后按 utf8 转回字符串。
+    return Buffer.concat(chunks).toString("utf8");
+}
+function paramsInvalidError(toolName) {
+    // 错误文案不能包含参数原文，避免把敏感或超大内容写进 stderr/埋点。
+    return new CliError("params_invalid", "Params must be valid JSON and no larger than 1MB.", `Run ae detail ${toolName} and provide params that match the schema.`);
+}
+function isRecord(value) {
+    // execute params 必须是普通对象；数组、null 和标量都不能作为工具参数对象。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=execute.js.map

package/dist/commands/execute.js.map

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

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runList(context: CommandContext, args: string[]): Promise<CommandSuccess>;

package/dist/commands/list.js

@@ -0,0 +1,94 @@
+/**
+ * `ae list` 命令实现。
+ *
+ * list 是“agent 已经知道大致工具类别”时的入口。它调用后端工具列表接口，
+ * 可以接收一个可选 JSON object，把其中的一层标量字段转成 URL query 参数。
+ * 这样后端以后新增筛选字段时，CLI 不需要马上改命令语法。
+ */
+import { TOOLS_LIST_PATH } from "../constants.js";
+import { mapBackendError } from "../core/backendErrors.js";
+import { CliError, usageError } from "../core/errors.js";
+import { getJson } from "../core/http.js";
+import { resolveApiKey } from "../storage/credentials.js";
+import { writeSession } from "../storage/session.js";
+import { readUpdateHint } from "./updateHint.js";
+export async function runList(context, args) {
+    // list 最多接收一个 JSON 参数；多了就说明 agent 用法不对。
+    if (args.length > 1) {
+        throw usageError("Missing or invalid list arguments.", "Run ae list or ae list '<json>'.");
+    }
+    // 没传 JSON 时使用默认分页；传了 JSON 时解析成 query。
+    const query = parseListQuery(args[0]);
+    // list 是后端业务请求，需要 API key。
+    const apiKey = await resolveApiKey(context.options);
+    // GET 请求会把 query 中的字段拼到 URL 后面。
+    const response = await getJson(TOOLS_LIST_PATH, query, {
+        apiKey,
+        baseUrl: context.options.baseUrl,
+        timeoutMs: context.options.timeoutMs
+    });
+    // 后端业务失败统一走错误映射。
+    if (response.error_no !== 0) {
+        throw mapBackendError("list", response.error_msg);
+    }
+    // error_no=0 后仍要校验 tools 是数组，避免结构损坏的成功响应污染后续缓存。
+    if (!Array.isArray(response.tools)) {
+        throw new CliError("backend_response_invalid", "List response is missing tools array.", "Retry later.");
+    }
+    // list 返回的工具也写入本地缓存，后续 execute 可以直接通过 tool_name 找到 tool_url。
+    const cachedTools = await writeSession(response.tools);
+    const result = {
+        total: response.total ?? cachedTools.length,
+        page: response.page ?? query.page,
+        page_size: response.page_size ?? query.page_size,
+        tools: cachedTools.map((tool) => ({
+            tool_name: tool.tool_name,
+            description: tool.description,
+            when_to_use: tool.when_to_use,
+            credit: tool.credit
+        }))
+    };
+    const update = await readUpdateHint();
+    if (update) {
+        result.update = update;
+    }
+    return result;
+}
+function parseListQuery(raw) {
+    // 没有传筛选条件时，默认请求第一页，每页 20 条。
+    if (raw === undefined) {
+        return { page: 1, page_size: 20 };
+    }
+    // agent 一旦传了 list 参数，该参数就必须是非空 JSON object，否则属于命令用法错误。
+    if (!raw.trim()) {
+        throw usageError("List query must be valid JSON.", "Run ae list '{\"page\":1,\"page_size\":20}'.");
+    }
+    let value;
+    try {
+        // raw 必须是 JSON 字符串，例如 {"page":1,"page_size":20}。
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw usageError("List query must be valid JSON.", "Run ae list '{\"page\":1,\"page_size\":20}'.");
+    }
+    // list 参数必须是 object，不能是数组、字符串或数字。
+    if (!isRecord(value)) {
+        throw usageError("List query must be a JSON object.", "Run ae list '{\"page\":1,\"page_size\":20}'.");
+    }
+    const query = {};
+    for (const [key, fieldValue] of Object.entries(value)) {
+        // 为了避免复杂对象序列化歧义，只允许一层 string/number/boolean。
+        if (typeof fieldValue !== "string"
+            && typeof fieldValue !== "number"
+            && typeof fieldValue !== "boolean") {
+            throw usageError("List query only supports first-level scalar fields.", "Use string, number, or boolean values in ae list '<json>'.");
+        }
+        query[key] = fieldValue;
+    }
+    return query;
+}
+function isRecord(value) {
+    // TypeScript 里 object 也包含数组，所以这里显式排除 Array。
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/list.js.map

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

package/dist/commands/login.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runLogin(context: CommandContext): Promise<CommandSuccess>;

package/dist/commands/login.js

@@ -0,0 +1,96 @@
+/**
+ * `ae login` 命令实现。
+ *
+ * login 只负责第一次安装或用户主动换 key 时的本地初始化：
+ * 1. 从 `--api-key-stdin`、`--api-key`、`AGENT_EARTH_API_KEY` 或 TTY 隐藏输入读取 API key；
+ * 2. 调用 recommend 接口做一次轻量验证；
+ * 3. 验证成功后，把 key 写入本机 credentials.json。
+ * 4. 输出 npm 包内置 skill 的 source，让 agent 知道如何安装或引用使用说明。
+ *
+ * 注意：这里不生成普通 config，也不生成机器身份 ID。后续命令会自动读取
+ * credentials.json，agent 不需要每次自己携带 API key。
+ */
+import { fileURLToPath } from "node:url";
+import { CLI_VERSION, RECOMMEND_PATH } from "../constants.js";
+import { mapBackendError } from "../core/backendErrors.js";
+import { CliError, usageError } from "../core/errors.js";
+import { readHiddenInput } from "../core/hiddenInput.js";
+import { postJson } from "../core/http.js";
+import { resolveLoginApiKey, writeCredentials } from "../storage/credentials.js";
+// 编译后本文件位于 dist/commands/login.js，向上两级就是 npm 包根目录。
+// skill 文件不复制进 dist，而是作为 package files 中的独立资源发布。
+const SKILL_SOURCE = fileURLToPath(new URL("../../skills/agentearth/SKILL.md", import.meta.url));
+export async function runLogin(context) {
+    // login 不读旧 credentials，必须拿到本次传入的新 key。
+    const apiKey = await resolveLoginApiKeyForLogin(context);
+    // 复用 recommend 接口验证 key，避免为了 login 单独开发验证接口。
+    const response = await postJson(RECOMMEND_PATH, 
+    // 固定 query 和 limit=1 只是为了让验证请求足够轻量。
+    { query: "weather tool", limit: 1 }, {
+        apiKey,
+        baseUrl: context.options.baseUrl,
+        timeoutMs: context.options.timeoutMs
+    });
+    // 后端业务失败时，转换成 CLI 稳定错误码。
+    if (response.error_no !== 0) {
+        throw mapBackendError("login", response.error_msg);
+    }
+    try {
+        // 只有后端验证通过后才落盘，避免把明显错误的 key 保存起来。
+        await writeCredentials(apiKey);
+    }
+    catch {
+        // credentials 写失败是后端看不到的本地错误，需要用专门错误码。
+        throw new CliError("credentials_write_failed", "Failed to write local credentials.", "Check write permission for AgentEarth credentials directory.");
+    }
+    // 成功输出不包含 key，也不包含本地路径，只返回 agent/用户需要知道的信息。
+    return {
+        version: CLI_VERSION,
+        skill: {
+            required: true,
+            phase: 1,
+            source: SKILL_SOURCE,
+            message: "Install this skill into your agent before using AgentEarth CLI."
+        },
+        next: "Install the skill, then run ae list or ae recommend.",
+        message: "AgentEarth CLI login succeeded."
+    };
+}
+async function resolveLoginApiKeyForLogin(context) {
+    // --api-key 和 --api-key-stdin 不能同时使用，否则 key 来源不明确。
+    if (context.options.apiKey && context.options.apiKeyStdin) {
+        throw usageError("Use either --api-key or --api-key-stdin, not both.");
+    }
+    if (context.options.apiKeyStdin) {
+        // stdin 模式适合 agent/脚本：key 不会出现在 shell history 或进程参数里。
+        const apiKey = (await readStdin()).trim();
+        if (!apiKey) {
+            throw new CliError("auth_missing", "No API key provided on stdin.", "Pipe the API key into ae login --api-key-stdin.");
+        }
+        return apiKey;
+    }
+    try {
+        // 非 stdin 模式优先沿用原有来源：--api-key 或 AGENT_EARTH_API_KEY。
+        return resolveLoginApiKey(context.options);
+    }
+    catch (error) {
+        // 如果没有任何显式 key 来源，人工 TTY 场景进入隐藏输入；非 TTY 会继续返回 auth_missing。
+        if (error instanceof CliError && error.code === "auth_missing") {
+            const apiKey = (await readHiddenInput("AgentEarth API key: ")).trim();
+            if (!apiKey) {
+                throw new CliError("auth_missing", "No API key provided.", "Pipe the API key into ae login --api-key-stdin.");
+            }
+            return apiKey;
+        }
+        throw error;
+    }
+}
+async function readStdin() {
+    // stdin 是流，可能分多块到达，所以先收集所有 chunk。
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/login.js.map

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

package/dist/commands/recommend.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runRecommend(context: CommandContext, args: string[]): Promise<CommandSuccess>;

package/dist/commands/recommend.js

@@ -0,0 +1,58 @@
+/**
+ * `ae recommend` 命令实现。
+ *
+ * recommend 是“不明确工具类别”时的入口。agent 把用户任务原文传给 CLI，
+ * CLI 请求后端推荐工具。后端返回的 tool_url 中带有全局唯一 tool_name，
+ * CLI 会解析 tool_name 并把完整 tool_url 缓存在本地，最终只把 tool_name
+ * 和工具摘要输出给 agent。
+ */
+import { RECOMMEND_PATH } from "../constants.js";
+import { mapBackendError } from "../core/backendErrors.js";
+import { CliError, usageError } from "../core/errors.js";
+import { postJson } from "../core/http.js";
+import { resolveApiKey } from "../storage/credentials.js";
+import { writeSession } from "../storage/session.js";
+import { readUpdateHint } from "./updateHint.js";
+export async function runRecommend(context, args) {
+    // recommend 的 query 允许由多个位置参数组成，例如 ae recommend weather in Beijing。
+    const query = args.join(" ").trim();
+    // 没有 query 时，后端无法推荐工具，直接返回用法错误。
+    if (!query) {
+        throw usageError("Missing recommend query.", "Run ae recommend \"weather in Beijing\".");
+    }
+    // 业务命令读取 key 的顺序是 --api-key -> 环境变量 -> credentials.json。
+    const apiKey = await resolveApiKey(context.options);
+    // 调用真实 recommend API。当前主流程不让 agent 指定 limit。
+    const response = await postJson(RECOMMEND_PATH, { query }, {
+        apiKey,
+        baseUrl: context.options.baseUrl,
+        timeoutMs: context.options.timeoutMs
+    });
+    // error_no 非 0 表示后端业务失败，需要映射成稳定 CLI 错误。
+    if (response.error_no !== 0) {
+        throw mapBackendError("recommend", response.error_msg);
+    }
+    // error_no=0 只能说明业务成功，CLI 仍要校验响应结构，避免坏响应被当成空推荐结果。
+    if (!Array.isArray(response.tools)) {
+        throw new CliError("backend_response_invalid", "Recommend response is missing tools array.", "Retry later.");
+    }
+    // 本地缓存保存完整 tool_url/input_schema；输出给 agent 时不暴露 tool_url。
+    const cachedTools = await writeSession(response.tools);
+    // agent 只需要 tool_name 和选择信息；后续 detail/execute 都用 tool_name。
+    const result = {
+        // total 是后端返回的匹配总量；缺失时才用本次缓存工具数兜底。
+        total: response.total ?? cachedTools.length,
+        tools: cachedTools.map((tool) => ({
+            tool_name: tool.tool_name,
+            description: tool.description,
+            when_to_use: tool.when_to_use,
+            credit: tool.credit
+        }))
+    };
+    const update = await readUpdateHint();
+    if (update) {
+        result.update = update;
+    }
+    return result;
+}
+//# sourceMappingURL=recommend.js.map

package/dist/commands/recommend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend.js","sourceRoot":"","sources":["../../src/commands/recommend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuB,EAAE,IAAc;IACxE,oEAAoE;IACpE,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEpC,gCAAgC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,UAAU,CAAC,0BAA0B,EAAE,0CAA0C,CAAC,CAAC;IAC3F,CAAC;IAED,yDAAyD;IACzD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpD,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAC7B,cAAc,EACd,EAAE,KAAK,EAAE,EACT;QACE,MAAM;QACN,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO;QAChC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS;KACrC,CACF,CAAC;IAEF,wCAAwC;IACxC,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,eAAe,CAAC,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACzD,CAAC;IAED,kDAAkD;IAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,4CAA4C,EAAE,cAAc,CAAC,CAAC;IAC/G,CAAC;IAED,0DAA0D;IAC1D,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEvD,4DAA4D;IAC5D,MAAM,MAAM,GAAmB;QAC7B,mCAAmC;QACnC,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,WAAW,CAAC,MAAM;QAC3C,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChC,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;KACJ,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;IACtC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext, CommandSuccess } from "../types/cli.js";
+export declare function runUpdate(context: CommandContext): Promise<CommandSuccess>;