koishi-plugin-codex-reset 0.1.5 → 0.1.6

package/README.md

@@ -24,11 +24,15 @@
 
 概率、最近重置、日历和历史时间线命令始终启用；安装并启用 `koishi-plugin-puppeteer` 后会发送对应图片，没有 Puppeteer 时概率和最近重置会回退为纯文本，日历和历史时间线会提示安装 Puppeteer。
 
-日历、月度统计及右侧动态仅展示已确认且日期不晚于今天的事件，不展示预告。日期优先使用实际发生日期，缺失时使用北京时间的确认日期；两者均缺失时不展示，不使用预计时间窗口代替实际日期。
-
-首次安装时的第一份快照只建立基线，不会把历史事件全部推送。插件将已见事件状态和待发送通知保存在 Koishi 工作目录的 `data/codex-reset/` 中；重启后继续去重并重试未成功的目标。API 暂时漏掉旧事件、随后又补回时，也不会把它再次当作新事件。只有最近 48 小时内发布的预告或确认事件才会新建推送；超过 48 小时仍未送达的通知会放弃。更改 API 地址或推送目标后会建立新的基线。
-
-图片生成最多同时进行 2 项，新的图片任务至少间隔 3 秒；历史图片超过 120 条事件时会提示缩小查询范围。图片中的长篇来源文字会截短。API 响应上限为 4 MiB。
+日历、月度统计及右侧动态仅展示已确认且日期不晚于今天的事件，不展示预告。日期优先使用实际发生日期，缺失时使用北京时间的确认日期；两者均缺失时不展示，不使用预计时间窗口代替实际日期。
+
+首次安装时的第一份快照只建立基线，不会把历史事件全部推送。插件将已见事件状态和待发送通知保存在 Koishi 工作目录的 `data/codex-reset/` 中；重启后继续去重并重试未成功的目标。API 暂时漏掉旧事件、随后又补回时，也不会把它再次当作新事件。只有最近 48 小时内发布的预告或确认事件才会新建推送；超过 48 小时仍未送达的通知会放弃。更改 API 地址或推送目标后会建立新的基线。
+
+从 0.1.6 起，需要启用 Koishi 数据库服务（例如 SQLite、MySQL 或 PostgreSQL）。完整 API 快照、ETag、最近同步时间和下次允许请求的时间保存在 `codex_reset_cache` 表中，相同 API 地址共用一份记录。所有查询命令只读数据库，不直接请求上游；首次同步尚未成功时会提示稍后再试。重启、重载插件后仍可查询已保存的数据，并继续遵守冷却时间。同步失败时保留上次成功的数据，可能暂时不是最新状态。
+
+后台默认每 660 秒同步一次；旧配置小于 660 秒时，实际请求也不会快于 660 秒。请求前先保存冷却时间，收到 HTTP 429 或 503 时遵循 `Retry-After`（也支持响应正文的 `retryAfter` 秒数），冷却期间不会因重启或手动查询再次请求。数据库写入失败时不会继续发起新的上游请求。
+
+图片生成最多同时进行 2 项，新的图片任务至少间隔 3 秒；历史图片超过 120 条事件时会提示缩小查询范围。图片中的长篇来源文字会截短。API 响应上限为 4 MiB。
 
 ## 安装
 
@@ -36,12 +40,12 @@
 npm install koishi-plugin-codex-reset
 ```
 
-如果需要概率卡片、最近重置卡片、日历或历史时间线图片，再安装并启用 `koishi-plugin-puppeteer`。不安装 Puppeteer 时，监控、最近重置和概率分析仍然可以使用，概率与最近重置命令回退为纯文本，日历和历史命令会给出提示。
+先在 Koishi 中启用一个数据库插件，再启用本插件；如果已经使用数据库服务，无需另建数据库。如果需要概率卡片、最近重置卡片、日历或历史时间线图片，再安装并启用 `koishi-plugin-puppeteer`。不安装 Puppeteer 时，监控、最近重置和概率分析仍然可以使用，概率与最近重置命令回退为纯文本，日历和历史命令会给出提示。
 
 ## 配置
 
 - `监控接口地址`：监控 API 地址，默认 `https://aihot.news/api/v1/codex-resets`。
-- `监控间隔`：轮询间隔，单位为秒，默认 300 秒。
+- `监控间隔`：轮询间隔，单位为秒，默认 660 秒（11 分钟）。实际请求间隔至少 660 秒，并遵守服务端更长的缓存及重试等待时间。
 - `请求超时时间`：单次 API 请求超时时间，单位为毫秒，默认 15000 毫秒。
 - `推送目标`：推送目标表，填写“平台”和“频道或群组 ID”；平台留空会按频道尝试在线 Bot，同一平台/频道只发送一次。
 - `推送重置预告`：是否推送预告。

package/lib/cache.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from 'koishi';
+import type { CodexResetsResponse } from './types';
+export declare const MIN_POLL_INTERVAL_MS = 660000;
+export interface SnapshotCache {
+    id: string;
+    snapshot: CodexResetsResponse | null;
+    etag: string | null;
+    fetchedAt: number;
+    nextFetchAt: number;
+    requestId: string;
+}
+declare module 'koishi' {
+    interface Tables {
+        codex_reset_cache: SnapshotCache;
+    }
+}
+export interface FetchResult {
+    snapshot: CodexResetsResponse | null;
+    etag: string | null;
+    notModified: boolean;
+    maxAgeMs: number;
+}
+export declare class SnapshotRequestError extends Error {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+export declare function extendCacheModel(ctx: Context): void;
+export declare class SnapshotStore {
+    private readonly ctx;
+    private readonly validate;
+    private readonly id;
+    constructor(ctx: Context, apiUrl: string, validate: (value: unknown) => value is CodexResetsResponse);
+    read(): Promise<SnapshotCache>;
+    refresh(intervalMs: number, timeoutMs: number, fetchSnapshot: (cache: SnapshotCache) => Promise<FetchResult>): Promise<SnapshotCache>;
+    private performRefresh;
+}

package/lib/cache.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotStore = exports.SnapshotRequestError = exports.MIN_POLL_INTERVAL_MS = void 0;
+exports.extendCacheModel = extendCacheModel;
+const node_crypto_1 = require("node:crypto");
+// Leave a little room beyond AIHOT's ten-minute full-history limit.
+exports.MIN_POLL_INTERVAL_MS = 660_000;
+const TABLE = 'codex_reset_cache';
+const inFlight = new WeakMap();
+class SnapshotRequestError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.SnapshotRequestError = SnapshotRequestError;
+function extendCacheModel(ctx) {
+    ctx.model.extend(TABLE, {
+        id: 'string',
+        snapshot: { type: 'json', nullable: true, initial: null },
+        etag: { type: 'string', nullable: true, initial: null },
+        fetchedAt: { type: 'double', initial: 0 },
+        nextFetchAt: { type: 'double', initial: 0 },
+        requestId: { type: 'string', initial: '' },
+    }, { primary: 'id' });
+}
+class SnapshotStore {
+    ctx;
+    validate;
+    id;
+    constructor(ctx, apiUrl, validate) {
+        this.ctx = ctx;
+        this.validate = validate;
+        // Targets do not affect API data or the upstream request quota.
+        this.id = (0, node_crypto_1.createHash)('sha256').update(new URL(apiUrl).href).digest('hex');
+    }
+    async read() {
+        let [cache] = await this.ctx.database.get(TABLE, this.id);
+        if (!cache) {
+            try {
+                cache = await this.ctx.database.create(TABLE, { id: this.id });
+            }
+            catch (error) {
+                // Another instance may have created the same API cache concurrently.
+                const existing = await this.ctx.database.get(TABLE, this.id);
+                cache = existing[0];
+                if (!cache)
+                    throw error;
+            }
+        }
+        if (!this.validate(cache.snapshot))
+            return { ...cache, snapshot: null, etag: null };
+        return cache;
+    }
+    refresh(intervalMs, timeoutMs, fetchSnapshot) {
+        const root = this.ctx.root ?? this.ctx;
+        let requests = inFlight.get(root);
+        if (!requests)
+            inFlight.set(root, requests = new Map());
+        const pending = requests.get(this.id);
+        if (pending)
+            return pending;
+        const request = this.performRefresh(intervalMs, timeoutMs, fetchSnapshot)
+            .finally(() => requests.delete(this.id));
+        requests.set(this.id, request);
+        return request;
+    }
+    async performRefresh(intervalMs, timeoutMs, fetchSnapshot) {
+        const cache = await this.read();
+        const now = Date.now();
+        if (now < cache.nextFetchAt)
+            return cache;
+        const delay = Math.max(exports.MIN_POLL_INTERVAL_MS, intervalMs);
+        const requestId = (0, node_crypto_1.randomUUID)();
+        // Reserve the next request before network I/O. A restart or another plugin
+        // instance must observe this reservation, even if the request fails.
+        await this.ctx.database.set(TABLE, {
+            id: this.id,
+            nextFetchAt: cache.nextFetchAt,
+            requestId: cache.requestId,
+        }, {
+            requestId,
+            nextFetchAt: now + Math.max(delay, timeoutMs + 1000),
+        });
+        const reserved = await this.read();
+        if (reserved.requestId !== requestId)
+            return reserved;
+        try {
+            const result = await fetchSnapshot(cache);
+            await this.ctx.database.set(TABLE, { id: this.id, requestId }, {
+                snapshot: result.notModified ? cache.snapshot : result.snapshot,
+                etag: result.etag,
+                fetchedAt: Date.now(),
+                nextFetchAt: Math.max(now + delay, Date.now() + result.maxAgeMs),
+            });
+        }
+        catch (error) {
+            const retryAfterMs = error instanceof SnapshotRequestError ? error.retryAfterMs : 0;
+            await this.ctx.database.set(TABLE, { id: this.id, requestId }, {
+                nextFetchAt: Date.now() + Math.max(delay, retryAfterMs),
+            });
+            throw error;
+        }
+        return this.read();
+    }
+}
+exports.SnapshotStore = SnapshotStore;

package/lib/calendar.js

@@ -175,7 +175,7 @@ function renderDetails(events) {
         const statusClass = event.status === 'confirmed' ? 'confirmed-state' : 'announced-state';
         return `<section class="event-group">
       <div class="event-state ${statusClass}"><span class="state-icon">${event.status === 'confirmed' ? '✓' : '◷'}</span>${status}</div>
-      <h2>${escapeHtml(event.title.slice(0, 200))}</h2>
+      <h2>${escapeHtml(event.title.slice(0, 200))}</h2>
       ${renderPostCard(event, post)}
     </section>`;
     }).join('');
@@ -270,7 +270,7 @@ function renderCalendarHtml(events, now = new Date()) {
       </header>
       <div class="weekday-row">${WEEK_NAMES.map((name) => `<span>${name}</span>`).join('')}</div>
       <div class="calendar-grid">${renderCalendarGrid(month, marks, selectedDate, today)}</div>
-      <div class="calendar-note">仅显示已确认事件；按北京时间记录实际发生日期，缺失时按确认日期展示；不含预告。</div>
+      <div class="calendar-note">仅显示已确认事件；按北京时间记录实际发生日期，缺失时按确认日期展示；不含预告。</div>
     </section>
     ${renderDetails(events)}
   </main>

package/lib/event.js

@@ -121,7 +121,7 @@ function renderLatestResetHtml(summary, now = new Date()) {
     </section>
     <section class="source">
       <header class="source-header"><h2>事件来源</h2><span>北京时间</span></header>
-      <h2 class="event-title">${escapeHtml(event.title.slice(0, 200))}</h2>
+      <h2 class="event-title">${escapeHtml(event.title.slice(0, 200))}</h2>
       ${renderSourcePost(summary)}
       <p class="source-note">${escapeHtml(event.scope ? `范围：${event.scope}` : '公开来源帖子记录')}</p>
       <div class="mark">RESET MONITOR</div>

package/lib/history.js

@@ -114,7 +114,7 @@ function renderTimelineItem(event) {
     <div class="timeline-dot ${statusClass}"></div>
     <div class="event-card">
       <div class="event-meta"><span class="type-label">${typeLabel(event)}</span><span class="status ${statusClass}">${statusLabel(event)}</span></div>
-      <h2>${escapeHtml(event.title.slice(0, 200))}</h2>
+      <h2>${escapeHtml(event.title.slice(0, 200))}</h2>
       ${schedule}
       ${renderPostPreview(event)}
     </div>

package/lib/index.d.ts

@@ -2,8 +2,10 @@ import { Context, Schema } from 'koishi';
 import type { Config as PluginConfig } from './types';
 export declare const name = "codex-reset";
 export declare const inject: {
+    required: string[];
     optional: string[];
 };
 export type Config = PluginConfig;
+export type { SnapshotCache } from './cache';
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,6 +10,7 @@ const calendar_1 = require("./calendar");
 const history_1 = require("./history");
 const event_1 = require("./event");
 const probability_1 = require("./probability");
+const cache_1 = require("./cache");
 const stats_1 = require("./stats");
 exports.name = 'codex-reset';
 const MAX_NOTIFICATION_AGE_MS = 48 * 60 * 60 * 1000;
@@ -21,6 +22,7 @@ const RENDER_START_INTERVAL_MS = 3000;
 class RenderBusyError extends Error {
 }
 exports.inject = {
+    required: ['database'],
     optional: ['puppeteer'],
 };
 exports.Config = koishi_1.Schema.object({
@@ -29,8 +31,8 @@ exports.Config = koishi_1.Schema.object({
         .description('监控接口地址。通常不需要修改。'),
     pollInterval: koishi_1.Schema.number()
         .min(60)
-        .default(300)
-        .description('监控间隔，单位为秒。AIHOT 推荐约 5 分钟轮询一次。'),
+        .default(660)
+        .description('监控间隔，单位为秒，默认 660 秒。兼容旧配置，实际请求间隔至少 660 秒；重启后继续遵守已保存的冷却时间。'),
     requestTimeout: koishi_1.Schema.number()
         .min(5000)
         .default(15000)
@@ -219,8 +221,7 @@ async function sendToTargets(ctx, targets, content, deliveredBindings, onDeliver
 class CodexResetMonitor {
     ctx;
     config;
-    snapshot = null;
-    etag = null;
+    snapshots;
     pollPromise = null;
     disposed = false;
     statePath;
@@ -233,22 +234,26 @@ class CodexResetMonitor {
     constructor(ctx, config) {
         this.ctx = ctx;
         this.config = config;
+        this.snapshots = new cache_1.SnapshotStore(ctx, config.apiUrl, isSnapshot);
         const instanceId = (0, node_crypto_1.createHash)('sha256')
             .update(JSON.stringify({ apiUrl: config.apiUrl, targets: config.targets }))
             .digest('hex').slice(0, 16);
         this.statePath = (0, node_path_1.join)(ctx.baseDir, 'data', 'codex-reset', `${instanceId}.json`);
         this.stateLoaded = this.loadState();
     }
-    get currentSnapshot() {
-        return this.snapshot;
-    }
     get hasPuppeteer() {
         return Boolean(this.ctx.puppeteer);
     }
     async ensureSnapshot() {
-        if (!this.snapshot)
-            await this.poll();
-        return this.snapshot;
+        // Commands only read the database. A missing snapshot must not turn every
+        // user command into another upstream request during a rate-limit window.
+        try {
+            return (await this.snapshots.read()).snapshot;
+        }
+        catch (error) {
+            this.ctx.logger('codex-reset').warn(`读取重置数据失败：${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
     }
     async poll() {
         if (this.disposed)
@@ -263,24 +268,32 @@ class CodexResetMonitor {
             this.pollPromise = null;
         }
     }
+    async start() {
+        await this.poll();
+        if (!this.disposed) {
+            this.ctx.setInterval(() => this.poll(), Math.max(cache_1.MIN_POLL_INTERVAL_MS, this.config.pollInterval * 1000));
+        }
+    }
     dispose() {
         this.disposed = true;
     }
     async performPoll() {
         try {
             await this.stateLoaded;
-            const result = await this.fetchSnapshot();
-            if (!result.notModified && result.snapshot) {
-                this.snapshot = result.snapshot;
-                this.etag = result.etag ?? this.etag;
+            if (this.disposed)
+                return;
+            const cache = await this.snapshots.refresh(this.config.pollInterval * 1000, this.config.requestTimeout, (cached) => this.fetchSnapshot(cached));
+            if (this.disposed)
+                return;
+            if (cache.snapshot) {
                 if (!this.initialized) {
                     // A fresh installation starts with the entire current snapshot as its baseline.
-                    for (const event of result.snapshot.events)
+                    for (const event of cache.snapshot.events)
                         this.markSeen(event);
                     this.initialized = true;
                 }
                 else {
-                    this.captureChanges(result.snapshot, Date.now());
+                    this.captureChanges(cache.snapshot, Date.now());
                 }
             }
             await this.flushPending();
@@ -428,67 +441,90 @@ class CodexResetMonitor {
         if (changed)
             await this.saveState();
     }
-    async fetchSnapshot() {
+    async fetchSnapshot(cache) {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.config.requestTimeout);
         try {
             const headers = {
                 Accept: 'application/json',
-                'User-Agent': 'koishi-plugin-codex-reset/0.1.5',
+                'User-Agent': 'koishi-plugin-codex-reset/0.1.6',
             };
-            if (this.etag && this.snapshot)
-                headers['If-None-Match'] = this.etag;
+            if (cache.etag && cache.snapshot)
+                headers['If-None-Match'] = cache.etag;
             const response = await fetch(this.config.apiUrl, {
                 method: 'GET',
                 headers,
                 signal: controller.signal,
             });
-            if (response.status === 304 && this.snapshot) {
-                return { snapshot: null, etag: this.etag, notModified: true };
+            const maxAgeMs = Math.max(0, ...Array.from((response.headers.get('cache-control') ?? '').matchAll(/(?:^|[,\s])(?:s-maxage|max-age)=(\d+)/gi), (match) => Number(match[1]) * 1000).filter(Number.isFinite));
+            if (response.status === 304 && cache.snapshot) {
+                return { snapshot: null, etag: response.headers.get('etag') ?? cache.etag, notModified: true, maxAgeMs };
             }
             if (response.status === 304)
                 throw new Error('服务端在没有本地快照时返回了 304');
-            if (!response.ok)
-                throw new Error(`HTTP ${response.status}`);
-            const declaredLength = Number(response.headers.get('content-length'));
-            if (declaredLength > MAX_API_RESPONSE_BYTES)
-                throw new Error('API 响应超过 4 MiB');
-            if (!response.body)
-                throw new Error('API 响应没有内容');
-            const reader = response.body.getReader();
-            const chunks = [];
-            let size = 0;
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                size += value.byteLength;
-                if (size > MAX_API_RESPONSE_BYTES) {
-                    await reader.cancel();
-                    throw new Error('API 响应超过 4 MiB');
+            if (response.status === 429 || response.status === 503) {
+                const retryAfter = response.headers.get('retry-after');
+                let retryAfterMs = 0;
+                if (retryAfter) {
+                    retryAfterMs = /^\d+$/.test(retryAfter.trim())
+                        ? Number(retryAfter) * 1000
+                        : Date.parse(retryAfter) - Date.now();
+                }
+                try {
+                    const problem = await this.readResponseBody(response);
+                    if (isRecord(problem) && typeof problem.retryAfter === 'number' && Number.isFinite(problem.retryAfter)) {
+                        retryAfterMs = Math.max(Number.isFinite(retryAfterMs) ? retryAfterMs : 0, problem.retryAfter * 1000);
+                    }
                 }
-                chunks.push(value);
+                catch {
+                    // An HTML or malformed error body must still honor Retry-After.
+                }
+                retryAfterMs = Math.max(cache_1.MIN_POLL_INTERVAL_MS, Number.isFinite(retryAfterMs) ? retryAfterMs : 0);
+                throw new cache_1.SnapshotRequestError(`HTTP ${response.status}，至少等待 ${Math.ceil(retryAfterMs / 1000)} 秒后重试`, retryAfterMs);
             }
-            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            const body = await this.readResponseBody(response);
             if (!isSnapshot(body))
                 throw new Error('响应格式不符合 Codex 重置 API v1');
             return {
                 snapshot: body,
                 etag: response.headers.get('etag'),
                 notModified: false,
+                maxAgeMs,
             };
         }
         finally {
             clearTimeout(timeout);
         }
     }
+    async readResponseBody(response) {
+        const declaredLength = Number(response.headers.get('content-length'));
+        if (declaredLength > MAX_API_RESPONSE_BYTES)
+            throw new Error('API 响应超过 4 MiB');
+        if (!response.body)
+            throw new Error('API 响应没有内容');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_API_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new Error('API 响应超过 4 MiB');
+            }
+            chunks.push(value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
 }
 function apply(ctx, config) {
+    (0, cache_1.extendCacheModel)(ctx);
     const monitor = new CodexResetMonitor(ctx, config);
-    ctx.on('ready', () => {
-        void monitor.poll();
-        ctx.setInterval(() => void monitor.poll(), config.pollInterval * 1000);
-    });
+    ctx.on('ready', () => monitor.start());
     ctx.on('dispose', () => monitor.dispose());
     ctx.command('codex.probability', '分析 Codex 重置事件的历史概率')
         .alias('重置概率')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-codex-reset",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Monitor AIHOT Codex reset events and notify Koishi channels.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -44,6 +44,7 @@
     }
   },
   "devDependencies": {
+    "@minatojs/driver-sqlite": "4.7.0",
     "@types/node": "^22.0.0",
     "koishi": "^4.18.9",
     "typescript": "^5.7.0"