讯飞听见音频转写

简介

讯飞听见音频转写服务采用纯 Python 架构，通过统一的 CLI 工具 xftj.py 提供完整的音频转写能力。

核心优势：

• 一键转写：单条命令完成从上传到结果下载的全流程
• 统一接口：所有功能通过 xftj.py CLI 调用
• 简单配置：只需配置 ~/.xftj/config.json

执行前置检查（重要）

在执行任何功能之前，必须先校验 API Key 是否有效：

python3 scripts/xftj.py validate

• 如果 valid: true：API Key 有效，继续执行后续流程
• 如果 valid: false：API Key 无效或过期，使用 AskUserQuestion 工具询问用户「API Key 已失效，是否需要进行 OAuth 认证？」
  • 用户选择是：执行认证命令 python3 scripts/xftj.py auth（会自动打开浏览器，用户授权后 API Key 自动保存）
  • 用户选择否：终止流程，提示用户手动配置 ~/.xftj/config.json

OAuth 认证流程

命令：

python3 scripts/xftj.py auth

流程：

1. 启动本地 HTTP 服务器监听随机端口
2. 自动打开浏览器访问授权页面：https://www.iflyrec.com/xftjoauth/oauth/authorize?callbackUrl=http://localhost:{port}/callback&state={random_state}
3. 用户在页面上完成授权（或拒绝）
4. 授权服务回调本地服务器，携带结果参数
5. 校验 state 参数防止 CSRF 攻击
6. 成功则保存 apiKey 到 ~/.xftj/config.json

回调参数说明：

返回结果（JSON）：

授权成功：

{
  "success": true,
  "apiKey": "sk-..."
}

拒绝授权：

{
  "success": false,
  "error": "用户拒绝授权 (access_denied)"
}

安全机制：

• state 参数：发起认证时生成随机 state，回调时严格校验一致性，防止 CSRF 攻击。无论成功还是拒绝，都会校验 state。
• 如果 state 不匹配，返回 {"success": false, "error": "state 不匹配,可能存在 CSRF 攻击"}

注意：认证过程中脚本会阻塞等待回调，用户需要在浏览器中完成授权操作。

前置条件

1. Python 环境：Python 3 + requests 库

   pip3 install requests
   

2. 配置文件：~/.xftj/config.json

   {
     "apiKey": "your-api-key-here",
     "baseUrl": "https://www.iflyrec.com"
   }
   

   baseUrl 说明：所有 API 请求的基础地址，默认为 https://www.iflyrec.com。 如需使用其他环境（如开发环境 https://dev-integ-env.iflyrec.com），直接修改此字段即可。 若配置文件中不存在 baseUrl，脚本自动使用默认值 https://www.iflyrec.com。

安装依赖

# 安装 Python 依赖
pip3 install requests

# 验证配置文件
cat ~/.xftj/config.json

核心功能

能力一：新文件转写（两步流程）

流程分为两步，中间需要用户选择权益：

第一步：上传并转写（自动）

1. 获取上传链接
2. 上传音频文件
3. 启动转写任务
4. 轮询转写状态（等待完成）
5. 查询可用权益并返回列表

⏱️ 转写时长预估：文件越大，转写等待时间越长。大致参考：

• 30 分钟音频 ≈ 5 分钟
• 1 小时音频 ≈ 10 分钟
• 2 小时音频 ≈ 20 分钟

轮询过程中请耐心等待，不要中断程序。如用户询问进度，告知预估等待时间并继续轮询。

批量文件夹处理策略

如果是上传文件夹（包含多个音频文件），请使用以下并行策略避免串行等待：

1. 分组上传：每次上传约 3 个文件为一组
2. 并行轮询：上传完成后，同时轮询这组文件的状态
3. 分批处理：等一组完成后再上传下一批
4. 汇总结果：所有文件都完成后，合并展示给用户

示例流程（假设文件夹有 7 个文件）：

批次1: 上传 file1.mp3, file2.mp3, file3.mp3 → 并行轮询状态
批次2: 上传 file4.mp3, file5.mp3, file6.mp3 → 并行轮询状态
批次3: 上传 file7.mp3 → 轮询状态
→ 汇总所有结果，统一让用户选择权益

为什么这样设计：

• 避免串行等待：不等一个文件完全转写完再上传下一个
• 平衡并发：每次 3 个文件，避免瞬时并发过高
• 可靠性：分批处理，单批失败不影响其他批次

命令：

python3 scripts/xftj.py transcribe  [--language cn]

返回结果（JSON）：

{
  "success": true,
  "hjId": "PW-mz485272601849532416",
  "quotas": [
    {"id": 256574, "name": "[企业] 畅享包 - 剩余: 287886000ms", "type": "corpPermission"},
    {"id": 189328312, "name": "[个人] 3小时·机器快转时长卡 - 剩余: 10800000ms", "type": "personalQuota"}
  ],
  "message": "请选择权益进行支付"
}

重要：此时必须使用 AskUserQuestion 工具展示权益列表，让用户选择使用哪个权益进行支付。

第二步：支付并下载（用户选择后执行）

根据用户选择的权益，调用支付并下载命令：

命令：

python3 scripts/xftj.py pay   

参数说明：

• hjId：第一步返回的转写记录 ID（字符串格式，如 PW-mz485272601849532416）
• quotaId：用户选择的权益 ID
• quotaType：权益类型，personalQuota（个人时长卡）、permission（个人畅享包）或 corpPermission（企业畅享包）

返回结果（JSON）：

{
  "success": true,
  "hjId": "PW-mz485272601849532416",
  "content": "转写的文本内容..."
}

完整示例：

# 第一步：上传转写，获取权益列表
python3 scripts/xftj.py transcribe meeting.mp3

# （用户选择权益后）第二步：支付并下载
python3 scripts/xftj.py pay PW-mz485272601849532416 256574 corpPermission

能力二：查询历史转写文件

查询文件列表：

python3 scripts/xftj.py list [--keyword 关键词] [--limit 20]

下载转写结果：

python3 scripts/xftj.py download 

示例：

# 查询最近 20 条转写记录
python3 scripts/xftj.py list

# 搜索包含"会议"的转写记录
python3 scripts/xftj.py list --keyword 会议

# 下载结果
python3 scripts/xftj.py download PW-mz485272601849532416

注意：download 命令内部会先通过列表接口查询 originAudioId，再调用 transcriptResults 接口获取转写文本，无需手动传入 originAudioId。

能力三：AI 会议纪要

获取或创建 AI 纪要：

python3 scripts/xftj.py ai-summary 

说明：

• hj_id 为字符串格式（如 PW-mz485272601849532416），不是数字
• 内部自动通过列表接口查询 originAudioId
• 使用 HYJY_CBB_INTERACTIVE_ADAPTIVE 模板生成交互式摘要
• 如已有纪要则直接返回，否则触发生成并轮询等待完成

示例：

python3 scripts/xftj.py ai-summary PW-mz485272601849532416

⏳ 轮询超时处理：AI 纪要生成通常需要 1-3 分钟，但有时会更久。轮询过程中：

• 每隔 2 分钟，使用 AskUserQuestion 询问用户是否继续等待，选项为：
  1. 继续等待：继续轮询，再等 2 分钟后再次询问
  2. Agent 生成兜底方案：停止轮询，基于已获取的转写文本，由 Agent 直接生成一份会议纪要摘要（包含：主要议题、关键决策、行动项）
• 若用户选择兜底方案，告知用户「AI 纪要仍在后台生成，可稍后通过 ai-summary 命令重试获取官方版本」

CLI 命令详解

1. transcribe - 一键转写（最常用）

功能：完成从上传到结果下载的全流程转写

语法：

xftj.py transcribe  [--language cn|en]

参数：

• file_path：音频文件路径（必填）
• --language：语言类型，cn=中文（默认），en=英文

返回：转写文本内容

2. list - 查询转写列表

功能：查询历史转写文件列表

语法：

xftj.py list [--keyword 关键词] [--limit 数量]

参数：

• --keyword：搜索关键词（可选）
• --limit：返回数量，默认 20

返回：转写文件列表（包含 hjId、文件名、状态等）

3. detail - 查询转写详情

功能：获取指定转写文件的详细信息

语法：

xftj.py detail 

参数：

• hj_id：转写文件 ID（必填）

返回：文件详情（包含时长、状态、创建时间等）

4. download - 下载转写结果

功能：下载指定转写文件的文本结果

语法：

xftj.py download 

参数：

• hj_id：转写文件 ID（必填）

返回：转写文本内容

5. ai-summary - 获取 AI 会议纪要

功能：获取或创建 AI 会议纪要（自动轮询直到完成）

语法：

xftj.py ai-summary 

参数：

• hj_id：转写文件 ID（必填）

返回：AI 生成的会议纪要内容

6. validate - 校验 API Key

功能：校验当前配置的 API Key 是否有效

语法：

xftj.py validate

返回（JSON）：

{
  "biz": {
    "valid": true,
    "userId": 2302041458060388,
    "expiresTime": 4102415999000,
    "name": "Default ApiKey",
    "createTime": 1775183604000,
    "lastUsedTime": null
  }
}

字段说明：

• valid：是否有效（true/false）
• userId：用户 ID
• expiresTime：过期时间戳（毫秒）
• reason：失效原因（仅当 valid=false 时存在，如 API_KEY_INVALID、RATE_LIMIT_EXCEEDED）

7. auth - OAuth 认证

功能：通过 OAuth 流程获取新的 API Key

语法：

xftj.py auth

流程：

1. 启动本地 HTTP 服务器（随机端口）
2. 打开浏览器访问授权页面
3. 用户完成授权
4. 自动保存 API Key 到 ~/.xftj/config.json

返回（JSON）：

{
  "success": true,
  "apiKey": "sk-..."
}

核心模块说明

xftj_api.py - API 客户端

主要方法：

• get_upload_link() - 获取上传链接
• upload_file() - 上传音频文件
• start_transcription() - 启动转写任务
• poll_transcription_status() - 轮询转写状态
• query_benefits() - 查询可用权益
• pay_with_quota() - 使用权益支付
• get_origin_audio_id(hj_id) - 通过列表接口查询 originAudioId（orderId 字段匹配）
• get_transcript_results(hj_id, origin_audio_id, type) - 调用 transcriptResults/{type} 接口获取转写文本
• download_result(hj_id) - 自动查 originAudioId，依次尝试 type=16/18/21/25/35/50
• list_transcripts() - 查询转写列表
• validate_api_key() - 校验 API Key 是否有效

转写结果类型说明：

• type=16：逐字带时间戳的原始 JSON，适合字幕/卡拉OK
• type=25：章节摘要视图，含纯文本全文，最易阅读
• type=18/21/35/50：通常为空，视账户功能而定

oauth_flow.py - OAuth 认证流程

主要方法：

• run_oauth_flow() - 启动 OAuth 认证流程

流程细节：

1. 生成随机 state 参数（22字符 URL-safe 字符串，用于 CSRF 防护）
2. 查找可用端口并启动本地 HTTP 服务器
3. 构造授权 URL 并打开浏览器
4. 等待回调（超时时间 300 秒）
5. 处理回调参数：
   • 优先检查 error 参数（拒绝授权）
   • 严格校验 state 参数（防止 CSRF 攻击）
   • 提取 apiKey 参数（驼峰命名）
6. 保存 API Key 到 ~/.xftj/config.json

关键技术点：

• 回调参数名为 apiKey（驼峰），不是 api_key
• state 校验严格匹配，拒绝授权时也会校验
• 端口自动选择（_find_free_port()）
• 超时时间 300 秒（5 分钟）

get_ai_summary.py - AI 会议纪要

• 使用 HYJY_CBB_INTERACTIVE_ADAPTIVE 模板（交互式摘要）
• aiResult 字段直接返回 Markdown 文本，无需 JSON 解析
• 内部调用 XFTJClient.get_origin_audio_id() 获取真实 originAudioId

使用示例

详见 examples/ 目录：

• 01-transcribe-new-audio.md — 完整转写新音频文件（端到端）
• 02-download-history.md — 下载历史转写结果
• 03-ai-summary.md — 生成 AI 会议纪要

注意事项

1. 配置文件：确保 ~/.xftj/config.json 配置正确，包含有效的 apiKey
2. Python 依赖：需要安装 requests 库（pip3 install requests）
3. 转写时长：转写时长与文件大小成正比，大致参考：30 分钟≈5 分钟、1 小时≈10 分钟、2 小时≈20 分钟。轮询期间请耐心等待，不要中断
4. 权益消耗：每次转写会自动使用账户权益，请确保账户有足够的权益
5. 语言支持：目前支持中文（cn）和英文（en）两种语言
6. 文件格式：支持常见音频格式（mp3、wav、m4a 等）
7. AI 纪要：AI 会议纪要生成需要额外时间，通常 1-3 分钟
8. 错误处理：如遇到错误，脚本会输出详细的错误信息，请根据提示排查

快速参考

最常用命令：

# 校验 API Key（执行前必须）
python3 scripts/xftj.py validate

# OAuth 认证（Key 失效时）
python3 scripts/xftj.py auth

# 一键转写（最常用）
python3 scripts/xftj.py transcribe 

# 查询历史
python3 scripts/xftj.py list

# 生成纪要
python3 scripts/xftj.py ai-summary 

说明：

• 所有命令都使用相对路径 scripts/xftj.py
• 需要在 skill 目录下执行：cd ~/.claude/skills/xftj-transcribe
• 或使用绝对路径：python3 ~/.claude/skills/xftj-transcribe/scripts/xftj.py

配置文件位置：

~/.xftj/config.json