AssemblyAI转录、语音理解以及面向智能体的友好导出

当用户需要AssemblyAI而非通用转录服务时，或当任务受益于AssemblyAI特有功能时使用此技能，例如：

• 跨模型路由universal-3-pro与universal-2
• 语言检测与语码转换
• 说话人分离增强说话人姓名/角色映射
• 翻译、自定义格式化或AssemblyAI说话人识别
• 字幕、段落划分、句子切分、主题/实体/情感分析任务
• 易于被其他智能体以Markdown或标准化JSON格式解析的

转录输出

1. 此技能专为OpenClaw等AI智能体设计，不仅面向终端用户。它提供：零依赖的Node命令行工具位于（以及一个兼容性包装器在assemblyai.mjs）
2. 捆绑的模型/语言知识通过模型和语言命令
3. 稳定的转录输出格式
   • 智能体友好的Markdown
   • 标准化的智能体JSON
   • 用于下游自动化的捆绑清单
4. 说话人映射工作流
   • 手动说话人/声道映射
   • AssemblyAI说话人识别
   • 合并的显示名称（在Markdown和JSON中）
5. AssemblyAI LLM网关集成用于从转录中结构化提取

按此顺序使用此技能

1) 判断用户是否需要AssemblyAI特定的行为

如果用户只是想要“一份转录稿”，通用的解决方案可能就足够了。当用户提到AssemblyAI、想要特定的AssemblyAI功能，或者需要本技能提供的更丰富的输出和后期处理时，再运用此技能。

2) 选择最佳入口点

• 新转录→转录
• 现有转录ID→获取或等待
• 重新渲染现有已保存的JSON→格式化
• 对现有转录稿进行后期处理→理解
• 通过LLM网关运行转录文本→llm
• 决策前需要快速查找功能→模型或语言

3) 优先采用对代理友好的默认设置

对于大多数未知语言或混合语言任务，建议采用：

node {baseDir}/assemblyai.mjs transcribe INPUT   --bundle-dir ./assemblyai-out   --all-exports

原因：

• 命令行界面默认采用自动最优当未指定模型时的路由策略
• 它会生成清单文件 + 多个输出文件代理程序无需重新解析终端输出即可直接检查
• Markdown和代理JSON格式可即时用于后续处理步骤

快速入门方案

最佳通用默认方案

当源语言未知或可能超出6种语言的Universal-3-Pro集合时使用：

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --bundle-dir ./out   --all-exports

除非请求已指定模型或语言，否则默认采用模型路由加语言检测

已知语言的最佳准确度方案

若语言已知且受Universal-3-Pro支持，建议采用明确指定方案：

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --speech-model universal-3-pro   --language-code en_us   --bundle-dir ./out

会议/访谈场景（带讲话人标签）

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --speaker-labels   --bundle-dir ./out

添加明确的讲话人姓名或角色标识

手动映射：

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --speaker-labels   --speaker-map @assets/speaker-map.example.json   --bundle-dir ./out

AssemblyAI 说话人识别：

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --speaker-labels   --speaker-type role   --known-speakers "host,guest"   --bundle-dir ./out

或对现有转录稿进行后处理：

node {baseDir}/assemblyai.mjs understand TRANSCRIPT_ID   --speaker-type name   --speaker-profiles @assets/speaker-profiles-name.example.json   --bundle-dir ./out

翻译

node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3   --translate-to de,fr   --match-original-utterance   --bundle-dir ./out

通过 LLM 网关进行结构化提取

node {baseDir}/assemblyai.mjs llm TRANSCRIPT_ID   --prompt @assets/example-prompt.txt   --schema @assets/llm-json-schema.example.json   --out ./summary.json

命令指引

转录

用于本地文件或远程 URL。

• 本地文件会先上传。
• 公共 URL 会直接发送给 AssemblyAI。
• 默认等待，然后渲染输出。

对于任何比简短片段更长的内容，建议使用--bundle-dir。

get/wait

当您已拥有转录稿 ID 时使用。wait会阻塞直到完成；get会立即获取，除非您添加--wait.

格式

在您已保存以下内容时使用：

• 来自 AssemblyAI 的原始转录 JSON，或
• 由本技能生成的标准化代理 JSON

当您想应用新的说话人映射、重新渲染 Markdown 或生成新的捆绑包而无需重新转录时，这很有用。

理解

当您需要对现有转录内容进行 AssemblyAI语音理解时使用：

• 翻译
• 说话人识别
• 自定义格式

此命令会获取转录内容，合并返回的理解结果，然后渲染更新后的 Markdown / 代理 JSON / 捆绑包输出。

大语言模型

当用户需要以下内容时使用：

• 摘要
• 提取
• 结构化 JSON
• 对转录内容进行下游推理

优先使用--schema当下一步自动化时。

输出策略

代理的最佳默认设置：捆绑模式

--bundle-dir写入一个包含以下内容的目录：

• Markdown 转录稿
• 代理 JSON
• 原始 JSON
• 可选段落 / 句子 / 副标题
• 一个机器可读的清单

这通常比将所有内容转储到标准输出更好。

主要输出种类

使用--export来选择主要输出：

• markdown（默认）
• agent-json
• json/raw-json
• text
• paragraphs
• 句子
• 字幕文件（SRT格式）
• 视频文本轨道（VTT格式）
• 清单文件

辅助输出文件

您可以直接请求以下额外文件：

• --markdown-out
• --agent-json-out
• --raw-json-out
• --paragraphs-out
• --sentences-out
• --srt-out
• --vtt-out
• --understanding-json-out

说话人映射规则

说话人显示名称按以下顺序合并：

1. 手动设置--speaker-map
2. AssemblyAI说话人识别映射
3. 回退通用名称，例如说话人A或声道1

这意味着您可以先让AssemblyAI识别说话人，之后仍可覆盖个别显示名称。

示例手动映射文件：assets/speaker-map.example.json

模型与语言查找

在选择参数之前，请检查捆绑的参考数据：

node {baseDir}/assemblyai.mjs models
node {baseDir}/assemblyai.mjs models --format json
node {baseDir}/assemblyai.mjs languages --model universal-3-pro
node {baseDir}/assemblyai.mjs languages --model universal-2 --codes --format json

捆绑数据位于：

• assets/model-capabilities.json
• assets/language-codes.json

重要操作说明

• 请勿在聊天记录中暴露API密钥；应使用环境变量注入。
• 当用户明确需要欧盟地区处理时，请使用欧盟AssemblyAI基础URL。
• 上传和转录创建必须使用来自同一AssemblyAI项目的API密钥。
• 对于长输出内容，建议使用--bundle-dir或--out参数。
• 本CLI工具为非交互式设计，并将诊断信息输出至标准错误流，这有助于代理程序实现更可靠的脚本化操作。
• 使用原始--配置或--请求当您需要此技能尚未公开的、新添加的AssemblyAI参数时。

参考文件

当您需要更深入的了解时，请阅读这些：

• 功能
• 工作流和配方
• 输出格式
• 说话人映射
• LLM网关说明
• 故障排除

关键捆绑文件

• assemblyai.mjs— 根包装器，用于与原技能兼容
• scripts/assemblyai.mjs— 主命令行界面
• assets/speaker-map.example.json
• assets/speaker-profiles-name.example.json
• assets/speaker-profiles-role.example.json
• assets/custom-spelling.example.json
• assets/llm-json-schema.example.json
• assets/transcript-agent-json-schema.json

任务完成前的完整性检查

• 你是否选择了正确的区域（api.assemblyai.com对比api.eu.assemblyai.com）？
• 你是否选择了与语言情境相匹配的模型策略？
• 如果说话者命名很重要，你是否启用了说话人识别和/或提供了说话者映射？
• 如果结果将提供给另一个代理，你是否生成了Markdown和/或代理JSON，而不仅仅是原始stdout？
• 如果转录内容将被机器使用，你是否保留了清单或明确的输出文件名？