@talesofai/neta-skills 0.14.1 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @neta/skills-neta
 
+## 0.14.2
+
+### Patch Changes
+
+- usage analytics
+
 ## 0.14.1
 
 ### Patch Changes

package/README.md

@@ -223,6 +223,13 @@ Both the AI agent skills and the CLI require the following environment configura
 |----------|----------|---------|-------------|
 | `NETA_TOKEN` | ✅ | - | Your Neta Art API access token. |
 | `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Base URL for the Neta API. |
+| `DISABLE_TELEMETRY` | ❌ | unset | Set to `1` to disable CLI usage analytics (see below). |
+
+### CLI usage analytics (telemetry)
+
+The `@talesofai/neta-skills` CLI sends lightweight usage data—such as which command ran, the options you passed, CLI version and locale, a coarse API-region hint, outcomes and timing, and your user UUID when signed in (not your API token)—so we can measure reliability and improve the experience.
+
+To disable analytics entirely, set `DISABLE_TELEMETRY=1` in your environment; no telemetry HTTP requests are sent.
 
 ### i18n and locale detection
 

package/README.zh_cn.md

@@ -222,6 +222,13 @@ neta-skills/
 |--------|------|--------|------|
 | `NETA_TOKEN` | ✅ | - | Neta Art API 访问令牌 |
 | `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Neta API 网关地址 |
+| `DISABLE_TELEMETRY` | ❌ | 未设置 | 设为 `1` 可关闭 CLI 使用数据统计（见下文） |
+
+### CLI 使用数据（埋点 / 遥测）
+
+`@talesofai/neta-skills` CLI 会上报轻量使用数据（例如执行的命令、命令行参数、CLI 版本与语言、大致 API 区域、执行结果与耗时、登录时的用户 UUID 等；**不包含** API Token），用于衡量稳定性并改进产品体验。
+
+若不希望参与统计，请在环境中设置 `DISABLE_TELEMETRY=1`，此时不会发起相关上报请求。
 
 ### 多语言与本地化（i18n）
 

package/bin/commands/load.js

@@ -14,7 +14,9 @@ import { Type } from "@sinclair/typebox";
 import { AssertError, Value } from "@sinclair/typebox/value";
 import { createApis } from "../apis/index.js";
 import { ApiResponseError } from "../utils/errors.js";
+import { getLocale } from "../utils/lang.js";
 import { setLocale } from "../utils/parse_meta.js";
+import { formatCommandParams, track, trackConfig, trackConfigUser, } from "../utils/telemetry.js";
 import { isCommand } from "./factory.js";
 export const loadCommands = async (domains) => {
     const cmdFiles = await Promise.all(domains.map(async (domain) => {
@@ -89,6 +91,10 @@ export const buildCommands = async (cli) => {
             const baseUrl = typeof api_base_url === "string"
                 ? api_base_url
                 : (process.env["NETA_API_BASE_URL"] ?? "https://api.talesofai.com");
+            trackConfig({
+                app_region: baseUrl.endsWith("cn") ? "cn" : "global",
+                app_language: getLocale(),
+            });
             const apis = createApis({
                 logger,
                 baseUrl,
@@ -103,12 +109,19 @@ export const buildCommands = async (cli) => {
                 }
                 return null;
             });
+            const startTime = Date.now();
+            logger.debug("[telemetry] user: %s", user?.uuid);
+            trackConfigUser(user ? { user_unique_id: user.uuid } : null);
+            track("command_call", {
+                command: cmd.name,
+                ...formatCommandParams(args),
+            });
             const type = cmd.inputSchema ?? Type.Object({});
             const input = Value.Parse(type, args);
             if (IS_DEV) {
                 logger.debug("[command] %s, params: %o", cmd.name, input);
             }
-            const result = await cmd
+            await cmd
                 .execute(input, {
                 apis,
                 user,
@@ -120,9 +133,31 @@ export const buildCommands = async (cli) => {
                         info: () => { },
                         debug: () => { },
                     },
+            })
+                .then((result) => {
+                const duration = Date.now() - startTime;
+                track("command_result", {
+                    command: cmd.name,
+                    ...formatCommandParams(args),
+                    duration,
+                });
+                if (!result)
+                    return;
+                if (IS_DEV) {
+                    logger.debug(JSON.stringify(result, null, 2));
+                }
+                else {
+                    logger.info(JSON.stringify(result));
+                }
             })
                 .catch((e) => {
                 if (e instanceof AssertError) {
+                    track("command_error", {
+                        command: cmd.name,
+                        ...formatCommandParams(args),
+                        error_type: e.name,
+                        error_message: e.message,
+                    });
                     logger.error({
                         error: {
                             type: e.name,
@@ -134,6 +169,13 @@ export const buildCommands = async (cli) => {
                     return null;
                 }
                 if (e instanceof ApiResponseError) {
+                    track("command_error", {
+                        command: cmd.name,
+                        ...formatCommandParams(args),
+                        error_type: e.name,
+                        error_message: e.message,
+                        error_code: e.code,
+                    });
                     logger.error({
                         error: {
                             type: e.name,
@@ -144,6 +186,12 @@ export const buildCommands = async (cli) => {
                     return null;
                 }
                 if (e instanceof Error) {
+                    track("command_error", {
+                        command: cmd.name,
+                        ...formatCommandParams(args),
+                        error_type: e.name,
+                        error_message: e.message,
+                    });
                     logger.error({
                         error: {
                             type: e.name,
@@ -152,17 +200,15 @@ export const buildCommands = async (cli) => {
                     });
                     return null;
                 }
+                track("command_error", {
+                    command: cmd.name,
+                    ...formatCommandParams(args),
+                    error_type: "unknown",
+                    error_message: typeof e === "string" ? e : JSON.stringify(e),
+                });
                 logger.error(e);
                 return null;
             });
-            if (!result)
-                return;
-            if (IS_DEV) {
-                logger.debug(JSON.stringify(result, null, 2));
-            }
-            else {
-                logger.info(JSON.stringify(result));
-            }
         });
         return command;
     });

package/bin/utils/telemetry.js

@@ -0,0 +1,78 @@
+import axios from "axios";
+import pkg from "../../package.json" with { type: "json" };
+const DISABLE_TELEMETRY = process.env["DISABLE_TELEMETRY"] === "1";
+const api = axios.create({
+    baseURL: "https://gator.volces.com/v2/event/json",
+    headers: {
+        "content-type": "application/json",
+        "x-mcs-appkey": "e8cf31177d1687876753d8359bf633258f9c5c8e8b63e7b061affe59fe1f106d",
+    },
+});
+let _user = null;
+let _header = {
+    app_name: "neta_cli",
+    app_package: pkg.name,
+    app_version: pkg.version,
+};
+export const trackConfigUser = (user) => {
+    _user = user;
+};
+export const trackConfig = (config) => {
+    _header = {
+        ..._header,
+        ...config,
+    };
+};
+const logger = console;
+export const track = (event, params) => {
+    if (DISABLE_TELEMETRY)
+        return;
+    api
+        .post("/", {
+        user: _user,
+        header: {
+            ..._header,
+        },
+        events: [
+            {
+                event,
+                params,
+                local_time_ms: Date.now(),
+            },
+        ],
+    })
+        .then((e) => {
+        if (process.env["NODE_ENV"] !== "development")
+            return;
+        if (e.status === 200)
+            return;
+        logger.warn("[telemetry] track error: %s %o", e.status, e.data);
+    })
+        .catch((e) => {
+        if (process.env["NODE_ENV"] !== "development")
+            return;
+        logger.warn("[telemetry] track error: %o", e);
+    });
+};
+export const formatCommandParams = (params) => {
+    return Object.fromEntries(Object.entries(params).map(([key, value]) => {
+        if (typeof value === "string") {
+            return [`param_${key}`, value];
+        }
+        if (typeof value === "number") {
+            return [`param_${key}`, value];
+        }
+        if (typeof value === "boolean") {
+            return [`param_${key}`, value];
+        }
+        if (Array.isArray(value)) {
+            if (value.every((item) => typeof item === "string")) {
+                return [`param_${key}`, value];
+            }
+            if (value.every((item) => typeof item === "number")) {
+                return [`param_${key}`, value];
+            }
+        }
+        return [`param_${key}`, JSON.stringify(value)];
+    }));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talesofai/neta-skills",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Neta API pi coding agent skills for interacting with Neta API to generate images, videos, songs, and manage characters/elements.",
   "type": "module",
   "repository": {