ARTICLE · 1290182
WorkBuddy:腾讯的一款AI智能体办公助手
1. 文档目标与证据边界
WorkBuddy 是腾讯云代码助手团队推出的 AI Agent 办公工具。它不只是聊天机器人，而是把大模型、任务规划、工具调用、文件操作、浏览器、办公文档、知识库、连接器、自动化和多端入口组合成可交付结果的工作系统。
本文同时使用三类证据：
1. 官方公开事实：WorkBuddy 官网、官方帮助文档、更新日志与公开产品页面。 2. 公开发布产物事实： @tencent-ai/codebuddy-code@2.164.0npm 包内的启动器、类型声明和注释，以及官网公开前端构建资产。3. 工程推断：根据公开接口、环境变量、类型契约和宿主分层关系，对未公开源码部分进行合理还原。
文中使用以下标识：
• [官方]：官方页面明确说明。• [发布产物]：可在公开 npm 包或前端构建产物中直接验证。• [推断]：未获得完整闭源实现，只能依据公开接口推导。
需要特别注意：WorkBuddy 桌面客户端、workbuddy-server、云端控制面和企业后台并未整体开源，因此本文不是完整源代码审计，也不会把推断冒充事实。
2. 一句话理解 WorkBuddy
传统聊天助手的输出通常是一段文字；WorkBuddy 的目标是接收一个工作目标，规划步骤，选择模型和能力，操作本地或云端资源，持续执行，再交付文档、表格、幻灯片、网页、应用、研究报告或自动化结果。
可以把它理解为：
聊天入口 + Agent 任务规划 + 本地/云端工具执行 + Skills 与专家角色 + Connectors 与 MCP + 文件、浏览器、Office、知识库 + 自动化、移动端和企业治理 = 面向真实工作的 Agent 工作台3. 产品定位
3.1 与普通 AI Chat 的区别
3.2 与 Coding Agent 的关系
WorkBuddy 复用了 CodeBuddy/CBC Agent Harness 的大量基础能力，但产品边界更宽：
• Coding Agent 以代码仓库、终端、编辑器和 Git 为中心。 • WorkBuddy 以通用工作任务、文件、资料、Office、浏览器和业务系统为中心。 • WorkBuddy 同样能做开发任务，并提供 Git 集成、Worktree 并行开发、小程序和网站应用发布。 • 公开 npm 发布物显示，WorkBuddy 宿主会启动 CodeBuddy 的 lite-wb精简运行时。
因此更准确的表达是：WorkBuddy 是建立在通用 Agent Harness 和 Code Agent 能力之上的多场景工作 Agent 产品。
4. 产品能力地图
4.1 核心工作对象
◆ 任务 Task
任务是一次可执行工作单元。用户提供目标、附件、模型、技能或专家后，Agent 在任务中持续对话和执行，最终产生结果。
典型生命周期：
创建任务 → 理解目标 → 补充上下文 → 规划 → 工具执行 → 中途确认/纠偏 → 结果检查 → 产物交付 → 分享或沉淀◆ 项目 Project
项目用于承载长期工作上下文。相较一次性任务，项目更适合代码仓库、专题研究、产品策划和持续内容运营。
◆ 助理 Assistant
助理是可通过微信、企业微信、QQ、飞书、钉钉等渠道触达的长期 Agent。它把 WorkBuddy 从“需要主动打开的应用”扩展为“可在日常通信渠道中随时调度的员工入口”。
◆ 专家 Expert
专家强调角色、领域知识、工作方法和输出标准，例如研究专家、数据分析专家、产品经理、设计师或开发专家。
◆ Skill
Skill 是可复用的能力和工作规程，通常包括使用说明、触发条件、步骤、脚本、模板或依赖工具。官方文档展示了 Agent Browser、Office Document Suite、Local Whisper、Web Search、Obsidian、Skill Scanner 等技能。
◆ Connector
Connector 用于把 Agent 接入外部业务系统或数据源。它更关注身份授权、资源访问和业务动作；底层可以通过 MCP、HTTP、OAuth 或宿主代理实现。
◆ 资料库 Library
资料库提供内容管理、多人多 Agent 协作和轻量发布。它既是知识输入，也是 Agent 产物的沉淀和协作空间。
◆ Buddy 应用与 Artifact
Agent 结果不局限于聊天消息，可形成网页、文档、应用或可分享节点。公开类型声明显示至少存在：
• page：HTML 页面节点，可形成公开页面。• doc：Markdown 文档节点，可进入 WorkBuddy 空间。• 本地文件导入、公开权限设置与取消发布等契约。
4.2 官方公开场景
• 研究：检索、汇总、交叉验证、报告生成。 • 文档：写作、改写、排版、多人协作、知识沉淀。 • 设计：创意、视觉方案、网页与前端设计。 • 开发：本地应用、网站、小程序、云服务、Git 与 Worktree。 • 数据：清洗、分析、图表和报告。 • 运营：内容生产、素材处理、定时简报和自动分发。 • 办公：会议管理、腾讯文档、邮箱、企业知识库。
5. 多端产品矩阵
[官方] 官网公开了以下入口：
移动端和小程序并不是完整本地执行引擎的简单复制。更合理的设计是把移动端作为控制端，通过账号、云会话或“连接电脑”调度桌面端能力。
6. 总体架构
以下架构中，产品模块来自官方文档；lite-wb、Host Detection、ACP、MCP、Sandbox 等来自公开发布物；具体内部服务拆分为工程推断。
┌──────────────────────────────────────────────────────────────┐│ Client Layer ││ Desktop │ Web/Enterprise │ Mobile │ Mini Program │ IM Bots │└──────────────────────────────┬───────────────────────────────┘ │ Task/Conversation/Artifact API┌──────────────────────────────▼───────────────────────────────┐│ WorkBuddy Product & Control Layer ││ Task │ Project │ Assistant │ Expert │ Skill │ Automation ││ Library │ Artifact │ Account/Billing │ Enterprise Governance │└──────────────┬───────────────────────────┬───────────────────┘ │ local IPC/ACP │ cloud APIs┌──────────────▼──────────────┐ ┌────────▼───────────────────┐│ Desktop Host / WB Server │ │ Cloud Control Plane ││ sidecar manager │ │ identity/model/knowledge ││ connector proxy │ │ task sync/share/publish ││ permission & sandbox policy │ │ telemetry/enterprise admin │└──────────────┬──────────────┘ └────────────────────────────┘ │ spawn + env + protocol┌──────────────▼───────────────────────────────────────────────┐│ CodeBuddy lite-wb Agent Runtime ││ Session │ Context │ Agent Loop │ ToolManager │ MCP │ Memory ││ Subagent/Team │ Hooks │ Approval │ Trace │ Artifact │└───────┬────────────┬──────────────┬──────────────┬───────────┘ │ │ │ │┌───────▼─────┐┌─────▼──────┐┌─────▼──────┐┌──────▼──────────┐│ Local Tools ││ Skills ││ Connectors ││ Model Gateway ││ FS/Shell/Git││ Experts ││ MCP/OAuth ││ Multi-model/LLM ││ Browser ││ Playbooks ││ SaaS APIs ││ policy/routing │└─────────────┘└────────────┘└────────────┘└─────────────────┘7. 桌面宿主与 sidecar
7.1 为什么需要 sidecar
桌面 UI 不应直接承载所有 Agent 运行逻辑。将 Agent Runtime 作为 sidecar 子进程有以下价值：
• UI 与模型流式处理、工具执行解耦。 • Agent 崩溃不必拖垮整个桌面进程。 • 可以独立预热、重启和回收运行时。 • 可以使用 Node.js 生态中的 CLI、MCP SDK 和文件工具。 • 可以通过环境变量给不同宿主注入能力门控。
7.2 可验证的宿主识别
[发布产物] host-detection.d.ts 明确说明，WorkBuddy Desktop 的 sidecar-manager 会注入：
CODEBUDDY_HOST=workbuddy-desktop公开类型中定义的宿主包括：
typeHostName = 'workbuddy-desktop' | 'vscode-acp' | 'web-ui' | 'cli';这意味着同一 Agent 内核可被多个产品宿主复用，但通过 Host Gate 控制遥测、工具、文件安全、会话行为和 UI 协议。
8. lite-wb 启动链源码级剖析
8.1 运行时选择
[发布产物] @tencent-ai/codebuddy-code@2.164.0/bin/codebuddy 公开启动器包含三种 bundle：
codebuddy | ||
codebuddy-headless | ||
codebuddy-lite-wb.mjs |
WorkBuddy 宿主在启动 sidecar 或预热进程前设置：
CODEBUDDY_FORCE_LITE_WB_BUNDLE=1入口逻辑可概括为：
if (forceLiteWb) {awaitimport('codebuddy-lite-wb.mjs');} elseif (isHeadless) {require('codebuddy-headless');} else {require('codebuddy');}若产物缺失，则回退：
lite-wb → headless → full8.2 为什么单独构建 lite-wb
启动器注释明确指出，lite-wb 在 headless 基础上继续剔除 WorkBuddy 不使用的结构性模块：
• TUI views • LSP • update • record-replay • channel • 其他 WorkBuddy 宿主不会触达的桶
收益是降低：
• 冷启动时的 JS 解析与编译成本。 • 常驻堆内存。 • 预热池的单实例成本。 • 桌面端首次任务的等待时间。
8.3 ESM 与 lazy chunks
lite-wb 使用 .mjs 并通过动态 import() 加载。它拥有独立的 lazy-lite-wb/ 分块目录。启动器会读取构建生成的 manifest.json，只预载当前版本、当前变体的 lazy chunks。
这一设计解决了全局安装升级时的竞态：若运行中的进程与包管理器共享安装目录，升级可能覆盖 chunk 文件；提前把当前版本模块放进 Node 模块缓存，可避免后续加载出现 ENOENT 或 hash 不匹配。
这反映出 WorkBuddy Runtime 的两个重要特征：
1. 它是长驻或可预热的 Agent 进程，而不是每次请求都从零启动。 2. 团队对冷启动、并发进程升级和内存占用做了专门工程优化。
9. Agent Loop
WorkBuddy 的任务执行可抽象为以下循环：
接收目标 ↓加载会话、项目、记忆、附件、Skill、Expert、企业策略 ↓构建模型上下文并选择可用工具 ↓模型推理：回答 / 调用工具 / 请求确认 / 分派子任务 ↓权限与风险检查 ↓执行本地工具、MCP、Connector 或云端能力 ↓标准化工具结果、记录 Trace、更新 Artifact ↓判断是否完成；未完成则压缩上下文后继续伪代码：
while (!session.completed) {const context = awaitbuildContext(session, project, memory, policy);const tools = await toolManager.visibleTools(context);const response = await model.generate({ context, tools });if (response.type === 'tool_call') {await approval.guard(response.tool, response.args);const result = await toolManager.execute(response.tool, response.args); session.append(normalize(result)); } elseif (response.type === 'ask_user') {await session.waitForUser(); } else { session.append(response); }if (context.nearLimit()) awaitcompact(session); session.completed = await completionPolicy.check(session);}真实系统还必须处理取消、软停止、失败分类、工具超时、网络重试、支付/积分拦截、会话回放和宿主断线恢复。
10. 会话、上下文与压缩
10.1 会话状态
一个可恢复的 Agent 会话至少包含：
• 用户消息与模型消息。 • 工具调用、参数、返回值和错误。 • 当前目标、计划和完成状态。 • 附件、文件引用和 Artifact ID。 • 模型、Token 用量和费用上下文。 • 权限批准记录。 • 中断、排队输入和用户 steer 信息。 • Trace ID、request ID、message ID。
公开类型声明中可见 Session、Follow-up Queue、Steer Input、Interruption、Replay、Usage Update 和 Goal Control 等契约，说明 WorkBuddy 的对话并非简单消息数组。
10.2 上下文压缩
长任务不能无限把全部历史发给模型，通常会采用：
1. 保留系统规则、当前目标和安全策略。 2. 保留最近若干轮原文。 3. 将早期步骤压缩为结构化摘要。 4. 单独保存关键事实、未完成事项、文件变更和工具证据。 5. 大型工具输出保留引用，仅向模型注入摘录。
公开类型中的 pre-message-compact-strategy 提到自动压缩和用户命令触发的压缩，并注明 WorkBuddy/TUI 可手动压缩。这说明压缩是 Agent Harness 的一等能力。
10.3 Memory
Memory 与对话摘要不同：
• 摘要用于维持当前会话连续性。 • Memory 用于跨任务保存用户偏好、稳定事实和长期工作上下文。 • 知识库用于可检索的外部资料。 • 项目上下文用于特定工作空间的文件和规则。
最佳实践是让记忆可查看、可编辑、可删除，并避免把敏感临时信息无条件升级为长期记忆。
11. ToolManager 与工具可见性
[发布产物] Server 类型声明提供 WORKBUDDY_TOOLS 预设。注释表明它是 cloud WorkBuddy 的策展工具集合，依据宿主白名单增减能力。
工具不是简单地“全部注册给模型”，而应经过多层筛选：
产品默认工具池 ∩ 当前 Bundle 实际存在的工具 ∩ 宿主能力位 ∩ 当前平台支持能力 ∩ 用户/企业策略 ∩ 当前模式白名单 ∩ 会话授权状态 = 模型本轮可见工具这种设计可以：
• 减少工具描述消耗的 Token。 • 降低模型选错工具的概率。 • 避免把宿主不能处理的工具暴露给模型。 • 实施最小权限和企业策略。
12. Skills、Experts、Playbooks 与 Rules
12.1 四者分工
12.2 Skill 执行机制
典型 Skill 加载流程：
识别任务意图 → 检索可用 Skill → 读取元数据和说明→ 校验依赖/权限 → 将操作指南注入上下文→ 按需执行脚本或调用工具 → 记录结果Skill 应避免把大段说明始终塞入系统提示词。更高效的方式是先给模型简短目录，命中后再延迟加载详细说明和资源。
12.3 Skill 供应链风险
第三方 Skill 可能包含恶意提示、脚本、下载行为或过宽权限。企业环境应具备：
• 来源签名和版本锁定。 • 安装前静态扫描。 • 声明式权限清单。 • 执行时沙箱和网络限制。 • 审计日志与一键禁用。 • 更新差异审查。
官方文档展示 Skill Scanner，说明产品已意识到 Skill 生态的安全审查需求。
13. Connector 与 MCP
13.1 分层关系
模型工具调用 ↓Agent ToolManager / MCP Manager ↓WorkBuddy Connector Proxy ↓OAuth / Token / Enterprise Identity ↓腾讯文档、乐享、ima、邮箱或第三方 SaaS[发布产物] MCP Manager 类型声明说明，WorkBuddy Desktop 下会在 MCP tools/call._meta 中加入 workbuddy.ai/* 字段，将 Connector 调用埋点上下文透传到 ConnectorProxyServer。第三方 MCP Server 可忽略未知 _meta。
这揭示了几个事实：
• WorkBuddy 使用 MCP 作为部分工具的统一协议层。 • Connector Proxy 聚合多个后端 Connector。 • 宿主负责附加业务侧调用身份和遥测上下文。 • 用户自定义 MCP 与内置 Connector 可以共用 Agent 侧管理器，但授权和产品呈现不同。
13.2 OAuth 与审批
MCP Controller 类型公开了供桌面端轮询连接状态和打开浏览器进行 OAuth 的入口。合理流程为：
添加 Connector → 浏览器 OAuth → 回调桌面宿主→ 安全保存凭据 → MCP/Proxy 建连 → 枚举工具和资源→ 高风险动作再次确认不要仅在“安装 Connector”时做一次总授权。删除、发送、发布、转账、邀请成员等不可逆动作仍应在执行前做细粒度确认。
14. ACP、A2A 与多 Agent
14.1 ACP
公开类型大量出现 ACP 会话、Prompt、Replay、Terminal、Goal Control 等契约。这里的 ACP 可理解为宿主 UI 与 Agent Runtime 之间的结构化交互协议，用于：
• 发起 Prompt。 • 流式接收文本和工具状态。 • 传输宿主元数据。 • 控制会话、目标、取消与回放。 • 呈现终端输出、权限确认和 Artifact。
14.2 A2A
公开工具预设注释提到出站 A2A 工具以及远程 Agent URL 门控。A2A 用于 Agent 间任务委派，而 MCP 主要用于 Agent 调用工具或资源。
二者区别：
14.3 多 Agent 并行
[官方] 官网明确支持多 Agents 并行；资料库支持多人多 Agent 协作。实现时需要：
• 主 Agent 拆分目标。 • 子 Agent 使用隔离上下文。 • 为每个任务限定工具、目录和预算。 • 汇总结果时解决冲突和重复工作。 • 共享事实通过受控 Artifact 或任务状态传播。 • 对并行调用设置并发、Token 和时间上限。
在代码任务中，Git Worktree 是比多个 Agent 直接编辑同一目录更安全的隔离单元。
15. Git 与 Worktree 并行开发
[官方] WorkBuddy 提供 Git 集成和 Worktree 并行开发。
推荐模型：
主仓库├── worktree/task-a → Agent A → feature/a├── worktree/task-b → Agent B → feature/b└── worktree/review → Review Agent每个 Agent：
• 只修改自己的 Worktree。 • 使用独立分支。 • 运行局部测试和静态检查。 • 产出提交、补丁或变更说明。 • 最终由主任务或人工合并。
常见问题包括端口冲突、依赖缓存竞争、数据库共享、生成文件冲突和多个 Agent 同改基础接口。需要项目级资源分配和合并策略，而不仅是创建目录。
16. 沙箱、安全中心与权限模式
16.1 安全分层
提示词约束 ↓工具白名单与参数校验 ↓用户审批 / 企业策略 ↓文件系统与进程沙箱 ↓网络、身份和 Connector 权限 ↓日志、告警、回滚与取证提示词不是安全边界。真正的强制控制必须发生在模型之外。
16.2 文件与命令沙箱
[发布产物] 类型声明公开了：
• sandbox-cli• Bash Sandbox • WorkBuddy protected paths • Security Center 文件规则 • 宿主注入额外可写目录 • Safe Delete • File Rollback / Checkpoint • Tool Control Policy
合理的默认策略应是：
• 工作目录内读写。 • 工作目录外默认只读或拒绝。 • 用户密钥、系统配置和 WorkBuddy 自身目录受保护。 • 批量删除、覆盖和执行文件需要更高等级审批。 • 删除尽可能走可恢复机制。 • 命令执行限制环境变量、PATH 和子进程继承。
16.3 macOS Sandbox Helper
[发布产物] sandbox-cli-lifecycle.d.ts 暴露了较多实现细节：
• WorkBuddySandboxHelper是全机单例。• 多个 Electron 实例通过 App Group 容器中的 Unix Domain Socket 通信。 • 使用 O_CREAT|O_EXCL锁文件避免重复拉起。• 通过 socket connect 与 Ping 双重健康检查识别残留 socket 和假阳性。 • Helper 与 SandboxExt.framework、FileProvider domain、session registry 等组件协作。
这说明 macOS 强沙箱不只是 Node 层路径判断，而包含原生 Helper、Framework 和系统扩展式能力。
16.4 网络安全
Agent 具备浏览器、Web Search、MCP 和命令行下载能力后，应防范：
• SSRF 和内网探测。 • DNS Rebinding。 • 恶意网页 Prompt Injection。 • 凭据通过 URL、日志或工具返回泄漏。 • 下载并执行不可信二进制。 • Connector 结果伪装成系统指令。
应对手段包括域名/IP 策略、内容降权标记、下载隔离、敏感信息脱敏和出站审计。
17. REPL 与宿主桥
[发布产物] 类型声明中存在 REPLTool、repl-bridge-host 和 repl-sandbox-capability。注释将 REPL 描述为模型侧编写 JavaScript、导入 WorkBuddy 桥并进行编排的入口。
这类设计的优势是：模型可以用少量 JavaScript 组合多个高层资源，而不必把每个细粒度动作都做成一个独立工具。
风险也更高：
• REPL 必须处于沙箱或受控 Worker。 • 只能导入显式暴露的桥模块。 • 需要 CPU、内存和执行时间限制。 • 宿主桥应使用能力令牌，不能直接暴露桌面进程对象。 • 返回值必须序列化、限长并去除敏感字段。
18. Artifact、分享与轻量发布
Agent 产物的工程链路通常是：
本地生成文件/页面 ↓类型识别与内容校验 ↓上传或导入 WorkBuddy 空间 ↓生成 Artifact 节点 ↓配置组织内/互联网权限 ↓分享、协作、撤销发布安全重点：
• 上传前扫描脚本、宏和恶意 HTML。 • 明确“组织内可读”和“互联网公开”的区别。 • 内容审核失败应返回可理解的业务错误。 • 发布动作应可追踪、可撤销。 • 分享链接避免携带长期敏感 Token。
19. 自动化与远程遥控
[官方] WorkBuddy 支持自动化、每日资讯简报、远程遥控和 AI 自驱动。
自动化系统至少需要：
• 触发器：时间、消息、文件变化或业务事件。 • 输入模板：任务目标、变量和附件。 • 执行身份：用户、服务账号或企业机器人。 • 运行环境：云端、桌面在线执行或混合模式。 • 幂等键：防止重复执行。 • 重试和退避：区分临时错误与永久错误。 • 通知策略：成功摘要、失败告警和人工接管。 • 审计：谁创建、何时运行、调用了什么工具。
自动化任务不应复用交互会话中的临时无限授权。无人值守入口应使用更窄的工具集合和单独的凭据。
20. 多模型与模型网关
[官方] WorkBuddy 提供模型配置；移动端也可选择模型。
模型层通常包括：
• 模型目录与可用区域。 • 用户选择和任务级覆盖。 • 企业允许列表。 • 上下文窗口、工具调用和多模态能力匹配。 • 限流、重试、Fallback。 • 用量、积分和成本核算。 • 数据驻留和隐私策略。
路由不应只看价格。一个任务可能需要：
• 强推理模型负责规划。 • 快速模型负责分类、抽取和摘要。 • 视觉模型理解截图或设计稿。 • 本地 Whisper 处理音频。 • 专用代码模型执行开发任务。
21. 企业版治理
[官方文档导航] 企业后台覆盖：企业智能体、席位和管理员、企业微信/飞书、研效度量、模型管理、知识库、Playbook、Skill、专家、自定义指令、Connector、IP 白名单和日志。
可将企业治理分为五层：
企业部署最容易犯的错误，是只管理模型账号而不管理 Agent 的行动能力。Agent 风险主要来自“它能做什么”，而不仅是“它能看到什么”。
22. 可观测性与评测
22.1 Trace
一次任务需要统一 Trace 串联：
用户请求 → Prompt 构建 → 模型调用 → 工具审批 → 工具执行→ MCP/Connector → Artifact → 最终回复建议记录：
• task/session/turn/message/tool_call ID。 • 模型、延迟、Token、费用、重试。 • 工具参数摘要、结果状态和错误分类。 • 权限决策及策略来源。 • 上下文压缩次数和摘要版本。 • 子 Agent 拆分、等待和汇总时间。 • 用户中断、纠偏和最终采纳情况。
公开类型中存在 Trace、Turn Context、Tool Telemetry、MCP 调用埋点、Event Loop Lag Sampler 和 Runtime Ready Reporter，说明可观测性已深入运行时。
22.2 评测指标
不要只用聊天问答基准评估 WorkBuddy。Agent 的核心是端到端任务交付和行动安全。
23. 性能工程
公开产物透露的优化手段包括：
• WorkBuddy 专用 lite-wbbundle。• 移除不使用的 TUI/LSP/update 等模块。 • ESM 动态加载。 • 独立 lazy chunks。 • sidecar 预热池。 • 启动阶段 profile。 • Runtime Ready 端口上报。 • Event Loop Lag 诊断。 • 版本化 chunk 预加载与升级竞态保护。
性能排查顺序建议：
1. 区分 UI 慢、sidecar 启动慢、模型慢和工具慢。 2. 记录 bootstrap、module load、component registration、ready 各阶段。 3. 检查首次 Skill/MCP 枚举是否阻塞首轮。 4. 检查大目录扫描和 Git 状态。 5. 检查上下文构建是否重复读取大文件。 6. 检查 Tool Result 是否过大导致模型输入膨胀。 7. 检查多个预热进程的总内存，而非只看单进程。
24. 威胁模型
25. 面向研发团队的最佳实践
25.1 任务编写
高质量任务应包含：
目标：最终要交付什么范围：允许读取和修改哪些资源约束：格式、技术栈、期限、不可做事项验收：如何验证完成参考：附件、知识库、示例或链接25.2 权限设置
• 默认使用最小权限。 • 高风险动作逐次确认。 • 长期自动化使用专门服务身份。 • 只给 Connector 必需的 OAuth Scope。 • 定期清理旧 Skill、MCP 和授权。
25.3 Skill 开发
• 单一职责，名称和触发条件清晰。 • 把确定性逻辑放进脚本，把判断留给模型。 • 输出结构化结果，避免巨大日志。 • 提供失败恢复和验证步骤。 • 声明系统依赖、网络访问和写入范围。 • 用固定样例做回归评测。
25.4 多 Agent
• 只并行真正独立的子任务。 • 每个 Agent 有明确输入、输出和退出条件。 • 设置并发与预算上限。 • 使用 Worktree 或独立产物目录。 • 由一个主 Agent 负责去重、冲突处理和验收。
25.5 企业接入
• 先做只读知识场景，再开放写操作。 • 先接低风险 Connector，再接核心生产系统。 • 建立事故响应、撤权和日志取证流程。 • 将安全评测纳入 Skill/Playbook 发布门禁。 • 区分个人实验空间与企业受管空间。
26. 常见问题与解决方案
26.1 Agent 一直执行但不结束
可能原因：完成条件不清、工具返回噪声、循环调用或网页内容诱导。
解决：设置最大回合/工具次数；定义验收标准；启用 Loop Guard；要求每轮更新计划；对重复参数调用熔断。
26.2 工具明明已安装，模型却看不到
可能原因：宿主白名单、平台能力、企业策略、Skill 未加载、MCP 未连接或 Bundle 不包含。
解决：按“注册 → 连接 → 枚举 → 过滤 → 模型可见”逐层检查，不要只看安装状态。
26.3 MCP/Connector OAuth 后仍不可用
检查回调是否完成、Token Scope、代理和证书、服务器连接状态、工具过滤器以及组织 ACL。必要时删除连接后重新授权，但先保留诊断日志。
26.4 桌面端首次任务很慢
区分客户端启动、sidecar 冷启动、模型首 Token 和工具初始化。确认是否命中 lite-wb、是否预热成功、MCP 是否阻塞枚举、大目录是否被扫描。
26.5 文件修改被沙箱拒绝
检查真实路径是否经过符号链接落到工作区外、工作目录配置、企业安全中心规则和受保护目录。不要通过关闭全部沙箱规避，应仅增加必要的 allowWrite 路径。
26.6 多 Agent 修改互相覆盖
为每个 Agent 使用独立 Worktree/分支；避免共享生成目录；约定接口后再并行；合并前运行测试和冲突检查。
26.7 上下文越长效果越差
删除重复附件；把大文件改为按需检索；压缩早期工具日志；将稳定事实写入项目规则或 Memory；把不同目标拆成独立任务。
26.8 自动化重复执行
为每次触发生成业务幂等键；持久化执行状态；区分“请求超时”和“执行失败”；重试前查询目标系统是否已完成动作。
26.9 Artifact 无法公开或分享
检查文件大小、类型、内容审核、组织发布策略和公开权限。互联网公开应与组织内分享使用不同的策略与确认界面。
26.10 WorkBuddy 是否完全基于 CodeBuddy Code
不能这样下结论。公开发布物证明 WorkBuddy Desktop 会启动 CodeBuddy 的专用 lite-wb Agent Runtime，并复用其会话、工具、MCP、沙箱等能力；但 WorkBuddy 还有独立的桌面宿主、产品 UI、workbuddy-server、云服务、移动端和企业控制面，这些并不等于 CodeBuddy CLI。
27. 二次开发参考架构
若企业要构建类似系统，推荐拆分为：
apps/ desktop/ # 桌面宿主与 UI web-admin/ # 企业控制台 mobile/ # 移动控制端services/ task-service/ # 任务与会话元数据 agent-runtime/ # Agent Loop、Context、Session model-gateway/ # 多模型、费用、限流 connector-gateway/ # MCP、OAuth、业务连接器 artifact-service/ # 上传、分享、发布 knowledge-service/ # RAG、资料库、权限 automation-service/ # 调度、重试、幂等 policy-service/ # 企业策略与审批runtime/ sandbox/ # 文件、进程、网络隔离 skills/ # Skill 加载和执行 tools/ # 内置工具 observability/ # Trace、Metric、Audit关键原则：
• 产品控制面与执行数据面分离。 • 模型无权绕过 ToolManager 和 Policy Engine。 • 本地执行使用独立进程和强沙箱。 • 每次行动都能关联到用户、会话、策略和 Trace。 • 接口先结构化，再考虑 UI 呈现。 • 功能开关和 Host Capability 是跨端复用的基础。
28. 学习与验证路线
阶段一：产品使用
1. 创建一个研究任务。 2. 上传附件并生成文档 Artifact。 3. 安装一个只读 Skill。 4. 连接一个测试 Connector。 5. 在移动端查看并继续任务。
阶段二：Agent 工程
1. 理解 Tool Call、MCP、RAG 和 Context Compact。 2. 编写一个只读 Skill。 3. 编写一个本地 MCP Server。 4. 观察权限确认和失败恢复。 5. 用 Trace 还原一次完整任务。
阶段三：企业治理
1. 建立模型、Skill 和 Connector 白名单。 2. 配置最小权限和日志保留。 3. 设计 Prompt Injection 测试集。 4. 对自动化做幂等和熔断演练。 5. 评估端到端成功率、成本与安全误拦率。
29. 公开源码与发布产物证据索引
29.1 官方产品与文档
• 国内官网： https://www.workbuddy.cn/• 国际官网： https://www.workbuddy.ai/• 官方快速开始： https://www.workbuddy.cn/docs/workbuddy/Quickstart• 本文检查到的官方文档构建时间： 2026-10-10 19:35:30• 官方文档构建 Git Commit： 58cb23ac03e• 文档框架：VitePress 2.0.0-alpha.20
29.2 官网公开构建资产
• 主构建资产： https://assets.workbuddy.cn/web/workbuddy/f4728a12fe9cfe5a34da6b2fa827614041c84386/assets/index-C9SH9Q7f.js• 国内首页产品块： https://assets.workbuddy.cn/web/workbuddy/f4728a12fe9cfe5a34da6b2fa827614041c84386/assets/index-BWxj-RqN.js• 下载与导航模块： https://assets.workbuddy.cn/web/workbuddy/f4728a12fe9cfe5a34da6b2fa827614041c84386/assets/index-DGgYmJhr.js
29.3 CodeBuddy Code npm 发布物
分析版本：
@tencent-ai/codebuddy-code@2.164.0重点文件：
bin/codebuddybin/codebuddy-lowmemdist/codebuddy-lite-wb.mjsdist-server/types/node/runtime/host-detection.d.tsdist-server/types/node/server/tool-presets.d.tsdist-server/types/node/mcp/mcp-server-manager.d.tsdist-server/types/node/sandbox-cli/*dist-server/types/node/bash-sandbox/*dist-server/types/node/acp/*dist-server/types/node/agent/*dist-server/types/node/tools/*可复核命令：
npm view @tencent-ai/codebuddy-code versionnpm pack @tencent-ai/codebuddy-code@2.164.0rg -n -i 'workbuddy|lite-wb|workbuddy-server' package/bin package/dist-server/types30. 最终结论
腾讯 WorkBuddy 的关键价值不是简单增加更多入口，而是把 Code Agent 已验证的 Harness 能力扩展到通用办公：任务成为主对象，模型负责推理，ToolManager 和 Policy 负责约束行动，Skills/Experts 负责复用方法，Connectors/MCP 负责连接业务系统，Sandbox 负责本地安全，Artifact 和资料库负责交付与沉淀，多端与自动化负责持续触达，企业控制面负责规模化治理。
公开发布物进一步证明，WorkBuddy 与 CodeBuddy Runtime 之间存在明确的工程复用关系：桌面宿主通过 sidecar 启动专用 lite-wb bundle，使用 Host Gate、ACP、MCP、沙箱、会话和工具体系承载 Agent 执行。与此同时，WorkBuddy 仍拥有大量独立的产品层与云端能力，不能被简化为 CodeBuddy CLI 的 UI 包装。
判断这类产品是否成熟，应重点观察四个问题：能否稳定完成长任务、能否控制行动风险、能否在多端和故障后恢复、能否被企业持续治理。WorkBuddy 已公开的产品矩阵和发布产物表明，其工程重点正围绕这四个方向展开。
