Add 蹬王之王 (expiry-guardian) · 只读版：本地到期账本与用卡决策（不碰宿主任何私有数据）

[Hylouis233]

这是什么

社区插件版本的蹬王之王（Expiry Guardian）：看你自己维护的本地账本，
算出「该用卡还是该留积分」，并把理由说清楚。

Mini App 看板 + Rust 后台守护进程（launchd 常驻，只读）。

---

为什么不碰宿主的三类私有数据

上游社区插件有三条硬红线（2026-10-20 管理员 review 明确列出）。这一版按红线裁剪：

红线	v1.x（已移除）	v2.0（本 PR）
不能读 MiniMax Code 的登录凭据	读 lease socket / .cap 取 access token，再拿它调账号接口	不读。额度/积分/卡的信息改由本地账本提供
不能读写宿主内部数据库	sqlite3 直接 UPDATE/DELETE/INSERT 目标与执行队列，还读回合记录	不碰。只读插件自己的目录
不能读别的插件的数据目录	读 minimax-bot 的 state.json 拿 bot 与会话 id，再往那些会话发消息	不读。Bot 看门狗整体移除

⇒ 代价是明确的：v2.0 不再自动扣卡、不再自动暂停目标、不再自动叫醒 bot。
它只负责把结论算准、说清楚，动作由你自己做。

⇒ 好处也很明确：这是一份能进社区仓库的代码 ——
不碰宿主任何私有数据，行为全部可预测。

---

本地账本

路径：~/.config/mcode-reset-card/ledger.json（面板底部可直接编辑并保存）

{
  "schemaVersion": 1,
  "updatedAtMs": 1792480000000,
  "quota": {
    "fiveHour": { "usedPercent": 3, "totalPercent": 100, "unlimited": false, "resetTimeMs": 1792497600000 },
    "weekly":  { "usedPercent": 0, "totalPercent": 100, "unlimited": true,  "resetTimeMs": 1792944000000 }
  },
  "cards": [
    { "cardId": "card_1", "label": "Card A", "sourceType": "code",
      "outBizNo": "biz_1", "expireTimeMs": 1795000000000 }
  ],
  "credits": [
    { "label": "Granted", "source": "code", "granted": 400, "used": 0,
      "balance": 400, "expireTimeMs": 1795017600000 }
  ]
}

• 一张卡要算「可用」，outBizNo 与 sourceType 两个都要有；已过期的也不算
• 积分要 balance > 0 且未过期
• ⚠️ 缺 credits 字段 ≠ 没有积分 ⇒ 判成「数据不完整」⇒ 结论停在「暂不处理」，
  绝不会因为「读不到」就反过来建议你烧掉一张真卡

---

决策逻辑：先过期先用

情况	结论
额度没到触发线	额度充足
到线 + 无积分 + 有卡	建议用卡
到线 + 无积分 + 无卡	暂不处理
到线 + 有积分 + 无卡	建议留积分
到线 + 都有，卡先过期	建议用卡
到线 + 都有，积分先过期	建议留积分
到线 + 距刷新不到 N 分钟	暂不处理（烧卡纯浪费）
数据不完整	暂不处理（宁可不给建议，也不给错建议）

三方一致性（决策逻辑一字未改）

Rust / Mini App / Python 三份同构实现，daemon/verify-parity.mjs 让三方读
同一份用例，逐字比对「动作 + 理由文本」：

$ node daemon/verify-parity.mjs
19/19 三方完全一致（动作 + 理由文本逐字）

裁剪只改了「数据从哪来」，决策引擎的输入结构与之前从账号接口拿到时完全一致。

---

红线守卫（19 项）

tests/server-lint.test.mjs 把上面三条红线变成可执行的门禁：

• 不出现 lease socket / .cap / token 落盘
• 不出现 runtime-state.sqlite / 宿主表的 UPDATE·DELETE·INSERT
• 不出现 plugin-data / liveboards / 别的插件的 state.json
• 不出现扣卡接口 / 目标暂停恢复

⇒ 谁不小心把旧代码加回来，CI 立刻红。
（v1.x 那些代码在仓库里躺了好几个版本才被发现 —— 人工审计靠不住。）

---

后台守护进程（只读）

• 每轮读一次本地账本 → 跑一遍上面那套决策 → 写日志与 daemon-status.json
• 账本读不到 ⇒ 明确报「本轮没有任何结论」，连续失败逐级升级（5 轮 / 每 30 轮）
• 不做任何写操作：不扣卡、不暂停目标、不改宿主任何数据

---

local MCP 端点

工具	作用
watchdog_status	查账本里的额度、重置卡、积分与当前结论
watchdog_decide	立即判定一次（只判定不扣卡）

⚠️ 刻意不暴露扣卡：扣卡是真实写操作，让别的插件随手就能扣太危险。

---

校验

套件	结果
上游 npm run validate	本插件 OK（0 错 0 警）、repository: OK
上游 npm test	69/69
Rust	25/25
Python 决策单测	20/20
Mini App	79/79
三方一致性	19/19

---

文档

• plugins/hylouis233/expiry-guardian/README.md —— 英文
• plugins/hylouis233/expiry-guardian/docs/README.zh-CN.md —— 中文
• plugins/hylouis233/expiry-guardian/docs/BOT_DIAGNOSIS.md —— 排查手册

v1.x 的完整历史（自动扣卡、目标暂停、Bot 看门狗，以及那套「静默失效全部变成会说话」
的加固）保留在 git 里；那些加固在 v2.0 仍然生效，只是守护的对象换成了本地账本。

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Hylouis233]

这是「只读版」，与 #39 是二选一

• 本 PR（Add 蹬王之王 (expiry-guardian) · 只读版：本地到期账本与用卡决策（不碰宿主任何私有数据） #47）：同样的看板与决策逻辑，但数据源换成本地账本，
  不读宿主凭据、不碰宿主内部数据库、不读别的插件的数据，也不做任何写操作。
• Add 蹬王之王 (expiry-guardian): 额度到期雷达 + 无头守护进程 + Bot 看门狗（完整功能版；只读版见 #47） #39：完整功能版（自动扣卡 / 自动暂停目标 / 自动叫醒 bot），
  但它违反了社区插件的三条红线。

两者的决策逻辑一字未改（三方 Rust / Mini App / Python 仍 19/19 逐字一致），
差别只在「数据从哪来」与「能不能自动执行」。

⇒ 管理员 review 的原话是「很欢迎你提的方案：把只读、能直接交付的部分……单独开一个 PR。
直接把这个 PR 裁到这个范围也可以，两种方式都行」。
本 PR 就是那个「单独开一个」的方案；#39 保持完整版继续讨论。

请先决定走哪条路；如果走只读版，#39 可以直接关掉。