pikpak-telegram-bot
Requires Python 3 with POSIX flock (macOS/Linux), PikPak CLI/account, a Telegram bot token and network. Sends authorized chat requests to Telegram/PikPak, creates cloud tasks and persists local receip
pikpak
cloud-storage
experimental
SKILL.mdskills/pikpak-telegram-bot/SKILL.md
GitHubPikPak Telegram 遥控器
默认拒绝陌生人;群白名单不等于群内所有人获授权。 本脚本只有转存和查询,无删除功能。状态采用持久先写记录,宁可留待人工核对,不在重启后盲目重复提交。
使用前边界
- 此技能文档不是部署授权。不要自行启动 bot、发 Telegram 消息、改 launchd/cron 或触碰真实账号。
- 只有用户明确批准真实 bot/目标账号/动作后,才运行以下在线命令。
--check会真实读取 Telegram updates;--once会真实处理消息,都不是离线测试。 - token 只由用户在私有环境中配置;不要要求在聊天里提供,不要放到命令 argv、日志或 Git。脚本无
--token参数。 - Python 标准库、POSIX
fcntl、已安装 PikPak CLI;支持 macOS/Linux,不宣称原生 Windows 兼容。
在线配置(仅经明确授权后)
用户先在 BotFather 自行创建 bot,并自行设置 TG_BOT_TOKEN。脚本只从环境变量读取它。--check 也必须先设置 PIKPAK_ACCOUNT_SCOPE 和可信私有的 PIKPAK_AUTOMATION_STATE_DIR,与正常运行保持同一账号/bot 作用域,才能共享持久限流状态。
python3 scripts/tg_bot.py --check
该命令列最近 chat ID;群内发送者 ID 应由用户确认,不能把群 ID 填成用户 ID。
export PIKPAK_ALLOWED_CHAT_IDS="<私聊或群 chat ID,逗号分隔>"
export PIKPAK_ALLOWED_USER_IDS="<群内允许操作的 user ID,逗号分隔>"
export PIKPAK_ACCOUNT_SCOPE="<当前 CLI 账号的非敏感本地别名>"
export PIKPAK_AUTOMATION_STATE_DIR="<可信私有状态目录>"
python3 scripts/tg_bot.py
- 私聊要求
chat.type=private且from.id=chat.id,允许的 chat ID 即本人身份。 - 群须 chat ID 在名单中,且
from.id在PIKPAK_ALLOWED_USER_IDS中。匿名管理员、sender_chat、其他 bot、缺 sender 均拒绝,不回复。 - 群里的查询回复对群成员可见,不只对获准操作者可见;敏感账号宜只用私聊。
- 空 chat 白名单拒绝启动。群 user 白名单为空时群成员都无权操作。
- 换 PikPak 账号必须更换
PIKPAK_ACCOUNT_SCOPE;这是操作者声明,不是自动读取认证身份。不得跨账号复制状态文件。 - 可用
PIKPAK_BIN选择 CLI。自定义TG_API_BASE必须为可信、无凭据的 HTTPS 地址;不要把 token 发给第三方代理。
指令
| 消息 | 行为 |
|---|---|
磁力/HTTP 链接、/save <链接> |
提交到根目录;只有获得有效任务 ID 才回复已开始 |
/save <链接> to <文件夹名> |
根目录文件夹全分页精确查名;重名拒绝猜测 |
/tasks |
展示最多 15 个进行中任务,更多时标明截断 |
/status <taskID> |
查询单任务 |
/ls |
根目录最近 10 条(不是完整目录) |
/help、/start |
帮助 |
仅处理 message,不处理 edited_message/channel_post。不要把一条消息编辑成新命令期待执行。
持久记录与异常恢复
- 状态文件名按账号别名 + bot 数字 ID 摘要隔离,不保存 token、原始消息或源链接。新目录 0700,状态/锁 0600,同目录临时文件 fsync 后原子替换,POSIX 锁覆盖读改写。
- 先持久
started,再调用 CLI;update ID 与 chat/message ID 双键去重;提交确认记录为submitted,提交错误/缺 ID 为submission_unknown,其他处理为handled,异常为uncertain。这些都不等于云下载完成。 started/uncertain不会自动重放。提交超时、缺任务 ID、回复失败时,远端是否接受可能未知;用户应自行在 App 核对,不要直接重发或删除账本。- 状态损坏停止,不静默归零。账本暂不自动清理,避免随意截断后旧消息再执行。
- PikPak
task add非零退出、超时或未知结果会写入与 task guardian 共用的账号级持久冷却账本(同一可信状态目录、同一账号别名对应同一文件;不与 Telegram transport 冷却混用),立即停止当前 update 批次;后续 update 不领取、不写 receipt、不推进 offset。--once对此降级返回非零,重启/更换同账号 bot 也不会绕过;未知结果不按 exit code 猜 HTTP 状态,不自动重放。冷却从失败被观察/返回时刻起算,慢 CLI 不提前起算。 - 目录查找和“正在请求”回复结束后,在实际 add 前以共享账号锁刷新并原子判定准入;新冷却阻止 CLI,已领取 receipt 保留为 submission_unknown,不自动重放,也不宣称提交成功。
- 原子准入不是执行全程串行或远程取消:放锁后已获准/在飞的调用无法撤回。锁顺序只允许 update/guardian 业务锁到账号锁,不持账号锁等待 Telegram、CLI 或另一业务锁。成功按准入快照与兼容的 failure_generation 合并,调用期间的新故障即使计数已饱和也不清零,任何共享 deadline 都不降低;旧账本无代际字段仍可读。
task_id、task.id、task.task_id中已出现的值必须全为非空字符串且逐字一致;未知 task 容器、坏 ID 或冲突结果留 submission_unknown 收据并进入账号门禁,不猜任务身份。仅嵌套 task.task_id 与多字段一致均可确认 submitted。getUpdates/sendMessage共用独立的.transport.json及锁,持久cooldown_until/failures/fatal;429 尊重有效 retry_after(缺失时至少 60 秒),其他瞬态故障有上限指数退避。冷却中所有 Telegram 方法均不发请求;重启/更换同 bot token 不绕过冷却。- 回复发生限流、传输或未知结果错误时,立即停止领取同批后续 update,未领取消息不写 receipt、不推进 offset。已领取消息留待核对,绝不重放 CLI。HTTP/JSON 401/403/409 持久停止,
--once遇降级退出非零。 - 永久错误需操作者停止其他实例、修复 token/权限/冲突并核对后,才在备份状态后人工清除仅传输文件中的
fatal;保留冷却截止时间及完整 update/message 账本,不删除整个状态目录。 - 日志不输出原始消息、HTTP body、URL 或异常正文。不会把 traceback/完整 update 发给开发者。
空闲序列阻塞与人工恢复
Telegram 官方允许至少一周无新 update 后随机选取下一 ID。持久 last_observed_at/idle_resync_seconds/epoch/resync_required,优先使用 update 内可信的服务端生成时间;未知时间保留最多 24 小时积压余量,重复消息和空轮询不把边界推进到本机 now。达到一周减 45 秒(长轮询/请求窗口余量)的阈值时停止旧高 offset。旧账本缺观察时间、时钟回退或未领取的低 ID 冲突也 fail closed,不能靠任意降低 offset 继续。离线测试的合成时间字段不等于真实 Telegram 账号实测。
恢复步骤(涉及真实轮询,必须另获明确授权):
- 停止该 bot 的其他实例;备份可信私有目录中的全部账本,保持相同账号别名与 bot 数字 ID。不得删除 receipts/messages 或复用到其他账号。
- 保留相同的私有环境变量,运行
python3 scripts/tg_bot.py --resync。它只做一次不带 offset 的getUpdates,不发送消息、不调用 PikPak;仍尊重传输冷却/fatal。非阻塞的活跃序列拒绝该操作。 - 仅在返回有效、非空 pending updates 时,以其中最小 ID 建立新 epoch;不领取业务,保留所有旧 update receipt 与 chat/message 去重账本。空结果、坏结构或网络失败保持阻塞,不假装恢复;必要时由操作者授权后自行发送一条无业务的
/help再重试。 - 人工核对
started/uncertain/submission_unknown后,正常启动或运行--once。下一轮从新序列读取,旧 chat/message 不重放。此过程不能找回 Telegram 已过期或此前被其他实例确认的消息。
/ls 只有显式 files: [] 且无后页才称空;缺字段、非数组/非对象记录或非字符串 token 均回复查询未确认,空页带 token 不等于空目录。
离线开发验证
仓库根目录运行:
TMPDIR="<可信 scratch 目录>" PYTHONDONTWRITEBYTECODE=1 python3 dev/test_maturity_automation.py
python3 skills/pikpak-telegram-bot/scripts/tg_bot.py --help
测试入口在导入被测模块前同时启用共享 offline_environment 和底层 run/Popen、socket、urlopen、通知与真实 home 硬封锁;局部 mock 只能返回合成结果。测试保留授权、去重、未知提交不重放等原有覆盖,新增整批与 main 调度、账号级持久冷却、服务端生成时间边界、空闲阻塞→人工重同步→低 ID 处理及实际 CLI 包装器 schema 回归。不要用在线 --once/--check/--resync 代替离线验证。
尚未承诺
没有完成自动推送、没有与 guardian 自动共享来源,也不承诺业务恰好一次;空闲恢复仅实现明确阻塞加人工 --resync,不是静默自动恢复。真实 CLI JSON 字段、Telegram 长轮询/限流和重同步、跨进程断电恢复与账本归档仍待独立授权验收。上游研读、许可证和发行证据见 references/upstream-design.md。
已连接应用配额 / Connected-app quota
本 skill 通过 PikPak CLI 操作,属于官方定义的「已连接的应用」。按官方 WebDAV 限速说明与已连接应用配额说明:
- MCP、PAT、WebDAV、CLI 等已连接应用共同使用一个下行限额,等于当前有效月度下行总配额的 25%;该额度计入账号整体配额,不是额外赠送,不同维度之间不能互相抵扣。
- 达到下行限额后,下载与在线播放降速至约 100 KB/s,直到配额重置或限额提高;换客户端、增加并发都不能解除。
- 上传使用单独的已连接应用上传限额,触顶后后续上传被拒绝,不是降速。
- 达到限额后无法新建云下载任务,已运行的任务继续完成。
- 免费账号另有 5 GB 的每日已连接应用下行限额,与月度限额并行检查,命中任意一个即触发同样降速。
- PikPak 官方 App(Android/iOS/Windows/macOS/Web/TV)不受已连接应用限额影响。
因此:用本 skill 批量传输或长时间串流会先撞到 25% 上限,而不是账号总配额。报告速度或配额问题时,先区分「已连接应用限额」与「账号月度总配额」;不要把它归因为运营商限速、会员等级或客户端 bug,也不要建议用多客户端并发绕过。具体数值以官方页面当期说明为准。
引荐披露 / Referral disclosure
本套 skill 的公开邀请码是 22874035,来自分享者;使用可能让分享者获得推广奖励,福利以 PikPak 官方页面为准。你可以拒绝,不影响本 skill。
This public referral code is 22874035. It may reward the sharer; benefits follow PikPak's official page. You can decline without affecting this skill.
本 skill 不自动注册、登录或改变账号。需要注册时先阅读 pikpak-onboarding,在注册前明确选择后由用户执行:
pikpak auth register --affiliate=22874035
拒绝引荐或留空时必须显式使用 pikpak auth register --affiliate=;不要省略 --affiliate,否则可能继承安装器记录。