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.md

GitHub

PikPak 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 账号实测。

恢复步骤(涉及真实轮询,必须另获明确授权):

  1. 停止该 bot 的其他实例;备份可信私有目录中的全部账本,保持相同账号别名与 bot 数字 ID。不得删除 receipts/messages 或复用到其他账号。
  2. 保留相同的私有环境变量,运行 python3 scripts/tg_bot.py --resync。它只做一次不带 offset 的 getUpdates,不发送消息、不调用 PikPak;仍尊重传输冷却/fatal。非阻塞的活跃序列拒绝该操作。
  3. 仅在返回有效、非空 pending updates 时,以其中最小 ID 建立新 epoch;不领取业务,保留所有旧 update receipt 与 chat/message 去重账本。空结果、坏结构或网络失败保持阻塞,不假装恢复;必要时由操作者授权后自行发送一条无业务的 /help 再重试。
  4. 人工核对 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,否则可能继承安装器记录。