WorkBuddy 高级使用手册

发布日期：2026/10/20 11:32:51      浏览量：

WorkBuddy 高级使用手册

从「会提问」到「会配置」——把 WorkBuddy 用成一个工作平台

第一章 认知升级：从「提问」到「下任务」

1.1 三层能力模型

理解 WorkBuddy 的正确方式，是把它的能力拆成三层。

交互层决定了你怎么下任务：自然语言指令、三种工作模式、@ 引用与附件、多任务并行。扩展层决定了能力从哪里来：技能、专家与专家团、连接器、MCP 服务、插件包、资料库与记忆。执行层是它真的动手做的部分：读写本地文件、运行命令脚本、生成文档表格 PPT、联网检索、内置浏览器预览，最后交付可验收的产物。

三层同时生效，缺一层都跑不完整：只有交互层，它只是个聊天工具；不配扩展层，复杂任务全靠现场发挥；不理解执行层，你就不知道该给它什么工作空间、该在哪一步拦截风险。

1.2 工作界面：三块主区域同屏闭环

WorkBuddy 的界面由四个区域组成。顶部是工具栏（关于、编辑、窗口、检查更新）；左侧是侧边栏，集中了新建任务、助理、项目、专家·技能·连接器、自动化、资料库等一级入口，下方是任务与空间列表，支持搜索与筛选；中间是对话区，含任务标题栏、消息列表和输入框；右侧是结果区，可在概览（工作空间文件）、浏览器、变更、产物四类视图间切换。

输入框底部的几个常驻控件值得记住：权限状态按钮（默认显示「默认权限」）、工作空间选择、模式切换和模型选择。发起任务前扫一眼这四个控件，是最简单的风险习惯。

几个提升效率的界面操作：

l 全局搜索：Ctrl+K 唤起，覆盖任务、空间、产物三类对象，键盘上下键选择、回车打开；

l 消息队列：模型正在执行时也可以继续发消息，消息先进队列，可编辑、删除、拖动排序，不打断当前输出；

l 引用追问：选中回复中的文本、悬停表格或组件点「添加到对话」，可附批注，让修改精准落在指定位置；

l 链接打开方式：设置 → 通用 → 链接打开方式，可选按需（默认）、始终内置、始终外部。

1.3 三种工作模式：两问定模式

WorkBuddy 提供三种工作模式，选择逻辑如下。第一问：需要 AI 真的动手执行吗？不需要就用「仅问答 Ask」——只回答、不动文件。需要就进入第二问：「怎么做」比「做出来」更值得先讨论吗？是则用「计划 Plan」——先补齐信息、给出可审阅的方案，确认后再执行；否则直接用「默认 Agent」模式。

Plan 模式适合四种场景：任务要拆多步才能完成、需求模糊有多种解法、关键前提未确定、产出成本高不想白跑。开启方式是在输入框左侧「+」菜单中打开「计划」或「仅问答」，两者互斥，关闭后自动回到默认模式。

1.4 高级提示词方法

同一个模型，任务描述的质量决定结果的上限。四条方法来自大量实测反馈：

第一，三要素公式：做什么 + 有什么 + 怎么样。「帮我把上次的会议纪要整理一下」是反面示范；「把 D:/会议纪要/0320产品评审.docx 里的会议纪要整理成清单，包含每个议题的结论、责任人与截止日期，标记有争议未决事项，用表格输出」才是可执行的任务。

第二，小步快跑，一次搞定一件事。「把这份 50 页报告读一遍、写 PPT、发给领导」一口气丢过去，往往每一环都不满意。拆成三轮：先提炼 5 条核心结论（附页码），再基于结论写大纲，最后扩展成 PPT 内容。每一步都能先确认方向，偏了就拉回来。

第三，不满意就调整，别一轮定生死。直接指出问题（「太长」「第三段逻辑不通，重写」）、换个角度重述需求、补充限制条件、切换角色视角，都是有效的调整手段。

第四，给样例比给要求管用。语言难以精确描述「感觉」时，把一个你满意的样本给它，说「照这个来」，输出会稳定得多。

第二章 权限与安全：高级使用的底盘

2.1 两种权限模式

权限入口位于输入框底部，是常驻的权限状态按钮。两种模式的选择逻辑如下。

默认权限以工作空间为边界：工作空间内的常规文件操作直接执行；一旦涉及四类高风险操作，它会停下来请求确认——写入受保护或敏感路径（避免覆盖密钥凭据）、删除受保护文件或批量删除、执行脚本命令或外部程序、网络访问与敏感能力。

完全访问权限则关闭二次确认，且是全局开关：开启后当前客户端内所有已存在任务和后续新建任务统一生效，不跨设备。它只适合任务完全可信、环境隔离（Docker、虚拟机、一次性目录）、结果可恢复的场景；处理生产资料、客户资料、唯一副本时不要开。用完立即关回去。

对比项	默认权限	完全访问权限
文件访问范围	沙箱约束内，越界需请求允许	计算机上任意位置
删除 / 修改文件	需逐次确认	多数直接执行
终端命令	系统级命令需确认	可直接运行、安装软件
生效范围	按操作逐次生效	全局，所有任务统一生效
适用场景	日常办公、首次处理某类任务	隔离环境中反复运行可信脚本

收到确认提示时，先看三件事：操作内容是什么、影响范围是否在工作空间内、这一步是否必需。拿不准就取消，让 WorkBuddy 先列文件清单、生成预览或改存到工作空间内。

2.2 安全中心：细粒度管控

权限模式决定整体访问范围，安全中心在此之下做细粒度控制。

几个值得专门配置的点：

l 文件安全：按文件路径配置三态规则，读取、写入、删除可分别设为允许、询问或拒绝；

l 命令安全：按命令前缀配置允许、询问或禁止规则；

l 网络安全：远程 HTTP 请求默认询问，本地请求默认放行，域名白名单内的访问不受限制；

l 工具管控：逐个启用或禁用 Agent 可调用的产品工具和 MCP 服务，禁用后执行前拦截，对本机所有 Agent 生效；

l 删除保护与批量删除审批：删除优先移入回收站；一次删除达到设定数量（默认 50 个）时需要审批。

2.3 自动备份与敏感保护

自动备份默认开启：Agent 修改已有文件前自动生成快照，同一文件在一轮对话内只在首次修改前备份一次；所有会话共享 3000 MB 备份空间，不足时按时间清理最早的备份。开启后文件修改可直接进行、不再逐个弹窗——这是「效率与安全兼得」的典型设计。注意它不替代你自己的重要文件备份。

敏感保护默认开启，用内置规则库识别密钥、凭证等信息：输入侧命中时可选允许访问、允许并加密访问（推荐）或禁止；输出侧在执行命令、联网搜索前检测，命中后弹窗确认。你命中后选择「允许并加密」的明文会生成密文保存，后续以密文参与上下文流转、输出时自动还原。

2.4 风险守则

五条守则，覆盖绝大多数风险场景：为任务准备独立工作空间，把要处理的文件放同一个文件夹；重要文件提前备份；日常保持默认权限；看懂确认弹窗再继续（重点看操作类型、路径、影响范围）；完全访问开关用完即关。

第三章 能力扩展体系

3.1 六类能力的关系

WorkBuddy 的扩展体系由六类能力构成，它们回答的是不同的问题。

技能让 AI 会做某件事；专家是某个领域的专业角色；专家团是多角色分工协作；连接器对接外部服务的账号；MCP 是标准化的外部工具协议；插件则是把一整组能力打包分发。它们是并集而非二选一——一个任务里可以同时挂载技能、召唤专家、调用连接器。

3.2 技能（Skill）

技能封装一组可执行的脚本与工作流。安装有三个入口：上传技能（导入本地技能包）、查找技能（输入任务描述自动查找）、创建技能（描述需求自动创建）。已安装技能可随时关闭或重新启用，无需卸载——关闭只是暂停模型调用，文件与配置保留；开关状态记录在用户全局配置中，多端同步。

两点提醒：仅启用当前任务所需的技能，减少误调用；技能可能将输入内容发往第三方，安装第三方技能前先看权限申请、来源与脚本内容，涉及文件删除、批量写入、资金类操作时先小范围验证。

3.3 专家与专家团

专家是「人设 + 方法论 + 工具链」的角色切换机制；专家团是「协作执行」机制——团长自动拆解任务、分配给多位专家并行执行、整合交付。

使用内置专家：在左侧边栏「专家·技能·连接器」中浏览卡片、查看擅长领域与任务示例，点击召唤后描述任务即可。常用专家支持搜索和置顶。

创建自己的专家（我的专家 → 创建专家）时，配置质量决定输出质量：

配置项	填写要点	避免
头像与显示名称	短角色名，如「文档评审官」	「专家1」「助手」
人设身份	是谁 + 背景，如「10 年后端工程师」	写成任务本身
擅长领域	写清边界，做什么、不做什么	「什么都行」
提示词	工作流程、输出格式与约束，能举例最好	只写「您是一个专家」

注意：专家名称创建后无法修改；删除专家无法恢复。专家本身不主动获取系统权限，仅在配备技能或 MCP 时才在你的授权下间接访问。成本提醒：专家团并行调用多位专家、多轮交互，积分消耗通常是单专家的 3-5 倍，召唤前先看积分余额。

3.4 连接器

连接器把外部服务接入工作流，当前已支持 QQ 邮箱、腾讯文档、腾讯乐享、腾讯会议、TAPD、腾讯网盘等，并支持自定义连接器（本质是安装自定义 MCP 服务）。

三种使用方式：在连接器页面点「去对话」直接发起；创建任务时通过输入框左下角「+」启用；任务执行中需要时，输入框上方会出现连接引导卡片，点击完成授权后任务自动继续，无需重新发起。

QQ 邮箱授权值得单独说明：扫码授权后 WorkBuddy 获得账号信息、读取近一个月邮件、代发邮件的权限（删除邮件为可选），可在邮箱 App 的「设置 - 账号 - 安全管理 - 应用授权」中随时撤销。

团队协作场景的关键区别：连接器分公共授权（管理员配置一次、全员共用票据）与个人授权（各自授权、票据仅存本地）；协作任务中个人授权连接器全部禁用，仅公共授权可用——开启协作前先确认项目已配好必要的公共授权连接器。

3.5 MCP：AI 的 USB 接口

MCP（Model Context Protocol）用于将外部工具和服务接入 WorkBuddy，支持上下文共享、工具调用、可组合工作流与数据控制。WorkBuddy 已把 MCP 配置做进界面，无需改配置文件也能接入，同时保留配置文件方式：

级别	适用场景	配置文件路径
用户级	配置一次，所有项目复用	~/.workbuddy/mcp.json
项目级	仅当前项目生效	＜项目目录＞/.workbuddy/mcp.json

选择原则：频繁跨项目使用的能力（如通知机器人）配用户级；仅特定项目需要的专属服务配项目级。

以企业微信机器人为例：在企微群里添加群机器人获取 WebHook URL，进入侧边栏「插件 → MCP 服务器 → 配置 MCP」，粘贴配置并替换 your-webhook-url 后保存。保存后看状态灯：绿色为连接成功，红色需检查配置内容、命令环境或地址。

最佳实践：公共能力配用户级、专属接入配项目级；从成熟示例起步；描述需求时说清通知对象、内容与是否需要 @。WebHook URL 是调用凭证，切勿泄露；配置失败优先检查 JSON 括号与引号。

3.6 插件：能力的打包分发

插件用于打包分发一组相关能力，一个插件可同时包含技能、MCP 连接、快捷指令（如输入 /周报 一键生成周报）、自动化规则（Hooks，在特定时机自动执行）和智能体。插件市场支持关键词搜索、一键安装；已安装插件可更新、启用、禁用。

3.7 怎么选：一句话判据

六类能力的选择判据：想让 AI 具备某种工具能力选技能；有明确的单点专业问题选专家；任务复杂需要多角色配合选专家团；要让 AI 读外部系统数据选连接器；要接入自建或第三方工具服务用 MCP；要把一组能力整体分发用插件。

组合使用的推荐顺序：先选角色（专家 / 专家团），再挂工具（技能 / 连接器），最后按需用插件整体分发。

第四章 上下文工程：记忆、项目、资料库

4.1 一次任务的上下文从哪里来

模型的输出质量，取决于上下文的质量。一次任务的上下文来源包括：任务描述与 @ 引用、上传的附件与截图、工作空间内的文件、项目指令（团队规则）、项目资料库（RAG 检索）、个人记忆、已挂载的技能与专家和连接器、会话历史与模型配置。

关键事实：每一轮对话都会把当前上下文完整发送给模型，上下文越大单轮消耗越大；默认 200K 窗口对绝大多数任务够用，开到 1M 不会让模型更聪明，只会让每轮消耗成倍增加。实践建议是：与其把一整份 50 页文档塞进去，不如先让它提炼要点，再基于要点推进——上下文窄一点，结果反而更准。

4.2 记忆：它记得你是谁

记忆功能从会话历史中提取事实信息、偏好习惯、人物关系与跟进事项，每晚整理当天会话，仅本人可见；后续对话自动注入相关记忆。记忆提取由 WorkBuddy 自费完成，不消耗积分。

管理入口在「设置 → 记忆」：可查看、通过对话方式增删（「记住我习惯用表格输出」）、一键清空或关闭功能；也支持从其他 AI 导入使用习惯（复制示例提示词到对方对话、把结果粘贴回来即可）。

提醒：记忆由模型自动抽取，可能存在概括偏差或时效性问题——依赖记忆做重要判断前先核验；涉及他人个人信息的内容，提交前确认已获授权。

4.3 项目：团队协作的阵地

项目把指令、连接器、专家、技能和资料统一组织起来，成员在项目中发起任务时这些共享配置自动注入，无需重复设置。项目配置包含：项目指令（对所有任务生效的全局规则）、连接器（公共授权与个人授权）、项目专家、项目技能。专家、技能、连接器的选择范围都是「项目配置 + 个人配置 + 全部可选」，项目配置置顶。

代码开发场景下，项目支持读取工作目录下的 .codebuddy/ 项目级配置，可提交版本控制随团队共享：

目录 / 文件	作用
.codebuddy/rules/	团队统一的代码规范与工作流约定
.codebuddy/agents/	项目专属 Agent 定义
.codebuddy/skills/	项目级技能（每个技能含 SKILL.md）
.codebuddy/commands/	自定义斜杠命令，/命令名 触发
.codebuddy/CODEBUDDY.md	项目级记忆：架构、约定、常用命令

优先级为「项目级 ＞ 用户级」，同名时项目级优先；与 CODEBUDDY.md、AGENTS.md 及用户级 ~/.codebuddy/ 配置兼容并存。

项目还提供：项目动态（与我有关 / 成员动态 / 自动化三类事件）、任务分享与任务流转（详见第六章）、项目资产库（默认 5 GB，依托腾讯网盘，成员手动上传或任务产物直接存入，以 RAG 形式注入任务上下文）。

4.4 资料库：人和 Agent 共同的产物存放地

资料库分「我的文档」（个人产出与收藏，仅自己可见）和「团队空间」（项目共享资料）两个区域。它的核心设计是 MD / CSV / HTML 三件套分工：MD 决定内容（方案、周报等叙事产物），CSV 存储数据（唯一数据源，由在线表格承载、多人可同时维护），HTML 负责表达（读取表格 ID 实时渲染图表与列表）。改内容改 MD、改数据改 CSV、改样子改 HTML，互不干扰、改一处处处生效。

工作闭环：把空间或文档「添加到任务」→ Agent 基于资料执行 → 成果保存回资料库。Agent 对 MD 文档的修改不直接覆盖原文，以待确认状态呈现，接受后才写入正文——AI 修改可审阅、可回退。做好的 HTML 页面还可以「发布为网站」，使用 workbuddy.link 域名，默认关闭、随时可关。

存储配额随会员版本：体验版 5 GB、标准版 10 GB、高级版 20 GB、旗舰版 50 GB。存储、目录组织、检索和手动编辑不消耗积分；AI 修订、按评论修订、HTML 划词修改等操作消耗积分，且按实际发起 AI 操作的人计费。

4.5 三种沉淀方式的分工

记忆、项目、资料库三者的分工：记忆管「谁记得你」，项目管「团队定什么规矩」，资料库管「文件与数据存在哪」。

沉淀闭环是：当天会话 → 夜间整理 → 记忆入库 → 下次任务自动注入 → 成果沉淀回资料库。团队协作的规矩放项目里，团队的文件放资料库里，两者都比单次会话耐久。

4.6 Worktree：并行任务互不干扰

工作空间内包含 Git 仓库时，两件事变得可行。

其一，分支显式化：新建任务页面显示当前检出分支，可直接切换；切换时若有未提交改动，可选择 Commit 到当前分支（默认，最安全）、Stash 变更或丢弃变更（需二次确认）。切换失败时工作区完整回滚，不留中间态。

其二，Worktree 并行任务：开启 Worktree 开关后，系统在 ~/WorkBuddy/Worktrees 目录下创建完全隔离的工作目录，基于所选 Base Branch 的 HEAD 自动新建任务分支，命名格式为 workbuddy/{基础分支}-{8位随机哈希}（如 workbuddy/main-a3f8c2b1），与手动创建的分支天然区分。文件系统层面完全隔离，多个 Agent 的改动互不污染。

注意三条边界：Base Branch 在任务创建后锁定；任务分支在任务生命周期内不可切换；达到 25 个 Worktree 时创建新任务会提示清理，达到 50 个时必须选择清理范围（超过 7 / 15 / 30 天）后才能继续创建。轻量改动、单点查询用普通任务即可，别为了炫技开 Worktree。

第五章 自动化与远程执行

5.1 自动化：按计划自己干活

自动化让 WorkBuddy 在指定时间自动执行周期性任务（每日简报、周报汇总、定时数据整理）。

创建自动化任务需要六项配置：名称、提示词（任务目标与输出要求）、工作空间（默认自动分配 automation-xxxx）、权限模式、模型与技能（含专家、连接器）、定时规则。

定时规则的重点：支持每周多天、每月多天，同一任务的多个执行日期合并在一条规则里，例如「每周一、三、五 09:00」一条即可，不要拆成多个任务。

结果推送两选一（可都不开）：推送到 WorkBuddy 小程序，任务完成后自动发送，手机上第一时间查看；推送到企业微信 bot，支持复用企微助理的 bot 通道或注册独立的自动化通知 bot。

三条纪律：新建任务后先以低频率试运行，确认理解与执行结果符合预期再放大频率；无人值守下涉及文件写入、删除、资金操作的提示词要审慎设置；对结果中涉及文件改动、数据变更、对外发送的部分保留可追溯的日志。不想从零写提示词，直接用任务模板（新闻推送、周报生成、体检预约、学习计划等）改一改就能用。

5.2 助理：手机遥控电脑

助理是远程控制功能：在手机的微信、企业微信、QQ、钉钉、飞书上发一条消息，电脑上的 WorkBuddy 自动执行，结果回到手机。

安全边界有三层：绑定身份（配置关联账号，支持换绑）、来源校验（每条远程指令多层校验）、高风险任务确认（文件删除、系统配置修改、批准命令执行需确认后执行）。

与普通任务的关键差异：工作目录固定使用助理专属文件夹（不支持修改）；仅一个会话，所有远程指令集中处理；保留完整对话历史，不可清空。建议：本地操作优先用主界面普通任务，需要远程触发或统一查看记录时才用助理。

两个前提别忘：电脑需保持开机并运行 WorkBuddy；移动端下发「上传桌面文件」类指令通常受设备权限限制，改为在本机侧明确指定文件路径更可靠。

5.3 我的邮箱：给 AI 的工作信箱

WorkBuddy 为每个用户创建专属邮箱（形如 xxx.agent@agent.qq.com），由 Agent Mail 提供底层服务。定位一句话：收件在界面看，干活在对话里。

与其他邮箱工具相比的三个优势：一次开通多端可用、身份不随设备丢失；端内查看邮件不消耗 Token（正文不进对话上下文）；新邮件在端内通知中心提醒，可一键添加到对话处理。

开通需要手动完成（同意补充协议，手机号注册再加短信验证码），两个入口：进入「我的邮箱」按提示开通；或在对话里第一次让 AI 发邮件时内联弹出开通卡片，不打断当前任务。

对外动作的硬约束：发邮件、回复、转发统一在对话中完成，由 WorkBuddy 起草，预填充后不自动发送——必须你确认并点发送。什么都没补就发送，它会反问「你想怎么回 / 发给谁」。邮箱绑定账号实例，个人版与企业版相互隔离；附件经过安全扫描，邮件内容仅作为输入数据处理，不会覆盖安全规则。

5.4 企业智能体：云端 Agent 运行平台

面向企业与开发场景，企业智能体提供完整的云端 Agent 生命周期管理。

三个核心概念：Runtime 是独立运行的云端沙箱实例（完整 Linux 文件系统与终端）；Manifest 是声明式 JSON 配置（id、name、system_prompt、skills、mcp、subagents、workspaces、secrets、envs）；Session 是每位用户的独立会话，拥有独立对话历史与文件存储，超过 10 分钟无访问自动休眠、再次访问自动唤醒。

配套能力：渠道接入（企微 AIBot、QQ 机器人、飞书、钉钉，每条记录对应一个 Bot 与 Session 的绑定）；凭据管理（加密存储，Agent 调用 MCP、技能或外部 API 时由代理层解密注入，不在代码或配置中明文暴露）；Agent 评测（标准化评测任务量化回答质量，启动评测消耗个人积分）；版本管理与 Test Run。

第六章 交付与协作

6.1 结果区与产物

任务执行中，右侧结果区提供四类视图：概览（工作空间文件树）、浏览器（网页与本地 Web 应用预览，支持多标签、Ctrl+T 新建）、变更（本次任务的文件修改差异，接受结果前先在这里核对）、产物（任务生成的文件与交付物，右键可打开所在文件夹）。

内置浏览器还有几个进阶用法：网址栏可直接输入关键词搜索；登录态按账号隔离并持久复用，切会话、新建标签都不丢失；「更多」菜单提供页面查找、缩放、设备调试工具栏（一键切换手机 / 平板 / 桌面视口）与截图复制。

6.2 四条交付出口与任务流转

产物的出口不止一个。

分享任务生成公开链接发到任意渠道；上传云端支持我的云端网盘、腾讯文档、ima 知识库、乐享知识库；保存到资料库进入目录树长期沉淀；发布为网站让任何获得链接的人可以访问。

任务流转则是把产出物连同上下文一起移交：系统自动打包任务产物、进度摘要（自动生成的执行总结）、自定义字段（标题、处理人、状态、截止日期，可编辑）与附加附件，接收方基于完整上下文继续推进，无需重复沟通背景。

6.3 独立文件浏览器：人机双写

把 WorkBuddy 设为文件打开方式后，在文件资源管理器中双击或右键「打开方式」即可进入独立文件窗口：一个窗口打开 Word、Excel、PPT、PDF、Markdown、HTML、图片、音频，多标签切换，窗口右侧内置 AI 对话栏——一边看文件，一边让 AI 总结、改写、润色，结果直接落到文档里。

使用要点：对话跟着文件标签走，历史对话关掉再开还在；AI 生成的新文件默认与原文件同目录；Office 文档编辑需登录，Markdown 不登录也能编辑；保存方式按类型区分（Office 手动 Ctrl+S，Markdown 自动保存，HTML 点「编辑 / 退出编辑」）。文件被占用时仅可查看；「文件在别处发生了修改」时优先选另存为，避免覆盖他人改动。

6.4 设计创意：WorkBuddy 与 Ardot

设计创意模式集成了腾讯自研设计平台 Ardot 画布：对话一句话生成 UI、PPT、海报，实时对话修改，可跳转 Ardot 精修，满意后一键生成应用代码。

工作流三步走：对话快速出稿（选风格模板，内置 TDesign、Apple、Notion、Spotify 等，或按设计类型切换专属模板）→ 跳转 Ardot 精修（点画布顶部「用浏览器打开进行编辑」，所见即所得拖拽调整，双向实时同步）→ 回到 WorkBuddy 生成代码（说「将当前画布中的设计稿生成应用」，可继续「用 React 重写」「加 dark mode」）。PPT 类产物可从 Ardot 导出 PPTX 或 PDF。

图片素材不足时可在「色块占位」（快速确认版式，稍后手动替换）与「AI 生图」（一次出稿即成品）之间切换。

第七章 成本与性能调优

7.1 积分机制：消耗由什么决定

所有对话相关请求均消耗积分，消耗量由两个因素决定：模型 Token 定价（高级模型单价更高）与任务复杂度（长代码分析、多轮对话、知识库检索消耗更多；专家团约为单专家的 3-5 倍）。

扣减顺序：优先使用最先到期的积分；到期时间相同时先扣基础积分、再扣赠送积分。积分按月发放，当月有效、不累积结转；赠送部分自到账日起 1 个月内有效。会员到期后额度降为体验版，加量包可继续使用至到期或耗尽。

一个容易忽略的规则——循环执行确认：检测到任务可能陷入循环时，WorkBuddy 会在工具调用执行前暂停确认。选「继续执行」照常计费；选「终止请求」则本次调用不执行，已产生但尚未生成最终回答的消耗进入退费评估（普通手动取消不进入退费评估，这是一个例外通道）。

7.2 模型选择与自定义接入

三档模型模式按任务复杂度选择：快速模式响应最快、消耗最低，适合简单明确的任务；均衡模式效果与速度兼顾，不确定就用它；极致模式响应稍慢、消耗更高，但复杂任务下结果更稳定。思考强度默认即可；对话中途切换模型在下一轮生效，频繁切换可能降低性能、增加消耗。

内置模型的擅长方向可作参考：MiniMax 擅长 Excel 处理、数据分析与 PPT 生成；智谱 GLM 擅长多步骤长流程复杂任务；Kimi 擅长截图分析、图片转文档等视觉任务；DeepSeek 响应快、成本低，适合日常问答与文案；腾讯混元擅长中文写作与会议纪要。

自定义模型支持五种接入：提供商接入（选厂商自动填充，只补 API Key）、腾讯云 Token Plan、Coding Plan、Ollama 本地部署（数据不出本机、零成本试用、离线可用，默认端口 11434）、自定义 API。配置（含 API Key）仅保存在本地 workbuddy/models.json，不上传云端；自定义模型产生的费用由你向第三方支付。

7.3 上下文窗口与 Max 模式

这两个设置直接影响长对话的成本曲线：

l 上下文窗口默认 200K，适用于绝大多数任务。只有在处理超长文档、或需要模型完整记住大量历史内容时才调大；

l Max 模式默认关闭：关闭时系统在合适时机自动触发上下文压缩，减少长对话中重复传输的上下文；开启后全程完整保留上下文、细节一点不丢，代价是积分消耗明显更快。保持关闭，仅超长上下文需求时开启。

第八章 排障与运维

8.1 诊断工具与日志

客户端异常（无法登录、连接失败、行为异常）时，先跑内置诊断工具：顶部「帮助 → 诊断工具 → 开始检测」，逐项检查网络（API 连通性、DNS、端口、代理、丢包率）、系统资源（磁盘低于 1 GB 报失败、低于 3 GB 告警、内存使用）、安全软件（EDR / 杀毒识别）、环境信息与崩溃日志。检测完成后自动生成脱敏报告（IP 仅保留前两段、用户名替换），保留最近 10 份，提交反馈时一并提供。

日志位置：顶部「帮助 → 打开日志文件夹 / 日志目录」。安全软件（火绒、360、电脑管家）误拦截是登录失败的常见原因，可临时退出后重试；Windows 升级重启后工作空间「消失」，到 C:\\Users\\＜用户名＞\\workbuddy（Mac 为 /Users/用户名/WorkBuddy）目录下找以日期或自定义名命名的文件夹即可找回。

8.2 常见问题速查

现象	首选处理
回复乱码、胡乱输出或长时间无响应	先切换模型；拆小任务；记录错误码与网络状况
任务卡住没有响应	停止任务 → 切换模型 → 重新执行历史任务
无法读取图片 / PDF / Excel	切换到支持图片或文档输入的模型；安装文档处理类技能
生成的文件打不开	下达任务时明确指定输出格式（Word / Excel / PDF）
Bot 已配置但不回复	确认连接状态在线；切换模型再测；微信场景断开重连
更新提示「安装目录下存在用户项目目录」	打开安装目录，移走个人文件与对话文件夹，仅保留系统文件夹后更新
升级后原工作空间消失	到用户目录下的 workbuddy 文件夹找回对应日期目录

通用原则：优先保留证据（错误码、截图、系统版本、网络环境、发生时间）；先做最小化验证（切模型、重连、拆任务）；重要文件先备份。

8.3 数据安全架构

WorkBuddy 的安全体系是三层纵深防御加通信保障。

技术防御层做沙箱隔离与权限控制（命令沙箱、文件系统隔离、防沙箱逃逸、默认只读启动）；管理管控层提供企业级统一管控（SSO、Credit 额度按部门角色设置、IP 白名单、精细化工具调用权限）；合规审计层覆盖 Skill 安全审计、本地安全检查与法规合规。通信侧为 HTTPS 全链路加密（TLS 1.2/1.3）、IM 内置 WebSocket 通道（不在防火墙开额外端口）、安全通信网关鉴权；VPC 专享版提供物理级隔离与数据主权。数据在本地执行处理、不上传云端；服务端仅处理数据片段，用后即弃、不保存、不用于模型训练。

附录

A.1  快捷键速查

快捷键	作用
Ctrl+K	全局搜索（任务 / 空间 / 产物）
Ctrl+Shift+E	展开左侧列表并定位到当前任务
Ctrl+T	内置浏览器新建标签页
Ctrl+F	对话区搜对话内容；焦点在网页内时搜页面
Ctrl+W	关闭文件浏览器当前标签
↑ / ↓ + Enter	列表或搜索结果中切换与打开
Esc	关闭弹窗、取消编辑

（macOS 将 Ctrl 换为 Cmd。）

A.2 配置与数据路径速查

用途	路径
用户级 MCP 配置	~/.workbuddy/mcp.json
自定义模型配置	workbuddy/models.json（设置 → 模型 可视化管理）
项目级 MCP / 规则 / 技能 / 命令	＜项目＞/.codebuddy/ 与 ＜项目＞/.workbuddy/mcp.json
默认工作空间根目录	Windows：C:\\Users\\＜用户名＞\\workbuddy；Mac：/Users/用户名/WorkBuddy
Worktree 工作目录	~/WorkBuddy/Worktrees（分支前缀 workbuddy/）
诊断报告	日志目录 logs/self-check/（保留最近 10 份）
已归档任务与已分享文件	头像 → 设置 → 数据管理

A.3 高级用法自检清单

逐条对照，全部打勾说明你已经在用「平台」，而不是「聊天框」：

1. 每类任务有独立工作空间，重要文件处理前有备份；

2. 日常保持默认权限，完全访问只在隔离环境短时开启；

3. 重复性工作已配置自动化，且先低频试运行过；

4. 常用专业角色已沉淀为自定义专家，而不是每次重新描述；

5. 跨项目复用的外部服务配了用户级 MCP，团队规矩写在项目指令里；

6. 产物有固定去向（资料库 / 云端 / 发布），不散落在会话里；

7. 模型档位与任务复杂度匹配，长对话不滥用 Max 模式与超大窗口；

8. 团队协作任务使用公共授权连接器，个人票据不出本机；

9. 出问题时先跑诊断工具、先切模型，而不是删掉重来。