手把手教你搭一个工作智能体/机器人

先花三分钟：工作智能体到底是个啥？

在日常办公中，我们最怕的不是活多，而是频繁被打断和重复当复读机： - 找一份半年前的部门管理制度，要切出聊天窗口，在五个网页和网盘里来回搜； - 同事问某个业务流程或历史项目结论，你得放下手头的活，去翻几十页会议纪要； - 直接问 ChatGPT 或通用大模型？它根本不知道你们部门内部的规章和最新文档，甚至还会一本正经地“胡说八道”。

这就是“工作智能体”要解决的问题：把它装在团队每天都在用的飞书里，连接你指定的工作资料，让它“现查现答”。

它的核心底层其实就一句话：

智能体（Agent）= 大模型（脑子）+ 工具（手脚/数据源）+ 思考循环（ReAct）

  • 大模型是脑子：负责看懂问题，并判断“要回答这个问题，我需要调哪个工具去查什么数据”；
  • 工具是手脚与数据源：比如“搜索本地知识库”、“查公司制度文档”、“查日历日程”、“查特定表格数据”。每个工具都配一份写给人话的“使用说明书”；
  • 循环是灵魂（ReAct 模式）： 模型说“我要查 A 文档” → 程序真去执行搜索 → 把查到的段落喂回给模型 → 模型看后发现还缺数据，继续说“我还要查 B 表格” → 查完塞回 → 材料齐备，整理输出最终汇报。

小黑在环形轨道上指挥工具卡：循环思考

对比一下你就会发现： - 普通聊天 AI：直接根据历史记忆盲猜，容易编造幻觉； - 简单搜索插件：搜一次就直接交卷，搜不准就答偏； - 工作智能体：像一个靠谱的实习生，带着工具去查资料，查不够继续查，证据确凿才出报告。

飞书机器人则是它的工作载体——你在飞书单聊或群聊里发消息 @ 它，它去后台翻资料，把整理好的答案直接推回飞书。

整个架构极其轻量清晰：

飞书聊天窗口（你打字的地方，随时 @ 提问）

↓

机器人调度程序（跑在本地电脑或轻量服务器上，负责收发消息与工具调度）

↓

大模型 API（云端大脑）＋ 你的工作数据源（规章制度 / 周报 / 文档 / 本地笔记）

下面开始动手，全程四个步骤。

第一步：申请一个大模型 API Key（10 分钟）

智能体需要一个大模型作为“思考中枢”，我们通过 API（应用程序接口）调用它，用多少扣多少，非常便宜。

1.1 注册模型平台。 国内推荐使用 DeepSeek（推理能力强、支持长上下文、调用成本极低，个人日常办公测试一个月几块钱）： - 浏览器打开：platform.deepseek.com - 用手机号注册并登录后台。

1.2 创建 API Key。 - 进入左侧菜单「API Keys」（API 密钥）； - 点击「创建 API key」，输入一个备注（比如 feishu-agent）； - 系统会生成一串以 sk- 开头的密钥字符串。

1.3 立刻复制保存。

⚠️ 注意：这个 Key 只在创建完成时完整展示一次，弹窗关掉就无法再次查看（丢了只能删掉重新建）。请把它临时粘贴到本地记事本中。Key 相当于你的扣费钱包密码，绝不要发给他人或上传到公开代码仓库。

1.4 充值余额。 - 在左侧「充值」页面充个 10 块钱，足够你调试跑通几百次问答。

第二步：在飞书开放平台创建机器人应用（25 分钟）

这一步是让飞书平台给你的机器人发一张“工作工牌”。全程在网页上点击配置。

2.1 登录飞书开放平台。 - 浏览器打开：open.feishu.cn - 使用你的飞书账号扫码或验证码登录，点击右上角进入「开发者后台」。

2.2 创建企业自建应用。 - 点击「创建企业自建应用」（个人账号或公司账号均可正常创建）； - 填写应用名称（例如：“部门智库助手”或“小黑工作助理”），上传一个头像，写一句话描述； - 点击「创建」，进入应用配置主页。

2.3 获取飞书身份凭证。 - 在左侧「凭证与基础信息」中，找到： - App ID（形如 cli_xxxxxxxx） - App Secret（点击「查看」并复制） - 这两个字符串是飞书识别你程序的账号密码，和第一步的 sk- Key 一起保存好。

2.4 启用机器人能力。 - 点击左侧菜单「添加应用能力」 → 选择「机器人」 → 点击「添加」。 - 没有这一步，应用在飞书里就无法作为聊天对象接收和发送消息。

2.5 配置事件订阅（核心关键步）。 机器人怎么在飞书有人说话时收到通知？ - 点击左侧菜单「开发配置」 →「事件与回调」； - 把接收方式选择为「使用长连接接收事件」：

💡 为什么选长连接？ 传统方式需要你有公网 IP 服务器、独立域名和 SSL 证书，门槛极高；而飞书提供的长连接（WebSocket）模式，让机器人程序在你自己电脑上主动连接飞书服务器，不需要公网 IP、不需要域名备案、不用买云服务器，本地电脑开机就能跑！

  • 点击「添加事件」，搜索并勾选 im.message.receive_v1（接收消息事件），点击确认。

2.6 开通必要权限。 - 点击左侧菜单「开发配置」 →「权限管理」，搜索并开通以下权限： - im:message（读取用户发来的单聊/群聊消息） - im:message:send_as_bot（以机器人身份在会话中发送回复） - im:chat（获取群聊基本信息，用于群聊 @ 回复）

2.7 发布首个版本。 - 点击左侧菜单「版本管理与发布」 →「创建版本」； - 填入版本号（如 1.0.0）与更新说明； - 在「可用范围」里选择“所有员工”或“仅自己”（初期调试建议选自己）； - 点击「申请发布」。如果是个人自建租户会立即自动生效；如果是企业租户，联系企业飞书管理员通过审核即可。

✅ 自检清单： 机器人能力已开通 ✓ 长连接模式已勾选 ✓ im.message.receive_v1 已添加 ✓ 消息权限已开通 ✓ 1.0.0 版本已发布生效 ✓。

第三步：让 AI 编程助手帮你把程序跑起来（30-60 分钟）

不要被“写程序”吓退。现在有了 AI 编程助手（比如 Claude Code、Codex、Cursor 或任意支持终端交互的 AI 工具），你只需要提需求，代码全部由 AI 生成。

整个程序最小只需要三个文件： 1. requirements.txt：记录所需第三方库（飞书官方 SDK lark-oapi、大模型调用库 openai 或 requests、环境变量加载库 python-dotenv）； 2. .env：保存上面拿到的三串密钥； 3. bot.py：核心智能体运行脚本。

3.1 把结构化需求直接复制给 AI 编程助手：

“请帮我用 Python 编写一个飞书工作智能体程序。要求如下：

  1. 连接方式：使用飞书官方 SDK lark-oapi 的长连接（WebSocket / Client Mode）模式接收消息，无需本地起 Web 端口；
  2. 智能体核心（ReAct 循环）：
    • 接入 DeepSeek API（兼容 OpenAI 接口格式）；
    • 实现工具调用（Function Calling / Tools）循环：模型决定调工具 → 执行工具获取数据 → 结果追加回对话历史 → 再次请求大模型，直到模型输出最终文字；
    • 工具调用设置最大轮数兜底（最多 5 轮），防止死循环；
  3. 内置演示工作工具：
    • 工具 1：search_work_documents(query) —— 在本地指定的工作文档目录（如 data/docs/ 下的 markdown 或 txt 文件）中按关键词全文检索，返回最相关的段落与文件名；
    • 工具 2：get_current_time() —— 获取当前的系统准确日期与时间；
  4. 工作防幻觉系统指令（System Prompt）：
    • 明确要求：‘你是一名严谨的业务助理，回答必须严格基于工具查到的实际内容。如果检索结果中没有相关信息，请老实回答「未在当前知识库中检索到相关规定」，严禁凭空捏造事实。’
  5. 回复格式：使用飞书富文本格式（Post Message）回复给对应会话，并做好网络异常自动重试（重试 3 次）。
  6. 配置文件使用 .env 读取密钥。”

3.2 配置 .env 环境变量文件： 在项目根目录下新建 .env 文件，粘贴你的真实密钥：

1
DEEPSEEK_API_KEY=sk-你的DeepSeek密钥 FEISHU_APP_ID=cli_你的飞书AppId FEISHU_APP_SECRET=你的飞书AppSecret

3.3 依赖安装与启动： 在终端运行 AI 编程助手提供的安装和启动指令：

1
# 1. 安装依赖 pipinstalllark-oapiopenaipython-dotenv  # 2. 启动机器人 pythonbot.py

当终端控制台打印出 [INFO] Feishu WebSocket Client connected successfully... 时，说明你的工作智能体已经正式上线。

3.4 见证时刻：去飞书打个招呼。 打开手机或电脑飞书，在搜索框搜你的机器人名字，进入单聊发一句：

“你好，请帮我查一下上个月的文档写了什么？”

看着后台日志里模型自动调起 search_work_documents 工具、翻阅本地文档并把带出处的精准答案回复到飞书对话框时——你所搭建的就不再是一个冷冰冰的聊天窗口，而是一个真正有手有脚、能翻你资料的“数字同事”。

3.5 关键提醒：连上飞书 ≠ 马上能答业务问题，先喂数据。

很多朋友兴冲冲发完第一句提问，得到的却是“未在当前知识库中检索到相关规定”——这不是机器人坏了，而是它根本不知道你的资料放在哪。大模型本身没有你的部门制度、项目纪要，演示程序里的检索工具也只会翻 data/docs/ 这一个固定目录。想让它“懂业务”，先做两件事：

  • 把资料放进检索目录：把部门制度、常见问答、项目纪要等整理成 .md 或 .txt 文件，放进 data/docs/。文件名本身就是检索线索，建议按“主题 + 日期”命名（如 2026差旅报销标准.md），别用“新建文档1”这种无效名字；
  • 让工具说明书和资料对得上：修改工具函数的 description，写清楚这个目录里到底存了什么（见第四步第 1 节），大模型才知道什么时候该翻这批资料。

放好资料重启程序，同一个问题再问一遍，答案立刻就不一样了。之后你每补充一批新文档，它的能力圈就扩大一圈——智能体的业务能力，本质上是喂出来的。

小黑扎破

第四步：从“能跑”到“好用”的实战调教

搭建出原型只需要一个小时，但要让它在真实工作中越用越顺手，关键在日常的低代码调教：

. 工具描述必须“说人话”

大模型挑选工具完全依赖工具函数上的 description（说明书）。

  • ❌ 差的描述：“query_doc_01: 查询文档库内容。”

  • ✅ 好的描述：“search_policy_docs: 检索公司人事、财务、考勤及日常行政制度文件。当用户询问休假天数、报销额度、采购流程时优先调用该工具。”

说明书写得越清晰，大模型在复杂问题下的工具选择命中率就越高。

小黑把乱码旧标签换成

. 循序渐进搭建你的“工作工具箱”

工作智能体的威力取决于你给它开了多少扇窗：

  • 第一周（知识查询）：接本地工作文档、常见问答库（FAQ）、产品白皮书；

  • 第二周（办公协同）：增加查日历日程工具、飞书多维表格数据查询工具；

  • 第三周（自动化处理）：增加自动生成周报模版、提取待办事项等执行动作。

每加一个新能力，只需要让 AI 编程助手“帮我在 bot.py 里新增一个查 XX 的工具函数并注册到工具列表中”，连核心框架都不用动。

. 企业工作环境的安全红线

在把机器人推广给团队其他同事前，牢记三条安全底线：

  • 数据保密：公司未公开的商业机密、敏感个人隐私数据，切勿直接上传到未经合规审批的公共公有云 API；

  • 权限最小化：飞书应用权限按需开通，先开单聊私聊测试，验证稳定后再拉入特定业务群；

  • 事实边界兜底：在 System Prompt 里反复强调“不瞎猜、严禁捏造”，对于查不到的事实宁可报空，也不让错误的 AI 回答误导业务决策。

我踩过的三个坑，帮你提前绕开

坑一：试图用固定规则做“意图分类路由”。 我最初写过死板的 if "报销" in text: run_baoxiao() 路由逻辑，结果稍微换个问法（比如“出差花了钱怎么弄”）就直接趴窝。一定要信任大模型的自主决策能力——把工具清单和说明书整齐地摊给它，让它自己理解语义并循环调度，灵活性有质的飞跃。

坑二：直接发 Markdown 纯文本导致排版灾难。 飞书客户端的普通单条文本消息不会解析标准 Markdown 语法，你的 **加粗**、### 标题、列表项都会原封不动带星号展示。必须封装成飞书的富文本消息（Post 格式）或消息卡片（Interactive Card），排版清晰、层级分明，在手机端阅读体验才会好。

坑三：把一次失败当成模型笨。 一次复杂业务提问背后往往伴随 2~4 次工具检索。如果偶尔回答不理想，先去控制台看完整的运行日志（它调了哪个工具？工具返回了什么数据？）。90% 的问题都是因为搜索关键词没给对或文档源里根本没有这句话，而不是大模型智商不够。

总结与行动清单

整个搭建流程浓缩成一张清单：

步骤 耗时 核心产出 关键要点
① 大模型 API Key 10 分钟 sk- 密钥串 推荐 DeepSeek，性价比高、推理能力强
② 飞书建应用 25 分钟 App ID + Secret 务必选择长连接接收事件，免服务器公网 IP
③ AI 写代码并运行 30 分钟 bot.py + .env 把结构化需求丢给 AI 编程助手，本地一键启动
④ 业务工具调教 持续迭代 懂业务的数字助手 工具说明书说人话，严格设定防幻觉规则

搭建工作智能体的门槛从来不在深奥的技术代码，而在于你想清楚了在工作中要它帮你分担什么重复劳动。

你最清楚你每天要翻哪些资料、要回答同事哪些高频问题——而这，正是你能为自己和团队搭出一个“最接地气、最懂业务”的工作智能体的核心壁垒。