@talesofai/neta-skills 0.6.0

package/bin/commands/load.js

@@ -0,0 +1,157 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Option, } from "@commander-js/extra-typings";
+import { Type } from "@sinclair/typebox";
+import { Default, Value } from "@sinclair/typebox/value";
+import { createApis } from "../apis/index.js";
+import { ApiResponseError } from "../utils/errors.js";
+import { getLocale, setLocale } from "../utils/parse_meta.js";
+import { isCommand } from "./factory.js";
+export const loadCommands = async (domains) => {
+    const cmdFiles = await Promise.all(domains.map(async (domain) => {
+        return readdir(resolve(import.meta.dirname, domain))
+            .then((files) => files
+            .filter((file) => file.endsWith(".cmd.ts") || file.endsWith(".cmd.js"))
+            .map((file) => resolve(import.meta.dirname, domain, file)))
+            .catch((_error) => {
+            return [];
+        });
+    })).then((files) => files.flat());
+    return await Promise.all(cmdFiles.map(async (file) => {
+        const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        return Object.getOwnPropertyNames(module)
+            .filter((name) => {
+            const value = module[name];
+            return isCommand(value);
+        })
+            .map((name) => module[name]);
+    })).then((commands) => commands.flat());
+};
+const IS_DEV = process.env["NODE_ENV"] === "development";
+const logger = console;
+export const buildCommands = async (cli) => {
+    setLocale();
+    const commands = await loadCommands(["creative", "community"]);
+    return commands.map((cmd) => {
+        const command = cli.command(cmd.name);
+        command.description(cmd.title || cmd.description || "");
+        const inputSchema = cmd.inputSchema;
+        if (inputSchema && "properties" in inputSchema) {
+            const properties = inputSchema.properties;
+            if (!properties)
+                return command;
+            Object.entries(properties).forEach(([key, property]) => {
+                if (typeof property !== "object")
+                    return;
+                const option = new Option(`--${key} <${property["type"]}>`, property.description);
+                if (property.default) {
+                    option.default(property.default);
+                }
+                if (property["anyOf"]) {
+                    option.choices(property["anyOf"].map((item) => item.const));
+                }
+                if (inputSchema.required?.includes(key) &&
+                    property.default === undefined) {
+                    option.makeOptionMandatory();
+                }
+                if (property.type === "boolean") {
+                    option.argParser((value) => value === "true" || value === "1");
+                }
+                if (property.type === "number") {
+                    option.argParser((value) => Number.parseFloat(value));
+                }
+                if (property.type === "integer") {
+                    option.argParser((value) => Number.parseInt(value, 10));
+                }
+                if (property.type === "null") {
+                    option.argParser(() => null);
+                }
+                command.addOption(option);
+            });
+        }
+        command.action(async (args) => {
+            const { api_base_url, token } = cli.opts();
+            const _locale = getLocale();
+            const baseUrl = typeof api_base_url === "string"
+                ? api_base_url
+                : (process.env["NETA_API_BASE_URL"] ??
+                    (_locale === "zh_cn"
+                        ? "https://api.talesofai.cn"
+                        : "https://api.talesofai.com"));
+            const apis = createApis({
+                baseUrl,
+                headers: {
+                    "x-token": typeof token === "string"
+                        ? token
+                        : (process.env["NETA_TOKEN"] ?? ""),
+                    "x-platform": "nieta-app/web",
+                },
+            });
+            const user = await apis.user.me().catch((e) => {
+                if (e instanceof ApiResponseError) {
+                    return null;
+                }
+                return null;
+            });
+            const type = cmd.inputSchema ?? Type.Object({});
+            const input = Value.Decode(type, Default(type, args));
+            if (IS_DEV) {
+                logger.debug("command: %s, params: %o", cmd.name, input);
+            }
+            const result = await cmd
+                .execute(input, {
+                apis,
+                user,
+                log: IS_DEV
+                    ? logger
+                    : {
+                        error: () => { },
+                        warn: () => { },
+                        info: () => { },
+                        debug: () => { },
+                    },
+            })
+                .catch((e) => {
+                if (e instanceof ApiResponseError) {
+                    logger.error({
+                        error: {
+                            type: e.name,
+                            code: e.code,
+                            message: e.message,
+                        },
+                    });
+                    return null;
+                }
+                if (e instanceof Error) {
+                    logger.error({
+                        error: {
+                            type: e.name,
+                            message: e.message,
+                        },
+                    });
+                    return null;
+                }
+                logger.error(e);
+                return null;
+            });
+            if (!result)
+                return;
+            if (IS_DEV) {
+                logger.debug(result);
+            }
+            else {
+                logger.info(JSON.stringify(result));
+            }
+        });
+        return command;
+    });
+};

package/bin/utils/errors.js

@@ -0,0 +1,61 @@
+import { AxiosError } from "axios";
+import { safeParseJson } from "./json.js";
+export class ApiResponseError extends Error {
+    code;
+    message;
+    constructor(code, message, options) {
+        super(message, {
+            ...options,
+        });
+        this.code = code;
+        this.message = message;
+        this.name = "ApiResponseError";
+    }
+}
+export const catchErrorResponse = (data) => {
+    if (typeof data !== "string" && typeof data !== "object")
+        return String(data);
+    const parsedData = typeof data === "string" ? (safeParseJson(data) ?? {}) : data;
+    const detail = parsedData?.["detail"];
+    if (typeof detail === "string") {
+        return detail;
+    }
+    if (typeof detail === "object") {
+        if (Array.isArray(detail)) {
+            return detail.map(({ msg } = { msg: "" }) => msg).join(", ");
+        }
+        else {
+            return detail["message"] ?? detail["msg"] ?? JSON.stringify(detail);
+        }
+    }
+    const message = parsedData?.["message"] ??
+        parsedData?.["msg"] ??
+        JSON.stringify(parsedData);
+    return message;
+};
+export const handleAxiosError = (error) => {
+    if (error instanceof AxiosError) {
+        if (error.response?.status) {
+            let message = error.message;
+            if (error.response.status >= 400 && error.response.status < 500) {
+                message = catchErrorResponse(error.response.data);
+            }
+            throw new ApiResponseError(error.response.status, message, {
+                cause: error,
+            });
+        }
+    }
+    if (error instanceof Error) {
+        throw new ApiResponseError(-1, error.message, {
+            cause: error,
+        });
+    }
+    if (typeof error === "object" && error !== null) {
+        throw new ApiResponseError(-1, JSON.stringify(error), {
+            cause: error,
+        });
+    }
+    throw new ApiResponseError(-1, String(error), {
+        cause: error,
+    });
+};

package/bin/utils/json.js

@@ -0,0 +1,8 @@
+export function safeParseJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}

package/bin/utils/lang.js

@@ -0,0 +1,8 @@
+import osLocale from "os-locale";
+export const getLocale = () => {
+    const locale = osLocale();
+    if (locale.startsWith("zh")) {
+        return "zh_cn";
+    }
+    return "en_us";
+};

package/bin/utils/parse_meta.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { Value } from "@sinclair/typebox/value";
+import yaml from "yaml";
+import { getLocale as getLocaleFromLang } from "./lang.js";
+let _locale = "en_us";
+export const setLocale = (locale) => {
+    _locale = locale ?? getLocaleFromLang();
+};
+export const getLocale = () => {
+    return _locale;
+};
+export const parseMeta = (schema, importMeta) => {
+    const file = readFileSync(importMeta.filename.replace(/\.(ts|js)$/, `.${_locale}.yml`), "utf-8");
+    const data = yaml.parse(file);
+    return Value.Decode(schema, data);
+};

package/bin/utils/polling.js

@@ -0,0 +1,17 @@
+export const polling = async (fn, condition, interval = 2000, timeout = 10 * 60 * 1000) => {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const result = await fn();
+        if (await condition(result)) {
+            return {
+                result,
+                isTimeout: false,
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    return {
+        result: null,
+        isTimeout: true,
+    };
+};

package/bin/utils/prompts.js

@@ -0,0 +1,186 @@
+export const mapTCP2Tag = (tcp, weight = 1) => {
+    if (tcp.type === "elementum") {
+        return {
+            uuid: tcp.uuid,
+            name: tcp.name,
+            value: tcp.uuid,
+            type: "elementum",
+            weight,
+        };
+    }
+    return {
+        uuid: tcp.uuid,
+        name: tcp.name,
+        value: tcp.uuid,
+        type: "oc_vtoken_adaptor",
+        weight,
+    };
+};
+export const SEPARATORS = [",", "，", "。", ";", "；", "!", "！", "?", "？"];
+const parseSeparatedListOfString = (chars, getContent) => {
+    let offset = 0;
+    const pop = () => (offset >= chars.length ? null : (chars[offset++] ?? null));
+    const contents = [];
+    const separators = [];
+    let currentToken = "";
+    let startOffset = 0;
+    while (true) {
+        const next = pop();
+        if (!next) {
+            break;
+        }
+        else if (getContent(next) === "\\") {
+            const nextnext = pop();
+            if (nextnext) {
+                currentToken += getContent(nextnext);
+            }
+            else {
+                // is this valid?
+                currentToken += "\\";
+            }
+        }
+        else if (SEPARATORS.includes(getContent(next))) {
+            // we will insert a separator
+            contents.push({
+                parsedText: currentToken,
+                start: startOffset,
+                end: offset - 1,
+            });
+            separators.push({
+                parsedText: getContent(next),
+                start: offset - 1,
+                end: offset,
+            });
+            currentToken = "";
+            startOffset = offset;
+        }
+        else {
+            currentToken += getContent(next);
+        }
+    }
+    contents.push({
+        start: startOffset,
+        end: offset,
+        parsedText: currentToken,
+    });
+    if (contents.length - separators.length !== 1) {
+        throw new Error("Assertation failed: contents.length - separators.length !== 1");
+    }
+    return {
+        contents,
+        separators,
+    };
+};
+export const REF_IMG_PROMPT_PLACEHOLDER = "REF_IMG_PROMPT_PLACEHOLDER";
+export const REF_IMG_PROMPT_INVALID = "REF_IMG_PROMPT_INVALID";
+function stringToPrompt(promptString, options) {
+    const str = promptString.trim();
+    function extractWeight(str) {
+        const segs = str.split(":");
+        if (segs.length > 1) {
+            const f = parseFloat(segs[segs.length - 1] ?? "1");
+            return [
+                segs.slice(0, -1).join(":"),
+                Number.isNaN(f) ? 1 : Math.min(Math.max(0.1, f), 2),
+            ];
+        }
+        return [segs[0] ?? "", 1];
+    }
+    if (str.startsWith("@")) {
+        const [name, weight] = extractWeight(str.slice(1));
+        return { type: "character", name, weight, value: "" };
+    }
+    if (str.startsWith("/")) {
+        const [name, weight] = extractWeight(str.slice(1));
+        return { type: "elementum", name, weight };
+    }
+    if (str.startsWith("参考图-") || str.startsWith("图片捏-")) {
+        const [uuid, weight] = extractWeight(str.slice(4));
+        const refImageUrl = uuid ? options?.refImages?.[uuid] : undefined;
+        return {
+            name: "",
+            type: "ref_image",
+            value: refImageUrl ?? REF_IMG_PROMPT_PLACEHOLDER,
+            weight,
+            sub_type: "v1",
+            ref_img_uuid: uuid ?? null,
+        };
+    }
+    if (str.startsWith("ref_img-")) {
+        const [uuid, weight] = extractWeight(str.slice(8));
+        const refImageUrl = uuid ? options?.refImages?.[uuid] : undefined;
+        return {
+            name: "",
+            type: "ref_image",
+            value: refImageUrl ?? REF_IMG_PROMPT_PLACEHOLDER,
+            weight,
+            sub_type: "v1",
+            ref_img_uuid: uuid ?? null,
+        };
+    }
+    if ((str.startsWith("(参考图-") || str.startsWith("(图片捏-")) &&
+        str.endsWith(")")) {
+        const [uuid, weight] = extractWeight(str.slice(5, -1));
+        const refImageUrl = uuid ? options?.refImages?.[uuid] : undefined;
+        return {
+            name: "",
+            type: "ref_image",
+            value: refImageUrl ?? REF_IMG_PROMPT_PLACEHOLDER,
+            weight,
+            sub_type: "v1",
+            ref_img_uuid: uuid ?? null,
+        };
+    }
+    if (str.startsWith("(ref_img-") && str.endsWith(")")) {
+        const [uuid, weight] = extractWeight(str.slice(9, -1));
+        const refImageUrl = uuid ? options?.refImages?.[uuid] : undefined;
+        return {
+            name: "",
+            type: "ref_image",
+            value: refImageUrl ?? REF_IMG_PROMPT_PLACEHOLDER,
+            weight,
+            sub_type: "v1",
+            ref_img_uuid: uuid ?? null,
+        };
+    }
+    if (str.startsWith("(") && str.endsWith(")")) {
+        const [value, weight] = extractWeight(str.slice(1, -1));
+        return { type: "text", value, weight };
+    }
+    if (str === "参考图" || str === "图片捏") {
+        return {
+            name: "",
+            type: "ref_image",
+            value: REF_IMG_PROMPT_PLACEHOLDER,
+            weight: 1,
+            sub_type: "v1",
+            ref_img_uuid: null,
+        };
+    }
+    if (str === "ref_img") {
+        return {
+            name: "",
+            type: "ref_image",
+            value: REF_IMG_PROMPT_PLACEHOLDER,
+            weight: 1,
+            sub_type: "v1",
+            ref_img_uuid: null,
+        };
+    }
+    return {
+        type: "text",
+        value: str,
+        weight: 1,
+    };
+}
+export const splitPrompts = (str) => {
+    const { contents } = parseSeparatedListOfString([...str], (x) => x);
+    return contents.map((x) => x.parsedText.trim()).filter((x) => x !== "");
+};
+export function stringToPrompts(str, options) {
+    const { contents } = parseSeparatedListOfString([...str], (x) => x);
+    return contents
+        .map((x) => x.parsedText.trim())
+        .filter((x) => x !== "")
+        .map((text) => stringToPrompt(text, options));
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@talesofai/neta-skills",
+  "version": "0.6.0",
+  "description": "Neta API pi coding agent skills for interacting with Neta API to generate images, videos, songs, and manage characters/elements.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/talesofai/neta-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/talesofai/neta-skills/issues"
+  },
+  "homepage": "https://github.com/talesofai/neta-skills#readme",
+  "keywords": [
+    "neta",
+    "api",
+    "skill",
+    "pi-agent",
+    "image-generation",
+    "video-generation",
+    "ai"
+  ],
+  "author": "Neta Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "packageManager": "pnpm@10.25.0",
+  "bin": {
+    "neta-cli": "bin/cli.js"
+  },
+  "scripts": {
+    "lint": "biome check . --write --unsafe",
+    "validate": "skills-ref to-prompt ./skills/neta ./skills/neta-community ./skills/neta-creative ./skills/neta-suggest ./skills/neta-space",
+    "type-check": "tsc --noEmit",
+    "check": "pnpm lint && pnpm type-check && pnpm validate",
+    "changelog": "changeset",
+    "bump": "changeset version",
+    "prepare": "husky",
+    "build": "rimraf bin && tsc",
+    "postbuild": "node scripts/postbuild.js",
+    "dev": "NODE_ENV=development node src/cli.ts",
+    "start": "node bin/cli.js"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "@sinclair/typebox": "^0.34.48",
+    "axios": "^1.7.9",
+    "commander": "^14.0.0",
+    "dotenv": "^16.4.7",
+    "dotenv-flow": "^4.1.0",
+    "os-locale": "^8.0.0",
+    "qs": "^6.15.0",
+    "skills-ref": "^0.1.5",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^22.10.2",
+    "@types/qs": "^6.14.0",
+    "glob": "^13.0.6",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.1",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "package.json",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}

package/skills/neta/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: neta
+description: Neta capability index and routing skill — help choose the appropriate Neta‑related skill (neta-space / neta-creative / neta-community / neta-suggest). Use this skill when you need to understand Neta’s overall capabilities, decide which skill fits the current task, or migrate from older documentation that referenced the monolithic neta skill.
+---
+
+# Neta Skill
+
+Used for **overview and routing** of Neta‑related skills, rather than executing concrete commands directly.
+
+> This skill used to be a “kitchen‑sink” Neta interaction skill. It has now been split into multiple focused skills. Prefer using the skills listed below; use this skill only to understand the capability map or when migrating from older docs.
+
+## Installing sub‑skills
+
+In environments that support `skills add`, install sub‑skills as needed:
+
+```bash
+# Spaces and worldbuilding
+npx skills add talesofai/neta-skills/skills/neta-space
+
+# Creative content (images/videos/songs/MVs)
+npx skills add talesofai/neta-skills/skills/neta-creative
+
+# Community browsing and interactions
+npx skills add talesofai/neta-skills/skills/neta-community
+
+# Research and content suggestions
+npx skills add talesofai/neta-skills/skills/neta-suggest
+```
+
+## Instructions
+
+1. **Identify the task type**: classify the user’s need as one of: “space exploration”, “content creation”, “community interaction”, or “research/recommendation”.
+2. **Choose the corresponding sub‑skill**:
+   - Spaces/worldbuilding/gameplay structure → use `neta-space`
+   - Image/video/song/MV creation and idea deconstruction → use `neta-creative`
+   - Browsing feeds, viewing collection details, liking/interacting, community‑centric views → use `neta-community`
+   - Keyword/tag/category research and recommendation, progressive exploration from broad to narrow → use `neta-suggest`
+3. Use this skill only when boundaries are unclear or when you need to explain which sub‑skill to pick.
+
+## Capability map and sub‑skill overview
+
+### 1. Spaces and worldbuilding: `neta-space`
+
+Responsibilities:
+
+- List all available spaces.
+- Fetch worldbuilding (lore) for spaces/hashtags.
+- Fetch sub‑spaces, characters, and gameplay collections within a space.
+
+Use when:
+
+- The user talks about “worlds/universes/spaces/scene settings”.
+- They want to browse gameplay and content organized by spaces/activities.
+
+See `skills/neta-space/SKILL.md` for full details.
+
+### 2. Content creation: `neta-creative`
+
+Responsibilities:
+
+- Generate images, videos, songs, and MVs.
+- Remove image backgrounds.
+- Search and inspect characters (in a creation context).
+- Deconstruct creative ideas from existing collections via `read_collection`.
+
+Use when:
+
+- The user wants to “create/edit images/videos/songs/MVs”.
+- They want to create based on character settings or stories.
+- They want to analyze the creative intent behind an existing work.
+
+See `skills/neta-creative/SKILL.md` for full details.
+
+### 3. Community browsing and interactions: `neta-community`
+
+Responsibilities:
+
+- Fetch interactive recommendation feeds.
+- View collection details (in a community context).
+- Like/unlike or otherwise interact with content.
+- Browse community content grouped by tags or characters.
+
+Use when:
+
+- The user says “show me what people are doing”, “scroll the feed”.
+- They want to like or interact with specific works.
+
+See `skills/neta-community/SKILL.md` for full details.
+
+### 4. Research and recommendation engine: `neta-suggest`
+
+Responsibilities:
+
+- Keyword suggestions (`suggest_keywords`).
+- Tag suggestions (`suggest_tags`).
+- Category navigation and path validation (`suggest_categories` / `validate_tax_path`).
+- Multi‑mode content feeds (`suggest_content`).
+
+Use when:
+
+- The user has no clear target and wants ideas/topics.
+- They want to understand popular tags/category structure/content distribution.
+- They need systematic research before creating content.
+
+See `skills/neta-suggest/SKILL.md` for full details.
+
+## Migration notes (from legacy neta skill)
+
+If you encounter older docs or scripts that call commands directly under `neta`, migrate them according to this table:
+
+| Legacy capability                           | New skill        |
+|---------------------------------------------|------------------|
+| Space/tag lore and space browsing           | `neta-space`     |
+| Image/video/song/MV creation                | `neta-creative`  |
+| Collection details, feeds, likes/interacts  | `neta-community` |
+| Keyword/tag/category/recommendation research| `neta-suggest`   |
+
+For new development, always prefer the focused sub‑skills and avoid adding new command examples directly to this skill.
+