@talesofai/neta-skills 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @neta/skills-neta
 
+## 0.14.2
+
+### Patch Changes
+
+- usage analytics
+
+## 0.14.1
+
+### Patch Changes
+
+- - Add api logs for debug.
+  - Add api timeout with 10000ms.
+
+  - Fixed error info about remove_background input_image param in docs.
+
 ## 0.14.0
 
 ### Minor 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/apis/index.js

@@ -1,5 +1,5 @@
-import axios from "axios";
-import { handleAxiosError } from "../utils/errors.js";
+import axios, { AxiosError } from "axios";
+import { catchErrorResponse, handleAxiosError } from "../utils/errors.js";
 import { createActivityApis } from "./activity.js";
 import { createArtifactApis } from "./artifact.js";
 import { createAudioApis } from "./audio.js";
@@ -19,14 +19,31 @@ import { createUserApis } from "./user.js";
 import { createVerseApis } from "./verse.js";
 export const createApis = (option) => {
     const baseUrl = option.baseUrl;
+    const logger = option.logger;
     const client = axios.create({
         adapter: "fetch",
         baseURL: baseUrl,
         headers: {
             ...option.headers,
         },
+        timeout: 10 * 1000,
     });
-    client.interceptors.response.use((response) => response, (error) => {
+    client.interceptors.request.use((config) => {
+        const now = Date.now();
+        config.start_time = now;
+        logger.debug("[api] request: %s %s", config.method, config.url);
+        return config;
+    });
+    client.interceptors.response.use((response) => {
+        const now = Date.now();
+        const startTime = response.config.start_time ?? now;
+        const duration = now - startTime;
+        logger.debug("[api] response: %s %s %s %dms", response.config.method, response.status, response.config.url, duration);
+        return response;
+    }, (error) => {
+        if (error instanceof AxiosError) {
+            logger.debug("[api] response error: %s %s %s %s", error.request?.method, error.request?.url, error.response?.status, catchErrorResponse(error.response?.data));
+        }
         handleAxiosError(error);
     });
     const tcp = createTcpApis(client);

package/bin/commands/character_elementum/list_my_characters.cmd.js

@@ -16,9 +16,8 @@ export const listMyCharacters = createCommand({
     title: meta.title,
     description: meta.description,
     inputSchema: listMyCharactersParameters,
-}, async ({ keyword, page_index, page_size }, { apis }) => {
+}, async ({ keyword, page_index, page_size }, { apis, user }) => {
     // Get current user info to obtain UUID
-    const user = await apis.user.me();
     if (!user) {
         throw new Error("Failed to get user info. Please check your NETA_TOKEN.");
     }

package/bin/commands/character_elementum/list_my_elementum.cmd.js

@@ -16,9 +16,8 @@ export const listMyElementum = createCommand({
     title: meta.title,
     description: meta.description,
     inputSchema: listMyElementumParameters,
-}, async ({ keyword, page_index, page_size }, { apis }) => {
+}, async ({ keyword, page_index, page_size }, { apis, user }) => {
     // Get current user info to obtain UUID
-    const user = await apis.user.me();
     if (!user) {
         throw new Error("Failed to get user info. Please check your NETA_TOKEN.");
     }

package/bin/commands/creative/remove_background.cmd.en_us.yml

@@ -2,6 +2,8 @@ remove_background:
   name: remove_background
   title: Remove Image Background
   description: Remove the background of an input image while preserving the main subject, and return an image with a transparent background.
+  parameters:
+    input_image: The UUID of the input image artifact.
 
 remove_background_nocrop:
   name: remove_background_nocrop

package/bin/commands/creative/remove_background.cmd.js

@@ -7,6 +7,9 @@ const meta = parseMeta(Type.Object({
         name: Type.String(),
         title: Type.String(),
         description: Type.String(),
+        parameters: Type.Object({
+            input_image: Type.String(),
+        }),
     }),
     remove_background_nocrop: Type.Object({
         name: Type.String(),
@@ -15,7 +18,9 @@ const meta = parseMeta(Type.Object({
     }),
 }), import.meta);
 const removeBackgroundV1Parameters = Type.Object({
-    input_image: Type.String(),
+    input_image: Type.String({
+        description: meta.remove_background.parameters.input_image,
+    }),
 });
 export const removeBackground = createCommand({
     name: meta.remove_background.name,
@@ -24,6 +29,13 @@ export const removeBackground = createCommand({
     inputSchema: removeBackgroundV1Parameters,
 }, async ({ input_image }, { apis, log }) => {
     const createTask = async () => {
+        const artifacts = await apis.artifact.artifactDetail([input_image]);
+        if (!artifacts ||
+            !artifacts[0] ||
+            artifacts[0].modality !== "PICTURE" ||
+            artifacts[0].status !== "SUCCESS") {
+            throw new Error("Input is not a valid picture artifact UUID");
+        }
         return apis.artifact.postProcess(input_image, "0_null/抠图SEG", {
             entrance: "PICTURE,CLI",
         });
@@ -52,6 +64,13 @@ export const removeBackgroundNoCrop = createCommand({
     inputSchema: removeBackgroundV1Parameters,
 }, async ({ input_image }, { apis, log }) => {
     const createTask = async () => {
+        const artifacts = await apis.artifact.artifactDetail([input_image]);
+        if (!artifacts ||
+            !artifacts[0] ||
+            artifacts[0].modality !== "PICTURE" ||
+            artifacts[0].status !== "SUCCESS") {
+            throw new Error("Input is not a valid picture artifact UUID");
+        }
         return apis.artifact.postProcess(input_image, "0_null/抠图SEG", {
             entrance: "PICTURE,CLI",
         });

package/bin/commands/creative/remove_background.cmd.zh_cn.yml

@@ -2,6 +2,8 @@ remove_background:
   name: remove_background
   title: 去除图片背景
   description: 输入图片保留主体去除背景，返回透明通道图片
+  parameters:
+    input_image: 输入图片的 artifact UUID。
 
 remove_background_nocrop:
   name: remove_background_nocrop

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,7 +91,12 @@ 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,
                 headers: {
                     "x-token": process.env["NETA_TOKEN"] ?? "",
@@ -102,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);
+                logger.debug("[command] %s, params: %o", cmd.name, input);
             }
-            const result = await cmd
+            await cmd
                 .execute(input, {
                 apis,
                 user,
@@ -119,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,
@@ -133,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,
@@ -143,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,
@@ -151,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/commands/premium/get_current_premium_plan.cmd.js

@@ -17,11 +17,13 @@ export const getCurrentPremiumPlan = createCommand({
     name: meta.name,
     title: meta.title,
     description: meta.description,
-}, async (_, { apis }) => {
+}, async (_, { apis, user }) => {
     if (!apis.baseUrl.endsWith("talesofai.com")) {
         throw new Error("This command is not supported in the current region");
     }
-    const user = await apis.user.me();
+    if (!user) {
+        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+    }
     const level = user.properties?.vip_level ?? 0;
     return {
         plan: PlanningMap[level],

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.0",
+  "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": {

package/skills/neta-creative/SKILL.md

@@ -52,7 +52,7 @@ Combine an audio track and video to create a full MV.
 **Remove background**
 
 ```bash
-npx -y @talesofai/neta-skills@latest remove_background --input_image "image_url"
+npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 
 ### Character queries

package/skills/neta-creative/references/image-generation.md

@@ -124,7 +124,7 @@ npx -y @talesofai/neta-skills@latest make_image --prompt "@character_name, shy e
 ### Background Removal
 
 ```bash
-npx -y @talesofai/neta-skills@latest remove_background --input_image "image_uuid"
+npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 ---
 

package/skills/zh_cn/neta-creative/SKILL.md

@@ -44,7 +44,7 @@ npx -y @talesofai/neta-skills@latest make_song --prompt "风格描述" --lyrics
 
 **移除背景**
 ```bash
-npx -y @talesofai/neta-skills@latest remove_background --input_image "image_url"
+npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 
 ### 角色查询

package/skills/zh_cn/neta-creative/references/image-generation.md

@@ -124,7 +124,7 @@ npx -y @talesofai/neta-skills@latest make_image --prompt "@角色名，害羞表
 ### 去背景（抠图）
 
 ```bash
-npx -y @talesofai/neta-skills@latest remove_background --input_image "image_uuid"
+npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 ---