启用Debug模式需三步：一、创建debug.conf配置log_level=debug和enable_execution_trace=true并加载；二、在控制台按技能模块设置日志分类；三、注入trace_id等结构化字段实现全链路追踪。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用QoderWake开发或调试数字员工任务时发现行为异常、逻辑跳转错误或变量值不符合预期，但标准日志未输出关键中间状态，则很可能是Debug模式未正确启用或配置粒度不足。以下是快速定位代码Bug所需的Debug模式配置操作路径：
一、启用QoderWake核心模块Debug日志通道
QoderWake默认仅输出INFO级别日志，无法暴露技能模块执行链路、状态机跃迁、上下文注入等关键调试信息。启用核心Debug通道可捕获Agent内部决策断点与变量快照，是定位代码级Bug的首要前提。
1、在QoderWake安装根目录下创建名为debug.conf的配置文件。
2、向该文件写入以下两行内容（确保无多余空格或BOM头）：
log_level = debug
enable_execution_trace = true
3、启动QoderWake时显式加载该配置：
qoderwake --config debug.conf --mode=standalone
4、确认启动日志中出现[DEBUG] Loaded configuration from debug.conf及Execution trace enabled字样。
二、绑定技能模块专属Debug日志分类
避免所有Debug日志混杂输出，需按技能模块（如skill_code_analyzer、skill_webhook_router）划分日志类别，使问题可精准收敛至具体技能包，大幅降低干扰噪声。
1、在QoderWake管理控制台“高级设置”中，进入【Logging Categories】页面。
2、点击“添加分类”，输入名称code_analyzer，匹配规则设为skill_code_analyzer.*，日志级别选debug。
3、对目标技能模块重复上述操作，例如为路由模块配置webhook_router分类，匹配规则skill_webhook_router.*。
4、重启QoderWake后，执行对应任务，日志将自动按分类隔离输出，可通过grep "code_analyzer" /var/log/qoderwake/runtime.log单独提取分析。
三、注入结构化上下文字段以支持跨模块追踪
单一模块日志缺乏请求唯一标识与多轮交互关联性，导致Bug复现路径断裂。通过注入trace_id、task_id、input_hash等结构化字段，可实现从用户输入到技能执行再到结果返回的全链路日志串联。
1、在任务触发入口处生成唯一trace_id：
trace_id = uuid.NewString() + "_" + strconv.FormatInt(time.Now().UnixNano(), 36)
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、在每个关键Debug语句前统一添加前缀：qCDebug(code_analyzer)
3、启用JSON格式日志输出，在环境变量中设置：
QODER_LOG_FORMAT=json
4、使用jq -r '. | select(.trace == "xxx")' /var/log/qoderwake/runtime.log提取完整调用链日志。
四、动态启用函数级变量快照与堆栈捕获
部分Bug由局部变量误赋值、闭包引用失效或goroutine上下文丢失引发，仅靠语句级日志无法还原现场。启用函数级变量快照可强制记录指定函数入口/出口时的参数、返回值与局部变量值。
1、在debug.conf中追加配置项：
enable_function_snapshot = true
snapshot_functions = ["AnalyzeCode", "RouteWebhook", "ValidateInput"]
2、确保目标函数已添加// @qoder:debug-snapshot注释标记（位于函数声明上方）。
3、重启QoderWake并触发对应任务，日志中将出现形如[SNAPSHOT] AnalyzeCode: args={...}, locals={...}, returns={...}的完整快照行。
4、比对快照中locals.input_tokens与returns.ast_root字段值，验证是否发生意外截断或nil传播。
五、过滤导出可疑逻辑段日志用于离线深度分析
当Bug复现概率低或需多人协同分析时，原始日志体积庞大且包含大量无关信息。通过正则过滤与时间窗口截取，可导出高度聚焦的可疑逻辑段日志，便于导入专用分析工具进行模式挖掘。
1、定位疑似Bug发生时间段，例如从2026-05-23T14:22:00至2026-05-23T14:22:30。
2、执行过滤导出命令：
sed -n '/2026-05-23T14:22:00/,/2026-05-23T14:22:30/p' /var/log/qoderwake/runtime.log | grep -E "(ERROR|FATAL|unhandled_state|panic)" > bug_segment.log
3、对导出文件进一步筛选含特定技能标识的日志：grep "code_analyzer" bug_segment.log > ca_bug.log
4、将ca_bug.log上传至Qoder IDE内置Log Analyzer插件，自动标出变量突变点与状态跃迁异常位置。
