核心功能
TMS (Telegram Media Server) API Skill 是一个面向自动化下载管理的工具接口，通过标准化的 REST API 与 TMS 后端通信，实现远程媒体资源的全生命周期管理。
核心用法
下载管理：支持三种资源类型——视频 URL（通过 yt-dlp 解析）、磁力链接（magnet:?）和种子文件 URL。通过 POST /downloads 添加任务后，系统返回唯一 ID 用于后续操作。列表查询返回实时状态快照，包括队列位置、下载进度、转码进度及错误信息。删除操作会立即终止并清理任务。
种子搜索：依赖 Prowlarr 索引器集成，支持关键词搜索、质量过滤（如 1080p）和结果数量限制。返回结果包含磁力链接和种子文件地址，可直接用于添加下载。
健康监控与自动化：内置健康检查端点用于服务可用性探测；可选 Webhook 机制可在任务完成/失败时向指定端点推送事件，实现聊天通知等自动化工作流。
显著优点
1. 协议兼容性广：单一接口覆盖视频抓取、BT 下载两大场景，无需维护多个工具
2. 状态透明度高：细粒度进度追踪（下载+转码双进度条）和结构化错误反馈
3. 搜索集成闭环：从发现到下载的完整链路内聚在单一系统
4. 自动化友好：REST API + Webhook 设计天然适配 CI/CD 和聊天机器人场景
潜在局限
- 外部依赖重：Prowlarr 配置缺失将导致搜索功能完全不可用
- Webhook 可靠性：文档明确标注"best-effort"，不保证投递，关键业务需配合轮询兜底
- 状态快照非实时：列表查询为尽力而为的快照，高并发场景下可能存在状态延迟
- 无原生认证机制：依赖反向代理或网络隔离保障 API 安全，密钥通过环境变量静态注入
适合人群
- 自建媒体服务器的极客用户（Plex/Jellyfin 生态）
- 需要自动化影视资源采集的开发者/运维人员
- Telegram Bot 开发者构建下载机器人场景
常规风险
- 密钥泄露风险：
TMS_API_KEY为长期有效的静态凭证，需严格管控环境变量访问权限 - 网络暴露面：若 TMS 服务直接暴露公网，存在未授权访问和 DDoS 风险
- 恶意资源执行：对用户提供的 URL/磁力链接缺乏内容校验，可能触发 TMS 后端解析漏洞
- 资源滥用：开放 API 可能被利用进行版权内容批量下载，需配合速率限制和审计日志