pixivflow 3.0.2 → 3.1.0

package/dist/commands/TopicCommand.js

@@ -7,6 +7,7 @@ const Database_1 = require("../storage/Database");
 const PixivAuth_1 = require("../auth/PixivAuth");
 const createPixivFlowClient_1 = require("../pixiv-client/createPixivFlowClient");
 const createTopicPipeline_1 = require("../topic/createTopicPipeline");
+const TopicPipeline_1 = require("../topic/TopicPipeline");
 const TopicResolver_1 = require("../topic/TopicResolver");
 const TopicCache_1 = require("../topic/TopicCache");
 const node_path_1 = require("node:path");
@@ -50,27 +51,48 @@ class TopicCommand extends Command_1.BaseCommand {
             database.close();
         }
     }
-    async resolve(context, _args, topic) {
+    async resolve(context, args, topic) {
         if (!topic) {
             console.error('\nUsage: pixivflow topic resolve <topic> [--type illustration|novel|all] [--refresh]\n');
             return this.failure('Missing topic for resolve');
         }
-        const type = (String(_args.options.type ?? 'all'));
-        const refresh = Boolean(_args.options.refresh);
+        const type = (String(args.options.type ?? 'all'));
+        const refresh = Boolean(args.options.refresh);
         const types = type === 'all' ? ['illustration', 'novel'] : [type];
         return this.withClient(context, async ({ client, database }) => {
             const cache = new TopicCache_1.TopicCache((0, node_path_1.dirname)(database.getDatabasePath()) + '/topic-cache');
+            const discovery = context.config.targets?.find((target) => target.mode === 'topic')?.topicDiscovery ?? {};
+            // §tag-provenance: the audit surface for "the original tag dominates and no
+            // related tag outranks it". Each row exposes where the tag came from, its
+            // semantic weight and whether the current tagRelations/relatedTags settings
+            // would actually search it today (the `searched` column).
+            const rows = [];
+            const lines = [];
             for (const contentType of types) {
                 const resolver = new TopicResolver_1.TopicResolver(client, cache, context.config.download?.requestDelay ?? 500);
                 const { space, fromCache, degraded } = await resolver.resolve(topic, contentType, { refresh });
-                console.log(`\nTopic: ${topic}  (${contentType})  ${fromCache ? (degraded ? '· stale cache' : '· cache') : '· fresh'}`);
-                console.log('Tag'.padEnd(28) + 'Score'.padStart(7) + 'Occ'.padStart(6) + 'Spec'.padStart(7));
+                const walked = (0, TopicPipeline_1.selectWalkedTags)(space.tags, key(topic), discovery.tagRelations);
+                const channels = new Set((0, TopicPipeline_1.recallChannels)(walked, key(topic), relatedMode(discovery.relatedTags)).map((tag) => key(tag.name)));
+                lines.push('');
+                lines.push(`Topic: ${topic}  (${contentType})  ${fromCache ? (degraded ? '· stale cache' : '· cache') : '· fresh'}`);
+                lines.push('Name'.padEnd(24) + 'Trans'.padEnd(16) + 'Source'.padEnd(28) + 'Weight'.padStart(7) + 'Score'.padStart(7) + 'Seed'.padStart(6) + 'Searched'.padStart(10));
+                const tagRows = [];
                 for (const tag of space.tags) {
-                    const name = (tag.name + (tag.translatedName ? ` / ${tag.translatedName}` : '')).slice(0, 27);
-                    console.log(name.padEnd(28) + tag.score.toFixed(2).padStart(7) + String(tag.occurrences).padStart(6) + tag.specificity.toFixed(2).padStart(7));
+                    const source = tag.source ?? (tag.seed ? 'seed' : 'cooccurrence');
+                    const weight = tag.weight ?? tag.score;
+                    const searched = channels.has(key(tag.name));
+                    tagRows.push({ name: tag.name, translatedName: tag.translatedName, source, weight, score: tag.score, seed: tag.seed, searched });
+                    lines.push(tag.name.slice(0, 23).padEnd(24)
+                        + (tag.translatedName ?? '-').slice(0, 15).padEnd(16)
+                        + source.padEnd(28)
+                        + weight.toFixed(2).padStart(7)
+                        + tag.score.toFixed(2).padStart(7)
+                        + (tag.seed ? 'yes' : 'no').padStart(6)
+                        + (searched ? 'yes' : 'no').padStart(10));
                 }
+                rows.push({ contentType, fromCache, degraded, tags: tagRows });
             }
-            return this.success('Topic resolved', { topic });
+            return this.success(lines.join('\n'), { topic, types: rows });
         });
     }
     async test(context, args, topic) {
@@ -92,6 +114,7 @@ class TopicCommand extends Command_1.BaseCommand {
                 const { works, selection } = await pipeline.selectWorks(target, contentType, day, limit, { refresh }, {});
                 console.log(`\n=== ${contentType} topic "${topic}" day ${day} ===`);
                 console.log(`resolvedTags=${selection.resolvedTagCount} raw=${selection.rawCount} deduped=${selection.dedupedCount} accepted=${selection.acceptedCount} selected=${works.length}`);
+                console.log(`searchedTags=${(selection.searchedTags ?? []).join(', ')}`);
                 selection.selected.forEach((c, i) => {
                     console.log(`  #${i + 1} id=${c.id} pop=${c.popularity.toFixed(1)} meta=${c.metadataScore.toFixed(2)}  ${c.title}`);
                 });
@@ -103,7 +126,8 @@ class TopicCommand extends Command_1.BaseCommand {
     getUsage() {
         return [
             'topic resolve <topic> [--type all|illustration|novel] [--refresh]',
-            '  Show the Pixiv-derived related tag space for a topic (cached).',
+            '  Show the Pixiv-derived related tag space for a topic (cached), with each',
+            '  tag\'s provenance (source), semantic weight, score and whether it is searched.',
             '',
             'topic test <topic> [--type all|illustration|novel] [--date YESTERDAY|YYYY-MM-DD] [--limit N] [--refresh]',
             '  Dry-run a daily selection: resolved tags, candidate counts, Top N (no downloads).',
@@ -111,4 +135,12 @@ class TopicCommand extends Command_1.BaseCommand {
     }
 }
 exports.TopicCommand = TopicCommand;
+/** Same normalization as the pipeline/resolver keys (trim + NFKC + lowercase). */
+function key(value) {
+    return value.normalize('NFKC').trim().toLocaleLowerCase();
+}
+/** Unknown modes fall back to the historical 'always', as in the pipeline. */
+function relatedMode(value) {
+    return value === 'when_seed_insufficient' || value === 'never' ? value : 'always';
+}
 //# sourceMappingURL=TopicCommand.js.map

package/dist/config/types.d.ts

@@ -4,6 +4,25 @@
 export type TargetType = 'illustration' | 'novel';
 import type { DeliveryCapabilityOverrides } from '../delivery/capabilities';
 export type DeliveryFieldValue = string | number | boolean | string[];
+/** Provenance names accepted by `TopicDiscoveryConfig.tagRelations`. */
+export declare const TAG_RELATION_SOURCES: readonly ["seed", "cooccurrence", "autocomplete"];
+export type TagRelationSource = (typeof TAG_RELATION_SOURCES)[number];
+/**
+ * Which resolved tags may become recall channels (§tag-provenance). Every list
+ * is optional and the defaults reproduce the pre-existing behaviour: walk the
+ * whole resolved space.
+ *
+ * `deny` always wins, then `allowSources`, then `allow`. The seed tag is never
+ * dropped by `allow`/`allowSources` — only `deny` can drop it.
+ */
+export interface TagRelationsConfig {
+    /** Provenance categories allowed to be walked (default: all three). */
+    allowSources?: TagRelationSource[];
+    /** If non-empty: ONLY these tag names are walked (the seed tag is kept). */
+    allow?: string[];
+    /** Always dropped, wins over `allow`/`allowSources` (default: none). */
+    deny?: string[];
+}
 /** Discovery tuning for mode='topic'. Every value has a safe default. */
 export interface TopicDiscoveryConfig {
     /** Max related tags used to build the search space (default 12). */
@@ -12,12 +31,42 @@ export interface TopicDiscoveryConfig {
     sampleWorks?: number;
     /** Cache lifetime in days for the resolved tag space (default 7). */
     cacheDays?: number;
-    /** Minimum relatedness score for a tag to enter the space (default 0.18). */
+    /** Minimum relatedness score for a tag to enter the space (default 0.22). */
     minScore?: number;
     /** Ignore a fresh cache and re-discover now (default false). */
     refresh?: boolean;
     /** Include R-18 works in topic sampling and collection (default false). */
     includeR18?: boolean;
+    /**
+     * When related tags may be searched as their own recall channel (§topic-recall).
+     *
+     * - `'always'` (default): walk the whole resolved tag space every day.
+     * - `'when_seed_insufficient'`: search the topic tag first and only fall back
+     *   to related tags when it cannot fill `limit` for that day — a related tag
+     *   is a hint, never a substitute for the topic the operator asked for.
+     * - `'never'`: search the topic tag alone.
+     */
+    relatedTags?: 'always' | 'when_seed_insufficient' | 'never';
+    /**
+     * Make the seed tag a HARD ranking tier (default `'off'`).
+     *
+     * `'off'` keeps the documented popularity-only ranking, where relevance is
+     * only an acceptance gate. `'on'` guarantees the invariant "原始 Tag 权重最高，
+     * 相关 Tag 权重不得超过原始 Tag": a work carrying the seed tag always outranks
+     * a work that only matched expanded tags, however popular the latter is.
+     */
+    seedTier?: 'off' | 'on';
+    /** Which resolved tags may be walked as recall channels (default: all). */
+    tagRelations?: TagRelationsConfig;
+    /**
+     * Also treat a work's `translated_name` as a tag hit (default false).
+     *
+     * Today only the work's `name` is compared with the resolved tag keys. When
+     * enabled, a work whose translated tag name matches a resolved tag counts as
+     * carrying that tag (and a translated match of the seed counts as a seed hit).
+     * Default `false` keeps today's matching exactly.
+     */
+    matchTranslatedNames?: boolean;
 }
 /** Candidate collection tuning for mode='topic'. */
 export interface CandidateCollectionConfig {
@@ -866,6 +915,21 @@ export interface StandaloneConfig {
          * Default: 'eager'
          */
         materializationPolicy?: 'eager' | 'on-demand';
+        /**
+         * Novel cover content policy (§media-asset-pipeline / §novel-cover).
+         *
+         * Pixiv serves author covers and its own generated design covers from the
+         * same URL shape, so the content type is classified from the fetched bytes:
+         * a generated design (exactly 640x900) is never delivered as Telegram media.
+         * This key governs the UNCERTAIN case only — a cover whose header cannot be
+         * classified. 'skip' (default) is safe mode: never ship an unclassifiable
+         * cover, and log `coverType=unknown` so a future Pixiv format change is
+         * visible instead of silently leaking designs again. 'keep' prefers
+         * availability over certainty. A failed probe always keeps the cover.
+         */
+        novelCover?: {
+            unknown?: 'skip' | 'keep';
+        };
     };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/config/types.js

@@ -3,4 +3,7 @@
  * Configuration type definitions
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_RELATION_SOURCES = void 0;
+/** Provenance names accepted by `TopicDiscoveryConfig.tagRelations`. */
+exports.TAG_RELATION_SOURCES = ['seed', 'cooccurrence', 'autocomplete'];
 //# sourceMappingURL=types.js.map

package/dist/config/validation.js

@@ -191,6 +191,48 @@ function validateConfig(config, location, databasePath) {
                 if (td.includeR18 !== undefined && typeof td.includeR18 !== 'boolean') {
                     errors.push(`targets[${index}].topicDiscovery.includeR18: Must be a boolean (got ${typeof td.includeR18})`);
                 }
+                if (td.relatedTags !== undefined && !['always', 'when_seed_insufficient', 'never'].includes(td.relatedTags)) {
+                    errors.push(`targets[${index}].topicDiscovery.relatedTags: Must be "always", "when_seed_insufficient" or "never" (got ${String(td.relatedTags)})`);
+                }
+                // §tag-provenance: all optional; the defaults reproduce the pre-change
+                // behaviour (whole space walked, popularity-only ranking, name-only match).
+                if (td.seedTier !== undefined && !['off', 'on'].includes(td.seedTier)) {
+                    errors.push(`targets[${index}].topicDiscovery.seedTier: Must be "off" or "on" (got ${String(td.seedTier)})`);
+                }
+                if (td.matchTranslatedNames !== undefined && typeof td.matchTranslatedNames !== 'boolean') {
+                    errors.push(`targets[${index}].topicDiscovery.matchTranslatedNames: Must be a boolean (got ${typeof td.matchTranslatedNames})`);
+                }
+                const relations = td.tagRelations;
+                if (relations !== undefined) {
+                    if (typeof relations !== 'object' || relations === null || Array.isArray(relations)) {
+                        errors.push(`targets[${index}].topicDiscovery.tagRelations: Must be an object (got ${Array.isArray(relations) ? 'array' : typeof relations})`);
+                    }
+                    else {
+                        const knownSources = ['seed', 'cooccurrence', 'autocomplete'];
+                        const listErrors = (field) => (field === 'allowSources'
+                            ? `targets[${index}].topicDiscovery.tagRelations.allowSources: Must be an array of tag sources: ${knownSources.map((s) => `"${s}"`).join(', ')} (got ${JSON.stringify(relations.allowSources)})`
+                            : `targets[${index}].topicDiscovery.tagRelations.${field}: Must be an array of tag names (got ${JSON.stringify(relations[field])})`);
+                        const checkList = (field) => {
+                            const value = relations[field];
+                            if (value === undefined)
+                                return undefined;
+                            if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry.trim() === '')) {
+                                errors.push(listErrors(field));
+                                return undefined;
+                            }
+                            return value;
+                        };
+                        const allowSources = checkList('allowSources');
+                        if (allowSources) {
+                            const unknown = allowSources.filter((source) => !knownSources.includes(source));
+                            if (unknown.length > 0) {
+                                errors.push(`targets[${index}].topicDiscovery.tagRelations.allowSources: Unknown tag source${unknown.length > 1 ? 's' : ''} ${unknown.map((source) => `"${source}"`).join(', ')}; known sources are ${knownSources.map((s) => `"${s}"`).join(', ')}`);
+                            }
+                        }
+                        checkList('allow');
+                        checkList('deny');
+                    }
+                }
             }
             const cc = target.candidateCollection;
             if (cc) {
@@ -657,6 +699,11 @@ function validateConfig(config, location, databasePath) {
                 config.download.candidateScanLimit > 100)) {
             warnings.push('download.candidateScanLimit: Should be an integer between 1 and 100');
         }
+        if (config.download.novelCover?.unknown !== undefined &&
+            config.download.novelCover.unknown !== 'skip' &&
+            config.download.novelCover.unknown !== 'keep') {
+            errors.push(`download.novelCover.unknown: Must be "skip" or "keep" (got ${String(config.download.novelCover.unknown)})`);
+        }
     }
     // The bounded candidate scan is what stops a page full of duplicates from
     // burning a whole scheduled slot, so a non-integer value is reported here.

package/dist/domain/media/NovelCoverPolicy.d.ts

@@ -0,0 +1,28 @@
+/** What a fetched novel cover actually is. */
+export type NovelCoverType = 'custom' | 'pixiv_generated' | 'unknown';
+/**
+ * The canvas Pixiv renders its built-in novel cover designs on. Every design
+ * observed in production (floral, seasonal sweets, treasure map, genre label,
+ * city night) is delivered at exactly this size, while author covers keep their
+ * own dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ */
+export declare const PIXIV_GENERATED_COVER_WIDTH = 640;
+export declare const PIXIV_GENERATED_COVER_HEIGHT = 900;
+export interface NovelCoverPolicy {
+    /**
+     * What to do with a cover whose content type could not be classified.
+     * 'skip' (default): safe mode — never ship an unclassifiable cover.
+     * 'keep': prefer availability over certainty.
+     */
+    unknownCover: 'skip' | 'keep';
+}
+/** Production-safe default: an unclassifiable cover is never shipped. */
+export declare const DEFAULT_NOVEL_COVER_POLICY: NovelCoverPolicy;
+/**
+ * Classify fetched cover bytes. Returns `unknown` when the image header cannot
+ * be read (no decoder in this project, so only the header is inspected).
+ */
+export declare function classifyNovelCover(cover: ArrayBuffer | Uint8Array | null | undefined): NovelCoverType;
+/** The delivery decision for one classified cover under a policy. */
+export declare function coverDeliveryDecision(policy: NovelCoverPolicy, type: NovelCoverType): 'deliver' | 'skip';
+//# sourceMappingURL=NovelCoverPolicy.d.ts.map

package/dist/domain/media/NovelCoverPolicy.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NOVEL_COVER_POLICY = exports.PIXIV_GENERATED_COVER_HEIGHT = exports.PIXIV_GENERATED_COVER_WIDTH = void 0;
+exports.classifyNovelCover = classifyNovelCover;
+exports.coverDeliveryDecision = coverDeliveryDecision;
+/**
+ * Novel cover content policy (§media-asset-pipeline / §novel-cover).
+ *
+ * Pixiv exposes a novel cover as a single URL and gives NO field that says what
+ * the image actually IS. Two very different things arrive through that one
+ * field:
+ *
+ *   custom          the author's own uploaded artwork — real content, must ship
+ *   pixiv_generated Pixiv's built-in design cover, rendered per novel on a fixed
+ *                   640x900 canvas with the title typeset on it — zero content
+ *                   value, must never ship as Telegram media
+ *
+ * The URL cannot separate them (both live under `novel-cover-master/img/...`
+ * behind a unique hash, and the old `novel-cover-master-default` placeholder no
+ * longer occurs), so the classification is made from the fetched bytes' header.
+ * A third outcome exists on purpose:
+ *
+ *   unknown         the payload could not be classified (unrecognized header,
+ *                   format Pixiv does not normally serve)
+ *
+ * `unknown` is a POLICY decision, not an accident: sending it can leak a design
+ * cover into a public channel (the exact bug this pipeline fixes), while
+ * dropping it costs one illustration on the card. The production-safe default is
+ * therefore to skip it and log `coverType=unknown` loudly, so a future Pixiv
+ * cover-format change surfaces as a visible log line instead of silently
+ * shipping generated covers again.
+ *
+ * A FAILED probe (network / auth / rate limit) is deliberately NOT `unknown`:
+ * it is `probe_failed` and always keeps the cover, because a transient fetch
+ * error must never cost a real one.
+ */
+const imageDimensions_1 = require("../../utils/imageDimensions");
+/**
+ * The canvas Pixiv renders its built-in novel cover designs on. Every design
+ * observed in production (floral, seasonal sweets, treasure map, genre label,
+ * city night) is delivered at exactly this size, while author covers keep their
+ * own dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ */
+exports.PIXIV_GENERATED_COVER_WIDTH = 640;
+exports.PIXIV_GENERATED_COVER_HEIGHT = 900;
+/** Production-safe default: an unclassifiable cover is never shipped. */
+exports.DEFAULT_NOVEL_COVER_POLICY = { unknownCover: 'skip' };
+/**
+ * Classify fetched cover bytes. Returns `unknown` when the image header cannot
+ * be read (no decoder in this project, so only the header is inspected).
+ */
+function classifyNovelCover(cover) {
+    const dimensions = (0, imageDimensions_1.readImageDimensions)(cover);
+    if (!dimensions)
+        return 'unknown';
+    if (dimensions.width === exports.PIXIV_GENERATED_COVER_WIDTH &&
+        dimensions.height === exports.PIXIV_GENERATED_COVER_HEIGHT) {
+        return 'pixiv_generated';
+    }
+    return 'custom';
+}
+/** The delivery decision for one classified cover under a policy. */
+function coverDeliveryDecision(policy, type) {
+    if (type === 'pixiv_generated')
+        return 'skip';
+    if (type === 'unknown')
+        return policy.unknownCover === 'keep' ? 'deliver' : 'skip';
+    return 'deliver';
+}
+//# sourceMappingURL=NovelCoverPolicy.js.map

package/dist/download/DownloadManager.js

@@ -6,6 +6,7 @@ const RankingService_1 = require("./RankingService");
 const IllustrationDownloader_1 = require("./IllustrationDownloader");
 const NovelDownloader_1 = require("./NovelDownloader");
 const MaterializationPolicy_1 = require("../domain/media/MaterializationPolicy");
+const NovelCoverPolicy_1 = require("../domain/media/NovelCoverPolicy");
 const ProgressReporter_1 = require("./report/ProgressReporter");
 const DownloadPlanner_1 = require("./plan/DownloadPlanner");
 const DownloadExecutor_1 = require("./exec/DownloadExecutor");
@@ -129,7 +130,10 @@ class DownloadManager {
         const materialization = config.download?.materializationPolicy
             ? { mode: config.download?.materializationPolicy }
             : MaterializationPolicy_1.DEFAULT_MATERIALIZATION_POLICY;
-        this.novelDownloader = new NovelDownloader_1.NovelDownloader(client, database, fileService, database, undefined, materialization);
+        const novelCoverPolicy = {
+            unknownCover: config.download?.novelCover?.unknown ?? NovelCoverPolicy_1.DEFAULT_NOVEL_COVER_POLICY.unknownCover,
+        };
+        this.novelDownloader = new NovelDownloader_1.NovelDownloader(client, database, fileService, database, undefined, materialization, novelCoverPolicy);
         this.planner = new DownloadPlanner_1.DownloadPlanner(database, {
             // `scope` is a single legacy target name, or the full fan-out array for a
             // multi-platform target (then only works confirmed on EVERY platform count).

package/dist/download/NovelDownloader.d.ts

@@ -6,6 +6,7 @@ import { PixivNovel } from '@redtidev/pixiv-client';
 import { DownloadedArtifact } from '../delivery/types';
 import { type MaterializationPolicy } from '../domain/media/MaterializationPolicy';
 import { type MediaMaterializer } from './materialization/MediaMaterializer';
+import { type NovelCoverPolicy } from '../domain/media/NovelCoverPolicy';
 import type { Database } from '../storage/Database';
 export declare class NovelDownloader {
     private readonly client;
@@ -14,7 +15,28 @@ export declare class NovelDownloader {
     private readonly metadataDb?;
     private readonly materializer;
     private readonly materializationPolicy;
-    constructor(client: IPixivClient, database: IDatabase, fileService: IFileService, metadataDb?: Database | undefined, materializer?: MediaMaterializer, materializationPolicy?: MaterializationPolicy);
+    private readonly novelCoverPolicy;
+    constructor(client: IPixivClient, database: IDatabase, fileService: IFileService, metadataDb?: Database | undefined, materializer?: MediaMaterializer, materializationPolicy?: MaterializationPolicy, novelCoverPolicy?: NovelCoverPolicy);
     download(novel: PixivNovel, tag: string, target: TargetConfig): Promise<DownloadedArtifact | undefined>;
+    /**
+     * Resolves the cover URL a novel should ship with (§novel-cover).
+     *
+     * Pixiv's "author set no cover" case is invisible in the API: the design it
+     * renders (title typeset on a template) is served from the same CDN path with
+     * a unique hash as a real cover, so the URL cannot decide. The candidate cover
+     * is therefore fetched once and classified from its header; Pixiv's design
+     * canvas is exactly 640x900.
+     *
+     * Policy (§media-asset-pipeline):
+     *  - custom          → deliver the cover
+     *  - pixiv_generated → never deliver (a design cover is not content and must
+     *                      not become Telegram media)
+     *  - unknown         → policy decision, default 'skip' (safe mode), so a future
+     *                      Pixiv cover-format change surfaces as a loud
+     *                      `coverType=unknown` log instead of leaking silently
+     * A FAILED probe (network / auth / rate limit) is a separate case and always
+     * keeps the cover: a transient fetch error must never cost a real one.
+     */
+    private resolveCoverUrl;
 }
 //# sourceMappingURL=NovelDownloader.d.ts.map

package/dist/download/NovelDownloader.js

@@ -43,6 +43,7 @@ const Artifact_1 = require("../domain/media/Artifact");
 const MediaMaterializer_1 = require("./materialization/MediaMaterializer");
 const novelMarkers_1 = require("./novelMarkers");
 const novelCover_1 = require("./novelCover");
+const NovelCoverPolicy_1 = require("../domain/media/NovelCoverPolicy");
 const zip_1 = require("../utils/zip");
 const LANGUAGE_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 class NovelDownloader {
@@ -52,13 +53,15 @@ class NovelDownloader {
     metadataDb;
     materializer;
     materializationPolicy;
-    constructor(client, database, fileService, metadataDb, materializer, materializationPolicy = MaterializationPolicy_1.DEFAULT_MATERIALIZATION_POLICY) {
+    novelCoverPolicy;
+    constructor(client, database, fileService, metadataDb, materializer, materializationPolicy = MaterializationPolicy_1.DEFAULT_MATERIALIZATION_POLICY, novelCoverPolicy = NovelCoverPolicy_1.DEFAULT_NOVEL_COVER_POLICY) {
         this.client = client;
         this.database = database;
         this.fileService = fileService;
         this.metadataDb = metadataDb;
         this.materializer = materializer ?? new MediaMaterializer_1.PixivMediaMaterializer(client, fileService);
         this.materializationPolicy = materializationPolicy;
+        this.novelCoverPolicy = novelCoverPolicy;
     }
     async download(novel, tag, target) {
         // Metadata cache: language filtering otherwise pulls FULL text per candidate
@@ -226,10 +229,11 @@ class NovelDownloader {
             }
         }
         // Novel cover (§novel-cover): normalized to null for Pixiv's default
-        // placeholder, carried as a dedicated `novelcover` MediaAsset so TelePost
-        // can build `cover root + TXT reply` without positional guessing. The
-        // cover is never materialized locally — Telegram fetches it (via proxy).
-        const coverUrl = (0, novelCover_1.normalizeNovelCoverUrl)(typeof textResponse === 'string' ? undefined : textResponse.coverUrl);
+        // placeholder AND for Pixiv's generated design covers, carried as a
+        // dedicated `novelcover` MediaAsset so TelePost can build
+        // `cover root + TXT reply` without positional guessing. The cover is never
+        // materialized locally — Telegram fetches it (via proxy).
+        const coverUrl = await this.resolveCoverUrl(detail.id, typeof textResponse === 'string' ? undefined : textResponse.coverUrl);
         const coverAsset = coverUrl ? (0, novelCover_1.novelCoverAsset)(String(detail.id), coverUrl) : undefined;
         const downloadByAssetKey = new Map(assets.filter((a) => a.status === 'downloaded' && a.localPath)
             .map((a) => [`${a.kind}:${a.sourceId}`, a]));
@@ -398,6 +402,66 @@ class NovelDownloader {
             language: detectedLang ? `${detectedLang.name} (${detectedLang.code})` : undefined,
         };
     }
+    /**
+     * Resolves the cover URL a novel should ship with (§novel-cover).
+     *
+     * Pixiv's "author set no cover" case is invisible in the API: the design it
+     * renders (title typeset on a template) is served from the same CDN path with
+     * a unique hash as a real cover, so the URL cannot decide. The candidate cover
+     * is therefore fetched once and classified from its header; Pixiv's design
+     * canvas is exactly 640x900.
+     *
+     * Policy (§media-asset-pipeline):
+     *  - custom          → deliver the cover
+     *  - pixiv_generated → never deliver (a design cover is not content and must
+     *                      not become Telegram media)
+     *  - unknown         → policy decision, default 'skip' (safe mode), so a future
+     *                      Pixiv cover-format change surfaces as a loud
+     *                      `coverType=unknown` log instead of leaking silently
+     * A FAILED probe (network / auth / rate limit) is a separate case and always
+     * keeps the cover: a transient fetch error must never cost a real one.
+     */
+    async resolveCoverUrl(novelId, coverUrl) {
+        const normalized = (0, novelCover_1.normalizeNovelCoverUrl)(coverUrl);
+        if (!normalized)
+            return null;
+        let cover;
+        try {
+            cover = await this.client.downloadImage(normalized);
+        }
+        catch (error) {
+            logger_1.logger.warn(`Novel ${novelId} cover probe failed; keeping the cover (coverType=probe_failed)`, {
+                novelId,
+                coverUrl: normalized,
+                coverType: 'probe_failed',
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            return normalized;
+        }
+        const coverType = (0, NovelCoverPolicy_1.classifyNovelCover)(cover);
+        const decision = (0, NovelCoverPolicy_1.coverDeliveryDecision)(this.novelCoverPolicy, coverType);
+        const canvas = `${NovelCoverPolicy_1.PIXIV_GENERATED_COVER_WIDTH}x${NovelCoverPolicy_1.PIXIV_GENERATED_COVER_HEIGHT}`;
+        if (decision === 'skip') {
+            if (coverType === 'pixiv_generated') {
+                logger_1.logger.info(`Novel ${novelId} cover is a Pixiv generated design (${canvas}); delivering without a cover (coverType=${coverType})`, { novelId, coverUrl: normalized, coverType, canvas });
+            }
+            else {
+                logger_1.logger.warn(`Novel ${novelId} cover could not be classified; skipping it per novelCover.unknown=skip (coverType=${coverType})`, { novelId, coverUrl: normalized, coverType, policy: this.novelCoverPolicy.unknownCover });
+            }
+            return null;
+        }
+        if (coverType === 'unknown') {
+            logger_1.logger.warn(`Novel ${novelId} cover could not be classified; keeping it per novelCover.unknown=keep (coverType=${coverType})`, { novelId, coverUrl: normalized, coverType, policy: this.novelCoverPolicy.unknownCover });
+        }
+        else {
+            logger_1.logger.debug(`Novel ${novelId} cover classified (coverType=${coverType})`, {
+                novelId,
+                coverUrl: normalized,
+                coverType,
+            });
+        }
+        return normalized;
+    }
 }
 exports.NovelDownloader = NovelDownloader;
 function buildMediaAssetById(mediaAsset, artifactIdValue) {

package/dist/download/novelCover.d.ts

@@ -2,12 +2,23 @@
  * Novel cover normalization (§novel-cover).
  *
  * Pixiv exposes the novel cover as `coverUrl` on the webview v2 text response.
- * Novels WITHOUT a custom cover return the stock "novel-cover-master-default"
- * placeholder — that is NOT a real cover and must never ship as Telegram
- * media. The normalized model is therefore `string | null`:
+ * Novels WITHOUT a custom cover used to return the stock
+ * "novel-cover-master-default" placeholder; today Pixiv instead RENDERS a
+ * per-novel design (floral / seasonal / genre template with the novel title
+ * typeset) and serves it from `novel-cover-master/img/...` with a unique hash,
+ * so it is URL-indistinguishable from an author cover. Those design covers are
+ * NOT real covers and must never ship as Telegram media, and no API field
+ * (app-api `novel/detail`, webview v2) marks them: the one reliable
+ * discriminator is the canvas Pixiv renders them on, always exactly 640x900
+ * (`PIXIV_DESIGN_COVER_*` below). The normalized model is therefore
+ * `string | null`:
  *
- *   real cover       → the Pixiv CDN URL (original size when derivable)
- *   default / absent → null
+ *   real cover             → the Pixiv CDN URL (original size when derivable)
+ *   default / design / absent → null
+ *
+ * Callers cannot tell a design cover from the URL alone, so the fetch-and-check
+ * step (`isPixivDesignCoverImage`) lives in the downloader; this module stays a
+ * pure URL/bytes helper.
  *
  * The cover rides the canonical MediaAsset contract with a dedicated
  * `novelcover` pixivKind, so consumers (TelePost) can distinguish it from
@@ -15,6 +26,19 @@
  * positional guessing.
  */
 import { MediaAsset } from '../domain/media/MediaAsset';
+/**
+ * Historical names for the generated-cover canvas; the classification and the
+ * policy live in `src/domain/media/NovelCoverPolicy.ts` (§media-asset-pipeline).
+ */
+export declare const PIXIV_DESIGN_COVER_WIDTH = 640;
+export declare const PIXIV_DESIGN_COVER_HEIGHT = 900;
+/**
+ * True when the fetched cover bytes are one of Pixiv's generated designs.
+ * Unknown formats / unreadable payloads return false — this predicate is the
+ * raw classification only; whether an unclassifiable cover is delivered is the
+ * caller's policy (`coverDeliveryDecision`, default: skipped).
+ */
+export declare function isPixivDesignCoverImage(cover: ArrayBuffer | Uint8Array | null | undefined): boolean;
 export declare function normalizeNovelCoverUrl(coverUrl?: string | null): string | null;
 export declare function novelCoverAsset(workId: string, coverUrl: string): MediaAsset;
 //# sourceMappingURL=novelCover.d.ts.map

package/dist/download/novelCover.js

@@ -1,17 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIXIV_DESIGN_COVER_HEIGHT = exports.PIXIV_DESIGN_COVER_WIDTH = void 0;
+exports.isPixivDesignCoverImage = isPixivDesignCoverImage;
 exports.normalizeNovelCoverUrl = normalizeNovelCoverUrl;
 exports.novelCoverAsset = novelCoverAsset;
 /**
  * Novel cover normalization (§novel-cover).
  *
  * Pixiv exposes the novel cover as `coverUrl` on the webview v2 text response.
- * Novels WITHOUT a custom cover return the stock "novel-cover-master-default"
- * placeholder — that is NOT a real cover and must never ship as Telegram
- * media. The normalized model is therefore `string | null`:
+ * Novels WITHOUT a custom cover used to return the stock
+ * "novel-cover-master-default" placeholder; today Pixiv instead RENDERS a
+ * per-novel design (floral / seasonal / genre template with the novel title
+ * typeset) and serves it from `novel-cover-master/img/...` with a unique hash,
+ * so it is URL-indistinguishable from an author cover. Those design covers are
+ * NOT real covers and must never ship as Telegram media, and no API field
+ * (app-api `novel/detail`, webview v2) marks them: the one reliable
+ * discriminator is the canvas Pixiv renders them on, always exactly 640x900
+ * (`PIXIV_DESIGN_COVER_*` below). The normalized model is therefore
+ * `string | null`:
  *
- *   real cover       → the Pixiv CDN URL (original size when derivable)
- *   default / absent → null
+ *   real cover             → the Pixiv CDN URL (original size when derivable)
+ *   default / design / absent → null
+ *
+ * Callers cannot tell a design cover from the URL alone, so the fetch-and-check
+ * step (`isPixivDesignCoverImage`) lives in the downloader; this module stays a
+ * pure URL/bytes helper.
  *
  * The cover rides the canonical MediaAsset contract with a dedicated
  * `novelcover` pixivKind, so consumers (TelePost) can distinguish it from
@@ -19,9 +32,25 @@ exports.novelCoverAsset = novelCoverAsset;
  * positional guessing.
  */
 const MediaAsset_1 = require("../domain/media/MediaAsset");
+const NovelCoverPolicy_1 = require("../domain/media/NovelCoverPolicy");
 const DEFAULT_COVER_PATTERN = /novel-cover-(master-)?default/i;
 /** Strip the `/c/<spec>/` resizer segment to recover the original-size URL. */
 const RESIZED_COVER_PATTERN = /\/c\/[^/]+\/(novel-cover-master\/)/;
+/**
+ * Historical names for the generated-cover canvas; the classification and the
+ * policy live in `src/domain/media/NovelCoverPolicy.ts` (§media-asset-pipeline).
+ */
+exports.PIXIV_DESIGN_COVER_WIDTH = NovelCoverPolicy_1.PIXIV_GENERATED_COVER_WIDTH;
+exports.PIXIV_DESIGN_COVER_HEIGHT = NovelCoverPolicy_1.PIXIV_GENERATED_COVER_HEIGHT;
+/**
+ * True when the fetched cover bytes are one of Pixiv's generated designs.
+ * Unknown formats / unreadable payloads return false — this predicate is the
+ * raw classification only; whether an unclassifiable cover is delivered is the
+ * caller's policy (`coverDeliveryDecision`, default: skipped).
+ */
+function isPixivDesignCoverImage(cover) {
+    return (0, NovelCoverPolicy_1.classifyNovelCover)(cover) === 'pixiv_generated';
+}
 function normalizeNovelCoverUrl(coverUrl) {
     const url = typeof coverUrl === 'string' ? coverUrl.trim() : '';
     if (!url)