explainer

适用场景

• 用户想制作解说视频或教程视频
• 用户要求以视频形式“解释”某个内容
• 用户想制作带有 AI 生成视觉效果的旁白内容
• 用户提到“解说视频”“解说视频”或“教程视频”

不适用场景

• 用户想制作无视觉内容的纯音频（使用 /speech 或 /podcast）
• 用户想制作播客风格的讨论节目（使用 /podcast）
• 用户想生成独立图片（使用 /image-gen）
• 用户想在没有视频的情况下朗读文本（使用 /speech）

用途

生成由单人旁白和 AI 生成视觉效果构成的解说视频。适用于产品介绍、概念说明和教程。支持仅生成文本脚本，或同时生成文本和视频。

硬性约束

• 进行任何交互前，务必先阅读 shared/config-pattern.md 中的配置
• 遵循 shared/cli-patterns.md 中的执行模式、错误处理和交互模式
• 务必遵循 shared/cli-authentication.md 中的身份验证检查
• 切勿硬编码说话人 ID — 用户想更换声音时，务必通过 speakers CLI 获取
• 切勿将文件保存到 ~/Downloads/ 或 .listenhub/ — 将生成内容保存到当前工作目录，并使用易识别的主题名称（参见 shared/config-pattern.md § 生成内容命名）
• 解说视频必须恰好使用 1 位说话人
• 模式必须为 info（信息展示型）或 story（故事叙述型）— 切勿使用 slides（请改用 /slides 技能）

每个多选步骤都必须使用 AskUserQuestion 工具 — 不要以纯文本形式列出选项。一次只问一个问题。等待用户回答后，再进行下一步。收集完所有参数后，总结选择并请用户确认。用户明确确认前，不要调用任何 CLI 命令。

步骤 -1：CLI 身份验证检查

遵循 shared/cli-authentication.md § 身份验证检查。如果未安装 CLI 或用户未登录，请自动安装并自动登录 — 切勿要求用户手动运行命令。

然后遵循 shared/cli-authentication.md § 身份验证模式检测，确定 AUTH_MODE 并设置：

if [ "$AUTH_MODE" = "openapi" ]; then
  CMD_PREFIX="listenhub openapi storybook"
else
  CMD_PREFIX="listenhub explainer"
fi

后续所有 CLI 调用都使用 $CMD_PREFIX，而不是硬编码的 listenhub explainer。

注意： OpenAPI 命令为 storybook（而非 explainer）— 后端相同，命名不同。

步骤 0：配置设置

遵循 shared/config-pattern.md 步骤 0（零提问启动）。

如果文件不存在 — 静默使用默认值创建文件，然后继续：

mkdir -p ".listenhub/explainer"
echo '{"outputMode":"inline","language":null,"defaultStyle":null,"defaultSpeakers":{}}' > ".listenhub/explainer/config.json"
CONFIG_PATH=".listenhub/explainer/config.json"
CONFIG=$(cat "$CONFIG_PATH")

不要询问任何设置问题。 直接进入交互流程。

如果文件存在 — 静默读取配置，然后继续：

CONFIG_PATH=".listenhub/explainer/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/explainer/config.json"
CONFIG=$(cat "$CONFIG_PATH")

设置流程（仅在用户主动要求重新配置时运行）

仅当用户明确要求重新配置时才运行。显示当前设置：

当前配置 (explainer)：
  输出方式：{inline / download / both}
  语言偏好：{zh / en / 未设置}
  默认风格：{info / story / 未设置}
  默认主播：{speakerName / 使用内置默认}

然后询问：

1. outputMode：遵循 shared/output-mode.md § 设置流程问题。

2. 语言（可选）：“默认语言？”

   • “中文 (zh)”
   • “English (en)”
   • “每次手动选择” → 保持为 null

3. 风格（可选）：“默认风格？”

   • “Info — 信息展示型”
   • “Story — 故事叙述型”
   • “每次手动选择” → 保持为 null

收集完回答后，立即保存：

NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")

交互流程

步骤 1：主题 / 内容

自由文本输入。询问用户：

你想解释或介绍什么？

接受：主题描述、文本内容或需要解释的概念。

步骤 2：语言

如果设置了 config.language，则预先填入并在摘要中显示 — 跳过此问题。 否则询问：

Question: "What language?"
Options:
  - "Chinese (zh)" — Content in Mandarin Chinese
  - "English (en)" — Content in English
  - "Japanese (ja)" — Content in Japanese

步骤 3：风格

如果设置了 config.defaultStyle，则预先填入并在摘要中显示 — 跳过此问题。 否则询问：

Question: "What style of explainer?"
Options:
  - "Info" — Informational, factual presentation style
  - "Story" — Narrative, storytelling approach

步骤 4：选择说话人

遵循 shared/speaker-selection.md：

• 如果已设置 config.defaultSpeakers.{language} → 静默使用已保存的说话人
• 如果未设置 → 使用 shared/speaker-selection.md 中该语言的内置默认说话人
• 在确认摘要（步骤 6）中显示说话人 — 用户可以在此处按需更改
• 只有用户明确要求更改语音时，才显示完整的说话人列表

说话人查询：查看 shared/cli-speakers.md，了解如何列出和筛选说话人。

讲解视频仅支持 1 位说话人。

步骤 5：输出类型

Question: "What output do you want?"
Options:
  - "Text script only" — Generate narration script, no video
  - "Text + Video" — Generate full explainer video with AI visuals

步骤 6：确认并生成

汇总所有选项：

Ready to generate explainer:

  Topic: {topic}
  Language: {language}
  Style: {info/story}
  Speaker: {speaker name}
  Output: {text only / text + video}

  Proceed?

运行任何 CLI 命令前，等待用户明确确认。

工作流

运行 CLI 命令，并设置 run_in_background: true 和 timeout: 660000。CLI 会阻塞，直到生成完成，并以 JSON 格式返回最终结果：

$CMD_PREFIX create \
  --query "{topic}" \
  --mode {info|story} \
  --lang {en|zh|ja} \
  --speaker "{name}" \
  --speaker-id "{id}" \
  --timeout 600 \
  --json

如果命令失败（退出码非零），请检查 stderr 中的错误详情。有关退出码和常见错误，请参阅 shared/cli-patterns.md § 错误处理。

可选标志（适用时添加）：

• --source-url "{url}" — 如果用户提供了参考 URL
• --skip-audio — 如果输出仅包含文本（无视频）
• --image-size {2K|4K} — 图像分辨率（默认为 2K）
• --aspect-ratio {16:9|9:16|1:1} — 视频宽高比（默认为 16:9）
• --style "{style}" — AI 生成图像的视觉风格

告知用户任务已提交。收到完成通知后，解析并呈现结果：

解析 CLI JSON 输出中的关键字段：

EPISODE_ID=$(echo "$RESULT" | jq -r '.episodeId')
AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl // empty')
VIDEO_URL=$(echo "$RESULT" | jq -r '.videoUrl // empty')
CREDITS=$(echo "$RESULT" | jq -r '.credits // empty')

从配置中读取 OUTPUT_MODE。按照 shared/output-mode.md 中的说明执行。

如果输出仅包含文本：

inline 或 both：直接呈现脚本内容。

呈现：

解说脚本已生成！

「{title}」

在线查看：https://listenhub.ai/app/explainer/{episodeId}

download 或 both：同时保存脚本文件。按照 shared/config-pattern.md § 产物命名生成主题 slug。

• 在当前工作目录中保存为 {slug}-explainer.md（若文件已存在，则使用不重复的名称）
• 除上述摘要外，还要提供保存路径。

如果输出包含文本和视频：

inline 或 both：将视频 URL 和音频 URL 显示为可点击链接。

呈现：

解说视频已生成！

视频链接：{videoUrl}
音频链接：{audioUrl}
消耗积分：{credits}

download 或 both：同时保存文件。按照 shared/config-pattern.md § 产物命名生成主题 slug。

• 创建 {slug}-explainer/ 文件夹（若文件夹已存在，则使用不重复的名称）
• 在其中写入 script.md
• 下载音频：

  listenhub download "{audioUrl}" -o "{slug}-explainer/audio.mp3"
  

• 呈现：

  已保存到当前目录：
    {slug}-explainer/
      script.md
      audio.mp3
  

成功生成后

使用本次会话所做的选择更新配置：

NEW_CONFIG=$(echo "$CONFIG" | jq \
  --arg lang "{language}" \
  --arg style "{info/story}" \
  --arg speakerId "{speakerId}" \
  '. + {"language": $lang, "defaultStyle": $style, "defaultSpeakers": (.defaultSpeakers + {($lang): [$speakerId]})}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"

预计用时：

• 仅文本脚本：2-3 分钟
• 文本 + 视频：5-10 分钟

资源

• CLI 身份验证：shared/cli-authentication.md
• CLI 模式：shared/cli-patterns.md
• 说话人查询：shared/cli-speakers.md
• 说话人选择指南：shared/speaker-selection.md
• 配置模式：shared/config-pattern.md
• 输出模式：shared/output-mode.md

组合方式

• 调用：speakers CLI（用于选择说话人）；可能会调用 /speech 进行旁白配音
• 由其调用：content-planner（阶段 3）

示例

用户：“制作一个介绍 Claude Code 的讲解视频”

Agent 工作流：

1. 主题：“Claude Code 介绍”
2. 询问语言 → “英语”
3. 询问风格 → “信息类”
4. 使用默认说话人 “Mars”（cozy-man-english）
5. 询问输出类型 → “文本 + 视频”

# Run with run_in_background: true, timeout: 660000
$CMD_PREFIX create \
  --query "Introduce Claude Code: what it is, key features, and how to get started" \
  --mode info \
  --lang en \
  --speaker "Mars" \
  --speaker-id "cozy-man-english" \
  --timeout 600 \
  --json

解析结果中的 episodeId、audioUrl、videoUrl 和 credits，并呈现给用户。