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 中配置步骤

  1. 找到 IDE 右侧面板 → 点击 配置 MCP
  2. 点击手动配置，弹出 mcp.json 编辑界面
  3. 粘贴服务配置，保存
  4. 等待服务状态变为绿色 = 配置成功
  5. 直接用自然语言调用："帮我查询本地 SQLite 数据库里的用户表"

与 Skill 的区别

 SkillMCP
本质 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] ← 按时间触发上述整个流程，无需人工介入

WorkBuddy 中 @ 与 📎 回形针 的区别

一、核心区别一览

对比维度@ 符号引用📎 回形针上传
本质 引用/索引，让 AI 去读文件 上传文件内容进入对话
文件位置 文件留在本地，AI 按需读取 文件内容被载入当前会话上下文
适用文件 本地目录下的文件、文件夹、代码 任意文件（PDF、图片、Excel、Word 等）
持久性 可跨步骤持续访问 仅当前会话/消息有效
可操作性 AI 可读写、修改、搜索原文件 AI 只能读取/分析上传内容
批量处理 ✅ 支持引用整个文件夹 ❌ 一般逐个上传
文件大小限制 取决于 AI 读取能力 有上传大小限制

二、@ 符号 — 本地文件引用

是什么： 在输入框输入 @ 后，会弹出文件/目录选择器，让 AI 定位并读取你本地的文件。AI 拿到的是一个"去哪里找"的地址，可以随时重新读取最新版本。

能做什么：

@src/utils/auth.js  → AI 读取这个文件并帮你分析/修改
@docs/              → AI 扫描整个目录，批量处理
@config.json        → AI 读取配置，结合上下文工作

典型场景：

  • 📝 "帮我看看 @src/components/Header.jsx 里的逻辑"
  • 🔧 "把 @project/ 目录下所有 var 改成 let"
  • 🔍 "在 @docs/ 里搜索所有包含 TODO 的文件"
  • 🔄 可修改原文件 — AI 改完直接写回原路径

关键特征：文件本身不动，AI 有"访问权限"，操作是实时生效的。

三、📎 回形针 — 文件上传

是什么： 点击输入框旁的回形针图标，把文件内容上传进当前对话。文件内容作为上下文的一部分传给 AI，AI 处理的是这份"副本"，不会改动原文件。

支持格式： PDF、DOCX、XLSX、PNG、JPG、TXT、CSV 等常见格式

典型场景：

  • 📊 上传竞品报告 PDF → "帮我提取核心数据，生成对比表格"
  • 📸 上传截图/图片 → "帮我描述这张图里的内容"
  • 📋 上传 Excel → "分析这份数据，找出异常值"
  • 📄 上传合同 Word → "帮我总结关键条款和风险点"

关键特征：原文件不受影响，AI 只是"看了一眼"，处理结果需要另存。

四、一句话记忆

@ = "去我电脑上读/改这个文件"（有写权限，实时生效）
📎 = "我把这个文件的内容给你看一眼"（只读副本，不改原文件）

五、针对你项目的使用建议

你的场景推荐方式原因
geb8 项目代码修改/测试 @ 引用 需要读写项目文件，实时修改
导入招标文档模板分析 📎 上传 分析即可，不需要改原文件
诗词视频脚本参考资料 📎 上传 一次性分析参考内容
金融报表数据处理 📎 上传 CSV/Excel 一次性数据分析任务
批量处理项目中多个文件 @ 引用目录 批量操作优势明显 
 

posted on 2026-04-26 09:07  fengZQ  阅读(4825)  评论(0)    收藏  举报

导航