WorkBuddy 深度使用指南
一、🧠 Memory（跨会话记忆）
是什么
WorkBuddy 的 Memory 是跨会话的持久化记忆系统，解决"AI 每次对话都忘事"的问题。分两层：
| 文件 | 作用 | 存放位置 |
|---|---|---|
YYYY-MM-DD.md |
当日操作日志（追加写，不覆盖） | .workbuddy/memory/2026-04-18.md |
MEMORY.md |
长期稳定记忆（用户偏好、项目约定） | .workbuddy/memory/MEMORY.md |
在项目中如何使用
读取时机（会话开始时自动读）：
- 任务涉及历史决策、先前约定时，AI 会先读 MEMORY.md 和近两天日志
- 你说"上次我们用 React 做的那个…"，AI 会查记忆找到对应上下文
写入时机（完成实质性工作后自动写）：
- 建了/改了项目
- 修复了 Bug
- 你告诉了 AI 项目规范或个人偏好
- 做了技术选型决策
实战案例——记录项目规范：
你：以后帮我写代码时，变量命名一律用驼峰，注释用中文，用 TypeScript
AI：好的，我会记住这个规范 → 自动写入 MEMORY.md
维护机制：
- 超过 30 天的日志会被蒸馏进 MEMORY.md，然后删除旧日志
- MEMORY.md 要保持简洁，避免堆砌无用信息
最佳实践：
# 主动告知偏好，让 AI 记住
"帮我记住：这个项目的 API base URL 是 https://api.geb8.com"
"以后生成的报告都用 Markdown 格式，不要用 Word"
二、⏮ Checkpoints（会话管理 / 检查点）
是什么
Checkpoints 是会话状态快照机制，允许你在任意时间点保存当前对话+工作状态，随时回退或分叉。
核心能力
| 操作 | 说明 |
|---|---|
| 创建检查点 | 保存当前会话进度，包含对话历史和文件状态 |
| 回退检查点 | 撤销到某个历史节点，不影响之前的文件 |
| 分叉 | 从同一节点开始，尝试不同的方案 |
在项目中如何使用
场景1：做高风险操作前先存档
# 重构前
"先保存一个检查点，然后帮我把 UserService 重构为工厂模式"
→ 重构失败？直接回退检查点，文件恢复原样
场景2：方案对比
# 同一个需求，试两种方案
检查点 A → 方案1（Vue 实现）
检查点 A → 方案2（React 实现）
对比后选最优
场景3：长任务断点续传
# 多小时的复杂任务中途被打断
→ 检查点记录了进度，下次继续从断点恢复
三、🔧 Skill（技能市场）
是什么
Skill 是可插拔的领域专家包，给 AI 注入特定领域的知识、工作流（SOP）和可执行脚本。
文件结构
~/.workbuddy/skills/
└── skill-name/├── SKILL.md ← 核心：描述 + 触发词 + 操作流程├── scripts/ ← 可执行脚本（Python/Node 等）├── references/ ← 参考文档、API 文档└── assets/ ← 资源文件
Skill 两种级别
| 级别 | 存放位置 | 适用范围 |
|---|---|---|
| 用户级 | ~/.workbuddy/skills/ |
个人全局，所有项目可用 |
| 项目级 | {workspace}/.workbuddy/skills/ |
团队共享，只对该项目生效 |
在项目中如何使用
查找并安装技能：
- 左侧菜单 → 技能市场 → 浏览分类安装
- 或直接说："找一个能帮我生成 PPT 的技能"
手动触发：
"使用 finance-data-retrieval 技能查询茅台最近一周股价"
自动触发： SKILL.md 中的 description 写了触发词，AI 识别用户意图后自动加载：
yaml
复制
description: >查股票行情、看财报、涨停板、基金净值、期货数据...
实战案例（当前项目）： 你现在正在使用的就有：
finance-data-retrieval— 209个金融API精确查询neodata-financial-search— 自然语言金融数据搜索pptx— 生成演示文稿docx— 生成 Word 文档
自建 Skill（适合 geb8 项目）：
markdown
复制
# SKILL.md
---
description: >生成招投标文档测试用例、标书模板验证、数字签名测试、
文档汇编流程测试、geb8 自动化测试
---## 能力说明
专门针对 geb8 产品的测试用例自动生成...## 执行脚本
scripts/generate_test_cases.py
四、🤖 Agent（智能体 / 多 Agent 协作）
是什么
Agent 是 WorkBuddy 的自主执行引擎，能规划任务、调用工具、自主迭代直到完成目标。支持多 Agent 团队模式（Team Mode）。
三种工作模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Craft（执行） | 直接行动，读写文件、跑命令、交付结果 | 正常开发任务 |
| Plan（计划） | 先出方案让你审核，再执行 | 高风险/复杂架构决策 |
| Ask（询问） | 只读不写，纯分析讨论 | 代码审查、技术调研 |
多 Agent 团队模式
WorkBuddy 支持并发启动多个 Agent 分工协作：
# 复杂功能开发
→ 创建团队
→ frontend-dev：负责 React UI
→ backend-dev：负责 API 接口
→ test-agent：负责测试用例生成
→ 三者并行，互相发消息协调
Agent 间通信：通过 send_message 工具传递信息：
frontend-dev → backend-dev：
"接口 /api/user 的返回格式确认了吗？我这边要开始对接了"
在 geb8 项目中的实战用法
你："帮我为 geb8 的文档汇编功能生成完整测试用例集"AI 执行流程：
1. 读取项目结构（code-explorer subagent）
2. 分析功能模块
3. 生成测试用例框架
4. 写入测试文件
5. 运行验证
6. 呈现结果
五、🛠 Tool（工具调用）
是什么
Tool 是 AI 的动作执行层，每个工具对应一种能力。WorkBuddy 提供了约 30+ 内置工具。
核心工具分类
文件操作类：
| 工具 | 说明 |
|---|---|
read_file |
读文件内容（支持图片） |
write_to_file |
写/覆盖文件 |
replace_in_file |
精确字符串替换（推荐用于代码修改） |
delete_file |
删除文件 |
list_dir |
列出目录内容 |
search_file |
通配符文件搜索 |
search_content |
正则内容搜索（类 ripgrep） |
代码诊断类：
| 工具 | 说明 |
|---|---|
read_lints |
读取 IDE 报错和警告 |
执行类：
| 工具 | 说明 |
|---|---|
execute_command |
执行终端命令（需用户确认危险操作） |
install_binary |
安装 Python/Node 运行时 |
网络类：
| 工具 | 说明 |
|---|---|
web_fetch |
抓取网页内容 |
web_search |
实时网络搜索 |
preview_url |
在 IDE 内预览 URL |
生成类：
| 工具 | 说明 |
|---|---|
image_gen |
AI 图片生成 |
RAG_search |
检索知识库（微信小程序、腾讯云 API 等） |
交互类：
| 工具 | 说明 |
|---|---|
ask_followup_question |
向用户提多选问题 |
deliver_attachments |
向用户投递文件附件 |
open_result_view |
展示结果预览 |
任务管理类：
| 工具 | 说明 |
|---|---|
todo_write |
创建/更新任务列表 |
task（subagent） |
启动子 Agent 探索代码库 |
工具调用最佳实践
python
复制
# ✅ 正确：多个无依赖的工具调用并发执行，节省时间
[read_file A] + [read_file B] + [search_content X] # 同时发出# ❌ 错误：不必要的串行等待
read_file A → 等结果 → read_file B → 等结果
六、🔌 MCP（模型上下文协议）
是什么
MCP（Model Context Protocol）是 AI 连接外部能力的标准化接口协议，相当于 AI 的"USB 接口"，任何符合 MCP 标准的服务都能即插即用。
配置方式
配置文件位置：~/.workbuddy/mcp.json
json
复制
{"mcpServers": {"filesystem": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/fzq"]},"cloudbase": {"command": "npx","args": ["@cloudbase/cloudbase-mcp@latest"],"timeout": 120000,"env": { "CLOUDBASE_DEBUG": "true" }},"n8n-mcp": {"command": "npx","args": ["n8n-mcp"],"env": {"MCP_MODE": "stdio","N8N_API_URL": "http://localhost:5678","N8N_API_KEY": "your-key"}}}
}
常用 MCP 服务分类
| 类别 | 典型服务 | 能做什么 |
|---|---|---|
| 🗂 文件系统 | @modelcontextprotocol/server-filesystem |
读写本地任意目录 |
| 🌐 浏览器控制 | @playwright/mcp |
自动化网页操作、截图、表单填写 |
| 🗄 数据库 | sqlite-mcp、postgres-mcp |
直接执行 SQL 查询 |
| ☁️ 云服务 | @cloudbase/cloudbase-mcp |
腾讯云开发 DB/存储/函数 |
| 🔧 开发工具 | n8n-mcp、github-mcp |
工作流自动化、Git 操作 |
| 🗺 地图 | 腾讯地图 MCP | 路线规划、POI 查询 |
在 IDE 中配置步骤
- 找到 IDE 右侧面板 → 点击 配置 MCP
- 点击手动配置，弹出
mcp.json编辑界面 - 粘贴服务配置，保存
- 等待服务状态变为绿色 = 配置成功
- 直接用自然语言调用："帮我查询本地 SQLite 数据库里的用户表"
与 Skill 的区别
| Skill | MCP | |
|---|---|---|
| 本质 | AI 的领域知识包 + SOP | 外部服务的连接器 |
| 扩展什么 | AI 的专业能力和工作流 | AI 可调用的外部工具 |
| 安装位置 | .workbuddy/skills/ |
~/.workbuddy/mcp.json |
| 典型用途 | "生成投标文档"的知识 | "读取本地文件系统"的权限 |
七、⚙️ CI/CD（自动化 / Automation）
是什么
WorkBuddy 的 Automation 是定时自动执行任务的机制，支持循环任务（Recurring）和一次性任务（One-time）。
配置存储
自动化任务配置：~/.workbuddy/automations/<id>/automation.toml
两种任务类型
循环任务（Recurring）——用 iCal RRULE 格式：
toml
复制
[automation]
name = "每日市场早报"
prompt = "查询今天 A 股涨跌幅前10，生成简报发送"
rrule = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0"
status = "ACTIVE"
cwds = ["/Users/fzq/WorkBuddy/reports"]
一次性任务（One-time）：
toml
复制
[automation]
name = "下午三点提醒开会"
prompt = "提醒用户：下午3点有周会，请准备上周进度汇报"
scheduleType = "once"
scheduledAt = "2026-04-18T15:00"
status = "ACTIVE"
常用 RRULE 速查
| 需求 | RRULE |
|---|---|
| 每小时 | FREQ=HOURLY;INTERVAL=1 |
| 每天早9点 | FREQ=DAILY;BYHOUR=9;BYMINUTE=0 |
| 每周一早9点 | FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0 |
| 工作日早9点 | FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0 |
| 每两小时 | FREQ=HOURLY;INTERVAL=2 |
在项目中的实战应用
场景1：geb8 测试报告自动化
"每天早上9点，自动运行 geb8 测试套件，生成测试报告，存到 /reports 目录"
→ 创建 Automation，RRULE=FREQ=DAILY;BYHOUR=9;BYMINUTE=0
场景2：金融数据定时采集
"每个工作日下午3点，采集今日 A 股行情数据，存为 CSV"
→ RRULE=FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=15;BYMINUTE=0
场景3：代码库定期健康检查
"每周一早9点，扫描项目代码，生成代码质量报告"
→ RRULE=FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0
有效期控制：
toml
复制
validFrom = "2026-04-18" # 从今天开始
validUntil = "2026-05-31" # 5月底结束（临时项目适用）
📊 七大模块关系图
用户需求│▼
[Agent] ← 读取 [Memory] 获取历史上下文│├── 加载 [Skill] ← 触发词匹配，注入领域专业能力│├── 调用 [Tool] ← 读写文件、搜索、执行命令、生成内容│├── 调用 [MCP] ← 连接外部服务（浏览器/数据库/云服务）│├── 保存 [Checkpoint] ← 重要节点快照，支持回退/分叉│└── 写入 [Memory] ← 持久化本次工作成果[Automation] ← 按时间触发上述整个流程，无需人工介入