WorkBuddy Harness拆解蓝皮书：证据驱动的Agent

把 Harness 拆开看

智见 AI 出品的《WorkBuddy Harness 拆解蓝皮书》用 60 页，把 WorkBuddy 这套 AI Agent 的「运行时骨架」拆了个底朝天。它不像产品手册那样教你怎么点按钮，而是顺着代码和数据流，讲清楚一次对话背后到底发生了什么：模型、记忆、工具、专家插件是怎么被编排到一起的。

01 一切都在 ~/.workbuddy 里

书的第一个洞见很朴素：WorkBuddy 的全部复杂性，都安静地躺在~/.workbuddy这个目录里。配置、记忆、会话、技能、专家都按约定好的结构分层存放。理解了目录，就理解了整台机器。作者建议读者先动手看一眼自己的目录，比读任何架构图都来得直接。这也是排查问题最靠谱的入口：卡住了、行为不对了，往往不是模型抽风，而是某个目录下的文件状态出了偏差。

02 官方五层模型

第二章给出官方五层模型：从最上层的用户交互，往下是编排层、能力层、上下文层，再到最底层的模型服务。作者强调把它当索引用，而不是死记层级。真正有意思的是系统提示词的四类零件：人格、记忆、工具描述、规则如何拼成一次请求，以及同一份模板在应用包里也藏着一份。这解释了为什么同一个 WorkBuddy，换个专家或技能包，语气和能力会明显不同——请求在到达模型前，已经被这些零件悄悄改写过。

03 证据驱动：三本账

这本书贯穿一个词：证据。第三章把「会话与证据」拆成三个家族：projects/存按项目分组的会话 JSONL，traces/存执行轨迹，audit-log/存审计记录。三本账分工明确：会话流水回答「它做了什么」，文件历史回答「它改了什么」，轨迹与审计回答「何时、为何」。这让 Agent 的任何动作都可回放、可追责。书中还给出一个实用的双轨对照法：把模型自述的「我以为」和文件里记录的「实际发生」摆在一起，幻觉和越权往往一眼就现形。

04 专家插件：带 UI 的 SubAgent

第七章解剖了最有特色的一块：专家插件。它本质上是一个带 UI 的 SubAgent，通过expertType声明自己是「单 Agent 型」还是「Team 型」。运行时，专家的人设文件被完整注入上下文，模型据此调用对应技能。专家团则是编排层的另一形态，把多个专家组合起来协同工作。这解释了为什么 WorkBuddy 能提供不同专业角色。书里特别提醒一个事故边界：当专家的人设和你的身份设定撞车时，谁优先、如何回退，是上线前必须想清楚的事。

05 身份四件套

第十三章讲到身份体系：身份四件套SOUL.md、IDENTITY.md、USER.md、MEMORY.md这组约定来自 OpenClaw 生态，分别管人格、身份、用户画像和长期记忆。作者给出三个推论：人格重塑是高成本操作要备份；语气调整影响更小；改之前先想清楚要动哪一层。这种分层设计让个性化定制既灵活又可控，也提醒用户：装了插件不等于启用，真正生效还要去开关里确认，否则只是躺在目录里的一堆文件。

写在最后

这本书的价值，是替普通用户把 Harness 这团黑盒里的绳子一根根解开了。读完你会明白，所谓「好用的 AI Agent」背后，是一套被精心设计的目录结构、分层模型和证据链。想真正用好 WorkBuddy，从翻开自己的~/.workbuddy目录开始，比追任何新功能都实在。

WorkBuddyHarness拆解蓝皮书：技术与实践指南.pdf