Skip to content

About

mcloud 的 JS/TS 重写版 —— 作为 rust-plugin-panel 的插件运行,同时也是把面板边界压出来的压力源

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

mcloud-plugin

把 mcloud(中国移动云盘的 Rust 自动化服务)用 JS/TS 重写一份, 作为面板(panel-llrt,0.4.x / 0.5.x)的四个插件跑起来;同一份核心也能当 Node CLI 跑 (mcloud-sign,见 docs/standalone.md)。

两个目标同等重要:

  1. 功能:mcloud 的任务与界面在插件形态下真的能用
  2. 压力与优化:它是这个面板能碰到的最大的东西 —— 用它把面板的边界压出来, 每压出一个就回面板仓库修掉,并在 docs/findings.md 记下 「怎么测的、什么数、改了什么」

它长什么样

四条插件、三条任务、一个界面。

插件 是什么
mcloud 界面 + 所有路由(读数 / 登录 / 配置)。没有定时任务。
mcloud-daily 日常 —— 一次触发从头跑到尾
mcloud-exchange 兑换
mcloud-live 直播

界面是菜单栏 + 一次一块,六块:账号 / 日常 / 兑换 / 直播 / 领奖 / 数据。 每块第一行回答那个块的核心问题(「登录了吗」「今天跑了吗」「有几件待领取」), 读数直接显示,按钮说人话(「现在跑一次」「贴进去领取」「扫码登录」「领取」)。

「领奖」那一块是 2026-10-31 新加的:选账号 → 看未领取 → 点「领取」→ 填短信验证码。 滑块由后端本地解(底图是 JPEG,见 docs/prize-claim.md), 界面上没有滑块图、也没有让用户填像素的格子。

⚠ 界面上没有「设置」页(原来那一页是六个地址口子 + 自检)。那些口子是 搭测试环境用的,用户看不懂、还会把面板指到错的地方去。要改基址请直接调 /plugins/mcloud/api/config(scripts/e2e-mock.sh 就是这么做的)。

截图在 docs/shots/。

这一版推翻重做过一次。 前一版是「25 条一次一步的任务 + 七张卡片平铺 + 一个『高级』开关 + 二十几个按钮」,用户的原话是 「界面完全搞不懂,文字一大堆,按钮点哪个都不知道」。 改的过程、以及每一步的理由写在 docs/redesign-plan.md。

三个设计决定(其余都是它们的推论)

① 任务是一次跑完的,不是"一次一步"

前一版把每条流程拆成"一次调用一个请求"的状态机。那是被面板的 2 秒执行预算 逼出来的:预算打断不了正在阻塞的 http_fetch,所以只能保证"每次调用足够短"。

用户说得很清楚:2 秒不是他的需求。所以解法换成两条面板侧的能力 (见下「面板为此补了什么」):

  • 长任务隔离 + 粗粒度共享:抢兑与路由插件 worker_hint('exclusive'); 日常/直播共享一条粗粒度 lane,面板自动抬到 4 条线程
  • 按任务声明执行预算:register_cron(name, expr, handler, { budget_ms })

有了这两条,「日常」就能是一条从换票一路跑到收尾读数的函数(十几步、几十个请求), 而不是 25 条任务互相接力。

② 登录恰恰必须一步一步 —— 因为状态机是用户本人

扫码:我出码 → 用户掏出手机扫 → 用户在手机上点确认 → 我才拿到凭据
短信:我发码 → 用户看手机 → 用户把 6 位码告诉我 → 我才拿到凭据
账密:用户给我手机号和口令 → 我一次换到凭据

中间那几步的时间由用户决定。硬塞进一个"从头跑到尾"的函数,结果只能是 "函数停在等用户输入"。所以:登录走路由、触发者是用户点按钮;任务一次跑完。 账密没有用户交互,所以它一个路由就完成。

③ 查询是读数,不是任务

面板的日志是环形 200 行、混着所有插件。所以:

  • 读数走一个聚合接口 GET /plugins/mcloud/api/readings,一次给全各区块 (前一版是一个区块一个接口 ⇒ 每块各有各的加载/错误状态 ⇒ 没人知道该看哪个)
  • 「一次运行」的结果落一条读数(日常把整趟的每一步结果存下来),界面读它
  • 这个接口只读:一个上游请求都不发 ⇒ 打开页面永远不会因为上游慢而卡住
  • 例外是点了才取的两格:「今日AI豆」(/beans/today) 与「待领取奖品」(/prizes)。 它们每次都要真打移动云盘(按账号、还要翻页),塞进首屏聚合等于替每个账号发一枪 才能打开页面 —— 所以进那一页才取,页面里写清"读到时间"。

先跑起来(不用真账号)

# ① 一整套本地验证:类型、测试、产物一致性、拆分检查
npm ci && npm run all

# ② 对着 mock 上游跑完整条链 —— **绝不碰真账号**,也不需要你的凭据
./scripts/e2e-mock.sh <面板可执行文件> 18900

# ③ 只跑「领奖」那条链:列表 → 自动过滑块(真 JPEG)→ 短信验证码 → 领取
./scripts/e2e-prize.sh <面板可执行文件> 18870

e2e-mock.sh 会起 mock 上游 + 一个面板实例,把上游指向 mock、导入一份假会话, 然后三条任务各跑一次,断言协议层逐字节正确:签到三段式(含回查)、 领小红花六步链 11 个请求、H5 换票四步含 smid、WS 升级头、query 逐字节 —— 以及 mock 侧的状态真的变了(todaySigned / curMonthBackupSignAccept / 领取清单 / 通知)。 e2e-prize.sh 单独跑「领奖」:滑块答案 282 必须由插件自己算出来(不只是"发出去了"), 而且列表/日志里不许出现凭据与验证码摘要。

它和你跑的是同一份脚本,CI 里跑的也是这一份。

手工把「直播」插件指到 mock

直播链有四个独立基址(三套信封 + 第三方页 + WS),都指向同一个 mock 即可:

node mock/upstream.mjs 18080   # 起 mock
# POST /plugins/mcloud/api/config:
#   {"baseUrl":"http://127.0.0.1:18080",   # 小红花 /ycloud
#    "gateBase":"http://127.0.0.1:18080",  # 直播门 /cmlive + 换票
#    "imBase":"http://127.0.0.1:18080",    # IM member/apply
#    "wsBase":"ws://127.0.0.1:18080",      # 弹幕(注意 ws://)
#    "liveUrl":"http://127.0.0.1:18080/xhs/profile"}

弹幕默认带自动随机流:连上 WS 后每 1.5~4 秒推一条(八成闲聊、偶尔提问、偶尔口令), 比「一连上就发口令」更像真直播间;/_debug/ws/auto 可开关(e2e 从启动时关以保证确定性)。 失败/边界分支可用 /_debug/live/behavior、/_debug/live/state、/_debug/ws/{heartbeat,close} 注入, 详见 mock/fixtures/README.md;test/mock-live-contract.test.ts 直接对着这些口做契约断言。

装到你自己的面板上

# 面板的插件目录指向本仓库的 plugins/(一个静态二进制 + 一个目录,没有依赖)
#
# ⚠ 新一点的面板**默认不认明文令牌**(`PANEL_TOKEN=<明文>` 会直接退出)。
#   要么用摘要形态(推荐,口令不离开浏览器):
PANEL_TOKEN_HASH="$(printf '%s' '<你的令牌>' | <面板二进制> hash-token)" \
  PLUGINS_DIR=/path/to/mcloud-plugin/plugins <面板二进制>
#   要么本机临时开一次开发口子:
# PANEL_ALLOW_PLAIN_TOKEN=1 PANEL_TOKEN=<你的令牌> PLUGINS_DIR=… <面板二进制>
#
# ⚠ 直播那条链要面板能谈 CBC 套件(上游只给 CBC,rustls 不实现任何一个)。
#   面板从 2026-10-17 起**默认就编进去了**(`default = ["legacy-tls"]`),
#   所以直接 `cargo build --release` 出来的二进制就能直播 —— 不用加参数。
#   自己精简过(`--no-default-features`)才需要补回来;「自检」有一条
#   「宿主支持 native TLS」替你盯着,红了就是编漏了。

登录页面会把口令先在浏览器里算成 sha256("plugin-panel/v1:"+口令) 再提交; 走接口的话,{"token": "<那个摘要>"}。

装好后:

  • 面板侧边栏出现**「云盘」**入口,点进去就是七块界面
  • 面板的任务列表里出现两条任务:日常 / 直播;兑换不占面板任务列表 —— 它是兑换功能的一部分,配置在「云盘 → 兑换 → 定时抢兑」里。一条计划 = 一个账号 + 一个目标(prizeId)+ 一个整点;两个号换不同的东西/不同的时间就建两条计划。 面板仍只有一条「兑换」任务,cron 取所有启用计划整点的并集(如 0 10,20 * * *), 到点由插件按目标整点分发(面板只负责叫醒和记录)
  • 日常默认每天 8:00 / 20:00(第二趟是兜底,不是重复扣次数)
  • 想让它立刻干活:界面上点「现在跑一次」,或者 curl -X POST -H 'X-Panel-Token: <令牌>' -H 'x-panel: 1' '<面板>/api/tasks/mcloud-daily/%E6%97%A5%E5%B8%B8/run'

⚠️ 写接口(POST)必须带 -H 'x-panel: 1' —— 面板的防跨站请求伪造要求, 插件自己注册的路由同样适用(见 docs/findings.md F-007)。

面板为此补了什么

插件这一版能成立,靠的是面板侧六项新能力(当年在旧面板仓里补的,现已并入 panel-llrt):

# 能力 为什么这个插件非要
①-1 worker 隔离(worker_hint('exclusive')) 抢兑和长路由不能被十几步的日常/直播拖住;日常/直播共享粗粒度 lane
①-2 任务参数(register_cron(..., { params })) 脚本任务用;兑换的多计划走插件自己的计划表(一条计划一个账号),面板仍是一条任务
①-3 侧边栏入口(register_nav) 插件得在面板上有个门
①-4 随机表达式(@every 5s -200ms / cron 抖动) 定时不该齐步走
①-5 smtp_send 10 个推送渠道里,邮件是唯一要发信的那条
①-6 按任务/路由声明执行预算({ budget_ms }) 没有它三条任务一条都跑不起来

①-6 是那条"没有它整件事不成立"的:一个从头跑到尾的函数必然超过默认的 2 秒。

仓库结构

mcloud-plugin/
  src/                     TS 源码
    crypto/                纯 JS 密码学(md5/sha1/sha256/hmac/aes/**二维码**)
    mcloud/                上游层:签名、信封、H5、登录、会话、口令池、直播…
      tasks/               每条任务的协议逻辑
    entries/               四个插件入口(mcloud / daily / exchange / live)
  dist/panel-llrt/*.js     构建产物(单文件,提交进仓库,CI 检查是否最新)
  webui/                   WebUI 源码(原生 ESM + CSS,零依赖)→ 构建成 <产物>/mcloud.webui/
  mcloud.panel.json        主清单(版本/配置表单);另外三份在 plugins/ 下平铺:
  plugins/mcloud-*.panel.json   daily / exchange / live 的清单
  mock/upstream.mjs        mock 上游(CI 全程只打它)
  scripts/                 构建、e2e、状态断言、截图
  docs/                    见下

配置只有一个文件

用户能改的东西全在 <data>/plugin-data/mcloud/config.json(带 schema_version): 面板「插件 → 配置」、插件自己的设置页、CLI 的 --config 读写的都是它。

  • 面板清单里只有 mcloud 声明配置表单(日常预算 / 定时抢兑两格); mcloud-daily / mcloud-exchange / mcloud-live 不再有独立表单 —— 同一格设置不会再有四个入口。
  • 保存后不用重载插件:下一次读就是新值(按 mtime+size 失效缓存)。
  • 账号凭据、session、进度、运行记录、日志仍然在 shared.json / state/<账号>.json / runs/;shared.json 里的 mcloud.accounts 是咪咕插件读的跨仓契约,位置与字段不变。
  • 旧的 asign.json / asign.config.js|mjs 可以一次性搬进统一文件:
mcloud-sign config:import --config asign.json --data-dir <面板的 plugin-data/mcloud> --dry-run
mcloud-sign config:import --config asign.json --data-dir <…>          # 真搬

账号进 mcloud.accounts,standalone.http|ws 进 cli.*;旧文件原样留着(只读)。 之后 --config <…>/config.json 就能直接跑,读到的是同一组设置。

  • 第一次加载会自动迁移旧的 state 键与四份旧 config.json,写 schema_version 作幂等判据, 迁移前把旧文件与旧键备份到 <store>/backup/config-migration-<时间>/。

边界一句话:用户能改的 → config.json;程序自己写的 → shared.json / 账号袋。

文档

文件 里面是什么
docs/architecture.md 架构现状:分层、import 规则、存储布局、产物、阶段状态
docs/refactor-plan.md 这次重构的账:为什么、定了什么、P0~P7 各到哪一步、验收结果
docs/p3-async-plan.md P3 的执行手册(同步 → 异步):量出来的范围、机械变换的做法、已知的坑、验收与回滚
docs/redesign-plan.md 上一版的设计总纲(历史;现状看 architecture.md)
docs/findings.md 压出来的面板边界:怎么测的、什么数、改了什么
docs/howto-session.md 使用者手册:怎么拿会话、怎么导入、失败了怎么看
docs/ui-wording.md 界面用词规则(对用户不许说"上游")
docs/live-spec.md 直播(小红花)业务规格:两条路、共享口令池、领取结果分类、哪些环节还没被证实
docs/prize-claim.md 领奖(待领取奖品):领取链四段、滑块为什么必须本地解(底图是 JPEG)、验证码摘要规则、哪些还没被证实
docs/app-task-parity.md App 任务对照表:mcloud-sign 的 runner 哪些搬了、哪些还没搬、日志怎么说
docs/app-task-ids.md App 任务逐条 id 台账(2026-11-01):每条 id 我们做什么、Rust 参考是什么、能做的/刻意不做的/还没搬的;以及「一条没成不许拖垮整趟」
docs/token-pk.md 算力大作战(National_TokenPK):实拍出来的状态机与七个口、计划分类、动作矩阵、用户看到的汇总句;以及哪些还没实拍
docs/smid-chain.md · docs/upload-chain.md 两条比较绕的链路的实测记录
docs/shots/ 界面截图(各区块一张 + 扫码)
docs/standalone.md 面板外独立运行:替代 mcloud-sign 的 CLI / 配置 / 导出函数
docs/cli-vs-mcloud-sign.md CLI 与 mcloud-sign 的差异清单:默认每日任务、日志、退出码、换票
docs/auth-families.md 鉴权分族(抓包实测):哪些接口认 jwttoken、哪些认 Authorization;以及对齐判据是用户看得见的行为,不是"照抄实现"
docs/task-state.md 任务状态规则:本地动作不算成功,只有服务端 FINISH 才算;每日/每月记录有效期,未确认可重试
docs/design-history.md 开工前的设计稿(历史;有些判断后来被推翻了,为什么留着见文件头)
docs/acceptance-real.md 真机验收清单(这一步只能在你的真机上做 —— 照着点,每步写清看什么算过)

起名即分组

面板把插件按名字里第一个 - / _ 之前那段归拢显示(mcloud-* 一组、 bilibili-* 一组),每组带「全部重载 / 全部启用」。

所以四个插件前缀都用 mcloud —— 面板上它们聚成一块,而不是散成一排。

零运行时依赖

QuickJS 沙箱里没有 Node(没有 fs / net / crypto / npm 包), host-api 由面板的 Resolver 提供。所以:

  • 密码学、UTF-8、hex、base64、PNG 解码、二维码全部自己写 (沙箱里连 TextEncoder / Buffer 都没有)
  • 产物是单文件、零依赖;界面是原生 ESM + CSS,零构建

安全

  • 上游账号不是测试资源:CI 全程只打 mock;真账号只在本地手工验,且优先只读任务
  • 凭据不进日志、不进读数、不进界面:要给界面看的一律走 maskAuth / maskPhone
  • 兑换会花真 AI豆(上游无幂等键)⇒ 界面上的「现在试一次」是显式动作,不自动跑
  • 登录的口令先按协议哈希再发出去(SHA1("fetion.com.cn:" + 口令),大写 hex), 不上传明文;日志与错误信息里都不回显口令

面板里怎么装:docs/install.md

面板契约(0.4)

面板侧的硬规则在 panel-llrt/docs/plugin-contract.md (~/mobile/workspace/panel-llrt/docs/plugin-contract.md):

  • 产物只进本仓 dist/panel-llrt/,PANEL_LLRT_PLUGINS 也不许指向面板仓; 面板仓的 plugins/ 只有面板自己的 webui-demo(R1 / R2)。
  • 上线是「本仓 → 实例 ~/panel-3030/plugins」,不经面板仓中转(R3)。
  • 只面向 0.4:不写 atLeast('0.3.0') 这类兼容分支,下限写进清单 min_panel(R5)。
  • 缺能力在面板仓加 API,别在插件里造轮子(R6)。

发布(面板 0.4 的 zip)

资产名 mcloud-plugin-<version>-panel<NN>.zip(NN 由清单 min_panel 推,当前 0.7.0 → panel07),挂在 https://github.com/asunajs/mcloud-plugin/releases;同目录还有 .sha256。

npm run build                # 产物 → dist/panel-llrt/(4 个 .js + 4 个清单 + mcloud.webui/)
npm run build:dir            # 同上,但出**目录式**插件(四个入口 import 同一份 mcloud/lib/)
npm run pack                 # → dist/mcloud-plugin-<version>-panel<NN>.zip(+ .sha256、SHA256SUMS)

必须从干净 worktree/tag 打:scripts/zip.mjs 固定了 DOS 时间戳(1980-01-01), 同输入同 sha256 —— 但在脏工作树里打,包里会混进未提交的改动,发布出去的 sha256 就和 干净树对不上(踩过,只能重做)。做法:

git worktree add /tmp/rel-v0.4.0 v0.4.0
cd /tmp/rel-vX.Y.Z && npm ci && npm run build && npm run pack

面板 → 插件卡片 → 配置 里有表单(不再是裸 JSON),四份清单各自声明自己真读的格子:

插件 配置项 落在哪
mcloud / mcloud-daily daily_budget_s(日常一趟预算,60–600 秒) mcloud.daily.budget_s
mcloud / mcloud-exchange exchange_enabled(定时抢兑开关) mcloud.exchange.schedule.enabled

判据是三方合并:插件配置页写的 plugin-data/<插件>/config.json 与插件自己界面改的值 互不覆盖 —— 文件里的值只在它自己变过的那一次生效(指纹在 mcloud.cfg.applied)。 实现与理由见 src/mcloud/configOverlay.ts 的文件头。

About

mcloud 的 JS/TS 重写版 —— 作为 rust-plugin-panel 的插件运行,同时也是把面板边界压出来的压力源

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages