日志与排查

遇到 Bot 未按预期回复、工具执行报错或插件运行不稳定时，可通过面板的回合卡片、系统日志与只读健康检查工具定位原因。

在面板中排查

群聊现场与回合诊断包

打开群聊 → 现场，每条群友消息旁展示唤醒判定详情（是否唤醒、渠道和原因）。展开任一回合卡片可逐项核对：

• 标题栏的唤醒渠道、总步数、发言条数、首句等待耗时（从唤醒消息到达至第一条表达完成）及本轮输入／输出 token。
• 本轮开始前自动召回记忆的具体块列表。
• 每一模型步的想法、回复正文、工具调用参数、返回结果、失败重试次数或底层错误原文。

已结束的回合卡片底部提供两个诊断入口：

• 本轮运行日志：跳转至系统日志页并自动按该回合的 turn_id 过滤全部关联事件。
• 下载诊断包：将该回合的元数据、模型请求与响应快照、工具记录及关联 JSONL 日志打包为脱敏 ZIP 文件（自动遮盖配置密钥及 5 位以上长数字）。后台任务同样可在群聊 → 任务详情的更多菜单中点击下载诊断包（不含文件）。

需要直接查看内部 ID、数据库原始字段与完整模型协议报文时，可在系统 → 设置 → 高级中勾选开发者模式。

系统日志与运行健康

系统 → 日志包含两个页签：

• 系统日志：支持按日志级别（全部、警告以上、仅错误）、群聊、模块来源、插件名、任务编号和具体事件类型组合过滤，或全文搜索关键字；开启实时跟随后自动滚动追加新事件。底部列出按天切分的原始日志文件供直接下载。
• 运行健康：持续监测异步事件主循环的调度延迟（记录卡顿次数、最长阻塞毫秒数与调用栈，并区分电脑休眠引起的进程暂停），同时按模型用途汇总近 7 天最近一次成功与失败调用（点击失败时间可直接展开该次原始请求与错误响应）。

磁盘日志文件

结构化运行日志默认写入实例目录的 logs/lenbot.jsonl（按天滚动切分，默认保留 14 天；路径、保留天数与记录级别可在系统 → 设置 → 高级 → 日志中实时调整）。

每行日志为单条 JSON 对象，带有时间戳、级别、event 事件名及跨模块追踪关联字段：

关联字段	覆盖范围
turn_id	单轮对话从唤醒、记忆召回、模型与工具调用到消息发出的全链路记录
task_id	单个后台任务从登记、容器启动、模型请求到交付结束的全周期记录
scene	所属群聊或私聊的场景标识符
plugin	写入该日志或触发异常的插件名称

宿主在落盘前自动抹除根配置中的 API Key、访问令牌及插件声明的 secret 字段；通过面板下载日志文件或诊断包时还会额外遮盖 5 位以上连续数字。

只读实例检查（doctor）

怀疑配置文件损坏、数据库表结构不匹配或插件目录异常时，在实例目录执行：

uv run --no-sync python -m len_bot.next.maintenance.doctor

doctor 以只读模式逐项检查 lenbot.config.json、业务数据库（含表格式、SQLite quick_check 与外键关联一致性）、记忆处理库、本地记忆索引库以及已配置插件的清单与 data_version，每项输出一行 JSON（状态全部为 ok 或 disabled 时退出码为 0，任一项为 error 时退出码为 1）。由于全程只读打开数据库，LenBot 运行期间也可安全执行。

提交问题报告

在 GitHub Issues 提交缺陷报告时，建议附上：

1. 当前代码版本（源码运行执行 git rev-parse --short HEAD，部署包查看面板系统 → 设置 → 版本与更新）。
2. 出错回合或任务的诊断包（或从 logs/lenbot.jsonl 中按 turn_id／task_id 摘出的日志行）。
3. doctor 命令的 JSON 输出。