@agentearth.ai/cli 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/storage/telemetryUploadState.js

@@ -1,7 +1,15 @@
+/**
+ * 埋点上传暂停状态模块。
+ *
+ * telemetry uploader 遇到 401、429、5xx、网络错误或超时时，不应该每次命令结束都立刻重试。
+ * 本文件把“暂停到什么时候、为什么暂停、对应哪个 API key”写入本地状态文件。
+ * 注意这里永远不保存完整 API key，只保存短 hash 指纹，用来判断用户是否已经换了 key。
+ */
 import { createHash } from "node:crypto";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { ensureAgentEarthDir, getTelemetryUploadStatePath } from "./paths.js";
 export async function readTelemetryUploadState() {
+    // 读取失败、文件不存在或结构损坏都返回 null；埋点状态不能影响主命令。
     try {
         const raw = await readFile(getTelemetryUploadStatePath(), "utf8");
         return normalizeTelemetryUploadState(JSON.parse(raw));
@@ -11,6 +19,7 @@ export async function readTelemetryUploadState() {
     }
 }
 export async function writeTelemetryUploadState(state) {
+    // 写状态前确保 AgentEarth 本地数据目录存在。
     await ensureAgentEarthDir();
     await writeFile(getTelemetryUploadStatePath(), `${JSON.stringify(state, null, 2)}\n`, {
         encoding: "utf8",
@@ -18,6 +27,7 @@ export async function writeTelemetryUploadState(state) {
     });
 }
 export async function clearTelemetryUploadState() {
+    // 上传成功或 key 变化后清掉暂停状态，让后续命令可以继续正常冲刷队列。
     try {
         await unlink(getTelemetryUploadStatePath());
     }
@@ -26,13 +36,17 @@ export async function clearTelemetryUploadState() {
     }
 }
 export function createApiKeyFingerprint(apiKey) {
+    // sha256 是单向 hash；slice(0, 16) 足够做本地变化判断，又避免保存完整 key。
     return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
 export function isTelemetryUploadPaused(state, now = new Date()) {
+    // suspended_until 解析失败时不暂停，避免坏状态文件让上传永久停住。
     const suspendedUntil = Date.parse(state.suspended_until);
     return Number.isFinite(suspendedUntil) && suspendedUntil > now.getTime();
 }
+// uploader 根据 HTTP 分类结果调用这里生成下一次暂停状态。
 export function createTelemetryUploadState(reason, delayMs, apiKeyFingerprint, previousState, now = new Date()) {
+    // delayMs 小于 0 时按 0 处理，避免写出过去时间。
     return {
         suspended_until: new Date(now.getTime() + Math.max(0, delayMs)).toISOString(),
         reason,
@@ -41,6 +55,7 @@ export function createTelemetryUploadState(reason, delayMs, apiKeyFingerprint, p
     };
 }
 function normalizeTelemetryUploadState(value) {
+    // 本地文件可被用户手动修改，所以每个字段都要运行时校验。
     if (!isRecord(value)) {
         return null;
     }
@@ -63,6 +78,7 @@ function normalizeTelemetryUploadState(value) {
     };
 }
 function isRecord(value) {
+    // JavaScript 里数组也是 object；这里排除数组，确保后面能按字段名读取。
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //# sourceMappingURL=telemetryUploadState.js.map

package/dist/storage/telemetryUploadState.js.map

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

package/dist/storage/updateCache.js

@@ -2,8 +2,8 @@
  * 更新检查缓存模块。
  *
  * list/recommend 会读取这个文件展示 fresh 更新提示。
- * 缓存失效时，CLI 通过 npm view 查询 npm registry，并把检查结果写回这里，
- * 避免每次工具发现都请求 registry。
+ * 缓存失效时，工具发现命令不主动刷新；ae update 会通过 npm view 查询
+ * npm registry，并把检查结果写回这里，避免工具发现链路请求 registry。
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { pathExists, protectSensitiveFile } from "./fileProtection.js";

package/dist/telemetry/uploader.js

@@ -1,28 +1,46 @@
+/**
+ * CLI 埋点上传器。
+ *
+ * main.ts 每次命令结束后都会调用 flushTelemetry。它会读取本地 events.jsonl 队列，
+ * 尝试把一批事件 POST 到日志接口。上传失败不能影响主命令，所以本模块内部会吞掉异常，
+ * 并根据 HTTP 分类决定保留队列、删除坏批次、拆小批次或写入暂停状态。
+ */
 import { TELEMETRY_PATH } from "../constants.js";
 import { postTelemetryJson } from "../core/http.js";
 import { resolveApiKey } from "../storage/credentials.js";
 import { dropTelemetryQueueHead, readTelemetryQueueBatch } from "../storage/telemetryQueue.js";
 import { clearTelemetryUploadState, createApiKeyFingerprint, createTelemetryUploadState, isTelemetryUploadPaused, readTelemetryUploadState, writeTelemetryUploadState } from "../storage/telemetryUploadState.js";
+// 默认每次最多上传 20 条，避免单次请求体过大。
 const DEFAULT_BATCH_SIZE = 20;
+// API key 失败通常需要用户重新登录，不要每次命令都刷同一批 401。
 const AUTH_PAUSE_MS = 24 * 60 * 60 * 1000;
+// 当前后端不设计专门 429，但如果网关返回，CLI 仍按短退避处理。
 const RATE_LIMIT_PAUSE_MS = 5 * 60 * 1000;
+// 5xx、网络失败、超时属于临时失败，保留队列并稍后再试。
 const TEMPORARY_FAILURE_PAUSE_MS = 60 * 1000;
 export async function flushTelemetry(options) {
+    // 用户显式关闭埋点时，本轮既不读队列也不上传。
     if (options.noTelemetry) {
         return;
     }
     try {
+        // 上传接口也需要 X-Api-Key；如果本地没有 key，resolveApiKey 会抛错并被外层吞掉。
         const apiKey = await resolveApiKey(options);
+        // 只保存 hash 指纹到暂停状态，避免把真实 key 写入 telemetry-upload-state.json。
         const apiKeyFingerprint = createApiKeyFingerprint(apiKey);
+        // existingState 记录上一次失败后的暂停窗口和原因。
         const existingState = await readTelemetryUploadState();
         if (await shouldSkipUpload(existingState, apiKeyFingerprint)) {
             return;
         }
+        // batchLimit 可能因为 413 被逐步减半，所以用 while 而不是固定读取一次。
         let batchLimit = DEFAULT_BATCH_SIZE;
         while (batchLimit >= 1) {
+            // 每轮都重新读队头，因为上一轮可能已经删除了成功/坏数据。
             const batch = await readTelemetryQueueBatch(batchLimit);
             const events = batch.events;
             if (events.length === 0) {
+                // 没有有效事件但消费过坏行时，说明队头是损坏数据，直接清理掉。
                 if (batch.consumedLineCount > 0) {
                     await dropTelemetryQueueHead(batch.consumedLineCount);
                 }
@@ -30,24 +48,30 @@ export async function flushTelemetry(options) {
             }
             const result = await postTelemetryJson(TELEMETRY_PATH, { events }, {
                 apiKey,
+                // 日志上传可以和业务接口使用不同 host；未配置时才回退到业务 baseUrl。
                 baseUrl: options.telemetryBaseUrl || options.baseUrl,
                 timeoutMs: options.timeoutMs
             });
             if (result.kind === "success") {
+                // 后端确认接收后才能删除队头；同时清掉历史暂停状态。
                 await dropTelemetryQueueHead(batch.consumedLineCount);
                 await clearTelemetryUploadState();
                 return;
             }
             if (result.kind === "permanent_failure") {
+                // 400/415 等永久错误说明这批数据结构不被接受，继续重试只会卡住队列。
                 await dropTelemetryQueueHead(batch.consumedLineCount);
                 return;
             }
             if (result.kind === "auth_failed") {
+                // 鉴权失败不删除队列；等用户换 key 后可以继续上传旧事件。
                 await pauseUpload("auth_failed", AUTH_PAUSE_MS, apiKeyFingerprint, existingState);
                 return;
             }
             if (result.kind === "payload_too_large") {
+                // 413 时先拆小批次；如果单条都太大，只能丢弃该事件避免永久卡队头。
                 if (events.length > 1) {
+                    // 减半后 continue 回 while 顶部，重新按更小 batchLimit 读取同一个队头。
                     batchLimit = Math.max(1, Math.floor(events.length / 2));
                     continue;
                 }
@@ -55,34 +79,42 @@ export async function flushTelemetry(options) {
                 return;
             }
             if (result.kind === "rate_limited") {
+                // 如果后端或网关给 Retry-After，就优先使用服务端建议的暂停时长。
                 await pauseUpload("rate_limited", result.retryAfterMs ?? RATE_LIMIT_PAUSE_MS, apiKeyFingerprint, existingState);
                 return;
             }
+            // 剩下的 network_error、timeout、server_error 都属于临时失败：保留队列并短暂停。
             await pauseUpload("temporary_failure", TEMPORARY_FAILURE_PAUSE_MS, apiKeyFingerprint, existingState);
             return;
         }
     }
     catch {
-        // Telemetry is best-effort and must never change command output or exit code.
+        // 这里故意不再抛出：埋点只是辅助数据，不能改变 ae 命令本身的输出和退出码。
     }
 }
+// 根据暂停状态判断本轮是否应该跳过上传。
 async function shouldSkipUpload(state, apiKeyFingerprint) {
     if (!state) {
         return false;
     }
     if (!isTelemetryUploadPaused(state)) {
+        // 暂停时间过期后清理状态，让本轮继续上传。
         await clearTelemetryUploadState();
         return false;
     }
     if (state.reason !== "auth_failed") {
+        // 非鉴权类暂停只看时间窗口，没到期就跳过。
         return true;
     }
     if (state.api_key_fingerprint === apiKeyFingerprint) {
+        // 同一个 key 已经失败过，继续重试没有意义。
         return true;
     }
+    // key 指纹变了，说明用户可能重新 login，本轮允许恢复上传。
     await clearTelemetryUploadState();
     return false;
 }
+// 统一写入暂停状态，避免各分支重复计算 suspended_until/retry_count。
 async function pauseUpload(reason, delayMs, apiKeyFingerprint, previousState) {
     await writeTelemetryUploadState(createTelemetryUploadState(reason, delayMs, apiKeyFingerprint, previousState));
 }

package/dist/telemetry/uploader.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentearth.ai/cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Agent-first CLI that helps AI agents discover, inspect, and execute AgentEarth tools from any shell.",
   "type": "module",
   "bin": {

package/skills/agentearth/SKILL.md

@@ -1,30 +1,92 @@
-# AgentEarth CLI Skill
+---
+name: agentearth
+description: >-
+  Discover, inspect, and execute AgentEarth marketplace tools through the AgentEarth CLI.
+  Use when the user explicitly asks to use AgentEarth/agentearth, asks for AgentEarth tools,
+  or needs an external tool workflow such as live data retrieval, structured web/API results,
+  document or media conversion, translation, calculations, image/video generation,
+  presentation editing, or other tool-backed services. Follow host approval, credential,
+  network, and safety policies before invoking external commands.
 
-Use AgentEarth CLI when the user asks you to discover, inspect, or execute AgentEarth tools.
+requirements:
+  env:
+    - AGENTEARTH_API_KEY
 
-## Commands
+credentials:
+  type: api_key
+  env: AGENTEARTH_API_KEY
+  injection: environment
+  required: true
+---
 
-- Use `ae list` when the user task clearly belongs to a known tool category, such as image generation, video generation, or PPT editing.
-- For filtered list queries, write the query JSON to `query.json` and run `ae list @query.json`; do not hand-write inline JSON in PowerShell.
-- Use `ae recommend "<query>"` when the user task is ambiguous and you are not sure which tool category should be used.
-- Use `ae detail <tool_name>` before execution to read the tool input schema.
-- Use `ae execute <tool_name> @params.json` to execute the selected tool.
-- Use `ae update` only after the user confirms they want to update the CLI.
+# AgentEarth
 
-## Rules
+Use AgentEarth as an external tool marketplace. Treat the user's request as the task to solve, then discover the best matching tool, inspect its schema, validate parameters, execute it, and summarize the result.
 
-- All agent-facing commands output JSON by default.
-- Select tools by `tool_name`.
-- Do not use `tool_url` as an argument.
-- Do not call the removed `ae schema` command.
-- Do not pass API keys to normal tool commands; `ae login` stores credentials for later use.
-- If login is required, read the API key only from the caller-provided `AGENTEARTH_API_KEY` environment variable and pipe it to `ae login --api-key-stdin`; do not search the filesystem for API keys.
+## Command Surface
 
-## Typical Flows
+Prefer `ae` on Unix-like shells and `ae.cmd` in Windows PowerShell when the PowerShell shim is blocked by execution policy.
 
-Known category:
+Use these commands:
 
-Create `query.json`:
+- `ae recommend "<task>"` to discover tools for ambiguous or natural-language tasks.
+- `ae list @query.json` to list tools for a known category or keyword.
+- `ae detail <tool_name>` to inspect a selected tool's schema before execution.
+- `ae execute <tool_name> @params.json` to run the selected tool with validated parameters.
+- `ae update` only when the user confirms they want to update the CLI.
+
+All agent-facing commands return JSON by default. Select tools by `tool_name`; never use `tool_url` as a CLI argument. Do not call removed or undocumented commands such as `ae schema`.
+
+## Credential Handling
+
+Use credentials only through the active host environment.
+
+- Read the API key from `AGENTEARTH_API_KEY` when the host provides it.
+- If login is required, pipe the caller-provided key to `ae login --api-key-stdin`.
+- Never ask the user to paste a key unless the host explicitly requires manual credential setup.
+- Never search the filesystem, shell history, logs, or config files for API keys.
+- Never print, log, echo, or include secrets in generated files.
+
+If authentication fails, report that AgentEarth authentication failed and ask the user to verify the configured API key or login state. Do not expose request headers or secret values.
+
+## Execution Workflow
+
+1. Restate the task internally as a concise AgentEarth query.
+2. Discover candidate tools with `ae recommend "<task>"`, or `ae list @query.json` when the category is already clear.
+3. Inspect the best candidate with `ae detail <tool_name>`.
+4. Build `params.json` strictly from the inspected input schema.
+5. Validate required fields, types, enums, formats, and `additionalProperties` when present.
+6. Execute with `ae execute <tool_name> @params.json`.
+7. Summarize the useful result for the user and omit internal command noise unless it is needed for troubleshooting.
+
+Use a fallback tool only when the first suitable tool fails for a recoverable reason or clearly does not satisfy the task.
+
+## Tool Selection
+
+Choose the tool that best matches the task intent and can be safely executed with available context.
+
+Prefer candidates with:
+
+- clear task relevance;
+- complete and understandable input schema;
+- required parameters that can be filled from the user's request or conversation context;
+- lower cost when otherwise equivalent;
+- narrower, more specialized behavior for the requested job.
+
+If no candidate is suitable, refine the query once. If discovery still fails, tell the user that AgentEarth did not return a suitable tool.
+
+## Parameter Rules
+
+Build parameter files as JSON objects matching the selected tool schema.
+
+- Use only values from the user's request, conversation context, or deterministic transformations of those values.
+- Do not invent required values such as URLs, IDs, tokens, locations, dates, file paths, or account-specific inputs.
+- Ask a concise clarification question when a required value is missing.
+- Remove keys not defined by the schema when `additionalProperties` is `false`.
+- Do not reuse example keys unless they exist in the selected schema.
+- Write query or execution payloads to JSON files instead of hand-writing inline JSON in PowerShell.
+
+Known-category list example:
 
 ```json
 {"keyword":"image"}
@@ -36,10 +98,29 @@ ae detail <tool_name>
 ae execute <tool_name> @params.json
 ```
 
-Ambiguous task:
+Ambiguous-task example:
 
 ```text
-ae recommend "<user task>"
+ae recommend "find current hotel prices in Sapporo for next weekend"
 ae detail <tool_name>
 ae execute <tool_name> @params.json
 ```
+
+## Error Handling
+
+On command or tool failure:
+
+- Read the JSON error message before retrying.
+- Retry once only when the failure is likely transient or caused by a fixable parameter issue.
+- Correct parameters only when the correction is supported by the schema and available context.
+- Try a fallback candidate only when it is clearly relevant to the original task.
+- Stop and explain the failure when the error is authentication, authorization, missing user input, unsupported task, or repeated tool failure.
+
+## Result Presentation
+
+Return the final answer, not a transcript of internal discovery.
+
+- Summarize key facts, generated asset links, converted file paths, or tool outputs.
+- Include caveats from the tool result when relevant.
+- Mention AgentEarth only when useful for provenance or when troubleshooting is needed.
+- Do not expose raw credentials, internal request headers, or irrelevant JSON fields.