插件管理

插件页面让实例所有者或管理员安装能力扩展，再为每个 Bot 单独保存配置和启用。安装与 Bot 启用是两步：安装成功不会自动把工具开放给所有 Bot。

安装可信插件

在管理面板打开 插件，选择内置插件，或填写第三方公开 GitHub 仓库及提交。

第三方来源只支持 https://github.com/owner/repository 格式和完整 40 位小写 Git SHA。不能用分支名、tag、短 SHA、私有仓库、带凭据的链接或仓库子目录。发布内容必须已经构建好；服务器不会自动安装依赖或执行构建脚本。

安装前需要明确接受服务端访问权限。插件代码在 Hanori 服务端进程中运行，能够获得该进程的权限；这不是沙箱。只安装你信任并审核过的发布提交。工具上的“只读”声明用于限制可见能力，不能隔离插件代码本身。

为 Bot 配置和启用

1. 选择已安装插件和目标 Bot，填写该插件声明的字段。
2. 保存配置，再启用。必填字段不完整时可以保存停用草稿，但不能启用。
3. 在测试聊天中使用插件支持的输入，并检查实际返回状态。

配置对每个 Bot 独立保存。插件启用后，工具仍按当前身份和聊天上下文筛选；声明为管理员专用的工具不会向普通用户开放，只读上下文只开放声明为只读的工具。管理插件与调用插件工具是不同权限。

Cookie、API Key 等秘密字段保存后只显示“已配置”，不会回显原值。留空表示保留已存秘密；点击清除才会删除。新输入在保存前只保留于当前页面内存，不写入浏览器本地存储。服务器加密保存秘密，并仅在已启用、已审核配置的服务端运行时解密。

测试已保存配置 使用已保存且启用的配置。插件有专门检查钩子时运行该钩子；没有钩子时，只验证它能创建合法会话。测试通过不一定说明 Cookie 有效、账号已登录或真实资源可访问。

若其他页面已修改配置，请重新载入并核对最新值。插件清单变化时，已有 Bot 配置会要求重新审核和保存，审核完成前不会执行。每次工具或检索调用都检查当前安装与 Bot 配置；保存更改、更新、卸载或服务停止后，会取消旧会话，迟到结果不会继续建立引用。

单次插件工具或检索调用最多等待 10 分钟，同时受调用方的取消信号和 AI 单轮总时限约束。管理员确认后的 ASR 在独立后台运行，使用下文的媒体任务时限。

扫码登录并保存 Cookie

支持扫码的插件会在目标 Bot 的配置中显示 扫码登录。Bilibili 和网易云音乐提供该入口：

1. 先保存当前配置草稿；如有清单变更提示，先审核并保存。
2. 点击 扫码登录，使用对应平台的手机 App 扫描面板上的二维码，并在手机上确认。
3. 等待面板显示已连接。服务器会验证平台账号，再将 Cookie 加密保存到当前 Bot；页面不会收到 Cookie 原文。

插件停用时也可以登录，登录不会自动启用插件、音频转录或视频下载。重新登录会替换该 Bot 已保存的平台凭据，其他普通配置和启用状态保持原样。确认保存后，旧工具会话和依赖旧配置的未完成媒体任务会取消；已开始向 Telegram 上传的视频无法承诺撤销。

二维码会话最多保留 5 分钟，平台可能更早使其失效。过期后重新获取；保存开始前，关闭弹窗可以取消登录，失败、取消或过期不会覆盖旧 Cookie。手机确认并验证通过后会自动保存，进入保存阶段后关闭窗口不会撤销保存。如果页面提示无法确认保存结果，先关闭弹窗、重新加载配置再判断是否重试。服务器重启、插件更新或配置发生变化后，需要重新开始。

扫码来自服务端的独立平台登录会话。它不会读取你浏览器里已有的登录信息，也不要求把账号密码填写到 Hanori。平台可能要求手机确认或额外验证；遇到平台拒绝或风控时，可以继续手动填写 Cookie。Cookie 失效后需要重新登录，目前不提供后台自动续期。

Bilibili 手机确认后，服务器优先使用扫码接口返回的 Cookie 验证账号；接口仅返回跨域登录票据时，再兑换票据并验证。游戏站的后续页面跳转不影响已取得凭据的账号校验，登录链接中的参数不会被当作 Cookie 保存。

更新、回滚和卸载

第三方插件更新仍指定完整提交 SHA，不会自动追踪默认分支。更新前审核目标提交的代码与配置变化；如果清单变更，逐个 Bot 重新审核配置。

回滚使用已保留的上一版本提交与清单，不是任意历史版本选择器。回滚后也要检查 Bot 配置是否需要审核。内置插件随 Hanori 更新，不通过第三方仓库更新按钮切换版本。

卸载会停止插件并停用它在所有 Bot 上的配置，保留已下载版本和加密配置草稿以便恢复。重新安装后仍需确认配置并手动启用；修订号继续递增，旧页面中的保存操作不会覆盖新状态。卸载不等于清除秘密或回收磁盘文件。

Bilibili 与网易云读取

这两个内置来源是链接解析与资源查询，不是关键词搜索引擎。启用后可通过统一检索查询元数据，返回当前轮有效的资源引用，再明确调用字幕或歌词工具读取正文。元数据成功不代表字幕、歌词或音频可用。

兼容接口与平台要求可能改变。Cookie 只发送到对应受信 API 源；空字幕响应会区分登录要求、认证未确认和确认没有字幕。空歌词不自动判为纯音乐。歌单与专辑预览会标注截断与未知总数，不能视为完整列表，也不能假定存在下一页。

字幕和歌词每页最多 40 条、4000 个正文字符；过长单条内容会标注截断。平台字幕、平台自动字幕和歌词保留来源，内容只作不可信资料阅读。默认检索不读取完整正文，也不自动把整首歌词或整段字幕复制到回复。

Bilibili 字幕优先使用固定版本的 yt-dlp B 站提取器，获取当前分 P 的平台字幕及平台自动字幕，排除弹幕。提取器不可用、超时或提取失败时，回退到现有 B 站接口；两条链路使用同一个 Bot 的登录凭据。空字幕结果仍核对登录状态，不会直接触发付费转录。平台字幕目前供 Bot 读取和总结；下文的 SRT/VTT 全文导出针对 ASR 任务结果。

插件不提供付费、DRM、账号权限或地区限制绕过。音频转录只处理 Bilibili 音轨，不代表已经观看视频画面，也不能据此可靠识别说话人。

通用 yt-dlp 视频读取与下载

在插件页面安装 yt-dlp（hanori.ytdlp），然后为目标 Bot 保存配置并启用。它自动调用 yt-dlp 的全部内置站点提取器，包括 YouTube 和其他受支持的视频站点，也可识别普通网页中的 HTML5 视频与媒体直链；不再逐个维护站点白名单。Bilibili 专用插件及其扫码登录、分 P、ASR 功能仍可独立使用。

先开始总结视频

1. 选择目标 Bot。站点 Cookies 可以先留空，视频下载保持关闭，其余选项保留默认值。
2. 选择表单底部的 保存配置，再选择上方的 启用。后续修改也须保存才生效。
3. 向该 Bot 发送一个具体视频链接，并说「帮我总结这个视频」。如果站点提示需要登录，再补充 Cookies。

测试已保存配置只检查 yt-dlp 插件能否启动，不会实际访问 YouTube 或验证 Cookies；请用视频链接确认访问结果。内容总结依赖可读取的字幕，没有字幕时不会自动启动语音转录。下方时长、大小和次数限制只影响视频文件下载，不影响字幕总结。

发送一个具体视频的 HTTP(S) 链接并要求总结时，Bot 可先读取标题、简介和章节，并直接用返回的推荐字幕读取带时间戳的正文。推荐优先选择原始语言的字幕，同语言优先平台 CC；原始语言未知时优先可用的平台 CC。平台 CC 与自动字幕分别标记来源，但 CC 不保证经过人工校对；只有简介时会明确标为元信息，不能当作已读取视频内容。格式列表提供编码、分辨率和预估大小，不向聊天公开带签名的下载地址。元信息和同一轨道的字幕在当前轮复用，查元信息不会默认下载整段音视频。

查找字幕与恢复失效引用

lookup_video 返回 primaryTrackReference 和推荐轨道的语言、来源、翻译标记，可直接交给 read_transcript，无需先翻字幕列表。没有可读取轨道时推荐引用为 null，不会把简介当字幕。

需要其他语言时，list_subtitles 支持 language（如 en，同时匹配 en-US）和 source（platform_cc / platform_auto），先筛选再分页。默认平台 CC 排在前面；已识别的 YouTube 自动翻译按原轨折叠，通过 translationCount 提示可用翻译语言数，不逐条占用分页名额。指定语言会直接列出该语言的翻译，也可设置 includeTranslations: true 展开全部；total 与 nextOffset 都以当前筛选和折叠结果为准。无法确认来源的其他站点自动字幕会保留，不根据名称猜测是否为翻译。

字幕正文的 track: translation 表示已识别的自动翻译，不能称为原语字幕。视频与字幕引用只在当前回合有效；跨回合、客户端重建或清理后返回 reference_expired，无法识别或不存在的引用返回 unknown_reference。两种错误都会提示用原视频链接重新调用 lookup_video，再使用新引用；上游响应格式错误仍返回 invalid_response。引用不会跨 Bot 复用，也不会为恢复旧引用保留登录凭据。

需要登录时填写 Cookies

在自己的浏览器登录目标站点，用支持 Netscape 格式的导出工具导出该站点的 cookies.txt，再用文本编辑器打开。把文件内容粘贴到页面输入框，不是文件路径；第一行通常是 # Netscape HTTP Cookie File。YouTube 的导出流程请参考 yt-dlp 官方指南。页面中输入框旁的「需要登录时，怎样填写 Cookies？」也可展开查看步骤。

站点要求登录时，可在插件的多行秘密输入框粘贴 Netscape 格式的 Cookies 文本，保留原文件的换行和制表符；输入遮蔽显示，保存后清空。仅导出需要的站点，文本最多 16,384 字符；不是单行 Cookie 请求头。凭据按 Bot 加密保存，依 Cookie 域名匹配发送，跨站跳转不会转发前一站的认证请求头。服务不会读取服务器上的浏览器登录信息，也没有通用扫码登录。匿名访问、Cookie 登录均不能保证绕过 YouTube 的机器人检查、平台限流或地区限制。

保存后输入框清空是正常的；显示「已保存密钥」表示凭据已保存，留空会保留已存内容。Cookies 相当于登录凭据，请勿发到聊天里。

需要视频文件时开启下载

启用 允许下载视频并发回 Telegram 后，管理员明确要求下载单个视频时会创建后台任务。该任务复用下文的视频缓存、取消、配额和投递机制；默认最长 600 秒、最大 45 MB，并受 Telegram 50 MB 上限约束。Bilibili 与通用下载共用执行队列和磁盘预算，配置变更只取消对应插件的任务。支持 yt-dlp 的原生 HTTP、HLS 和 DASH 下载路径，音视频在无网络的转换服务中合并或转换为 H.264/AAC MP4。上游没有提供时长时，下载仍受字节、时间和磁盘预算约束，转换后检查实际时长再发送。需要同时启用部署中的 media 转换服务；只读元信息和字幕不需要它。

请求单个视频链接；播放列表需要选择其中的视频，直播不进入文件下载队列。DRM、需要浏览器模拟或外部下载器的站点/协议可能不可用。无字幕不会自动启动付费 ASR；现有 ASR 仍由 Bilibili 专用插件提供。工具返回 login_required、rate_limited、unsupported_url 等错误时，Bot 应说明实际原因，不用其他网页的介绍冒充视频总结。

Docker 镜像包含固定版本的 yt-dlp[default] 和匹配的 YouTube EJS 组件，使用镜像已有的 Node 运行时。源码开发需要在启动服务所用的 Python 环境安装 infrastructure/bilibili-ytdlp/requirements.txt；该路径为兼容现有部署保留，依赖供两类插件共用。所有提取器请求经过公网地址校验、DNS 固定、字节上限和取消控制；站点支持不等于当前网络出口上的真实访问已通过。

可选 Bilibili 音频转录

转录默认关闭，与平台字幕读取独立。先查询平台字幕：有字幕时直接使用；确认已登录且没有字幕时，Bot 可以向管理员提出转录建议。建议只创建待确认任务，不下载音频、不向 ASR 上传，也不开始转录。没有 Cookie、登录状态无法确认或音频无权访问时，不会通过 ASR 绕过限制。

配置公共 ASR 账户

启用前，由实例维护者按 Docker 部署启动 media 转换服务。实例所有者或管理员在 设置 → 公共音频转录 配置供应商；每家供应商保存一个账户，供所有 Bot 共用。这里的凭据独立于聊天模型 Provider，不需要为每个 Bot 重复输入。

供应商默认停用、没有密钥、单价为 0。保存有效凭据、填写当前每分钟单价并启用该账户后，才成为候选。单价 0 表示价格未知，不能当作免费；Groq 只有管理员明确勾选“此密钥属于免费计划”后才允许零单价。应用不能自动核实 Groq 账户计划，付费计划必须填写实际价格。密钥加密保存、不回显；留空保留原值，显式清除在保存后生效。

确认前按腾讯云、阿里云、Groq、OpenAI 兼容顺序考虑已配置账户，并参考本实例记录的免费政策用量；这不是供应商账户的余额查询。确认卡会显示最终供应商和模型，确认后不会静默换成其他账户、模型或收费计划。

以下公开规则于 2026-10-03 核实，实际账号资格、地域、已消耗额度及之后的规则以供应商控制台为准：

• 腾讯云常规录音文件识别每月有 10 小时免费额度；大模型 1.0 / 2.0 不适用该免费额度。常规版本后付费首档当前为 1.75 元/小时，可按账户实际方案填写每分钟价格。腾讯云计费规则
• 百炼北京地域 paraformer-v2 每月提供 36,000 秒，月初发放、当月有效；当前公开单价为 0.00008 元/秒，即 0.0048 元/分钟。其他模型的新人额度有效期不能直接套用到 Paraformer。百炼模型价格
• Groq Whisper 免费计划公开速率限制为每日 28,800 秒、每小时 7,200 秒，由组织共享；实际账号限制可能不同，触及速率限制不自动切换收费供应商。Groq 速率限制

账户的实际剩余免费额度默认显示未知。管理员可在核实控制台后登记有效期；到期后核实状态失效。费用估算仍按完整时长与配置单价保守预留，不抵扣免费额度，不把失败或取消当作退款。费用预留包含时长误差与 10% 余量；Groq 付费请求按至少 10 秒估算，以官方计费说明为准。上传前再次用转换后的实际时长检查费用预留，超限则拒绝提交。CNY 和 USD 各自统计，不能直接相加。账户默认单任务 / 每日 / 每月金额上限分别为 CNY 1 / 3 / 10，USD 0.2 / 0.6 / 2；月分钟数默认 600，可在公共设置修改。

然后在 插件 → Bilibili → 目标 Bot 登录或保存可访问目标视频的 Cookie，明确启用音频转录与音频外传，并核对 Bot 限额。单视频默认限 5 分钟，每管理员每日 3 个任务、10 分钟和 1 个供应商货币单位；每管理员每月默认 120 分钟、10 个货币单位，每 Bot 每月默认 600 分钟、50 个货币单位，同时受更小的公共账户预算约束。时长、次数和分钟数须为正整数；不会截取超长内容来绕过限制。

旧版预置使用 OpenAI 兼容的 whisper-1，凭据保存在各 Bot 插件里。本次 Bilibili 清单升级到 1.3.0，预置改为公共腾讯云常规 ASR。已有配置在清单变化后须复核并保存；保存前先把所需凭据迁移到公共 ASR 设置。仍能读取到旧配置时会明确标记为旧版 OpenAI，并继续要求逐次确认；重新保存新清单不会自动把旧凭据复制到公共账户。升级时尚未提交识别的旧任务会失效，需重新提出并确认，不会沿用旧任务自动收费。

音轨流式下载限 512 MiB。腾讯云和百炼通过签名文件链接转录长音频，单段最多 5 小时，转换后的 16 kHz 单声道 PCM WAV 约为 576 MB；校验、保存及供应商下载均流式处理，不把长音频整体读入内存。该限制与 Bot 配置的单视频秒数上限共同生效。腾讯云 5 MiB 以内仍直接提交；Groq / OpenAI 兼容直传仍限 20 MiB（约 10 分 55 秒），当前不自动分段。URL 转录需要供应商可访问的公网 HTTPS BETTER_AUTH_URL。签名音频副本在转录结果保存成功后删除；删除失败会保留清理待办，后台及重启后继续重试，不丢弃已保存的结果，也不重复识别或通知。失败、取消或恢复中的任务仍保留音频供已提交的云任务读取，24 小时链接有效期结束后由后台清理。文件系统权限或 I/O 错误可能延迟本地删除，但不会延长签名链接有效期；恢复存储可写后，后台会继续清理。

Bilibili 清单 1.3.1 更新了长音频配置说明，已有配置须在面板复核并保存。提高单视频时长不会自动提高分钟数或费用预算；长视频仍可能因每日分钟数、单任务或账户金额上限被拒绝，确认前会展示原因。

管理员逐次确认、取消与恢复

管理员明确请求转录，或已登录的视频没有字幕时，Bot 会提供待确认卡片与任务 ID。卡片显示视频标题、链接、时长、供应商、模型、免费额度状态、预估费用和费用上限。只有发起任务的当前管理员本人，可以在原 Bot、聊天与话题中确认；仅口头回复“可以”、模型自动调用工具、另一位管理员点击或转发卡片均不能授权提交。

已确认的转录在独立后台执行，不继承聊天回复、模型步骤或插件工具调用的超时；聊天结束不会取消转录。音轨下载与隔离转换各最多等待 30 分钟，腾讯云 / 百炼异步任务最多等待 24 小时；单次网络请求仍有较短超时，查询暂时超时会继续轮询，不会重新提交识别。腾讯查询接口返回请求频率限制时也会等待后查询原任务，不重复上传音频；创建任务失败、配额错误及识别终态失败仍会报告错误。管理员取消、服务关闭、权限或配置变化仍可停止本地任务。腾讯云已记录的任务可跨日期恢复查询，超过提交后 24 小时不再查询，以免超过供应商任务有效期。

确认卡有效期为 15 分钟，只能消费一次。点击确认时，服务器重新检查管理员身份、插件与公共账户版本、视频限制及费用预算，通过后才进入后台下载、转换和转录。重复点击不会重复提交。超时、取消或设置变化使待确认授权失效，需要重新提出任务。实例一次处理一个音频任务。

可凭任务 ID 查询状态、取消或分页读取结果。Bot 工具只访问当前 Bot、聊天和用户自己的任务；实例所有者或管理员还可在网页管理该 Bot 的任务。取消可停止本地后续工作，但供应商已收到的任务没有可撤销保证：请求已经提交时只记录取消请求，不能声称已撤销识别或收费。

插件停用、卸载、更新或配置改变会使未完成任务失效。提交结果未知时不会重新上传，以免重复收费。服务重启后只查询已记录的供应商 TaskId，不新建供应商任务；超过供应商可安全查询的时间范围则结束恢复，核实旧请求状态与费用后再手动发起新任务。

查看与下载

在插件配置下方的 转录任务 查看最近 50 个任务，刷新状态或取消。完成后可分页查看、按关键字查询，每页最多 40 条字幕和 4,000 个正文字符；超长单条会标注截断。AI 转录可能有误，低置信度内容不能当作核实过的原文。

结果从任务创建起保留 24 小时，过期后正文会被清除。读取要求插件仍启用、配置仍有效且与任务创建时一致；保存新配置或更新插件后，旧结果可能不再可读。完成、失败、取消和过期均通知原聊天与话题；通知包含任务 ID、状态和固定失败码，不自动发送全文。通知采用至多一次投递，投递失败仍可在网页查询任务与有效结果；升级不会补发超过 24 小时的历史失败通知。

若要下载 SRT 或 VTT，先在该 Bot 配置中启用授权全文导出，再对网页当前任务单独勾选你有权处理和下载其转录内容。切换任务需要重新确认。导出全文不等于允许传播受版权保护的视频或字幕。

当前已实现配置、持久任务、取消恢复、分页和导出流程，并有本地合成内容测试。真实 Bilibili Cookie、平台音频访问和外部 ASR 的端到端可用性尚未验证；测试已保存配置 也不能证明这些链路已通过。

可选 Bilibili 视频下载

视频下载默认关闭，与音频转录独立，不需要启用 ASR 或允许向 ASR 供应商发送音频。在 插件 → Bilibili → 目标 Bot 保存可访问视频的 Cookie，启用 视频下载并发回 Telegram，核对下载和磁盘预算，再保存并启用插件。Bilibili 清单升级到 1.2.0 后，已有 Bot 配置须重新审核并保存。

默认单视频最长 600 秒、文件大小 45 MB；每 Bot、每用户按 UTC 日期限 5 个任务，取消和失败任务也占用当天预留。MB 使用十进制单位，1 MB 为 1,000,000 字节。面板数字字段没有人为上限，但须满足最小值、整数及服务端安全计算要求；Telegram 托管 Bot API 的 50 MB 上传上限仍有效，设置更大的文件上限不会突破它。超时长、超大小的视频会拒绝或失败，不会截取一部分后当作完整视频发回。

只在管理员明确请求时创建任务，例如：

下载这个B站视频并发给我：https://www.bilibili.com/video/你的BV号

验证通过后立即返回任务 ID。后台优先使用 yt-dlp B 站提取器取得选定单个视频或分 P 的 DASH 音视频流；提取器不可用、超时或提取失败时，回退到现有接口。服务器继续核对账号和平台下载权限，并按已保存的时长、大小及磁盘预算流式下载，再交给隔离 ffmpeg 使用 stream copy 合并为 MP4，最后以文件流上传到发起请求的 Telegram 聊天与话题。不会重新编码、下载合集、直播或绕过 DRM、付费及账号权限。检索、读取字幕、字幕缺失和下载完成都不会自动触发下载或 ASR。

可通过 get_video_download 查询自己的任务状态，通过 cancel_video_download 请求取消；任务状态记录保留 7 天，文件保留时间由缓存 TTL 单独控制。工具绑定当前 Bot、聊天、用户及话题，模型不能指定另一个发送目标或服务器路径。当前管理面板提供下载配置，尚无视频任务详情页面。聊天轮次结束不会取消已经创建的后台任务；插件停用、卸载、更新或配置改变会停止尚可取消的工作。进入 sending 后，取消不能承诺阻止发送，也不撤回消息。若状态为 delivery_unknown，先检查 Telegram 中是否已有文件，不会自动重发，以免重复投递。

服务器默认将成功文件缓存 30 分钟，缓存预算为 512 MB，保留至少 1024 MB 空闲磁盘空间。缓存预算至少须覆盖有效单视频大小上限的两倍再加 1 MiB，以容纳下载输入和合并输出的临时峰值；不足时不会启动任务。实例一次处理一个视频下载任务，并核对全局缓存占用及磁盘余量；音频转录和视频合并共用转换服务，按到达顺序一次处理一个转换任务。启动时清除残留文件，失败或取消后立即清理临时文件，成功缓存过期后定期清理；正在发送的文件保留到发送结束后再清理。缓存过期只删除服务器副本，已经发送到 Telegram 的文件不会撤回。

本地合成测试覆盖配置、工具和任务流程；真实平台访问及 Telegram 视频投递须单独验证。测试已保存配置 不会下载和发送视频。

排查问题

先检查插件是否已安装、目标 Bot 是否启用、清单是否待审核，再确认输入格式与 Cookie 状态。引用只属于当前回复；开始新一轮后，重新查询资源。

插件异常可能包含秘密，面板返回有界错误状态。分享诊断前移除 Cookie、Token、授权头和链接中的密钥。服务端插件故障、本地测试通过与真实平台可用性应分别判断。

扫码失败时，服务端日志会记录插件、Bot、登录会话编号、失败阶段和固定错误码，可按会话编号定位。该诊断不记录 Cookie、登录链接或平台原始错误内容。

开发第三方插件见插件开发契约。