AI 运行诊断

Bot 管理员可以直接询问：“为什么我上一条消息没有回复？请查询请求链路。”AI 会查询当前 Bot、当前聊天中的诊断记录，并根据实际记录说明请求停在哪一步。

这项能力需要 Bot 和 AI 仍能处理新的请求。如果 Bot 进程已停止、模型持续不可用或 Telegram 无法投递消息，请通过管理面板和故障排查指南检查服务。

权限与查询范围

只有当前 Bot 配置中的管理员可以使用诊断工具。普通成员、仅有 Telegram 群管理员身份的成员，以及委派群组管理员不会自动获得权限。身份来自实际发送消息的 Telegram 用户，工具参数不能指定另一个用户、Bot 或聊天。

查询始终限定当前聊天。需要检查另一个群时，管理员应进入目标群发起查询。群内的诊断回复仍会被该群成员看到，请根据交流场景决定是否展示结果。

所有查询都记录操作者、查询类型、范围、时间、结果数量和结果状态，包括拒绝、限流和未找到记录的查询。审计写入失败时不返回诊断数据。

五个只读工具

这些工具不会修改配置、重启服务或执行 shell。查询有频率、时间窗口、分页和响应大小限制；结果标记截断时，缩短时间范围或继续分页。

运行状态与有效配置查询无需参数。链路、日志与近期错误查询可使用 traceId、messageId、toolCallId，用 windowMs 缩小时间窗口。定位 ID 应来自实际记录；不知道时省略或传 null，不要猜测。空白的 trace ID 和 tool call ID 也视为未指定。每页默认 10 条，最多 50 条，offset 最多 500；get_request_trace 不传定位参数时查上一条自己的消息，previous: false 查当前诊断请求。单次响应最多约 24 KB。同一管理员在同一聊天每分钟最多查询 10 次，整个 Bot 每分钟最多 60 次。

如何判断请求停在哪一步

请求从入站开始记录，之后按实际执行路径记录权限与触发决策、持久化、上下文构建、排队、模型、工具、回复生成和 Telegram 投递。未执行的阶段不会被补成成功。

• 排队中的请求尚未获得执行机会；它与模型调用超时是不同状态。
• 工具失败说明某次工具执行出错，之后模型仍可能恢复并完成回复。
• 回复生成完成不表示已发送成功，应继续核对 Telegram 投递阶段。
• 用户取消、未满足接话条件、用量限制和没有可发送内容都有各自的结果。
• 合并处理的消息应结合关联请求查看，不能把单条消息缺少独立模型调用解释为丢失。

图片请求的工具事件可关联 generationId、providerOperationId 和 deliveryState。异步生成和投递的持久记录属于同一图片任务；即使本轮请求链路已经过期，仍可通过 /image status <任务 ID> 核对生成、取消、目标 chat/topic 和 Telegram 回执。Skill 或预设查询成功不能证明提交过图片任务。

组件显示 unknown 或未观测时，表示没有足够的检查证据。功能已启用、已配置凭据和远端服务健康是不同信息；没有安装的组件也不会显示为健康。

observationCapabilities 明确列出未接入的能力：模型和 Telegram 的主动探针为 not_implemented / active_probe_not_configured，GitHub 后台任务读取为 not_implemented / task_reader_not_connected。这些标记表示当前诊断能力的边界，不表示依赖故障；lastModelEvent 和 lastDeliveryEvent 仍可用于查看最近一次实际调用或投递的观测，不能据此宣称当前服务健康。

工具参数校验失败会记录为 tool_invalid_input，即使执行函数尚未运行也可查询。资产保存可区分 tool_not_found、tool_forbidden 和 tool_storage_error；具体校验或脱敏存储原因见面板的 AI tool input invalid / AI tool result 日志。存储结果未知时先检索资产，不能把工具失败直接当作“没有写入”。

运行状态中的 version 是部署的完整 commit SHA，无法读取时为 unknown。模型和 Telegram 提供最近一次当前聊天的观测事件，不会为自查额外调用付费模型或发送测试消息。图片状态统计最近一小时更新的任务和仍未结束的任务；RSS 提供活跃订阅集合数及最近摘要时间；配额只返回当前聊天及当前用户在该聊天内的额度。GitHub 后台任务、主机资源指标和跨重启历史暂未接入这些工具。

字段与隐私

诊断记录仅保留固定阶段、状态、错误类别、时间、耗时和有界的关联标识等白名单字段。配置输出只投影诊断所需字段。消息正文、完整系统提示词、工具参数和返回正文、URL、文件路径、堆栈、Cookie、Authorization、API Key、Bot Token、数据库连接串和私钥不会通过这些工具返回。

诊断工具读取专用的结构化记录。面板中的管理员运行日志仍可能包含有界的消息和工具内容，分享前需要遵循隐私与记忆指南进行检查。

保留范围和排障示例

请求链路保存在当前 Bot 运行实例的有界内存中。Bot 重启、进程重启、保留时间到期或容量淘汰后，旧链路可能不可查询；响应会提供启动时间、保留窗口及截断信息。未找到记录只能说明当前记录中不存在，不能证明当时没有错误。

每个 Bot 最多保留 500 条链路，每条最多 64 个事件，并保留最新事件。默认最近 24 小时没有新事件的链路会过期；可用非秘密环境变量 RUNTIME_DIAGNOSTIC_RETENTION_MS 配置保留毫秒数，允许 1 到 86400000（最多 24 小时），无效值使用默认 86400000。更改后重启服务生效；容量限制仍然适用，繁忙 Bot 的旧链路可能更早被淘汰。已有环境中显式设置的 3600000 仍表示一小时，需要修改该值或移除覆盖才能采用新默认值。响应的 historyScope=current_process 明确表示记录只覆盖当前进程。空的日志、错误列表或 not_found 不能证明历史无错误、图片没有提交或图片没有发送。

同一轮对话中，重复加载同一个未启用的 Skill，或重复读取同一份不存在的 Skill 参考资料，第三次失败会返回 skill_retry_limit。下一步结束工具调用并生成文字说明，避免继续消耗整轮预算重试。面板的 AI tool result 日志保留失败原因、次数和可用资料列表；新一轮对话重新计数。

查询时间参数最大允许 24 小时，但不能延长实际保留期。审计日志独立写入数据库，遵循已有日志保留策略。

上线前或重启前的链路不存在时，链路查询返回 not_found，日志和错误查询可能为空；运行状态与有效配置仍可查询。invalid_request 表示参数不符合要求，不能据此推断消息身份或链路 ID 没有注入。Diagnostic audit unavailable 表示本次审计未能在期限内完成，或审计等待容量已满，不一定是数据库未启用。正常的五工具并发查询会短暂排队写入审计；写入失败时仍不会返回诊断数据。

可直接这样询问：

请查询我上一条消息的执行链路，说明最终停在哪一步。
请查看当前聊天的有效模型、超时和已启用工具，不要输出提示词。
请汇总最近一小时的错误，区分模型、工具和 Telegram 投递失败。
请检查当前聊天是否在排队，并说明哪些组件没有健康检查证据。

AI 的结论应引用查询得到的阶段、时间和错误类别。诊断记录不完整时，应说明缺口，避免把推测写成已确认原因。