@talesofai/neta-skills 0.6.0

package/skills/zh_cn/neta/references/community-exploration.md

@@ -0,0 +1,636 @@
+# 玩法内容探索最佳实践
+
+## 概述
+
+玩法内容探索技能提供了一套完整的内容发现和筛选工具，支持从宽泛到精确的渐进式探索。包括关键词建议、标签推荐、分类导航和智能内容流四大功能模块。
+
+## 核心技能
+
+### 1. suggest_keywords - 获取搜索关键词建议
+
+基于输入前缀提供热门搜索词建议，帮助用户发现感兴趣的内容方向。
+
+```bash
+neta-cli suggest_keywords --prefix "游戏" --size 20
+```
+
+**参数说明：**
+- `--prefix`: 关键词前缀（必填）
+- `--size`: 返回数量，建议 10-20（可选，默认值根据系统配置）
+
+**适用场景：**
+- 用户只有模糊想法时
+- 探索热门话题和趋势
+- 为后续精确筛选做准备
+
+### 2. suggest_tags - 获取相关标签建议
+
+基于完整关键词推荐相关的 tax 标签。
+
+```bash
+neta-cli suggest_tags --keyword "角色塑造" --size 15
+```
+
+**参数说明：**
+- `--keyword`: 完整的关键词（必填）
+- `--size`: 返回数量，建议 10-20（可选）
+
+**适用场景：**
+- 了解某个主题的相关标签
+- 发现垂直领域的热门标签
+- 为内容创作选择合适的话题标签
+
+### 3. suggest_categories - 获取分类层级导航
+
+提供三级分类体系的导航建议，支持逐级深入探索。
+
+```bash
+# 获取一级分类（顶层分类）
+neta-cli suggest_categories --level 1
+
+# 获取二级分类（需要父级路径）
+neta-cli suggest_categories --level 2 --parent_path "衍生创作类"
+
+# 获取三级分类（最细粒度）
+neta-cli suggest_categories --level 3 --parent_path "衍生创作类>同人二创"
+```
+
+**参数说明：**
+- `--level`: 分类层级（1/2/3）（必填）
+- `--parent_path`: 父级分类路径，level>1 时必填（可选）
+
+**分类体系：**
+```
+一级分类（Level 1）
+├─ 衍生创作类
+│  ├─ 同人二创（Level 2）
+│  │  ├─ 崩坏星穹铁道（Level 3）
+│  │  └─ 原神（Level 3）
+│  └─ 数字艺术
+├─ 生活方式
+└─ ...
+```
+
+**适用场景：**
+- 系统性了解平台内容分类
+- 按图索骥查找特定领域内容
+- 验证分类路径的有效性
+
+### 4. validate_tax_path - 验证分类路径
+
+检查分类路径是否有效，避免使用不存在的分类。
+
+```bash
+neta-cli validate_tax_path --tax_path "衍生创作类>热门 IP>崩坏星穹铁道"
+```
+
+**参数说明：**
+- `--tax_path`: 完整的分类路径（必填）
+
+**适用场景：**
+- 在使用分类路径前进行验证
+- 确保分类路径的准确性
+
+### 5. suggest_content - 智能内容流引擎
+
+强大的内容推荐工具，支持三种模式：推荐、搜索、精确筛选。
+
+```bash
+# 模式 1：推荐模式（广泛探索）
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent recommend
+
+# 模式 2：搜索模式（关键词搜索）
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent search \
+  --search_keywords "角色,创意"
+
+# 模式 3：精确模式（分类筛选）
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent exact \
+  --tax_paths "衍生创作类>同人二创"
+
+# 组合使用（多条件筛选）
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --scene agent_intent \
+  --intent search \
+  --search_keywords "AI,绘画" \
+  --tax_paths "数字艺术>概念设计" \
+  --exclude_keywords "测试,废弃"
+```
+
+**参数说明：**
+- `--page_index`: 页码，从 0 开始（默认 0）
+- `--page_size`: 每页数量，范围 1-40（默认 20）
+- `--scene`: 场景标识（默认 "agent_intent"）
+- `--biz_trace_id`: 会话追踪 ID（可选）
+- `--intent`: 意图类型 `recommend` | `search` | `exact`（默认 recommend）
+- `--search_keywords`: 搜索关键词，多个之间用英文逗号分隔（可选）
+- `--tax_paths`: 分类路径，多个之间用英文逗号分隔（可选）
+- `--tax_primaries`: 一级分类，多个之间用英文逗号分隔（可选）
+- `--tax_secondaries`: 二级分类，多个之间用英文逗号分隔（可选）
+- `--tax_tertiaries`: 三级分类，多个之间用英文逗号分隔（可选）
+- `--exclude_keywords`: 排除关键词，多个之间用英文逗号分隔（可选）
+- `--exclude_tax_paths`: 排除分类路径，多个之间用英文逗号分隔（可选）
+
+## 渐进式探索流程
+
+### 标准探索路径（从宽到窄）
+
+```
+graph LR
+    A[浏览分类] --> B[发现标签]
+    B --> C[验证路径]
+    C --> D[获取内容]
+```
+
+#### 步骤 1：浏览分类体系
+
+先了解整体的内容分类结构：
+
+```bash
+# 查看所有一级分类
+neta-cli suggest_categories --level 1
+# 输出示例：["衍生创作类", "数字艺术", "生活方式"]
+
+# 对感兴趣的分类深入查看
+neta-cli suggest_categories --level 2 --parent_path "衍生创作类"
+# 输出示例：["同人二创", "原创故事", "互动小说"]
+```
+
+#### 步骤 2：发现相关标签
+
+基于分类或关键词发现热门标签：
+
+```bash
+# 基于关键词找标签
+neta-cli suggest_tags --keyword "同人二创" --size 15
+# 输出示例：["崩坏星穹铁道", "原神", "明日方舟"]
+
+# 或者用关键词建议辅助
+neta-cli suggest_keywords --prefix "崩" --size 10
+# 输出示例：["崩坏星穹铁道", "崩坏 3", "崩坏学园"]
+```
+
+#### 步骤 3：验证分类路径
+
+在正式使用前验证路径有效性：
+
+```bash
+neta-cli validate_tax_path \
+  --tax_path "衍生创作类>同人二创>崩坏星穹铁道"
+# 如果有效会返回成功，否则提示错误
+```
+
+#### 步骤 4：获取推荐内容
+
+使用验证过的路径获取内容：
+
+```bash
+# 精确模式：按分类筛选
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "衍生创作类>同人二创>崩坏星穹铁道" \
+  --page_size 20
+
+# 或者搜索模式：结合关键词
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "崩坏星穹铁道，同人" \
+  --tax_paths "衍生创作类>同人二创" \
+  --page_size 20
+```
+
+## 常见使用场景
+
+### 场景 1：无明确目标的探索
+
+用户只是随便看看，没有特定目标。
+
+```bash
+# 策略：使用推荐模式，广泛浏览
+neta-cli suggest_content \
+  --intent recommend \
+  --page_size 20
+```
+
+**技巧：**
+- 不设置任何筛选条件
+- 让算法根据热度推荐
+- 适合发现意外惊喜
+
+### 场景 2：有模糊兴趣方向
+
+用户对某个主题感兴趣，但不确定具体内容。
+
+```bash
+# 步骤 1：先用关键词建议发现方向
+neta-cli suggest_keywords --prefix "游" --size 15
+
+# 步骤 2：基于发现的关键词找标签
+neta-cli suggest_tags --keyword "游戏" --size 15
+
+# 步骤 3：使用搜索模式探索
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "原神" \
+  --page_size 20
+```
+
+**技巧：**
+- 从宽泛的关键词开始
+- 逐步缩小范围
+- 结合标签和关键词
+
+### 场景 3：有明确的分类目标
+
+用户明确想看某个分类的内容。
+
+```bash
+# 步骤 1：确认分类路径
+neta-cli suggest_categories --level 1
+neta-cli suggest_categories --level 2 --parent_path "衍生创作类"
+
+# 步骤 2：验证路径
+neta-cli validate_tax_path \
+  --tax_path "衍生创作类>同人二创>崩坏星穹铁道"
+
+# 步骤 3：精确筛选
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "衍生创作类>同人二创>崩坏星穹铁道" \
+  --page_size 20
+```
+
+**技巧：**
+- 先验证路径再使用
+- 使用 exact 模式确保精确匹配
+- 可以组合多个分类路径
+
+### 场景 4：内容创作前的调研
+
+准备创作内容，需要了解热门标签和分类。
+
+```bash
+# 步骤 1：了解热门标签
+neta-cli suggest_tags --keyword "角色塑造" --size 20
+
+# 步骤 2：了解相关分类
+neta-cli suggest_categories --level 2 --parent_path "衍生创作类"
+
+# 步骤 3：查看该分类下的热门内容
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "角色,设定" \
+  --tax_paths "衍生创作类>同人二创" \
+  --page_size 30
+```
+
+**技巧：**
+- 全面了解后再创作
+- 参考热门标签提高曝光
+- 选择合适的分类投放
+
+### 场景 5：排除特定内容
+
+想看某类内容，但想排除某些元素。
+
+```bash
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "AI,绘画" \
+  --tax_paths "数字艺术" \
+  --exclude_keywords "教程,广告" \
+  --exclude_tax_paths "数字艺术>课程培训" \
+  --page_size 20
+```
+
+**技巧：**
+- 使用 `exclude_keywords` 过滤不想要的内容
+- 使用 `exclude_tax_paths` 排除特定分类
+- 正向筛选 + 负向排除结合
+
+## 参数组合技巧
+
+### 组合 1：关键词 + 分类双重筛选
+
+```bash
+neta-cli suggest_content \
+  --intent search \
+  --search_keywords "视频,剪辑" \
+  --tax_paths "数字艺术>视频制作" \
+  --page_size 20
+```
+
+**效果：** 在"视频制作"分类下搜索包含"视频"和"剪辑"的内容
+
+### 组合 2：多级分类组合
+
+```bash
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "衍生创作类>同人二创>崩坏星穹铁道" \
+  --page_size 20
+```
+
+**效果：** 精确筛选三级分类，等价于 `tax_paths: "衍生创作类>同人二创>崩坏星穹铁道"`
+
+### 组合 3：推荐模式 + 排除条件
+
+```bash
+neta-cli suggest_content \
+  --intent recommend \
+  --exclude_keywords "教程,搬运" \
+  --exclude_tax_paths "课程类" \
+  --page_size 20
+```
+
+**效果：** 智能推荐，但排除教程和搬运内容
+
+### 组合 4：翻页连续性
+
+```bash
+# 第 1 页
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "创意"
+
+# 保存返回的 biz_trace_id（假设返回值为 "abc123"）
+
+# 第 2 页（使用第 1 页返回的 biz_trace_id）
+neta-cli suggest_content \
+  --page_index 1 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "创意" \
+  --biz_trace_id "abc123"
+```
+
+**效果：** 保持搜索结果的一致性
+
+## 输出数据结构
+
+### suggest_keywords / suggest_tags / suggest_categories
+
+返回建议列表：
+
+```json
+{
+  "suggestions": ["建议 1", "建议 2", "建议 3"]
+}
+```
+
+### validate_tax_path
+
+验证分类路径是否有效：
+
+```json
+{
+  "valid": true,
+  "message": "路径有效"
+}
+```
+
+或无效时：
+
+```json
+{
+  "valid": false,
+  "message": "错误信息"
+}
+```
+
+### suggest_content
+
+返回推荐内容列表和分页信息：
+
+```json
+{
+  "module_list": [
+    {
+      "data_id": "模块 ID",
+      "module_id": "模块类型",
+      "template_id": "模板 ID",
+      "json_data": {}
+    }
+  ],
+  "page_data": {
+    "has_next_page": true,
+    "page_index": 0,
+    "page_size": 20,
+    "biz_trace_id": "会话追踪 ID"
+  }
+}
+```
+
+## 性能优化建议
+
+### 1. 合理设置 page_size
+
+- **探索阶段**：10-15（快速试错）
+- **深入浏览**：20-30（减少翻页次数）
+- **精确查找**：20-40（一次性获取足够内容）
+
+### 2. 缓存建议结果
+
+缓存分类、标签等建议结果，避免重复请求：
+
+```bash
+# 第一次请求
+neta-cli suggest_categories --level 1 > /tmp/categories_level1.json
+
+# 后续使用缓存（示例：从缓存文件读取）
+cat /tmp/categories_level1.json
+```
+
+**实际应用中可以使用文件系统或数据库来缓存结果。**
+
+### 3. 预加载下一级分类
+
+在用户查看当前层级时，后台预加载可能的下一级分类：
+
+```bash
+# 获取 Level 1 分类
+neta-cli suggest_categories --level 1
+
+# 并行预加载 Level 2 分类（示例：使用后台任务）
+neta-cli suggest_categories --level 2 --parent_path "衍生创作类" &
+neta-cli suggest_categories --level 2 --parent_path "数字艺术" &
+neta-cli suggest_categories --level 2 --parent_path "生活方式" &
+wait
+```
+
+**这样可以提升用户体验，减少等待时间。**
+
+### 4. 批量验证分类路径
+
+一次性验证多个分类路径的有效性：
+
+```bash
+# 并行验证多个路径
+neta-cli validate_tax_path --tax_path "衍生创作类>同人二创>崩坏星穹铁道" &
+neta-cli validate_tax_path --tax_path "衍生创作类>同人二创>原神" &
+neta-cli validate_tax_path --tax_path "数字艺术>概念设计" &
+wait
+
+# 或者使用脚本批量处理
+cat > /tmp/paths.txt << EOF
+衍生创作类>同人二创>崩坏星穹铁道
+衍生创作类>同人二创>原神
+数字艺术>概念设计
+EOF
+
+while read path; do
+  neta-cli validate_tax_path --tax_path "$path"
+done < /tmp/paths.txt
+```
+
+**这样可以提前筛选出有效的分类路径，避免后续请求失败。**
+
+## 调试技巧
+
+### 1. 检查搜索关键词是否生效
+
+```bash
+# 开启 debug 日志
+DEBUG=* neta-cli suggest_content \
+  --intent search \
+  --search_keywords "测试关键词"
+```
+
+检查日志中是否正确传递了关键词参数。
+
+### 2. 验证分类路径匹配
+
+```bash
+# 先用 exact 模式测试
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "你的分类路径" \
+  --page_size 5
+
+# 如果返回空，可能是：
+# - 分类路径不存在
+# - 该分类下没有内容
+# - 路径格式不正确
+```
+
+### 3. 对比不同模式的结果
+
+```bash
+# 同一关键词，对比三种模式
+neta-cli suggest_content --intent recommend --page_size 10
+neta-cli suggest_content --intent search --search_keywords "关键词" --page_size 10
+neta-cli suggest_content --intent exact --tax_paths "分类路径" --page_size 10
+```
+
+观察不同模式下结果的差异，理解各模式的特点。
+
+## 常见问题
+
+### Q1: suggest_keywords 和 suggest_tags 有什么区别？
+
+**A:** 
+- `suggest_keywords`: 基于**前缀**的模糊匹配，适合探索阶段
+- `suggest_tags`: 基于**完整关键词**的相关性匹配，更精确
+
+```bash
+# keywords - 前缀匹配
+neta-cli suggest_keywords --prefix "崩"  # 返回所有以"崩"开头的词
+
+# tags - 相关性匹配
+neta-cli suggest_tags --keyword "游戏"   # 返回与"游戏"相关的标签
+```
+
+### Q2: 为什么 validate_tax_path 验证通过，但 suggest_content 返回空？
+
+**可能原因：**
+1. 分类路径有效，但该分类下暂时没有内容
+2. intent 模式不对（应该用 exact 却用了 recommend）
+3. 还有其他筛选条件冲突
+
+**解决方案：**
+```bash
+# 尝试去掉其他条件，只用分类路径
+neta-cli suggest_content \
+  --intent exact \
+  --tax_paths "你的分类路径" \
+  --page_size 10
+```
+
+### Q3: 如何选择合适的 intent 模式？
+
+**选择指南：**
+
+| 模式 | 使用场景 | 必需参数 |
+|------|---------|---------|
+| `recommend` | 无目的浏览、探索 | 无 |
+| `search` | 有明确关键词 | `search_keywords` |
+| `exact` | 严格按分类筛选 | `tax_paths` 或分类参数 |
+
+### Q4: exclude_keywords 和 exclude_tax_paths 如何使用？
+
+```bash
+# 排除包含特定词的内容
+neta-cli suggest_content \
+  --exclude_keywords "教程,广告,搬运" \
+  --search_keywords "绘画"
+
+# 排除特定分类
+neta-cli suggest_content \
+  --exclude_tax_paths "课程培训,商业推广" \
+  --tax_paths "数字艺术"
+```
+
+**注意：** 排除条件会显著减少结果数量，慎用。
+
+### Q5: biz_trace_id 在多轮对话中如何维护？
+
+**方法：保存第一次请求返回的 biz_trace_id，后续请求都使用这个值。**
+
+```
+# 第 1 次请求（首页）
+neta-cli suggest_content \
+  --page_index 0 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "关键词" > /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 suggest_content \
+  --page_index 1 \
+  --page_size 20 \
+  --intent search \
+  --search_keywords "关键词" \
+  --biz_trace_id "$BIZ_TRACE_ID"
+```
+
+**注意：** 应该使用第一次返回的 biz_trace_id，而不是每次都用上一次的返回值。
+
+## 总结
+
+使用玩法内容探索技能的关键点：
+
+1. **渐进式探索**：分类 → 标签 → 验证 → 内容
+2. **模式选择**：无目的用 recommend，有关键词用 search，有分类用 exact
+3. **参数组合**：善用关键词 + 分类的双重筛选
+4. **排除技巧**：合理使用 exclude 参数过滤噪音
+5. **会话连续**：正确维护 biz_trace_id 保证体验一致性
+
+遵循这些最佳实践，可以高效地探索和发现平台上的优质内容！