@talesofai/neta-skills 0.6.0

package/skills/neta-suggest/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: neta-suggest
+description: Neta API research and recommendation skill — provide keyword/tag/category suggestions, validate taxonomy paths, and power multi‑mode content feeds, supporting progressive exploration from broad to precise. Use this skill when the user has no clear goal, wants topic/idea suggestions, or needs systematic content filtering by keywords/categories. It does not directly generate media (handled by neta-creative); community interactions are handled by neta-community.
+---
+
+# Neta Suggest Skill
+
+## Instructions
+
+1. For research‑type tasks like “find me some ideas”, “what’s trending now”, or “filter content by a theme/category”, follow this flow:
+2. Recommended path: **browse categories → discover tags → validate paths → fetch content** (the “Progressive Exploration” section below contains full command examples).
+3. Before content creation, use this skill to research topics/tags/categories, then hand off to `neta-creative` for concrete creation.
+4. When the user wants to like/comment or otherwise interact with specific works, switch to `neta-community`.
+
+## Prerequisites
+
+Make sure the `NETA_TOKEN` environment variable is set.
+
+Install the latest version of the Neta CLI:
+
+```bash
+neta-cli --version
+0.6.0
+```
+
+```bash
+npm i @talesofai/neta-cli@latest -g
+```
+
+```bash
+pnpm add -g @talesofai/neta-cli@latest
+```
+
+## Core capabilities
+
+### 1. suggest_keywords — keyword suggestions
+
+Provide popular search keyword suggestions based on an input prefix, helping users discover directions of interest.
+
+```bash
+neta-cli suggest_keywords --prefix "game" --size 20
+```
+
+**Parameters**
+
+- `--prefix`: keyword prefix (required)
+- `--size`: number of results, recommended 10–20 (optional)
+
+**Use cases**
+
+- User only has a vague idea.
+- Explore trending topics and themes.
+- Prepare for later precise filtering.
+
+### 2. suggest_tags — related tag suggestions
+
+Recommend related taxonomy tags based on a full keyword.
+
+```bash
+neta-cli suggest_tags --keyword "character design" --size 15
+```
+
+**Parameters**
+
+- `--keyword`: full keyword (required)
+- `--size`: number of results, recommended 10–20 (optional)
+
+**Use cases**
+
+- Understand which tags surround a topic.
+- Discover popular tags in a vertical domain.
+- Choose suitable tags for publishing content.
+
+### 3. suggest_categories — category navigation
+
+Provide navigation suggestions in a 3‑level category hierarchy, supporting step‑by‑step exploration.
+
+```bash
+# Level 1 (top‑level categories)
+neta-cli suggest_categories --level 1
+
+# Level 2 (requires parent path)
+neta-cli suggest_categories --level 2 --parent_path "Derivative Creation"
+
+# Level 3 (most granular)
+neta-cli suggest_categories --level 3 --parent_path "Derivative Creation>Fan Works"
+```
+
+**Parameters**
+
+- `--level`: category level (1/2/3) (required)
+- `--parent_path`: parent category path, required when level > 1 (optional)
+
+**Example taxonomy**
+
+```text
+Level 1
+├─ Derivative Creation
+│  ├─ Fan Works (Level 2)
+│  │  ├─ Honkai: Star Rail (Level 3)
+│  │  └─ Genshin Impact (Level 3)
+│  └─ Digital Art
+├─ Lifestyle
+└─ ...
+```
+
+**Use cases**
+
+- Systematically understand the platform’s category structure.
+- Navigate by following the tree to find specific domains.
+- Validate candidate category paths.
+
+### 4. validate_tax_path — validate taxonomy path
+
+Validate that a taxonomy path string is valid before using it.
+
+```bash
+neta-cli validate_tax_path --tax_path "Derivative Creation>Fan Works>Honkai: Star Rail"
+```
+
+**Parameters**
+
+- `--tax_path`: full taxonomy path (required)
+
+**Use cases**
+
+- Validate paths before using them in filters.
+- Ensure taxonomy paths are accurate.
+
+### 5. suggest_content — intelligent content feed
+
+Powerful content recommendation tool supporting three modes: **recommend**, **search**, and **exact**.
+
+```bash
+# Mode 1: recommend (broad exploration)
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent recommend
+
+# Mode 2: search (keyword‑based)
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent search \
+  --search_keywords "character,creativity"
+
+# Mode 3: exact (category filtering)
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent exact \
+  --tax_paths "Derivative Creation>Fan Works"
+
+# Combined filters
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent search \
+  --search_keywords "AI,painting" \
+  --tax_paths "Digital Art>Concept Art" \
+  --exclude_keywords "test,discarded"
+```
+
+**Parameters**
+
+- `--page_index`: page index, starting from 0 (default 0)
+- `--page_size`: items per page, 1–40 (default 20)
+- `--scene`: scene identifier (default `"agent_intent"`)
+- `--biz_trace_id`: session trace ID (optional)
+- `--intent`: `recommend` \| `search` \| `exact` (default `recommend`)
+- `--search_keywords`: search keywords, separated by commas (optional)
+- `--tax_paths`: taxonomy paths, separated by commas (optional)
+- `--tax_primaries`: level‑1 categories (optional)
+- `--tax_secondaries`: level‑2 categories (optional)
+- `--tax_tertiaries`: level‑3 categories (optional)
+- `--exclude_keywords`: excluded keywords (optional)
+- `--exclude_tax_paths`: excluded taxonomy paths (optional)
+
+## Progressive exploration
+
+### Standard path (broad → narrow)
+
+```text
+graph LR
+    A[Browse categories] --> B[Discover tags]
+    B --> C[Validate paths]
+    C --> D[Fetch content]
+```
+
+#### Step 1: browse category system
+
+```bash
+# View all level‑1 categories
+neta-cli suggest_categories --level 1
+# Example output: ["Derivative Creation", "Digital Art", "Lifestyle"]
+
+# Dive into an interesting category
+neta-cli suggest_categories --level 2 --parent_path "Derivative Creation"
+# Example: ["Fan Works", "Original Stories", "Interactive Fiction"]
+```
+
+#### Step 2: discover related tags
+
+```bash
+# Find tags from a keyword
+neta-cli suggest_tags --keyword "Fan Works" --size 15
+# Example: ["Honkai: Star Rail", "Genshin Impact", "Arknights"]
+
+# Use keyword suggestions to help
+neta-cli suggest_keywords --prefix "Hon" --size 10
+```
+
+#### Step 3: validate taxonomy path
+
+```bash
+neta-cli validate_tax_path \
+  --tax_path "Derivative Creation>Fan Works>Honkai: Star Rail"
+```
+
+#### Step 4: fetch recommended content
+
+```bash
+# Exact mode: filter by taxonomy only
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "Derivative Creation>Fan Works>Honkai: Star Rail" \
+  --page_size 20
+
+# Search mode: combine keyword and taxonomy
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "Honkai: Star Rail,fan art" \
+  --tax_paths "Derivative Creation>Fan Works" \
+  --page_size 20
+```
+
+## Common scenarios
+
+### Scenario 1: exploration without a clear goal
+
+User is just browsing with no specific goal.
+
+```bash
+neta-cli suggest_content \
+  --intent recommend \
+  --page_size 20
+```
+
+Tips:
+
+- Avoid constraints at first.
+- Let the system recommend based on popularity.
+- Good for serendipitous discovery.
+
+### Scenario 2: vague interest direction
+
+User has a rough topic in mind but not specific content.
+
+```bash
+# Step 1: keyword suggestions
+neta-cli suggest_keywords --prefix "game" --size 15
+
+# Step 2: tag suggestions
+neta-cli suggest_tags --keyword "game" --size 15
+
+# Step 3: search mode
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "Genshin Impact" \
+  --page_size 20
+```
+
+### Scenario 3: clear category goal
+
+```bash
+# Step 1: confirm taxonomy path
+neta-cli suggest_categories --level 1
+neta-cli suggest_categories --level 2 --parent_path "Derivative Creation"
+
+# Step 2: validate path
+neta-cli validate_tax_path \
+  --tax_path "Derivative Creation>Fan Works>Honkai: Star Rail"
+
+# Step 3: exact filter
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "Derivative Creation>Fan Works>Honkai: Star Rail" \
+  --page_size 20
+```
+
+### Scenario 4: pre‑creation research
+
+```bash
+# Step 1: understand popular tags
+neta-cli suggest_tags --keyword "character writing" --size 20
+
+# Step 2: inspect related categories
+neta-cli suggest_categories --level 2 --parent_path "Derivative Creation"
+
+# Step 3: view popular content under that category
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "character,setting" \
+  --tax_paths "Derivative Creation>Fan Works" \
+  --page_size 30
+```
+
+### Scenario 5: excluding unwanted content
+
+```bash
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "AI,painting" \
+  --tax_paths "Digital Art" \
+  --exclude_keywords "tutorial,ad" \
+  --exclude_tax_paths "Digital Art>Courses" \
+  --page_size 20
+```
+
+## Parameter combination tips
+
+### Combination 1: keyword + taxonomy
+
+```bash
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "video,editing" \
+  --tax_paths "Digital Art>Video Production" \
+  --page_size 20
+```
+
+### Combination 2: multi‑level taxonomy
+
+```bash
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "Derivative Creation>Fan Works>Honkai: Star Rail" \
+  --page_size 20
+```
+
+### Combination 3: recommend + exclusions
+
+```bash
+neta-cli suggest_content \
+  --intent recommend \
+  --exclude_keywords "tutorial, repost" \
+  --exclude_tax_paths "Courses" \
+  --page_size 20
+```
+
+### Combination 4: pagination continuity
+
+```bash
+# Page 1
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "ideas" > /tmp/page0.json
+
+# Extract biz_trace_id
+BIZ_TRACE_ID=$(cat /tmp/page0.json | jq -r '.page_data.biz_trace_id')
+
+# Page 2 (reuse same biz_trace_id)
+neta-cli suggest_content \
+  --page_index 1 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "ideas" \
+  --biz_trace_id "$BIZ_TRACE_ID"
+```
+
+## Output formats
+
+### suggest_keywords / suggest_tags / suggest_categories
+
+```json
+{
+  "suggestions": ["Suggestion 1", "Suggestion 2", "Suggestion 3"]
+}
+```
+
+### validate_tax_path
+
+Valid path:
+
+```json
+{
+  "valid": true,
+  "message": "Path is valid"
+}
+```
+
+Invalid path:
+
+```json
+{
+  "valid": false,
+  "message": "Error message"
+}
+```
+
+### suggest_content
+
+```json
+{
+  "module_list": [
+    {
+      "data_id": "module id",
+      "module_id": "module type",
+      "template_id": "template id",
+      "json_data": {}
+    }
+  ],
+  "page_data": {
+    "has_next_page": true,
+    "page_index": 0,
+    "page_size": 20,
+    "biz_trace_id": "trace id"
+  }
+}
+```
+
+## Performance tips
+
+1. **Choose page_size wisely**
+   - Exploration: 10–15 for quick iteration.
+   - Deep browsing: 20–30 to reduce page switches.
+   - Precise lookup: 20–40 to fetch enough content at once.
+2. **Cache suggestions**
+   - Cache taxonomy and tag suggestions to avoid repeated calls.
+3. **Preload next‑level categories**
+   - While the user is viewing level‑1 categories, preload level‑2 categories in the background.
+4. **Batch‑validate taxonomy paths**
+   - Validate multiple candidate paths in parallel or via a simple script.
+
+## Debugging tips
+
+1. Turn on debug logs for `suggest_content` to verify parameters.
+2. Use exact mode with only taxonomy to test whether a path actually returns content.
+3. Compare `recommend`, `search`, and `exact` with the same topic to understand their differences.
+
+## FAQ
+
+### Q1: What’s the difference between suggest_keywords and suggest_tags?
+
+- `suggest_keywords`: prefix‑based fuzzy matching, good for early exploration.
+- `suggest_tags`: relevance‑based matching on full keywords, more precise.
+
+### Q2: Why does validate_tax_path succeed but suggest_content return empty?
+
+Possible reasons:
+
+1. The taxonomy path is valid but currently has no content.
+2. Wrong intent mode (e.g., using `recommend` instead of `exact`).
+3. Other filters conflict.
+
+### Q3: How to choose the right intent?
+
+| Intent      | Use case                    | Required params           |
+|------------|-----------------------------|---------------------------|
+| `recommend`| Browsing without clear goal | None                      |
+| `search`   | Keyword‑driven search       | `search_keywords`         |
+| `exact`    | Strict category filtering   | `tax_paths` or taxonomy params |
+
+### Q4: How to use exclude_keywords and exclude_tax_paths?
+
+Use them to aggressively filter noise content, but note they can significantly reduce result count.
+
+### Q5: How to maintain biz_trace_id across pages?
+
+Always keep and reuse the **first** `biz_trace_id` returned for a given query instead of chaining from page to page.
+
+## Summary
+
+Key points for using the exploration skill:
+
+1. **Progressive exploration**: Categories → Tags → Validation → Content.
+2. **Intent selection**: `recommend` for aimless browsing, `search` for keyword queries, `exact` for strict taxonomy.
+3. **Combination filters**: combine keywords with taxonomy for precise control.
+4. **Exclusions**: use `exclude_*` parameters judiciously to filter noise.
+5. **Session continuity**: maintain a consistent `biz_trace_id` for stable paging behavior.
+
+By following these practices, you can explore and discover high‑quality content on the platform efficiently.
+

package/skills/zh_cn/neta/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: neta
+description: Neta 能力索引与路由 skill——帮助选择合适的 Neta 相关 skill（neta-space / neta-creative / neta-community / neta-suggest）。当需要了解 Neta 整体能力、决定当前任务该用哪个 skill 或从旧文档迁移时使用本 skill。
+---
+
+# Neta Skill
+
+用于**总览和路由** Neta 相关技能，而不再直接执行具体命令。
+
+> 本 skill 以前是一个「大而全」的 Neta 交互 skill，现已拆分为多个专职 skill。优先使用下方列出的子 skill；仅在需要了解能力地图或从旧文档迁移时使用本 skill。
+
+## 安装子 Skills
+
+在支持 `skills add` 的环境中，可以按需安装：
+
+```bash
+# 空间与世界观
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-space
+
+# 内容创作（图片/视频/歌曲/MV）
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-creative
+
+# 社区浏览与互动
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-community
+
+# 内容调研与推荐
+npx skills add talesofai/neta-skills/skills/zh_cn/neta-suggest
+```
+
+## Instructions
+
+1. **判断当前任务类型**：先根据用户需求判断是「空间游览」「内容创作」「社区互动」「内容调研/推荐」中的哪一类。
+2. **选择对应子 skill**：
+   - 空间/世界观/玩法结构 → 使用 `neta-space`
+   - 生成图片/视频/歌曲/MV、拆解创作思路 → 使用 `neta-creative`
+   - 浏览推荐流、查看作品详情、点赞互动、社区视角浏览 → 使用 `neta-community`
+   - 关键词/标签/分类/推荐流调研、从宽到窄找题材 → 使用 `neta-suggest`
+3. **仅在边界不清或需要解释时使用本 skill**，帮用户说明应该选择哪一个子 skill。
+
+## 能力地图与子 Skill 说明
+
+### 1. 空间与世界观：`neta-space`
+
+负责：
+- 列出可供游览的空间
+- 获取空间/标签的世界观设定（lore）
+- 获取空间的子空间、空间内角色与玩法 collections
+
+适用场景：
+- 用户提到「世界观/宇宙/空间/场景设定」
+- 想按空间/活动来浏览玩法和内容
+
+详见 `skills/zh_cn/neta-space/SKILL.md`。
+
+### 2. 内容创作：`neta-creative`
+
+负责：
+- 生成图片、视频、歌曲、MV
+- 移除图片背景
+- 角色搜索与详情（创作语境下使用）
+- 通过 `read_collection` 从作品反向拆解创作思路
+
+适用场景：
+- 用户要「生成/修改 图片/视频/歌曲/MV」
+- 想根据角色/设定进行创作
+- 想分析某个作品的创作思路
+
+详见 `skills/zh_cn/neta-creative/SKILL.md`。
+
+### 3. 社区浏览与互动：`neta-community`
+
+负责：
+- 获取互动推荐流
+- 查看作品详情（社区语境下）
+- 点赞等社区互动
+- 基于标签/角色的社区内容浏览
+
+适用场景：
+- 用户想「随便看看大家在玩什么」「刷推荐流」
+- 想对作品进行点赞等互动
+
+详见 `skills/zh_cn/neta-community/SKILL.md`。
+
+### 4. 内容调研与推荐引擎：`neta-suggest`
+
+负责：
+- 关键词建议（`suggest_keywords`）
+- 标签建议（`suggest_tags`）
+- 分类体系导航与路径验证（`suggest_categories` / `validate_tax_path`）
+- 多模式内容推荐流（`suggest_content`）
+
+适用场景：
+- 用户没有明确目标，只是「找个方向」「找题材」
+- 想了解热门标签/分类结构/高热内容分布
+- 内容创作前的系统性调研
+
+详见 `skills/zh_cn/neta-suggest/SKILL.md`。
+
+## 迁移说明（从旧 neta skill）
+
+如果遇到旧文档或指令中引用了 `neta` skill 下的命令，请按下表迁移到新的专职 skill：
+
+| 旧能力                     | 新 skill            |
+|----------------------------|--------------------|
+| 空间/标签世界观、空间游览 | `neta-space`       |
+| 图片/视频/歌曲/MV 创作     | `neta-creative`    |
+| 作品详情、推荐流、点赞互动 | `neta-community`   |
+| 关键词/标签/分类/推荐调研 | `neta-suggest`     |
+
+今后的实现中，请优先调用这些子 skill，不再在本 skill 中添加新的命令示例。
+