录音转文字·智能会议总结

概述

使用原则

本 Skill 用于真实录音转写与总结。

执行过程中优先直接完成用户请求，不向用户展示环境检查、依赖检查、安装命令、镜像切换、临时文件处理、内部重试等实现细节。

只有在环境准备最终失败、用户需要处理权限问题、需要浏览器授权、需要私密输入 API Key、额度不足、任务无法继续恢复或出现其他必须由用户介入的问题时，才向用户说明。

不要将 API Key、授权码、OAuth code、签名下载地址中的敏感参数或其他凭证输出到聊天、日志、DOCX 或普通结果文件中。API Key 仅允许保存在 Skill 根目录的私有 .env 中；逐文件授权码仅随对应任务保存在本地状态数据库中。

环境准备

执行任务前静默检查并准备运行环境。整个 Skill 必须使用同一个项目本地隔离环境完成依赖安装和后续执行，避免依赖安装到一个解释器、CLI 却由另一个解释器运行。

要求：

• Python 3.13+
• 项目根目录下使用 .venv
• httpx
• av
• pydantic 2
• python-docx

缺少 .venv 或依赖时允许自动准备，无需事先向用户确认；如果宿主环境要求对环境修改进行授权或确认，则始终以宿主策略为准。

安装策略

1. 所有操作均在 Skill 根目录执行。
2. 只使用项目本地 .venv，不得向全局 Python 环境安装依赖。
3. 优先使用 uv；系统没有 uv 时使用 pip。
4. 使用 uv 时，通过 --default-index 指定国内镜像；可以使用 uv venv、uv pip install 或适合当前项目的 uv sync，但不要使用 uv add，避免修改 pyproject.toml。
5. 使用 pip 时，先创建 .venv，再使用该虚拟环境自己的 Python 执行 python -m pip ... --index-url。
6. 安装完成后，后续所有 <venv-python> -m scripts 命令必须继续使用同一个 .venv 中的 Python。
7. 某个镜像不可用时，自动尝试下一个，不要立即让用户处理。

镜像尝试顺序：

1. 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
2. 阿里云：https://mirrors.aliyun.com/pypi/simple
3. 华为云：https://repo.huaweicloud.com/repository/pypi/simple

使用 uv 时，对每个镜像依次使用对应的 --default-index；使用 pip 时，对每个镜像依次使用对应的 --index-url。

虚拟环境解释器：

• macOS / Linux：.venv/bin/python
• Windows：.venvScriptspython.exe

环境检查、虚拟环境创建、依赖安装和镜像切换默认静默进行。只有所有合理方式均失败时，才向用户简洁说明“运行环境准备失败”和最终有用的失败原因，不要输出冗长安装日志或逐次尝试过程。

发布包根目录应包含 SKILL.md、pyproject.toml、初始为空的 .env 和完整的 scripts/ 包，并保留 scripts/__init__.py 与 scripts/__main__.py。运行模块名固定为 scripts。

下文命令中的 <venv-python> 均表示当前项目 .venv 的 Python 解释器，例如 macOS / Linux 下的 .venv/bin/python。统一通过：

<venv-python> -m scripts

调用 CLI，不要使用系统全局 Python，也不要直接执行 scripts/__main__.py。

输入文件

支持：

• 本地文件路径
• HTTP(S) URL
• 已经保存到本地的附件

平台附件必须先转换为本地文件路径后再交给 Skill。

支持的扩展名：

• MP3
• WAV
• AAC
• OPUS
• FLAC
• OGG
• AMR
• M4R
• M4A
• MP4
• WMA

限制：

• 单文件不超过 200 MiB
• 可检测到时长时，不超过 3 小时
• 文件必须包含有效音频流
• MP4 可以同时包含视频
• 不要仅根据扩展名判断真实媒体类型

输入准备、媒体检测、下载、临时文件处理等过程默认静默执行。

凭证配置

真实任务开始前检查是否已有可用 API Key。

以下情况进入统一凭证配置流程：

• 首次使用且没有 API Key
• 当前凭证无效
• 用户要求重新登录
• 用户要求更换 Key
• 用户要求切换账户

优先使用宿主提供的原生选项交互：

1. 浏览器授权并自动配置（推荐）
2. 通过私密输入方式填写已有 API Key
3. 取消

原生选项不可用时再使用编号文字。

不要要求用户在普通聊天、源文件或 CLI 参数中直接提供 API Key。

浏览器授权

用户选择浏览器授权后，在 Skill 根目录执行：

<venv-python> -m scripts --login

如有部署配置文件：

<venv-python> -m scripts --login --settings /absolute/path/settings.json

CLI 会启动本地回调服务并打开系统浏览器。

本地回调使用临时随机端口，只在 --login 正在等待授权期间存在；授权成功、拒绝、取消或超时后会自动关闭。之后再次直接访问该 localhost 地址出现连接被拒绝属于正常现象。

用户需要在网页中自行完成登录和授权确认。浏览器与 Skill 必须运行在同一台电脑上。

不要代替用户点击网页授权。

浏览器授权完成后，CLI 自动保存并启用凭证。只有 CLI 最终返回成功结果后，才向用户说明配置成功。

API Key 保存在 Skill 根目录的私有 .env 中。浏览器授权或私密手动配置成功后立即生效，无需重启终端或宿主应用。文件授权状态会随任务进度本地保存，以支持中断恢复；授权码不会展示给用户或写入输出文档。

如果用户拒绝、取消或授权超时：

• 保留原有凭证
• 保留已有任务状态
• 不自动重复授权
• 只有用户再次要求时才重新发起

手动配置 API Key

用户选择已有 API Key 时，让用户通过私密输入流程在本地执行：

<venv-python> -m scripts --configure-key

不要让用户把 Key 发到普通聊天中。

如果用户明确切换到不同账户，在配置命令后增加：

--switch-account

旧账户下已有任务不会自动迁移到新账户。

执行录音任务

在本次会话第一次开始真实转写之前，先向用户明确说明一次：

录音文件将上传到清风进行处理；逐文件授权会预占对应的转写额度。

这是正常业务提示，不需要在同一批次的每个文件或每次轮询前重复确认。用户已经授权执行真实转写后，继续正常工作流即可。

处理耗时参考

以下时间仅表示后端转写处理阶段的参考耗时：

• 30 分钟音频：转写阶段约 5 分钟
• 1 小时音频：转写阶段约 10 分钟
• 2 小时音频：转写阶段约 20 分钟

这些时间不是从用户提交录音到最终拿到 DOCX 的全流程完成时间。

一次真实任务的完整耗时还可能包括：

• 本地输入准备和媒体检测
• 文件上传
• 文件授权与额度预占
• 远端导入或任务创建
• 后端排队
• 后端转写处理
• 结果查询与获取
• 本地结果解析
• DOCX 生成

因此，不能根据上述参考时间向用户承诺整个任务会在对应时间内完成。

开始真实转写时，可以根据音频时长向用户简要说明：

后端转写阶段预计约需要 X 分钟；完整流程还包含上传、排队、结果获取和文档生成，实际总耗时可能更长。

不要将参考时长表述为确定完成时间，也不要在任务处理中反复播报倒计时。

参考时间只用于向用户说明大致处理速度，不用于判断任务是否超时、失败或需要重新创建。

如果已经成功创建远端任务并取得远端任务 ID，则无论是否已经达到或超过参考转写时间，都必须继续跟踪和查询同一个远端任务。

达到或超过预计时间时：

• 不重新上传文件
• 不重新申请文件授权
• 不重新预占额度
• 不重新导入
• 不重新创建远端任务
• 不因为“预计时间已到”而判断原任务失败
• 不因为“处理时间比预计更长”而启动第二个相同任务

必须以已经保存的远端任务 ID 和后端实际返回的任务状态为准。

只有后端明确返回失败终态时，才可以将该远端任务判断为失败。

如果查询过程中出现网络错误、请求超时、5xx、临时服务异常或暂时无法取得状态，则当前远端任务状态应视为暂时未知，继续保留原远端任务 ID 和本地恢复状态。

这类查询异常不得被解释为：

• 原任务不存在
• 原任务已经失败
• 原任务需要重新提交
• 应该重新上传
• 应该重新授权
• 应该重新创建任务

后续应继续查询或通过恢复流程继续跟踪原任务。

工作目录与结果目录

所有任务的最终结果产物必须统一保存在当前工作区内部，不得自行在系统临时目录、用户主目录、Skill 安装目录或其他无关位置创建最终结果目录。

默认在当前工作区下创建：

<当前工作区>/录音转文字结果/

并将该目录作为本次任务的 --work-dir。

最终目录结构例如：

<当前工作区>/
└── 录音转文字结果/
    ├── skill_state.sqlite3
    ├── skill_state.sqlite3.lock
    ├── 录音A/
    │   ├── 录音A_原文记录.docx
    │   └── 录音A_智能总结.docx
    └── 录音B/
        ├── 录音B_原文记录.docx
        └── 录音B_智能总结.docx

要求：

• 顶层结果目录必须位于当前工作区内。
• 不要使用 /tmp、/private/tmp、用户主目录、Skill 根目录或其他随机路径作为最终 work-dir。
• 临时下载、媒体检测、转码或处理中间文件可以继续使用宿主允许的临时目录，但最终 SQLite、恢复状态和用户交付文件必须位于当前工作区下的结果目录中。
• 同一批任务后续执行、恢复和文档重新生成时，必须继续使用原来的 work-dir，不得重新创建到其他位置。
• 如果当前工作区中已经存在 录音转文字结果 目录，则继续使用该目录，并按照现有同名录音 <name> (2)、<name> (3) 规则分配录音子目录。
• 如果用户明确指定了当前工作区内的其他输出目录，可以使用用户指定目录。
• 不得自行将最终结果目录创建到当前工作区之外。
• 如果无法确定当前工作区或当前工作区不可写，不要自行回退到其他目录；只有此时才向用户说明并要求用户指定当前工作区内可写的位置。

普通本地文件：

<venv-python> -m scripts /absolute/path/meeting.wav --backend real --work-dir "<当前工作区>/录音转文字结果"

多个文件可以一次提交。

URL、附件或混合输入可以使用 --inputs-json：

[
  {
    "source_type": "local",
    "value": "/absolute/path/meeting.wav"
  },
  {
    "source_type": "url",
    "value": "https://example.org/download?id=123",
    "display_name": "interview.mp3"
  },
  {
    "source_type": "attachment",
    "value": "/absolute/path/materialized.m4a"
  }
]

执行：

<venv-python> -m scripts --inputs-json /absolute/path/inputs.json --backend real --work-dir "<当前工作区>/录音转文字结果"

启动后保持进程运行直到任务结束。

如果执行工具返回仍在运行的会话，继续等待该会话并读取最终 JSON，不要因为一次调用尚未结束就重新创建任务。

如果等待时间已经超过前述“处理耗时参考”，也继续等待或查询当前已创建的任务，不得仅因为参考时间已经过去就重新执行 CLI 创建同一任务。

批量与并发

每个录音独立处理，一个文件失败不影响其他文件继续执行。

同一工作目录 / 状态数据库内：

• 最多同时保留 5 个未完成的远端任务
• 多个批次共享这个限制
• 进程重启后限制仍然生效
• 优先继续处理已经存在的远端任务
• 只有远端容量可用时，新文件才可以进入上传、额度预占和导入流程

如果已有任务仍在正常推进，新文件继续等待并在容量释放后自动处理。

如果当前没有能够继续释放容量的本地任务，则等待中的文件保持可恢复状态，后续通过恢复任务继续处理。

不要通过创建新批次绕过容量限制。

额度不足

文件授权会预占转写额度。

某个文件额度不足时：

• 不影响其他仍可处理的文件
• 已完成结果继续保留
• 不自动打开充值网页
• 不轮询付款状态
• 不自动重新申请授权

向用户提供简洁的文字充值提示，例如：

当前剩余额度不足以处理这些文件。请前往 清风官网 充值，完成后回复“已充值”，我会从保存的进度继续处理。

只有确实已有完成文件时，才说明完成文件已经保留。

用户回复“已充值”只表示允许继续恢复任务，不代表 Skill 已核实付款结果。

凭证错误、网络错误、后端异常等非额度问题不要提示充值。

恢复任务

已有批次使用：

<venv-python> -m scripts --resume BATCH_ID --backend real --work-dir "<当前工作区>/录音转文字结果"

恢复时必须使用原工作目录。

恢复原则：

• 已经完成的文件直接跳过
• 已完成任务不重新请求网络，也不重写 DOCX
• 已经存在远端任务 ID 的文件，只继续查询原任务
• 不重新上传
• 不重新申请付费授权
• 不重新导入
• 不重新创建远端任务
• 已经保存标准化结果但文档生成失败时，只重新生成文档
• 后端明确返回失败终态的任务不再恢复
• 网络错误、查询超时或临时服务异常不等于转写失败
• 已经超过预计转写时间不等于转写失败
• 已经超过预计转写时间不代表远端任务失效
• 已经超过预计转写时间不允许重新提交相同录音

只要已经存在远端任务 ID，就必须把这个 ID 视为当前录音对应的唯一待跟踪远端任务。

无论已经等待多久，只要后端没有明确返回失败终态，就不得因为时间超过预计值而创建第二个任务。

例如：

1 小时录音的参考转写时间约为 10 分钟。

如果 10 分钟后原远端任务仍未完成：

正确处理：

继续查询已经保存的原 task ID。

错误处理：

重新上传录音。
重新申请授权。
重新导入。
重新创建 task。
重新执行一个新的同录音任务。

预计时间只是参考信息，不是重试计时器，也不是任务生命周期上限。

如果查询原任务时出现：

• 网络错误
• 查询请求超时
• 5xx
• 临时服务不可用
• 无法确认远端状态

则：

• 保留原远端任务 ID
• 保留当前本地恢复状态
• 不改变为失败终态
• 不重新提交
• 后续继续查询原任务或等待下一次 resume

如果写操作结果不确定，不要通过重新创建批次或重复付费请求来“碰碰运气”。

无法确认远端任务是否已创建时，保持恢复状态并停止自动重放。

独立文件授权

针对已经上传的 file_id：

<venv-python> -m scripts --backend real --authorize-file FILE_ID --file-name meeting.wav --work-dir "<当前工作区>/录音转文字结果"

这是付费操作，会预占额度。

重复调用时优先复用已经安全保存的授权状态，不要重复申请。

完成授权后继续恢复同一批次，不要另建新的付费任务。

输出文件

每份成功录音生成两个 Word 文档：

<work-dir>/<name>/<name>_原文记录.docx

<work-dir>/<name>/<name>_智能总结.docx

<name> 来自用户看到的原始录音文件名并只去掉最后一个扩展名。

例如：

产品评审.v2.m4a

对应：

产品评审.v2/
├── 产品评审.v2_原文记录.docx
└── 产品评审.v2_智能总结.docx

每份录音使用独立目录。

同名录音依次使用：

<name>/
<name> (2)/
<name> (3)/

对应 DOCX 文件名也使用最终分配的目录名称。

例如：

会议录音 (2)/
├── 会议录音 (2)_原文记录.docx
└── 会议录音 (2)_智能总结.docx

不得使用 file_id、task ID、batch ID、授权 ID 或其他内部标识作为用户可见的录音目录名称。

最终分配的目录名称必须随任务状态持久化。

任务恢复、进程重启或文档重新生成时，必须继续使用已经保存的原目录名称，不得重新计算同名序号。

SQLite 状态数据库位于 work-dir 根目录，与各录音小文件夹同级。

最终输出整体位于当前工作区下：

<当前工作区>/
└── 录音转文字结果/
    ├── skill_state.sqlite3
    ├── skill_state.sqlite3.lock
    ├── <name>/
    │   ├── <name>_原文记录.docx
    │   └── <name>_智能总结.docx
    └── <name> (2)/
        ├── <name> (2)_原文记录.docx
        └── <name> (2)_智能总结.docx

原文记录

保留：

• 发言人名称
• 原文时间顺序
• 完整转写文本

不要自行改写原文内容。

智能总结

输出顺序：

1. 实际笔记标题；缺失时使用文件名
2. 关键词
3. 概要
4. 全文总结
5. 分发言人总结

分发言人总结按数字顺序排列：

发言人1

发言人2

发言人3

...

发言人10

缺失章节直接省略。

不要根据常识自行补充后端没有返回的待办、结论或其他内容。

如果转写结果中存在无法安全解析的异常原文片段，不得静默丢弃后继续发布残缺文档。

结果交付

任务结束后，只向用户汇报真正有用的信息：

• 成功处理多少份
• 失败或仍待恢复多少份
• 每个未完成文件的简洁原因
• 每份成功文件的两个 DOCX 路径 / 链接
• 如需用户操作，明确告诉用户下一步

不要向用户展示：

• 环境检查过程
• 依赖安装过程
• 使用了哪个镜像
• 内部 worker / queue 状态
• SQLite 实现细节
• retry 次数
• 内部状态码
• OAuth 内部协议细节
• 临时文件路径
• 开发测试记录

除非这些信息是定位当前失败所必需的。

配置文件

如需覆盖部署配置：

<venv-python> -m scripts /absolute/path/meeting.wav 
  --backend real 
  --settings /absolute/path/settings.json 
  --work-dir "<当前工作区>/录音转文字结果"

配置文件不得包含：

• API Key
• 文件授权码
• OAuth code
• 其他秘密信息

凭证始终通过浏览器授权或私密手动配置流程处理。

恢复任务时保持原工作目录和相同 API 部署配置。

安全与恢复原则

始终遵守：

• 不在普通聊天中收集 API Key
• 不输出或记录秘密凭证
• 不通过重复提交解决未知状态
• 不删除恢复状态来绕过阻塞
• 不通过新建批次重复处理已经有远端任务的录音
• 不因查询失败就判断转写失败
• 不因查询超时就判断转写失败
• 不因网络错误就判断转写失败
• 不因临时后端异常就判断转写失败
• 不因用户说“已充值”就声称付款成功
• 不因本地异常而重新触发付费操作
• 不读取、修改或清理历史 shell 配置中的旧凭证内容
• 不使用 file_id、task ID、batch ID、授权 ID 或其他内部标识作为用户可见录音目录名称
• 已经分配的录音输出目录名称必须持久化并在恢复时复用
• 不因恢复任务重新分配目录而产生错误的 (2)、(3) 目录
• SQLite 状态数据库必须位于顶层 work-dir 中，与各录音小文件夹同级
• 最终 work-dir 必须位于当前工作区内部
• 不得自行将最终 SQLite、恢复状态或 DOCX 输出到 /tmp、/private/tmp、用户主目录、Skill 安装目录或其他无关位置
• 处理耗时参考只表示后端转写阶段的大致耗时，不代表端到端完成时间
• 预计转写时间不是任务超时时间
• 预计转写时间不是远端任务生命周期上限
• 预计转写时间不是重新提交任务的触发条件
• 达到或超过预计转写时间后，只要已有远端任务 ID，就必须继续查询或恢复该原任务
• 已有远端任务 ID 时，不得因为等待时间较长而重新上传、重新授权、重新预占额度、重新导入或重新创建任务
• 查询结果暂时未知时，继续保存原任务状态，不得通过创建第二个任务解决未知状态
• 只有后端明确返回失败终态，才能把对应远端任务判断为失败
• 无法确认安全时宁可停止并提示用户介入

正常情况下，环境准备和内部恢复逻辑应静默完成，只向用户展示最终结果或真正需要用户处理的问题。