pixivflow 2.19.4 → 2.20.0

package/dist/download/pipeline/DownloadPipeline.js

@@ -4,6 +4,7 @@ exports.DownloadPipeline = void 0;
 const logger_1 = require("../../logger");
 const target_label_1 = require("../../utils/target-label");
 const errors_1 = require("../../utils/errors");
+const TargetOutcome_1 = require("../../scheduler/TargetOutcome");
 class DownloadPipeline {
     config;
     planner;
@@ -33,119 +34,135 @@ class DownloadPipeline {
             skippedCount: 0,
             skipDetails: [],
         };
-        const concurrency = plan.mode === 'sequential' && plan.queue.length > targetLimit
-            ? 1
-            : itemType === 'novel' && target.languageFilter
-                ? 1
-                : (this.config.download?.concurrency || 3);
-        if (plan.mode === 'random') {
-            await this.executeRandomMode(plan, targetLimit, planAvailableCount, itemType, tagForLog, downloadFn, retryAttempts, concurrency, state);
-        }
-        else {
-            await this.executeSequentialMode(plan, targetLimit, itemType, tagForLog, downloadFn, retryAttempts, concurrency, state);
-        }
-        this.updateProgress(state.downloaded, targetLimit, `完成下载: ${state.downloaded} 个 ${itemType === 'illustration' ? '插画' : '小说'}`);
-        return {
-            downloaded: state.downloaded,
-            skipped: state.skippedCount,
-            alreadyDownloaded: alreadyDownloadedCount,
-            filteredOut: filteredOutCount,
-            skipDetails: state.skipDetails,
+        /**
+         * Bounded candidate scan bookkeeping. `bound` is the plan's window (the
+         * planner already clamped it to the configured limit) AND the item list
+         * length, so the scan is structurally unable to exceed it: a page full of
+         * duplicates terminates after at most `bound` attempts instead of looping.
+         */
+        const scan = {
+            bound: plan.scanBound ?? plan.queue.length,
+            attempted: 0,
+            skipped: [...(plan.prefiltered ?? [])],
+            outages: [],
         };
-    }
-    async executeRandomMode(plan, targetLimit, planAvailableCount, itemType, tagForLog, downloadFn, retryAttempts, concurrency, state) {
-        const candidates = plan.queue;
-        if (planAvailableCount === 0) {
-            logger_1.logger.info('All search results have already been downloaded');
-            return;
-        }
-        if (candidates.length === 0) {
-            return;
+        /**
+         * Candidate INDEXES this run has attempted. Retries of the same candidate
+         * (the executor's backoff path) must not count as new candidates, and must
+         * not be blocked by the bound: that would silently convert a retried failure
+         * into a success.
+         */
+        const attemptedIndices = new Set();
+        if (scan.skipped.length > 0) {
+            logger_1.logger.info(`Candidate scan pre-filtered ${scan.skipped.length} candidate(s) before download ` +
+                `(${[...new Set(scan.skipped.map((s) => s.code))].join(', ')})`, { target: tagForLog });
         }
-        const selectionLimit = plan.random?.maxAttempts ?? candidates.length;
-        let attemptCounter = 0;
-        let completedForProgress = 0;
-        const totalPlanned = Math.min(candidates.length, targetLimit);
-        await this.executor.run({
-            items: candidates,
-            concurrency,
+        /** Record a candidate-level skip: the scan advances to the next candidate. */
+        const recordCandidateSkip = (skip) => {
+            scan.skipped.push(skip);
+            if (scan.skipped.length <= 5) {
+                logger_1.logger.info(`Candidate ${skip.workId} skipped (${skip.code}${skip.retryable ? ', transient' : ''}): ${skip.reason}`, { target: tagForLog });
+            }
+            if (state.skipDetails.length < 3 && !state.skipDetails.some((d) => d.id === skip.workId)) {
+                state.skipDetails.push({ id: skip.workId, error: skip.reason });
+            }
+        };
+        /**
+         * Classify a candidate FAILURE. A dead database / dead token / dead
+         * delivery provider / dead network is a JOB problem and is recorded as an
+         * outage, so the target can fail instead of reporting "no eligible
+         * candidate". Anything else is a candidate problem: skip, try the next.
+         */
+        const recordCandidateFailure = (error, workId) => {
+            const failure = (0, TargetOutcome_1.classifyCandidateFailure)(error, workId);
+            if (failure.scope === 'job') {
+                if (!scan.outages.includes(failure.outage)) {
+                    scan.outages.push(failure.outage);
+                }
+                logger_1.logger.error(`Job-level outage while scanning (${failure.outage}): ${failure.error}`, {
+                    target: tagForLog,
+                    candidate: workId,
+                });
+                return;
+            }
+            recordCandidateSkip(failure.skip);
+            state.skippedCount++;
+        };
+        const runOptions = {
+            concurrency: plan.mode === 'sequential' && plan.queue.length > targetLimit
+                ? 1
+                : itemType === 'novel' && target.languageFilter
+                    ? 1
+                    : this.config.download?.concurrency || 3,
             maxAttempts: retryAttempts,
             recovery: this.recovery,
             contextProvider: () => ({ itemType }),
-            task: async (item) => {
+            task: async (item, index) => {
                 if (state.downloaded >= targetLimit || this.isRunCancelled()) {
                     return;
                 }
-                const attempt = ++attemptCounter;
-                const remaining = Math.max(0, candidates.length - attempt + 1);
-                const typeLabel = itemType === 'illustration' ? 'Illustration' : 'Novel';
-                logger_1.logger.info(`Randomly selected ${typeLabel.toLowerCase()} ${item.id} from ${remaining} remaining result(s) (attempt ${attempt}/${selectionLimit})`);
-                await downloadFn(item, tagForLog);
-                state.downloaded++;
-                this.updateProgress(state.downloaded, targetLimit, `已下载 ${itemType === 'illustration' ? '插画' : '小说'} ${item.id} (${state.downloaded}/${targetLimit})`);
-                if (itemType === 'novel') {
-                    logger_1.logger.info(`Successfully downloaded novel ${item.id} (${state.downloaded}/${targetLimit})`);
-                }
-            },
-            onProgress: (done, total) => {
-                completedForProgress = done;
-                const msgBase = itemType === 'illustration' ? '插画' : '小说';
-                this.updateProgress(Math.min(state.downloaded, targetLimit), targetLimit, `随机模式进行中(${completedForProgress}/${total}) - 已下载 ${msgBase}: ${state.downloaded}`);
-            },
-            onDecision: (decision, { item, error }) => {
-                const typedItem = item;
-                this.logRecoveryDecision(decision, error, typedItem.id, itemType, typedItem.title);
-                if (decision.action === 'skip') {
-                    state.skippedCount++;
-                    const detail = (0, errors_1.getErrorMessage)(error) || decision.reason || 'download failed';
-                    if (state.skipDetails.length < 3 && !state.skipDetails.some((d) => d.id === String(typedItem.id))) {
-                        state.skipDetails.push({ id: String(typedItem.id), error: detail });
+                // Strict bound, measured in CANDIDATES — not in task invocations. A
+                // retry of the same candidate (the executor's backoff path) must not
+                // consume a new slot, or the guard would silently turn a retried failure
+                // into a success and swallow it.
+                if (!attemptedIndices.has(index)) {
+                    if (attemptedIndices.size >= scan.bound) {
+                        return;
                     }
+                    attemptedIndices.add(index);
+                    scan.attempted = attemptedIndices.size;
                 }
-            },
-        });
-        if (totalPlanned < targetLimit && state.downloaded < targetLimit) {
-            logger_1.logger.info(`Random mode ended after ${totalPlanned} attempt(s); downloaded ${state.downloaded}/${targetLimit} ${itemType}(s)`);
-        }
-    }
-    async executeSequentialMode(plan, targetLimit, itemType, tagForLog, downloadFn, retryAttempts, concurrency, state) {
-        const toProcess = plan.queue;
-        const totalPlanned = toProcess.length;
-        let completedForProgress = 0;
-        await this.executor.run({
-            items: toProcess,
-            concurrency,
-            maxAttempts: retryAttempts,
-            recovery: this.recovery,
-            contextProvider: () => ({ itemType }),
-            task: async (item) => {
-                if (state.downloaded >= targetLimit || this.isRunCancelled()) {
-                    return;
+                const attempt = await downloadFn(item, tagForLog);
+                if ((0, TargetOutcome_1.isSelectedAttempt)(attempt)) {
+                    state.downloaded++;
+                }
+                else if (attempt?.kind === 'skipped') {
+                    recordCandidateSkip(attempt.skip);
+                }
+                else {
+                    state.downloaded++;
                 }
-                await downloadFn(item, tagForLog);
-                state.downloaded++;
                 this.updateProgress(state.downloaded, targetLimit, `已下载 ${itemType === 'illustration' ? '插画' : '小说'} ${item.id} (${state.downloaded}/${targetLimit})`);
-                if (itemType === 'novel') {
+                if (itemType === 'novel' && state.downloaded > 0) {
                     logger_1.logger.info(`Successfully downloaded novel ${item.id} (${state.downloaded}/${targetLimit})`);
                 }
             },
             onProgress: (done, total) => {
-                completedForProgress = done;
                 const msgBase = itemType === 'illustration' ? '插画' : '小说';
-                this.updateProgress(Math.min(state.downloaded, targetLimit), targetLimit, `进行中(${completedForProgress}/${totalPlanned}) - 已下载 ${msgBase}: ${state.downloaded}`);
+                this.updateProgress(Math.min(state.downloaded, targetLimit), targetLimit, `进行中(${done}/${total}) - 已下载 ${msgBase}: ${state.downloaded}`);
             },
-            onDecision: (decision, { item, error }) => {
-                const typedItem = item;
-                this.logRecoveryDecision(decision, error, typedItem.id, itemType, typedItem.title);
+            onDecision: (decision, info) => {
+                const typedItem = info.item;
+                this.logRecoveryDecision(decision, info.error, typedItem.id, itemType, typedItem.title);
                 if (decision.action === 'skip') {
-                    state.skippedCount++;
-                    const detail = (0, errors_1.getErrorMessage)(error) || decision.reason || 'download failed';
-                    if (state.skipDetails.length < 3 && !state.skipDetails.some((d) => d.id === String(typedItem.id))) {
-                        state.skipDetails.push({ id: String(typedItem.id), error: detail });
-                    }
+                    const message = (0, errors_1.getErrorMessage)(info.error) || decision.reason || 'download failed';
+                    recordCandidateFailure(info.error === undefined || info.error === null ? new Error(message) : info.error, String(typedItem.id));
                 }
             },
-        });
+        };
+        if (plan.mode === 'random') {
+            if (planAvailableCount === 0) {
+                logger_1.logger.info('All search results have already been downloaded');
+            }
+            else if (plan.queue.length > 0) {
+                await this.executor.run({ ...runOptions, items: plan.queue });
+            }
+        }
+        else if (plan.queue.length > 0) {
+            await this.executor.run({ ...runOptions, items: plan.queue });
+        }
+        logger_1.logger.info(`Candidate scan ${tagForLog}: attempted ${scan.attempted}/${scan.bound}, produced ${state.downloaded} ` +
+            `${itemType}(s), skipped ${scan.skipped.length}` +
+            `${scan.outages.length > 0 ? `, job-level outage(s): ${scan.outages.join(', ')}` : ''}`);
+        this.updateProgress(state.downloaded, targetLimit, `完成下载: ${state.downloaded} 个 ${itemType === 'illustration' ? '插画' : '小说'}`);
+        return {
+            downloaded: state.downloaded,
+            skipped: state.skippedCount,
+            alreadyDownloaded: alreadyDownloadedCount,
+            filteredOut: filteredOutCount,
+            skipDetails: state.skipDetails,
+            scan,
+        };
     }
     updateProgress(current, total, message) {
         this.progressReporter.update(current, total, message);

package/dist/download/plan/DownloadPlanner.d.ts

@@ -1,26 +1,62 @@
 import type { TargetConfig } from '../../config';
 import type { PixivIllust, PixivNovel } from '@redtidev/pixiv-client';
 import type { IDatabase } from '../../interfaces/IDatabase';
+import type { CandidateSkip } from '../../scheduler/TargetOutcome';
 export type DownloadItem = PixivIllust | PixivNovel;
 export interface PlannedDownload<T extends DownloadItem> {
     queue: T[];
     mode: 'sequential' | 'random';
     limit: number;
+    /**
+     * Maximum candidates this plan may ATTEMPT. Always `queue.length`, so the
+     * bound is enforced structurally: the pipeline cannot scan further than the
+     * window it was handed. Reported in the terminal outcome as "scanning N".
+     */
+    scanBound: number;
     filteredOut: number;
     deduplicated: number;
     alreadyDownloaded: number;
     availableCount: number;
     originalCount: number;
+    /**
+     * Candidates the planner itself dropped BEFORE the download attempt —
+     * already in download history, already CONFIRMED delivered to this target, or
+     * already handled per durable history. They are skips, not failures, and are
+     * reported in the terminal outcome so "skipping Y candidates" includes the
+     * ones that never had to be downloaded.
+     */
+    prefiltered: CandidateSkip[];
     random?: {
         maxAttempts: number;
     };
 }
+/**
+ * Default candidate-scan window. Five candidates is enough to survive a few
+ * already-delivered works on a ranking page without turning one slot into a
+ * long crawl; the operator can raise it per target or globally.
+ */
+export declare const DEFAULT_CANDIDATE_SCAN_LIMIT = 5;
+/** Hard ceiling on the scan so a misconfigured value cannot become a crawl. */
+export declare const MAX_CANDIDATE_SCAN_LIMIT = 100;
+/**
+ * Resolve the candidate-scan bound for one target: per-target override, then
+ * the global `download.candidateScanLimit`, then the default. Clamped so a bad
+ * value degrades to a working bound instead of disabling the bound.
+ */
+export declare function resolveCandidateScanLimit(target: TargetConfig, fallback?: number): number;
 /**
  * Centralizes planning logic (filtering, deduplication, already-downloaded detection, random selection).
  */
 export interface DeliveryDedupeSource {
     /** Returns the subset of ids already CONFIRMED delivered to this target. */
     deliveredIds?(deliveryTarget: string, workType: 'illustration' | 'novel', ids: string[]): Set<string>;
+    /**
+     * Returns the subset of ids already SUBMITTED for this target — delivered OR
+     * still awaiting a review answer. Candidate selection prefers this over
+     * `deliveredIds`: a work whose review submission is pending is already in the
+     * human queue, so selecting it again would submit it twice.
+     */
+    submittedIds?(deliveryTarget: string, workType: 'illustration' | 'novel', ids: string[]): Set<string>;
     /**
      * Works this bot has already handled ANYWHERE — durable history owned by a
      * control plane, supplied by the caller.
@@ -35,7 +71,17 @@ export interface DeliveryDedupeSource {
 export declare class DownloadPlanner {
     private readonly database;
     private readonly deliveryDedupe?;
-    constructor(database: IDatabase, deliveryDedupe?: DeliveryDedupeSource | undefined);
+    /**
+     * Global candidate-scan bound (`download.candidateScanLimit`). A per-target
+     * `candidateScanLimit` overrides it.
+     */
+    private readonly defaultCandidateScanLimit?;
+    constructor(database: IDatabase, deliveryDedupe?: DeliveryDedupeSource | undefined, 
+    /**
+     * Global candidate-scan bound (`download.candidateScanLimit`). A per-target
+     * `candidateScanLimit` overrides it.
+     */
+    defaultCandidateScanLimit?: number | undefined);
     planDownloads<T extends DownloadItem>(items: T[], target: TargetConfig, itemType: 'illustration' | 'novel'): PlannedDownload<T>;
     private filterItems;
     private deduplicate;

package/dist/download/plan/DownloadPlanner.js

@@ -1,39 +1,100 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DownloadPlanner = void 0;
+exports.DownloadPlanner = exports.MAX_CANDIDATE_SCAN_LIMIT = exports.DEFAULT_CANDIDATE_SCAN_LIMIT = void 0;
+exports.resolveCandidateScanLimit = resolveCandidateScanLimit;
 const date_utils_1 = require("../../utils/date-utils");
 const ai_detection_1 = require("../../utils/ai-detection");
 const logger_1 = require("../../logger");
+/**
+ * Default candidate-scan window. Five candidates is enough to survive a few
+ * already-delivered works on a ranking page without turning one slot into a
+ * long crawl; the operator can raise it per target or globally.
+ */
+exports.DEFAULT_CANDIDATE_SCAN_LIMIT = 5;
+/** Hard ceiling on the scan so a misconfigured value cannot become a crawl. */
+exports.MAX_CANDIDATE_SCAN_LIMIT = 100;
+/**
+ * Resolve the candidate-scan bound for one target: per-target override, then
+ * the global `download.candidateScanLimit`, then the default. Clamped so a bad
+ * value degrades to a working bound instead of disabling the bound.
+ */
+function resolveCandidateScanLimit(target, fallback) {
+    const configured = target.candidateScanLimit ?? fallback ?? exports.DEFAULT_CANDIDATE_SCAN_LIMIT;
+    if (!Number.isFinite(configured))
+        return exports.DEFAULT_CANDIDATE_SCAN_LIMIT;
+    return Math.min(Math.max(Math.trunc(configured), 1), exports.MAX_CANDIDATE_SCAN_LIMIT);
+}
 class DownloadPlanner {
     database;
     deliveryDedupe;
-    constructor(database, deliveryDedupe) {
+    defaultCandidateScanLimit;
+    constructor(database, deliveryDedupe, 
+    /**
+     * Global candidate-scan bound (`download.candidateScanLimit`). A per-target
+     * `candidateScanLimit` overrides it.
+     */
+    defaultCandidateScanLimit) {
         this.database = database;
         this.deliveryDedupe = deliveryDedupe;
+        this.defaultCandidateScanLimit = defaultCandidateScanLimit;
     }
     planDownloads(items, target, itemType) {
         const filtered = this.filterItems(items, target, itemType);
         const { items: deduplicatedItems, removed } = this.deduplicate(filtered.items);
+        /**
+         * Candidates dropped before any download attempt. Reported as explicit
+         * skips so the terminal outcome can say "skipping Y candidates" instead of
+         * claiming a run produced nothing for no stated reason.
+         */
+        const prefiltered = [];
+        const ruleFiltered = new Set(deduplicatedItems.map((item) => String(item.id)));
+        for (const item of items) {
+            const id = String(item.id);
+            if (!ruleFiltered.has(id)) {
+                // Excluded by the target's own rules (bookmarks/date/AI) — or a
+                // repeated id inside the page. Both are candidate-level skips.
+                prefiltered.push({ code: 'filtered', workId: id, reason: 'excluded by target filters (bookmarks/date/AI)' });
+            }
+        }
         const itemIds = deduplicatedItems.map((item) => String(item.id));
         const downloadedIds = itemIds.length > 0 ? this.database.getDownloadedIds(itemIds, itemType) : new Set();
         let available = deduplicatedItems.filter((item) => !downloadedIds.has(String(item.id)));
         const alreadyDownloadedCount = deduplicatedItems.length - available.length;
+        for (const item of deduplicatedItems) {
+            const id = String(item.id);
+            if (downloadedIds.has(id)) {
+                prefiltered.push({ code: 'duplicate', workId: id, reason: 'already in download history' });
+            }
+        }
         // DELIVERY dedupe (pre-lock, distinct from download dedupe): skip works
-        // already CONFIRMED delivered to THIS target so ranking falls through to
-        // the next valid candidate instead of selecting a historical duplicate.
+        // already SUBMITTED for THIS target — confirmed delivered, or still awaiting
+        // a review answer — so ranking falls through to the next valid candidate
+        // instead of selecting a historical duplicate. `submittedIds` is preferred
+        // because a pending review submission is already in the human queue.
         // Best-effort only: downstream reconciliation remains the final safety net.
         const deliveryTarget = target.delivery?.target?.trim();
+        const submittedQuery = this.deliveryDedupe?.submittedIds ?? this.deliveryDedupe?.deliveredIds;
         let deliveryDuplicateCount = 0;
         if (deliveryTarget &&
-            this.deliveryDedupe?.deliveredIds &&
+            submittedQuery &&
             typeof this.database.deliveries === 'object') {
             try {
-                const delivered = this.deliveryDedupe.deliveredIds(deliveryTarget, itemType, available.map((item) => String(item.id)));
+                const taken = submittedQuery.call(this.deliveryDedupe, deliveryTarget, itemType, available.map((item) => String(item.id)));
                 const before = available.length;
-                available = available.filter((item) => !delivered.has(String(item.id)));
+                for (const item of available) {
+                    const id = String(item.id);
+                    if (taken.has(id)) {
+                        prefiltered.push({
+                            code: 'duplicate',
+                            workId: id,
+                            reason: `already submitted to ${deliveryTarget} (delivery ledger)`,
+                        });
+                    }
+                }
+                available = available.filter((item) => !taken.has(String(item.id)));
                 deliveryDuplicateCount = before - available.length;
                 if (deliveryDuplicateCount > 0) {
-                    logger_1.logger.info(`Delivery dedupe skipped ${deliveryDuplicateCount} already-delivered ${itemType}(s) for ${deliveryTarget}`);
+                    logger_1.logger.info(`Delivery dedupe skipped ${deliveryDuplicateCount} already-submitted ${itemType}(s) for ${deliveryTarget}`);
                 }
             }
             catch (error) {
@@ -49,6 +110,12 @@ class DownloadPlanner {
             try {
                 const processed = processedSource(itemType, available.map((item) => String(item.id)));
                 const before = available.length;
+                for (const item of available) {
+                    const id = String(item.id);
+                    if (processed.has(id)) {
+                        prefiltered.push({ code: 'duplicate', workId: id, reason: 'already handled (durable history)' });
+                    }
+                }
                 available = available.filter((item) => !processed.has(String(item.id)));
                 const skipped = before - available.length;
                 if (skipped > 0) {
@@ -62,40 +129,63 @@ class DownloadPlanner {
             }
         }
         const limit = target.limit && target.limit > 0 ? target.limit : 10;
+        // How many candidates this run may ATTEMPT. Distinct from `limit`, which is
+        // how many it may PRODUCE. A scheduled one-post-per-slot target has
+        // `limit: 1`, so keying the candidate window off `limit` alone handed the
+        // pipeline exactly one candidate: the first duplicate ended the slot with
+        // nothing submitted. Never below `limit`, so a multi-work target can still
+        // fill its own limit.
+        const scanBound = Math.max(limit, resolveCandidateScanLimit(target, this.defaultCandidateScanLimit));
         if (target.random) {
             const shuffled = this.shuffle(available);
-            const maxAttempts = Math.min(shuffled.length, 50);
+            // Historical 50-attempt random pool, unless the operator set an explicit
+            // bound — in which case that bound is the contract.
+            const attemptPool = target.candidateScanLimit !== undefined ? scanBound : 50;
+            const maxAttempts = Math.min(shuffled.length, Math.max(limit, attemptPool));
             const queue = shuffled.slice(0, maxAttempts);
             return {
                 queue,
                 mode: 'random',
                 limit,
+                scanBound: queue.length,
                 filteredOut: filtered.filteredOut,
                 deduplicated: removed,
                 alreadyDownloaded: alreadyDownloadedCount,
                 availableCount: available.length,
                 originalCount: filtered.originalCount,
+                prefiltered,
                 random: { maxAttempts },
             };
         }
-        // Language is detected from the full novel body during download. Keep a
-        // bounded popularity-ordered retry pool so a non-matching Top-1 candidate
-        // can be skipped and replaced by the next matching novel.
-        const backfillLimit = itemType === 'novel' && target.languageFilter
+        // How many candidates the run may ATTEMPT:
+        //   window = clamp(candidateScanLimit, lower = limit, upper = pool)
+        // where `pool` is what the operator asked to consider — the whole page for a
+        // plain search/ranking target, and a deliberately deeper pool for full-text
+        // novel language filtering or topic discovery. `candidateScanLimit` is the
+        // hard cap; it is never exceeded, and it is never allowed below `limit`
+        // because a multi-work target must still be able to fill its own limit.
+        const pool = itemType === 'novel' && target.languageFilter
             ? Math.max(limit, Math.min(target.languageCandidateLimit ?? 20, 100))
             : target.mode === 'topic'
                 ? Math.max(limit, 20)
-                : limit;
-        const queue = available.slice(0, Math.min(available.length, backfillLimit));
+                : available.length;
+        const windowSize = Math.max(limit, Math.min(pool, scanBound));
+        const queue = available.slice(0, Math.min(available.length, windowSize));
+        if (queue.length > limit) {
+            logger_1.logger.info(`Candidate scan window: up to ${queue.length} candidate(s) to fill ${limit} slot(s) ` +
+                `(bound ${scanBound}, pool ${pool}, ${available.length} available)`);
+        }
         return {
             queue,
             mode: 'sequential',
             limit,
+            scanBound: queue.length,
             filteredOut: filtered.filteredOut,
             deduplicated: removed,
             alreadyDownloaded: alreadyDownloadedCount,
             availableCount: available.length,
             originalCount: filtered.originalCount,
+            prefiltered,
         };
     }
     filterItems(items, target, itemType) {

package/dist/notification/NotificationPolicy.d.ts

@@ -33,6 +33,7 @@ export declare class NotificationPolicy {
         hardFail: (slotId: string, targetId: string) => string;
         summary: (slotId: string) => string;
         dead: (slotId: string, targetId: string) => string;
+        refetchOutcome: (slotId: string, targetId: string) => string;
     };
     noteOutcome(slotId: string, slot: SlotContext, schedule: ScheduleConfig, target: TargetConfig, outcome: TargetOutcome): void;
     /** One consolidated summary per slot, delivered to every notifying target's endpoint. */
@@ -45,5 +46,16 @@ export declare class NotificationPolicy {
         error: string | null;
     }>): void;
     private send;
+    /**
+     * Report the terminal verdict of a REMOTE MANUAL replacement ("重抓") back to
+     * the requester through the durable outbox. Only terminal outcomes are
+     * reported (no_candidate / non-retryable failed); a successful replacement is
+     * correlated by the submission itself (its payload carries the request id).
+     *
+     * The key is anchored to the manual SLOT, so a slot recovered and re-run can
+     * never enqueue a second verdict for the same logical attempt, and helpers
+     * that already returned remain idempotent.
+     */
+    noteRefetchOutcome(slot: SlotContext, _schedule: ScheduleConfig, target: TargetConfig, requestId: string, outcome: TargetOutcome): void;
 }
 //# sourceMappingURL=NotificationPolicy.d.ts.map

package/dist/notification/NotificationPolicy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotificationPolicy = void 0;
 const DeliveryService_1 = require("../delivery/DeliveryService");
+const logger_1 = require("../logger");
 /**
  * Central policy for all operational notifications. Handlers/scheduler do not
  * decide how or when to notify — they emit domain outcomes and this policy
@@ -44,6 +45,7 @@ class NotificationPolicy {
         hardFail: (slotId, targetId) => `notification:${slotId}:${targetId}:failed`,
         summary: (slotId) => `notification:${slotId}:summary`,
         dead: (slotId, targetId) => `notification:${slotId}:${targetId}:delivery-dead`,
+        refetchOutcome: (slotId, targetId) => `refetch-outcome:${slotId}:${targetId}`,
     };
     noteOutcome(slotId, slot, schedule, target, outcome) {
         const name = this.targetName(target);
@@ -104,6 +106,90 @@ class NotificationPolicy {
             console.warn('notification enqueue failed', { targetName, key, error: error.message });
         }
     }
+    /**
+     * Report the terminal verdict of a REMOTE MANUAL replacement ("重抓") back to
+     * the requester through the durable outbox. Only terminal outcomes are
+     * reported (no_candidate / non-retryable failed); a successful replacement is
+     * correlated by the submission itself (its payload carries the request id).
+     *
+     * The key is anchored to the manual SLOT, so a slot recovered and re-run can
+     * never enqueue a second verdict for the same logical attempt, and helpers
+     * that already returned remain idempotent.
+     */
+    noteRefetchOutcome(slot, _schedule, target, requestId, outcome) {
+        const name = this.targetName(target);
+        if (!name)
+            return;
+        const deliveryTarget = this.config.delivery?.targets?.[name];
+        if (!deliveryTarget || deliveryTarget.type !== 'httpMultipart')
+            return;
+        if (!deliveryTarget.refetchOutcomeUrl?.trim()) {
+            // No endpoint configured: skip the report (content is still durable).
+            logger_1.logger.info('Refetch outcome not reported: refetchOutcomeUrl unset', {
+                slot: slot.slotId,
+                target: target.id,
+                requestId,
+            });
+            return;
+        }
+        let payload;
+        if (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate') {
+            payload = {
+                requestId,
+                disposition: 'no_alternative',
+                reason: outcome.reason,
+                workId: outcome.kind === 'duplicate' ? outcome.workId : undefined,
+                ...scanCounts(outcome.scan),
+            };
+        }
+        else if (outcome.kind === 'failed' && !outcome.retryable) {
+            payload = {
+                requestId,
+                disposition: 'failed',
+                reason: outcome.error,
+                ...scanCounts(outcome.scan),
+            };
+        }
+        else {
+            return; // not terminal for refetch purposes
+        }
+        try {
+            new DeliveryService_1.DeliveryService(this.database).enqueueNotification(name, `refetch outcome: ${payload.disposition} (slot ${slot.slotId})`, NotificationPolicy.keys.refetchOutcome(slot.slotId, target.id ?? target.type), payload);
+            logger_1.logger.info('Refetch outcome enqueued for report', {
+                slot: slot.slotId,
+                target: target.id,
+                requestId,
+                disposition: payload.disposition,
+            });
+        }
+        catch (error) {
+            // A failed VERDICT report never changes the terminal content state; it is
+            // retried by the operator/resume path, and never unwinds the run.
+            logger_1.logger.warn('Refetch outcome report enqueue failed', {
+                slot: slot.slotId,
+                target: target.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
 }
 exports.NotificationPolicy = NotificationPolicy;
+/** Fold a CandidateScanSummary into the refetch-outcome bookkeeping (bounded). */
+function scanCounts(scan) {
+    if (!scan)
+        return {};
+    const skipped = scan.skipped ?? [];
+    const duplicate = skipped.filter((s) => s.code === 'duplicate').length;
+    const unavailable = skipped.filter((s) => s.code === 'unavailable').length;
+    const invalid = skipped.filter((s) => ['deleted', 'access_denied', 'unsupported_media', 'invalid_metadata', 'filtered'].includes(s.code)).length;
+    return {
+        scanned: scan.attempted,
+        skipped: {
+            total: skipped.length,
+            duplicate,
+            invalid,
+            unavailable,
+        },
+    };
+}
 //# sourceMappingURL=NotificationPolicy.js.map

package/dist/package.json

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