WorkBuddy 架构原理 完全拆解一句话指令如何变成桌面上一个真实存在的文件？本文从分层架构、Agent 闭环、云端/本地职责切分、Skill 与 MCP 机制、模式切换、安全沙箱六个角度切入，

WorkBuddy 架构原理完全拆解一句话指令如何变成桌面上一个真实存在的文件本文从分层架构、Agent 闭环、云端/本地职责切分、Skill 与 MCP 机制、模式切换、安全沙箱六个角度切入并全程用 SVG 图例把数据流画出来。分析对象腾讯 WorkBuddy2026 年 3 月 9 日正式上线桌面端 Agent 工作台 · 资料来源官方技术博客、腾讯云开发者社区、本地数据逆向分析文章先说清一件事WorkBuddy 是腾讯的闭源商业产品内部实现细节并未公开。本文的架构复原是基于其公开构件Skills、MCP 连接器、三种交互模式、自动化机制与第三方对本地数据的逆向分析拼合而成属于高可信的工程推断不等于官方披露。凡属推断处我会明确标注。01 / POSITION它到底是什么从「副驾」到「主驾」WorkBuddy 的定位是桌面级 AI Agent 工作台装在你电脑上能读本地文件、跑命令、调 Office、连外部系统用自然语言驱动最终把成品递到你手上。它的底层能力从 CodeBuddy 长出——MCP 协议、Skills 技能系统、多模型调度被向上封装了一层。一句话区分三家CodeBuddy 是你的「键盘」在 IDE 里帮你写代码WorkBuddy 是你的「双手」独立桌面客户端能操作电脑、连通办公平台云端聊天机器人只是「嘴巴」只会回答。三者同源可以搭配使用。维度聊天机器人RPAWorkBuddy本质对话接口固定流程自动化分层 Agent 架构核心能力文本生成按脚本重复执行安全执行 工具调用 领域知识可操作性只能聊只能做教过的事读文件、跑 Shell、调云 API、改文档适应变化—页面一变脚本就失效理解意图动态规划02 / LAYERS四层架构从用户到执行的物理映射分层解耦是 WorkBuddy 设计哲学的核心。四层各司其职你只跟第一层打交道右侧贯穿始终的是数据 状态层。四层架构从上到下 从用户到执行① 交互入口层桌面客户端 (Win/macOS)Claw IM 通道 · 企微/微信/飞书/钉钉/QQ微信小程序 · 远程派活② Agent Core 编排层意图理解 NLU任务规划 Planner工具调度 Tool Use执行监控 重试/重规划③ 能力扩展层Skills 技能 (SKILL.md)专家 / 专家团MCP 连接器Plugin 插件数据 状态层SQLite会话/任务/自动化规则jsonl 事件流traces · audit-log三层 Memory云端画像/用户级/工作区级文件系统工作区白名单内读写图 1 · 四层架构总览。入口层接收指令 → 编排层把一句话变成流程 → 能力扩展层提供「插件插槽」→ 执行层在本地落地SQLite / jsonl / Memory / 文件系统全程被读写。第 1 层 · 入口桌面客户端Win / macOS Claw IM 通道企微、微信、飞书、钉钉、QQ 微信小程序远程派活通过 Webhook / Polling 收指令。第 2 层 · 编排意图理解 → 任务拆解Plan→ 多步执行与自主迭代 → 异常重试与重规划支持多 Agent 团队协作Team Mode。这一层是「大脑」。第 3 层 · 能力Skills技能包 专家 / 专家团 MCP 连接器 Plugin。所有业务 Agent 都是用户自建或从市场装的WorkBuddy 本身不预设任何业务 Agent。第 4 层 · 执行本地文件读写、Office 生成、脚本执行、30 内置工具连接器调外部服务。模型在云端它从不直接碰你的硬盘。03 / LOOPAgent 闭环一句话如何变成成品把 AI 从「顾问」变成「执行者」靠的就是这条感知 → 规划 → 执行 → 交付的闭环。每一步都有明确的工程职责而不是「模型自己想办法」。用户说一句人话NLU 结构化 目标 / 约束 / 输出格式Planner 拆子步骤 读文件→清洗→计算→生成→保存模型路由 按任务切模型快/强/长文本Tool Use 生成工具调用 function_call 参数沙箱策略引擎 路径白名单 · 高危二次确认本地执行器 Bash / 文件 / Office / MCP结果回传 验证 失败→重试/重规划交付制品 文件 / 文档 / 图表 / 报告反馈闭环不满意改一句重来云端本地图 2 · 一次任务的完整链路。虚线回路是它和聊天机器人的本质分野任务不是一次 completion 就结束而是推理—调用—回传—再推理的循环直到交付条件满足或触发人工确认。NLU 引擎把人话翻译成机器可执行的任务规格目标、约束、输出格式。你说的是人话它产出的是结构化描述。Planner把大目标切成有序子步骤读文件→清洗→计算→生成→保存执行中可动态调整、可重规划。Tool Use由模型输出结构化工具调用function_call 参数调度内置工具、MCP、Plugin、Skill 去「动手」。执行监控容错重试、状态跟踪、超时处理是整个长任务的「安全网」确保不会悄悄跑偏。04 / SPLIT「云端是脑本地是身体」这是把 WorkBuddy 和开源 Agent 框架彻底区分开的一个架构选择。区别不在「是否调云端 API」——全本地框架也可以调云端 API 做推理区别在于云端承担了多少职责。本地宿主Electron 主进程① Jinja2 渲染 system prompt ② 拼装 Skills / 记忆 / 模式片段 ③ 组装工具 schema 白名单云端认知中枢· LLM 推理 工具选择 · 记忆生成与用户画像 · conversation_search 检索排名 · 多模型调度 / 分层本地执行 落盘· 子进程 / 沙箱跑 Bash · 文件读写 · MCP 调用 · jsonl 追加事件 · traces / audit-log渲染好的 prompt 上下文工具调用 decision执行结果回传记忆/排名产物关键分野模型从不直接碰你的硬盘它只输出「结构化工具调用」由本地执行器落地图 3 · 云端/本地职责切分。云端是认知中枢推理、工具选择、记忆生成、历史对话排名、用户画像本地是身体prompt 渲染、工具执行、事件落盘、安全隔离。职责全本地框架Hermes / OpenCode / AiderWorkBuddy云端角色「推理即服务」发 prompt、拿 completion结束认知中枢承担记忆/排名/编排本地角色推理 执行 存储全在本地渲染 执行 落盘 隔离系统 prompt源码里硬编码改行为 改代码/等版本Jinja2 模板 .md 片段运行时拼装顺带说一个容易被忽略的设计prompt 是拼出来的不是写死的。主模板里用include织入片段插槽变量承载 ResponseLanguage、dataFolderName、IsWindows、三层记忆内容等运行时值22 个 include 10 运行时变量才凑成一份完整的 system prompt。想改 Agent 行为协议改一个 .md 片段即可无需重新编译。05 / SKILLSkill一个 Markdown 文件的威力Skill 是能力体系的原子单位。它不是代码组件也不是一段提示词而是一份写给 AI 看的「工作手册」——告诉 AI 遇到这类任务该按什么步骤做、用什么工具、注意什么坑。启动扫描 skills 目录skill_index常驻上下文只存 name description用户输入命中 trigger关键词 / skill 手动指定匹配load_skill 读取 SKILL.md 正文 注入 prompt正文 写给 AI 看的「工作手册」角色定义 · 执行流程 · 输出格式 · 约束规则 可选 scripts/ references/ assets/用到才读省 token本质Skill 不是代码组件是一份 Markdown 方法论文档写不好 description技能就永远唤不醒。图 4 · Skill 的两阶段加载。启动只把name description塞进常驻上下文省 token正文等到真正触发时才读取并注入 prompt —— 这套「渐进式披露」是它的精髓。文件结构my-skill/SKILL.md必需 可选references/参考资料、scripts/辅助脚本、assets/模板。SKILL.mdYAML frontmattername/description/trigger/version Markdown 正文角色定义、执行流程、输出格式、约束规则。触发方式自动输入匹配 trigger 关键词、手动skill:xxx、命令/skills查看已安装。存放位置用户级~/.workbuddy/skills/跨项目 项目级.workbuddy/skills/团队共享、随仓库走。三个实战要点①description是第一要务模型只凭它决定要不要唤醒这个技能写不清就永远唤不醒② trigger 放 3–5 个核心词多了会跟别的 Skill 冲突③ 正文写「操作手册」不写论文——动词开头、规则可验证正文控制在 5000 词内详情丢进 references。06 / MCPMCP 连接器AI 的「USB 口」MCPModel Context Protocol定义了大模型与外部工具之间的通信标准。以前 AI 只能靠自己的知识回答有了 MCP它就能查地图、查数据库、操作浏览器、收发邮件。WorkBuddy MCP Client协议适配层JSON-RPC → 平台原生协议能力声明层manifest capabilities权限隔离层最小权限集 / 独立进程传输层stdio 本地 · SSE 远程MCP Server 独立进程调用腾讯文档 / 邮箱 / 会议飞书 · 企微 · GitHub数据库 · 浏览器 · 地图MCP 是「AI 的 USB 口」工具端暴露带 schema 的函数模型端选工具并填参数双方靠标准协议解耦。图 5 · MCP 连接器四层结构。工具端Server暴露一组带 schema 的函数模型端Client选工具并填参数传输层支持 stdio本地进程与 SSE远程服务。三个工程细节值得记独立进程运行通过 Unix Domain Socket 与主 Server 通信每个连接器启动时强制指定最小权限集如飞书连接器默认无文件读写权限——即使某个连接器存在 RCE 漏洞也难以突破到 MCP Server 层声明式 UI工作台根据 manifest 里的capabilities如requires_oauth2动态生成配置界面该出「授权按钮」还是「Token 输入框」由声明决定传输双模本地用 stdio低延迟、无网络远程用 SSE。07 / STATE记忆、任务与自动化让它越用越懂你三层记忆云端画像长期偏好服务端维护。用户级~/.workbuddy/MEMORY.md跨项目复用。工作区级.workbuddy/memory/MEMORY.md 每日日志沉淀单个项目的决策与约定。注这三层是全文注入非向量检索没有 embedding、没有相似度检索。任务 自动化任务系统复杂工作拆成可追踪子任务状态从待办→进行中→完成流转进度全程可见。自动化支持定时RRULE与一次性调度定义存在 SQLite 里——「每天早上生成经营晨报」可无人值守跑。conversation_search独立的服务端检索排名工具与常驻记忆注入是两套机制。08 / CASE案例同一套管线如何跑通三类活案例周报自动化一句话 → 成品你说把本周 git 提交和会议纪要做成周报入口 · 桌面或企微NLU 抽出数据源 周期 输出格式结构化Planner取提交→读纪要→归类→成文→存盘拆解 5 步触发 weekly-report Skilldescription 命中能力扩展层沙箱校验路径白名单 → 逐条工具调用安全层生成 .docx沉淀到工作区更新 MEMORY.md交付 记忆同样的管线换 Skill / 换连接器就能跑「整理乱文件夹」「合同审查」「生成经营晨报」。图 6 · 周报自动化案例。从一句人话到一份 .docx六个环节横跨入口层、编排层、能力层、执行层、安全层。案例触发管线关键节点沉淀物周报生成一句话 / 每周五定时取 git 提交 会议纪要 → 归类本周事项 → 按模板成文 → 存盘.docx 更新 MEMORY.md乱文件夹整理「整理桌面上的报告」读目录清单 → 按类型/日期分桶 → 建子目录 → 移动先备份整洁目录 操作审计日志合同审查合同文件 技能命中加载合同审查 Skill 法务专家人设 → 调法条连接器 → 出风险清单批注版 docx 风险表经营晨报每天 08:30 定时拉销售数据 → 计算环比 → 画图 → 推送企微群图表 群消息无人值守这四个案例的管线完全一样差异只在于换了哪个 Skill、接了哪个连接器、落在哪个目录。这就是「引擎式设计」的含义——不是为每个领域单独部署 Agent 实例而是「一套通用 Agent 领域 persona 工具链」覆盖全场景。09 / MODE模式切换同一运行时的四张皮肤WorkBuddy 有 ask / plan / craft / expert 四种交互模式分别对应不同的风险胃口。本地逆向发现一个反直觉事实模式选择不落盘。ask只读不动plan先出方案再执行craft直接动手默认expert人设注入 craft 工具集切换只做四件事换 interactionmode/ 片段集 → 重建工具 schema 白名单 → 重渲染 Jinja 变量 → 重拼 system prompt• 模式由 UI 进程临时持有不落盘重启回到默认 craft没有「上次用的模式」这种记忆• 不需要重启进程、不重建上下文 —— 同一套运行时换了一张「行为皮肤」图 7 · 模式切换管线。切换 换片段集 重建工具 schema 重渲染模板变量 重拼 system prompt不需要重启进程、不重建上下文。模式行为适用ask纯问答 / Code Review不动文件「帮我看看这坨代码啥意思」plan先列分步计划你点头再执行重构、架构设计、多文件操作craft默认模式直接动手改文件、跑命令目标明确、风险低的活expertcraft 工具集 专家人设注入合同法务、DB 运维等单点深水区由此带来的两个可观测结论① 重启 WorkBuddy 后模式回到默认 craft没有「上次使用的模式」这种记忆② 模式切换是即时生效的——换的只是 prompt 和工具白名单。10 / SECURITY安全模型把 Agent 当「有明确岗位的同事」桌面 Agent 最大的质疑永远是「它会不会乱删我东西」。WorkBuddy 的答案是把安全做成分层防线而不是一句「已开启沙箱」。工具调用请求策略引擎L1 全自动读L2 会话内确认写L3 人工审批删/资金trust profile通过执行 写审计日志拒绝返回 ApprovalRequired高危纵深防线工作目录授权 → 沙箱隔离 → 路径白名单 → 敏感命令二次确认 → 自动备份/删除进回收站 → TraceID 全链路审计图 8 · 工具调用前的策略检查。每一次工具执行都要先过 trust profile 分级被拒的请求会拿到ApprovalRequired而不是静默失败。L1 全自动仅读取操作与环境信息查询ls、非敏感 API 调用。L2 会话内确认写入操作但影响范围可控创建文件、调内部工具链。L3 人工审批涉及资金、数据删除或跨租户操作必须你显式批准。纵深防线工作目录授权 → 沙箱隔离 → 路径白名单自动拦截系统/敏感目录→ 敏感命令二次确认 → 自动备份改前备原版→ 删除进回收站 → TraceID 全链路审计。给自动化任务加「硬边界」是必须的无人值守的定时任务没有弹窗可以确认所以要在提示词里自建护栏 —— 写死工作目录绝不超出、只允许「读源 新增结果文件」、禁止删除/覆盖/对外上传、遇不确定项跳过并在末尾列「⚠️ 跳过项」。11 / VERDICT对比与启示它揭示了什么架构上的三个聪明之处①引擎式而非实例式不预设业务 Agent靠通用 Runtime persona 工具链组合覆盖全场景。②Skill 即契约用 Markdown 文件承载能力人人可读可写可分享把「经验」变成可版本管理的资产。③Prompt-as-Code模板 片段 插槽变量让行为协议可配置、可热切换。仍然要清醒看到的边界① 闭源产品内部细节全靠推断本文结论需以官方披露为准。② 「计划」很可能不是结构化 Plan 对象而是模型 reasoning 里的文本——本地不解析、不持久化、不调度重规划完全依赖模型自觉。③ 云端承担认知中枢意味着离线可用性与数据不出域需要额外权衡。一句话总结聊天机器人只会「说」RPA 只会「按脚本做」WorkBuddy 把「理解 规划 安全执行 领域经验 多智能体协同」串成了一条完整的交付链——这正是 AI 产品从「对话接口」走向「智能体运行时」的范式转移。