NcatBot 文档

外观

实战案例与调试

约 597 字大约 2 分钟

2026-03-19

四大实战案例概览与调试排查技巧。完整源码请访问 examples/ 目录。

实战案例

案例 1：群管理机器人

完整代码：examples/qq/06_group_manager/main.py

整合：RBAC 权限 + 通知事件 + 群管理 API + 配置管理

关键模式：

  • 封装 _is_admin() 权限检查，所有管理命令共用
  • 欢迎语模板通过 ConfigMixin 持久化，支持运行时修改
  • on_group_increase() 自动处理新成员入群

案例 2：定时报告与统计

完整代码：examples/qq/08_scheduled_reporter/main.py

整合：定时任务 + 数据持久化 + 高优先级消息统计 + 合并转发

关键模式：

  • 高优先级 Handler（priority=200）统计所有消息，不影响其他命令
  • 任务回调方法与任务同名（daily_report）
  • ForwardConstructor 将长报告打包为合并转发消息

案例 3：外部 API 集成

完整代码：examples/common/07_external_api/main.py

整合：异步 HTTP 请求 + 配置管理 + 错误处理 + 优雅降级

关键模式：

  • API 地址通过 ConfigMixin 管理，运行时可修改
  • 多层异常捕获：HTTP 状态码 → 网络异常 → 未知异常
  • pip 依赖声明在 manifest.toml 的 [pip_dependencies]

案例 4：全功能群助手

完整代码：examples/qq/09_full_featured_bot/main.py

覆盖所有框架特性的综合案例：

子系统使用的 Mixin / 特性
签到与积分DataMixin + MessageArray
关键词自动回复DataMixin + 高优先级 Handler
管理命令RBACMixin + api.manage
定时早安TimeTaskMixin
新成员欢迎on_group_increase() + ConfigMixin

调试与排查

日志系统

from ncatbot.utils import get_log
LOG = get_log("MyPlugin")
LOG.info("消息: %s", text)
LOG.debug("调试信息")  # 仅在 debug=True 时输出

常见问题

问题原因解决方案
插件没有加载manifest.toml 缺必填字段检查 name / version / main
命令不响应Handler 未注册确认 @registrar.on_*() 在类方法上
配置/数据丢失异常退出手动调用 _save_data()
热重载不生效__pycache__ 缓存手动删除 __pycache__
循环依赖A ↔ B 互相依赖提取公共逻辑到第三个插件
权限检查总是 FalseRBAC 服务未加载检查 self.rbac is not None
定时任务不执行回调方法名不匹配任务名须与方法名完全一致

下一步

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot