# lark-bot

**Repository Path**: SparkPoon/lark-bot

## Basic Information

- **Project Name**: lark-bot
- **Description**: WG-Larkbot
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 器材管家 — 飞书 AI Agent 机器人

基于 DeepSeek API 的多功能飞书机器人，运行在 NAS Docker 上。

## 架构

```
飞书用户 → ngrok 公网 → NAS Docker → FastAPI → DeepSeek Agent
                                                    │
                                          ┌─────────┼─────────┐
                                          │         │         │
                                       器材管理   新闻简报   Skill 插件
                                          │         │         │
                                          └─────────┼─────────┘
                                                    │
                                               SQLite (lark_bot.db)
```

## 功能

| 功能 | 说明 |
|------|------|
| 📦 器材出库 | AI 引导多轮对话，选器材→数量→借用人→归还日期→自动通知 |
| 📥 器材入库 | 识别归还意图，查未归还记录，一键归还+通知 |
| 📋 库存查询 | 按分类查看，绿色可借红色借完 |
| ⚠️ 逾期预警 | 每天自动检查超期未归还，推送预警 |
| 📰 新闻简报 | 每日 9:00 推送四板块结构化新闻（DeepSeek 格式化） |
| 💬 AI 聊天 | DeepSeek Agent 自然对话，带长期记忆 |
| 🧩 Skill 插件 | 搜索/URL/AI 生成 → 安装 → 动态执行 |
| 🧠 记忆压缩 | 超过 15 条自动摘要，保留关键信息 |

## 项目结构

```
lark-bot/
├── main.py                  # FastAPI 入口 + webhook
├── lark_bot.py              # AI Agent（DeepSeek function calling）
├── equipment_service.py     # 器材管理 + 聊天记忆 + Skill 管理
├── news_service.py          # 新闻抓取 + DeepSeek 格式化
├── scheduler.py             # APScheduler 定时任务
├── database.py              # SQLAlchemy 引擎 + 初始化
├── models.py                # ORM 模型（7 张表）
├── config.py                # 配置管理
├── Dockerfile               # Docker 镜像
├── docker-compose.yml       # NAS 部署配置（bot + ngrok）
├── requirements.txt         # Python 依赖
└── .env.example             # 环境变量模板
```

## 更新流程

```
1. 本地改代码 → git push GitHub
2. Gitee 强制同步
3. NAS 重建 Compose（自动 git clone 最新代码）
   或者飞书发「更新」（容器有 git 且网络可达 Gitee 时）
```

## 数据库表

```
SQLite: /app/data/lark_bot.db
├── equipment           # 器材库存
├── checkout_record     # 出库入库记录
├── project_group       # 群配置（新闻推送等）
├── chat_memory         # 🧠 长期聊天记忆（按 chat_id 隔离）
├── skill               # 🧩 动态安装的插件
└── conversation_state  # 出库/入库对话临时状态
```

## 环境变量

见 `.env.example`，关键变量：

| 变量 | 说明 |
|------|------|
| LARK_APP_ID | 飞书应用 App ID |
| LARK_APP_SECRET | 飞书应用 Secret |
| DEEPSEEK_API_KEY | DeepSeek API Key（Agent + 新闻格式化） |
| DATABASE_URL | SQLite 路径（默认 data/lark_bot.db） |

## 飞书后台配置

1. 事件订阅 → `https://xxx.ngrok-free.dev/webhook`
2. 添加事件 → `im.message.receive_v1`
3. 权限 → `im:message:send_as_bot`
4. 发布应用