MetaCore/FeishuAgent/README.md

本地局域网飞书机器人 (Gemma 4B + Feishu Ws)

这是一个完全“纯本地运行”的个人办公助手。 借用您的强大机器算力，以 Ollama + Gemma 4B 作为 AI 分析大脑，并以最新的 飞书长连接（无须内网穿透） 作为沟通控制桥梁。只需简单配置应用密钥并运行，它就可以自动回复所有单聊给它的消息内容，并能够智能寻找资料室的文件发送回去。

---

一、前期环境安装

1. 配置 Python 虚拟环境（推荐 3.9 以上）： 在终端（VS Code 或 CMD）进入本目录 D:\MetaCore\FeishuAgent 然后执行：

   pip install -r requirements.txt
   

2. 下载并开启 Ollama 引擎： 如果您还没有安装 Ollama，请访问 Ollama.com 下载 Windows 客户端。安装后，在您的终端执行以下命令拉取并运行 Gemma 4B（系统后台会自动驻留）：

   ollama run gemma:4b
   

   打开这一步后，即便把窗口最小化，本地服务 localhost:11434 也已经随时待命了。

---

二、配置属于你个人的飞书开发者应用

为了让该代码监听到事件，需要您上飞书开发者后台获取一把连接密钥：

1. 打开 飞书开发者开放平台企业自建应用页 并登录您的账号。
2. 点击右上角 “创建企业自建应用”（名称例如: MetaCore 资源机器人）。
3. 获取凭证：
   • 创建成功后，在首界面找到栏目里的 App ID 和 App Secret，将它们复制替换到本文件夹的 main.py 最顶端的相关变量里（或是以系统环境变量 FEISHU_APP_ID 存在）。
4. 开通机器人能力并赋予权限：
   • 侧边栏点开 添加应用能力 -> 开启 “机器人”。
   • 侧边栏点开 权限管理，在搜索栏按序申请以下权限然后点击开通：
     1. im:message:receive_as_bot (接收单聊消息)
     2. im:message 或 im:message:send_as_bot (发送单聊消息)
     3. im:file 与 im:resource （获取与上传图片或文件资源，此项很重要以确保能发附件）
5. 开启长连接订阅（极重要，否则接不到消息）：
   • 在侧边栏寻找 事件订阅 -> 将右上角的事件模式切换为主推长连接模式（WebSocket）。
   • 在下方的 “添加事件” 里搜索并勾选上 接收消息 - im.message.receive_v1。
   • 然后务必在左侧“版本发布”处，创建一个最新版本并审核发布您的应用。（对部分企业，自己免审秒过即可）

---

三、启动与测试

将需要被检索分发的“材料文件（Word、PDF、压缩包等）”，全部拖放归档到本目录的 materials\ 文件夹里。如果您还没创建，脚本执行时会自动帮您新建这一层文件夹。

启动你的大作：

python main.py

终端应出现 [ 服务状态 ] 长连接订阅已成功建立 字样。 此时，在你的飞书主界面搜索这个机器人的名字，然后和它说：“在吗”。 你又可以说：“给我发个元核服务器报价清单资料”。大模型会去分析匹配并尝试调出该文件，然后发送。

一切搞定了！祝您使用舒心！