WorkBuddy 使用指南
提供 WorkBuddy 全场景功能说明、使用决策、问题排查的实用指南。面向实际使用场景编写，非产品说明书。
触发条件
当用户提出以下类型问题时加载此 Skill：
- WorkBuddy 功能询问（"X怎么用"、"支持X吗"、"能X吗"）
- 使用中遇到问题或报错
- 想了解最佳实践或工作流优化
- 不确定该用哪种方式完成任务
- 上下文管理、对话管理相关问题
- 连接器/自动化配置问题
一、核心概念
工作区（Workspace）
- 一个文件夹 = 一个工作区
- 不同工作区下的对话历史完全隔离
- 切换工作区 = 看到该工作区下的任务列表和对话
- 默认工作区通常为用户主目录或最后使用的目录
决策规则：同一项目的所有对话放在同一工作区下；不同项目用不同工作区。
任务（Task）vs 对话（Conversation）
| 概念 | 说明 |
|---|---|
| 任务 | 一次完整的执行单元，有标题、状态（进行中/已完成/失败）、所属工作区 |
| 对话 | 任务内的消息交互历史，每次追问追加到同一对话 |
| 新任务 | 在工作区内开启全新对话，不继承旧对话的上下文 |
| 继续任务 | 进入已有任务继续发消息，继承全部历史上下文 |
AI 的能力边界
WorkBuddy 能做：
- 读写本地文件（需授权文件夹）
- 执行命令行（bash/PowerShell）
- 搜索网络（WebSearch/WebFetch）
- 生成多种格式文件（文档/表格/PPT/代码/图片/视频）
- 连接外部服务（飞书/腾讯文档/邮箱等）
WorkBuddy 不能做：
- 访问未授权的文件夹
- 操作系统级 GUI 操作（除非有对应自动化工具）
- 执行需要图形界面的程序
二、三种工作模式
Craft（你出嘴，我出手）
直接执行任务，不需确认。适合：
- 明确的任务（"帮我写一个脚本"）
- 文件操作（"整理这个文件夹"）
- 内容生成（"写一份报告"）
Plan（先规划，再执行）
先分析需求、设计方案，需要用户确认后才动手。适合：
- 复杂任务（"开发一个完整应用"）
- 架构决策（"设计数据库结构"）
- 不确定需求时需要讨论的场景
Ask（只分析，不动手）
只读模式，不修改任何文件。适合：
- 了解代码逻辑（"这段代码是什么意思"）
- 调研分析（"帮我看看这个项目"）
- 学习用途（"解释一下这个配置"）
切换方式：在对话中输入模式名称即可切换，如"切换到 Plan 模式"。
三、上下文管理（核心能力）
问题：长对话为什么会"变笨"？
每次对话的上下文窗口有限。当对话超过数十轮：
- 大量历史消息挤占有效空间
- 模型在噪音中做决策，精度下降
- 早期信息可能被截断丢失
典型症状：回复越来越泛、忘记之前讨论过的细节、重复犯同样的错误。
解决策略：开新对话
何时开新对话：
| 场景 | 做法 |
|---|---|
| 上一任务已完成，开始新功能 | 新建任务，通过 Skill/MEMORY.md 加载上下文 |
| 对话超过 ~30 轮 | 总结当前进展到 MEMORY.md，开新对话 |
| 模型开始答非所问 | 立即止损，开新对话 |
| 项目搁置后重新捡起 | 加载项目 Skill + 读 MEMORY.md，在新对话中继续 |
何时继续旧对话：
| 场景 | 做法 |
|---|---|
| 上一个任务还没做完，需要微调 | 继续旧对话（上下文还在） |
| 需要引用前面聊过的具体细节 | 继续旧对话 |
| 对话在 10 轮以内 | 继续旧对话，没必要开新的 |
三层上下文传递机制
Layer 1: 项目 Skill（~/.workbuddy/skills/<项目名>/SKILL.md）
→ 存储架构、文件清单、技术栈、API配置、已知问题（静态）
→ 新对话加载 Skill 后秒获项目全貌
Layer 2: 项目 MEMORY.md（<工作区>/.workbuddy/memory/MEMORY.md）
→ 存储决策记录、进度、团队约定（动态）
→ 自动注入，跨对话持久
Layer 3: 当前对话
→ 即时交互，任务聚焦
标准流程：
1. 项目启动时创建项目 Skill（基于 HANDOFF.md）
2. 每个功能/修bug开新对话
3. 加载项目 Skill 获取上下文
4. 完成工作后更新 MEMORY.md / Skill
5. 新对话 → 重复步骤 3
HANDOFF 模式
在项目根目录创建 HANDOFF.md，包含：
- 项目概述（一句话 + 技术栈）
- 目录结构和文件职责
- 关键配置说明
- 已知问题和待优化项
- 打包/部署流程
HANDOFF.md 是项目 Skill 的素材来源——写好 HANDOFF.md，Skill 可以直接转化。
四、记忆系统
三层记忆架构
| 层级 | 文件位置 | 范围 | 写入方式 | 典型内容 |
|---|---|---|---|---|
| Cloud Memory | 服务端自动管理 | 所有对话 | 自动学习 | 长期偏好、习惯模式 |
| 用户 MEMORY.md | ~/.workbuddy/MEMORY.md |
所有项目 | 显式指令 | 跨项目规则、约定 |
| 项目 MEMORY.md | <工作区>/.workbuddy/memory/MEMORY.md |
单项目 | 自动追加 | 项目决策、踩坑 |
| 日报 | <工作区>/.workbuddy/memory/YYYY-MM-DD.md |
单项目 | 自动追加 | 每日做了什么 |
使用原则
- Cloud Memory：无需手动操作，服务端自动学习
- 用户 MEMORY.md：跨项目共用的硬性规则存这里（如"打包路径必须纯英文"）
- 项目 MEMORY.md：项目级偏好和约定（如"用 electron-builder + NSIS 打包"）
- 日报：由 AI 自动维护，不要手动编辑
与 Skill 的配合
- MEMORY.md = 记录"发生了什么"（事件、决策）
- Skill = 记录"怎么做"（流程、规范）
- 遇到新决策 → 同时更新 MEMORY.md 和 Skill 的相关部分
五、Skill 系统
Skill 是什么
Skill 是模块化的知识包，让 AI 在特定领域获得专业能力。可以理解为"给 AI 装的插件"。
Skill 的层次
| 类型 | 路径 | 范围 |
|---|---|---|
| 用户 Skill | ~/.workbuddy/skills/<name>/ |
跨所有项目可用 |
| 项目 Skill | <项目>/.workbuddy/skills/<name>/ |
仅当前项目 |
核心操作
查找已有 Skill：
调用 find-skills Skill 或搜索 SkillHub
加载 Skill：
"帮我加载 XXX Skill"
创建 Skill：
"帮我创建一个 XXX Skill"
→ AI 会走 skill-creator 标准流程
创建项目 Skill 的标准姿势：
1. 确保项目有 HANDOFF.md
2. 告诉 AI："基于 HANDOFF.md 创建项目 Skill"
3. AI 会提取关键信息，生成结构化的 SKILL.md
4. 之后每次新对话说"加载 XXX Skill"即可
Skill 的内容结构
---
name: skill-name
description: 清晰描述何时触发
agent_created: true
---
# 标题
简短说明。
## 核心流程
步骤化的操作指南。
## 关键配置
配置文件、环境变量等。
## 常见问题
踩坑记录和经验。
六、文件与产物管理
支持的文件类型
- 文档：PDF、Word(.docx)、Markdown、TXT、RTF
- 表格：Excel(.xlsx)、CSV、TSV
- 演示：PPT(.pptx)
- 图片：JPG、PNG、GIF、BMP
- 代码：所有常见编程语言文件
- 压缩包：ZIP、RAR
文件交互方式
| 操作 | 方式 |
|---|---|
| 上传文件 | 拖拽到输入框 / 点击上传按钮 / Ctrl+V 粘贴截图 |
| @引用文件 | 在输入框输入 @ 选择文件 |
| 查看产物 | 右侧"产物"面板 |
| 下载产物 | 产物预览右上角下载按钮 |
| 网页预览 | 内置浏览器自动打开 HTML/本地服务器 |
产物分享
- 分享链接：点击分享按钮生成公开链接
- 上传云端：支持上传到腾讯文档、ima 知识库、乐享知识库
- CloudStudio 部署：生成在线 URL
七、连接器生态
已支持的主要连接器（按类别）
办公协作：
- 飞书全套（IM/文档/表格/日历/任务/审批/会议/邮件/多维表格/知识库等）
- 腾讯文档（个人版 + 企业版）
- 腾讯会议
通讯：
- QQ邮箱
- 企业微信
- 钉钉
存储：
- 微云
- 百度网盘
数据与查询：
- 企查查 / 天眼查（企业信息）
- 智慧芽（专利检索）
- 北大法宝 / 法研（法律检索）
开发与部署：
- GitHub
- CloudStudio
- EdgeOne Pages
- 腾讯云 CloudBase
其他：
- 携程问道（旅行）
- 销售易 CRM
- Canva 可画
连接器状态
连接器在左侧边栏显示状态：
- 已连接（绿色）：可以直接使用
- 未连接：需要先授权/配置
使用连接器
连接器通常是 Skill 的一部分。例如飞书多维表格操作：
1. 先确保飞书连接器已连接
2. 加载 lark-base Skill
3. 按 Skill 指引操作
八、自动化
什么是自动化
按定时规则自动触发任务的机制。支持：
- 每天/每周/每月定时执行
- 一次性定时任务
- 指定有效期
创建自动化
告诉 AI：
"每天早上 8 点帮我生成一份情报简报"
"每周一 9 点汇总上周会议纪要"
AI 会设置定时规则，到时自动执行。
已有自动化示例
- 情报简报：每日 5 条高度相关行业动态
- 会议纪要汇总：按周期生成结构化报告
- 日程待办摘要：生成当日安排
九、常见问题与解决方案
问题：长对话后 AI 变笨
症状：回复越来越不精确、忘记之前讨论的细节、答非所问。
解决：
1. 立即开新对话（不要继续旧对话）
2. 确保项目有 Skill 或 MEMORY.md 保存上下文
3. 新对话加载 Skill 后继续工作
4. 预防：对话超过 30 轮主动开新的
问题：打包/构建失败
症状：中文路径报错、找不到模块。
解决：
1. 检查项目路径是否包含中文字符 → 复制到纯英文路径
2. 检查 npm/pip 镜像源配置（国内需要镜像）
3. 参考项目 MEMORY.md 中的打包经验
问题：文件找不到或路径错误
症状：AI 说找不到文件，但你确定文件存在。
解决：
1. 确认工作区是否正确（看左侧任务列表的工作区路径）
2. 用 @ 引用文件确保路径正确
3. 检查文件夹是否在授权范围内
问题：换文件夹后看不到旧对话
原因：对话按工作区隔离。换了工作区就是全新的对话列表。
解决：在左侧任务列表切换回原来的工作区。
问题：网络不通 / 外网访问失败
解决：
1. 大部分操作在本地完成，不需要 VPN
2. 访问 GitHub/Twitter 等外网时需要 VPN
3. 优先使用国内镜像源（npmmirror、docker 镜像等）
问题：不知道某个功能是否支持
解决步骤：
1. 先查本 Skill 的目录
2. 加载 find-skills 搜索是否有对应 Skill
3. 直接提问——AI 会告知能否做到以及怎么做到
问题：多项目/多任务管理混乱
解决：
1. 每个项目一个工作区文件夹
2. 每个项目创建一个项目 Skill
3. 任务列表按工作区筛选
4. 完成的任务可以归档
十、高效工作流模板
模板 A：新项目启动
1. 创建项目文件夹作为工作区
2. 用 Plan 模式让 AI 做技术方案设计
3. AI 实现基础架构
4. 创建 HANDOFF.md 记录项目全貌
5. 基于 HANDOFF.md 创建项目 Skill
6. 后续功能开发 = 新对话 + 加载 Skill
模板 B：长项目持续开发
1. 加载项目 Skill 获取全貌
2. 在 Craft 模式下描述具体任务
3. AI 完成后，更新 MEMORY.md 记录决策
4. 必要时更新 Skill（如新增依赖、改架构）
5. 下一个功能 → 新对话 → 重复步骤 1
模板 C：研究/调研任务
1. 用 Ask 模式让 AI 搜索和分析
2. 结果满意后切换到 Craft 模式输出报告
3. 产出存到 deliverables 目录
模板 D：报错排查
1. 截图/Ctrl+V 粘贴报错信息
2. AI 分析原因并给出修复方案
3. 确认后执行修复
4. 把踩坑经验写入项目 MEMORY.md
十一、快速索引
按问题类型快速定位：
| 你想做什么 | 看哪个部分 |
|---|---|
| 不知道选哪种工作模式 | 第二节：三种工作模式 |
| 对话太长 AI 不听话了 | 第三节：上下文管理 |
| 想让 AI 记住项目信息 | 第三、四节：上下文管理 + 记忆系统 |
| 想给 AI 装个"插件" | 第五节：Skill 系统 |
| 不知道怎么上传/下载文件 | 第六节：文件与产物管理 |
| 想连接飞书/腾讯文档 | 第七节：连接器生态 |
| 想定时执行任务 | 第八节：自动化 |
| 遇到具体报错或问题 | 第九节：常见问题 |
| 不确定整体怎么操作 | 第十节：工作流模板 |
