WorkBuddy保姆级教程：从零搭建AI工作流

最近花了不少时间把 WorkBuddy 从安装到实战完整跑了一遍过程里踩了不少坑也把网上碎片化的资料重新梳理成了自己的知识体系。与其让这些内容躺在本地笔记里不如整理成一套从零开始的保姆级教程。网上类似的“60 节付费课”其实把一件本来不复杂的事情拆碎了核心就是三件事理解概念、完成安装、做出一条能复用的工作流。本文按“概念 → 安装 → 原理 → 实战 → 排错 → 最佳实践”的顺序展开零基础读者可以跟着一步步操作有一定经验的开发者可以直接跳到第 4 节看完整工作流案例。1. WorkBuddy 是什么AI 工作台要解决什么问题1.1 为什么我们需要一个 AI 工作台过去两年AI 工具已经多到让人眼花缭乱聊天助手、代码补全、文档生成、自动化流程平台每个工具都能解决一部分问题。但问题也随之而来——工具之间是割裂的。你上午用 A 工具写文案下午用 B 工具整理表格晚上还要手工把结果复制到 Word 里排版AI 并没有真正把“完整工作流”串起来。WorkBuddy 这类产品被称为 AI 工作台核心思路不是再做一个“更聪明的聊天框”而是把 AI 能力、脚本工具、数据处理步骤和最终输出整合到一条可重复执行的流程中。你可以把日常工作中“收集资料 → 整理分析 → 生成文档 → 转换格式”这类多步骤任务抽象成一个工作流以后每次只需要换输入内容不需要重复设计流程。从实际使用来看AI 工作台最大的价值不是“生成一段文字”而是“把生成文字之后的一系列动作也自动化”。这是它与普通聊天工具最本质的区别。1.2 WorkBuddy、Coze、Dify、n8n 的定位区别很多读者会在选型时把 WorkBuddy 和 Coze、Dify、n8n 放在一起比较。这里先做一个简单的区分。工具/平台主要定位适合人群Coze扣子国内生态友好的 Bot 搭建平台偏对话机器人、抖音生态、低代码场景DifyLLM 应用开发平台需要 RAG、知识库、数据集管理的团队n8n通用自动化工作流平台偏传统系统集成、API 编排、定时任务WorkBuddyAI 工作台偏向把 AI 对话、Skills 脚本、文件处理放在本地一体化操作简单理解Coze 和 Dify 更侧重“在线平台搭建”n8n 更侧重“系统间集成”而 WorkBuddy 这类工具更强调“本地工作台 可编程技能Skill”你可以在工作台里调用模型也可以直接跑 Python 脚本处理文件。它们不是完全替代关系侧重点不同。另外也经常有人问 CodeBuddy 和 WorkBuddy 有什么区别。从定位上看CodeBuddy 更偏编程助手围绕代码生成、代码补全、仓库上下文做文章WorkBuddy 的覆盖面更广瞄准的是日常工作任务本身代码处理只是其中一个能力节点。如果你主要写代码编程助手更直接如果你想把写文档、整理资料、格式转换这类杂活也做成自动化工作台思路会更合适。1.3 本文会用到的核心概念在进入实操前先统一几个后面反复出现的词Workflow工作流一组按顺序执行的操作步骤每步可以是读取文件、调用模型、执行脚本、输出结果。Skill技能一段可复用的脚本或工具封装比如“把 Markdown 转成 Word”“批量重命名文件”“提取 PDF 文本”。Context上下文AI 模型在处理任务时能“记住”的信息量通常受模型上下文窗口限制。节点Node工作流中的一个最小执行单元一个工作流由多个节点组成。这四个概念会贯穿全文。后面第 3 节会对工作流、Skill、上下文做更细致的拆解。2. 环境准备与安装思路这一节介绍安装 WorkBuddy 前的准备工作。由于 WorkBuddy 更新速度较快不同版本的安装命令可能存在差异所以我不会把某个具体版本号写死而是给出通用的安装思路。2.1 硬件与运行环境先看硬件。WorkBuddy 本身是一个本地运行的工作台普通办公电脑即可运行不需要高端显卡如果你希望在本地跑开源模型才需要考虑 GPU 资源。日常使用云厂商的模型 API 时CPU 和内存才是主要瓶颈。系统方面Windows 10/11、macOS、主流 Linux 发行版都能运行。如果你使用 Windows建议优先使用 PowerShell 而不是 CMD因为很多工作流脚本依赖路径和编码能力PowerShell 的兼容性更好。需要提前安装的工具Git用于拉取项目代码。Python 3.10 或更高版本用于运行工作台本体和 Skill 脚本。一个文本编辑器推荐 VS Code。如果需要转换文档格式建议提前安装 pandoc后面实战案例会用到。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.2 Python 与 Git 环境搭建如果你已经安装过 Python 和 Git可以跳过这一步。建议先检查版本python --version git --version如果提示找不到命令需要先安装对应工具。macOS 上可以用 Homebrewbrew install python git pandocUbuntu/Debian 上可以用 aptsudo apt update sudo apt install python3 python3-venv python3-pip git pandocWindows 用户建议从 Python 官网下载安装包安装时勾选“Add Python to PATH”Git 则从官网下载 Git for Windows。安装完成后重新打开终端确认命令可以正常识别。2.3 安装 WorkBuddy 并验证启动安装 WorkBuddy 通常采用源码方式也就是从 GitHub 或其他开源仓库拉取代码在本地创建虚拟环境然后安装依赖。下面给出通用步骤# 1. 克隆项目仓库仓库地址以官方 README 为准 git clone workbuddy-仓库地址 cd workbuddy # 2. 创建 Python 虚拟环境避免污染全局环境 python -m venv .venv # 3. 激活虚拟环境 # macOS / Linux source .venv/bin/activate # Windows PowerShell .venv\Scripts\Activate.ps1 # 4. 升级 pip 并安装依赖 python -m pip install --upgrade pip pip install -r requirements.txt安装完成后启动方式一般有两种命令行入口或 Web 管理界面。常见启动命令类似python main.py # 或者 workbuddy serve具体命令以项目 README 为准。验证是否启动成功可以观察终端是否输出监听地址例如http://localhost:3000有浏览器界面的工具也可以直接访问该地址。第一次启动会比较慢因为要初始化配置目录、加载默认 Skills 列表这是正常现象。2.4 模型 API Key 准备WorkBuddy 本身不包含大模型能力它需要对接外部模型 API 才能完成生成、分析、总结等任务。目前主流选择有三类OpenAI 兼容接口包括 OpenAI、DeepSeek、Moonshot 等。Anthropic 的 Claude 系列 API。本地开源模型通过 Ollama 等工具暴露成 OpenAI 兼容接口。在开始之前你需要准备一个可用的 API Key并把它配置到 WorkBuddy 的配置文件中。API Key 是敏感信息建议通过环境变量或本地配置文件保存不要提交到 Git 仓库。后续第 6 节会专门讲密钥管理。3. 核心原理拆解工作流、Skill 与上下文3.1 工作流Workflow的本质工作流本质上是一个“状态转换过程”。输入是一份原始数据经过若干个节点处理后最终变成你想要的输出。每个节点执行一个小任务节点之间通过参数或文件传递结果。举个例子一条“文章整理工作流”可以做如下设计读取指定目录下的 Markdown 文件。调用大模型对内容进行分段、去重、补全标题。把整理后的内容写入新的 Markdown 文件。调用 pandoc 将 Markdown 转为 Word 文档。这个流程的每一步都是独立的你可以单独调试任何一步也可以替换其中某一步的实现。比如第 2 步原来用 GPT 模型后来想换成 Claude只需要修改模型配置不需要改动其他步骤。工作流设计有一个原则每个节点职责单一。不要把“读取文件 调用模型 保存文件”写在一个超大脚本里否则后期维护会非常痛苦。把节点拆小每个节点只做一件事调试时能快速定位问题。3.2 Skill把能力封装成可复用节点Skill 是工作流中的“能力单元”。它可以是 Python 脚本、Shell 命令、Node.js 程序甚至是一个简单的 API 请求。为什么要封装成 Skill第一复用。你写了一个“PDF 转文本”的脚本下次在别的流程里也需要这个能力直接引用即可不用重写。第二隔离。某个 Skill 出错了不会影响整个工作台你只需单独调试这个 Skill。第三可分享。开源社区里大量 Skill 可以直接拿来用这是 WorkBuddy 生态很重要的一部分。一个 Skill 通常包含两部分一个入口脚本负责接收参数并执行逻辑一份描述文件说明这个 Skill 的输入、输出和用途。工作台通过描述文件来识别 Skill并把参数传给它。3.3 上下文Context管理上下文是 AI 工作流里最容易被忽略、也最容易出问题的概念。大模型对单次对话能处理的信息量有上限比如某些模型支持 32K、64K 或 128K token。当你的任务输入过长时会出现“上下文用量满了”的提示。常见的表现有两种模型开始“遗忘”对话开头的内容。工作流直接报错提示超出上下文限制。解决上下文过载的方法不是盲目换更大窗口的模型而是从工作流设计上优化分段处理。把大文档按章节拆开逐段交给模型最后再汇总。只传递摘要。上游节点先对内容做摘要再把摘要传给下游模型节点。清理历史消息。在重复执行任务时不需要保留之前的对话记录。按需加载。不要把整份文件一次全部读入只读取需要处理的部分。3.4 模型路由与工具调用复杂工作流中不一定所有步骤都用同一个模型。有些任务适合快而便宜的小模型比如标题生成、关键词提取有些任务需要强推理能力比如代码修复、长文档分析。因此工作流应该支持“模型路由”按任务类型选择不同模型。同时真正的 AI 工作台不应该只停留在“让模型说话”还要让模型能调用外部工具。比如模型判断出需要转换文档格式时可以调用 md2docx 这个 Skill需要查天气时可以调用天气 API。工具调用Function Calling是连通“AI 大脑”和“执行手脚”的关键机制也是 WorkBuddy 这类工作台区别于普通聊天软件的重要特征。4. 完整实战从零搭建“资料整理 Markdown 转 Word”工作流下面进入实战环节。我们以一条高频场景为例把一篇 Markdown 笔记整理成适合导出的 Word 文档。这个需求在写周报、整理课程笔记、输出技术方案时非常常见。4.1 场景分析输入一篇结构混乱的 Markdown 笔记。输出一份排版清晰的 Word 文档。流程拆解读取 Markdown 文件。调用大模型对内容进行整理补充标题层级、删除冗余、规范化格式。将整理结果保存为一个新的 Markdown 文件。调用 md2docx Skill 将该文件转换为 Word 文档。4.2 创建项目结构建议在工作台的数据目录下创建一个独立项目文件夹例如workflows/doc-converter并保持以下结构doc-converter/ ├── workflow.yaml # 工作流定义 ├── docs/ │ ├── input.md # 原始笔记 │ └── output.md # 整理后的笔记 ├── skills/ │ └── md2docx/ │ ├── SKILL.md # Skill 描述文件 │ └── skill.py # 转换脚本 └── logs/ # 存放运行日志这样组织的好处是工作流定义、输入输出文件、Skill 脚本、运行日志全部隔离维护起来很清楚。4.3 定义工作流配置文件工作流配置负责描述整个执行过程。下面是一个通用结构的 YAML 示例字段命名可能随 WorkBuddy 版本有所变化重点看设计思路name: doc-converter description: 整理 Markdown 笔记并转换为 Word 文档 steps: - id: read_input type: file_reader params: path: ./docs/input.md - id: optimize_content type: llm_call params: model: gpt-4o-mini prompt: | 你是一个文档编辑助手。请对下面的 Markdown 内容进行整理 1. 补充合理的标题层级 2. 删除重复表述 3. 保持技术术语不变 4. 输出格式为 Markdown。 原始内容 {{steps.read_input.output}} temperature: 0.3 - id: save_markdown type: file_writer params: path: ./docs/output.md content: {{steps.optimize_content.output}} - id: convert_docx type: skill skill: md2docx params: input: ./docs/output.md output: ./docs/output.docx配置里的{{steps.read_input.output}}表示引用上一个步骤的输出这种模板变量写法可以让你把多个节点串联起来。temperature: 0.3是模型生成参数值越低输出越稳定适合文档整理场景。4.4 编写 Skill 脚本接下来实现 md2docx 这个 Skill。这里选择 pandoc 作为转换引擎因为 pandoc 对 Markdown 转 Word 的支持非常成熟代码量也很少。先写 Skill 描述文件skills/md2docx/SKILL.md--- name: md2docx description: 使用 pandoc 将 Markdown 文件转换为 Word 文档 input: - input: Markdown 文件路径 - output: Word 文件路径 output: - result: 执行结果信息 --- 该 Skill 依赖系统已安装 pandoc。再写核心脚本skills/md2docx/skill.pyimport subprocess import sys from pathlib import Path def convert(input_md: str, output_docx: str) - str: 将 Markdown 文件转换为 Word 文档。 依赖系统已安装 pandoc转换成功后返回提示信息。 input_path Path(input_md) output_path Path(output_docx) if not input_path.exists(): return f错误找不到输入文件 {input_path} # 确保输出目录存在 output_path.parent.mkdir(parentsTrue, exist_okTrue) cmd [pandoc, str(input_path), -o, str(output_path)] try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout60) if result.returncode ! 0: return f转换失败{result.stderr} return f转换成功{output_path} except FileNotFoundError: return 错误未安装 pandoc请先安装后再重试 except subprocess.TimeoutExpired: return 错误转换超时请检查文件大小 if __name__ __main__: if len(sys.argv) 3: print(用法python skill.py input.md output.docx) sys.exit(1) print(convert(sys.argv[1], sys.argv[2]))这段脚本的逻辑很简单接收两个路径参数检查输入文件是否存在然后调用 pandoc 完成转换最后返回成功或失败信息。它把“路径判断”“命令执行”“错误处理”都覆盖到了可以在工作台之外单独运行验证。4.5 运行与验证先准备一份示例输入文件docs/input.md# 项目周报 ## 本周进展 完成了登录模块开发。 修复了三个bug。 本周联调通过。 ## 下周计划 - 编写接口文档 - 部署测试环境 - 准备评审材料 ## 风险 联调进度略滞后需要协调测试资源。然后在项目目录下手动验证 Skillcd docs python ../skills/md2docx/skill.py input.md output.docx如果系统已经安装 pandoc终端会输出转换成功output.docx接着打开 WorkBuddy 工作台运行 doc-converter 这个工作流。工作流会自动读取input.md调用大模型整理内容保存为output.md最后把output.md转成output.docx。4.6 结果说明与扩展运行完成后你会得到两个文件output.md模型整理后的 Markdown 内容。output.docx通过 pandoc 生成的 Word 文档。打开output.docx可以看到标题层级被合理规整内容比原始笔记更流畅。这就是“AI 工作流”的直观效果大模型负责思维工作脚本负责机械操作两者配合完成整条链路。进一步扩展的方向很多把 md2docx 替换为“PDF 转 Word”“网页转 Markdown”等 Skill。在流程中增加“发送到企业微信/钉钉”节点。增加定时触发每天自动整理指定目录的笔记。5. 高频问题与排查思路在使用 WorkBuddy 的过程中下面几个问题出现的频率最高。整理成一张速查表方便遇到问题时快速对照。问题现象常见原因解决思路上下文用量满了一次向模型传入过多文本分段处理、先摘要再传内容、清理历史消息提示缺失 Python 包项目依赖未完整安装检查 requirements.txt重新执行 pip install模型 API 超时网络波动或请求体过大减小请求规模、延长超时时间、检查代理Skill 不生效描述文件格式错误或路径不对检查 SKILL.md 字段确认 Skill 目录结构Word 转换后格式乱原始 Markdown 标题层级不规范先让模型整理标题层级再执行转换5.1 上下文用量满了怎么办这是很多新手最容易卡住的点。出现这个问题时先不要急着换更大窗口的模型按以下顺序排查查看工作流中传入模型的文本大小。如果一次性传入了一整本书任何模型都不够用。检查是否重复传递了相同的上下文。比如步骤 A 已经输出了摘要步骤 B 又把原文传给模型这是浪费。对输入做分段。把大文档拆成多个小段分批处理后再汇总。如果业务允许可以换用支持更长上下文的模型但要注意成本和速度。记住一句话上下文优化永远优先于模型升级。优化好输入结构普通的 32K 模型也够用不优化输入结构128K 模型也会爆。5.2 提示缺失 Python 包很多开源工作流会引用第三方库比如pandas、requests、openai。如果你从网上复制了一个工作流运行时提示“请安装缺失的包”不要慌通常执行以下命令即可pip install pandas requests openai如果你不知道具体缺哪些包可以看报错信息里的ModuleNotFoundError缺哪个装哪个。更稳妥的做法是在项目根目录执行pip install -r requirements.txt如果项目没有 requirements.txt建议你把用到的依赖整理出来方便以后重建环境。5.3 模型 API 超时或报错模型 API 调用失败是另一类高频问题。常见报错包括连接超时、401 鉴权失败、429 限流。排查思路如下401检查 API Key 是否配置正确是否有多余空格。429请求频率超过限制改为降低并发或增大请求间隔。超时先确认网络是否能访问目标 API 地址如果配置了代理检查代理是否稳定。建议在你的配置中单独设置请求超时时间例如timeout: 60避免默认值太短导致大任务频繁失败。5.4 Skill 不生效或脚本执行失败Skill 不生效先检查三件事目录结构是否标准WorkBuddy 通常要求每个 Skill 有独立目录目录内包含 SKILL.md 描述文件。描述文件格式是否正确YAML 字段写错会导致 Skill 无法被识别。脚本是否有可执行权限Linux/macOS 上需要chmod x或通过 Python 执行。建议在 WorkBuddy 外部先手动运行 Skill 脚本一次确认脚本本身没问题再放入工作流调试。这样可以缩小排查范围。6. 最佳实践与工程建议6.1 配置与密钥管理API Key 是敏感信息。开发时为了方便很多人会直接写在配置文件里比如llm: api_key: sk-xxxxxxxx这种做法在个人电脑上问题不大但一旦项目要分享给别人或者上传到 GitHub就非常危险。正确做法是使用环境变量export WORKBUDDY_API_KEYsk-xxxxxxxx然后在配置文件中引用环境变量llm: api_key: ${WORKBUDDY_API_KEY}如果你使用 Git一定要把.env、config.local.yaml等文件加入.gitignore避免密钥泄露。6.2 Prompt 与 Skill 维护工作流里的 Prompt 不是写一次就完事的。随着使用场景变化Prompt 需要持续迭代。建议把 Prompt 集中管理而不是散落在多个工作流文件里。可以为每个常用任务维护一个 Prompt 模板文件例如prompts/ ├── summarize.md ├── doc-organize.md └── code-review.md这样当模型效果变差时你可以快速找到对应模板进行修改不用在一个几百行的工作流文件里翻找。Skill 同样需要版本管理。一个 Skill 的脚本更新后要同步更新 SKILL.md 中的描述否则容易造成“脚本已经变了文档还是旧的”的问题。如果 Skill 做得足够通用考虑提交到开源社区让别人也能复用。6.3 日志与可观测性工作流一旦多起来排查问题的难度会上升。建议从第一天就建立日志习惯每个工作流运行前打印输入摘要。每个节点执行后打印输出摘要。出现异常时打印完整错误堆栈而不是只打印“出错了”。一个简单做法是在工作流配置中增加日志路径logging: level: info file: ./logs/workflow.log如果某个工作流稳定运行很久可以在日志中记录每次执行的耗时、token 消耗量。这些数据后续可以做成本分析帮助你判断哪个环节最贵、最值得优化。6.4 安全与权限边界让 AI 工作台自动化执行命令本质上是在授予程序执行能力。这里必须强调最小权限原则。不要用管理员或 root 账户运行工作台创建一个普通用户并限制目录权限。不要让模型直接执行任意命令如非必要只允许模型调用白名单 Skill。涉及删除、覆盖、移动文件的操作务必在工作流设计阶段增加确认环节或备份机制。如果你的工作流会读取个人数据、内部文档先确认这些数据所在的存储位置是否合规是否能被模型 API 合法传输。安全不是最后加上的功能而是工作流设计阶段就要考虑的约束。尤其是当你准备把工作流分享到社区时务必检查代码里有没有硬编码的密钥、有没有危险的文件操作。7. 总结与下一步学习路线到这里你已经完成了从概念到实操的完整闭环理解了 AI 工作台和工作流的本质完成了本地安装学会了 Skill 的编写方式并亲手跑通了一条“资料整理 Markdown 转 Word”的工作流。下一步的学习方向可以有层次地推进。首先把工作流从“单条”变成“多条”。尝试给自己常用的场景分别设计工作流比如周报生成、会议纪要整理、简历筛选。简历筛选就是一个很好的练手项目读取简历文件让模型提取姓名、技能、年限、项目亮点再按岗位匹配度打分最后输出一份排序后的候选人表格。其次深入研究模型路由和成本优化。整理一条工作流中每个节点的 token 消耗把高频简单任务切换到更便宜的模型把复杂任务留给强模型。这种优化能力在真实项目中非常值钱。最后关注社区生态。开源项目最有趣的部分是别人的用法会超出你的想象。多看看开源仓库里其他人贡献的 Skill思考他们为什么这样设计再试着模仿改造一个。如果你的某个 Skill 足够通用把它开源出去回馈社区。动手是最好的学习方式。挑一个你工作中真实的重复性任务用今天这套思路把它做成一条工作流。过程中遇到的任何问题都可以顺着第 5 节的排查表逐步定位如果你在搭建过程中踩到其他坑欢迎在评论区留言讨论。