WorkBuddy 使用指南

要解决的问题

WorkBuddy 是一个功能复杂的 AI 工作台，集成了连接器、专家、自动化、Teams 协作、人机双写等多个模块。用户在实际使用中经常遇到以下具体困惑：

• 配置与连接故障：连接器报错（如错误码 1001、3002）、环境不兼容、代理设置问题，导致工具无法正常调用。
• 功能使用模糊：不知道如何创建专家、设置自动化任务、使用人机双写编辑文档，或操作资料库和设计创意功能。
• 新手入门障碍：首次使用时缺乏清晰路径，容易迷失在大量功能中，不知从何开始配置。
• AI 行为不理想：AI 回答不准、格式错误、答非所问，需要个性化调教但不知方法。
• 故障排查低效：遇到问题时尝试多种方法仍无效，缺乏系统化的诊断流程。

技能如何工作

本指南作为 WorkBuddy 的参考手册，通过以下核心能力和关键步骤帮助用户解决问题：

核心能力：分层检索与结构化知识

• 三层检索体系：从 references/05-quick-cards.md 的快速卡入手，逐步深入深度文档（如 references/troubleshooting.md），最后参考官方文档。避免新手直接面对冗长文档。
• 关键词速查表：将自然语言问题映射到技术关键词和对应文档，例如“连不上”对应 MCP失败，自动匹配到 references/02-connector-troubleshooting.md。
• 诊断工具集成：提供 scripts/check_env.py 一键检测环境状态（代理、连接器、专家），支持 --fix 自动修复 JSON 和代理配置，--collect-logs 导出脱敏快照用于深度分析。
• 触发规则自动匹配：在对话中提到 WorkBuddy 相关问题（如功能名、报错、配置）时，手册自动加载，无需手动激活。覆盖 14 种场景，包括连接器故障、专家创建、自动化设置等。

关键步骤：从问题到解决

1. 问题识别与匹配：用户描述问题（如“连接器报错 401”），系统根据触发规则（如场景 2：描述 WorkBuddy 报错）自动加载相关参考文件。
2. 分步排查：遵循修复路径分级——例如在 references/02-connector-troubleshooting.md 中，先检查一级修复（常见原因：代理未启动），再尝试二级修复（检查 API 凭证），最后验证（运行 check_env.py）。
3. 个性化配置：通过 Soul.md 系统定义 AI 行为，采用聊天式分步引导（每次只问一个问题）：

- 定义核心性格、说话方式、工作原则等六条规矩。
- 例如，设置“禁用客套话”以减少 AI 味，或“一次到位不反复确认”提升效率。

1. 高级场景支持：

- 自动化任务：参考 references/04-automation-patterns.md 中的 RRULE 模板库，设置定时任务（如每日备份）。
- 团队协作：使用 references/13-teams-collaboration.md 配置项目看板和任务流转。
- 多端同步：在 references/10-interaction-modes.md 中查看手机远程电脑、锁屏远程等操作。

1. 官方文档检索：当参考文件不足时，使用 WebFetch 主动查询 https://www.codebuddy.cn/docs/workbuddy/Overview 等链接，获取最新信息。

适用边界与注意点

本指南设计为只读参考，专注于使用指导，以下情况不适用：

• 纯编程问题：如写函数、调 bug，应直接让 AI 处理代码，不通过本手册。
• 修改 skill 文件本身：需退出本 skill，直接要求 AI 编辑文件。
• 版本更新日志细节：文档可能滞后，建议用 WebFetch 查官方 Changelog。
• 特定连接器 API 细节：连接器文档由 MCP 工具自描述，可直接询问 AI。
• 不可复现的一次性故障：运行 check_env.py 获取诊断报告，提交给 AI 分析。

边界模糊问题处理：例如用户说“WorkBuddy 好卡”，系统先反问区分网络慢、响应慢还是文件过多，再提供对应排查路径。确保每次交互聚焦一个具体问题，避免堆砌所有可能性。

使用原则：

• 检索优先级：快速卡 → 深度文档 → 官方文档，不跳层。
• 读取粒度：先用 scripts/quick-search.sh grep 关键词，再读取段落，避免全文件加载。
• 更新维护：踩坑经验追加到对应文件的“踩坑经验”区域，保持手册实用。