最近在折腾 WorkBuddy，顺手把飞书机器人拉到本地 RAGFlow 知识库前面，搭了一条能直接问答的业务知识链路。从第一天踩 RAGFlow 部署的坑，到第三天 WorkBuddy 终于把带引用的答案回传到飞书群里，全程踩了不少跟教程无关的坑。这篇文章就把完整流程写清楚，拆解每一步的关键参数、选型理由和常见问题，适合已经有点 AI 应用基础、但第一次把「智能体 + 机器人 + 知识库」串起来的朋友参考。我会把链路怎么设计、RAGFlow 怎么部署、WorkBuddy 怎么调 API、飞书机器人怎么接入，以及联调时最典型的几个坑，全部摊开讲。

1. 方案总览：为什么是 WorkBuddy + RAGFlow 这套组合

1.1 链路到底长什么样

先确认一下我们要搭的东西到底是什么。整条链路本质上是一个「问答闭环」：用户在飞书里给机器人发消息，机器人把消息转给 WorkBuddy 智能体，WorkBuddy 收到请求后去本地 RAGFlow 知识库做向量检索，把命中的片段拿回来，再交给大模型生成回答，最后把回答通过飞书机器人发回群里。

简化成数据流就是：飞书消息 → WorkBuddy 智能体 → RAGFlow 检索 → LLM 生成 → 飞书回复。中间最难的一环不是某个单点功能，而是把四个系统用 Webhook、HTTP API、鉴权串起来。你会发现单独看 RAGFlow 的部署、单独看飞书机器人配置，都有大量教程，但把它们真正连成一条链时，问题都出在格式对接、超时限制、鉴权方式这些细节上。

我为什么选择 WorkBuddy 而不是直接从飞书调用 RAGFlow API？因为 WorkBuddy 在整个链路里充当「调度器」角色，它能统一管 LLM 调用、工具调用、会话上下文和回复格式，后续想加更多知识库、加定时任务，都在一个地方改，不用反复改飞书事件回调代码。

1.2 三套主流方案对比：RAGFlow / Dify / 扣子

如果你搜索相关关键词，会看到很多国内 AI Agent 产品盘点，至少会提到三套路径：RAGFlow 单独部署、Dify 知识库流水线、扣子（Coze）智能体。我横向对比用下来：

我最后选了 RAGFlow + WorkBuddy，核心原因是 RAGFlow 的 DeepDoc 解析对中文 PDF、扫描表格的识别效果确实好，而且它可以完全跑在本地，数据不出内网。WorkBuddy 则负责把「检索」和「生成」拆成独立步骤，我可以在 Skill 里控制检索参数，比如 top_k 设置、引用片段数量、结果过滤规则，这在纯低代码平台上反而不容易精细控制。

需要说明的是，如果团队里没有人写代码，我建议直接用 Dify 的飞书机器人集成，二十分钟能通；但如果想搞成本地可控、知识库要长期积累、后续还要接内部系统的链路，这套组合更耐折腾。

2. 第一步：把 RAGFlow 知识库在本地跑起来

2.1 Docker 部署 RAGFlow 的关键参数

RAGFlow 官方部署方式就是用 Docker，版本拉infiniflow/ragflow:v0.15.0（写这篇文章时我用的是这个版本，API 路径有变化）。先确认机器配置，这点非常重要：RAGFlow 实际跑起来会同时启动 MySQL、Redis、MinIO、Elasticsearch 等多个容器，最低建议 8GB 内存，16GB 才跑得舒服。我第一次在一台 4GB 机器上硬上，ES 频繁重启，索引一直失败，后来才发现是 JVM 堆内存不够。

部署时用 Docker Compose 最稳。官方docker-compose.yml里需要注意几个挂载目录：

volumes: - ./ragflow-logs:/ragflow/logs - ./ragflow-data:/root/.ragflow - ./nginx:/etc/nginx/conf.d

其中ragflow-data是知识库元数据和配置，nginx目录下可以改反代配置。启动命令没什么特别的：

docker compose -f docker-compose.yml up -d

这里有个坑：首次启动后要等 Elasticsearch 就绪才能访问页面，很多教程没提。等 30 秒到 1 分钟是正常的，别急着判断启动失败。判断就绪可以看日志：

docker logs -f ragflow-server

看到Server started类似的日志后再打开http://localhost:9380，用默认账号admin初始化密码infini_rag_flow登录，进去第一件事改密码。

2.2 创建知识库与文件解析技巧

进入 RAGFlow 页面后，创建一个知识库，我建议按业务域拆分，比如「产品手册库」「售后问题库」「合同模板库」，而不是一股脑全放一个大库里。拆分的好处是检索时可指定知识库，避免跨域干扰，后续权限管理也方便。

创建完知识库，上传文件。RAGFlow 的解析模板很关键：

• 通用：适合混排文档，遇到图片会保留并做 OCR
• 手动：适合有明确结构、要自己控制 chunk 的场景
• QA：适合 FAQ 类文档，能提取问题答案对
• 表格：适合 Excel/CSV 为主的资料

我实际测试下来，解析 PDF 时用「通用」模板最省心，扫描版合同也能 OCR 出来。但要注意，解析结果不是一上传就立刻可检索的，需要等状态从「解析中」变成「就绪」。批量上传时，后台会排队，文件多的时候耐心等待，不要在解析中反复删除重传。

还有一个很多人忽略的点：Word 转 PDF 后再上传，解析效果往往比直接传 Word 好。RAGFlow 对 PDF 的版面还原比 Docx 稳定得多，尤其是包含表格的文档，直接传 Docx 容易出现表格被拆碎的问题。

2.3 RAGFlow 能存图片吗？文件类型与图片处理

这个很多人问：知识库能存储图片吗？答案是能，但要区分场景。RAGFlow 会把你上传的 PDF 里的图片提取出来，在解析详情里可以看到图片片段；也可以在知识库里直接上传图片文件，解析后通过 OCR 提取文字。但需要明确「存图片」和「检索图片」是两回事：RAGFlow 的向量检索是针对文本的，图片本身不会被用来做语义匹配，它只是作为解析内容的一部分被关联。

如果你的知识库资料里有大量非文字图表，比如架构图、截图，建议在图片下面补充一段文字说明，或者单独维护一个「图片说明文档」，否则用户问「登录流程是怎样的」时，系统可能找不到图里的关键信息。这是当前所有 RAG 知识库的通病，不是 RAGFlow 独有。

3. 第二步：WorkBuddy 安装与智能体搭建

3.1 WorkBuddy 安装与基础配置

WorkBuddy 可以理解为本地优先的 AI 智能体工作台，安装过程并不复杂，但有两个细节要注意：一是选择适合自己系统的安装包，Win 和 macOS 的包名不同；二是安装后需要指定模型服务，WorkBuddy 本身不内置大模型，它依赖你配置的模型 API，可以接云端服务也可以接本地 Ollama。

如果你希望整个链路完全本地化，可以在本机跑一个 Ollama 服务，然后在 WorkBuddy 里把模型地址指到http://localhost:11434，用类似qwen2.5:7b的模型。但我的经验是，本地小模型在回答质量上会明显不如云端大模型，尤其是需要从长文档里提炼结论的场景。折中方案是：检索和路由在本地，生成回答调一个更智能的云端模型。具体怎么取舍，取决于你对数据隐私的要求。

WorkBuddy 首次打开后会引导创建项目或工作台，这里就是智能体的载体。每个智能体本质上是「提示词 + 工具集 + 模型参数」的组合。先把基础模型配好，后面 Skill、工具都在这个智能体下面挂。

3.2 配置 RAGFlow API 连接：Skill 的编写思路

WorkBuddy 通过 Skill 来扩展能力。每个 Skill 是一个可以调用的工具，里面可以有提示词，也可以有代码。我这里把「检索 RAGFlow 知识库」封装成一个 Skill，核心逻辑是调用 RAGFlow 的检索接口。

RAGFlow 的 HTTP API 接口路径在不同版本有变化，常见的是/api/v1/retrieval。请求需要带 API Key，这个 Key 在 RAGFlow 右上角头像 → API 里生成。请求体大致长这样：

{ "question": "查询问题", "dataset_ids": ["你的知识库ID"], "top_k": 5, "similarity_threshold": 0.2, "keywords": [] }

在 WorkBuddy 的 Skill 里，我推荐用 Python 脚本来做实际请求，方便处理异常和重试。核心代码框架可以这样写：

import requests import json def run_retrieval(question: str) -> dict: url = "http://127.0.0.1:9380/api/v1/retrieval" headers = { "Authorization": "Bearer <your-api-key>", "Content-Type": "application/json" } payload = { "question": question, "dataset_ids": ["<dataset-id>"], "top_k": 5, "similarity_threshold": 0.2 } resp = requests.post(url, headers=headers, json=payload, timeout=30) resp.raise_for_status() return resp.json()["data"]["chunks"]

返回的chunks里每一条都带content、similarity、document_keyword等字段。下一步把这些片段拼接成提示词，交给模型生成回答。

这里要注意两个易错点：第一个是dataset_ids前面我吃过亏，传了知识库名称而不是 ID，结果一直空结果；第二个是similarity_threshold，如果设得太高（比如 0.5），很多相关片段会被过滤掉，回答会变得很干。

3.3 WorkBuddy Skill 编写经验：命名、输入输出、超时控制

WorkBuddy 的 Skill 命名最好不要带空格和特殊字符，用ragflow_retrieval、feishu_send_message这种小写下划线风格。Skill 的输入输出尽量用 JSON 结构，返回结果里至少包含status、message、data三个字段，这样调试时能一眼看出失败原因。

另一个容易忽略的是超时控制。飞书的事件回调一般有超时要求，WorkBuddy 在调用 RAGFlow 检索 + 大模型生成时，耗时很容易超过 10 秒。我的做法是：把检索和生成分成两个 Skill，检索 Skill 先跑，结果落到一个临时变量里；生成部分重新组织提示词，在生成前检查检索结果是否为空，避免模型对着空上下文硬答。

还要处理 RAGFlow 返回的引用来源。很多使用者在最终回答里会带上「参考文档」，这个不是 RAGFlow 默认返回的，需要从 chunks 里的document_keyword或title字段提取，拼接成引用列表，再当作回复的一部分返回给飞书。

4. 第三步：飞书机器人接入

4.1 在飞书开放平台创建应用并开启机器人

飞书机器人属于「企业自建应用」，管理员权限不是必须，但有管理员权限会省很多事。创建应用后，先到「应用能力」里启用机器人，然后拿到 App ID 和 App Secret。

紧接着配置事件订阅。这里我踩了最久的一个坑：飞书要求回调地址必须在公网可访问，而且返回的响应体格式必须严格匹配。事件订阅里要添加的事件是im.message.receive_v1，这个是接收消息的入口，千万别选错成im.message.read什么的。

WorkBuddy 一般会提供一个 Webhook 地址，比如http://your-server:8080/webhook/feishu，把它填到飞书的「请求地址」里。飞书后台会先发一个 URL 验证请求，里面带challenge参数，你的 Webhook 必须原样返回这个值，否则保存时直接报错。如果你的 WorkBuddy 没有内置飞书协议解析，你需要在 Webhook 入口代码里手动处理：

def handle_feishu_event(event): if event.get("type") == "url_verification": return {"challenge": event["challenge"]} # 其他消息事件处理

我在这一步卡了差不多一小时，原因就是返回了标准 JSON，但忘记把challenge原样带上，飞书一直显示「验证失败」。

4.2 权限配置与机器人发布

飞书机器人的权限不是开了机器人就自动有的，需要到「权限管理」里开通至少这几项：

• im:message：读取消息内容
• im:message.send：发送消息
• im:chat:read：读取群信息

权限开通后，还必须发布应用版本，否则机器人只对开发者可见。这里有第二个容易踩的坑：即使你发布后，机器人也不能主动给用户发消息，必须用户先给机器人发一条消息，或者把机器人拉进群并 @ 它，飞书才允许机器人回复。这是平台限制，不是代码问题。

在群里测试时，建议建一个只有自己和小号的群，别在正式业务群调试。因为群消息里 @ 机器人才会触发事件，如果 @ 的是别人，你的 Webhook 不会收到事件，还会造成「为什么机器人没反应」的困惑。

4.3 怎么让机器人发送表格样式的结果

很多需求是让机器人把检索结果整理成表格发到飞书群里。这里要注意：飞书消息的text字段不支持 Markdown 表格，你需要用「消息卡片」的 Markdown 元素，或者直接发富文本 JSON。

最简单的方案是发送interactive类型卡片，里面用lark_md元素。由于 RAGFlow 返回的 chunk 数量、相似度都不一样，我通常只在需要对比时发送卡片表格，日常问答直接发纯文本回答。

一个简化卡片格式示例：

{ "msg_type": "interactive", "card": { "header": { "title": {"tag": "plain_text", "content": "知识库检索结果"} }, "elements": [ { "tag": "div", "text": { "tag": "lark_md", "content": "| 文件名 | 相似度 |\n| --- | --- |\n| 产品手册.pdf | 0.82 |" } } ] } }

实际测试下来，飞书卡片对lark_md的表格支持不算完整，如果列太多会被截断。我最终的做法是让模型把回答压缩成「问题 + 结论 + 参考来源」三段式纯文本，偶尔需要表格时才走卡片，兼顾稳定性和可读性。

5. 全链路联调：从发消息到拿回答

5.1 一次完整的请求链路排查

把 RAGFlow、WorkBuddy、飞书三端都配好后，开始联调。第一次测试建议在飞书群 @ 机器人发一条简单问题，比如「报销流程是什么」。然后按照链路逐步排查：

1. 飞书是否把事件送到 WorkBuddy Webhook：可以在 WorkBuddy 日志里看receive event日志
2. WorkBuddy 是否成功调用 RAGFlow：重点看日志里有没有retrieval请求和返回 chunk 数量
3. WorkBuddy 是否成功调用 LLM：注意生成耗时，如果超时，飞书会显示「操作失败」
4. 飞书是否成功回传消息：检查机器人有没有报权限错误

我通常在每个环节打印带时间戳的日志，比如：

2025-01-15 10:00:01 [feishu] receive msg from user: oc_xxx 2025-01-15 10:00:03 [ragflow] retrieval success, chunks: 3 2025-01-15 10:00:05 [llm] generation done, answer length: 186 2025-01-15 10:00:06 [feishu] message sent

这套日志能迅速定位问题。如果发现检索成功但回答为空，多半是 LLM 调用时的系统提示词没把检索片段作为上下文，或者片段里的内容和问题不相关。

5.2 常见问题速查表

我整条链路跑下来，遇到的高频问题基本可以归纳成一张表：

这里面最容易被忽略的是「RAGFlow 返回空结果」，我第一次遇到时一直以为是知识库没数据，后来才发现是dataset_ids传了名字，而 RAGFlow 要求的是数字或者 UUID 格式的 ID。获取真实 ID 的办法是在知识库列表页点击查看，留意 URL 里的参数，或者调 API 获取。

5.3 踩坑实录：本地部署与回调地址的取舍

这节聊聊最现实的部署问题。飞书回调地址要求公网可达，但 RAGFlow 是跑在公司内网或者你自己机器上的，两边不能直接用 localhost 互通。我的做法是：WorkBuddy 的 Webhook 服务和 RAGFlow 都部署在同一台云主机上，WorkBuddy 通过127.0.0.1访问 RAGFlow，飞书只访问 WorkBuddy 的公网地址。这样既不用暴露 RAGFlow 端口，也避免了内网穿透工具带来的不稳定。

如果你实在只有一台本地机器，也可以在路由器或防火墙上做端口映射，把 8080 端口映射到公网。但我不太推荐长期这么做，一来不安全，二来家里的公网 IP 经常变动。最稳的方案还是直接把服务部署到一台云主机，哪怕是低配的，也能跑。

另外，RAGFlow 的 Elasticsearch 对磁盘和内存敏感，云主机建议至少 8GB 内存，并且把日志文件做定期清理，否则跑一个月后/var/lib/docker会被日志撑爆。我踩过一次磁盘 100% 的问题，排查了半天才发现是 docker 容器日志无限增长，最后加了 logrotate 才解决。

结尾：一些个人体会

整套链路搭完回头看，真正花时间的不是任何单一组件的安装，而是组件之间的对接规范。飞书要标准 challenge，RAGFlow 要正确的 dataset ID，WorkBuddy 要合理设计 Skill 输入输出，每一环错的都是格式和约定。我的建议是先把最小链路跑通——飞书发一条消息，本地打印出一行日志，这就已经成功了一半；然后再逐步加上 RAGFlow、LLM、卡片格式，不要一上来就追求十全十美。后面如果要把这套东西往团队里推广，可以再加一层权限控制，按用户、按群去限制可访问的知识库范围，这样就不只是一个演示 demo，而是一个能真正沉淀业务知识的问答入口了。