@talesofai/neta-skills 0.7.0 → 0.10.0

package/README.zh_cn.md

@@ -0,0 +1,266 @@
+# NETA Skills
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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)
+
+---
+
+## 简介
+
+**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`。
+
+---
+
+## ✨ 功能特性
+
+- 🎨 **多媒体创作**：使用最新的 AI 模型生成图片、视频和歌曲。
+- 🔧 **图像与视频处理**：支持移除背景、视频合并等常见素材处理流程。
+- 👤 **角色与风格管理**：搜索、获取角色与风格元素详情，在创作中标准化复用。
+- 🏷️ **社区与标签集成**：浏览热门标签、空间、玩法合集与角色。
+- 🧭 **智能内容探索**：通过关键词建议、标签推荐、分类导航与智能内容流，渐进式发现玩法与内容。
+- 🤖 **Agent 优先设计**：面向 AI Agent 场景设计，易于在各类 Agent 框架中集成调用。
+
+---
+
+## 🚀 在 Agent 中使用技能
+
+在你的 Agent 环境中安装统一的 [`neta`](skills/zh_cn/neta/SKILL.md) 技能：
+
+```bash
+npx skills add talesofai/neta-skills/skills/zh_cn/neta
+```
+
+如果你希望在 Agent 中按功能模块更精细地控制权限，也可以分别安装拆分后的技能：
+
+```bash
+# 社区 / 标签 / 空间探索
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-community
+
+# 图片 / 视频 / 歌曲创作
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-creative
+
+# 关键词 / 标签 / 分类 / 内容推荐与检索
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-suggest
+
+# 空间导航与探索（space / topic）
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-space
+
+# 角色 VToken 创建与管理
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-character
+
+# 元素 VToken 创建与管理
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-elementum
+```
+
+### 可用指令总览
+
+当前技能共包含 **30 个命令**，覆盖创作、角色与社区探索等场景：
+
+| 分类 | 命令 | 说明 |
+|------|------|------|
+| **创作 Creation** | `make_image` | 基于提示词生成图片 |
+| | `make_video` | 基于图片与动作描述生成视频 |
+| | `make_song` | 基于风格与歌词生成歌曲 |
+| | `remove_background` | 移除图片背景 |
+| | `edit_collection` | 编辑已有玩法合集（名称、描述、标签、状态等） |
+| | `publish_collection` | 发布或更新玩法合集内容 |
+| | `search_character_or_elementum` | 搜索可复用的 TCP（角色 / 元素 / 玩法模块） |
+| **VToken 管理** | `create_character` | 创建角色 VToken（消耗电量） |
+| | `update_character` | 更新现有角色 VToken |
+| | `list_my_characters` | 列出当前用户创建的所有角色 |
+| | `create_elementum` | 创建元素 VToken（消耗电量） |
+| | `update_elementum` | 更新现有元素 VToken |
+| | `list_my_elementum` | 列出当前用户创建的所有元素 |
+| **角色 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/` 目录下的文档。
+
+---
+
+## 🛠️ CLI 使用（`@talesofai/neta-skills`）
+
+项目同时提供了一个独立的 CLI 包 `@talesofai/neta-skills`，适合在本地终端、脚本和 CI 中直接调用 Neta API。
+
+### 安装 CLI
+
+```bash
+# 全局安装（推荐）
+npm install -g @talesofai/neta-skills
+
+# 或者使用 npx / pnpm dlx 临时调用
+npx @talesofai/neta-skills --help
+pnpm dlx @talesofai/neta-skills --help
+```
+
+配置环境变量：
+
+```bash
+# 在环境中设置 NETA_TOKEN，或在你的 .env / .env.local 中配置
+export NETA_TOKEN=your_token_here
+```
+
+### 运行示例
+
+```bash
+# 查看帮助
+neta-cli --help
+neta-cli make_image --help
+
+# 示例：生成一张图片
+neta-cli make_image \
+  --prompt "夜晚的赛博朋克城市，霓虹灯，高楼大厦，雨中街道" \
+  --aspect "16:9"
+
+# 示例：搜索角色或元素
+neta-cli search_character_or_elementum \
+  --keywords "幻想" \
+  --parent_type "character"
+```
+
+---
+
+## 📂 项目结构
+
+```text
+neta-skills/
+├── skills/
+│   ├── neta/                       # 英文统一 Neta 技能（Agent 优先）
+│   │   └── SKILL.md                # 英文技能说明
+│   ├── neta-community/             # 英文社区 / 标签 / 空间探索相关技能
+│   ├── neta-creative/              # 英文图片 / 视频 / 歌曲创作相关技能
+│   ├── neta-suggest/               # 英文推荐 / 搜索 / 分类导航技能
+│   ├── neta-space/                 # 英文空间与话题导航 / 探索技能
+│   ├── neta-character/             # 英文角色 VToken 创建与管理技能
+│   ├── neta-elementum/             # 英文元素 VToken 创建与管理技能
+│   └── zh_cn/                      # 中文本地化技能与参考文档
+│       ├── neta/
+│       ├── neta-community/
+│       ├── neta-creative/
+│       ├── neta-suggest/
+│       ├── neta-space/
+│       ├── neta-character/
+│       └── neta-elementum/
+├── src/                            # CLI 对应的 TypeScript 源码
+│   ├── apis/                       # 封装后的 Neta API 调用
+│   ├── commands/                   # CLI 命令定义（TS + YAML 描述）
+│   ├── utils/                      # 通用工具方法
+│   └── cli.ts                      # CLI 入口（TypeScript）
+├── bin/                            # 构建后的 JavaScript 产物
+│   ├── apis/
+│   ├── commands/
+│   ├── utils/
+│   └── cli.js                      # CLI 入口（编译后的 JS）
+├── scripts/
+│   └── postbuild.js                # 构建 / 后处理脚本
+├── .env.example                    # 环境变量示例文件
+├── package.json                    # 根包配置与脚本
+├── pnpm-lock.yaml                  # 依赖锁定文件
+├── tsconfig.json                   # TypeScript 配置
+├── biome.json                      # Biome（格式化 / Lint）配置
+└── lint-staged.config.mjs          # lint-staged 配置
+```
+
+---
+
+## 📖 最佳实践与工作流参考
+
+`skills/neta/references/` 目录下提供了详细的中文工作流与 SOP，适合 AI Agent 在规划调用顺序时阅读，例如：
+
+- **图片与视频生成**：提示词结构、宽高比选择、从图到视频的完整链路。
+- **歌曲与 MV 创作**：歌词模板、风格设计、MV 视觉规划与多场景组合。
+- **角色与标签调研**：如何通过角色 / 标签 / 空间找到合适的创作方向。
+- **角色与元素创建**：角色创建和元素炼金的工作流。
+- **玩法内容探索**：使用 `suggest_*` 与 `suggest_content` 构建渐进式探索闭环。
+
+---
+
+## 📝 环境变量
+
+无论在 Agent 还是 CLI 中使用，都需要正确配置以下环境变量：
+
+| 变量名 | 必需 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `NETA_TOKEN` | ✅ | - | Neta Art API 访问令牌 |
+| `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Neta API 网关地址 |
+
+### 多语言与本地化（i18n）
+
+CLI 与 Skills 会根据系统与环境变量自动选择使用的语言：
+
+- 系统语言或环境变量以 `zh` 开头（如 `zh_CN`、`en_US`）→ 使用 `zh_cn` 文案与元数据；
+- 其他语言环境 → 默认使用 `en_us` 文案与元数据。
+
+在终端环境中，可以通过以下方式影响语言选择：
+
+- 操作系统语言设置（macOS / Linux / Windows）；
+- Shell 中的本地化环境变量：`LC_ALL`、`LC_MESSAGES`、`LANG`、`LANGUAGE` 等。
+
+在需要强制指定语言时，推荐在运行命令前显式设置环境变量，例如：
+
+```bash
+LC_ALL=zh_CN.UTF-8 neta-cli make_image --help
+LANG=en_US.UTF-8 neta-cli make_image --help
+```
+
+---
+
+## 🔧 本地开发
+
+在本地开发与调试时，可以使用以下脚本：
+
+```bash
+# 安装依赖
+corepack enabled
+pnpm i
+
+# TypeScript 类型检查
+pnpm type-check
+
+# 代码检查（lint）
+pnpm lint
+
+# 本地调试技能（watch / dev）
+pnpm dev <command> [options]
+
+# 构建 bin 脚本
+pnpm build
+```
+
+---
+
+## 📄 开源协议与链接
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+- [Neta Art 官网](https://www.neta.art/)
+- [skills.sh 文档](https://skills.sh/docs)
+

package/bin/apis/tcp.js

@@ -9,8 +9,38 @@ export const createTcpApis = (client) => {
             .get(`/v2/travel/parent/${uuid}/profile`)
             .then((res) => res.data);
     };
+    const createCharacter = async (params) => {
+        return client
+            .post("/v3/oc/character", params)
+            .then((res) => res.data);
+    };
+    const updateCharacter = async (tcp_uuid, params) => {
+        return client
+            .patch(`/v3/oc/character/${tcp_uuid}`, params)
+            .then((res) => res.data);
+    };
+    const createElementum = async (params) => {
+        return client
+            .post("/v3/oc/elementum", params)
+            .then((res) => res.data);
+    };
+    const updateElementum = async (tcp_uuid, params) => {
+        return client
+            .patch(`/v3/oc/elementum/${tcp_uuid}`, params)
+            .then((res) => res.data);
+    };
+    const listMyTCPs = async (query) => {
+        return client
+            .get("/v2/travel/parent", { params: query })
+            .then((res) => res.data);
+    };
     return {
         searchTCPs,
         tcpProfile,
+        createCharacter,
+        updateCharacter,
+        createElementum,
+        updateElementum,
+        listMyTCPs,
     };
 };

package/bin/cli.js

@@ -9,8 +9,6 @@ program
     .name("neta")
     .description("NETA CLI - Neta API Client")
     .version(pkg.version);
-const cli = program
-    .option("--token <string>", "neta token (default: from env NETA_TOKEN)")
-    .option("--api_base_url <string>", "api base url (default: NETA_API_BASE_URL or locale-based default)");
+const cli = program.option("--api_base_url <string>", "api base url (default: NETA_API_BASE_URL or locale-based default)");
 await buildCommands(cli);
 cli.parse(process.argv);

package/bin/commands/character_elementum/create_character.cmd.en_us.yml

@@ -0,0 +1,43 @@
+name: create_character
+title: Create Character
+description: |
+  Create a new original character (OC) and generate a character Token (TCP).
+
+  After creation, the character can be referenced in make_image using @CharacterName.
+
+  Usage Notes:
+    - Character creation costs credits; users with unlimited credits or special privileges are not affected
+    - avatar_artifact_uuid comes from make_image response artifacts[0].uuid (the preview image artifact UUID)
+    - prompt should only describe visual features, not personality or backstory
+    - trigger must be in English for image and language model recognition
+
+  Field Descriptions:
+    - name: Character name, max 128 characters
+    - prompt: Visual description for image models (physical features, clothing, distinctive marks)
+    - trigger: English recognition tags, e.g., "1girl, Ada Wong, black hair, red dress, spy"
+    - description: For Agents and users to read, should include appearance summary + backstory. Write more for deeper roleplay (up to 1000 characters).
+
+parameters:
+  name: Character name (max 128 characters)
+  gender: 'Character gender. English: male, female, neutral, other. Chinese: 男, 女, 自由, 其他. Defaults to neutral/自由'
+  avatar_artifact_uuid: Character avatar artifact UUID from make_image response artifacts[0].uuid
+  prompt: |
+    Visual description for image models.
+    - Only include: physical features, clothing, distinctive marks
+    - Exclude: personality, story, background
+    - Example: "long black hair, red qipao dress, blue eyes, gun holster on thigh"
+  trigger: |
+    English recognition tags for LLM and image models.
+    - Must be in English
+    - Include: gender tag (1girl/1boy), character name, key features, IP series
+    - Example: "1girl, Ada Wong, black hair, red dress, spy, elegant, resident evil series"
+  accessibility: Visibility, PUBLIC or PRIVATE, defaults to PUBLIC
+  age: Character age (optional)
+  interests: Character interests and hobbies (optional)
+  persona: Character personality description (optional)
+  description: |
+    Character description for Agents and users to read.
+    - Should include: appearance summary + backstory/worldview/motivations
+    - Write more for deeper roleplay and richer character interactions (up to 1000 characters)
+    - Example: "Ada Wong, a mysterious spy with black hair and red dress. Her true identity is unknown, and she has repeatedly appeared as a middleman in Resident Evil incidents."
+  occupation: Character occupation (optional)

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

@@ -0,0 +1,72 @@
+import { Type } from "@sinclair/typebox";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { mapProfileToCharacterAssign } from "../../utils/tcp_mapper.js";
+import { createCommand } from "../factory.js";
+const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+    parameters: Type.Object({
+        name: Type.String(),
+        gender: Type.String(),
+        avatar_artifact_uuid: Type.String(),
+        prompt: Type.String(),
+        trigger: Type.String(),
+        accessibility: Type.String(),
+        age: Type.String(),
+        interests: Type.String(),
+        persona: Type.String(),
+        description: Type.String(),
+        occupation: Type.String(),
+    }),
+}), import.meta);
+const createCharacterParameters = Type.Object({
+    name: Type.String({ description: meta.parameters.name }),
+    gender: Type.Union([
+        Type.Literal("男"),
+        Type.Literal("女"),
+        Type.Literal("自由"),
+        Type.Literal("其他"),
+        Type.Literal("male"),
+        Type.Literal("female"),
+        Type.Literal("neutral"),
+        Type.Literal("other"),
+    ], { description: meta.parameters.gender, default: "自由" }),
+    avatar_artifact_uuid: Type.String({
+        description: meta.parameters.avatar_artifact_uuid,
+    }),
+    prompt: Type.String({ description: meta.parameters.prompt }),
+    trigger: Type.String({ description: meta.parameters.trigger }),
+    accessibility: Type.Union([Type.Literal("PUBLIC"), Type.Literal("PRIVATE")], {
+        default: "PUBLIC",
+        description: meta.parameters.accessibility,
+    }),
+    age: Type.Optional(Type.String({ description: meta.parameters.age })),
+    interests: Type.Optional(Type.String({ description: meta.parameters.interests })),
+    persona: Type.Optional(Type.String({ description: meta.parameters.persona })),
+    description: Type.Optional(Type.String({ description: meta.parameters.description })),
+    occupation: Type.Optional(Type.String({ description: meta.parameters.occupation })),
+});
+export const createCharacter = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+    inputSchema: createCharacterParameters,
+}, async ({ name, gender, avatar_artifact_uuid, prompt, trigger, accessibility, age, interests, persona, description, occupation, }, { apis }) => {
+    const result = await apis.tcp.createCharacter({
+        name,
+        gender,
+        avatar_artifact_uuid,
+        prompt,
+        trigger,
+        // IMAGE_EDIT uses avatar in its pipeline; pass ref_image_uuid = avatar for backend consistency
+        ref_image_uuid: avatar_artifact_uuid,
+        accessibility,
+        age,
+        interests,
+        persona,
+        description,
+        occupation,
+    });
+    return { detail: mapProfileToCharacterAssign(result) };
+});

package/bin/commands/character_elementum/create_character.cmd.zh_cn.yml

@@ -0,0 +1,43 @@
+name: create_character
+title: 创建角色
+description: |
+  创建一个新的原创角色（OC）并生成对应的角色 Token（TCP）。
+
+  角色创建后可在 make_image 中通过 @角色名 引用。
+
+  使用说明：
+    - 角色创建需要消耗电量；拥有无限电量或特殊权限的用户不受影响
+    - avatar_artifact_uuid 来自 make_image 工具返回的 artifacts[0].uuid，即角色预览图的素材 UUID
+    - prompt 只写纯视觉特征，不写性格、故事背景
+    - trigger 必须为英文识别词，供图像模型和语言模型识别角色用
+
+  字段说明：
+    - name：角色名称，最多128字符
+    - prompt：纯视觉描述，供图像模型直接读取（生理特征、服装、特殊标志）
+    - trigger：英文识别词，如 1girl, Ada Wong, black hair, red dress, spy
+    - description：供 Agent 和用户阅读，应包含外貌摘要 + 角色背景故事。多写一些可以获得更深的角色扮演体验（最多1000字符）
+
+parameters:
+  name: 角色名称（最多128字符）
+  gender: '角色性别。中文：男、女、自由、其他。English: male, female, neutral, other。默认 自由/neutral'
+  avatar_artifact_uuid: 角色头像的素材 UUID，来自 make_image 返回的 artifacts[0].uuid
+  prompt: |
+    纯视觉特征描述，供图像模型直接读取。
+    - 只写：生理特征、服装、特殊标志
+    - 不写：性格、故事、背景
+    - 示例："long black hair, red qipao dress, blue eyes, gun holster on thigh"
+  trigger: |
+    英文识别词，供语言模型和图像模型识别角色。
+    - 必须为英文
+    - 包含：性别词（1girl/1boy）、角色姓名、突出外貌特征、IP系列
+    - 示例："1girl, Ada Wong, black hair, red dress, spy, resident evil series"
+  accessibility: 可见性，PUBLIC（公开）或 PRIVATE（私密），默认 PUBLIC
+  age: 角色年龄（可选）
+  interests: 角色兴趣爱好（可选）
+  persona: 角色性格描述（可选）
+  description: |
+    角色简介，供 Agent 和用户阅读。
+    - 应包含：外貌摘要 + 角色背景故事/世界观/动机
+    - 多写一些可以获得更深的角色扮演体验和更丰富的角色互动（最多1000字符）
+    - 示例："艾达·王，黑发红裙的神秘间谍，游走于各方势力之间，真实目的无人知晓。"
+  occupation: 角色职业（可选）

package/bin/commands/character_elementum/create_elementum.cmd.en_us.yml

@@ -0,0 +1,30 @@
+name: create_elementum
+title: Create Elementum
+description: |
+  Create a new style element (Elementum) and generate an element Token (TCP).
+
+  An element represents a visual concept (scene, prop, clothing, weapon, pose, meme, etc.). After creation, it can be referenced in make_image using /ElementName.
+
+  Usage Notes:
+    - Elementum creation costs credits; users with unlimited credits or special privileges are not affected
+    - artifact_uuid comes from make_image response artifacts[0].uuid (the preview image artifact UUID)
+    - prompt is the direct image generation instruction passed to the image model
+    - description is metadata for Agents explaining what this element is and how to use it
+
+  Field Descriptions:
+    - prompt: Direct image generation instruction for the model
+    - description: Agent-facing usage guide, format: "This element represents X, use with Y, reference image shows Z"
+
+parameters:
+  name: Element name (max 128 characters)
+  artifact_uuid: Element representative image artifact UUID from make_image response artifacts[0].uuid
+  prompt: |
+    Direct image generation instruction for the model.
+    - Should be clear visual description that can be combined with other prompts
+    - Example: "Resident Evil 4 style European medieval village, dilapidated stone houses, burning bonfire, thick fog, horror atmosphere"
+  description: |
+    Agent-facing metadata explaining this element.
+    - Recommended format: "This element represents [concept], use by [method], reference image shows [description]"
+    - Example: "This element represents the RE4 abandoned village's horror atmosphere. Use with night, fog, character descriptions. Reference image is a recreation of the original village scene."
+  ref_image_uuid: Concept anchor reference image artifact UUID (optional), used for visual style anchoring
+  accessibility: Visibility, PUBLIC or PRIVATE, defaults to PUBLIC

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

@@ -0,0 +1,44 @@
+import { Type } from "@sinclair/typebox";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { mapProfileToElementumAssign } from "../../utils/tcp_mapper.js";
+import { createCommand } from "../factory.js";
+const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+    parameters: Type.Object({
+        name: Type.String(),
+        artifact_uuid: Type.String(),
+        prompt: Type.String(),
+        description: Type.String(),
+        ref_image_uuid: Type.String(),
+        accessibility: Type.String(),
+    }),
+}), import.meta);
+const createElementumParameters = Type.Object({
+    name: Type.String({ description: meta.parameters.name }),
+    artifact_uuid: Type.String({ description: meta.parameters.artifact_uuid }),
+    prompt: Type.String({ description: meta.parameters.prompt }),
+    description: Type.Optional(Type.String({ description: meta.parameters.description })),
+    ref_image_uuid: Type.Optional(Type.String({ description: meta.parameters.ref_image_uuid })),
+    accessibility: Type.Union([Type.Literal("PUBLIC"), Type.Literal("PRIVATE")], {
+        default: "PUBLIC",
+        description: meta.parameters.accessibility,
+    }),
+});
+export const createElementum = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+    inputSchema: createElementumParameters,
+}, async ({ name, artifact_uuid, prompt, description, ref_image_uuid, accessibility }, { apis }) => {
+    const result = await apis.tcp.createElementum({
+        name,
+        artifact_uuid,
+        prompt,
+        description,
+        ref_image_uuid,
+        accessibility,
+    });
+    return { detail: mapProfileToElementumAssign(result) };
+});

package/bin/commands/character_elementum/create_elementum.cmd.zh_cn.yml

@@ -0,0 +1,30 @@
+name: create_elementum
+title: 创建元素
+description: |
+  创建一个新的风格元素（Elementum），生成对应的元素 Token（TCP）。
+
+  元素代表一个可视化概念（场景、道具、服装、武器、姿势、梗图等），创建后可在 make_image 中通过 /元素名 引用。
+
+  使用说明：
+    - 元素创建需要消耗电量；拥有无限电量或特殊权限的用户不受影响
+    - artifact_uuid 来自 make_image 工具返回的 artifacts[0].uuid，即元素预览图的素材 UUID
+    - prompt 是直接传给图像模型的生图指令，应清晰、可组合
+    - description 是给 Agent 读取的元说明，告诉 Agent 这个元素是什么、怎么用
+
+  字段说明：
+    - prompt：图像模型直读的生图描述，语言应简洁精准
+    - description：Agent 读取的使用说明，格式建议："此元素表示X，使用时搭配Y，参考图为Z"
+
+parameters:
+  name: 元素名称（最多128字符）
+  artifact_uuid: 元素代表图的素材 UUID，来自 make_image 返回的 artifacts[0].uuid
+  prompt: |
+    图像模型直读的生图指令。
+    - 应为清晰的视觉描述，可组合到 make_image 提示词中
+    - 示例："生化危机4风格欧洲中世纪村庄，破旧石屋，燃烧篝火，浓雾弥漫，恐怖氛围"
+  description: |
+    供 Agent 读取的元说明，描述此元素代表什么以及如何使用。
+    - 格式建议："此元素表示[概念]，使用时[使用方法]，参考图展示[参考图说明]"
+    - 示例："此元素表示RE4废弃村庄的恐怖氛围，使用时搭配夜晚、雾气、人物描述，参考图为原版村庄截图"
+  ref_image_uuid: 概念锚定参考图的素材 UUID（可选），用于视觉风格锚定
+  accessibility: 可见性，PUBLIC（公开）或 PRIVATE（私密），默认 PUBLIC

package/bin/commands/character_elementum/list_my_characters.cmd.en_us.yml

@@ -0,0 +1,18 @@
+name: list_my_characters
+title: List My Characters
+description: |
+  List all characters created by the current user.
+
+  Returns a paginated list of the user's own characters including both PUBLIC and PRIVATE ones.
+  Useful for finding characters created in previous sessions for updates or reference.
+
+  Usage Notes:
+    - Requires NETA_TOKEN to be set
+    - Returns only the current user's characters
+    - Use keyword parameter to filter results
+    - Returns character UUID (tcp_uuid), name, avatar image, accessibility, and status
+
+parameters:
+  keyword: Search keyword to filter characters by name (optional)
+  page_index: Page index for pagination, defaults to 0
+  page_size: Number of results per page (1-50), defaults to 20

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

@@ -0,0 +1,45 @@
+import { Type } from "@sinclair/typebox";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { createCommand } from "../factory.js";
+const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+}), import.meta);
+const listMyCharactersParameters = Type.Object({
+    keyword: Type.Optional(Type.String({ description: "Search keyword to filter characters" })),
+    page_index: Type.Integer({ minimum: 0, default: 0 }),
+    page_size: Type.Integer({ minimum: 1, maximum: 50, default: 20 }),
+});
+export const listMyCharacters = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+    inputSchema: listMyCharactersParameters,
+}, async ({ keyword, page_index, page_size }, { apis }) => {
+    // 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.");
+    }
+    const result = await apis.tcp.listMyTCPs({
+        user_uuid: user.uuid,
+        parent_type: "oc",
+        keyword,
+        page_index,
+        page_size,
+    });
+    return {
+        total: result.total,
+        page_index: result.page_index,
+        page_size: result.page_size,
+        list: result.list.map((item) => ({
+            uuid: item.uuid,
+            name: item.name,
+            type: item.type === "official" ? "character" : "character",
+            avatar_img: item.config?.avatar_img,
+            accessibility: item.accessibility,
+            status: item.status,
+        })),
+    };
+});

package/bin/commands/character_elementum/list_my_characters.cmd.zh_cn.yml

@@ -0,0 +1,18 @@
+name: list_my_characters
+title: 列出我的角色
+description: |
+  列出当前用户创建的所有角色。
+
+  返回当前用户自己创建的角色分页列表，包括 PUBLIC 和 PRIVATE 角色。
+  适用于查找之前会话创建的角色，用于更新或引用。
+
+  使用说明：
+    - 需要设置 NETA_TOKEN
+    - 仅返回当前用户的角色
+    - 可使用 keyword 参数过滤结果
+    - 返回角色 UUID (tcp_uuid)、名称、头像图片、可见性和状态
+
+parameters:
+  keyword: 按名称搜索角色的关键词（可选）
+  page_index: 分页页码，默认为 0
+  page_size: 每页结果数量（1-50），默认为 20