v2er-insight 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 V2EX 用户画像深度分析工具。通过自动化抓取数据、统计解析及 AI 语言模型建模，构建多维度的用户行为与心理画像。
 
+目前画像结果一般。受限于模型能力、Analyze 结果、提示词，后两个需要更多的迭代。
+
 ## 核心流程 (Pipe Flow)
 
 本项目采用管道化设计，目前通过以下步骤逐步生成深度报告：
@@ -50,7 +52,7 @@ v2er <username>
 | 选项                       | 说明                                                               |
 | -------------------------- | ------------------------------------------------------------------ |
 | `--force`                  | 强制重新抓取（忽略本地缓存）                                       |
-| `--model [name]`           | 指定 AI 模型（默认: `gemini-3-pro-preview`）                       |
+| `--model [name]`           | 指定 AI 模型（默认: `gemini-3.1-pro-preview`）                     |
 | `--thinking-level [level]` | 指定思考等级（默认: `high`，可选 `minimal`/`low`/`medium`/`high`） |
 | `-v, --verbose`            | 显示调试输出                                                       |
 
@@ -98,7 +100,7 @@ v2er ai <username> [选项]
 
 | 选项                       | 说明                                                               |
 | -------------------------- | ------------------------------------------------------------------ |
-| `--model [name]`           | 指定 Gemini 模型（默认: `gemini-3-pro-preview`）                   |
+| `--model [name]`           | 指定 Gemini 模型（默认: `gemini-3.1-pro-preview`）                 |
 | `--thinking-level [level]` | 指定思考等级（默认: `high`，可选 `minimal`/`low`/`medium`/`high`） |
 
 ### 4. 报告展示 (Show)
@@ -131,6 +133,12 @@ v2er config set ai.thinkingLevel medium     # 设置思考等级
 v2er config set log.level debug             # 开启调试日志
 v2er config set data.keepRaw true           # 保留原始数据
 v2er config set ai.timeout 120000           # AI 请求超时 120s
+v2er config set ai.maxRetries 5             # AI 最大重试次数
+v2er config set ai.baseDelay 2000           # AI 重试基础延迟 2s
+v2er config set ai.maxDelay 20000           # AI 重试最大延迟 20s
+v2er config set fetch.maxRetries 5           # 抓取最大重试次数
+v2er config set fetch.baseDelay 2000         # 抓取重试基础延迟 2s
+v2er config set fetch.maxDelay 30000         # 抓取重试最大延迟 30s
 
 # 重置
 v2er config reset                           # 重置全部为默认值

package/dist/cli/commands/ai.js

@@ -52,7 +52,7 @@ async function runAi(username, options) {
     // 字符串时直接使用，否则回退到配置/默认值（后续支持交互选择时替换此逻辑）
     const model = typeof options.model === 'string'
         ? options.model
-        : (config.ai?.model ?? 'gemini-3-pro-preview');
+        : (config.ai?.model ?? config_1.DEFAULT_CONFIG.ai.model);
     // 同上：--thinking-level [level] 无值时为 true，字符串时直接使用
     const rawThinkingLevel = typeof options.thinkingLevel === 'string' ? options.thinkingLevel : config.ai?.thinkingLevel;
     // 校验 thinkingLevel 合法性
@@ -81,9 +81,14 @@ async function runAi(username, options) {
     // 创建 Provider
     const provider = new ai_1.GeminiProvider(apiKey, model);
     const retryOptions = {
-        maxRetries: config.ai?.maxRetries,
-        baseDelay: config.ai?.baseDelay,
-        maxDelay: config.ai?.maxDelay,
+        maxRetries: config.ai?.maxRetries ?? config_1.DEFAULT_CONFIG.ai.maxRetries,
+        baseDelay: config.ai?.baseDelay ?? config_1.DEFAULT_CONFIG.ai.baseDelay,
+        maxDelay: config.ai?.maxDelay ?? config_1.DEFAULT_CONFIG.ai.maxDelay,
+        onRetry: (attempt, maxRetries, error, delay) => {
+            const delaySec = (delay / 1000).toFixed(1);
+            logger_1.logger.warn(`  AI 重试 (${attempt}/${maxRetries}) [${delaySec}s 后]`);
+            logger_1.logger.debug(`  原因: ${error.message}`);
+        },
     };
     try {
         // 初始化会话

package/dist/cli/commands/config.js

@@ -36,6 +36,9 @@ const CONFIG_PATHS = {
     'ai.maxDelay': { type: 'number' },
     // Fetch
     'fetch.timeout': { type: 'number' },
+    'fetch.maxRetries': { type: 'number' },
+    'fetch.baseDelay': { type: 'number' },
+    'fetch.maxDelay': { type: 'number' },
     // Analyzer
     'analyzer.inactivityThreshold': { type: 'number' },
     'analyzer.chunkMaxTopics': { type: 'number' },

package/dist/cli/commands/fetch.js

@@ -132,8 +132,6 @@ async function runFetch(username, options) {
             meta: {
                 failedTopics,
                 failedPages,
-                // TODO(ia319): 在实现 --retry 后补充真实失败页索引 [2026-02-14]
-                failedPageIndices: [],
             },
         };
     }

package/dist/cli/index.js

@@ -48,8 +48,12 @@ commander_1.program
     .option('--topics', 'Fetch topics only')
     .option('--replies', 'Fetch replies only')
     .option('--force', 'Force refetch even if cache exists')
-    .action(async (username, options) => {
-    const result = await (0, commands_1.runFetch)(username, options);
+    .option('-v, --verbose', 'Show debug output')
+    .action(async (username, _, command) => {
+    const opts = command.optsWithGlobals();
+    if (opts.verbose)
+        logger_1.logger.setLevel('debug');
+    const result = await (0, commands_1.runFetch)(username, opts);
     if (result.status === 'failed')
         process.exitCode = 1;
 });
@@ -58,7 +62,11 @@ commander_1.program
     .command('analyze')
     .description('Process raw data and generate statistics')
     .argument('<username>', 'V2EX username')
-    .action(async (username) => {
+    .option('-v, --verbose', 'Show debug output')
+    .action(async (username, _, command) => {
+    const opts = command.optsWithGlobals();
+    if (opts.verbose)
+        logger_1.logger.setLevel('debug');
     const result = await (0, commands_1.runAnalyze)(username);
     if (result.status === 'failed')
         process.exitCode = 1;
@@ -70,8 +78,12 @@ commander_1.program
     .argument('<username>', 'V2EX username')
     .option('--model [name]', 'Specify Gemini model (or select interactively)')
     .option('--thinking-level [level]', 'Specify thinking level: minimal | low | medium | high')
-    .action(async (username, options) => {
-    const result = await (0, commands_1.runAi)(username, options);
+    .option('-v, --verbose', 'Show debug output')
+    .action(async (username, _, command) => {
+    const opts = command.optsWithGlobals();
+    if (opts.verbose)
+        logger_1.logger.setLevel('debug');
+    const result = await (0, commands_1.runAi)(username, opts);
     if (result.status === 'failed')
         process.exitCode = 1;
 });
@@ -82,8 +94,12 @@ commander_1.program
     .argument('<username>', 'V2EX username')
     .option('--json', 'Output raw JSON')
     .option('--brief', 'Show brief summary only')
-    .action(async (username, options) => {
-    const result = await (0, commands_1.runShow)(username, options);
+    .option('-v, --verbose', 'Show debug output')
+    .action(async (username, _options, command) => {
+    const opts = command.optsWithGlobals();
+    if (opts.verbose)
+        logger_1.logger.setLevel('debug');
+    const result = await (0, commands_1.runShow)(username, opts);
     if (result.status === 'failed')
         process.exitCode = 1;
 });

package/dist/cli/utils.js

@@ -43,6 +43,11 @@ function createFetchEvents(label) {
         onError: (result) => {
             logFetchError(result);
         },
+        onRetry: (url, attempt, maxRetries, delay, reason) => {
+            const delaySec = (delay / 1000).toFixed(1);
+            logger_1.logger.warn(`  重试 (${attempt}/${maxRetries}) [${delaySec}s 后]: ${url}`);
+            logger_1.logger.debug(`  原因: ${reason}`);
+        },
     };
 }
 //# sourceMappingURL=utils.js.map

package/dist/config/defaults.d.ts

@@ -21,7 +21,7 @@ export type ResolvedConfig = Required<{
 export declare const DEFAULT_CONFIG: {
     readonly ai: {
         readonly provider: "gemini";
-        readonly model: "gemini-3-pro-preview";
+        readonly model: "gemini-3.1-pro-preview";
         readonly thinkingLevel: "high";
         readonly timeout: 60000;
         readonly maxRetries: 3;
@@ -30,6 +30,9 @@ export declare const DEFAULT_CONFIG: {
     };
     readonly fetch: {
         readonly timeout: 30000;
+        readonly maxRetries: 3;
+        readonly baseDelay: 1000;
+        readonly maxDelay: 8000;
     };
     readonly analyzer: {
         readonly inactivityThreshold: 60;

package/dist/config/defaults.js

@@ -15,7 +15,7 @@ exports.DEFAULT_CONFIG = void 0;
 exports.DEFAULT_CONFIG = {
     ai: {
         provider: 'gemini',
-        model: 'gemini-3-pro-preview',
+        model: 'gemini-3.1-pro-preview',
         thinkingLevel: 'high',
         timeout: 60000,
         maxRetries: 3,
@@ -24,6 +24,9 @@ exports.DEFAULT_CONFIG = {
     },
     fetch: {
         timeout: 30000,
+        maxRetries: 3,
+        baseDelay: 1000,
+        maxDelay: 8000,
     },
     analyzer: {
         inactivityThreshold: 60,

package/dist/config/types/fetch.d.ts

@@ -5,5 +5,11 @@
 export interface FetchConfig {
     /** HTTP 请求超时（毫秒） */
     timeout?: number;
+    /** HTTP 请求最大重试次数（0 = 不重试） */
+    maxRetries?: number;
+    /** 重试基础延迟（毫秒） */
+    baseDelay?: number;
+    /** 重试最大延迟上限（毫秒） */
+    maxDelay?: number;
 }
 //# sourceMappingURL=fetch.d.ts.map

package/dist/core/ai/utils/retry.d.ts

@@ -1,15 +1,8 @@
 /**
- * 重试工具 - 指数退避
- */
-export interface RetryOptions {
-    maxRetries?: number;
-    baseDelay?: number;
-    maxDelay?: number;
-}
-/**
- * 带重试逻辑执行函数
+ * 重试工具 — 向后兼容 re-export
  *
- * 使用指数退避 + 随机抖动策略
+ * 实现已迁移至 infra/retry，此文件保留以维持 core/ai 的公开 API 不变。
  */
-export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export { withRetry } from '../../../infra/retry';
+export type { RetryOptions } from '../../../infra/retry';
 //# sourceMappingURL=retry.d.ts.map

package/dist/core/ai/utils/retry.js

@@ -1,37 +1,11 @@
 "use strict";
 /**
- * 重试工具 - 指数退避
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withRetry = withRetry;
-const config_1 = require("../../../config");
-/**
- * 带重试逻辑执行函数
+ * 重试工具 — 向后兼容 re-export
  *
- * 使用指数退避 + 随机抖动策略
+ * 实现已迁移至 infra/retry，此文件保留以维持 core/ai 的公开 API 不变。
  */
-async function withRetry(fn, options = {}) {
-    const aiConfig = (0, config_1.getConfig)().ai;
-    const { maxRetries = aiConfig?.maxRetries ?? 3, baseDelay = aiConfig?.baseDelay ?? 1000, maxDelay = aiConfig?.maxDelay ?? 10000, } = options;
-    const safeMaxRetries = Math.max(0, maxRetries);
-    let lastError;
-    for (let attempt = 0; attempt <= safeMaxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error : new Error(String(error));
-            if (attempt === safeMaxRetries) {
-                break;
-            }
-            const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
-            const jitter = delay * 0.1 * Math.random();
-            await sleep(delay + jitter);
-        }
-    }
-    throw lastError;
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = void 0;
+var retry_1 = require("../../../infra/retry");
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return retry_1.withRetry; } });
 //# sourceMappingURL=retry.js.map

package/dist/core/v2ex/use-cases/user/topics-detail.d.ts

@@ -1,6 +1,6 @@
 /**
  * 用户发帖详情获取服务
- * 获取用户所有发帖的完整内容
+ * 获取用户所有发帖的完整内容，支持失败帖二次重试
  */
 import type { TopicDetailParseResult } from '../../types';
 import type { ServiceOptions } from '../types';
@@ -22,6 +22,9 @@ export interface UserTopicsDetailResult {
 /**
  * 获取用户所有发帖的完整详情
  *
+ * 第一轮批量抓取所有帖子，收集失败项（HTTP 失败或解析失败）；
+ * 第一轮结束后，若存在失败项，发起第二轮重试。
+ *
  * @param username - 用户名
  * @param options - 服务配置选项
  * @returns 包含所有帖子详情的结果

package/dist/core/v2ex/use-cases/user/topics-detail.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * 用户发帖详情获取服务
- * 获取用户所有发帖的完整内容
+ * 获取用户所有发帖的完整内容，支持失败帖二次重试
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAllUserTopicsDetail = getAllUserTopicsDetail;
@@ -11,6 +11,9 @@ const topic_urls_1 = require("./topic-urls");
 /**
  * 获取用户所有发帖的完整详情
  *
+ * 第一轮批量抓取所有帖子，收集失败项（HTTP 失败或解析失败）；
+ * 第一轮结束后，若存在失败项，发起第二轮重试。
+ *
  * @param username - 用户名
  * @param options - 服务配置选项
  * @returns 包含所有帖子详情的结果
@@ -34,8 +37,8 @@ async function getAllUserTopicsDetail(username, options) {
     };
     const topics = [];
     let fetchedTopics = 0;
-    let failedTopics = 0;
-    // 批量抓取并解析帖子详情
+    const failedUrls = [];
+    // 第一轮：批量抓取并解析帖子详情
     for await (const result of fetcher.fetch(urlsResult.data, fetchOptions, options?.events)) {
         if (result.success && result.content) {
             try {
@@ -44,18 +47,45 @@ async function getAllUserTopicsDetail(username, options) {
                 fetchedTopics++;
             }
             catch {
-                failedTopics++;
+                // 解析失败，记录 URL 用于二次重试
+                failedUrls.push(result.url);
             }
         }
         else {
-            failedTopics++;
+            failedUrls.push(result.url);
+        }
+    }
+    // 第二轮：对失败帖发起重试
+    if (failedUrls.length > 0) {
+        const recoveredUrls = new Set();
+        for await (const result of fetcher.fetch(failedUrls, fetchOptions, options?.events)) {
+            if (result.success && result.content) {
+                try {
+                    const detail = (0, parsers_1.parseTopicDetail)(result.content);
+                    topics.push(detail);
+                    fetchedTopics++;
+                    recoveredUrls.add(result.url);
+                }
+                catch {
+                    // 二次重试解析仍失败
+                }
+            }
         }
+        // 最终失败数 = 原失败列表 - 已恢复
+        const stillFailed = failedUrls.filter((url) => !recoveredUrls.has(url));
+        return {
+            topics,
+            totalTopics: urlsResult.data.length,
+            fetchedTopics,
+            failedTopics: stillFailed.length,
+            isHidden: false,
+        };
     }
     return {
         topics,
         totalTopics: urlsResult.data.length,
         fetchedTopics,
-        failedTopics,
+        failedTopics: failedUrls.length,
         isHidden: false,
     };
 }

package/dist/core/v2ex/use-cases/utils/page-orchestrator.d.ts

@@ -1,6 +1,6 @@
 /**
  * 分页数据编排器
- * 提供通用的多页数据获取逻辑
+ * 提供通用的多页数据获取逻辑，支持失败页二次重试
  */
 import type { PagedResult, ServiceOptions } from '../types';
 /**
@@ -14,6 +14,10 @@ export interface PaginatedParseResult {
 /**
  * 获取分页数据的通用函数
  *
+ * 第一轮遍历所有页面，收集失败项；
+ * 第一轮结束后，若存在失败页，发起第二轮重试。
+ * 最终返回的 failedPages 为二次重试后仍失败的数量。
+ *
  * @param urlGenerator - 根据页码生成 URL 的函数
  * @param parser - 解析 HTML 并返回包含分页信息的结果
  * @param extractor - 从解析结果中提取数据列表的函数

package/dist/core/v2ex/use-cases/utils/page-orchestrator.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * 分页数据编排器
- * 提供通用的多页数据获取逻辑
+ * 提供通用的多页数据获取逻辑，支持失败页二次重试
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchPagedData = fetchPagedData;
@@ -9,6 +9,10 @@ const fetcher_1 = require("../../../../infra/fetcher");
 /**
  * 获取分页数据的通用函数
  *
+ * 第一轮遍历所有页面，收集失败项；
+ * 第一轮结束后，若存在失败页，发起第二轮重试。
+ * 最终返回的 failedPages 为二次重试后仍失败的数量。
+ *
  * @param urlGenerator - 根据页码生成 URL 的函数
  * @param parser - 解析 HTML 并返回包含分页信息的结果
  * @param extractor - 从解析结果中提取数据列表的函数
@@ -24,7 +28,6 @@ async function fetchPagedData(urlGenerator, parser, extractor, options) {
     const allData = [];
     let totalPages = 1;
     let fetchedPages = 0;
-    let failedPages = 0;
     // 抓取第一页，获取分页信息
     // total 参数使用 -1 表示尚未确定总页数
     const firstPageUrl = urlGenerator(1);
@@ -56,14 +59,15 @@ async function fetchPagedData(urlGenerator, parser, extractor, options) {
     }
     // 单页时直接返回
     if (totalPages <= 1) {
-        return { data: allData, totalPages, fetchedPages, failedPages };
+        return { data: allData, totalPages, fetchedPages, failedPages: 0 };
     }
-    // 生成剩余页 URL 并批量抓取
+    // 生成剩余页 URL 并批量抓取（第一轮）
     const remainingUrls = [];
     for (let page = 2; page <= totalPages; page++) {
         remainingUrls.push(urlGenerator(page));
     }
-    let pageIndex = 1; // 从第2页开始，index=1
+    const failedItems = [];
+    let pageIndex = 1; // 从第 2 页开始，index = 1
     for await (const result of fetcher.fetch(remainingUrls, fetchOptions, options?.events)) {
         if (result.success && result.content) {
             try {
@@ -72,7 +76,7 @@ async function fetchPagedData(urlGenerator, parser, extractor, options) {
                 fetchedPages++;
             }
             catch (error) {
-                // 单页解析失败，通知错误并继续
+                // 单页解析失败，记录并继续
                 options?.events?.onError?.({
                     url: result.url,
                     success: false,
@@ -80,14 +84,42 @@ async function fetchPagedData(urlGenerator, parser, extractor, options) {
                     error: error instanceof Error ? error : new Error(String(error)),
                     statusCode: 0,
                 }, pageIndex, totalPages);
-                failedPages++;
+                failedItems.push({ url: result.url, pageIndex });
             }
         }
         else {
-            failedPages++;
+            failedItems.push({ url: result.url, pageIndex });
         }
         pageIndex++;
     }
-    return { data: allData, totalPages, fetchedPages, failedPages };
+    // 第二轮：对失败页发起重试
+    if (failedItems.length > 0) {
+        const retryUrls = failedItems.map((item) => item.url);
+        const recoveredUrls = new Set();
+        for await (const result of fetcher.fetch(retryUrls, fetchOptions, options?.events)) {
+            if (result.success && result.content) {
+                try {
+                    const parsed = parser(result.content);
+                    allData.push(...extractor(parsed));
+                    fetchedPages++;
+                    recoveredUrls.add(result.url);
+                }
+                catch (error) {
+                    // 二次重试解析仍失败，通知调用方
+                    const item = failedItems.find((f) => f.url === result.url);
+                    options?.events?.onError?.({
+                        url: result.url,
+                        success: false,
+                        content: null,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                        statusCode: 0,
+                    }, item?.pageIndex ?? -1, totalPages);
+                }
+            }
+        }
+        const stillFailed = failedItems.filter((item) => !recoveredUrls.has(item.url));
+        return { data: allData, totalPages, fetchedPages, failedPages: stillFailed.length };
+    }
+    return { data: allData, totalPages, fetchedPages, failedPages: 0 };
 }
 //# sourceMappingURL=page-orchestrator.js.map

package/dist/infra/fetcher/fetcher.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Fetcher — HTTP 请求执行器
+ *
+ * 支持传输级自动重试：对网络错误、5xx、429 使用指数退避重试。
+ * 4xx 等客户端错误不重试，直接返回失败结果。
+ */
 import type { IFetchStrategy, FetchResult, FetchOptions, FetchEvents } from './types';
 export declare class SequentialStrategy implements IFetchStrategy {
     fetch(urls: string[], options?: FetchOptions, events?: FetchEvents): AsyncGenerator<FetchResult>;

package/dist/infra/fetcher/fetcher.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Fetcher — HTTP 请求执行器
+ *
+ * 支持传输级自动重试：对网络错误、5xx、429 使用指数退避重试。
+ * 4xx 等客户端错误不重试，直接返回失败结果。
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,6 +13,8 @@ exports.Fetcher = exports.SequentialStrategy = void 0;
 const axios_1 = __importDefault(require("axios"));
 const agent_1 = require("./agent");
 const config_1 = require("../../config");
+const defaults_1 = require("../../config/defaults");
+const retryable_1 = require("./retryable");
 /**
  * 将响应数据转换为字符串
  */
@@ -21,49 +29,101 @@ function responseToString(data) {
         return String(data);
     }
 }
+/**
+ * 计算指数退避延迟 + 随机抖动
+ */
+function getRetryDelay(attempt, baseDelay, maxDelay) {
+    const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+    const jitter = delay * 0.1 * Math.random();
+    return delay + jitter;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * 将 axios 响应转换为 FetchResult
+ */
+function toFetchResult(url, response) {
+    const isSuccess = response.status >= 200 && response.status < 300;
+    const responseBody = responseToString(response.data);
+    return {
+        url,
+        content: isSuccess ? responseBody : null,
+        success: isSuccess,
+        statusCode: response.status,
+        ...(isSuccess ? {} : { errorBody: responseBody }),
+    };
+}
 class SequentialStrategy {
     async *fetch(urls, options, events) {
         const total = urls.length;
         const httpsAgent = (0, agent_1.getHttpsAgent)();
+        const fetchConfig = (0, config_1.getConfig)().fetch;
+        const maxRetries = Math.max(0, options?.maxRetries ?? fetchConfig?.maxRetries ?? defaults_1.DEFAULT_CONFIG.fetch.maxRetries);
+        const baseDelay = options?.baseDelay ?? fetchConfig?.baseDelay ?? defaults_1.DEFAULT_CONFIG.fetch.baseDelay;
+        const maxDelay = options?.maxDelay ?? fetchConfig?.maxDelay ?? defaults_1.DEFAULT_CONFIG.fetch.maxDelay;
         for (let i = 0; i < total; i++) {
             const url = urls[i];
-            // 触发开始事件
             events?.onStart?.(url, i, total);
-            try {
-                const response = await axios_1.default.get(url, {
-                    timeout: options?.timeout ?? (0, config_1.getConfig)().fetch?.timeout ?? 30000,
-                    ...(options?.headers && { headers: options.headers }),
-                    ...(httpsAgent && { httpsAgent }),
-                    proxy: false,
-                    validateStatus: () => true,
-                });
-                const isSuccess = response.status >= 200 && response.status < 300;
-                const responseBody = responseToString(response.data);
-                const result = {
-                    url,
-                    content: isSuccess ? responseBody : null,
-                    success: isSuccess,
-                    statusCode: response.status,
-                    ...(isSuccess ? {} : { errorBody: responseBody }),
-                };
-                // 触发成功/失败事件
-                if (result.success) {
-                    events?.onSuccess?.(result, i, total);
+            let lastResult = null;
+            let yielded = false;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    const response = await axios_1.default.get(url, {
+                        timeout: options?.timeout ?? fetchConfig?.timeout ?? defaults_1.DEFAULT_CONFIG.fetch.timeout,
+                        ...(options?.headers && { headers: options.headers }),
+                        ...(httpsAgent && { httpsAgent }),
+                        proxy: false,
+                        validateStatus: () => true,
+                    });
+                    const result = toFetchResult(url, response);
+                    // 成功 或 不可重试的错误 → 直接返回
+                    if (result.success || !(0, retryable_1.isRetryable)(result)) {
+                        if (result.success) {
+                            events?.onSuccess?.(result, i, total);
+                        }
+                        else {
+                            events?.onError?.(result, i, total);
+                        }
+                        yield result;
+                        yielded = true;
+                        break;
+                    }
+                    // 可重试的失败，记录并准备重试
+                    lastResult = result;
+                    if (attempt < maxRetries) {
+                        // 429 时优先使用 Retry-After 值
+                        const retryAfterSeconds = result.statusCode === 429
+                            ? (0, retryable_1.parseRetryAfter)(response.headers)
+                            : null;
+                        const delay = retryAfterSeconds !== null
+                            ? Math.min(retryAfterSeconds * 1000, maxDelay)
+                            : getRetryDelay(attempt, baseDelay, maxDelay);
+                        const reason = result.statusCode ? `HTTP ${result.statusCode}` : 'unknown';
+                        events?.onRetry?.(url, attempt + 1, maxRetries, delay, reason);
+                        await sleep(delay);
+                    }
                 }
-                else {
-                    events?.onError?.(result, i, total);
+                catch (error) {
+                    // 网络错误（超时、连接重置等）→ 可重试
+                    lastResult = {
+                        url,
+                        content: null,
+                        success: false,
+                        error: error,
+                    };
+                    if (attempt < maxRetries) {
+                        const delay = getRetryDelay(attempt, baseDelay, maxDelay);
+                        const reason = error.message ?? 'network error';
+                        events?.onRetry?.(url, attempt + 1, maxRetries, delay, reason);
+                        await sleep(delay);
+                    }
                 }
-                yield result;
             }
-            catch (error) {
-                const result = {
-                    url,
-                    content: null,
-                    success: false,
-                    error: error,
-                };
-                events?.onError?.(result, i, total);
-                yield result;
+            // 所有重试耗尽，yield 最后一次失败结果
+            if (!yielded && lastResult) {
+                events?.onError?.(lastResult, i, total);
+                yield lastResult;
             }
         }
     }

package/dist/infra/fetcher/retryable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP 请求重试判定
+ *
+ * 根据响应状态码判断是否值得重试。
+ * 仅网络错误和服务端瞬态故障可重试，客户端错误（4xx）不重试。
+ */
+import type { FetchResult } from './types';
+/**
+ * 判断请求结果是否可重试
+ *
+ * - 无状态码（网络错误、超时等）→ 可重试
+ * - 429 Too Many Requests → 可重试
+ * - 5xx 服务端错误 → 可重试
+ * - 其余（含 4xx 客户端错误）→ 不可重试
+ */
+export declare function isRetryable(result: FetchResult): boolean;
+/**
+ * 从响应头解析 Retry-After 值（秒）
+ *
+ * @returns 延迟秒数，无法解析时返回 null
+ */
+export declare function parseRetryAfter(headers?: Record<string, string>): number | null;
+//# sourceMappingURL=retryable.d.ts.map

package/dist/infra/fetcher/retryable.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * HTTP 请求重试判定
+ *
+ * 根据响应状态码判断是否值得重试。
+ * 仅网络错误和服务端瞬态故障可重试，客户端错误（4xx）不重试。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryable = isRetryable;
+exports.parseRetryAfter = parseRetryAfter;
+/**
+ * 判断请求结果是否可重试
+ *
+ * - 无状态码（网络错误、超时等）→ 可重试
+ * - 429 Too Many Requests → 可重试
+ * - 5xx 服务端错误 → 可重试
+ * - 其余（含 4xx 客户端错误）→ 不可重试
+ */
+function isRetryable(result) {
+    if (!result.statusCode)
+        return true;
+    if (result.statusCode === 429)
+        return true;
+    if (result.statusCode >= 500)
+        return true;
+    return false;
+}
+/**
+ * 从响应头解析 Retry-After 值（秒）
+ *
+ * @returns 延迟秒数，无法解析时返回 null
+ */
+function parseRetryAfter(headers) {
+    if (!headers)
+        return null;
+    // header 名称不区分大小写
+    const value = headers['retry-after'] ?? headers['Retry-After'];
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (!Number.isNaN(seconds) && seconds >= 0) {
+        return seconds;
+    }
+    return null;
+}
+//# sourceMappingURL=retryable.js.map

package/dist/infra/fetcher/types.d.ts

@@ -5,6 +5,12 @@
 export interface FetchOptions {
     headers?: Record<string, string>;
     timeout?: number;
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 重试基础延迟（毫秒） */
+    baseDelay?: number;
+    /** 重试最大延迟上限（毫秒） */
+    maxDelay?: number;
 }
 /** 抓取结果 */
 export interface FetchResult {
@@ -21,6 +27,8 @@ export interface FetchEvents {
     onStart?: (url: string, index: number, total: number) => void;
     onSuccess?: (result: FetchResult, index: number, total: number) => void;
     onError?: (result: FetchResult, index: number, total: number) => void;
+    /** 重试时触发 */
+    onRetry?: (url: string, attempt: number, maxRetries: number, delay: number, reason: string) => void;
 }
 /** 抓取策略接口 */
 export interface IFetchStrategy {

package/dist/infra/retry/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 重试模块导出
+ */
+export { withRetry } from './retry';
+export type { RetryOptions } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/infra/retry/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * 重试模块导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = void 0;
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return retry_1.withRetry; } });
+//# sourceMappingURL=index.js.map

package/dist/infra/retry/retry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 通用重试工具 — 指数退避 + 随机抖动
+ *
+ * 纯参数驱动，不依赖任何 config 模块。
+ * 调用方（AI / Fetcher）负责从 config 读取默认值并传入。
+ */
+import type { RetryOptions } from './types';
+/**
+ * 带重试逻辑执行异步函数
+ *
+ * 使用指数退避（2^attempt * baseDelay）+ 10% 随机抖动策略。
+ * 当所有重试耗尽后，抛出最后一次捕获的错误。
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/infra/retry/retry.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * 通用重试工具 — 指数退避 + 随机抖动
+ *
+ * 纯参数驱动，不依赖任何 config 模块。
+ * 调用方（AI / Fetcher）负责从 config 读取默认值并传入。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+/**
+ * 带重试逻辑执行异步函数
+ *
+ * 使用指数退避（2^attempt * baseDelay）+ 10% 随机抖动策略。
+ * 当所有重试耗尽后，抛出最后一次捕获的错误。
+ */
+async function withRetry(fn, options) {
+    const { maxRetries, baseDelay, maxDelay, onRetry } = options;
+    const safeMaxRetries = Math.max(0, maxRetries);
+    let lastError;
+    for (let attempt = 0; attempt <= safeMaxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt === safeMaxRetries) {
+                break;
+            }
+            const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+            const jitter = delay * 0.1 * Math.random();
+            const actualDelay = delay + jitter;
+            onRetry?.(attempt + 1, safeMaxRetries, lastError, actualDelay);
+            await sleep(actualDelay);
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/infra/retry/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 重试模块类型定义
+ */
+/** 重试配置选项（所有字段必填，由调用方从 config 传入） */
+export interface RetryOptions {
+    /** 最大重试次数（0 = 不重试） */
+    maxRetries: number;
+    /** 首次重试基础延迟（毫秒） */
+    baseDelay: number;
+    /** 重试最大延迟上限（毫秒） */
+    maxDelay: number;
+    /** 重试时回调，用于日志输出（可选） */
+    onRetry?: (attempt: number, maxRetries: number, error: Error, delay: number) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/infra/retry/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * 重试模块类型定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v2er-insight",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "",
   "main": "./dist/cli/index.js",
   "bin": {