把 mcloud(中国移动云盘的 Rust 自动化服务)用 JS/TS 重写一份,
作为面板(panel-llrt,0.4.x / 0.5.x)的四个插件跑起来;同一份核心也能当 Node CLI 跑
(mcloud-sign,见 docs/standalone.md)。
两个目标同等重要:
- 功能:mcloud 的任务与界面在插件形态下真的能用
- 压力与优化:它是这个面板能碰到的最大的东西 —— 用它把面板的边界压出来,
每压出一个就回面板仓库修掉,并在
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 <面板可执行文件> 18870e2e-mock.sh 会起 mock 上游 + 一个面板实例,把上游指向 mock、导入一份假会话,
然后三条任务各跑一次,断言协议层逐字节正确:签到三段式(含回查)、
领小红花六步链 11 个请求、H5 换票四步含 smid、WS 升级头、query 逐字节 ——
以及 mock 侧的状态真的变了(todaySigned / curMonthBackupSignAccept / 领取清单 / 通知)。
e2e-prize.sh 单独跑「领奖」:滑块答案 282 必须由插件自己算出来(不只是"发出去了"),
而且列表/日志里不许出现凭据与验证码摘要。
它和你跑的是同一份脚本,CI 里跑的也是这一份。
直播链有四个独立基址(三套信封 + 第三方页 + 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.mdF-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
面板侧的硬规则在 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)。
资产名 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 的文件头。