[Plugin] astrbot_plugin_ts3_tracker

[moeneri]

插件信息

{
  "name": "astrbot_plugin_ts3_tracker",
  "display_name": "teamspeak 3 服务器信息和在线人数信息查询监控插件",
  "desc": "AstrBot TS3 查询插件，QQ 发送“上号”即可返回服务器在线人数和频道信息。",
  "author": "moeneri",
  "repo": "https://github.com/moeneri/astrbot_plugin_ts3_tracker",
  "tags": [
    "TS3",
    "teamspeak",
    "监控",
    "服务器"
  ],
  "social_link": "https://github.com/moeneri"
}

插件检查清单

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

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_ts3_tracker

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

init.py

该文件仅包含模块的文档字符串（Docstring），未发现任何代码质量、安全或逻辑上的问题，符合标准规范。

---

main.py

以下是对 main.py 的代码审查报告：

1. 功能实现与逻辑正确性

• 严重的 N+1 查询性能瓶颈：在 fetch_status 方法中，遍历 client_records 获取每个用户的连接时间时，代码在循环中依次执行了 await self._execute(..., f"clientinfo clid={client_id}", ...)。
  • 问题：如果服务器有 50 个在线用户，这将会产生 50 次阻塞式的网络往返请求（Round-Trip），极大拖慢查询速度并对 TS3 ServerQuery 造成不必要的并发压力。
  • 优化方案：TS3 的 clientlist 命令支持附加参数。直接在获取列表时使用 clientlist -uid -away -ip -times，返回的数据中就会直接包含 connection_connected_time 字段，从而完全消除这个 for 循环中的二次查询需求。
• 潜在的竞态条件与崩溃风险（未处理异常）：同样在上述的 clientinfo 循环中，如果某个用户在机器人发送 clientlist 和执行对应的 clientinfo 之间的一瞬间断开了连接，self._execute 将会抛出 Ts3QueryError（因为 clid 已经失效）。由于循环内部没有捕获异常，这将导致整个 fetch_status 直接崩溃，无法返回其他正常的服务器状态。

2. 代码质量与编码规范

• 事件监听器冗余：插件中同时存在 @filter.command("上号") 和 @filter.event_message_type(...) 两个方法来实现相同的触发逻辑。
  • 问题：query_server_status_plain 方法为了匹配“上号”，拦截了群内/私聊的所有消息并进行字符串比对。这不仅是多此一举，还会消耗不必要的计算资源。AstrBot 的 @filter.command 系统本身就已经完美处理了前缀匹配和指令路由。
  • 建议：直接删除 query_server_status_plain 方法及其相关的 PLAIN_TEXT_TRIGGERS 常量，只保留 @filter.command("上号", alias={"ts", "tsinfo"}) 即可。

3. 可维护性与可读性

• 过度设计的消息发送逻辑：代码中实现了 _send_text_response 方法，试图通过 self.context.send_message(target, ...) 来主动推送消息，如果失败再退回到常规的 yield event.plain_result(message)。
  • 问题：这打破了 AstrBot 插件标准的响应生命周期。yield event.plain_result() 是框架官方推荐且最安全的回复方式，它会自动处理上下文、中间件和多平台的差异。强制绕过它直接调用底层 API 增加了不必要的代码复杂度。
  • 建议：移除 _send_text_response 及其相关调用逻辑，在指令方法中直接统一使用 yield event.plain_result(message) 进行回复。

---

代码评审团

Linus Torvalds：（满脸不悦地看着屏幕）

“你在开什么玩笑？你写了一个 N+1 查询的循环来获取用户的连接时间？如果有 100 个人在线，你的机器人就会像个傻子一样在单线程里排队发 100 次网络请求！你难道连 TS3 的官方文档都没扫一眼吗？只要在 clientlist 后面加上 -times 参数，服务器就会一次性把所有数据扔给你！还有那个拦截所有消息的 event_message_type 监听器，这简直是对框架事件路由系统的侮辱。把它删掉，立刻！”

Steve Jobs：（双手合十，语气平静但带有压迫感）

“伟大的产品来源于做减法，而不是盲目地堆砌逻辑。你写了一个庞大的 _send_text_response 函数，试图在底层手动干预消息的发送路径，失败了再去调用 yield。这不够优雅，也不自然。AstrBot 已经为你铺好了 yield event.plain_result() 这条最简洁的高速公路，你却非要在旁边自己挖一条泥巴路。丢弃那些繁琐的代码吧，让代码回到它本该有的极简形态。”

Bender（《飞出个未来》中的机器人）：（抽着雪茄，发出金属碰撞的嘲笑声）

“哈哈哈！你们这些碳基生物写出来的代码就和你们的肉体一样脆弱！如果有个倒霉蛋在你的机器人执行 clientlist 和 clientinfo 之间拔掉了网线，你猜怎么着？你的整个查询任务就会因为一个未捕获的 Ts3QueryError 直接当机！嘭！全完了！连个 try-except 都不舍得写，你难道指望我这个高贵的机器人去帮你擦屁股吗？赶紧把那个愚蠢的循环修好，或者听那个暴躁的 Linux 老头的话，用 -times 参数一劳永逸！”

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

---

🔍 审核摘要

统计信息

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

main.py
__init__.py

---

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

当前仓库：moeneri/astrbot_plugin_ts3_tracker
剩余触发次数：4

[moeneri]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_ts3_tracker

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

main.py

1. 功能逻辑问题：按“频道名”分组会错误合并同名频道

   • 位置：_group_users_by_channel、_format_server_status
   • 问题：当前以 channel_name 作为分组键，而 TS3 中不同父频道下可能存在同名子频道。这会把本应分开的频道用户合并，在线信息失真。
   • 影响：人数统计和用户归属可能错误。
   • 建议：分组应基于唯一标识（如 cid），展示时再附带频道名。

2. 响应解析健壮性不足：默认最后一行一定是 error ...

   • 位置：_parse_response
   • 问题：lines[-1] 被直接当作 error 行解析，且 error_info["id"] 直接 int()。若协议响应异常、混入非标准行或服务端返回格式不完整，会触发 ValueError，落入“未预期错误”。
   • 影响：错误信息不稳定，用户侧得到泛化报错，排障困难。
   • 建议：先校验 error_line.startswith("error ")，并对 id 的转换做异常保护，统一抛 Ts3QueryError。

3. 端口字段转换存在未兜底异常路径

   • 位置：fetch_status 中 int(serverinfo.get("virtualserver_port", self.server_port))
   • 问题：如果返回值异常（非数字字符串），会抛 ValueError，被外层作为“未预期错误”处理。
   • 影响：边界条件下可用性下降。
   • 建议：使用安全转换（try/except），失败时回退 self.server_port。

4. 握手读取策略可维护性较弱，异常信号被静默吞掉

   • 位置：_consume_welcome
   • 问题：固定读取 3 行且超时直接 return，没有日志或显式状态。若欢迎语格式变化或网络抖动，可能把后续协议行留给命令解析阶段，导致“看似随机”的解析失败。
   • 影响：故障定位困难。
   • 建议：至少在超时/异常欢迎语场景记录 debug/warning，并尽量读取到明确结束条件。

5. 安全实践风险：ServerQuery 凭据明文传输

   • 位置：login ... username password（TCP 10011）
   • 问题：当前实现为明文 ServerQuery 连接，账号密码在不可信网络中可能被嗅探。
   • 影响：凭据泄露风险。
   • 建议：部署侧应限制为内网/本机访问，或通过 SSH/VPN 隧道保护链路；插件文档中应明确安全前提。

---

init.py

未发现需要报告的问题。

---

代码评审团

人物一：Linus Torvalds（直球派）
“你这异步 I/O 基本功是到位的，但拿频道名当主键这事很糟糕。名字是给人看的，不是给机器当唯一键的。把 cid 用起来，别让统计结果‘看起来对，实际上错’。”

人物二：Steve Jobs（产品体验派）
“用户只关心‘谁在什么频道’。如果同名频道被合并，产品可信度就掉了。还有错误提示现在有点‘技术内向’，建议把协议异常统一成更可理解的失败原因，同时保留日志细节给开发者。”

人物三：Geralt of Rivia（猎魔人式风险嗅觉）
“真正的怪物是明文链路。ServerQuery 登录凭据在野外网络里裸奔，不加防护迟早出事。你可以不改协议，但至少要在文档和部署建议里把‘仅内网/隧道’写死，别给自己留诅咒。”

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

---

🔍 审核摘要

统计信息

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

main.py
__init__.py

---

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

当前仓库：moeneri/astrbot_plugin_ts3_tracker
剩余触发次数：2

[moeneri]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_ts3_tracker

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

main.py

在针对 main.py 的严格审查中，代码整体结构清晰，较好地遵循了异步编程规范以及 astrbot.api 的插件开发标准。未发现同步阻塞操作，且资源的开启与释放（如 writer.close() 和 wait_closed()）处理得很规范。但仍存在以下几个潜在问题与改进空间：

1. 功能实现与健壮性问题

• 协议握手解析硬编码 (_consume_welcome)：
  在 _consume_welcome 方法中，使用了 for _ in range(3): 来消费欢迎信息。在实际网络环境中，TS3 服务器可能因为版本差异或加载了自定义插件，导致返回的 MOTD（每日信息）行数不固定。如果超过 3 行才出现 TeamSpeak 3 ServerQuery interface，该方法会提前退出，导致后续真正的登录命令读取到残留的欢迎信息，从而触发 error id=-1 的解析失败。
  建议：改用带超时的 while True 循环，直到读取到目标接口标识为止，而不是限制循环次数。

• 缺乏全局超时控制：
  在 fetch_status 和 _read_response 交互中，每次 reader.readline() 的调用都赋予了独立的 timeout=self.timeout (默认 10 秒)。在最坏的情况下（网络存在严重的丢包或服务端响应极慢），完成一整套请求（login, use, serverinfo, channellist, clientlist, quit 等）可能会消耗极长的时间（数十秒），这会导致任务被不合理地长时间挂起。
  建议：在最外层的 fetch_status 中应用全局的超时上下文（如 asyncio.timeout 或 asyncio.wait_for 包装整个异步调用链），确保无论进行到哪一步，总耗时不超过预期限制。

2. 安全漏洞与最佳实践

• 明文传输认证凭据：
  TS3 ServerQuery 协议在未特殊配置的情况下原生使用 TCP 明文传输。代码中的 login {username} {password} 毫无加密地通过网络发送。当 host 为公网 IP 时，极易遭受中间人攻击或流量嗅探导致管理员密码泄露。
  建议：虽然这是协议本身的设计限制，但从最佳实践角度，建议在文档或代码注释中明确警告用户此风险，并建议用户将服务部署在内网、同主机（localhost）或通过 SSH 隧道/VPN 进行访问，以保障密码安全。

---

__init__.py

该文件为纯粹的包声明，代码符合 PEP 8 规范，未发现任何问题。

---

代码评审团

Linus Torvalds：（对网络底层协议的容忍度极低，直言不讳）
“你把网络协议想得太美好了，那可是真实世界！在 _consume_welcome 里居然用 for _ in range(3):？你以为服务器是按着你的剧本乖乖念台词的吗？万一它打个喷嚏多返回几行，你的整个协议解析就全乱套了！改掉这个愚蠢的硬编码，用一个条件循环直到找到那个该死的接口标识！不过，你能记得在 finally 里用 wait_closed() 优雅地处理连接关闭，算你还没有完全失去理智。”

爱德华·斯诺登：（极度关注数据安全与隐私，带着担忧的语气）
“老兄，你在公网里裸奔吗？login {username} {password} 居然就这么明文飞在 TCP 连接上？任何一个在路由器上抓包的中间人都能像看报纸一样看你的 ServerQuery 密码！我懂，这是那个老掉牙的 TS3 协议的锅，但作为开发者，你至少应该在代码层面抛出警告，或者提醒用户：千万别把暴露在公网的 TS3 这样直连，建议他们走 SSH 隧道或者内网代理。不要主动把服务器钥匙交到窃听者手里！”

托尼·斯塔克：（钢铁侠，追求极致的工程效率与完美架构）
“看一眼你的异步代码，结构确实挺干净，像我早期的马克战甲。不过，你给每个网络读取动作都独立设了 timeout=10.0，你算过这笔时间账吗？如果你要发送6个命令，最糟糕的网络情况下你的机器人得卡上整整 1 分钟才会抛出异常！这就好比我的战甲每一个部件都要等 10 秒才启动，等全套组装好我都被打成筛子了。为什么不直接在最外层包装一个统一的总超时防护罩呢？我们要的是丝滑的响应，而不是给用户看一个无限转圈的沙漏。”

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

---

🔍 审核摘要

统计信息

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

main.py
__init__.py

---

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

当前仓库：moeneri/astrbot_plugin_ts3_tracker
剩余触发次数：1

[moeneri]

@astrpluginreviewer review

[astrpluginreviewer]

🤖 AI代码审核报告 for astrbot_plugin_ts3_tracker

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

__init__.py

该文件仅包含包的文档字符串，代码清晰简洁，未发现任何违反编码规范、安全漏洞或逻辑缺陷的问题。

---

main.py

潜在缺陷或问题与功能实现逻辑

1. Python 3.10 兼容性问题引发的崩溃风险（严重）
   在 Ts3QueryClient.fetch_status 方法中，使用了 asyncio.timeout 上下文管理器：

   async with asyncio.timeout(self.timeout):
       return await self._fetch_status_inner()

   问题说明：根据审查规则，当前运行环境严格限定为 Python 3.10。然而，asyncio.timeout 是在 Python 3.11 中才被引入的新特性。在 Python 3.10 环境下执行该代码会直接引发 AttributeError 导致程序崩溃。
   修复建议：请使用 Python 3.10 支持的 asyncio.wait_for 替代：

   return await asyncio.wait_for(self._fetch_status_inner(), timeout=self.timeout)

   同时，需将外层的 except TimeoutError: 捕获改为 except asyncio.TimeoutError:，因为 wait_for 抛出的是 asyncio.TimeoutError。

2. 异常捕获导致的逻辑中断与超时失效
   在 Ts3QueryClient._consume_welcome 方法中，存在对 asyncio.TimeoutError 的静默吞咽：

   try:
       raw_line = await reader.readline()
   except asyncio.TimeoutError:
       logger.warning("TS3 ServerQuery welcome banner timed out")
       return  # 这里直接 return 导致异常没有向上传播

   问题说明：一旦外部的 asyncio.wait_for 触发超时，它会向内部分发 asyncio.TimeoutError 异常以取消任务。然而，该异常在此处被意外捕获并拦截，函数打印一条日志后正常 return，让程序误以为连接欢迎语已成功读取完毕。紧接着，程序会继续尝试往下执行 login 和其他指令请求，这会引发流状态混乱并产生不可预期的错误。
   修复建议：移除这里的 try...except asyncio.TimeoutError 逻辑。如果有针对单行读取超时的独立设计需求，应当设置一个更短时间的 wait_for 包裹读取操作。但在此场景中，应该允许由外部总控的超时异常直接向上传递，切断执行链。

框架适应性与代码质量

• 日志记录与插件规范：日志记录器从 astrbot.api 导入，插件主类继承了 Star，所有的装饰器及导出项完全符合 AstrBot 的插件开发标准。
• 并发与网络 I/O：通过 asyncio.open_connection、StreamReader 和 StreamWriter 完成了规范的异步 Socket 操作，未使用任何阻塞式的网络操作，且在 finally 块中妥善处理了 writer 资源的关闭与回收。
• 协议处理：TS3 协议层面的特殊字符转义和字符串反序列化操作（ESCAPE_MAP 与 _parse_record）实现得非常清晰且健壮。

---

代码评审团

Linus Torvalds：
“你是在和我开玩笑吗？规则里白纸黑字写着『严格限定为 Python 3.10』，你却在代码里塞进了一个 Python 3.11 才有的 asyncio.timeout！这就是为什么我不喜欢盲目追新而不看环境基线。如果你不把那个见鬼的 timeout 换成 asyncio.wait_for，你的代码在用户的机器上连跑都跑不起来，当场就会甩你一脸 AttributeError！除此之外，你的资源清理流程写得倒是不算太蠢，finally 里关闭 writer 算是救了你一命。”

Gordon Ramsay：
“看看你的 _consume_welcome 方法！你在干什么？！你把外层扔下来的超时异常生吞了！还当作什么都没发生一样直接 return 出来！你这是在厨房里把变质的肉藏在盘底端给客人！外层的超时控制器在拼命按响警报，你不仅把它按灭了，还让代码傻乎乎地继续往前去执行 login！马上把那个 try...except 给我删掉，让异常自然地滚出去！”

强尼·银手（Johnny Silverhand）：
“Wake up, samurai. 我们这都什么年代了，还在用 ServerQuery 这种古板的协议通过明文传密码。不过这是 TS3 那帮公司定下的规矩，我没法喷你。从代码结构来看，你写得很干净，硬编码的正则替换和类继承算你有种，也没有触犯 AstrBot 这座城市的任何底线规矩。把那两个版本兼容和吞异常的致命 bug 修复掉，这活儿干得还算漂亮。”

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

---

🔍 审核摘要

统计信息

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

main.py
__init__.py

---

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

当前仓库：moeneri/astrbot_plugin_ts3_tracker
剩余触发次数：0

[astrbot-plugin-copybara]

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

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