WorkBuddy 智能体应用的技术架构与运行逻辑分析

内容提要

一、WorkBuddy 的本质是一套"以大模型为决策核、以工具协议为手脚、以文件系统为状态层"的智能体运行时。本文基于对其实际运行行为的观察，拆解其智能体循环、三层工具拓扑（内置工具 / 延迟加载工具 / MCP 外挂）、技能（Skill）装载机制、多智能体协作与三层记忆系统。

二、架构上最值得注意的三个设计：其一，用"延迟加载 + 语义检索"（ToolSearch）控制上下文中工具描述的膨胀；其二，用"提示词契约 + 文件系统"而非数据库来承载技能、记忆与流水线状态；其三，用"质检脚本门禁"把 LLM 生成结果的验收标准固化成可执行代码（如文档流水线的 review 与 verify 双门禁）。

三、本文所有论据均来自可观察行为：工具调用契约、目录结构、脚本参数与真实踩坑记录（孤儿 CSS 类、TOC 域识别条件等），不含对内部实现的臆测；凡属推断处均已标注。

一、研究对象与方法论

WorkBuddy 是一款桌面端 AI 智能体应用：用户以自然语言下达任务，智能体在本地文件系统与网络环境中自主完成"读文件—写代码—跑脚本—查网络—生成文档"的完整闭环，并以文件或在线链接的形式交付结果。本文不介绍其功能清单，而是回答三个工程问题：它如何组织一次任务的执行？它如何管理不断膨胀的能力与上下文？它如何保证 LLM 输出的工程质量？

方法论上，本文只采用"可观察证据"：直接可见的工具参数契约（JSON Schema）、系统注入的环境信息、磁盘上的目录与脚本、以及真实任务中的报错与修复记录。对无法直接观察的内部实现（如模型路由、服务端架构），本文明确标注为推断或不予讨论。这一约束同时也是对智能体写作的一种方法示范——在作者与运行环境之间，"能查证"优先于"能想象"。

二、总体架构：一个"带手脚的对话系统"

从外部观察，WorkBuddy 的架构可以抽象为四层：

表 1　WorkBuddy 的四层抽象架构（据可观察行为归纳）

这套架构的关键取舍在于：状态不放数据库，放文件。技能是 SKILL 指令文件，记忆是 Markdown 文件，流水线状态是 YAML，交付物是磁盘上的真实文件。好处是用户可直接审计与备份每一步产物（例如转换中间产物保留在 stage2/stage3 目录中），坏处是跨会话的查询能力弱于数据库——这解释了为什么 WorkBuddy 需要一个服务端的会话检索工具来做补充（见第七章）。

三、智能体循环：七步执行模型

WorkBuddy 的单次任务执行遵循一个显式的循环协议，每轮迭代固定为七步：分析上下文 → 思考 → 选择工具 → 执行动作 → 接收观察 → 迭代循环 → 交付结果（present_files）。这个协议有三个工程细节值得展开。

细节一：观察即上下文。工具执行结果（包括报错）会以"观察"的形式追加进对话上下文，成为下一轮思考的输入。这意味着智能体的调试方式是"读报错—改参数—重试"，而非人类开发者的断点调试。真实案例：文档转换工具曾因参数名不对而报 usage 错误，智能体立即改用 --help 查看参数契约（--html 而非位置参数），下一轮调用即成功——报错信息本身就是 API 文档的一部分。

细节二：并行与串行由依赖关系决定。系统提示中明确规定"无依赖的调用并行发、有依赖的串行等"。实践中，读两个不相关文件会被合并为一轮并行调用；而"质检通过后才转换"这类链式步骤则严格分轮执行，前一步的输出（如质检 JSON 报告）作为后一步的前置判断。

细节三：交付是一个工具调用，不是一段文字。任务完成的标志是把成品文件路径传入 present_files，由宿主打开预览面板。这把"生成内容"与"呈现内容"解耦：同一个工具既能弹浏览器预览 HTML，也能展示图片/文档卡片，还能对 http://localhost 做可达性检查后回退为本地文件服务——交付逻辑收敛在工具内部，模型侧只需给出路径。

四、工具体系：三层工具拓扑与权限模型

WorkBuddy 的能力面以工具形式组织，观察可见的拓扑分三层：

表 2　三层工具拓扑

延迟层是上下文工程的典型解法。工具少则几十、多则上百，每个工具的 JSON Schema 都是实打实的 token 开销。WorkBuddy 的做法是：Schema 不进初始上下文，等模型用 ToolSearch 以关键词/工具名检索时才返回目标工具的完整契约，再经 DeferExecuteTool 调用。这相当于把"工具文档"做成了按需分页——代价是低频工具多一跳发现成本，收益是常驻上下文显著变短。

权限模型上，Shell 命令默认跑在沙箱里。观察可见：Bash/PowerShell 调用携带 dangerouslyDisableSandbox 参数，默认 false；当命令因沙箱策略被拒时，工具会引导模型走"升级申请"流程，由用户逐次批准越出沙箱。文件写入层面则另有个人目录保护规则（桌面/下载/文档等目录的删除、批量操作被提示词级规则强约束，须用户二次确认）——即安全模型 = 运行时沙箱 + 提示词规则 + 用户批准三道闸，而非单一闸门。

MCP 外挂层兼容社区生态。配置文件是标准的 MCP Server 格式（command/args/env/headers/url），支持 stdio 与远程两种形态。一个真实的细节约束：修改 mcp.json 后服务不会自动生效，必须由用户在连接器管理界面手动"信任"新服务——外部代码接入永远需要一次显式的人工确认。

五、技能系统：把流程知识装进文件

如果说工具是"手脚"，技能（Skill）就是"操作手册"。其机制可观察为三部分：

第一，目录即分发。技能以文件夹为单位安装，路径约定为三级：插件缓存（~/.workbuddy/plugins/cache/发布方/技能名/版本/skills）、用户级（~/.workbuddy/skills，跨项目生效）、项目级（工作区/.workbuddy/skills，团队共享）。同级技能目录内是脚本与文档（如 html-review/scripts/review_html.py、html-to-doc/scripts/convert_doc.py），即技能 = 提示词 + 可执行脚本的捆绑发布。

第二，加载即注入。会话启动时只有技能清单（名称+一句话描述）进上下文；模型根据用户请求匹配到技能后，调用 Skill 工具把该技能的完整指令文本装载进上下文，之后按指令行事。这是一个"目录页 → 章节正文"的两级按需加载结构，与工具层的 ToolSearch 异曲同工。

第三，技能可以编排技能。高阶技能扮演路由器角色。真实案例：文档创作场景中，office-routing 技能先判定任务类型（新建/编辑/转换），再把流程交给 tdoc-orchestrator 编排技能，后者按"创作（S1）→ 排版（S2）→ 转换（S3）"派发给三个专职子智能体（doc-writer / doc-formatter / doc-converter），并以 pipeline-state.yaml 记录每阶段产物路径。技能系统因此不止是"插件"，而是一张可组合的流程图。

六、多智能体协作与任务管理

单会话之外，WorkBuddy 提供两级并行机制。其一，子智能体（subagent）。通过 Agent 工具派生独立上下文的执行体，类型包括通用型（general-purpose）、只读探索型（Explore，仅可读文件与执行检索）、规划型（Plan）与领域专用型（如表格处理的 sheet-agent）。子智能体的结果只返回给主智能体，其过程不进入主上下文——这是控制主上下文膨胀的又一层手段：把大搜索、长执行"外包"出去，主对话只收结论。子智能体还支持后台运行（run_in_background），完成时以通知形式回填结果。

其二，任务清单。TaskCreate/TaskUpdate/TaskList 提供跨工具调用的任务状态机（pending → in_progress → completed），并以 blockedBy 字段表达依赖。工程意义在于把"多步任务"的进度显式化：模型每完成一步即更新状态，用户在界面上可见执行进度，而非只看到最终结果。

七、三层记忆系统

WorkBuddy 的记忆设计回答的是"跨会话如何不失忆、又如何不失速"。观察可见三层：

表 3　三层记忆系统对照

三层的读写权设计是精髓：自动习得的画像只读（防止本地篡改与服务器版本冲突），显式记忆可写（保证"必须遵守"的规则被精确保留），工作区日志只追加（保留时间线，30 天后蒸馏进摘要再删除旧文件）。跨项目的模糊回忆则交给服务端的会话检索工具（零访问当前会话、服务端排序），补齐文件式记忆"难检索"的短板。整套设计的哲学是：记忆分热度——常驻的只有摘要与规则，冷数据落文件，模糊查询走服务端。

八、自动化调度：RRULE 驱动的无人值守

WorkBuddy 支持把任务注册为定时/周期自动化，机制上有两个可观察的工程约束。其一，调度与任务分离：创建自动化的工具（automation_update）携带独立的调度字段——scheduleType（once/recurring）、scheduledAt（ISO 8601）或 rrule（RFC 5545 格式），而任务本体是一段 prompt；RRULE 直接复用日历领域的表达法（FREQ=HOURLY/DAILY/WEEKLY/MONTHLY/YEARLY，配合 INTERVAL、BYDAY、BYHOUR 等），不发明新语法。

其二，prompt 必须自包含。系统明确要求：未来运行看不到当前会话，任何公司名、文件路径、口径、偏好都必须写进 prompt 本体。这实际上把自动化 prompt 当作"定时执行的独立程序"对待——入口参数完整、无对外部状态的隐式依赖。安全上另有硬约束：自动化的增删改只能经调度工具完成，禁止用脚本直接触碰底层数据，杜绝了"绕过 API 写坏调度库"的路径。

九、运行时隔离与安全模型

WorkBuddy 自带受管运行时：Python 3.13.12 与 Node.js 22.22.2 安装在应用私有目录（binaries/versions/...）下，调用须用绝对路径，禁止裸命令。包管理同样被隔离——Python 依赖只能装进运行时目录下的专用 venv，Node 依赖装进受管 workspace 并以 NODE_PATH 注入，全局安装（pip install / npm install -g）被规则禁止。这套设计保证的是：智能体对环境的所有写操作收敛在可控目录内，不污染用户系统环境；版本冲突时按提示换用隔离目录里的其他版本，而不是动用户的全局环境。

把第九章与第四章合起来看，WorkBuddy 的安全模型是四道同心闸：提示词级规则（哪些事不许做）→ 沙箱执行（Shell 命令默认隔离）→ 用户批准（越界操作逐次授权）→ 路径约束（受管运行时与 venv 收敛写操作）。没有一道闸是完美的，但四道闸叠加后，高危操作的漏过概率被压到很低。

十、实战案例：文档生成流水线的完整链路

以本文所用的 Word 文档生成为例，可以完整看到上述机制如何咬合。链路共六步：

● ① 路由：office-routing 技能判定"新建文档"，指向 docx 技能的编排器；

● ② 创作/排版：编排器派发子智能体产出 HTML 母版（本报告即由 HTML + CSS 变量排版而来），状态记入 pipeline-state.yaml；

● ③ 质检门禁：review_html.py 脚本按 genre 参数执行静态检查——设计令牌合规（颜色/字号必须走 CSS 变量）、结构完整性（唯一 h1、封面/目录分节）、孤儿 CSS 类检查（定义了样式但正文未使用的类会报 PF-03 错误）；

● ④ 转换门禁：convert_doc.py 执行预检→转换→verify 三段式，其中对目录域的识别条件精确到 HTML 写法——必须用 <nav class="doc-toc"> + <ol class="toc-list">，写 div/ul 会退化为无域的普通列表；目录须独占封面分节、正文分节须带 data-page-restart 标记，否则报分节错误；

● ⑤ 后处理：对生成的 docx 以 zipfile 重写 document.xml，把目录域级别改写为 \o "1-3" 并置 dirty 标记，使 Word 打开时提示更新页码——这是模型用 Bash 写的一段确定性代码补丁，而非"再生成一次"的玄学重试；

● ⑥ 交付：present_files 弹出成品预览，工作区记忆追加一条流水线日志（含踩坑点，供下次复用）。

这个案例集中体现了 WorkBuddy 的工程哲学：把 LLM 用在"判断与组织"上，把"验收"固化成脚本。质检与 verify 都是纯代码门禁，通过与否不取决于模型的自评；踩坑知识不进模型权重，而是写进记忆文件——下次生成 HTML 时，孤儿 CSS 类与 TOC 写法约束已被预先遵守，同类错误不再复现。

十一、局限与技术观察

● 上下文仍是硬约束。长会话仍会触发压缩（compaction），被折叠的过程信息依赖智能体在最终答复中"完整转述"来补偿；三层记忆缓解但不消除这一约束。

● 文件式状态利于审计、弱于查询。跨会话检索依赖服务端工具，本地状态没有索引；若任务历史极长，"找历史上下文"本身会成为一个任务。

● 门禁脚本是质量上限。review/verify 只能校验可静态化的规则（结构、令牌、域完整性），内容准确性的最终责任仍在模型与用户——白皮书中"不编造数据"这类约束靠提示词规则而非脚本来保证。

● 工具契约即产品界面。从报错信息内嵌 usage 提示、参数默认值引导（如 --require-page-furniture 需显式传），到 ToolSearch 的语义检索，WorkBuddy 把大量产品打磨花在了"让模型一次调用就成功"上——这是所有智能体产品的共性命题。

以大模型为决策核、以工具协议为手脚、以文件系统为状态层、以脚本门禁为质检——这是 WorkBuddy 架构的四块基石。