quota-keepalive 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quota-keepalive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# quota-keepalive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 Magpie 全部已登录供应商的额度签到、真实对话保活、执行留痕和额度趋势页面。
+插件不接管任何供应商的登录，也不会把页面伪装成单一供应商专属功能；登录、模型、
+额度和签到 Hook 仍由各供应商插件维护，本插件负责统一检测、调度、执行和展示。
+
+## 功能
+
+- 一键检测 Magpie 当前已登录的供应商、账号、模型和额度窗口。
+- 一键签到：通过各供应商登录插件公开的 `auth.checkin` 接口执行，尊重供应商、
+  账号两级启停；页面会明确显示未适配或未登录的账号，不会静默跳过。
+- 真实对话保活：通过各供应商自己的登录插件取得签名请求，发送一条真实消息。
+- 模型选择：只从该账号实际列出的模型中选择。默认优先近期真实保活成功过的模型，
+  再按成功率、成功时间和失败次数排序；没有历史记录时沿用供应商自己的模型顺序，
+  不再按免费或价格抢先选择。第一个模型不可用时自动换下一档，全部不可用才记失败。
+- 自定义模型：页面里每个供应商都有可搜索的模型下拉框；选中模型会优先尝试，
+  失败后仍会自动回退到该账号可用的其他模型。列表会显示倍率、免费状态和模型 ID。
+- 定时任务：页面内可配置每 5 分钟到 7 天执行一次，任务可选“只签到”“只保活”
+  或“签到 + 保活”。
+- 执行记录：检测、签到、模型切换、保活、额度和失败都会写入 JSONL 诊断日志；
+  页面“最近执行记录”只展示签到和保活任务，刷新额度不会挤占任务记录。点击记录
+  可查看完整执行时间、账号明细和同一轮执行链路。单独账号触发、没有总任务总结
+  锚点的保活记录也会显示，不会因为缺少汇总日志而被旧任务掩盖。
+- 今日结果：供应商行分别汇总“签到 X/Y”和“保活 X/Y”，账号卡显示已签到、
+  签到积分（如 `+100`）、已保活，以及设备受限、额度不足、待重试等具体原因。
+  跳过项不再计入“需要处理”，只有明确失败才进入待处理数量。
+- 近 5 天历史：每个有执行记录的账号可展开查看最近 5 天的签到、积分和保活结果。
+- 额度视图：统一展示账号“可用 / 总计”额度窗口和余额变化，并由 Magpie 的额度历史
+  提供趋势数据。供应商若只返回“已用 / 总量”展示值，只有在数值能相互核对时才换算，
+  无法确认语义时保留原始展示，避免把“已用”误当成“可用”。
+- 自动刷新额度：启用中的供应商每 1 分钟刷新一次，停用的供应商不刷新；顶部可刷新全部
+  启用供应商，每个供应商卡片也可单独立即刷新。供应商没有可读取额度卡时记为跳过；
+  Magpie 30 秒内已刷新过时使用缓存并记为跳过，只有网络、登录失效或空数据等真实
+  异常才记为失败。
+- 多账号支持：所有供应商账号逐个执行，同一账号同一北京时间日成功后不会重复发送。
+- 账号级控制：每个账号的“签到/保活”开关只控制自动任务；旁边独立的“执行签到”
+  “执行保活”按钮只对当前账号立即执行一次。手动保活必须二次确认，仍会遵守供应商
+  整体启停，但可以单独执行一个已关闭自动任务的账号。
+
+## 安装
+
+从 GitHub 安装：
+
+```sh
+magpie plugin add github:sljdxde/quota-keepalive
+```
+
+从本地目录安装：
+
+```sh
+magpie plugin add "$(pwd)"
+```
+
+插件不需要接管 provider。供应商登录仍由 Magpie 已安装的对应社区插件提供；本插件
+直接从 Magpie 的插件目录加载这些签名适配器，因此 Magpie 或供应商插件更新后，
+只要其公开接口没有变化，本插件仍可继续使用。若供应商包改名为不兼容的接口，页面
+会明确显示失败原因，不会静默跳过。
+
+安装后在 Magpie 左侧 `Plugins` 分组打开“额度签到”。如果页面文件刚更新，
+重新打开一次插件页即可刷新清单，不需要重启 Magpie。
+
+发布到 npm 后也可以按包名安装：
+
+```sh
+magpie plugin add quota-keepalive
+```
+
+## 页面操作
+
+- `一键检测`：刷新供应商、账号、模型和额度快照。
+- `全部签到`：立即对所有具备签到能力的供应商执行签到。
+- `发送保活`：确认真实请求后，为所有已登录且适配的供应商账号发送消息。
+- 账号后的“签到/保活”开关：控制该账号是否参加自动任务，不会立即发送请求。
+- 账号后的“执行签到/执行保活”：只对当前账号立即执行一次；执行保活会先弹出确认框。
+- 连续切换多个开关时会合并成最后一次状态写入，并按 Magpie 的页面配置限频串行保存，
+  不会因为快速连续点击触发“每秒只能写入一次”的报错。
+- 圆形刷新按钮：立即刷新全部启用供应商额度；供应商卡片内的刷新按钮只刷新该供应商。
+- `保存计划`：设置统一执行间隔和任务类型。计划默认关闭，防止无意间消耗积分。
+- 定时计划保存或修改后，从下一个间隔开始执行；需要立即执行时使用页面顶部的手动按钮。
+
+页面每 5 秒读取一次本地快照；插件后台每 1 分钟刷新启用中供应商的额度，停用项会
+跳过。额度刷新仍写入后台诊断日志，但不会出现在页面的签到/保活执行记录中。
+执行中的任务会显示在状态条中。快照生成时会一次
+计算今日状态和近 5 天摘要，页面轮询只读取结果，不会在浏览器里重复聚合历史日志。
+最近执行记录按任务折叠显示；点击任意记录可展开精确执行时间、耗时、供应商、账号
+数量、执行 ID、完整说明，以及本次任务下每个账号的结果和积分。
+
+## 模型可用性
+
+保活不是“只选免费或最便宜”后盲目发送：
+
+1. 从供应商模型和该账号的模型白名单取交集。
+2. 读取近 5 天真实保活记录，优先该账号成功过的模型。
+3. 账号没有记录时，优先该供应商其他账号成功过的模型；仍无记录则跟随供应商模型列表顺序。
+4. 已知失败的模型排在未验证模型之后；单个账号最多尝试配置数量的候选模型。
+5. 模型不存在、额度拒绝、上游不可用或空回复时切换下一个候选。
+6. WorkBuddy CN 按 dsh 的 probe 语义，HTTP 2xx 表示上游已经接受并记录一次真实对话；
+   `max_tokens` 为 1 时可能只有 `[DONE]`、usage 或空正文，仍算成功。JSON 业务错误、
+   HTML 登录页和超时不算成功。
+
+账号卡片会优先显示最近一次真实保活实际使用的模型（`实际模型`）；没有执行历史时，
+依次显示用户指定的 `所选模型` 或自动排序出的 `自动首选`。供应商设置行也会汇总
+最近实际使用的模型，日志会保留每次模型切换及失败原因。
+
+展开供应商卡片后，可在“保活模型”输入框里搜索模型名或模型 ID。下拉列表默认包含
+该供应商的全部可用模型，并显示免费状态、倍率和模型 ID；选中后点击“自动”可恢复
+自动选择。实际请求仍只使用该账号模型白名单中的模型；选中项不可用时自动回退。
+
+## 配置
+
+页面保存的配置写入 Magpie 插件级 options。也可以用命令修改：
+
+```sh
+magpie plugin options quota-keepalive '{
+  "scheduleEnabled": true,
+  "scheduleMinutes": 60,
+  "scheduleAction": "all",
+  "modelPreferences": {
+    "workbuddy": "deepseek-v4.1-flash",
+    "codearts": "deepseek-v4.1-flash"
+  },
+  "modelCandidates": 4,
+  "inputTokens": 25000,
+  "maxAttempts": 3,
+  "timeoutMs": 90000,
+  "logMaxBytes": 2097152
+}'
+```
+
+- `scheduleEnabled`：是否启用定时任务，默认 `false`。
+- `scheduleMinutes`：统一执行间隔，默认 60 分钟，范围 5 分钟到 7 天。
+- `scheduleAction`：`checkin`、`keepalive` 或 `all`，默认 `checkin`。
+- `model`：可选的首选模型；不是白名单，候选仍会按可用性回退。
+- `modelPreferences`：按供应商指定首选模型，例如
+  `{"workbuddy":"deepseek-v4.1-flash","codearts":"deepseek-v4.1-flash"}`。未配置时
+  WorkBuddy CN 默认优先 `deepseek-v4.1-flash`，这是 dsh 实测较稳定的真实对话模型；
+  其他供应商按近 5 天可用性排序，没有成功记录时按供应商模型顺序选择，不按免费或倍率抢先选择。
+- `modelCandidates`：每个账号每次最多尝试的模型数，默认 4，范围 1–12。
+- `inputTokens`：真实请求的输入规模，默认 25000，范围 1000–25000。
+- `maxAttempts`：每个账号每个北京时间日最多保活尝试轮数，默认 3。
+- `timeoutMs`：单个模型请求的整体截止时间，默认 90 秒，范围 10–180 秒。WorkBuddy
+  CN 的 25k 输入请求可能先返回响应头、再继续流式读取；90 秒比 25 秒更接近 dsh 的
+  probe 容忍度，同时仍避免任务无限挂起。即使供应商
+  登录插件内部忽略中止信号，外层也会结束该候选并继续回退；账号较多时不要调得过大。
+- `logMaxBytes`：单个日志上限，默认 2 MiB，超出后轮转一份 `.1`。
+- `statePath`、`logPath`、`snapshotPath`、`commandPath`：可选绝对路径。
+
+## 执行周期与失败
+
+Magpie 自己的每日签到调度仍会在启动后约 2 分钟进行首轮，之后约每 30 分钟巡检；
+失败约 30 分钟后重试。本插件的定时任务是额外的统一调度，默认关闭，适合需要更
+频繁签到或保活的场景。本插件的定时任务不会在保存后立即执行，也不会在修改后
+重启 Magpie；修改配置会替换运行中的定时器，并从新的间隔重新计时。
+
+保活失败会按 `maxAttempts` 重试；达到上限后当天不再自动发送。网络失败、登录过期、
+模型不可用和空回复都会进入日志。遇到明确的 HTTP 402/429 额度耗尽或免费额度用尽时，
+当天停止自动重试，避免持续发送无效请求。手动“发送保活”或账号级“执行保活”可以重试
+当天失败或额度耗尽的账号；签到或保活当天已经成功时，即使手动触发也会跳过，不会重复
+发送。供应商整体停用时，账号级手动按钮也会禁用。
+
+## 日志
+
+默认日志文件：
+
+```text
+~/.config/magpie/workbuddy-daily.log.jsonl
+```
+
+查看最近记录：
+
+```sh
+node ./bin/daily-keepalive-log.js --limit 50
+node ./bin/daily-keepalive-log.js --day 2026-10-30 --status failed
+node ./bin/daily-keepalive-log.js --json
+```
+
+也能通过 Agent 工具 `quota-keepalive_logs` 查询。日志只记录账号稳定哈希、供应商、
+结果、模型和脱敏后的错误，不保存令牌、完整账号标识、企业标识或模型回复。
+
+## 安全
+
+- 状态和日志文件以 `0600` 创建，写入使用临时文件和原子 rename。
+- `plugin-auth.json` 的更新使用短锁，避免与 Magpie 或另一个任务并发写坏登录。
+- 模型回复不会写入状态或日志。
+- 日志和页面显示会对令牌、Bearer、API key 和账号标识做脱敏。
+- 未安装对应供应商插件、未登录或没有可用模型时，会明确记为跳过或失败。
+
+## 验证
+
+```sh
+bun test
+bun test --coverage
+```
+
+测试使用 mock 请求，不会访问供应商，也不会消耗积分。当前核心 JavaScript
+模块的行覆盖率和函数覆盖率均为 100%。性能边界测试覆盖 60 个供应商、600 个账号、
+5,000 个模型、10 万条记录和 16 组执行历史的聚合路径；测试使用宽松的固定预算，
+同时校验输出规模与结果正确性，避免只看耗时。页面视觉和真实供应商协议仍需在
+Magpie 中人工验收。

package/bin/daily-keepalive-log.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./workbuddy-daily-log.js"

package/bin/workbuddy-daily-log.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { resolve } from "node:path"
+import {
+  defaultLogPath,
+  formatLogRecords,
+  readDailyLogs,
+} from "../src/log.js"
+
+const STATUSES = new Set(["started", "success", "failed", "skipped"])
+
+function usage() {
+  return `Usage: workbuddy-daily-log [options]
+
+Options:
+  --limit N          Show the last N matching records (default 50, max 500)
+  --day YYYY-MM-DD   Filter by Beijing date
+  --status STATUS    started, success, failed, or skipped
+  --file PATH        Read one exact log file instead of current plus previous
+  --json             Print JSONL instead of human-readable lines
+  -h, --help         Show this help
+
+Default log:
+  ${defaultLogPath()}`
+}
+
+function parse(args) {
+  const out = { limit: 50, json: false }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === "-h" || arg === "--help") return { help: true }
+    if (arg === "--json") {
+      out.json = true
+      continue
+    }
+    if (!["--limit", "--day", "--status", "--file"].includes(arg)) {
+      throw new Error(`unknown option: ${arg}`)
+    }
+    const value = args[++i]
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`${arg} needs a value`)
+    }
+    if (arg === "--limit") out.limit = Number(value)
+    if (arg === "--day") out.day = value
+    if (arg === "--status") out.status = value
+    if (arg === "--file") out.file = resolve(value)
+  }
+  if (!Number.isInteger(out.limit) || out.limit < 1 || out.limit > 500) {
+    throw new Error("--limit must be an integer from 1 to 500")
+  }
+  if (out.day && !/^\d{4}-\d{2}-\d{2}$/.test(out.day)) {
+    throw new Error("--day must be YYYY-MM-DD")
+  }
+  if (out.status && !STATUSES.has(out.status)) {
+    throw new Error("--status must be started, success, failed, or skipped")
+  }
+  return out
+}
+
+async function main() {
+  const args = parse(process.argv.slice(2))
+  if (args.help) {
+    console.log(usage())
+    return
+  }
+  const logPath = args.file || process.env.WORKBUDDY_DAILY_LOG || defaultLogPath()
+  const result = await readDailyLogs({
+    logPath,
+    includePrevious: !args.file,
+    day: args.day || "",
+    status: args.status || "",
+    limit: args.limit,
+  })
+  if (result.malformed) {
+    console.error(`Skipped ${result.malformed} malformed or unrelated JSONL line(s).`)
+  }
+  if (!result.records.length) {
+    console.log("没有找到符合条件的日志记录。")
+    console.log(`已查看:\n${result.files.join("\n")}`)
+    return
+  }
+  if (args.json) {
+    console.log(result.records.map((record) => JSON.stringify(record)).join("\n"))
+  } else {
+    console.log(formatLogRecords(result.records))
+  }
+}
+
+main().catch((error) => {
+  console.error(`读取日志失败: ${error instanceof Error ? error.message : error}`)
+  process.exitCode = 1
+})

package/index.js

@@ -0,0 +1,333 @@
+import { resolveKeepaliveOptions } from "./src/config.js"
+import { beijingDay } from "./src/common.js"
+import {
+  formatLogRecords,
+  readDailyLogs,
+} from "./src/log.js"
+import { appendDailyLog, newRunId } from "./src/log.js"
+import { readLivePluginOptions } from "./src/live-options.js"
+import { consumePendingCommand, runCommand } from "./src/runner.js"
+import { snapshotWarning, writeDailySnapshot } from "./src/snapshot.js"
+import { createProviderCheckin } from "./src/checkin-runner.js"
+import { createWorkBuddyKeepalive } from "./src/workbuddy.js"
+import { readCommand } from "./src/commands.js"
+
+const LOG_STATUSES = new Set(["started", "success", "failed", "skipped"])
+const SCHEDULER = Symbol.for("quota-keepalive.scheduler")
+const OPTIONS_WATCHER = Symbol.for("quota-keepalive.options-watcher")
+const QUOTA_REFRESHER = Symbol.for("quota-keepalive.quota-refresher")
+const REFRESH_INTERVAL_MS = 60_000
+
+export function stopScheduler() {
+  const previous = globalThis[SCHEDULER]
+  if (previous?.timer) clearInterval(previous.timer)
+  if (previous) delete globalThis[SCHEDULER]
+}
+
+export function startScheduler({ config, checkin, keepalive }) {
+  // Every behavior setting must participate in the signature. Otherwise a
+  // model or provider/account preference change would leave the running timer
+  // on the previous closures and configuration.
+  const signature = JSON.stringify(config)
+  const previous = globalThis[SCHEDULER]
+  if (previous?.signature === signature) return
+  stopScheduler()
+  if (!config.scheduleEnabled) return
+  let running = false
+  const timer = setInterval(async () => {
+    if (running) return
+    running = true
+    try {
+      const result = await runCommand({
+        action: config.scheduleAction,
+        config,
+        checkin,
+        keepalive,
+        force: false,
+      })
+      await appendDailyLog({
+        logPath: config.logPath,
+        logMaxBytes: config.logMaxBytes,
+        entry: {
+          ts: new Date().toISOString(),
+          day: beijingDay(),
+          provider: "quota-keepalive",
+          run: result.run || newRunId(),
+          event: "schedule",
+          status: result.status,
+          outcome: result.status,
+          message: result.summary,
+        },
+      })
+      await writeDailySnapshot({
+        ...(config.configHome ? { configHome: config.configHome } : {}),
+        logPath: config.logPath,
+        snapshotPath: config.snapshotPath,
+        commandPath: config.commandPath,
+      })
+    } catch (error) {
+      await appendDailyLog({
+        logPath: config.logPath,
+        logMaxBytes: config.logMaxBytes,
+        entry: {
+          ts: new Date().toISOString(),
+          day: beijingDay(),
+          provider: "quota-keepalive",
+          run: newRunId(),
+          event: "schedule",
+          status: "failed",
+          outcome: "failed",
+          error: error instanceof Error ? error.message : String(error),
+        },
+      })
+    } finally {
+      running = false
+    }
+  }, config.scheduleMinutes * 60_000)
+  timer.unref?.()
+  globalThis[SCHEDULER] = { timer, signature }
+}
+
+export function stopOptionsWatcher() {
+  const previous = globalThis[OPTIONS_WATCHER]
+  if (previous?.timer) clearInterval(previous.timer)
+  if (previous) delete globalThis[OPTIONS_WATCHER]
+}
+
+export function stopQuotaRefresher() {
+  const previous = globalThis[QUOTA_REFRESHER]
+  if (previous?.timer) clearInterval(previous.timer)
+  if (previous?.initial) clearTimeout(previous.initial)
+  if (previous) delete globalThis[QUOTA_REFRESHER]
+}
+
+export async function refreshQuotasNow({
+  config,
+  run = runCommand,
+  command = readCommand,
+  log = appendDailyLog,
+}) {
+  const current = await command(config.commandPath).catch(() => null)
+  if (current && ["queued", "running"].includes(current.status)) {
+    return { status: "skipped", summary: "额度刷新已跳过：已有任务正在执行。" }
+  }
+  let result
+  try {
+    result = await run({ action: "refresh", config })
+  } catch (error) {
+    result = {
+      run: newRunId(),
+      status: "failed",
+      summary: `额度刷新失败：${error?.message || error}`,
+      error: error?.message || String(error),
+    }
+  }
+  await log({
+    logPath: config.logPath,
+    logMaxBytes: config.logMaxBytes,
+    entry: {
+      ts: new Date().toISOString(),
+      day: beijingDay(),
+      provider: "quota-keepalive",
+      run: result.run || newRunId(),
+      event: "refresh",
+      status: result.status,
+      outcome: result.status,
+      message: result.summary,
+      ...(result.error ? { error: result.error } : {}),
+    },
+  }).catch(() => {})
+  await writeDailySnapshot({
+    ...(config.configHome ? { configHome: config.configHome } : {}),
+    logPath: config.logPath,
+    snapshotPath: config.snapshotPath,
+    commandPath: config.commandPath,
+  }).catch((error) => {
+    console.warn(`[quota-keepalive] ${snapshotWarning(error)}`)
+  })
+  return result
+}
+
+export function startQuotaRefresher({
+  config,
+  refresh = refreshQuotasNow,
+  intervalMs = REFRESH_INTERVAL_MS,
+  firstDelayMs = 30_000,
+}) {
+  const signature = JSON.stringify([
+    config.configHome || "",
+    config.commandPath,
+    config.providerPreferences,
+  ])
+  const previous = globalThis[QUOTA_REFRESHER]
+  if (previous?.signature === signature) return
+  stopQuotaRefresher()
+
+  let running = false
+  const tick = async () => {
+    if (running) return
+    running = true
+    try {
+      await refresh({ config })
+    } catch (error) {
+      console.warn(`[quota-keepalive] cannot refresh quotas: ${error?.message || error}`)
+    } finally {
+      running = false
+    }
+  }
+  const initial = setTimeout(tick, firstDelayMs)
+  const timer = setInterval(tick, intervalMs)
+  initial.unref?.()
+  timer.unref?.()
+  globalThis[QUOTA_REFRESHER] = { timer, initial, signature }
+}
+
+export function startOptionsWatcher({
+  input,
+  rawOptions,
+  config,
+  readOptions = readLivePluginOptions,
+  start = startScheduler,
+  consume = consumePendingCommand,
+  makeCheckin = createProviderCheckin,
+  makeKeepalive = createWorkBuddyKeepalive,
+  startRefresh = startQuotaRefresher,
+}) {
+  stopOptionsWatcher()
+  if (!config.watchOptions) return
+  let running = false
+  const timer = setInterval(async () => {
+    if (running) return
+    running = true
+    try {
+      const liveOptions = await readOptions(config.configHome)
+      const liveRaw = { ...rawOptions, ...liveOptions }
+      const liveConfig = resolveKeepaliveOptions(liveRaw)
+      const checkin = makeCheckin({ input, config: liveConfig })
+      const keepalive = makeKeepalive({ input, config: liveConfig })
+      start({ config: liveConfig, checkin, keepalive })
+      startRefresh({ config: liveConfig })
+      await consume({
+        config: liveConfig,
+        rawOptions: liveRaw,
+        checkin,
+        keepalive,
+      })
+    } catch (error) {
+      console.warn(`[quota-keepalive] cannot read live options: ${error?.message || error}`)
+    } finally {
+      running = false
+    }
+  }, 2_000)
+  timer.unref?.()
+  globalThis[OPTIONS_WATCHER] = { timer }
+}
+
+export function logTool(config) {
+  return {
+    logs: {
+      description:
+        "Reads recent quota check-in and keepalive logs. Logs use hashed account tags and never include tokens, full account ids, or model replies.",
+      args: {
+        type: "object",
+        properties: {
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 200,
+            default: 50,
+            description: "Number of most recent matching records to return.",
+          },
+          day: {
+            type: "string",
+            pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+            description: "Only return records for this Beijing date (YYYY-MM-DD).",
+          },
+          status: {
+            type: "string",
+            enum: ["started", "success", "failed", "skipped"],
+            description: "Only return records with this status.",
+          },
+          file: {
+            type: "string",
+            enum: ["all", "current", "previous"],
+            default: "all",
+            description: "Read the current log, its previous rotated log, or both.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async execute(args = {}) {
+        const limit = args.limit === undefined ? 50 : Number(args.limit)
+        if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+          throw new Error("limit must be an integer from 1 to 200")
+        }
+        if (args.day && !/^\d{4}-\d{2}-\d{2}$/.test(args.day)) {
+          throw new Error("day must be YYYY-MM-DD")
+        }
+        if (args.status && !LOG_STATUSES.has(args.status)) {
+          throw new Error("status must be started, success, failed, or skipped")
+        }
+        const file = args.file || "all"
+        if (!["all", "current", "previous"].includes(file)) {
+          throw new Error("file must be all, current, or previous")
+        }
+
+        const previousOnly = file === "previous"
+        const result = await readDailyLogs({
+          logPath: previousOnly ? `${config.logPath}.1` : config.logPath,
+          includePrevious: file === "all",
+          day: args.day || "",
+          status: args.status || "",
+          limit,
+        })
+        if (!result.records.length) {
+          return `No quota keepalive log records matched. Looked in:\n${result.files.join("\n")}`
+        }
+        const warning = result.malformed
+          ? `\nSkipped ${result.malformed} malformed or unrelated line(s).`
+          : ""
+        return `Quota Keepalive logs (${result.records.length} records, Beijing time)${warning}\n${
+          formatLogRecords(result.records)
+        }`
+      },
+    },
+  }
+}
+
+// This plugin deliberately declares no provider/auth hook. The installed
+// provider plugins keep owning sign-in, model lists, quota and check-in for
+// WorkBuddy, CodeArts, MiniMax and every other provider. This plugin only
+// orchestrates their tasks, so Magpie's plugin card stays provider-neutral.
+export async function QuotaKeepalivePlugin(input, rawOptions = {}) {
+  const config = resolveKeepaliveOptions(rawOptions)
+  const checkin = createProviderCheckin({ input, config })
+  const keepalive = createWorkBuddyKeepalive({ input, config })
+  startScheduler({ config, checkin, keepalive })
+  startQuotaRefresher({ config })
+  startOptionsWatcher({ input, rawOptions, config })
+
+  await consumePendingCommand({ config, rawOptions, checkin, keepalive }).catch((error) => {
+    console.warn(`[quota-keepalive] cannot run the page command: ${error?.message || error}`)
+  })
+  await writeDailySnapshot({
+    ...(config.configHome ? { configHome: config.configHome } : {}),
+    logPath: config.logPath,
+    snapshotPath: config.snapshotPath,
+    commandPath: config.commandPath,
+  }).catch((error) => {
+    console.warn(`[quota-keepalive] ${snapshotWarning(error)}`)
+  })
+
+  return {
+    tool: logTool(config),
+  }
+}
+
+// Magpie treats every named export as a plugin entry unless the default
+// export identifies one server. Keep testable helpers named while exposing
+// only QuotaKeepalivePlugin to the host.
+export default {
+  id: "quota-keepalive",
+  server: QuotaKeepalivePlugin,
+}