Debug 日志 | Qnbot Docs Center

先读：安装与环境要求 · 读完你能：开对模块的 Debug 日志，并在报告问题时交出可复查的日志

现场报告问题时，先按这一章打开 Debug 日志。日志是事后唯一能复查的数据。按症状定位问题见常见问题；设备状态与错误处理见诊断与错误。

打开 Debug 日志

from qnbot_sdk import DebugConfig, DebugDetail, DebugModule, Sdk
from qnbot_sdk.glove import GloveConfig

debug = DebugConfig(
    modules=tuple(DebugModule),
    detail=DebugDetail.SUMMARY,
    sample_rate=10,
)

sdk = Sdk(devices=(GloveConfig(),), debug=debug)
glove = sdk.glove()
try:
    glove.start()
    glove.run_forever()
finally:
    glove.close()

modules：可选择 transport、device、capture、calibration、retargeting 和 output。
detail：SUMMARY 或 FULL。
sample_rate：可选的正整数采样率。

Debug 日志保存在应用数据目录的 <QNBOT_HOME>/logs 下，每次诊断运行使用独立的 session 目录。

省略 DebugConfig 或将 debug 设为 None 时不会创建 Debug 日志。FULL 会记录更多运行数据并增加日志量；日常诊断建议使用 SUMMARY，需要详细排查时再使用 FULL，并按需要设置 sample_rate。

创建 Sdk 时通过 debug 传入配置，之后按普通流程运行即可；不需要单独启动 Debug 模块。

复现问题后，把这次运行对应的 session 目录连同终端输出一起提供给我们的技术支持；日志里已经包含设备与运行状态，便于对照问题。

模块与详细程度

DebugConfig 只有三个字段：modules、detail 和 sample_rate。排查某一类问题时只列相关模块即可；示例代码里传入全部六个模块。

`DebugModule`

值	类型	覆盖的子系统
`TRANSPORT`	`DebugModule`	串口传输（字符串形式 `transport`）
`DEVICE`	`DebugModule`	设备发现、身份与连接（`device`）
`CAPTURE`	`DebugModule`	采集流程（`capture`）
`CALIBRATION`	`DebugModule`	标定流程（`calibration`）
`RETARGETING`	`DebugModule`	retargeting 计算（`retargeting`）
`OUTPUT`	`DebugModule`	灵巧手输出通道（`output`）

modules 的类型是 Sequence[DebugModule | str]：既接受 DebugModule 枚举成员，也接受它的字符串值（例如 "device"）。传入其它值会抛出 ValueError，并在消息里列出支持的取值；默认是空序列。

`DebugDetail`

值	类型	含义
`SUMMARY`	`DebugDetail`	关键事件与结果；默认值，日志量小
`FULL`	`DebugDetail`	在 `SUMMARY` 基础上记录更多运行数据，日志量明显更大

detail 的类型是 DebugDetail，只接受枚举成员：DebugDetail.FULL 可以，字符串 "full" 会抛出 TypeError。

`sample_rate`

类型 int | None，默认 None（普通事件不采样）。设置后必须是 1 到 4294967295 之间的整数（bool 不接受），用于在 FULL 下按该频率抽样、控制日志量。

完整字段与约束见配置字段速查的 DebugConfig。