@talesofai/neta-skills 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @neta/skills-neta
 
+## 0.10.0
+
+### Minor Changes
+
+- bump npm package version
+
+## 0.9.0
+
+### Minor Changes
+
+- add commands about character create and management
+
+## 0.8.0
+
+### Minor Changes
+
+- use https://api.talesofai.com for default api endpoint
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -4,198 +4,220 @@
 [![Node](https://img.shields.io/badge/Node-%3E%3D20-green)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
-[简体中文](./README.md) · [English](./README.en.md)
+[English](./README.md) · [简体中文](./README.zh_cn.md)
 
 ---
 
-## 简体中文
+## Overview
 
-### 简介
+**NETA Skills** is a collection of powerful AI agent skills and accompanying CLI tools designed for interacting with the [Neta Art](https://www.neta.art/) API. Built for developers and AI agents, it seamlessly extends any agent's capabilities to generate multimedia, manage characters, and process audio/video workflows.
 
-**NETA Skills** 是一组基于 [Neta Art](https://www.neta.art/) API 的 AI Agent 技能与 CLI 工具集合，帮助你在 Agent 环境中一站式完成：
-
-- 生成图片 / 视频 / 歌曲等多媒体内容
-- 查询与管理角色（Character）与风格元素（Elementum）
-- 进行标签（Hashtag）与空间玩法探索
-- 通过推荐引擎和互动 Feed 进行玩法内容发现
-
-你可以在 [Neta 开放平台](https://www.neta.art/open/) 获取访问令牌 `NETA_TOKEN`。
-也可以在[国内登陆账号后台](https://app.nieta.art/security) 获取访问令牌 `NETA_TOKEN`。
+You can get your access token from the [Neta Open Portal](https://www.neta.art/open/).
 
 ---
 
-### ✨ 功能特性
+## ✨ Features
 
-- 🎨 **多媒体创作**：使用最新的 AI 模型生成图片、视频和歌曲。
-- 🔧 **图像与视频处理**：支持移除背景、视频合并等常见素材处理流程。
-- 👤 **角色与风格管理**：搜索、获取角色与风格元素详情，在创作中标准化复用。
-- 🏷️ **社区与标签集成**：浏览热门标签、空间、玩法合集与角色。
-- 🧭 **智能内容探索**：通过关键词建议、标签推荐、分类导航与智能内容流，渐进式发现玩法与内容。
-- 🤖 **Agent 优先设计**：面向 AI Agent 场景设计，易于在各类 Agent 框架中集成调用。
+- 🎨 **Multimedia Creation:** Generate stunning images, videos, and songs using state-of-the-art AI models.
+- 🔧 **Image & Video Processing:** Effortlessly remove backgrounds and merge video assets.
+- 👤 **Character & Style Management:** Search, fetch details, and manage characters and stylistic elements.
+- 🏷️ **Community Integrations:** Explore trending hashtags, popular characters, and curated collections.
+- 🧭 **Smart Discovery & Suggestions:** Explore interactive feeds and get keyword, tag, and category suggestions for progressive content discovery.
+- 🤖 **Agent First:** Designed from the ground up to plug into your favorite AI agent frameworks.
 
 ---
 
-### 🚀 在 Agent 中使用技能
+## 🚀 Getting Started with Skills
+
+The primary way to use this project is by installing the skills into your AI agent environment.
 
-在你的 Agent 环境中安装统一的 [`neta`](skills/zh_cn/neta/SKILL.md) 技能：
+### Installation (skills.sh)
+
+Install the unified [`neta`](skills/neta/SKILL.md) skill into your agent:
 
 ```bash
-npx skills add talesofai/neta-skills/skills/zh_cn/neta
+npx skills add talesofai/neta-skills/skills/neta
 ```
 
-如果你希望在 Agent 中按功能模块更精细地控制权限，也可以分别安装拆分后的技能：
+You can also install the specialized skills separately if your agent prefers more granular capabilities:
 
 ```bash
-# 社区 / 标签 / 空间探索
-npx skills add talesofai/neta-skills/skills/zh_cn/neta-community
+# Community exploration (hashtags, spaces, interactive feed)
+npx skills add talesofai/neta-skills/skills/neta-community
+
+# Creation workflows (image / video / song)
+npx skills add talesofai/neta-skills/skills/neta-creative
 
-# 图片 / 视频 / 歌曲创作
-npx skills add talesofai/neta-skills/skills/zh_cn/neta-creative
+# Discovery & suggestions (keywords, tags, categories, content)
+npx skills add talesofai/neta-skills/skills/neta-suggest
 
-# 关键词 / 标签 / 分类 / 内容推荐与检索
-npx skills add talesofai/neta-skills/skills/zh_cn/neta-suggest
+# Space navigation & exploration
+npx skills add talesofai/neta-skills/skills/neta-space
 
-# 空间导航与探索（space / topic）
-npx skills add talesofai/neta-skills/skills/zh_cn/neta-space
+# Character VToken creation and management
+npx skills add talesofai/neta-skills/skills/neta-character
+
+# Elementum VToken creation and management
+npx skills add talesofai/neta-skills/skills/neta-elementum
 ```
 
-#### 可用指令总览
-
-当前技能共包含 **26 个命令**，覆盖创作、角色与社区探索等场景：
-
-| 分类 | 命令 | 说明 |
-|------|------|------|
-| **创作 Creation** | `make_image` | 基于提示词生成图片 |
-| | `make_video` | 基于图片与动作描述生成视频 |
-| | `make_song` | 基于风格与歌词生成歌曲 |
-| | `remove_background` | 移除图片背景 |
-| | `edit_collection` | 编辑已有玩法合集（名称、描述、标签、状态等） |
-| | `publish_collection` | 发布或更新玩法合集内容 |
-| | `search_character_or_elementum` | 搜索可复用的 TCP（角色 / 元素 / 玩法模块） |
-| **角色 Characters** | `request_character_or_elementum` | 通过名称或 UUID 获取角色 / 元素详情 |
-| **社区 Community** | `get_hashtag_info` | 查询标签基础信息与 worldbuilding lore |
-| | `get_hashtag_characters` | 获取标签下的角色列表 |
-| | `get_hashtag_collections` | 获取标签下的玩法合集 |
-| | `read_collection` | 读取单个玩法合集（含 Remix 模板） |
-| | `list_spaces` | 列出可游览的空间 |
-| | `list_space_topics` | 获取空间下的子空间（topic）信息 |
-| | `request_interactive_feed` | 获取玩法互动 Feed（合集、空间、用户等场景） |
-| | `suggest_keywords` | 获取搜索关键词自动补全建议 |
-| | `suggest_tags` | 基于关键词获取相关标签建议 |
-| | `suggest_categories` | 按层级获取玩法分类导航 |
-| | `validate_tax_path` | 验证分类路径是否有效 |
-| | `suggest_content` | 推荐 / 搜索 / 精确筛选三模式内容流 |
-| | `get_fan_list` | 获取当前用户的粉丝列表 |
-| | `get_subscribe_list` | 获取当前用户关注的创作者列表 |
-| | `favor_collection` | 收藏 / 取消收藏玩法合集 |
-| | `like_collection` | 点赞 / 取消点赞玩法合集 |
-| | `subscribe_user` | 关注 / 取消关注创作者 |
-| | `create_comment` | 对玩法合集创建评论 |
-
-更详细的中文 CLI 示例与最佳实践，请参考 `skills/neta/SKILL.md` 以及 `skills/neta/references/` 目录下的文档。
+### Available Commands
+
+The skill includes **30 commands** for various tasks:
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Creation** | `make_image` | Generate images from text prompts |
+| | `make_video` | Generate videos from images and prompts |
+| | `make_song` | Compose songs with custom prompts and lyrics |
+| | `remove_background` | Remove the background from an image |
+| | `edit_collection` | Edit an existing collection (name, description, tags, status, etc.) |
+| | `publish_collection` | Publish or update a collection |
+| | `search_character_or_elementum` | Search reusable TCP building blocks (characters / elements / flows) |
+| **VToken Management** | `create_character` | Create a character VToken (consumes credits) |
+| | `update_character` | Update an existing character VToken |
+| | `list_my_characters` | List all characters created by the current user |
+| | `create_elementum` | Create an elementum VToken (consumes credits) |
+| | `update_elementum` | Update an existing elementum VToken |
+| | `list_my_elementum` | List all elementa created by the current user |
+| **Characters** | `request_character_or_elementum` | Fetch character or elementum details by name or UUID |
+| **Community** | `get_hashtag_info` | Get details and lore for a specific hashtag |
+| | `get_hashtag_characters` | Get a list of characters under a hashtag |
+| | `get_hashtag_collections` | Get curated collections under a hashtag |
+| | `read_collection` | Read details for a specific collection (玩法) |
+| | `list_spaces` | List spaces that can be explored |
+| | `list_space_topics` | List topics available under a specific space |
+| | `request_interactive_feed` | Get interactive content feeds for collections, spaces, and users |
+| | `suggest_keywords` | Get autocomplete suggestions for search keywords |
+| | `suggest_tags` | Get recommended hashtags related to a keyword |
+| | `suggest_categories` | Get navigation suggestions for taxonomy categories |
+| | `validate_tax_path` | Validate that a taxonomy path is valid |
+| | `suggest_content` | Discover content via recommend, search, or exact filter modes |
+| | `get_fan_list` | Get the list of users who follow the current user |
+| | `get_subscribe_list` | Get the list of creators the current user follows |
+| | `favor_collection` | Favorite or unfavorite a collection |
+| | `like_collection` | Like or unlike a collection |
+| | `subscribe_user` | Follow or unfollow a creator |
+| | `create_comment` | Create a comment on a collection |
 
 ---
 
-### 🛠️ CLI 使用（`@talesofai/neta-skills`）
+## 🛠️ CLI Usage (`@talesofai/neta-skills`)
 
-项目同时提供了一个独立的 CLI 包 `@talesofai/neta-skills`，适合在本地终端、脚本和 CI 中直接调用 Neta API。
+The project also ships a standalone CLI package `@talesofai/neta-skills` for testing, scripting, and CI automation.
 
-#### 安装 CLI
+### Install CLI
 
 ```bash
-# 全局安装（推荐）
+# Global install (recommended)
 npm install -g @talesofai/neta-skills
 
-# 或者使用 npx / pnpm dlx 临时调用
+# Or use npx / pnpm dlx without global install
 npx @talesofai/neta-skills --help
 pnpm dlx @talesofai/neta-skills --help
 ```
 
-配置环境变量：
+Configure your environment:
 
 ```bash
-# 在环境中设置 NETA_TOKEN，或在你的 .env / .env.local 中配置
+# Set NETA_TOKEN in your environment or put it into a .env / .env.local file
 export NETA_TOKEN=your_token_here
 ```
 
-#### 运行示例
+### Running Commands
 
 ```bash
-# 查看帮助
+# Get general help or specific command help
 neta-cli --help
 neta-cli make_image --help
 
-# 示例：生成一张图片
-neta-cli make_image \
-  --prompt "夜晚的赛博朋克城市，霓虹灯，高楼大厦，雨中街道" \
-  --aspect "16:9"
+# Example: Generate an image
+neta-cli make_image --prompt "A cyberpunk cityscape at night" --aspect "16:9"
 
-# 示例：搜索角色或元素
-neta-cli search_character_or_elementum \
-  --keywords "幻想" \
-  --parent_type "character"
+# Example: Search for characters or elementum
+neta-cli search_character_or_elementum --keywords "fantasy"
 ```
 
 ---
 
-### 📂 项目结构
+## 📂 Project Structure
 
 ```text
 neta-skills/
 ├── skills/
-│   ├── neta/                       # 统一 Neta 技能（Agent 优先，仍然维护）
-│   │   ├── SKILL.md                # 技能说明与中文用法示例
-│   │   ├── package.json            # 子包依赖配置
-│   │   ├── src/                    # Agent / skills 实现
-│   │   └── references/             # 最佳实践与工作流参考文档（面向 Agent）
-│   ├── neta-community/             # 社区 / 标签 / 空间探索相关技能
-│   ├── neta-creative/              # 图片 / 视频 / 歌曲等创作相关技能
-│   ├── neta-suggest/               # 推荐 / 搜索 / 分类导航等探索技能
-│   └── neta-space/                 # 空间与话题导航 / 探索技能
-├── packages/
-│   └── neta-cli/                   # CLI 包（发布名：@talesofai/neta-skills）
-│       ├── bin/                    # CLI 入口构建产物
-│       ├── src/                    # 仅 CLI 相关的源码（命令、IO 等）
-│       └── scripts/                # 构建 / 发布 / 校验脚本
-├── .env.example                    # 环境变量示例
-└── package.json                    # 根包配置
+│   ├── neta/                       # Unified Neta skill (agent-first)
+│   │   └── SKILL.md                # Core skill documentation (EN)
+│   ├── neta-community/             # Community / hashtag / space exploration skills (EN)
+│   ├── neta-creative/              # Image / video / song creation skills (EN)
+│   ├── neta-suggest/               # Discovery & suggestion skills (EN)
+│   ├── neta-space/                 # Space navigation & exploration skills (EN)
+│   ├── neta-character/             # Character VToken creation & management (EN)
+│   ├── neta-elementum/             # Elementum VToken creation & management (EN)
+│   └── zh_cn/                      # Chinese-localized skills & references
+│       ├── neta/
+│       ├── neta-community/
+│       ├── neta-creative/
+│       ├── neta-suggest/
+│       ├── neta-space/
+│       ├── neta-character/
+│       └── neta-elementum/
+├── src/                            # TypeScript source for the CLI
+│   ├── apis/                       # Typed Neta API client helpers
+│   ├── commands/                   # CLI command definitions (TS + YAML meta)
+│   ├── utils/                      # Shared utilities
+│   └── cli.ts                      # CLI entrypoint (TypeScript)
+├── bin/                            # Built JavaScript output for the CLI
+│   ├── apis/
+│   ├── commands/
+│   ├── utils/
+│   └── cli.js                      # CLI entrypoint (compiled JS)
+├── scripts/
+│   └── postbuild.js                # Build/post-build helpers
+├── .env.example                    # Environment variable template
+├── package.json                    # Root package config / scripts
+├── pnpm-lock.yaml                  # Dependency lockfile
+├── tsconfig.json                   # TypeScript configuration
+├── biome.json                      # Biome (formatter / linter) config
+└── lint-staged.config.mjs          # lint-staged configuration
 ```
 
 ---
 
-### 📖 最佳实践与工作流参考
+## 📖 Best Practices & Workflows (References)
+
+The `skills/neta/references/` directory contains detailed **best practice workflows**. These guides are designed to help AI agents (and developers) understand how to combine multiple commands to achieve complex goals effectively. 
 
-`skills/neta/references/` 目录下提供了详细的中文工作流与 SOP，适合 AI Agent 在规划调用顺序时阅读，例如：
+Agents use these references to learn the optimal sequence of actions, parameter tuning, and standard operating procedures for specific NETA Art workflows, such as:
 
-- **图片与视频生成**：提示词结构、宽高比选择、从图到视频的完整链路。
-- **歌曲与 MV 创作**：歌词模板、风格设计、MV 视觉规划与多场景组合。
-- **角色与标签调研**：如何通过角色 / 标签 / 空间找到合适的创作方向。
-- **玩法内容探索**：使用 `suggest_*` 与 `suggest_content` 构建渐进式探索闭环。
+- **Image & Video Generation:** Best practices for chaining prompts, generating assets, and assembling videos.
+- **Song & MV Creation:** Workflows for composing songs and creating music videos with synchronized visuals.
+- **Character & Hashtag Research:** Processes for finding trending content, searching characters, and utilizing community trends.
+- **Character & Elementum Creation:** Character creation and elementum alchemy workflows.
 
 ---
 
-### 📝 环境变量
+## 📝 Environment Variables
 
-无论在 Agent 还是 CLI 中使用，都需要正确配置以下环境变量：
+Both the AI agent skills and the CLI require the following environment configuration:
 
-| 变量名 | 必需 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `NETA_TOKEN` | ✅ | - | Neta Art API 访问令牌 |
-| `NETA_API_BASE_URL` | ❌ | zh_cn: `https://api.talesofai.cn`；en_us: `https://api.talesofai.com` | Neta API 网关地址 |
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NETA_TOKEN` | ✅ | - | Your Neta Art API access token. |
+| `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Base URL for the Neta API. |
 
-#### 多语言与本地化（i18n）
+### i18n and locale detection
 
-CLI 与 Skills 会根据系统与环境变量自动选择使用的语言：
+The CLI and skills automatically detect the current locale and map it to internal language variants:
 
-- 系统语言或环境变量以 `zh` 开头（如 `zh_CN`、`en_US`）→ 使用 `zh_cn` 文案与元数据；
-- 其他语言环境 → 默认使用 `en_us` 文案与元数据。
+- Locales starting with `zh` (for example, `zh_CN`, `en_US`) → use `zh_cn` docs and metadata.
+- All other locales → default to `en_us` docs and metadata.
 
-在终端环境中，可以通过以下方式影响语言选择：
+In terminal environments, locale is typically controlled by:
 
-- 操作系统语言设置（macOS / Linux / Windows）；
-- Shell 中的本地化环境变量：`LC_ALL`、`LC_MESSAGES`、`LANG`、`LANGUAGE` 等。
+- Your operating system language settings (macOS / Linux / Windows), and
+- Environment variables such as `LC_ALL`, `LC_MESSAGES`, `LANG`, and `LANGUAGE`.
 
-在需要强制指定语言时，推荐在运行命令前显式设置环境变量，例如：
+If you want to force a specific language for a single command, you can prefix it with the desired locale, for example:
 
 ```bash
 LC_ALL=zh_CN.UTF-8 neta-cli make_image --help
@@ -204,34 +226,38 @@ LANG=en_US.UTF-8 neta-cli make_image --help
 
 ---
 
-### 🔧 本地开发
+## 🔧 Development
 
-在本地开发与调试时，可以使用以下脚本：
+To develop and test locally:
 
 ```bash
-# 安装依赖
+# Install dependencies
 corepack enabled
 pnpm i
 
-# TypeScript 类型检查
+# Run TypeScript type checking
 pnpm type-check
 
-# 代码检查（lint）
+# Run lint
 pnpm lint
 
-# 本地调试技能（watch / dev）
+# Test CLI commands locally
 pnpm dev <command> [options]
 
-# 构建 bin 脚本
+# Build bin scripts
 pnpm build
 ```
 
 ---
 
-### 📄 开源协议与链接
+## 📄 License
+
+This project is open-sourced under the [MIT License](LICENSE).
+
+---
 
-本项目基于 [MIT License](LICENSE) 开源。
+## 🔗 Links
 
-- [Neta Art 官网](https://www.neta.art/)
-- [skills.sh 文档](https://skills.sh/docs)
+- [Neta Art Official Website](https://www.neta.art/)
+- [skills.sh Documentation](https://skills.sh/docs)