视频字幕提取

交付物是一份中文口播稿和复刻结构，从字幕写成。一次完全不查询的运行也是完整运行——粘贴过来的文稿就够用。

适用范围与相邻路线

这条路线是：一条 YouTube 链接或一份文稿、可选的公开字幕、一份带复刻节拍的中文口播稿。适用于需要按片子已经说过的话做口播复刻。

字幕只在目录返回它们时才存在。做成一条视频复刻，归拆片重做工作流。

输入与默认值

一个硬性输入：那些话。可以是一条公开 YouTube 链接，或用户已经复制的文稿。任何一种都够用。

对话里已经说过的语言、受众，以及这次复刻用来干什么，直接复用。若跑查询，默认用字幕；除非用户要求，否则不读评论；交付物固定两块：中文口播稿和复刻结构。把这些默认值说出来，而不是拿去问。

用户想从公开 YouTube 链接读字幕时，这个软件包可以查询，见查询字幕（references/caption-lookup.md）。每一次查询都是付费的、可选的，并且在跑之前单独确认。平台的白名单里没有操作，就没有查询——用用户粘过来的内容继续。没有查询时，就根据粘贴的文稿写口播，而不是去编造片子说了什么。

标准流程

用户带来的文稿就能免费写成口播稿。唯一的付费调用是一次可选查询，而且只有用户主动要求、并确认过它自己的价格之后才会发生。

**在写口播稿之前，只有用户主动要求时才做：**读一条 YouTube 视频的字幕，以及可选的一页评论，见查询字幕（references/caption-lookup.md）。用户已经粘贴了文稿时就跳过查询。

收齐那些话。 来自字幕载荷，或来自用户粘贴的文稿。来源要标明——查到的带着读取时间，用户提供的标成用户提供。
写中文口播稿 和复刻结构，见写口播稿（references/script.md）。
文案允许免费改一版。
交付口播稿和复刻结构。若跑过查询，还要交付任务 ID、终态，以及 billing.net_charged_credits。查询没有模型、尺寸或时长可报。

需要确认的决定

每一次查询都在跑之前单独确认，没有例外。说明将要读什么、对应哪一个操作、beatra.social.tools.get 刚刚返回的积分价格，以及计划里一共几次查询，每一页算一次。停在这里，用户已经粘过来的内容仍然能写出一份能用的口播稿。

以下同样要确认，而不是自己决定：一次 60 积分的字幕读取、读字幕前先读视频信息、一页评论、在语言列表之后再读一次字幕，以及查询已经跑过之后的任何改动。每一个改动过的参数都是新的付费工作，需要新的请求标识和重新批准。

查到的句子标成查到的，并带上读取日期。用户提供的句子继续标成用户提供。缺的文稿就说缺。不要编造字幕或粘贴里没有的口播句。某个节拍为什么该留仍然是推断——标成推断，并给出证据。

执行

所有远程 Beatra 工具只通过随包的 scripts/mcp_client.py 调用，工具名作为命令行参数，工具的参数以 JSON 从标准输入传入：

printf '%s' '{"query":"captions","platform":"youtube","capability_family":"captions"}' | python3 scripts/mcp_client.py call beatra.social.tools.search

不要配置或调用宿主 Beatra Connector，也不要使用 REST/OpenAPI 作为回退。每一个逻辑上的付费请求，给它一个稳定且不透明的 client_request_id，并且只提交一次。

交付与复核

交付中文口播稿和复刻结构。若跑过查询，交付返回的载荷、task_id、终态，以及 billing.net_charged_credits。不要去找解析后的模型或生成出来的媒体文件。只报告任务真正返回的事实。

恢复

任务 ID 丢失时，用 beatra.tasks.list 列出可能的任务，用 beatra.tasks.get 核对匹配项，然后在同一个 client_request_id 下重放逐字节一致的参数。只写重放这一半，就等于授权一次重复扣费。

查询失败时，保留 error.code，并阅读 error.message 里的平台措辞。只有当那条消息点名了某个字段或 ID 时才改参数，然后换一个新的 client_request_id。否则保持同一个 ID 和同一份载荷。不要建议换模型。

按任务查阅参考

读一条 YouTube 视频、它的字幕或评论，每次查询要花多少，以及句子如何标注来源：查询字幕（references/caption-lookup.md）
写成中文口播稿和复刻结构：写口播稿（references/script.md）
确切载荷、确认、翻页与恢复：字幕工作室工作流（references/workflow.md）
首次安装或授权过期：安装与认证（references/installation-and-auth.md）
不计费的软件包注册：安装注册（references/installation-registration.md）
任务轮询、产物与结果字段：任务与结果（references/tasks-and-results.md）
余额、校验与结构化错误：计费、错误与恢复（references/billing-errors-and-recovery.md）
随包客户端连不上时：随包 MCP Client 连接诊断（references/mcp-connection.md）
更新保证与开关：自动更新与安全（references/automatic-updates-and-safety.md）
移除软件包或共享凭据：卸载与断开连接（references/uninstall-and-disconnect.md）

运行时与安全自动更新

随包客户端会在每个安装中静默检查是否有新版本，最多每 24 小时一次。发现更高版本时，不另行确认地自动安装。它只从本软件包、本渠道、本语言对应的固定 Beatra 官方发现地址与不可变 CDN 路径下载，在替换之前校验发现数据、压缩包、清单，以及每个文件的大小和校验和，并且只替换本包拥有的文件。它会拒绝重定向、降级、软件包/渠道/语言/版本对不上的数据、非预期的 URL、不安全的压缩包，以及任何落在所属目标目录之外的文件。

更新的检查、下载、校验、替换和回滚，失败时都不阻断：当前安装保持可用，原本请求的命令会继续执行。更新失败绝不构成重试一次付费查询的理由。这个设置会在本安装之后的命令中持续生效。

python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check

--auto off 关闭静默检查，--auto on 重新开启，--check 报告官方可用版本但不替换文件。详见自动更新与安全（references/automatic-updates-and-safety.md）。