讯飞听见音频转写

> 版本：1.0.12
>
> 本文所称的文本 resultType、AI taskType / promptTemplate、导出 fileType 是三套独立契约，禁止混用。

执行约束

除非用户明确要求修改本 Skill 或其流程，否则必须严格按照本 Skill 已定义的流程执行。不得以优化、兼容、试错或临时绕过为由偏离流程。不得自行修改 SKILL.md、脚本、测试或执行流程。

发现流程不通、接口合同变化或说明疑似过时时，先报告证据和影响；只有用户明确要求修改后，才可调整流程或回写 Skill。

执行入口

Skill 目录：~/.codex/skills/xftj-transcribe。以下命令默认从该目录执行：

cd ~/.codex/skills/xftj-transcribe
python3 scripts/xftj.py --help
python3 scripts/xftj.py <command> --help

仅在缺少依赖时安装 requests。

配置位于 ~/.xftj/config.json。不要打印、回显或复制其中的 API Key。App 路由需要配置 appPlatform 和 appClientVersion；本地 HTTP Mock 才允许显式启用 allowInsecureHost，生产环境不要启用。

每次执行前

先校验 API Key：

python3 scripts/xftj.py validate

• valid=true：继续。
• valid=false：告知失效原因，询问用户是否执行 OAuth。
• 用户确认后才运行 python3 scripts/xftj.py auth；用户拒绝则停止，不替用户修改或展示配置。

授权边界

• validate、历史列表、详情和已有结果下载属于读取。
• 上传、发起转写、Chat 提问、AI 生成、语篇规整等会创建外部任务；仅在用户请求包含该动作时执行。
• 用户只说“拉取、查询、下载”时，不要因结果缺失自动创建 AI 纪要或其他生成任务。
• pay 会消耗权益。必须展示 transcribe 返回的权益，让用户明确选择；随后原样传递权益字段，并显式使用 --confirm。
• 不提交笔记、重点标记或其他写操作，除非用户明确要求并确认目标。

核心工作流

新文件转写

当前只支持单文件，不要把目录批处理或并行转写当作现有能力。

1. 上传并启动转写，等待完成并取得权益列表：

bash python3 scripts/xftj.py transcribe <file_path> [--language cn|en]

上传申请只提交 fileName、fileSize 和 uploadChannel，不要求本地读取音频时长，也不依赖本地音频探测工具。拿到签名上传地址后，必须使用 multipart POST 上传，并在 URL 查询参数中追加实际字节数 size=<fileSize>；表单同时带 name、size、file。不要改用二进制 PUT。

2. 展示权益名称、类型、剩余额度及企业/角色信息，等待用户选择。
3. 用户确认后支付并下载：

bash python3 scripts/xftj.py pay <hjId> <quotaId> <quotaType> \ [--group-id GROUP_ID] [--user-role-id USER_ROLE_ID] --confirm

groupId、userRoleId 和权益类型以接口返回值为准，不猜测、不改写。transcribe 成功不等于已支付或已下载全文。

历史结果与最近 N 天

list 当前没有日期参数。查询“最近半个月”等时间范围时：

1. 运行 list --limit N，按每条记录的创建时间在本地筛选。
2. 如果返回的最早记录仍落在目标时间窗内，说明列表覆盖不足；增大 limit 后重查，不能声称结果完整。
3. 保留标题、创建时间、orderId/hjId、originAudioId/audioId 和实际 fileSource。
4. 下载时逐条按该记录的 fileSource 分流；分流前先按 hjLockStatus 做锁定判定（见下节）。

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

锁定订单前置判定

查询任何结果（转写、纪要、字幕、笔记、导出等）之前，先通过 list / detail 返回的 hjLockStatus 判断订单是否锁定：

• hjLockStatus = LOCKED：向用户提示"该订单处于锁定状态，结果不可见"，跳过该订单的全部下载 / 查询 / 导出操作，不发起转写结果、纪要、字幕等任何结果类请求。
• hjLockStatus = UNLOCKED：继续按正常流程下载转写、查询纪要等。

必须遵守：

• 判定依据为接口实际返回的 hjLockStatus，不根据 hjFrom / hjFromDesc / 订单 ID 前缀猜测锁定状态。
• 锁定订单即使 orderStatus=completed，各结果类型（16/18/21/25 等）也只会返回空结构；不要因结果为空反复重试其他类型。
• 解锁由讯飞听见平台侧处理，本 Skill 不提供解锁命令；锁定订单缺失结果时如实报告"订单锁定"，不擅自发起生成或支付。
• 批量处理时逐条判定，不能因为部分订单解锁就给整批跳过或放行。

fileSource 分流

历史列表中当前记录的 fileSource 是唯一分流依据：

必须遵守：

• 批量处理逐条读取 fileSource，不能给所有记录固定传 hj 或 app。
• PC/网站记录通常是 hjFrom=xftj、hjFromDesc=网站，但实际下载参数仍为 hj。
• CLI 不支持 pc。不要根据界面名称、hjFrom、hjFromDesc 或订单 ID 前缀猜来源。
• 未知新值不能静默映射；保留原值，确认路由契约后再处理。
• 只改请求参数不够，业务头也必须与来源匹配。

API Key 统一流程与 AppAdapt 边界

fileSource=app 描述数据来源，不等于必须调用 AppAdapt。当前核心目标“历史列表、转写文本、已有会议纪要、按需生成会议纪要”可以统一使用 MCP API Key 流程：

• 历史列表：WebAdapt /v2/hjProcess/recentOperationFiles，返回 HJ/APP 融合记录。
• 文本结果（含洞察 58）：WebAdapt /v1/hyjy/{hjId}/transcriptResults/{resultType}，逐条透传实际 fileSource。
• 已有会议纪要：WebAdapt /v1/hj/aiPower/queryLastHyjyTaskResult 代理 HJService，逐条透传实际 fileSource。
• 生成会议纪要：WebAdapt /v1/hj/aiPower/asyncTask/textGenerate 代理 HJService，逐条透传实际 fileSource。

HJService 的上述纪要接口代码明确支持 fileSource=hj|app，因此完成当前核心目标不需要 AppAdapt。公网调用仍应经过 WebAdapt；当前生产域名直接访问 /HJService/... 可能命中 HTML 前端兜底，不等于控制器不可用。AppAdapt 只用于 HJService/API Key 白名单未覆盖的 App 专属合同，例如 V4 专有结果 50/70、专属 AI 能力和专属 Chat；这些能力需要有效 App 会话及对应客户端头，不能把 API Key 当作 App 登录会话。

HJService 当前 MCPApiKeyAuthFilter 对 /v1/audios/transcriptResults/{resultType} 的实现仍有缺口：白名单写了路径变量，但实际只做字符串精确匹配。服务端修复为模板匹配前，普通转写继续使用已验证的 WebAdapt 兼容入口，不直接依赖该有缺陷的 HJService 路径。

这组 API Key 白名单只覆盖核心转写与会议纪要闭环，不等于覆盖本 Skill 的全部扩展命令。V2 笔记、重点标记、AI 任务列表/按 taskId 查询、缩略图、Chat、语篇规整和原生导出等路径不在当前白名单中；调用前必须分别确认 WebAdapt 代理、API Key 鉴权或 App 会话合同，不能因为控制器代码存在就假定公网可用。

for each item in history:
    source = item.fileSource
    download(item.orderId, file_source=source)

python3 scripts/xftj.py download <hj_id> --file-source hj
python3 scripts/xftj.py download <hj_id> --file-source app

转写文本和已有会议纪要

转写文本优先按业务语义读取：

python3 scripts/xftj.py download <hj_id> \
  --kind readable --file-source <hj|app> [--output FILE]

• download --kind readable 先取规整结果 18；缺失时才从原始结构 16 提取可读文本，不会跨到纪要、摘要等其他业务语义。
• 未知 JSON 不视为成功文本；使用 --kind raw 或 --output 保留原始结构。
• 鉴权、网络和协议错误不得通过尝试其他语义类型掩盖。

用户只要求“拉取已有纪要”时：

• HJ 与 App 记录均先查询统一的最新 AI 会议纪要：

bash python3 scripts/xftj.py ai-summary <hj_id> \ --file-source <hj|app> --existing-only

• HJ 存储型纪要还可读 download --kind minutes --file-source hj，同语义 fallback 为 20 -> 57。
• 缺少已有结果时报告缺失；只有用户同意生成后，才发起 AI 任务。

已有 AI 洞察

洞察属于数字文本结果类型 58，不是自然语言分类，也不是 AI 纪要的字符串 taskType：

洞察 documentId = originAudioId + "_58"

查询前仍须从历史列表读取当前记录的 hjLockStatus、originAudioId 和实际 fileSource。仅对 UNLOCKED 记录执行：

python3 scripts/xftj.py download <hj_id> \
  --kind insights --file-source <hj|app> [--output FILE]

显式数字类型与上述命令等价：

python3 scripts/xftj.py download <hj_id> \
  --result-type 58 --file-source <hj|app> [--output FILE]

• HJ 和 App 均走 WebAdapt /v1/hyjy/{hjId}/transcriptResults/58，同时传历史记录中的 originAudioId 与实际 fileSource；App 使用匹配来源的业务头。
• {originAudioId}_58 是服务内部 TextStorage 定位键。公网不能直接调用 TextStorage；其接口还依赖内部 index/type，生产域名直连可能返回 HTML 前端兜底。
• CLI 从业务响应的 transcriptResult 解析并返回洞察数组；使用 --output 时保存为 JSON。单条外层包含 seqNo、favorState、resultType、createTime、result，其中 result 是具体洞察的 JSON 字符串，当前可包含 title、text、refs、tag、tagName、timeOffset 等字段。
• 接口成功但数组为空表示没有已归档洞察：报告缺失并跳过，不自动触发生成。
• NORMAL、NOTICE、EGG 是洞察内容子类型，不是下载接口的 resultType 参数；下载参数固定为数字 58。

AI 纪要的 TextStorage 文档键

AI 纪要写入 TextStorage/ES 时，按历史记录中的 originAudioId 和字符串结果类型构造 documentId：

文本纪要 documentId = originAudioId + "_HYJY_CBB_ADAPTIVE"
图文纪要 documentId = originAudioId + "_INFOGRAPHIC_SUMMARY"

• 这两个值是 TextStorage documentId，不是 taskId，也不是 transcriptResults/{resultType} 使用的数字结果类型。
• originAudioId 必须取自当前历史记录；不能用 orderId/hjId、文件 ID 或 AI taskId 替代。
• 文档键公式只说明结果的存储定位规则，不代表公网已经提供可按 documentId 直读的接口。调用前仍要确认 WebAdapt/API Key 或已登录会话下的只读入口。
• /v1/hyjy/web/aiPower/queryAIMeetingSummaryTasks 虽名为查询，但 HJService 在缺少 HYJY_CBB_ADAPTIVE 或 INFOGRAPHIC_SUMMARY 任务时会自动补发。用户只要求拉取已有结果时禁止调用它。
• 已有文本纪要继续用 queryLastHyjyTaskResult。图文纪要只有在已经安全取得现有 taskId 后，才可用 python/queryAsyncAITaskResult 读取；不要为了获得 taskId 触发自动补发接口。

读取已有结果时采用以下验证判据：

• 文本纪要成功：任务状态为 completed 且结果非空。
• 图文纪要成功：taskType、resultType 均为 INFOGRAPHIC_SUMMARY，任务状态为 completed，且 aiResult 非空。
• 当前图文纪要的 aiResult 含 section 时，可作为内容结构性检查；不要把该字段描述成服务端长期合同。
• 最近时间窗的记录总数、来源分布、纪要命中数和内容长度都属于现场快照，必须每次重新查询，不能固化为 Skill 的长期规则。

AI 会议纪要

HJ/APP 统一 API Key 链路：

python3 scripts/xftj.py ai-summary <hj_id> \
  --file-source <hj|app> [--mode interactive|adaptive]

ai-summary 通过 WebAdapt 调用 HJService 白名单中的 asyncTask/textGenerate 和 queryLastHyjyTaskResult；APP 记录仍传 fileSource=app，并使用 X-Biz-Id: xftjapp。查询结果按 taskId 校验，避免把其他最新任务误认成本次结果。

AppAdapt 专属自适应纪要合同仅在明确需要该合同且具备 App 会话时使用：

python3 scripts/xftj.py adaptive-summary <hj_id> [--audio-id AUDIO_ID] --file-source app
python3 scripts/xftj.py adaptive-summary-result <hj_id> [--audio-id AUDIO_ID] --file-source app
python3 scripts/xftj.py adaptive-summary-poll <hj_id> [--audio-id AUDIO_ID] \
  [--task-id ID] [--max-polls 60] [--interval 5] --file-source app

• 三个 App 命令必须使用 fileSource=app；CLI 不接受 hj。
• hj_id 是订单 ID；audioId/originAudioId 是数字。只提供数字 audioId 不能替代订单作用域。
• App V4 需要 X-Platform、X-Client-Version。
• 已确认状态为 wait_process、processing、completed、failed。未知状态不能视为等待或成功。
• completed 但 aiResult 为空视为失败；failed 应返回非零退出码并保留 failReason。
• adaptive-summary-result/poll、ai-task-query、ai-task-result 查询入口不可混用。

字幕、笔记、AI 与导出

下表中的 <hj_id> 命令只要 --help 显示支持 --file-source，就必须传当前历史记录的实际值；不要依赖默认来源。

常用命令：

Chat 和 AI 文本生成可能返回 SSE/流式原文，保留原文及响应头中的 contextId，不要强制按 JSON 解析。图文纪要命令只承诺已确认的缩略图 URL，不承诺完整可编辑思维导图文件。

三套契约速查

文本结果 resultType

resultType 是 transcriptResults/{resultType} 的数字类型：

App V4 直连结果路由当前只允许 16、18、50、70，且 audioId 必须为数字；本 Skill 在 API Key 读取普通转写时，type 16、18 走 WebAdapt 兼容入口，type 50、70 才需要 AppAdapt 直连。20/57 是 HJ 纪要结果，不能因为语义相近就发往 App V4 路由。

AI taskType / promptTemplate

App aiPowerResult 已确认的 taskType 为 KEYWORD、CHAPTER_QUICK_VIEW、FULLTEXT_ABSTRACT、HYJY_CBB_ADAPTIVE_SUMMARY。

“待办、风险、矛盾、建议”等洞察未确认存在固定四类枚举。使用平台返回的 promptTemplate 或 chat-ask，不要自行把中文分类硬编码为 taskType / resultType。

HJ textGenerate 的历史请求体还存在一个同名字符串字段 resultType，当前值可能与 promptTemplate 相同；它属于 AI 生成接口契约，不是 transcriptResults/{resultType} 的数字文本类型。

导出 fileType

fileType=4 是原生导出格式，服务端读取 resultType=9。平台未确认原生 VTT fileType；VTT 由本地 subtitle.py 转换生成。

错误处理

• 先区分鉴权、网络、协议、空结果和业务失败，不跨语义猜测结果类型。
• 结构化结果无法可靠提取时保存 --kind raw。
• 列表、详情或结果缺少 fileSource 时，不使用 CLI 默认值冒充已确认来源。
• App 与 HJ 的订单 ID、数字音频 ID、业务头和任务入口必须成套匹配。
• 长任务按 CLI 的轮询参数执行并向用户同步进度；不要承诺固定完成时间。
• 需要未列出的参数时运行 python3 scripts/xftj.py <command> --help，不要在 Skill 中复制整套参数说明。