WorkBuddy 会话证据与五步排查法：它到底做了什么、为什么配置没生效

WorkBuddy 是腾讯出品的全场景 AI 办公工作台。本专题 46 篇课程，覆盖"认识工具—设计任务—验收结果—扩展能力—自动化协作—长期维护—实战案例—进阶方法—岗位行业—底层机制"完整路径，包含 100+ 真实使用场景。

一句话结论

「它说做了但文件没变」「改了配置不生效」这类问题，答案在 ~/.workbuddy 的四类证据文件里；按五步排查法走，十分钟内定位绝大多数异常。

本章概述

这一课讲两件事：WorkBuddy 在本地留下的四类会话证据怎么读，以及一套五步排查法怎么用。学完你不再需要「重启试试」「重装试试」，而是像工程师一样定位问题。

四类证据：AI 工作的行车记录仪

证据类型位置记录什么什么时候看
会话流水~/.workbuddy/sessions/<会话ID>.json完整对话消息、文件产出找回历史任务内容
执行轨迹~/.workbuddy/traces/<会话ID>/每次工具调用的输入输出核对它实际执行了什么
审计日志~/.workbuddy/audit-log/YYYY-MM-DD.jsonl关键操作按天记录时间线还原
文件历史~/.workbuddy/file-history/改动前的文件快照恢复被改坏的文件

实战用法一：找回历史任务。 你三个月前让它做过一版方案，聊天记录早被清了——去 sessions/ 目录按时间排序找 JSON 文件，打开搜索关键词，完整对话和产物路径都在里面。

实战用法二：核对执行。 它说「已修复 15 个文件」但你不确定真假——打开该会话的 traces/ 目录，每次文件写入操作都有记录，改了哪个文件、写入什么内容、成功还是失败，一目了然。

实战用法三：文件后悔药。 它把你的配置文件改坏了——file-history/ 里存着改动前的快照，找到对应版本恢复即可，不用求助于时光机。

五步排查法：配置为什么不生效

这是蓝皮书总结的通用排查路径，专门对付「我明明改了，为什么没生效」：

第一步：层级——改对地方了吗？

同一个配置往往有多层：用户级 vs 项目级 vs 会话级。常见错误是在项目级找用户级的问题。先确认你改的层级和生效的层级是同一个：

你想改的应该改哪里
全局人格~/.workbuddy/SOUL.md 等身份文件
某项目的规则<项目>/.workbuddy/ 下的文件（如 WORKBUDDY.md、memory/）
单次会话行为对话里直接说，不落盘

第二步：优先级——被覆盖了吗？

多层同时存在时，高优先级覆盖低优先级。项目级规则压过用户级默认，最近指令压过早期指令。你的配置没生效，可能是被更高层覆盖了——检查所有层级里有没有冲突条目。

第三步：缓存——旧上下文还活着吗？

已开启的会话不会重新读配置文件。改完配置必须开新会话 测试。「改了没生效」的经典误判：在旧会话里测试。同理，专家会话缓存了专家人设，退回普通会话才能验证你的身份文件改动。

第四步：同步——多端一致吗？

如果你在多台设备用 WorkBuddy（或走云同步），配置可能有同步延迟。A 设备改的文件没同步到 B 设备，B 上自然不生效。确认方式：直接看 B 设备上的文件内容是不是新的。

第五步：版本——更新改了默认值吗？

WorkBuddy 更新很快，新版本可能调整默认行为或字段格式。升级后配置突然失效，先查更新日志确认相关机制有没有变，再对照本机实际文件结构核对（书里的路径字段也有版本边界，以本机实际为准）。

排查案例走一遍

症状 ：你在 USER.md 里写了「输出用表格」，但它一直输出大段文字。

  1. 层级：确认改的是 ~/.workbuddy/USER.md（不是项目里的同名文件）——对
  2. 优先级：项目 WORKBUDDY.md 里有没有「输出用完整段落」的冲突规则——假设没有
  3. 缓存：你是不是在旧会话里测试的——开新会话再试，生效了，结案

八成的问题停在第三步。这就是为什么「重启」看起来万能——重启即新会话，绕过了缓存。但知道原理后你不用重启，开新会话就行。

三个高阶实用模式

  1. 双设备对照 ：怀疑某行为是配置导致，在另一台干净设备上复现——不复现就是本机配置问题，复现就是产品机制
  2. 最小复现 ：复杂任务出问题，把可疑部分拆出来单独跑一个小任务，缩小范围
  3. 证据先行 ：报 bug 或求助于人时，直接附上 traces/ 里的相关记录，比描述「它不工作」高效十倍

维护节奏

频率动作
遇到异常时五步排查法走一遍，从缓存开始查（命中率最高）
每月抽查 file-history/ 占用，过大的快照可清理
升级版本后测一遍身份注入是否正常（问它「你的名字和我的偏好是什么」）

原文信息