pixivflow 3.0.3 → 3.2.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). */
@@ -28,6 +47,26 @@ export interface TopicDiscoveryConfig {
      * - `'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 {
@@ -876,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

@@ -194,6 +194,45 @@ function validateConfig(config, location, databasePath) {
                 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) {
@@ -660,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,8 @@ 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).
@@ -22,9 +24,18 @@ export declare class NovelDownloader {
      * 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 its header inspected; Pixiv's design canvas is
-     * exactly 640x900. Anything that cannot be classified keeps the cover — a
-     * failed probe must never cost a real 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;
 }

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
@@ -405,30 +408,59 @@ class NovelDownloader {
      * 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 its header inspected; Pixiv's design canvas is
-     * exactly 640x900. Anything that cannot be classified keeps the cover — a
-     * failed probe must never cost a real 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 {
-            const cover = await this.client.downloadImage(normalized);
-            if ((0, novelCover_1.isPixivDesignCoverImage)(cover)) {
-                logger_1.logger.info(`Novel ${novelId} cover is a Pixiv design cover (${novelCover_1.PIXIV_DESIGN_COVER_WIDTH}x${novelCover_1.PIXIV_DESIGN_COVER_HEIGHT}); delivering without a cover`, { novelId, coverUrl: normalized, designCover: true });
-                return null;
-            }
-            return normalized;
+            cover = await this.client.downloadImage(normalized);
         }
         catch (error) {
-            logger_1.logger.warn(`Novel ${novelId} cover probe failed; keeping the cover`, {
+            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;

package/dist/download/novelCover.d.ts

@@ -27,17 +27,16 @@
  */
 import { MediaAsset } from '../domain/media/MediaAsset';
 /**
- * The canvas Pixiv renders its built-in novel cover designs on. Every design
- * observed in production (floral, seasonal sweets, treasure map, genre label)
- * is delivered at exactly this size, while author covers keep their own
- * dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ * 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 so callers fail open and
- * keep the cover rather than dropping a real one.
+ * 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;

package/dist/download/novelCover.js

@@ -32,27 +32,24 @@ exports.novelCoverAsset = novelCoverAsset;
  * positional guessing.
  */
 const MediaAsset_1 = require("../domain/media/MediaAsset");
-const imageDimensions_1 = require("../utils/imageDimensions");
+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\/)/;
 /**
- * The canvas Pixiv renders its built-in novel cover designs on. Every design
- * observed in production (floral, seasonal sweets, treasure map, genre label)
- * is delivered at exactly this size, while author covers keep their own
- * dimensions (512x512, 768x768, 800x1200, 822x1200, 826x1169, 1024x1024 …).
+ * 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 = 640;
-exports.PIXIV_DESIGN_COVER_HEIGHT = 900;
+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 so callers fail open and
- * keep the cover rather than dropping a real one.
+ * 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) {
-    const dimensions = (0, imageDimensions_1.readImageDimensions)(cover);
-    return (dimensions?.width === exports.PIXIV_DESIGN_COVER_WIDTH &&
-        dimensions?.height === exports.PIXIV_DESIGN_COVER_HEIGHT);
+    return (0, NovelCoverPolicy_1.classifyNovelCover)(cover) === 'pixiv_generated';
 }
 function normalizeNovelCoverUrl(coverUrl) {
     const url = typeof coverUrl === 'string' ? coverUrl.trim() : '';

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "private": true
 }

package/dist/topic/TopicPipeline.d.ts

@@ -1,6 +1,6 @@
 import type { TargetConfig } from '../config';
 import type { TopicResolver } from './TopicResolver';
-import type { TopicCandidate, TopicClient, TopicCollectOptions, TopicContentType, TopicDiscoveryOptions, WorkLike } from './types';
+import type { RelatedTagMode, ResolvedTag, TopicCandidate, TopicClient, TopicCollectOptions, TopicContentType, TopicDiscoveryOptions, TopicRelationsOptions, WorkLike } from './types';
 export interface TopicSelection {
     candidates: TopicCandidate[];
     selected: TopicCandidate[];
@@ -18,6 +18,26 @@ export interface TopicSelection {
     /** Works seen more than once across the topic tag space (recorded, dropped). */
     duplicateRemovedCount: number;
 }
+/**
+ * The tag the operator asked for, even when `tagRelations` filters it out.
+ *
+ * `deny` may drop the seed, but a space filtered down to nothing must still be
+ * usable: the pipeline then falls back to the seed tag alone, exactly like the
+ * resolver's `seedOnly()` degradation. `weight` defaults to the tag's `score`
+ * for spaces persisted before provenance existed.
+ */
+export declare function seedFallbackTag(seedTag: ResolvedTag): ResolvedTag;
+/**
+ * Applies `topicDiscovery.tagRelations` to a resolved space (§tag-provenance).
+ *
+ * Deny beats allow, and deny is the only thing that can drop the seed tag. A
+ * tag whose provenance is unknown (a space persisted before `source` existed, or
+ * a hand-written space) is treated as `cooccurrence` so that `allowSources` can
+ * still narrow it while the default (all sources) keeps walking everything.
+ */
+export declare function selectWalkedTags(tags: readonly ResolvedTag[], seedKey: string, relations?: TopicRelationsOptions): ResolvedTag[];
+/** Which of the walked tags a `relatedTags` mode will actually search today. */
+export declare function recallChannels(walked: readonly ResolvedTag[], seedKey: string, relatedMode: RelatedTagMode): ResolvedTag[];
 /**
  * Resolves a topic to a tag space, collects that day's works across the tags,
  * filters by lightweight metadata relevance and ranks by local popularity, then
@@ -63,6 +83,16 @@ export declare class TopicPipeline {
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
      * No text model — case/symbol-insensitive substring matching only.
+     *
+     * `matchTranslatedNames` (default false) additionally counts a work's
+     * `translated_name` as a hit for the resolved tag it translates to, so a
+     * topic written in one language can still match works tagged in another. The
+     * translated name is matched against the resolved space — never added to
+     * `candidate.tags` — so the work is not reported as carrying a tag it lacks.
+     *
+     * A resolved tag counts at most ONCE per work, whether it matched through the
+     * tag name or through its translation (and a work that repeats a tag, as Pixiv
+     * payloads do for a tag plus its translation, does not double its weight).
      */
     private metadataScore;
     /**
@@ -72,12 +102,13 @@ export declare class TopicPipeline {
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
      *
-     * `seedKey` adds a single tier in front of that popularity order and is only
-     * passed by the seed-first recall modes (§topic-recall): when related tags
-     * were reached as a fallback, a work that actually carries the topic tag must
-     * outrank a related-only work, and popularity decides within each tier. The
-     * default mode passes no `seedKey`, so the documented popularity-only ranking
-     * is unchanged.
+     * `seedKey` adds a single tier in front of that popularity order and is
+     * passed by the seed-first recall modes (§topic-recall) and by
+     * `topicDiscovery.seedTier: 'on'` (§tag-provenance): a work that actually
+     * carries the topic tag outranks a related-only work, however popular the
+     * latter is, and popularity decides within each tier. With `seedTier: 'off'`
+     * and the default `relatedTags: 'always'` no `seedKey` is passed, so the
+     * documented popularity-only ranking is unchanged.
      */
     private popCompare;
     private rankCompare;