YiMao · Telegram 影视求片助手

⚠️ 更新提示

更新前请务必阅读 更新指南，避免数据丢失。

简介

YiMao（云海影视助手）是一个 Telegram Bot，把"找片—求片—等片—看片"这条链路全部搬进聊天窗口：

• 搜片：直接发片名，Bot 返回 TMDB 候选，点进去看详情。
• 求片：详情页一键发起，走管理员审核 + 配额控制，通过后由 MoviePilot 自动下载。
• 等片：候选列表有"预产期灯牌"给心理预期；搜不到的片可以丢进许愿池，找到源主动私信通知；多人想看的同一部片可以拼车 +1。
• 看片：入库后自动推送通知；追剧能看到集数进度条；还有每日入库汇总、每周观影周报。

下载、刮削、入库由 MoviePilot 负责，媒体库与入库回调由 Emby / Jellyfin 提供，YiMao 是把这套后端能力包装成"人话"交互的前台。

隐私保护：搜片、求片、进度、配额等个人操作在私聊中进行；群组仅用于接收入库通知、拼车到货提醒和公告。

✨ 核心功能

🔍 智能搜片

私聊直接发送片名（中英文均可），返回 TMDB 候选列表；点击进入详情页查看简介、年份、海报，并决定是否求片。也支持 🔥 本周热门 / 📺 热门剧集 / ⭐ 必看神作 / 🆕 最新上映 / 🎲 随机探索 等精选入口。

🎬 求片（审核流 + 配额）

详情页点「求片」即可发起请求：

• 绑定校验：首次需用 /link 用户名 密码 绑定 MoviePilot 账号。
• 配额扣减：电影扣 1，剧集扣 3（一整季对服务器资源消耗更大），每日 00:00 重置（按访问惰性刷新）。默认电影/剧集各 2 个/天。
• 去重提醒：媒体库已存在或已有相同请求时会提示，可选择"仍要订阅"。
• 审核流：请求进入管理员审核，管理员可 ✅ 批准 / ❌ 拒绝。批准后调用 MoviePilot 下单；若下单失败会标记为 stuck（兜底保留，可重试，不会丢单）；拒绝时自动返还配额。

🚦 候选预产期灯牌

浏览某部片的候选资源列表时，根据已扫到的站点做种情况给出一个轻量"状态灯牌"（只给预期、不承诺精确时间）：

📈 剧集进度条

追剧时在入库通知里展示集数进度条，如 📈 已更 S03E07/S03E16 ▓▓▓▓░░░░ 44%（距完结还差 9 集），完结显示 100%（已完结）。分母取自 TMDB 当季实际集数，支持本季 / 全剧双口径。

🙋 拼车 +1

详情页点「我也想看」，把自己加入这部片的拼车列表，并提示"已加入，共 N 人想看"。该片到货时会在群里 @ 拼过车的用户。

🌟 许愿池（/wish）

搜不到的片可以许愿，找到源第一时间通知你：

• /wish 片名 入池：TMDB 强校验匹配、与现有订阅去重、容量上限（每人 20 条 / 全局 500 条）。
• /wish（无参）列出"我的许愿"，可取消。
• 众筹计数：同一部片多人许愿会合并，重复许愿时提示"目前 N 人在等，出源会自动通知你"。
• 定时重搜：调度器约每天对每条许愿重搜一次（错峰），命中（做种数 ≥ WISH_MIN_SEEDERS）后主动私信许愿人"🎉 你许愿的影片出源啦！"并附「🎬 立即求片」按钮；其他许愿者也会收到提醒。出源后仅通知不自动求片，需用户点按钮确认后才走求片流程。
• 超期处理：入池 WISH_EXPIRE_DAYS（默认 30）天仍无源会做一次最终重搜，仍无源则取消并私信发起人。

状态机：PENDING → SEARCHING → FOUND → NOTIFIED → FULFILLED，旁路 EXPIRED（超期/放弃）/ ORPHANED（用户退群/不可达）。

📋 我的请求（聚合视图）

/requests（或 /watchlist）把分散的状态聚合成一页，按状态分组展示并标出计数：

• 【进行中】：审核中 / 下载中 / 搜索中等
• 【许愿中】：许愿池里待出源的条目
• 【已完成】：已入库
• 【异常/失败】：失败 / 已取消

数据同时来自 MoviePilot 订阅、待处理的审核单和许愿池，避免来回切界面查状态。

🎬 AI 推荐 · 今晚看什么

点「🎬 今晚看什么」或发送 /ai，进入一次性 AI 对话模式，把口味/心情用一句话告诉 Bot（如"想看烧脑悬疑、别太长"），由 AI 帮你挑片。需配置 AI Key 或将 AI_ENABLED=true。

说明：AI 推荐是按钮/命令触发的交互，不存在"AI 电台主动定时推送"。系统自带的每日 9:00 推荐是基于 MoviePilot 热门榜（非 AI 生成），且受用户通知开关控制。

📊 观影周报

每周一 9:00 自动生成并按用户通知开关推送（也可在通知设置中开关）。内容包括本周搜索/求片/通过数、剩余配额、行为标签、热搜关键词、类型偏好与专属建议。

🔔 通知设置与每日汇总

「设置 → 通知设置」可单独开关：入库通知 / 每日推荐 / 周报 / 公告。每日 DAILY_SUMMARY_HOUR（默认 21:00）推送当天的入库汇总。

🤖 /status

查看 Bot 运行状态：版本、服务端时间、当前用户 ID、聊天类型、是否管理员。

⌨️ 命令速查

管理操作（审核、配额管理等）通过菜单内「🛠️ 管理」入口进入，仅管理员可见。

🚀 快速开始

方式一：Docker（推荐）

# 1. 准备配置
cp .env.example .env
vim .env        # 至少填写 TELEGRAM_BOT_TOKEN / MOVIEPILOT_URL / MOVIEPILOT_API_KEY

# 2. 拉起（host 网络，便于访问内网 MoviePilot / Emby）
docker compose up -d

# 3. 查看日志
docker compose logs -f

docker-compose.yml 默认使用 network_mode: host，数据持久化到 ./data。

方式二：本地构建运行

# 需要 Go 1.24
go build -o yimao ./cmd/bot
export $(grep -v '^#' .env | xargs)
./yimao

服务默认监听 :8080，提供 /health 健康检查。首次部署后，用 /link 绑定的第一个用户会自动成为管理员，也可用 ADMIN_USER_IDS 预先指定。

⚙️ 配置说明

所有配置通过环境变量提供，完整示例见 .env.example。

核心（必需）

MoviePilot（必需）

Emby / Jellyfin（可选但推荐）

配额 / 会话

配额额度（电影/剧集每人每日上限）由服务在运行时管理（默认各 2，电影扣 1、剧集扣 3），并可与 MoviePilot 同步。

许愿池（WISH_*）

预产期灯牌（ETA_*）

AI（可选）

通知 / 调度

其他

📦 部署指南

服务端点

• GET /health、GET /api/health：健康检查
• POST /webhook、/telegram-webhook：Telegram 更新（Webhook 模式）
• POST /webhook/emby、/webhook/moviepilot、/webhook/mp、/webhook/jellyseerr、/api/summary：媒体后端入库回调

在 Emby/Jellyfin 与 MoviePilot 中配置对应 Webhook 指向上述地址，YiMao 即可在入库时推送通知、更新剧集进度、触发拼车与许愿出源逻辑。若设置了 WEBHOOK_SECRET，回调请求需携带签名。

数据持久化

运行数据（配额、管理员、偏好、反馈、许愿池 SQLite 等）保存在 DATA_DIR（容器内默认 /app/data，已挂载到 ./data）。升级前请备份该目录。

更新

更新前务必阅读 docs/UPDATE.md，按指引迁移数据后再拉取新镜像 / 重新构建。

🧱 技术栈与架构

• 语言/运行时：Go 1.24，单二进制，Docker 多阶段构建（alpine 运行）
• 存储：本地 JSON（配额/管理员/偏好等）+ SQLite（modernc.org/sqlite，纯 Go，免 CGO；许愿池、搜索历史等）
• 交互：Telegram Bot API（轮询 / Webhook 双模式）
• 后端集成：MoviePilot（搜索、订阅下载、热门榜）、Emby/Jellyfin（媒体库查重、入库回调）、TMDB（元数据）
• 后台任务：每日推荐（9:00，热门榜）、每日入库汇总（DAILY_SUMMARY_HOUR）、每周周报（周一 9:00）、许愿池每分钟错峰重搜与过期清理

更多设计细节见 docs/（ARCHITECTURE.md、FEATURES.md、COMMANDS.md、DEPLOY.md 等）。

License

MIT