Bot 使用指南
本页是 Spore Telegram Bot 的使用入口，面向终端用户和管理员，覆盖：申请使用、发送链接、全部命令、任务进度、媒体与相册行为、配额限流、频道绑定、频道加入、取消任务和常见提示。
相关页面：
1. 使用前提
- Bot 只在私聊中工作。群组、频道里发送的内容会被忽略。
- Bot 只读取文字消息。直接发送图片、视频等媒体给 Bot 不会解析，Bot 会回复"现阶段只支持发送文字消息链接"。
- 使用需要经过审批：向 Bot 发送
/start提交申请，管理员在 Web 管理端批准后，Bot 会私聊通知你。审批结果通知失败不影响审批本身。
用户状态与对应表现：
| 状态 | 发送 /start 或链接时的表现 |
|---|---|
| 未申请 | 创建待审批申请，携带你的 Telegram 用户名和昵称 |
| 待审批 | 刷新申请时间（重复发送无副作用），提示等待审批 |
| 已启用 | 正常使用，/start 返回欢迎与帮助信息 |
| 已停用 / 已归档 | 提示账号已停用 |
2. 发送消息链接
2.1 支持的链接写法
把 Telegram 消息链接直接发给 Bot 即可。以下写法都支持：
| 形式 | 示例 |
|---|---|
| 公开频道/群组消息 | https://t.me/durov/120、t.me/durov/120 |
| 私有频道消息（内部 ID） | https://t.me/c/1234567890/456 |
telegram.me 域名 | telegram.me/durov/120 |
带 www 前缀 | www.t.me/durov/120 |
带 /s/ 前缀 | t.me/s/durov/120 |
省略 http:// / https:// | t.me/durov/120 |
补充规则：
- 链接前后可以有其他文字或中文标点，例如"看这个 https://t.me/durov/120 转给我"。
- 链接上的查询参数（
?...）和锚点（#...）会被忽略。 - 公开链接的用户名为 4–64 位字母、数字或下划线；消息 ID 和私有频道内部 ID 为正整数，最多 16 位。
- 处理时统一按规范化后的
https://t.me/...链接记录与去重。
2.2 一次提交多条链接
一条普通消息可以包含多个链接，/download 也可以携带多个链接并上传到同一目的地。Bot 按出现顺序为每条有效链接独立创建请求；提交频率按整条输入检查一次，去重、日额度、并发和队列限制仍逐条计算，因此同一批次允许部分成功、部分失败，提交结束后会返回汇总。
默认每次最多处理 10 条有效链接，管理员可在「运行设置」中调整为 1–50 条。超过当前上限时整批拒绝，不创建任务、不扣额度；请拆分后重新发送。非法片段不计入条数，重复出现的有效链接仍分别进入校验。
当前不支持：消息 ID 区间抓取、按日期范围抓取、话题（Forum Topic）与回复线程归属保留。/cancel 仍一次只取消第一条有效链接。
2.3 来源访问权限
- 公开链接：由系统登录的读取账号解析并拉取消息。
- 私有频道链接（
t.me/c/...）：不要求你本人加入了该频道，要求的是系统的读取账号能访问。读取账号未加入时，Bot 会提示使用/join让它加入。
关于"受保护内容"：Spore 不使用 Telegram 的转发/复制通道，而是读取账号取数后重新下载媒体并构造新消息发送。能否提取取决于读取账号是否有权限访问该消息。
2.4 引用回复操作任务（/pin、/cancel）
/pin 与 /cancel 支持作为对 Bot 消息的回复发送（Telegram 原生命令用法）：长按/右键回复 Bot 发出的任务消息（进度提示、投递结果、失败通知）再输入命令，命令即作用于该消息对应的任务，无需复制链接。消息坐标落库后跨重启有效；功能上线前的历史消息、其他 bot 发出的消息查不到时会返回引导文案。
/cancel回复在途任务的任意消息 → 取消该任务（进度提示、已送达的部分消息均可回复）/pin回复在途任务的消息 → 补置顶标记，任务完成时副本照常置顶/pin回复已完成任务的投递消息 → 按落库的频道副本坐标事后补置顶（逐目标执行并回写结果；完成时无频道副本则提示无法补置顶）- 命令带链接参数时优先按链接处理，回复被忽略；无参且不是回复任务消息时进入 ForceReply 输入引导，可查看用法或取消
2.5 置顶+转存网盘（/pin 输入引导）
云盘功能开启时，通过 /pin 的输入引导（无参发送 /pin 后回复粘贴链接）提交会先弹出提交方式选择：
- 📌 仅置顶：与直接发送
/pin 链接完全一致，只做转发与置顶。 - 📌☁️ 置顶+转存网盘：同一链接同时提交两个任务——先转发置顶，再把媒体上传到网盘默认目的地（需要账号有云盘下载权限）。两个任务各占一次每日额度；云盘任务优先级较低，仅在无转发任务排队时执行，因此确认消息会稍后到达。
云盘功能关闭、账号无下载权限或未配置默认目的地时不会出现选择按钮（或自动降级为仅置顶并提示）。需要指定非默认目的地时，请单独使用 /download 目的地 链接。
3. 命令总览
Bot 命令菜单均需在私聊中使用。命令支持 /命令@机器人用户名 的写法，也可携带参数；无法识别的首个词会按链接解析；/pin、/cancel 还支持作为对 Bot 消息的回复发送（见 2.4 节）。
| 命令 | 说明 |
|---|---|
/start | 申请使用；已启用用户显示欢迎与帮助 |
/help | 查看使用帮助 |
/usage | 查询今日已用额度、限额、剩余次数和重置时间 |
/status | 查看服务运行状态（读取账号连接、大文件通道、数据库、队列等） |
/health | 健康自检 |
/cancel <链接> | 取消该链接的在途任务；也可回复任务消息直接使用 |
/download [目的地] <链接> | 下载到网盘而不是重发到 Telegram；无参时可回复链接并按启用目的地自动选择/弹出选择按钮，详见下载功能 |
/pin <链接> | 提交任务并在成功后置顶到绑定的频道/群组；也可回复任务消息使用（在途补标记、已完成补置顶）。无参进入输入引导时还可选择「置顶+转存网盘」一并上传到默认目的地（云盘功能开启时），见 下载功能 |
/bind <频道> | 绑定频道，任务成功后同步副本 |
/unbind <频道> | 解绑频道 |
/channels | 查看已绑定的频道列表 |
/join <邀请链接> | 让系统读取账号加入频道 |
/watch <频道> | 添加监听源频道/群组，新消息自动预热缓存 |
/watchlist | 查看我的监听源与邀请申请状态 |
/unwatch <频道> | 移除我的监听源 |
4. 任务处理与进度
提交链接后的流程：
- Bot 先回复一条"正在获取消息..."占位消息。
- 任务通过准入检查后进入队列（队列满会直接提示，不发送占位）。
- 读取账号拉取消息、标准化文本与媒体、下载媒体。
- 通过 Bot API（或大文件直传通道）发送给你。
- 成功或失败后删除占位消息。
进度显示：
- 占位消息约每 5 秒检查一次，内容有变化才编辑；显示下载、上传两行的百分比和字节数。
- 纯文本任务、无占位消息的任务不显示进度。
- 进度只保存在内存中，服务重启后自然消失。
超时与中断：
- 拉取消息的超时为 15 分钟；发送窗口为 15 分钟加上每 1MB 约 1 秒，最长 2 小时。
- 服务重启时，未完成任务标记为"已中断"，Bot 会提示重新发送链接；管理员也可以在管理端对失败的请求发起重试（累计尝试上限默认 3 次，可在「运行设置」页配置为 1–10；已达上限的请求可在消息记录详情页重置尝试计数后再次重试）。
5. 支持的内容类型
5.1 文本消息
原样重发文本（保留加粗、斜体、下划线、删除线、代码、代码块、引用、剧透、链接等格式），顶部附"原消息"链接。
- 正文上限 4096（UTF-16 单位），媒体说明文字上限 1024，超限会截断并提示"原文过长已截断"。
5.2 媒体类型
| 类型 | 支持 | 说明 |
|---|---|---|
| 图片 | 支持 | 官方 Bot API 模式下超过 10MB 的图片按文件发送 |
| 视频 | 支持 | |
| 文件 | 支持 | |
| 音乐 | 支持 | |
| 语音 | 支持 | |
| GIF 动图 | 支持（按视频处理） | video/mp4 动图按视频发送 |
| 贴纸、投票、联系人、位置、故事等 | 不支持 | 提示"暂不支持这种消息类型" |
| 网页预览 | 未确认 | 当前实现没有专门的网页预览处理分支，带网页预览的消息可能按不支持处理，请以实际表现为准 |
5.3 相册
- 发送相册中任意一条消息的链接即可识别整组，按消息 ID 升序发送。
- 相册最多 10 项；不会自动拆分成多个相册。
- 只有图片和视频能整组发送；包含文件、音乐、语音的相册会退化为逐条单独发送。
- 每条成员保留各自的说明文字；"原消息"链接只附在第一条。
- 任一成员下载失败时，整组任务失败。
6. 大小限制与发送通道
| 场景 | 行为 |
|---|---|
文件超过 MAX_FILE_SIZE（默认 2000 MiB） | 下载前直接拒绝，提示超过大小上限 |
| 不超过 50MB（官方 Bot API 模式） | 由 Bot API 直接发送 |
超过 50MB 且不超过 MAX_FILE_SIZE | 走机器人账号的 MTProto 直传通道；该通道未就绪时提示"大文件发送通道暂不可用"，小文件不受影响 |
配置了本地 Bot API 服务器（BOT_API_URL） | 上传上限放宽到 MAX_FILE_SIZE，不再使用 MTProto 直传 |
说明：
- 20MB 以内的媒体边下边传（流式），更大的媒体先下载到内存或临时文件再上传，临时文件在任务结束后清理；同时下载共享一个进程级"内存预算"（管理端运行设置可调），预算不足的文件自动改走临时文件路径，多任务并发也不会把内存占满。
- 云盘下载（
/download）同样受MAX_FILE_SIZE限制，并不绕过 Telegram 下载上限。 - Bot API 的媒体上传遇到限流不会自动重试（媒体数据只能消费一次）；轻量文本操作最多自动重试一次。MTProto 侧的限流会自动等待重试，仍失败时提示"请求过于频繁"。
7. 配额、限流与去重
每次提交链接（含 /download）都要通过同一套准入检查：
| 步骤 | 检查 | 默认值 |
|---|---|---|
| 1 | 账号状态为已启用 | — |
| 2 | 链接不在去重窗口内 | 窗口默认 10 分钟 |
| 3 | 距上次提交超过间隔 | 10 秒 |
| 4 | 当日额度未用完 | 50 次/天 |
| 5 | 未完成任务数未达并发上限 | 2 个 |
| 6 | 内存队列未满 | 容量默认 64 |
规则：
- 被拒绝时不创建任务、不扣除额度。
- 额度按运营时区（默认
Asia/Shanghai）每日重置；失败和取消不返还额度。 - 去重只针对"投递到 Telegram 的成功记录"：窗口内重复提交同一条链接会提示"该链接刚刚已处理"。失败和取消的记录不进入去重。
- owner（号主）跳过间隔、额度、并发三项检查，但仍受账号状态、去重和队列满约束。
/usage可查询当日已用、限额、剩余和重置时间；owner 显示为不限额度。- 管理员可在管理端为单个用户调整以上限额。
8. 缓存频道复用
8.1 效果与行为
- 任务成功时会把结果保存一份"干净副本"到缓存频道（不含任何用户的频道脚注）。
- 之后任意用户再次发送同一条链接，可直接从缓存频道复制结果，不限媒体大小，相册保持整组，速度更快。
- 绑定了频道的用户命中缓存时，会额外补上自己的频道脚注。
- 缓存条目不存在或复制失败时，自动回退到完整的下载上传流程，任务仍会正常完成。
- 可在管理端"频道设置"中开关；未配置缓存频道时始终走完整流程。
8.2 一次性配置步骤
- 用管理员账号新建一个频道（可直接建私有；或先建公开、配置后再转私有——数字 ID 不变，转私有后照常使用）。
- 把 Bot 拉进该频道并设为管理员（只需发消息权限）。
- 打开 Web 管理端「频道设置 → 缓存频道（重复链接复用）」，填入
@用户名、t.me 链接（公开频道）或-100数字 ID（私有频道；可从管理端频道列表复制，或把频道消息转发给@userinfobot查询），点「验证并保存」——服务端解析并校验 Bot 已是管理员后，保存数字 ID 与标题，即时生效、无需重启。
也可以在 .env 里预置 DUMP_CHANNEL_ID（仅作 Web 配置为空时的兜底，详见配置参考）。
8.3 安全边界
- 不配置则完全没有复用（每次完整下载上传）；启用开关与去重窗口都在管理端「频道设置」页（清空频道配置同样关闭复用）。
- 缓存频道会累积所有成功投递的副本；副本集中存放于该频道，账号封禁会连带失效，敏感度与管理员 Session 同级，勿公开该频道。
- 缓存频道不能开启 Telegram 的「限制保存内容」（限制转发）：复制会失败并回落完整下载上传；当前实现不会在启动时预检该设置。
9. 绑定频道同步
9.1 绑定命令
/bind <频道>：目标可以是@用户名、t.me/频道链接、t.me/c/<内部ID>（可带消息段）、t.me/+…/t.me/joinchat/…私有邀请链接，或-100开头的频道 ID。- 使用邀请链接时，系统会先确认链接指向频道/超级群组，再让读取账号实际加入以解析频道 ID；邀请无效、已过期或指向普通群组会直接拒绝。若频道开启加入审核，请先等待频道管理员批准读取账号加入，再重试
/bind；也可改用t.me/c/…或-100ID。 - 邀请链接不会自动添加 Bot。仍须人工把当前接收
/bind的机器人加入目标并授予所需管理员权限；Web 绑定则校验主机器人。 /unbind <频道>：只能解绑自己名下的频道。/channels：查看已绑定频道，展示公开链接或私有频道内部链接。
前置条件：
- 仅已启用用户可绑定。
- Bot 必须是目标频道的管理员且拥有发帖权限，否则提示先把它设为频道管理员。
- 一个频道只能绑定给一个用户。
- 绑定数量有上限：普通用户默认 1 个，owner 默认 3 个，管理员可在管理端按用户调整。
9.2 同步行为
- 任务成功后，已发给你的消息会被复制到你的绑定频道；文本和媒体末尾会附频道脚注（形如「📢 频道」，每个频道独占一行，公开频道显示可点击的用户名，私有频道显示标题和内部链接）。
- 置顶结果确认（含
/pin回复补置顶）里的频道名同样是可点击链接，多个频道逐行列出。 - 频道副本是尽力而为：单个频道复制失败只记录日志，不影响你收到消息，也不构成与用户消息的原子双投递。
10. 监听源预热（/watch）
用途：把你管理的频道/超级群组配置为监听源——bot 接收源内新消息并自动转存一份到缓存频道，之后任何人把该源的消息链接发给 bot 都直接命中缓存复用秒回（无需等下载上传）。
- 前提：先把 bot 加为该频道/群的管理员（管理员身份保证 bot 能收到全部消息；超级群组若不加管理员，需在 BotFather
/setprivacy关闭）。 - 目标支持频道与超级群组，可配置多个监听源；受保护内容（开启"禁止转发"）的源会自动改走读取账号下载重传管线（需读取账号能访问该源）。
- 支持私有邀请链接（
t.me/+…、t.me/joinchat/…）：提交后进入邀请申请流程——审批通过（或免审批）时系统读取账号经邀请加入目标；若该频道开启了"加入需审核"，则等待频道管理员批准后自动继续。注意平台边界：邀请链接只能让读取账号加入，Bot 不会被自动拉入，仍需人工把 Bot 设为频道/群管理员；读取账号加入后 Bot 管理员校验通过，监听才正式生效（期间申请处于"等待 Bot 管理员权限"状态，配置完成后自动/手动重试生效）。 - 管理端为独立「监听源」菜单组：「监听源管理」页直接添加（支持公开标识与私有邀请链接，不受上限约束）、审批用户申请与邀请申请、重试等待中的邀请申请、暂停/删除；监听源列表与邀请申请均支持状态/关键词筛选（「查询」按钮生效），监听源列表支持批量同意/拒绝/暂停/恢复/删除。「监听源配置」页管理申请开关、审批模式与上限（总数缺省 20、每用户缺省 3），即时生效；「监听记录」页是逐次转储留痕（哪个 Bot、哪个源、消息直链、路径与关联请求），支持按源/按方式筛选、单条与批量删除留痕（不影响已缓存副本）。移出 Bot 经监听源删除流程处理（全部机器人退出源并删配置）。
- 业务统计页的「监听源」页签：源状态计数、按源/按 Bot/按用户的转储聚合与按日趋势，随页首时间范围与机器人筛选查询。
/watch不带参数查看我的监听源与邀请申请状态；/unwatch移除自己的源（任意状态）。
权限边界（与 /join 相反）：/watch 要求用户已 /start 通过（enabled），申请默认需号主审批（可配免审批）；每用户上限与总上限同时约束普通监听源与邀请申请（活动中的邀请申请计入上限）。
11. 频道加入（/join）
用途：让系统的读取账号加入频道（例如访问私有频道取数需要读取账号可见）。
- 输入支持
t.me/+分享链接、t.me/joinchat/...或裸邀请码。 - 功能默认关闭，管理员需在管理端"受邀设置"中开启。
权限边界（与其他命令不同）：
/join不检查用户的"已启用"状态：功能开启时，待审批或未授权用户也可能提交加入申请或直接加入。管理员应结合这一差异决定是否开启该功能。
审核与结果：
| 场景 | 行为 |
|---|---|
| owner | 即时加入 |
| 普通用户（默认开启审核） | 提交申请，号主在管理端审批后实际加入 |
| 关闭审核 | 普通用户直接加入 |
| 请求制邀请链接 | 提示已向频道管理员发送加入请求，等待 Telegram 侧批准 |
| 已是成员 | 直接提示 |
补充：
- 实际加入动作由读取账号完成；加入成功后按配置自动静音、归档。
- 最大同时加入频道数默认 20。
- 被外部拉入的频道会按配置补静音/归档；"自动退出外部拉入频道"默认关闭。
- 读取账号自己创建的频道、超级群组跳过自动静音与归档；已被旧版本处理的对话需在 Telegram 客户端手动取消归档、恢复通知。
- 创建者的频道无法退出。
12. 云盘下载（/download）
text
/download <t.me 消息链接>
/download <目的地名称> <t.me 消息链接>与普通链接的差异：
- 成功后发送确认文本，不会把媒体重发到 Telegram，也不生成频道副本和脚注。
- 共用同一套准入检查（状态、去重、间隔、额度、并发、队列），此外还需要：管理员开启云盘功能、rclone 可用，以及你的账号被授予云盘下载权限（默认仅 owner）。
- 未授权、待审批或已停用用户看到与普通链接相同的提示，不会暴露云盘功能是否存在。
目的地的配置、网盘账号、备份恢复和排障见下载功能。
13. 取消任务
/cancel <原消息链接>：取消你提交的、该链接对应的所有排队中和处理中的任务，并返回取消数量（0 个时提示无进行中任务）。- 也可以回复 Bot 发出的任务消息（进度提示、投递结果、失败通知）直接发送
/cancel，取消该消息对应的任务，无需复制链接（见 2.4 引用回复操作任务）。 - 取消不返还当日额度；请求记录保留，可在管理端查看。
- 已停用的用户仍可以取消自己在途的任务。
- 管理员也可以在管理端单条或批量取消请求。
取消后的画面：占位消息不会被删除，而是改为"任务已取消"并附删除线的来源链接。
14. 服务状态与健康
| 命令 | 内容 |
|---|---|
/status | 用户号连接、大文件直传通道、数据库、队列水位、处理中数量、worker 数 |
/health | 健康判定：用户号连接正常 + 数据库正常 + worker 在运行 |
- 大文件直传通道未就绪不会让
/health变为不健康，也不会影响文本和小文件；它只影响超过 Bot API 上限的媒体。 /status输出经过脱敏，不包含链接、Session 等敏感信息。
15. 常见提示与错误
Bot 的失败提示都是受控中文文案，底层错误细节只写日志。任务执行失败的提示会附带来源链接（可点击），一次处理多条链接时可据此区分是哪条失败了。常见对应关系：
| 提示要点 | 含义与处理建议 |
|---|---|
| 无法识别有效的 t.me 消息链接 | 链接格式不受支持，检查写法 |
| 找不到这条消息 | 消息已删除或链接无效 |
| 无法访问该频道 | 读取账号无法访问，可用 /join 让它加入 |
| 这是一条服务消息 | 目标是加群/置顶等服务消息，无可提取内容 |
| 暂不支持这种消息类型 | 贴纸、投票等类型不在支持范围 |
| 文件超过大小上限 | 超过 MAX_FILE_SIZE，详见配置参考 |
| 临时目录空间已满 | 管理员需清理或调整临时目录容量 |
| 媒体下载失败 / 发送失败 | 多为暂时性错误，可稍后重试或请管理员重试 |
| 请求过于频繁 | Telegram 侧限流，稍后再试 |
| 大文件发送通道暂不可用 | 大文件直传通道未就绪；小文件不受影响 |
| 当前任务较多 | 队列满，稍后再试 |
| 该链接刚刚已处理 | 去重窗口内重复提交 |
| 提交过于频繁 / 今日额度已用完 / 还有未完成的任务 | 触发限流、额度或并发限制，等待重置或完成 |
| 任务因服务重启被中断 | 重新发送链接，或请管理员重试 |
| 请求已取消 | 任务被你或管理员取消，额度不返还 |
更多排查路径见问题与解决记录；管理端 API 的错误码定义见 API 参考。
16. 支持边界与限制
- 仅支持私聊文字消息；不能把媒体直接发给 Bot 解析。
- 一次可处理多条链接（默认最多 10 条，运行设置可调 1–50）；不支持区间、定时抓取，不保留话题/回复线程归属。
- 相册最多 10 项，不自动拆组；仅图片和视频能整组发送。
- 贴纸、投票、联系人、位置等类型不支持；网页预览行为未确认，不作为承诺能力。
- 单文件上限默认 2000 MiB；云盘下载不绕过该上限。
- Bot API 媒体上传遇限流不自动重试；频道副本与脚注为尽力而为。
- 缓存频道开启"限制保存内容"会导致复用失效并回退完整链路。
- 取消和失败不返还额度；额度按运营时区每日重置。
- 任务进度仅保存在内存中，重启后清零；服务重启会中断在途任务。
- 自动化测试覆盖纯逻辑部分；Telegram 登录、频道读取、媒体上传、相册与大文件等真实链路仍待真机验收，使用中遇到问题请结合问题与解决记录反馈。