@talesofai/neta-skills 0.6.0

package/skills/zh_cn/neta/references/interactive-feed.md

@@ -0,0 +1,377 @@
+# 互动玩法推荐列表最佳实践
+
+## 概述
+
+`request_interactive_feed` 是一个强大的互动玩法内容推荐接口，支持多种场景的自动判断。本文档介绍如何高效使用这个技能。
+
+## 核心概念
+
+### 场景自动判断机制
+
+接口根据传入参数自动判断场景，无需手动指定 Scene 枚举：
+
+- **提供 `collection_uuid`**：进入相关性场景
+- **提供 `target_user_uuid`**：进入个人主页场景
+
+
+- **无特殊参数**：默认首页互动流主模式
+
+### 关键参数说明
+
+- **`collection_uuid`**：最重要的场景控制参数
+  - `page_index=0`：获取单个作品的详细信息（单体接口）
+  - `page_index>0`：获取与该作品相关的其他作品（相关推荐）
+
+- **`page_index`**：不仅控制分页，还影响场景类型
+  - `0`：通常用于获取详情或首屏
+  - `>0`：用于获取相关推荐或继续浏览
+
+- **`biz_trace_id`**：保持会话连续性
+  - 首次请求：不传或传空
+  - 后续请求：使用上一次返回的 `biz_trace_id`
+
+## 常见使用场景
+
+### 1. 获取首页推荐列表（默认场景）
+
+最基础的用法，用于浏览首页互动流。
+
+```bash
+# 获取首页推荐
+neta-cli request_interactive_feed --page_index 0 --page_size 10
+```
+
+**特点：**
+- 不需要额外参数
+- 返回个性化的推荐内容
+- 适合用户打开 APP 时的默认展示
+
+### 2. 查看单个作品详情
+
+当需要获取某个作品的完整信息时使用。
+
+```bash
+# 获取单个作品详情
+neta-cli read_collection --uuid "目标作品 UUID"
+```
+
+### 3. 获取相似作品推荐
+
+基于某个作品获取相关推荐内容。
+
+```bash
+# 获取相似作品（从第 1 页开始）
+neta-cli request_interactive_feed \
+  --page_index 1 \
+  --page_size 10 \
+  --collection_uuid "种子作品 UUID"
+```
+
+**特点：**
+- 基于内容相似度推荐
+- 适合"看了又看"场景
+
+### 4. 查看原作及同款子作品
+
+查看某个作品的原作以及所有同款二创作品。
+
+```bash
+# 获取原作及全部同款
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 20 \
+  --scene 'relation_feed_child' \
+  --target_collection_uuid "目标合集 UUID" \
+  --collection_uuid "目标合集 UUID"
+```
+
+**特点：**
+- 需要同时提供 `collection_uuid` 和 `target_collection_uuid`
+- 指定 `scene='relation_feed_child'`
+- 返回原作信息和所有同款作品
+
+### 5. 查看用户个人主页
+
+获取指定用户的作品集。
+
+```bash
+# 获取用户主页
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 20 \
+  --scene 'personal_feed' \
+  --target_user_uuid "用户 UUID"
+```
+
+**特点：**
+- 必须提供 `target_user_uuid`
+- 指定 `scene='personal_feed'`
+- 返回该用户的所有作品
+
+### 6. 评论区查看子作品
+
+在评论区查看某个作品的子作品列表。
+
+```bash
+# 获取评论区子作品
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 20 \
+  --scene 'relation_feed_same' \
+  --collection_uuid "父作品 UUID"
+```
+
+**特点：**
+- 指定 `scene='relation_feed_same'`
+- 基于父子关系筛选
+- 适合"同系列作品"场景
+
+## 翻页连续性维护
+
+为了保持推荐结果的一致性和连续性，需要正确使用 `biz_trace_id`。
+
+### 正确的翻页流程
+
+**核心原则：使用第一次请求返回的 biz_trace_id，后续所有请求都使用这个值。**
+
+```bash
+# 第 1 次请求（首页）
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 10 > /tmp/page0.json
+
+# 从返回结果中提取 biz_trace_id
+BIZ_TRACE_ID=$(cat /tmp/page0.json | jq -r '.page_data.biz_trace_id')
+
+# 第 2 次请求（下一页）- 使用相同的 biz_trace_id
+neta-cli request_interactive_feed \
+  --page_index 1 \
+  --page_size 10 \
+  --biz_trace_id "$BIZ_TRACE_ID"
+
+# 第 3 次请求 - 继续使用同一个 biz_trace_id
+neta-cli request_interactive_feed \
+  --page_index 2 \
+  --page_size 10 \
+  --biz_trace_id "$BIZ_TRACE_ID"
+```
+
+### 错误示例
+
+**❌ 错误 1：每次都用上一次的返回值**
+```bash
+# 第 1 页
+neta-cli request_interactive_feed --page_index 0 > /tmp/page0.json
+BIZ_TRACE_ID_0=$(cat /tmp/page0.json | jq -r '.page_data.biz_trace_id')
+
+# 第 2 页（正确：使用第 1 页返回的）
+neta-cli request_interactive_feed --page_index 1 --biz_trace_id "$BIZ_TRACE_ID_0" > /tmp/page1.json
+BIZ_TRACE_ID_1=$(cat /tmp/page1.json | jq -r '.page_data.biz_trace_id')
+
+# 第 3 页（错误：使用了第 2 页返回的，应该一直用第 1 页的）
+neta-cli request_interactive_feed --page_index 2 --biz_trace_id "$BIZ_TRACE_ID_1"
+```
+
+**❌ 错误 2：完全不传 biz_trace_id**
+```bash
+# 每次都开启新的会话，推荐内容会不连续
+neta-cli request_interactive_feed --page_index 0
+neta-cli request_interactive_feed --page_index 1  # 没有 biz_trace_id
+neta-cli request_interactive_feed --page_index 2  # 没有 biz_trace_id
+```
+
+## 参数组合技巧
+
+### 组合 1：基础浏览
+
+```bash
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 10
+```
+
+### 组合 2：个人主页 + 翻页
+
+```bash
+# 第 1 页
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 20 \
+  --scene 'personal_feed' \
+  --target_user_uuid "user-uuid"
+
+# 第 2 页（使用返回的 biz_trace_id）
+neta-cli request_interactive_feed \
+  --page_index 1 \
+  --page_size 20 \
+  --scene 'personal_feed' \
+  --target_user_uuid "user-uuid" \
+  --biz_trace_id "从上一页获取"
+```
+
+### 组合 3：精确场景控制
+
+```bash
+# 查看某作品的同款二创
+neta-cli request_interactive_feed \
+  --page_index 0 \
+  --page_size 15 \
+  --scene 'relation_feed_same' \
+  --collection_uuid "parent-work-uuid"
+```
+
+## 输出数据结构
+
+### module_list 模块类型
+
+返回的 `module_list` 包含不同类型的模块：
+
+1. **NORMAL** - 普通作品模块
+   - `template_id: "NORMAL"`
+   - 包含完整的作品信息、封面图、作者信息等
+
+2. **DRAFT** - 草稿模块
+   - `template_id: "DRAFT"`
+   - 用户未完成的创作草稿
+
+3. **SPACE** - 空间入口模块
+   - `template_id: "into_space"`
+   - 引导用户进入特定空间
+
+### 关键数据字段
+
+每个模块项包含以下字段：
+
+- **data_id**: 模块唯一标识
+- **module_id**: 模块类型（NORMAL/DRAFT/SPACE）
+- **template_id**: 模板类型
+- **json_data**: 具体数据对象，根据 template_id 不同包含不同的字段
+  - uuid: 作品 UUID
+  - name: 作品名称
+  - coverUrl: 封面图 URL
+  - 等其他字段...
+
+## 性能优化建议
+
+### 1. 合理设置 page_size
+
+- **首页浏览**：10-20（平衡加载速度和流量）
+- **个人主页**：20-30（用户有明确目的）
+- **相关推荐**：10-15（快速试错）
+- **单个详情**：1（只获取一个）
+
+### 2. 缓存策略
+
+缓存推荐结果，避免重复请求：
+
+```bash
+# 缓存第一页结果
+neta-cli request_interactive_feed --page_index 0 > /tmp/feed_cache.json
+
+# 使用缓存（从文件读取）
+cat /tmp/feed_cache.json | jq '.module_list'
+```
+
+**实际应用中可以使用文件系统或数据库来缓存结果。**
+
+### 3. 预加载策略
+
+在用户浏览当前页时，后台预加载下一页：
+
+```bash
+# 获取当前页
+neta-cli request_interactive_feed --page_index 0 > /tmp/page0.json &
+
+# 同时预加载下一页（后台任务）
+neta-cli request_interactive_feed --page_index 1 > /tmp/page1.prefetch.json &
+wait
+```
+
+**这样可以提升用户体验，减少等待时间。**
+
+## 调试技巧
+
+### 1. 验证场景是否正确
+
+检查返回的 `module_list` 内容是否符合预期：
+- 首页应该有多样化的内容
+- 个人主页应该只有该用户的作品
+- 相关推荐应该与种子作品相似
+
+### 2. 检查 biz_trace_id 一致性
+
+验证请求和返回的 biz_trace_id 是否一致：
+
+```bash
+# 请求时指定 biz_trace_id
+neta-cli request_interactive_feed \
+  --page_index 1 \
+  --biz_trace_id "your-biz-trace-id" > /tmp/response.json
+
+# 检查返回的 biz_trace_id
+cat /tmp/response.json | jq '.page_data.biz_trace_id'
+
+# 两者应该相同（除非服务端主动更新）
+```
+
+### 3. 使用日志调试
+
+```bash
+# 开启 debug 日志查看请求参数
+DEBUG=* neta-cli request_interactive_feed --page_index 0
+```
+
+## 常见问题
+
+### Q1: 为什么返回的结果为空？
+
+**可能原因：**
+- 场景参数组合不正确
+- `collection_uuid` 或 `target_user_uuid` 无效
+- 该场景下确实没有内容
+
+**解决方案：**
+- 先尝试默认场景（不加任何参数）
+- 验证 UUID 是否有效
+- 检查 `page_index` 是否过大
+
+### Q2: biz_trace_id 应该用哪一个？
+
+**原则：使用第一次请求返回的 biz_trace_id**
+
+```bash
+# ✅ 正确：一直使用第一次返回的 biz_trace_id
+neta-cli request_interactive_feed --page_index 0 > /tmp/page0.json
+BIZ_TRACE_ID=$(cat /tmp/page0.json | jq -r '.page_data.biz_trace_id')
+
+neta-cli request_interactive_feed --page_index 1 --biz_trace_id "$BIZ_TRACE_ID"
+neta-cli request_interactive_feed --page_index 2 --biz_trace_id "$BIZ_TRACE_ID"
+
+# ❌ 错误：每次都用上一次的返回值
+neta-cli request_interactive_feed --page_index 0 > /tmp/page0.json
+BIZ_TRACE_ID_0=$(cat /tmp/page0.json | jq -r '.page_data.biz_trace_id')
+
+neta-cli request_interactive_feed --page_index 1 --biz_trace_id "$BIZ_TRACE_ID_0" > /tmp/page1.json
+BIZ_TRACE_ID_1=$(cat /tmp/page1.json | jq -r '.page_data.biz_trace_id')
+
+neta-cli request_interactive_feed --page_index 2 --biz_trace_id "$BIZ_TRACE_ID_1"  # 错误！应该用 BIZ_TRACE_ID_0
+```
+
+### Q3: 如何区分 NORMAL 模块中的不同内容类型？
+
+通过 `json_data` 中的字段判断：
+- 检查 `has_video` 判断是否有视频
+- 检查 `bgm_uuid` 判断是否有背景音乐
+- 检查 `is_interactive` 判断是否是交互式作品
+
+## 总结
+
+使用 `request_interactive_feed` 的关键点：
+
+1. **理解场景自动判断**：通过参数组合自动切换场景
+2. **掌握 page_index 语义**：0 通常是详情，>0 是推荐
+3. **维护 biz_trace_id**：保持会话连续性
+4. **合理设置 page_size**：根据场景选择合适的大小
+5. **善用 scene 参数**：精确控制特定场景
+
+通过遵循这些最佳实践，你可以更高效地使用这个技能，获得更好的推荐效果。

package/skills/zh_cn/neta/references/social-interactive.md

@@ -0,0 +1,73 @@
+## 社交互动技能
+
+### 1. 社区互动
+
+#### like_collection - 点赞/取消点赞作品
+
+```bash
+# 点赞作品
+neta-cli like_collection --uuid "目标作品 UUID"
+
+# 取消点赞
+neta-cli like_collection --uuid "目标作品 UUID" --is_cancel true
+```
+
+#### favor_collection - 收藏/取消收藏作品
+
+```bash
+# 收藏作品
+neta-cli favor_collection --uuid "目标作品 UUID"
+
+# 取消收藏
+neta-cli favor_collection --uuid "目标作品 UUID" --is_cancel true
+```
+
+#### create_comment - 发布评论
+
+支持对作品、评论发布评论
+
+**参数说明：**
+- `content`: 评论内容（1-500 字）
+- `parent_uuid`: 父级对象 UUID
+- `parent_type`: 父级类型（collection/comment）
+
+```bash
+# 对作品发表评论（主评论）
+neta-cli create_comment \
+  --parent_uuid "目标作品 UUID" \
+  --parent_type "collection" \
+  --content "老师，这个作品真的好棒啊！"
+
+# 对评论进行回复（楼中楼）
+neta-cli create_comment \
+  --parent_uuid "目标评论 UUID" \
+  --parent_type "comment" \
+  --content "同意楼上的观点！"
+```
+
+**注意：** `parent_type` 只支持 `collection`（作品）和 `comment`（评论），不支持角色或元素。
+
+### 2. 用户互动
+
+#### subscribe_user - 关注/取消关注用户
+
+```bash
+# 关注用户
+neta-cli subscribe_user --user_uuid "目标用户 UUID" --is_cancel false
+
+# 取消关注
+neta-cli subscribe_user --user_uuid "目标用户 UUID" --is_cancel true
+```
+
+#### get_subscribe_list - 查看我关注的人
+
+```bash
+neta-cli get_subscribe_list --page_index 0 --page_size 10
+```
+
+#### get_fan_list - 查看我的粉丝
+
+```bash
+neta-cli get_fan_list --page_index 0 --page_size 10
+```
+

package/skills/zh_cn/neta/references/song-creation.md

@@ -0,0 +1,247 @@
+# 歌曲生成最佳实践
+
+适用于 `make_song` 命令。
+
+---
+
+## 提示词结构
+
+**推荐格式：**
+```
+[音乐风格] + [情绪/氛围] + [节奏/速度] + [乐器/元素] + [主题/场景]
+```
+
+**示例：**
+```
+欢快的 J-Pop 风格，充满活力的少女感，中快节奏，电子合成器和鼓点，关于友情和梦想的主题
+```
+
+---
+
+## 音乐风格参考
+
+| 风格 | 描述示例 |
+|------|----------|
+| J-Pop | "欢快的 J-Pop，青春活力，电子合成器" |
+| 民谣 | "温柔的城市民谣，吉他伴奏，清新自然" |
+| 电子 | "动感电子舞曲，强烈节拍，未来感" |
+| 摇滚 | "激情摇滚，电吉他独奏，充满力量" |
+| 古典 | "优雅的钢琴曲，舒缓节奏，浪漫氛围" |
+| R&B | "节奏蓝调，慵懒嗓音，都市夜景" |
+| 古风 | "中国风，古筝笛子，诗意悠扬" |
+
+---
+
+## 情绪/氛围词汇
+
+| 情绪 | 示例描述 |
+|------|----------|
+| 欢快 | "充满活力"、"阳光明媚"、"积极向上" |
+| 忧伤 | "淡淡的忧伤"、"怀念过去"、"雨夜" |
+| 浪漫 | "温柔甜蜜"、"月光下"、"初恋感觉" |
+| 激昂 | "热血沸腾"、"战斗意志"、"永不放弃" |
+| 宁静 | "平和安详"、"清晨森林"、"冥想" |
+| 神秘 | "神秘莫测"、"古老传说"、"魔法氛围" |
+
+---
+
+## 歌词格式模板
+
+```
+[Verse 1]
+主歌第一段，叙述故事背景
+4-8 行，建议押韵
+
+[Pre-Chorus]
+预副歌，情绪铺垫
+2-4 行
+
+[Chorus]
+副歌，高潮部分，记忆点
+4-8 行，重复性强
+
+[Verse 2]
+主歌第二段，故事发展
+4-8 行
+
+[Chorus]
+副歌重复
+
+[Bridge]
+桥段，情绪转折或升华
+2-4 行
+
+[Chorus]
+副歌最后一次（可升调）
+
+[Outro]
+结尾，渐弱
+2-4 行
+```
+
+---
+
+## 歌词示例
+
+```
+[Verse 1]
+清晨的阳光洒在窗前
+微风吹过熟悉的街道
+想起昨天你的笑脸
+心中涌起温暖感觉
+
+[Pre-Chorus]
+时光悄悄流转
+我们的故事继续
+
+[Chorus]
+一起走过春夏秋冬
+手牵手看遍世间风景
+无论未来多么遥远
+这份友情永远不变
+
+[Verse 2]
+放学后的咖啡厅角落
+分享着彼此的梦想
+你说要成为歌手
+我说要环游世界
+
+[Chorus]
+一起走过春夏秋冬
+手牵手看遍世间风景
+无论未来多么遥远
+这份友情永远不变
+
+[Bridge]
+即使有一天各奔东西
+这份回忆永远珍藏
+
+[Chorus]
+一起走过春夏秋冬
+手牵手看遍世间风景
+无论未来多么遥远
+这份友情永远不变
+
+[Outro]
+谢谢你陪伴的每一天
+我们的故事继续书写
+```
+
+---
+
+## 常见用例
+
+### 角色主题曲
+
+```bash
+neta-cli make_song \
+  --prompt "角色专属主题曲，J-Pop 风格，活泼可爱，魔法少女感，电子合成器，明快节奏" \
+  --lyrics "[歌词内容...]"
+```
+
+### 背景音乐
+
+```bash
+neta-cli make_song \
+  --prompt "轻柔的钢琴背景音乐，宁静安详，适合阅读，舒缓节奏" \
+  --lyrics "[纯音乐可省略歌词或使用简单的哼唱]"
+```
+
+### 战斗曲
+
+```bash
+neta-cli make_song \
+  --prompt "激昂的战斗曲，摇滚风格，电吉他，强烈鼓点，热血沸腾" \
+  --lyrics "[Verse 1]
+  燃烧吧斗志
+  冲破黑暗黎明
+  ..."
+```
+
+### 抒情歌曲
+
+```bash
+neta-cli make_song \
+  --prompt "温柔的抒情歌曲，民谣风格，吉他伴奏，清新自然，淡淡忧伤" \
+  --lyrics "[Verse 1]
+  雨后的街道
+  一个人走着
+  ..."
+```
+
+---
+
+## 歌词写作技巧
+
+### 1. 押韵
+
+句尾押韵让歌曲更流畅：
+```
+清晨的阳光洒在窗前 (qián)
+微风吹过熟悉的街道 (dào)
+想起昨天你的笑脸 (liǎn)
+心中涌起温暖感觉 (jué)
+```
+
+### 2. 意象具体
+
+使用具体的意象而非抽象概念：
+- ❌ "我很开心"
+- ✅ "阳光洒在窗前，微风吹过街道"
+
+### 3. 情感递进
+
+从主歌到副歌情感逐渐升华：
+```
+Verse: 叙述故事
+Pre-Chorus: 情绪铺垫
+Chorus: 情感爆发
+```
+
+### 4. 重复记忆点
+
+副歌要有容易记住的核心句：
+```
+一起走过春夏秋冬
+手牵手看遍世间风景
+```
+
+---
+
+## 参数限制
+
+| 参数 | 限制 |
+|------|------|
+| prompt | 10-2000 字符 |
+| lyrics | 10-3500 字符 |
+
+---
+
+## 常见问题
+
+### Q: 歌词太长怎么办？
+
+**A:** 
+- 精简到 3500 字符以内
+- 优先保留主歌和副歌
+- 可以省略部分重复段落
+
+### Q: 纯音乐如何生成？
+
+**A:**
+- 歌词可以填写简单的哼唱词（如"啦~"）
+- 或者填写简短的氛围描述
+- 重点在 prompt 中描述音乐风格
+
+### Q: 如何保持风格一致性？
+
+**A:**
+- 保存成功的 prompt 模板
+- 使用相似的风格描述词汇
+- 参考同类型的成功作品
+
+---
+
+## 相关文档
+
+- [歌曲 MV](./song-mv.md) - 结合歌曲和视频制作完整 MV