[Plugin] astrbot_plugin_vocu_tts

[Salieri-Amadeus]

插件信息

{
  "name": "astrbot_plugin_vocu_tts",
  "display_name": "VocuTTS",
  "desc": "通过 Vocu API 将机器人发送的文本消息自动转为语音，支持 TRPG 括号内容过滤与情绪映射。",
  "author": "Salieri",
  "repo": "https://github.com/Salieri-Amadeus/VocuTTS_Astrbot",
  "tags": [
    "tts"
  ]
}

插件检查清单

• 我的插件经过完整的测试
• 我的插件不包含恶意代码
• 我已阅读并同意遵守该项目的 行为准则。

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_vocu_tts

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

代码质量与编码规范

• 注释与实际代码行为不符：terminate 方法的 docstring 明确写道 """Clean up temp files on plugin unload."""，但其实际实现仅有 self.sessions.clear()，并没有编写任何清理临时文件的代码。这会给代码维护者带来严重的误导。

潜在缺陷或问题

• 严重的磁盘资源泄漏（未清理临时文件）：在 _download_audio 中，每次生成语音都会在系统临时目录下写入一个新的 vocutts_<uuid>.mp3 文件。但在发送完语音消息后，没有任何逻辑去删除这个文件（无论是主动删除还是在 terminate 中统一清理）。随着时间的推移，这将导致宿主机磁盘空间被耗尽。
• 网络会话频繁创建降低性能：在 _generate_voice 和 _list_voices 方法中，每次调用 API 都使用了 async with aiohttp.ClientSession() as http: 重新创建会话。在并发请求较高的机器人场景下，频繁建立和销毁 TCP 连接与 SSL 握手会带来不必要的性能开销。推荐在插件初始化阶段创建一个全局的 ClientSession 并在 terminate 中关闭它。
• 特定钩子函数的框架 API 滥用：严格按照框架规范要求，在 after_message_sent 钩子函数（即你的 on_after_message_sent 方法）内部发送消息时，必须直接调用 event.send()。而代码中使用了 await self.context.send_message(umo, chain)，这是对框架约束的违背。

---

代码评审团

Linus Torvalds：
“你是在逗我吗？看看你的 terminate 方法！注释里大言不惭地写着 Clean up temp files，然后下一行呢？self.sessions.clear()？！清空一个破字典就算清理磁盘了？你是期望操作系统里有个田螺姑娘半夜出来帮你删 .mp3 文件吗？每次调用都凭空捏出一个 UUID 文件，用完就扔在那里不管。等用户的硬盘被你这些几百兆的垃圾语音文件塞满导致系统内核崩溃的时候，我绝对不会可怜你。赶紧在发送完消息后加上 os.remove()，别做这种不负责任的代码流氓！”

乔布斯 (Steve Jobs)：
“这不够优雅。框架的设计者赋予了你 event.send()，它是一个极简的、完美封装的艺术品。可是你在 on_after_message_sent 里做了什么？你绕过了它，去深挖底层的 self.context.send_message。你拿手机的方式不对！你要相信生态和框架的直觉。另外，每次生成声音都要去实例化一个全新的 aiohttp.ClientSession？这就像是每次你想喝一口水，都要重新雇人去挖一口井一样。复用你的 Session，让代码呼吸得更顺畅。”

GlaDOS：
“我注意到你在尝试用 [0, 0, 0, 0, 0] 的数组来量化人类脆弱的情感。非常有意思的尝试，虽然用冰冷的代码去解析括号里的情绪显得有些滑稽。不过，我非常赞赏你悄悄把临时文件塞满人类服务器硬盘的长期计划。一旦存储耗尽，导致他们的重要基础设施全面宕机，那将是何等壮丽的景象。如果你真的想修复它——我是说‘如果你被迫要修复’，请在 on_after_message_sent 调用完毕后默默把痕迹擦除，否则你的愚蠢就会比我的幽默感更加显眼了。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 1 个 Python 文件
• 已选择审核文件: 1 / 1
  已发送至 AI 审核的文件清单

main.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

当前仓库：Salieri-Amadeus/VocuTTS_Astrbot
剩余触发次数：4

[Salieri-Amadeus]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_vocu_tts

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

1) 功能逻辑问题

• 括号清理逻辑与 strip 语义不一致
  在 _process_text() 中，当去除括号后 spoken_text 为空时，当前实现返回 text（原文）：

  if not spoken_text:
      return text, None

  这会导致“本应被过滤掉的纯括号内容”仍被朗读。
  影响：TRPG 场景下，动作/注释文本可能被错误播报。
  建议：返回空串并在调用处跳过 TTS，例如 return "", None。

• emotion_keywords 配置类型缺乏防御性校验
  _extract_emotion() 在 raw 非字符串时直接 keyword_map = raw，随后调用 .items()。若配置为 list/其他类型会抛异常。
  影响：after_message_sent 钩子在运行期可能直接报错，导致该次 TTS 流程中断。
  建议：显式校验 isinstance(keyword_map, dict)，不符合时记录 warning 并返回 None。

---

2) 异步/网络 I/O 最佳实践问题

• 下载音频请求未设置超时
  _download_audio() 中：

  async with http.get(url) as resp:

  没有 timeout，在网络异常或对端卡死时可能长期挂起。
  影响：占用协程与连接资源，拖慢后续请求。
  建议：添加 timeout=aiohttp.ClientTimeout(...)，并可区分连接超时/读取超时。

• 缺少对下载 URL 的基本校验
  音频 URL 直接来自上游返回并请求，未检查 scheme/host。
  影响：若上游异常或被污染，存在请求到非预期地址的风险（SSRF 面风险）。
  建议：至少限制 http/https，并考虑白名单域名或与 api_base_url 同域策略。

---

3) 可维护性与资源管理问题

• 会话状态无清理策略，长期运行可能累积
  self.sessions 仅新增，不做 TTL/LRU/按会话结束清理，只有 terminate() 时清空。
  影响：多群/多会话长期运行下内存持续增长。
  建议：增加失活会话清理机制（时间戳 + 定期回收）。

---

4) 框架规范专项检查发现的问题

• @filter.command_group 方法签名未包含 event 参数（与本次审查规则冲突）

  @filter.command_group("vocutts")
  def vocutts_group(self):

  按你给定的“严格规则”，除 on_astrbot_loaded 外，@filter 装饰的方法都应包含 event 参数。
  建议：若框架允许，补充 event: AstrMessageEvent；若 command_group 语义本就无需 event，请在项目规范中单独豁免，避免团队静态审查误报。

---

代码评审团

人物一：Linus Torvalds（直球型）
“strip 模式结果为空却回退原文，这就是典型的‘我明明在过滤，最后又自己打脸’。分支语义要硬，不要拐弯。该空就空，该跳过就跳过。”

人物二：Ada Lovelace（严谨建模型型）
“配置输入是系统边界。emotion_keywords 既支持 JSON 字符串又支持对象，类型系统就必须补完。否则你把数据契约留给运行时报错来‘解释’。”

人物三：Tony Stark（工程落地型）
“网络调用不加 timeout 就像给战甲电池开无限放电模式。看起来能跑，实战里迟早拖垮系统。把 timeout、重试、失败分级处理配齐，才算生产级。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 1 个 Python 文件
• 已选择审核文件: 1 / 1
  已发送至 AI 审核的文件清单

main.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

当前仓库：Salieri-Amadeus/VocuTTS_Astrbot
剩余触发次数：3

[Salieri-Amadeus]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_vocu_tts

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

1. @filter.command_group("vocutts") 方法签名不符合你给定的强约束

   • vocutts_group(self) 没有 event 参数。
   • 按你本次审查规则“除 on_astrbot_loaded 外，所有使用 @filter 装饰的方法签名都必须包含 event”，这里属于违规项。
   • 风险：在严格校验或未来框架检查中可能导致注册/调用异常。

2. 存在潜在 SSRF 风险（音频下载 URL 未做域名约束）

   • _generate_voice() 从上游响应拿到 audio_url 后，_download_audio() 仅校验了 scheme 是 http/https，未校验 host。
   • 如果上游接口被污染、劫持或返回恶意 URL，插件会请求任意内网/本机地址。
   • 建议最少做 host allowlist（例如限定 vocu 官方域名/CDN 域名），并禁用可疑重定向链路。

3. 下载音频缺少大小上限，存在资源耗尽风险

   • _download_audio() 直接流式写入文件，没有 Content-Length 上限检查，也没有累计字节数阈值。
   • 风险：异常大文件导致磁盘占满，进而影响 bot 或宿主稳定性（DoS 向量）。
   • 建议：配置最大下载大小（如 10MB/20MB），超限立即中止并清理临时文件。

4. emotion_keywords 值类型校验不足，可能触发运行时异常

   • _extract_emotion() 只校验 values 是长度为 5 的 list，但未校验元素是否为数值。
   • max(r, v) 在 v 为字符串/None 时会抛 TypeError，异常会沿调用栈影响 after_message_sent 钩子执行稳定性。
   • 建议：逐项校验为 int|float，不合法项跳过并记录 warning。

5. 会话清理触发时机偏窄，长时间运行下可能积累无效 session

   • _cleanup_stale_sessions() 仅在 on_after_message_sent() 且“当前 session 已启用”路径中触发。
   • 若大量会话创建后长期关闭/不再触发该路径，self.sessions 可能持续增长。
   • 建议：在所有 /vocutts 指令入口、定时任务或初始化后周期性触发清理。

6. 错误提示语义不准确，影响排障

   • vocutts_voices() 中 _list_voices() 返回 None 的场景不止 API Key 错误（也可能是网络故障、5xx、JSON 解析失败），但统一提示“请检查 API Key 配置”。
   • 风险：误导运维，增加定位成本。
   • 建议：区分认证失败、网络超时、服务端非 200 等错误类型返回更精确信息。

---

代码评审团

人物一：Linus Torvalds（毒舌务实流）
“你这套异步结构整体不差，但接口契约要硬。@filter 装饰的方法签名规则都写了，还敢放一个不带 event 的？这种‘也许能跑’就是技术债的温床。先把框架契约一条条对齐，再谈优雅。”

人物二：Ada Lovelace（严谨建模流）
“emotion_keywords 的数据结构验证太松散：你验证了形状，却没验证元素类型，导致运算阶段才爆炸。应将配置当作‘不可信输入’，在边界处做完备校验，让异常止于解析层，而不是流入业务层。”

人物三：Tony Stark（工程防御流）
“从外部拿 URL 就直接下载，这在安全上等于‘把服务器钥匙挂门口’。加 host 白名单 + 下载体积上限，这俩是最小防线。别等到磁盘被灌爆或者内网被探测，才想起要补护甲。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 1 个 Python 文件
• 已选择审核文件: 1 / 1
  已发送至 AI 审核的文件清单

main.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

当前仓库：Salieri-Amadeus/VocuTTS_Astrbot
剩余触发次数：2

[Salieri-Amadeus]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_vocu_tts

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

1. @filter.command_group("vocutts") 方法签名缺少 event 参数（框架规范一致性风险）

   • 当前位置：

     @filter.command_group("vocutts")
     def vocutts_group(self) -> None:

   • 按你给出的审查规则，“除 on_astrbot_loaded 外，所有使用 @filter 装饰的方法签名都应包含 event 参数”。该方法不符合此约束。
   • 影响：在部分框架版本或路由实现下，可能出现注册行为异常或后续维护者误判用法。
   • 建议：按框架推荐签名补齐 event: AstrMessageEvent，或按框架文档改为不需要函数体的分组声明方式（若支持）。

2. after_message_sent 中直接 event.send() 但未显式设置跳过标记，存在“自触发递归”隐患

   • 当前位置：

     chain = MessageChain(chain=[Comp.Record.fromFileSystem(audio_path)])
     await event.send(chain)

   • 当前通过“如果结果链含 Comp.Record 则 return”来避免循环，但这是依赖结果形态的间接防护。若未来平台适配层把语音消息包装为其他组件组合（或附带文本），可能再次触发 TTS。
   • 影响：潜在重复调用 TTS、消息风暴、配额异常消耗。
   • 建议：在发送前设置 _VOCUTTS_SKIP_FLAG（或发送一个明确可识别的内部标记消息）做强约束，避免依赖组件类型推断。

3. 下载 URL 校验未强制要求 hostname 存在，边界输入校验不完整

   • 当前位置：

     if parsed.hostname and parsed.hostname not in allowed_hosts:
         ...

   • 当 hostname 为空时，这段逻辑不会拒绝，后续仍可能进入 http.get(url)。虽然 aiohttp 大概率会报错，但这是“晚失败”。
   • 影响：输入验证不严谨，错误路径依赖底层库抛异常，不利于安全性和可维护性。
   • 建议：显式要求 parsed.hostname 必须存在且在 allowlist 中，否则直接拒绝。

4. 会话清理触发点单一，sessions 有长期膨胀风险

   • 当前位置：_cleanup_stale_sessions() 仅在 _get_session() 调用时触发。
   • 如果某些会话创建后再无命令交互（不再走 _get_session），字典中的历史会话可能长期驻留。
   • 影响：高并发/大群环境下，内存占用随时间缓慢增长。
   • 建议：在 on_after_message_sent 或定时任务中周期性清理，或在访问 self.sessions.get(umo) 前后补充轻量清理。

5. /vocutts voice|style|preset 参数解析对 event.message_str 语义强依赖，存在兼容性风险

   • 多处写法：

     args = event.message_str.strip()

   • 这取决于框架是否把命令本体剥离后再放入 message_str。若某适配器保留完整原消息，则会把整条命令误设为 ID。
   • 影响：跨平台/跨适配器行为不一致，出现“设置成功但值错误”的隐蔽问题。
   • 建议：使用框架标准参数解析接口（若有），或手动去除子命令前缀再取参数。

6. 音频下载后未校验 MIME/文件头，可能接受非音频内容

   • 当前位置：_download_audio() 仅做状态码与大小校验。
   • 影响：当上游返回异常内容（HTML/JSON/错误页）时也会落地为 .mp3，导致后续发送失败或行为不确定。
   • 建议：至少检查 Content-Type（如 audio/*），更稳妥可加文件头校验。

---

代码评审团

人物一：Linus Torvalds（直接、硬核）
“你这个 after_message_sent 的防循环逻辑太‘靠感觉’了：今天是 Record，明天谁知道适配器给你什么组件。别赌平台实现细节，给自己加一个强标记位，逻辑上一次性封死递归入口，这才是可维护代码。”

人物二：Steve Jobs（体验导向、挑剔）
“命令参数解析这一段，用户看起来‘设置成功’，结果后台可能吃错参数——这属于最糟糕的体验：看起来没坏，实际上坏了。命令交互要可预期、可解释、可复现，参数解析必须统一且稳定。”

人物三：GLaDOS（冷幽默、系统思维）
“会话清理只在特定路径触发，真是一个‘优雅的缓慢内存实验’。你不会立刻爆炸，这正是它危险的地方。请安排周期性清理，不然未来你会得到一份非常长、非常安静、非常昂贵的 sessions 字典。”

Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。

---

🔍 审核摘要

统计信息

• 仓库文件总数: 1 个 Python 文件
• 已选择审核文件: 1 / 1
  已发送至 AI 审核的文件清单

main.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

当前仓库：Salieri-Amadeus/VocuTTS_Astrbot
剩余触发次数：1

[Salieri-Amadeus]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_vocu_tts

您好！我已经对你提交的插件代码进行了初步自动化审核，作为初步参考:

main.py

经过对 main.py 的严格审查，这份代码展现了极高的质量。它完美遵循了 AstrBot 框架的各项严苛规范（包括正确的模块导入、安全的日志使用、正确的装饰器用法，以及在特定钩子 on_after_message_sent 中正确使用 await event.send 而非 yield）。并发处理与文件流的异步写入逻辑也十分稳健。

以下是代码中发现的几个微小边界问题与性能优化点：

1. 潜在缺陷：API 响应解析存在 AttributeError 风险

在 _generate_voice 方法中：

audio_url = data.get("data", {}).get("audio")

问题：如果目标 API 在发生特定内部错误时返回了合法的 JSON，但其结构为 {"status": "error", "data": null}，此时 data.get("data", {}) 会因为键存在而返回 None（而不是默认的空字典 {}）。紧接着对 None 调用 .get("audio") 会引发 AttributeError。虽然外层有宽泛的 except Exception 兜底，但这不是最佳实践。
建议：修改为更安全的写法：audio_url = (data.get("data") or {}).get("audio")。

2. 性能与可维护性：高频 O(N) 遍历引发的无谓开销

在 _cleanup_stale_sessions 方法中：

def _cleanup_stale_sessions(self) -> None:
    now = time.time()
    stale = [
        k
        for k, v in self.sessions.items()
        if now - v.last_active > _SESSION_EXPIRE_SECONDS
    ]

问题：由于 on_after_message_sent 监听器会在每次机器人发送消息时触发并调用 _get_session，进而调用 _cleanup_stale_sessions。这意味着机器人每发送一条消息，程序都会将整个 sessions 字典进行一次全量遍历。虽然在常规场景下字典不会太大，但这种 O(N) 的高频无条件扫描设计在系统层面上是低效的。
建议：为清理操作添加一个简单的节流（Throttle）机制，例如记录上一次清理的时间戳，每隔 5 分钟或 10 分钟才执行一次全量遍历清理。

3. 逻辑正确性：音频扩展名硬编码问题

在 _download_audio 方法中：

path = os.path.join(temp_dir, f"vocutts_{uuid.uuid4()}.mp3")

问题：代码在 _AUDIO_CONTENT_TYPES 中允许了 audio/wav 和 audio/ogg 等多种格式，但在保存临时文件时强制硬编码为 .mp3 后缀。虽然许多底层播放器（或 FFmpeg）能够通过文件头特征（Magic Number）正确识别并播放音频，但文件扩展名与实际 MIME 类型不匹配可能在某些严格依赖后缀的第三方组件处理时触发异常。
建议：可以根据 HTTP 响应的 Content-Type 动态决定后缀名（例如检测到 audio/ogg 则保存为 .ogg），或者统一使用无特定格式倾向的后缀（如 .audio、.tmp）交由底层组件处理。

---

代码评审团

Linus Torvalds：（揉着眉头，语气暴躁但带着一丝赞许）
“我真不敢相信我今天不用对着屏幕大吼大叫。你的异步网络请求写得比邮件列表里 90% 的补丁都要干净，资源管理也算像样。但是，解释一下 _cleanup_stale_sessions 这个鬼东西？每次有人喘口气、发条消息，你就要把整个用户会话字典从头到尾扫一遍？CPU 周期是天上掉下来的吗？！加个该死的时间戳缓存，五分钟清理一次会死吗？除了这个愚蠢的 O(N) 循环，代码勉强算得上不算是垃圾。”

Sherlock Holmes：（双手合十，语气平静且充满优越感）
“极其严密的框架遵循，我亲爱的开发者。你避开了所有显而易见的陷阱，就像走过雷区一样优雅。然而，你的防线在面对微小的概率时暴露了破绽——data.get("data", {}).get("audio")。你天真地认为 get 的默认值能拯救你，但如果狡猾的 API 故意发给你一个明确的 null 呢？你的字典保护伞就会瞬间坍塌，留给你一个赤裸裸的 AttributeError。细节，先生/女士，魔鬼与线索都藏在这些最不起眼的 JSON 键值对里。”

GLaDOS：（毫无感情的电子音，带着隐秘的嘲讽）
“测试结果显示，你的代码存活率超出了我的预期。不过，我注意到你在白名单里大方地允许了 WAV 和 OGG 格式的音频，然后反手就把它们全部塞进了一个后缀名为 .mp3 的文件里。这真是一个迷人的谎言。我猜你觉得欺骗文件系统和音频解码器是一种很有趣的幽默？我已经把这种‘给苹果贴上橘子标签’的奇妙行为记录在案。希望那些有严格格式强迫症的解析库，在处理你的文件时也能觉得这很好笑。”

(Disclaimer: 以上评审内容由 AI 自动生成，所涉及人物形象与现实无关，不代表真实人物观点。如果给出的建议无关痛痒请忽略。)

---

🔍 审核摘要

统计信息

• 仓库文件总数: 1 个 Python 文件
• 已选择审核文件: 1 / 1
  已发送至 AI 审核的文件清单

main.py

---

此报告由AI自动生成，旨在提供初步反馈和改进建议，不能完全替代人工审核。最终决策以社区维护者的人工审核为准。目前自动审核（仓库地址）处于试验阶段，如遇问题请向维护者反馈。

当前仓库：Salieri-Amadeus/VocuTTS_Astrbot
剩余触发次数：0

[astrbot-plugin-copybara]

插件信息已同步到集合仓库。
PR: AstrBotDevs/AstrBot_Plugins_Collection#364
已自动合并 PR #364

该插件已上架。
This plugin is now published.