AudioClaw 技能：语音输入处理（Voice Intake）

适用场景

当用户发送语音消息，且 AudioClaw 需在回复前理解其内容时，请使用本技能。

常见触发条件：

• 飞书（Feishu）或聊天机器人接收到的是音频消息而非文本消息。
• AudioClaw 需要语音转写结果（transcript）及结构清晰的用户消息载荷（clean user message payload）。
• 工作流需支持更丰富的自动语音识别（ASR）能力，例如时间戳、情感分析或说话人分离（speaker separation）。
• 团队希望统一使用一个稳定的 AudioClaw 语音输入入口，而非手动编写 ASR 请求逻辑。
• 接入渠道将入站语音文件存储为 .ogg 或 .opus 格式，而 AudioClaw 仍需一条统一、稳定的 ASR 处理路径。

本技能不适用于语音输出（TTS），如需语音合成，请使用 $audioclaw-skills-voice-reply。

工作流程

1. 将接收到的音频文件本地保存。
2. 以音频文件路径为参数，运行 scripts/openclaw_voice_intake.py。
3. 若未显式指定模型，脚本将自动选择最优模型：
   • 常规单说话人语音理解：选用 sense-asr-deepthink
   • 已提供语言提示（language hint）时：选用 sense-asr
   • 请求返回时间戳、情感分析、说话人角色分离（speaker diarization）或标点恢复时：选用 sense-asr-pro
   • 请求热词（hotwords）识别时：选用 sense-asr-lite
4. 将脚本返回的 JSON 清单（manifest）作为 AudioClaw 的交接数据（handoff）使用，关键字段包括：
   • transcript.normalized_text
   • openclaw.turn_payload
   • routing.selected_model
5. 若 understanding.clarification_needed 字段值为 true，则应提示用户重说或重新发送音频。

运行时模型

官方 HTTP ASR 接口：

• 端点（Endpoint）：https://api.senseaudio.cn/v1/audio/transcriptions
• 内容类型（Content type）：multipart/form-data
• 文件大小限制：<=10MB
• 本技能实际支持的本地输入音频后缀（practical local input suffixes）：.wav、.mp3、.ogg、.opus、.flac、.aac、.m4a、.mp4

支持的响应目标（response goals）：

• 纯文本转写结果（plain transcript）
• 更丰富的原始响应透传（richer raw response passthrough）
• 可直接供 AudioClaw 使用的回合载荷（AudioClaw-ready turn payload）

本技能保持两层职责分离：

• AudioClaw ASR 生成的原始 ASR 输出
• AudioClaw 封装逻辑与澄清启发式策略（AudioClaw packaging and clarification heuristics）

API 密钥查找机制

本技能当前再次将 SENSEAUDIO_API_KEY 视为默认 API 密钥来源。

运行时规则：

• 若宿主应用（host app）将 SENSEAUDIO_API_KEY 注入为 AudioClaw 登录令牌（如 v2.public... 形式），共享启动引导程序（shared bootstrap）将在 ASR 启动前，从 ~/.audioclaw/workspace/state/senseaudio_credentials.json 中读取真实的 sk-... 密钥并完成替换。
• --api-key-env 参数仍可用，但默认运行时密钥路径为 SENSEAUDIO_API_KEY。

命令示例

基础语音输入处理：

python3 scripts/openclaw_voice_intake.py 
  --input /path/to/user_audio.mp3

带更丰富 AudioClaw 结构的语音输入处理：

python3 scripts/openclaw_voice_intake.py 
  --input /path/to/meeting_clip.m4a 
  --enable-punctuation 
  --timestamp-granularity segment 
  --enable-sentiment 
  --out-json /tmp/openclaw_voice_turn.json

强制指定特定模型：

python3 scripts/openclaw_voice_intake.py 
  --input /path/to/user_audio.mp3 
  --model sense-asr-deepthink

AudioClaw 集成模式

推荐的交接方式（handoff）：

1. 渠道适配器（channel adapter）负责存储入站音频文件。
2. AudioClaw 调用 scripts/openclaw_voice_intake.py 进行处理。
3. AudioClaw 读取以下字段：
   • openclaw.turn_payload.role
   • openclaw.turn_payload.content
   • openclaw.turn_payload.metadata
4. 后续对话流程正常继续，如同用户直接输入了识别出的文本内容。

运维规范（operational rules）：

• 在元数据（metadata）中保留原始音频路径，便于调试。
• 仅在对语种高度确定时才显式传入 language 参数；否则交由 ASR 自动检测。
• 若请求时间戳、情感分析或说话人分离功能，应允许脚本自动选择 sense-asr-pro 模型。
• 若转写结果（transcript）为空，不得虚构用户意图；必须发起澄清请求。

相关资源

• scripts/senseaudio_asr_client.py
  • AudioClaw ASR 的 multipart HTTP 客户端
  • 支持模型路由校验，以及 JSON 或纯文本响应格式处理
• scripts/openclaw_voice_intake.py
  • AudioClaw 主运行时脚本
  • 构建转写文本、标准化用户文本及回合载荷（turn payload）
• references/openclaw_voice_intake.md
  • 官方 ASR 文档摘要、各模型支持说明，以及 AudioClaw 载荷示例