WorkBuddy 底层机制：一次对话在本地磁盘上发生了什么

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

一句话结论

WorkBuddy 界面上的每一个按钮，背后都对应 ~/.workbuddy 目录里的具体文件；看懂这个目录，就看懂了它为什么记住这件事、为什么忘了那条规矩、为什么插件装完反而变笨。

本章概述

这一课讲 WorkBuddy 的「身体」：一次对话从按下回车到交付结果，在本地磁盘上依次发生了什么。学完你能在自己的电脑上找到 WorkBuddy 的配置目录，说出每个子目录管什么，并掌握「UI → 文件 → 请求」的排查思路。这一套方法不限于 WorkBuddy，在任何 Agent 产品里都能用。

为什么你需要看懂底层

用 WorkBuddy 的人迟早会撞上同一堵看不见的墙：

这些现象的答案都不在界面上，而在本地一个你从没打开过的目录里。WorkBuddy 把你的身份、记忆、插件、技能、会话记录全部存在 ~/.workbuddy 里——看懂这个目录，墙就不存在了。

第一环：你的话加上它的记忆，一起出发

你按下回车的第一件事，不是「发给大模型」。WorkBuddy 先组装上下文，这次请求的零件包括：

  1. 你输入的这句话
  2. 系统提示词 ——定义它行为方式的底层说明书
  3. 记忆里的相关内容 ——三层记忆（见第 44 课）中检索出的历史信息
  4. 当前工作区的项目上下文 ——项目指令、技能清单等
  5. 专家人设提示词 ——如果这次对话挂在某个专家身上

这些零件几乎全部来自 ~/.workbuddy 目录。也就是说：你得到的每一次回答，质量上限在你提问之前就被这个目录里的文件决定了。

第二环：模型只做一件事

上下文组装完成后才轮到大模型。模型拿到的是一段拼装好的文本，它做的事只有一件：基于这些内容决定下一步——直接回答、调用工具，还是向你确认。

关键理解：模型不知道「按钮」「界面」「市场」这些概念，它只知道拼进这次请求的内容。所以「模型变笨了」很多时候不是模型的问题，是拼装环节出了问题——某个插件注入了多余的提示词，或者记忆里塞满了过期信息。

第三环：工具执行，风险拦截

模型决定调用工具（写文件、执行命令、访问外部服务）时，WorkBuddy 的安全层介入：

第四环：留下痕迹

每一步操作都会留证据，分布在三个地方：

证据位置用途
会话流水sessions/（JSON 文件，按会话 ID 命名）完整对话记录
执行轨迹traces/（按会话 ID 分目录）每个工具调用的输入输出
审计日志audit-log/（按天的 JSONL 文件）关键操作的时间线

排查「它说做了但文件没变」「昨天它到底改了什么」，答案全在这三处。

第五环：交付与沉淀

任务结束，交付物落进工作空间。同时还在发生两件安静的事：这次会话的关键信息被写入记忆（受限额约束，见下一课）；如果是定时任务，下次执行时间写进本地数据库 workbuddy.db。

工作没有真的结束——它变成了下一次对话的上下文。

动手：三分钟逛完数据目录

打开 Finder，按 Cmd+Shift+G，输入 ~/.workbuddy，你会看到 70 个左右的条目。核心家族如下：

家族代表成员职责
身份SOUL.md、IDENTITY.md、USER.md、MEMORY.md人格、身份、用户画像、跨项目记忆
调度workbuddy.db（SQLite）任务、自动化、会话状态
能力skills/、plugins/、connectors/技能、插件、外部连接
证据sessions/、traces/、audit-log/、file-history/会话、轨迹、审计、文件快照
产物workspace/、blobs/、artifact-index/工作空间、产物存储与索引
配置settings.json、user-state.json全局设置与状态

一条关键架构判断：SQLite 管调度，文件管 Harness。 需要事务一致性的调度数据（任务队列、自动化状态）走数据库；而决定「AI 是谁、会什么、记得什么」的 Harness 配置全部是纯文件——所以你可以直接用文本编辑器打开看、改、备份。这是 WorkBuddy 可定制性的根基。

两个实用推论：

  1. 备份 Harness = 备份那几个 md 文件和 skills 目录 ，不用管数据库
  2. 换机器迁移 时，身份和技能跟着文件走，任务历史留在数据库里

把这套方法带走

这五环模型和「UI → 文件 → 请求」的追问路径，是可迁移的 Agent 素养：看到任何 Agent 产品的行为，先问「实现它的文件在哪」，再问「这次请求里拼了什么」。带着这两个问题，你在任何 Agent 产品里都不会迷路。

原文信息