pixivflow 3.0.3 → 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). */
@@ -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.1.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;

package/dist/topic/TopicPipeline.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicPipeline = void 0;
+exports.seedFallbackTag = seedFallbackTag;
+exports.selectWalkedTags = selectWalkedTags;
+exports.recallChannels = recallChannels;
 const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
 const pixiv_utils_1 = require("../utils/pixiv-utils");
@@ -14,6 +17,105 @@ const STOP_TAGS = new Set([
     '1000users入り', '5000users入り', '10000users入り', '500users入り', '100users入り',
     'pixiv', 'commission', 'skeb', '依頼絵', '仕事絵',
 ]);
+/** Normalization shared by the tag-relation filter and the pipeline itself. */
+function normalizeKey(value) {
+    return value.trim().normalize('NFKC').toLocaleLowerCase();
+}
+/**
+ * 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.
+ */
+function seedFallbackTag(seedTag) {
+    if (seedTag.source === 'seed' && seedTag.weight !== undefined)
+        return seedTag;
+    return { ...seedTag, source: 'seed', weight: seedTag.weight ?? seedTag.score, seed: true };
+}
+/**
+ * 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.
+ */
+function selectWalkedTags(tags, seedKey, relations = {}) {
+    const seedTag = tags.find((tag) => normalizeKey(tag.name) === seedKey);
+    const allowed = tags.filter((tag) => normalizeKey(tag.name) !== seedKey);
+    const deny = (relations.deny ?? []).map(normalizeKey);
+    const deniedKeys = new Set(deny);
+    const seedDenied = seedTag !== undefined && deniedKeys.has(seedKey);
+    if (seedDenied)
+        deniedKeys.clear(); // the seed fallback ignores deny
+    const allow = (relations.allow ?? []).map(normalizeKey);
+    const allowKeys = new Set(allow);
+    const open = allowKeys.size === 0;
+    const sources = relations.allowSources;
+    const sourceAllowed = (tag) => {
+        if (!sources || sources.length === 0)
+            return true;
+        const name = normalizeKey(tag.name);
+        if (allowKeys.has(name))
+            return true; // an explicit allow beats allowSources
+        const provenance = tag.source;
+        if (provenance === undefined)
+            return sources.includes('cooccurrence');
+        if (provenance === 'cooccurrence+autocomplete') {
+            return sources.includes('cooccurrence') || sources.includes('autocomplete');
+        }
+        return sources.includes(provenance);
+    };
+    const walked = allowed.filter((tag) => {
+        const name = normalizeKey(tag.name);
+        if (deniedKeys.has(name))
+            return false;
+        if (!open && !allowKeys.has(name))
+            return false;
+        return sourceAllowed(tag);
+    });
+    // No seed tag in the space at all: there is nothing to dominate, so fall back
+    // to walking the whole (filtered) space — the pre-provenance behaviour.
+    if (!seedTag)
+        return walked;
+    // A denied seed empties the space, exactly like the resolver's seedOnly():
+    // the operator still gets their own topic, and no related tag is walked.
+    if (seedDenied)
+        return [seedFallbackTag(seedTag)];
+    return [seedTag, ...walked];
+}
+/** Every spelling under which a set of resolved tags can be recognized. */
+function buildTagAliases(tags, matchTranslatedNames) {
+    const aliases = new Map();
+    for (const tag of tags) {
+        const primary = normalizeKey(tag.name);
+        const entry = { primary, weight: tag.weight ?? tag.score };
+        if (!aliases.has(primary))
+            aliases.set(primary, entry);
+        if (!matchTranslatedNames)
+            continue;
+        // The work-side `translated_name` for this tag is the same resolved tag: the
+        // space still exposes one tag, it is simply recognized under two keys.
+        const translated = tag.translatedName ? normalizeKey(tag.translatedName) : '';
+        if (translated && !aliases.has(translated))
+            aliases.set(translated, entry);
+    }
+    return aliases;
+}
+/** Which of the walked tags a `relatedTags` mode will actually search today. */
+function recallChannels(walked, seedKey, relatedMode) {
+    const seedTags = walked.filter((tag) => normalizeKey(tag.name) === seedKey);
+    // A space with no seed tag has nothing to protect: every remaining tag is the
+    // only channel there is, so the whole space is walked whatever the mode
+    // (pre-provenance fallback for a hand-written space).
+    if (seedTags.length === 0)
+        return [...walked];
+    if (relatedMode === 'never' || relatedMode === 'when_seed_insufficient')
+        return seedTags;
+    return [...seedTags, ...walked.filter((tag) => normalizeKey(tag.name) !== seedKey)];
+}
 /**
  * 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
@@ -42,7 +144,6 @@ class TopicPipeline {
     async selectWorks(target, contentType, day, limit, discovery, collect) {
         const topic = (target.topic ?? '').trim();
         const { space } = await this.resolver.resolve(topic, contentType, discovery);
-        const tagScores = new Map(space.tags.map((t) => [this.key(t.name), t.score]));
         const maxPerTag = this.bound(collect.maxPerTag, COLLECT_DEFAULTS.maxPerTag, 5, 100);
         const maxCandidates = this.bound(collect.maxCandidates, COLLECT_DEFAULTS.maxCandidates, 20, 500);
         const minMetadataScore = collect.minMetadataScore ?? COLLECT_DEFAULTS.minMetadataScore;
@@ -55,11 +156,22 @@ class TopicPipeline {
         let rawCount = 0;
         let aiExcludedCount = 0;
         let duplicateRemovedCount = 0;
-        const tagNames = space.tags.map((t) => t.name);
         const seedKey = this.key(topic);
+        // §tag-provenance: apply tagRelations where the walked list is built, so the
+        // filter governs seedTags/relatedTags BEFORE any search is issued. The seed
+        // tag survives allow/allowSources; a deny entry that empties the space falls
+        // back to the seed tag alone, exactly like the resolver's seedOnly().
+        const matchTranslatedNames = discovery.matchTranslatedNames === true;
+        const walked = selectWalkedTags(space.tags, seedKey, discovery.tagRelations);
+        const tagNames = walked.map((t) => t.name);
         const seedTags = tagNames.filter((name) => this.key(name) === seedKey);
         const relatedTags = tagNames.filter((name) => this.key(name) !== seedKey);
+        // Ranking reads the documented semantic weight, falling back to `score` for
+        // spaces persisted before provenance existed. The two are always equal.
+        const tagScores = buildTagAliases(walked, matchTranslatedNames);
         const searchedTags = [];
+        // A hard seed tier: 'on' always, and the seed-first modes keep their layer.
+        const hardSeedTier = discovery.seedTier === 'on' || relatedMode !== 'always';
         const collectTag = async (tag) => {
             // Cancellation is checked between tags, so a cancelled run stops issuing
             // new searches even when the aborted request itself had already returned.
@@ -100,11 +212,11 @@ class TopicPipeline {
         if (seedTags.length === 0 || relatedMode === 'always') {
             // No seed tag in the space (hand-written space): keep walking everything
             // rather than returning nothing.
-            await runTags(seedTags.length === 0 ? tagNames : [...seedTags, ...relatedTags]);
+            await runTags(recallChannels(walked, seedKey, relatedMode).map((t) => t.name));
         }
         else {
             await runTags(seedTags);
-            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType).length;
+            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames).length;
             if (relatedMode === 'never') {
                 logger_1.logger.info('[TopicRecall] mode=never tag=' + topic + ' day=' + day + ' accepted=' + seedAccepted);
             }
@@ -118,19 +230,19 @@ class TopicPipeline {
         }
         const dedupedCount = byId.size;
         logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount + ' searchedTags=' + searchedTags.length);
-        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType);
-        const chosen = this.topByPopularity(accepted, limit, relatedMode === 'always' ? undefined : seedKey);
+        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames);
+        const chosen = this.topByPopularity(accepted, limit, hardSeedTier ? seedKey : undefined);
         const selected = chosen.map((e) => e.candidate);
         logger_1.logger.info('[MetadataTopicFilter] accepted=' + accepted.length);
         if (selected[0]) {
-            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + ' title=' + selected[0].title);
+            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + (hardSeedTier ? ' seedTier=on' : '') + ' title=' + selected[0].title);
         }
         return {
             works: chosen.map((e) => e.work),
             selection: {
                 candidates: [...byId.values()].map((e) => e.candidate),
                 selected,
-                resolvedTagCount: space.tags.length,
+                resolvedTagCount: walked.length,
                 searchedTags,
                 rawCount,
                 dedupedCount,
@@ -163,12 +275,16 @@ class TopicPipeline {
     }
     toCandidate(work, type) {
         const popularity = (0, pixiv_utils_1.calculatePopularityScore)(work);
+        const translatedTags = (work.tags ?? [])
+            .map((t) => t.translated_name)
+            .filter((name) => Boolean(name));
         return {
             id: work.id,
             type,
             title: work.title ?? '',
             caption: work.caption ?? '',
             tags: (work.tags ?? []).map((t) => t.name).filter(Boolean),
+            ...(translatedTags.length > 0 ? { translatedTags } : {}),
             bookmarks: Number(work.total_bookmarks ?? work.bookmark_count ?? 0) || 0,
             views: Number(work.total_view ?? work.view_count ?? 0) || 0,
             popularity,
@@ -184,16 +300,23 @@ class TopicPipeline {
      * the seed pass can be evaluated before deciding whether the related channel
      * is needed at all (§topic-recall).
      */
-    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType) {
+    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames) {
         const accepted = [];
+        const hitsSeed = (candidate) => {
+            if (candidate.tags.some((t) => this.key(t) === seedKey))
+                return true;
+            if (!matchTranslatedNames)
+                return false;
+            return (candidate.translatedTags ?? []).some((t) => this.key(t) === seedKey);
+        };
         for (const entry of byId.values()) {
-            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores);
+            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores, matchTranslatedNames);
             if (entry.candidate.metadataScore >= minMetadataScore)
                 accepted.push(entry);
         }
         if (accepted.length === 0 && byId.size > 0) {
             const fallback = [...byId.values()]
-                .filter((e) => e.candidate.tags.some((t) => this.key(t) === seedKey))
+                .filter((e) => hitsSeed(e.candidate))
                 .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
             accepted.push(...fallback.slice(0, Math.max(limit, 1)));
             logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
@@ -204,25 +327,49 @@ 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).
      */
-    metadataScore(candidate, seedKey, tagScores) {
+    metadataScore(candidate, seedKey, tagScores, matchTranslatedNames) {
         let seedHit = false;
         let relatedSum = 0;
         let relatedHits = 0;
-        for (const tag of candidate.tags) {
-            const k = this.key(tag);
-            if (STOP_TAGS.has(k))
-                continue;
-            if (k === seedKey) {
+        let strongRelated = false;
+        // A resolved tag is matched through its own name, and — when the caller
+        // opted in — through the work-side translation of that tag. Either spelling
+        // maps back to the SAME resolved tag, so a work carrying both spellings
+        // counts once and never gets a double weight.
+        const countedTagKeys = new Set();
+        const consider = (candidateKey) => {
+            if (candidateKey === '' || STOP_TAGS.has(candidateKey))
+                return;
+            if (candidateKey === seedKey) {
                 seedHit = true;
-                continue;
-            }
-            const related = tagScores.get(k);
-            if (related !== undefined) {
-                relatedSum += Math.min(related, 0.6);
-                relatedHits += 1;
+                return;
             }
+            const aliases = tagScores.get(candidateKey);
+            if (!aliases || countedTagKeys.has(aliases.primary))
+                return;
+            countedTagKeys.add(aliases.primary);
+            relatedSum += Math.min(aliases.weight, 0.6);
+            relatedHits += 1;
+            if (aliases.weight >= 0.6)
+                strongRelated = true;
+        };
+        if (matchTranslatedNames) {
+            for (const tag of candidate.translatedTags ?? [])
+                consider(this.key(tag));
         }
+        for (const tag of candidate.tags)
+            consider(this.key(tag));
         const hayTitle = this.normalize(candidate.title);
         const hayCaption = this.normalize(candidate.caption);
         const titleSeed = !!seedKey && hayTitle.includes(seedKey);
@@ -239,7 +386,6 @@ class TopicPipeline {
         // deliberately does NOT clear the bar, so a hugely popular tangential work
         // cannot crowd out core topic works.
         let score = 0;
-        const strongRelated = [...tagScores.entries()].some(([k, w]) => w >= 0.6 && candidate.tags.some((t) => this.key(t) === k));
         if (titleSeed)
             score += 0.8;
         if (captionSeed)
@@ -256,12 +402,13 @@ 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.
      */
     popCompare(a, b) {
         return b.popularity - a.popularity;

package/dist/topic/TopicResolver.js

@@ -97,6 +97,9 @@ class TopicResolver {
             name: seed,
             translatedName: suggested.find((t) => this.scorer.key(t.name) === this.scorer.key(seed))?.translated_name,
             score: 1,
+            weight: 1,
+            // The tag the operator asked for: the strongest provenance, never a hint.
+            source: 'seed',
             occurrences: topicWorks.length,
             coverage: 1,
             specificity: 1,
@@ -168,7 +171,7 @@ class TopicResolver {
             expiresAt: new Date(now + cacheDays * 24 * 60 * 60_000).toISOString(),
             sampleSize: 0,
             sampledWorks: 0,
-            tags: [{ name: seed, score: 1, occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
+            tags: [{ name: seed, score: 1, weight: 1, source: 'seed', occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
         };
     }
     ageDays(space) {

package/dist/topic/TopicTagScorer.js

@@ -99,10 +99,17 @@ class TopicTagScorer {
             const suggestionWeight = stat.suggested ? 1.1 : 1.0;
             const genericPenalty = GENERIC_TAG_PENALTY.has(k) ? 0.4 : 1.0;
             const raw = recall * specificity * suggestionWeight * genericPenalty;
+            const score = Number(raw.toFixed(4));
             resolved.push({
                 name: stat.name,
                 translatedName: stat.translatedName,
-                score: Number(raw.toFixed(4)),
+                score,
+                // `weight` is the same semantic number; ranking and diagnostics read it
+                // while `score` stays for backward compatibility (§tag-provenance).
+                weight: score,
+                // Both channels may agree on a tag; the combined provenance records
+                // that, which is strictly more informative than either alone.
+                source: stat.suggested ? 'cooccurrence+autocomplete' : 'cooccurrence',
                 occurrences: stat.topicDocs,
                 coverage: Number(coverage.toFixed(4)),
                 specificity: Number(specificity.toFixed(4)),
@@ -127,6 +134,10 @@ class TopicTagScorer {
                 name: name,
                 translatedName: sug.translated_name?.trim() || undefined,
                 score: AUTOCOMPLETE_ONLY_SCORE,
+                weight: AUTOCOMPLETE_ONLY_SCORE,
+                // Pixiv autocomplete is the only evidence for this tag: it never
+                // co-occurred in the bounded sample.
+                source: 'autocomplete',
                 occurrences: 0,
                 coverage: 0,
                 specificity: 1.0, // Pixiv-endorsed related; treated as specific but unobserved

package/dist/topic/types.d.ts

@@ -4,12 +4,34 @@
  * local models are used anywhere in this module.
  */
 export type TopicContentType = 'illustration' | 'novel';
+/**
+ * Where a resolved tag came from. Provenance is what lets a caller treat a weak
+ * expansion differently from the topic it was asked for (§tag-provenance):
+ *
+ * - `'seed'`: the tag the operator asked for. Always the strongest key.
+ * - `'cooccurrence'`: sampled together with the seed, but Pixiv autocomplete
+ *   does not relate it to the seed. Co-occurrence evidence only.
+ * - `'autocomplete'`: Pixiv autocomplete relates it to the seed, but it never
+ *   appeared in the sample. No co-occurrence evidence.
+ * - `'cooccurrence+autocomplete'`: both channels agree — the strongest related
+ *   provenance available.
+ */
+export type TagSource = 'seed' | 'cooccurrence' | 'autocomplete' | 'cooccurrence+autocomplete';
 /** A single related tag with a 0..1 relatedness score and provenance. */
 export interface ResolvedTag {
     name: string;
     translatedName?: string;
     /** Combined relatedness score (co-occurrence * specificity * suggestion). */
     score: number;
+    /**
+     * Semantic weight used for ranking, filtering and diagnostics. Always the
+     * same number as `score`; kept as a separate, documented field so ranking can
+     * be explained (and, later, adjusted) without redefining `score`.
+     * Optional: spaces persisted before provenance existed have neither field.
+     */
+    weight?: number;
+    /** Provenance of the tag. Optional for the same reason as `weight`. */
+    source?: TagSource;
     /** How many sampled works (of the seed search) carried this tag. */
     occurrences: number;
     /** Coverage of the sampled seed works (occurrences / sample size). */
@@ -57,6 +79,26 @@ export interface TopicDiscoveryOptions {
      * `'never'` searches the seed tag alone.
      */
     relatedTags?: RelatedTagMode;
+    /**
+     * Which resolved tags may become recall channels (§tag-provenance). Deny wins
+     * over allow; the seed tag is never dropped by `allow`/`allowSources`.
+     */
+    tagRelations?: TopicRelationsOptions;
+    /** Make the seed tag a hard ranking tier (default `'off'`). */
+    seedTier?: 'off' | 'on';
+    /** Count a work's translated tag names as tag hits (default false). */
+    matchTranslatedNames?: boolean;
+}
+/**
+ * Runtime shape of `TopicDiscoveryConfig.tagRelations`, declared here so the
+ * topic module does not depend on the config layer (the topic pipeline is also
+ * driven by hand-written targets in tests and by callers that never load a
+ * config file).
+ */
+export interface TopicRelationsOptions {
+    allowSources?: TagSource[];
+    allow?: string[];
+    deny?: string[];
 }
 export interface TopicCollectOptions {
     maxPerTag?: number;
@@ -76,6 +118,12 @@ export interface TopicCandidate {
     popularity: number;
     /** Metadata topic-relevance score computed by the filter stage. */
     metadataScore: number;
+    /**
+     * Translated tag names carried by the work, kept beside `tags` so
+     * `matchTranslatedNames` can compare them WITHOUT claiming the work itself
+     * carries a tag it does not (§tag-provenance). Default-off.
+     */
+    translatedTags?: string[];
     /** Pixiv AI classification copied from illustration search metadata. */
     aiType?: number;
 }

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '3.0.3', commit: 'b01a93d49e63' };
+exports.BUILD = { version: '3.1.0', commit: '583a74c98ef7' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixivflow",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "🎨 Pixiv 下载、筛选与自动收集工具 - 批量下载插画和小说、按标签/热度/日期筛选、定时任务与可靠 HTTP 交付 | Pixiv downloader and automation toolkit with filtering, scheduling and reliable HTTP delivery",
   "repository": {
     "type": "git",