讯飞听见音频转写

简介

讯飞听见音频转写服务采用纯 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

流程：

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

回调参数说明：

| 场景 | 回调 URL 示例 | 说明 | |------|-------------|------| | 授权成功 | /callback?apiKey=sk-xxx&state=xxx | apiKey 为驼峰命名 | | 拒绝授权 | /callback?error=access_denied&state=xxx | error 标识拒绝原因 |

返回结果（JSON）：

授权成功：

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

拒绝授权：

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

安全机制：

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

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

前置条件

Python 环境：Python 3 + requests 库
```
pip3 install requests
```
配置文件：~/.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

核心功能

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

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

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

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

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

30 分钟音频 ≈ 5 分钟

1 小时音频 ≈ 10 分钟

2 小时音频 ≈ 20 分钟

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

批量文件夹处理策略

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

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

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

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

为什么这样设计：

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

命令：

python3 scripts/xftj.py transcribe <file_path> [--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> <quotaId> <quotaType>

参数说明：

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 <hj_id>

示例：

# 查询最近 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>

说明：

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

示例：

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

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

每隔 2 分钟，使用 AskUserQuestion 询问用户是否继续等待，选项为：

继续等待：继续轮询，再等 2 分钟后再次询问

Agent 生成兜底方案：停止轮询，基于已获取的转写文本，由 Agent 直接生成一份会议纪要摘要（包含：主要议题、关键决策、行动项）

若用户选择兜底方案，告知用户「AI 纪要仍在后台生成，可稍后通过 ai-summary 命令重试获取官方版本」

CLI 命令详解

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

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

语法：

xftj.py transcribe <file_path> [--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>

参数：

hj_id：转写文件 ID（必填）

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

4. download - 下载转写结果

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

语法：

xftj.py download <hj_id>

参数：

hj_id：转写文件 ID（必填）

返回：转写文本内容

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

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

语法：

xftj.py ai-summary <hj_id>

参数：

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

流程：

启动本地 HTTP 服务器（随机端口）
打开浏览器访问授权页面
用户完成授权
自动保存 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 认证流程

流程细节：

生成随机 state 参数（22字符 URL-safe 字符串，用于 CSRF 防护）
查找可用端口并启动本地 HTTP 服务器
构造授权 URL 并打开浏览器
等待回调（超时时间 300 秒）
处理回调参数：
- 优先检查 error 参数（拒绝授权）
- 严格校验 state 参数（防止 CSRF 攻击）
- 提取 apiKey 参数（驼峰命名）
保存 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 会议纪要

注意事项

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

快速参考

最常用命令：

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

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

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

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

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

说明：

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

配置文件位置：

~/.xftj/config.json

讯飞听见转写流程

讯飞听见音频转写

简介

执行前置检查（重要）

OAuth 认证流程

前置条件

安装依赖

核心功能

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

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

批量文件夹处理策略

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

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

能力三：AI 会议纪要

CLI 命令详解

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

2. list - 查询转写列表

3. detail - 查询转写详情

4. download - 下载转写结果

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

6. validate - 校验 API Key

7. auth - OAuth 认证

核心模块说明

xftj_api.py - API 客户端

oauth_flow.py - OAuth 认证流程

get_ai_summary.py - AI 会议纪要

使用示例

注意事项

快速参考