koishi-plugin-anime-schedule 1.0.4 → 1.0.5

package/lib/config.d.ts

@@ -35,7 +35,10 @@ export interface Config {
     localize: {
         enabled: boolean;
         titleStyle: TitleStyle;
+        /** 标题与封面的缓存天数 */
         cacheTtlDays: number;
+        /** 评分与评价人数的缓存小时数 */
+        scoreTtlHours: number;
         /** 播出状态（是否已完结）的缓存有效期，单位小时 */
         airingTtlHours: number;
     };

package/lib/config.js

@@ -111,9 +111,14 @@ exports.Config = koishi_1.Schema.intersect([
             ])
                 .description('标题展示方式')
                 .default('localized'),
+            scoreTtlHours: koishi_1.Schema.number()
+                .min(1).step(1)
+                .description('评分与评价人数的缓存小时数。新番开播头几周评分天天在变，'
+                + '因此单独给一个比标题封面短得多的保质期')
+                .default(constants_1.DEFAULT_SCORE_TTL_HOURS),
             cacheTtlDays: koishi_1.Schema.number()
                 .min(1).step(1)
-                .description('标题、封面与评分的缓存天数')
+                .description('标题与封面的缓存天数')
                 .default(30),
             airingTtlHours: koishi_1.Schema.number()
                 .min(1).step(1)
@@ -204,6 +209,7 @@ function normalizeConfig(config) {
         localize: {
             ...config.localize,
             cacheTtlDays: int(config.localize?.cacheTtlDays, 30, 1),
+            scoreTtlHours: int(config.localize?.scoreTtlHours, constants_1.DEFAULT_SCORE_TTL_HOURS, 1),
             airingTtlHours: int(config.localize?.airingTtlHours, 6, 1),
         },
         render: {

package/lib/constants.d.ts

@@ -64,6 +64,13 @@ export declare const LOCALIZE_CACHE_FILE = "localize-cache.json";
  * v6：新增 `hasEpisodeTimes`。逐集档期不再是每条必取，需要靠它区分
  *     「没取过逐集档期」与「取过但没有集数日期」。
  */
+/**
+ * 评分与评价人数的缓存小时数。
+ *
+ * 比标题封面的 cacheTtlDays 短得多：新番开播头几周评分天天在变，样本量从个位数
+ * 涨到几百，用 30 天缓存会一直显示「只有十几个人投票」时的噪声值。
+ */
+export declare const DEFAULT_SCORE_TTL_HOURS = 24;
 export declare const LOCALIZE_CACHE_VERSION = 6;
 /** 本地化缓存最大条目数，超出后按写入时间淘汰最旧的一半 */
 export declare const LOCALIZE_CACHE_MAX_ENTRIES = 5000;

package/lib/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOG_MESSAGES = exports.RESPONSES = exports.MESSAGES = exports.IMAGE_THEME = exports.IMAGE_LAYOUT = exports.DEFAULT_FONT_FAMILY = exports.DEFAULT_JPEG_QUALITY = exports.BOLD_FONT_CANDIDATES = exports.FONT_CANDIDATES = exports.COVER_CACHE_MAX_FILES = exports.COVER_CACHE_TTL_MS = exports.COVER_CACHE_DIR = exports.COVER_MAX_BYTES = exports.COVER_TIMEOUT_MS = exports.COVER_CONCURRENCY = exports.LOCALIZE_CONCURRENCY = exports.EPISODE_QUERY_LIMIT = exports.LOCALIZE_CACHE_MAX_ENTRIES = exports.LOCALIZE_CACHE_VERSION = exports.LOCALIZE_CACHE_FILE = exports.LATE_NIGHT_END_HOUR = exports.IMAGE_LIST_TWO_COLUMN_AT = exports.IMAGE_MAX_CARDS = exports.DIGEST_LABELS = exports.PLUGIN_HOMEPAGE = exports.PLUGIN_VERSION = exports.DATA_DIR = exports.BANGUMI_DATA_FILE = exports.BANGUMI_DATA_FALLBACK_URLS = exports.ANILIST_MIN_INTERVAL_MS = exports.ANILIST_BATCH_SIZE = exports.ANILIST_API_URL = exports.BANGUMI_API_HOST = exports.PLUGIN_NAME = void 0;
+exports.LOG_MESSAGES = exports.RESPONSES = exports.MESSAGES = exports.IMAGE_THEME = exports.IMAGE_LAYOUT = exports.DEFAULT_FONT_FAMILY = exports.DEFAULT_JPEG_QUALITY = exports.BOLD_FONT_CANDIDATES = exports.FONT_CANDIDATES = exports.COVER_CACHE_MAX_FILES = exports.COVER_CACHE_TTL_MS = exports.COVER_CACHE_DIR = exports.COVER_MAX_BYTES = exports.COVER_TIMEOUT_MS = exports.COVER_CONCURRENCY = exports.LOCALIZE_CONCURRENCY = exports.EPISODE_QUERY_LIMIT = exports.LOCALIZE_CACHE_MAX_ENTRIES = exports.LOCALIZE_CACHE_VERSION = exports.DEFAULT_SCORE_TTL_HOURS = exports.LOCALIZE_CACHE_FILE = exports.LATE_NIGHT_END_HOUR = exports.IMAGE_LIST_TWO_COLUMN_AT = exports.IMAGE_MAX_CARDS = exports.DIGEST_LABELS = exports.PLUGIN_HOMEPAGE = exports.PLUGIN_VERSION = exports.DATA_DIR = exports.BANGUMI_DATA_FILE = exports.BANGUMI_DATA_FALLBACK_URLS = exports.ANILIST_MIN_INTERVAL_MS = exports.ANILIST_BATCH_SIZE = exports.ANILIST_API_URL = exports.BANGUMI_API_HOST = exports.PLUGIN_NAME = void 0;
 exports.buildUserAgent = buildUserAgent;
 exports.getMessages = getMessages;
 /** 插件名，同时作为日志前缀与 User-Agent 主体 */
@@ -80,6 +80,13 @@ exports.LOCALIZE_CACHE_FILE = 'localize-cache.json';
  * v6：新增 `hasEpisodeTimes`。逐集档期不再是每条必取，需要靠它区分
  *     「没取过逐集档期」与「取过但没有集数日期」。
  */
+/**
+ * 评分与评价人数的缓存小时数。
+ *
+ * 比标题封面的 cacheTtlDays 短得多：新番开播头几周评分天天在变，样本量从个位数
+ * 涨到几百，用 30 天缓存会一直显示「只有十几个人投票」时的噪声值。
+ */
+exports.DEFAULT_SCORE_TTL_HOURS = 24;
 exports.LOCALIZE_CACHE_VERSION = 6;
 /** 本地化缓存最大条目数，超出后按写入时间淘汰最旧的一半 */
 exports.LOCALIZE_CACHE_MAX_ENTRIES = 5000;

package/lib/services/digest.js

@@ -780,7 +780,9 @@ class DigestService {
             // 取不到（无 aniListId、没查到状态、或那条没给图）时回退 Bangumi。
             coverUrl: aniList?.coverUrl || (entry.bangumiId !== null ? (subject?.coverUrl ?? '') : ''),
             scoreValue,
-            score: scoreValue !== null ? scoreValue.toFixed(1) : '',
+            // 两位小数：`score` 由 `rating.count` 算出的算术平均得来（见 `LocalizeCacheEntry.score`），
+            // 比 Bangumi 自己给的一位小数更有区分度；四舍五入到一位后与网站显示一致
+            score: scoreValue !== null ? scoreValue.toFixed(2) : '',
             firstYear: firstDate ? Number(firstDate.slice(0, 4)) : null,
             firstMonth: firstDate ? Number(firstDate.slice(5, 7)) : null,
             subscribed: entry.bangumiId !== null && subscribed.has(`bgm:${entry.bangumiId}`),

package/lib/services/localizer.d.ts

@@ -37,6 +37,19 @@ export declare class Localizer {
     private scheduleFlush;
     /** 主动落盘，插件卸载与调度结束后调用 */
     save(): Promise<void>;
+    /**
+     * 这一条缓存是否还够用。
+     *
+     * 拆成「标题封面」与「评分」两个保质期，因为两者变化速度差很多：
+     *
+     * - **标题与封面**几乎不变，用 `cacheTtlDays`（默认 30 天）；
+     * - **评分**在新番开播头几周天天在变（样本量从个位数涨到几百），用 `scoreTtlHours`
+     *   （默认 24 小时）。早先两者共用 30 天，导致「只有 1 个人投票」时的 7.0 被当成
+     *   评分显示整整一个月，而网站早已是 6.1。
+     *
+     * @param wantEpisodeTimes 调用方这次是否需要逐集档期。需要时，缺档期的条目即使标题
+     *   还新鲜也得重取一次；不需要时（本季表、检索这类纯展示路径）就不为它白跑请求。
+     */
     private isFresh;
     /**
      * 批量取回条目详情，返回「条目 ID → 详情」。

package/lib/services/localizer.js

@@ -21,6 +21,42 @@ function resolveEpisodeTotal(subject) {
         return eps;
     return null;
 }
+/**
+ * 算评分，保留两位小数。
+ *
+ * **不用 `rating.score`**：Bangumi 只把它保留一位小数（实测 60 个条目里带两位小数的为 0），
+ * 直接拿来显示，第二位永远是 0，没有信息量。API 同时给了 `rating.count`
+ * （1~10 各分数段的人数），据此算**算术平均**即可拿到真实精度：
+ *
+ * ```
+ * 至高之力    score=6.1  count 平均=6.0833
+ * 药屋第三季  score=7.3  count 平均=7.3231
+ * 药屋第一季  score=7.5  count 平均=7.4764
+ * ```
+ *
+ * 与网站显示的关系：四舍五入到一位后与 `score` 一致（`6.0833 → 6.1`、`7.3231 → 7.3`），
+ * 因此不会出现「插件和网站对不上」的观感，只是多给了两位真实精度。
+ *
+ * `count` 缺失（老条目或没投票）时退回 `score`；两者都没有则返回 null。
+ */
+function computeScore(rating) {
+    const count = rating?.count;
+    if (count && typeof count === 'object') {
+        let sum = 0;
+        let votes = 0;
+        for (const [key, value] of Object.entries(count)) {
+            const score = Number(key);
+            const people = Number(value);
+            if (!Number.isFinite(score) || !Number.isFinite(people) || people <= 0)
+                continue;
+            sum += score * people;
+            votes += people;
+        }
+        if (votes > 0)
+            return Math.round((sum / votes) * 100) / 100;
+    }
+    return typeof rating?.score === 'number' ? rating.score : null;
+}
 /**
  * 兼容不同的 http 适配器：Koishi 的 http 服务返回响应体本身，
  * 而直接使用 axios 的调用方会拿到完整的响应对象。
@@ -135,14 +171,31 @@ class Localizer {
         }
         await this.flush();
     }
-    isFresh(entry) {
-        // 「不存在」也是有效结果：同一季内不必反复去问一个不会出现的条目
-        if (entry.missing)
+    /**
+     * 这一条缓存是否还够用。
+     *
+     * 拆成「标题封面」与「评分」两个保质期，因为两者变化速度差很多：
+     *
+     * - **标题与封面**几乎不变，用 `cacheTtlDays`（默认 30 天）；
+     * - **评分**在新番开播头几周天天在变（样本量从个位数涨到几百），用 `scoreTtlHours`
+     *   （默认 24 小时）。早先两者共用 30 天，导致「只有 1 个人投票」时的 7.0 被当成
+     *   评分显示整整一个月，而网站早已是 6.1。
+     *
+     * @param wantEpisodeTimes 调用方这次是否需要逐集档期。需要时，缺档期的条目即使标题
+     *   还新鲜也得重取一次；不需要时（本季表、检索这类纯展示路径）就不为它白跑请求。
+     */
+    isFresh(entry, wantEpisodeTimes) {
+        if (entry.missing) {
+            // 「不存在」也是有效结果：同一季内不必反复去问一个不会出现的条目
             return Date.now() - entry.cachedAt < this.config.localize.cacheTtlDays * 24 * 60 * 60 * 1000;
-        // 取过条目详情、却没取逐集档期（本季表与检索这两条路径会这样），
-        // 而完结判定需要逐集档期时，必须重新取一次而不是当作新鲜数据用。
+        }
+        // 取过条目详情、却没取逐集档期，而这次需要档期 → 必须重取。
         // 旧版缓存没有 hasEpisodeTimes 字段，按「取过」处理。
-        if (entry.hasEpisodeTimes === false)
+        if (wantEpisodeTimes && entry.hasEpisodeTimes === false)
+            return false;
+        // 评分单独算保质期：到期就重取详情，但重取时仍按调用方的需要决定要不要连档期一起取
+        const scoreAt = entry.scoreCachedAt ?? entry.cachedAt;
+        if (Date.now() - scoreAt >= this.config.localize.scoreTtlHours * 60 * 60 * 1000)
             return false;
         return Date.now() - entry.cachedAt < this.config.localize.cacheTtlDays * 24 * 60 * 60 * 1000;
     }
@@ -162,6 +215,8 @@ class Localizer {
             return result;
         await this.load();
         const wanted = [];
+        /** 这次要重取的条目里，缓存中已有的那一份；用于判断是否还需要补逐集档期 */
+        const previous = new Map();
         const seen = new Set();
         for (const id of ids) {
             if (!Number.isFinite(id) || seen.has(id))
@@ -174,16 +229,24 @@ class Localizer {
             }
             // 过期条目也先返回，避免一次请求失败就让整张表掉封面
             result.set(id, cached);
-            if (!this.isFresh(cached))
+            if (!this.isFresh(cached, wantEpisodeTimes)) {
                 wanted.push(id);
+                previous.set(id, cached);
+            }
         }
         if (!wanted.length)
             return result;
         const started = Date.now();
         const looked = await (0, utils_1.mapLimit)(wanted, constants_1.LOCALIZE_CONCURRENCY, async (id) => {
+            const stale = previous.get(id);
+            // 逐集档期只在「调用方要」且「有正规集数」时才值得请求：用它拿首末集日期。
+            //
+            // 已经取过档期的条目**不重复取**——评分每天刷新，而档期是另一笔请求，
+            // 跟着一起重发会让请求量凭空翻倍（周表 77 部就是多 77 个请求）。
+            // 只有「没取过」或「这次确实缺它」才补。
+            const needsTimes = wantEpisodeTimes && !(stale && stale.hasEpisodeTimes !== false);
             const subject = await this.fetchSubject(id);
-            // 逐集档期只在「调用方要」且「有正规集数」时才值得请求：用它拿首末集日期
-            const times = wantEpisodeTimes && subject && resolveEpisodeTotal(subject)
+            const times = needsTimes && subject && resolveEpisodeTotal(subject)
                 ? await this.fetchEpisodeTimes(id)
                 : null;
             return { id, subject, times };
@@ -193,18 +256,24 @@ class Localizer {
             if (!subject)
                 continue;
             ok++;
+            const stale = previous.get(id);
+            // 这次没重新取档期（评分刷新）时，沿用上一次的结果，别把它当「没有档期」
+            const hasTimes = times !== null || stale?.hasEpisodeTimes === true;
             const entry = {
                 subjectId: subject.id,
                 title: subject.name_cn?.trim() || subject.name,
                 coverUrl: subject.images?.large ?? subject.images?.common ?? '',
-                score: typeof subject.rating?.score === 'number' ? subject.rating.score : null,
+                score: computeScore(subject.rating),
                 ratingTotal: typeof subject.rating?.total === 'number' ? subject.rating.total : null,
                 totalEpisodes: resolveEpisodeTotal(subject),
-                hasEpisodeTimes: times !== null,
-                firstAirMs: times?.first ?? null,
-                lastAirMs: times?.last ?? null,
+                hasEpisodeTimes: hasTimes,
+                firstAirMs: times?.first ?? stale?.firstAirMs ?? null,
+                lastAirMs: times?.last ?? stale?.lastAirMs ?? null,
                 airDate: subject.date ?? null,
-                cachedAt: Date.now(),
+                // `cachedAt` 只在真的取全（含档期）时推进，否则标题封面的 30 天保质期会被
+                // 每天一次的评分刷新无限续期，等于永远不校验
+                cachedAt: times !== null || !stale ? Date.now() : stale.cachedAt,
+                scoreCachedAt: Date.now(),
             };
             this.memory.set(id, entry);
             this.scheduleFlush();

package/lib/types.d.ts

@@ -70,8 +70,26 @@ export interface LocalizeCacheEntry {
     /** 中文名，缺失时回落为日文原名 */
     title: string;
     coverUrl: string;
+    /**
+     * 评分，两位小数。
+     *
+     * 由 `rating.count`（各分数段人数）算出的**算术平均**，而不是 Bangumi 直接给的
+     * `rating.score`——后者只保留一位小数（实测 60 个条目里带两位小数的为 0），
+     * 自己算才有第二位。四舍五入到一位后与网站显示一致，不会造成「对不上」的观感。
+     * `rating.count` 缺失时退回 `rating.score`。
+     */
     score: number | null;
     ratingTotal: number | null;
+    /**
+     * 评分与 `ratingTotal` 的取回时刻。
+     *
+     * 与 `cachedAt` 分开，因为两者保质期差很多：标题与封面几乎不变（`cacheTtlDays`，
+     * 默认 30 天），而**新番的评分在开播头几周会剧烈变化**（样本量从个位数涨到几百），
+     * 用 30 天缓存会一直显示「只有十几个人投票」时的噪声值。见 `localize.scoreTtlHours`。
+     *
+     * 旧缓存没有这个字段，按 `cachedAt` 处理（即可能立刻被刷新一次）。
+     */
+    scoreCachedAt?: number;
     /**
      * Bangumi 给出的总集数，仅作缓存留档。
      *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-anime-schedule",
   "description": "番剧更新表与订阅提醒：每日 / 深夜档 / 本周 / 本季四张表，支持单部订阅",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -56,6 +56,7 @@ npm i koishi-plugin-anime-schedule
 | `output.format` | `image` | `image` / `text` |
 | `output.layout` | `table` | 图片排版：`table` / `list` |
 | `localize.titleStyle` | `localized` | `localized` 仅中文 / `both` 中文（日文原名）/ `original` 仅日文原名 |
+| `localize.scoreTtlHours` | `24` | 评分与评价人数的缓存小时数。新番开播头几周评分天天在变，因此单独给一个较短的保质期 |
 | `render.jpegQuality` | `100` | 图片编码质量，调低可减小体积 |
 | `advanced.debug` | `false` | 输出调试日志 |