v2er-insight 1.0.0

package/dist/cli/commands/config.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * config 命令
+ *
+ * 提供配置的查看、设置和代理管理功能。
+ * 所有配置持久化到 ~/.v2er-insight/config.json。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configProxy = configProxy;
+exports.configShow = configShow;
+exports.configSet = configSet;
+exports.configReset = configReset;
+const config_1 = require("../../config");
+const logger_1 = require("../../infra/logger");
+/**
+ * 合法配置路径白名单
+ *
+ * 作用：
+ * 1. 校验用户输入的 dotpath 是否合法
+ * 2. 自动推断值类型并做类型转换
+ * 3. 枚举路径做候选值校验
+ */
+// NOTE: 枚举 values 与类型定义（ThinkingLevel、LogLevel 等）存在耦合，新增枚举值时需同步更新。
+// 未来可考虑从类型定义中统一导出枚举值以减少维护负担。
+const CONFIG_PATHS = {
+    // 顶层
+    proxy: { type: 'string' },
+    // AI
+    'ai.provider': { type: 'enum', values: ['gemini'] },
+    'ai.apiKey': { type: 'string' },
+    'ai.model': { type: 'string' },
+    'ai.thinkingLevel': { type: 'enum', values: ['minimal', 'low', 'medium', 'high'] },
+    'ai.timeout': { type: 'number' },
+    'ai.maxRetries': { type: 'number' },
+    'ai.baseDelay': { type: 'number' },
+    'ai.maxDelay': { type: 'number' },
+    // Fetch
+    'fetch.timeout': { type: 'number' },
+    // Analyzer
+    'analyzer.inactivityThreshold': { type: 'number' },
+    'analyzer.chunkMaxTopics': { type: 'number' },
+    'analyzer.chunkMaxReplies': { type: 'number' },
+    'analyzer.nodeDistributionTopN': { type: 'number' },
+    // Data
+    'data.keepRaw': { type: 'boolean' },
+    'data.rawRetention': { type: 'number' },
+    // Log
+    'log.level': { type: 'enum', values: ['error', 'warn', 'info', 'debug'] },
+};
+/** 所有合法的顶层分组名 */
+const CONFIG_GROUPS = ['ai', 'fetch', 'analyzer', 'data', 'log'];
+// -- 工具函数 -----------------------------------------------------------------
+/**
+ * 掩码敏感字段（如 apiKey）
+ *
+ * 保留前 4 位和后 4 位，中间用 **** 替代。
+ * 长度不足 8 位时全部掩码。
+ */
+function maskSensitive(value) {
+    if (value.length <= 8)
+        return '****';
+    return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+/**
+ * 格式化配置值用于显示
+ *
+ * 对 apiKey 字段做掩码处理，其余原样输出。
+ */
+// NOTE: 目前仅 ai.apiKey 需要掩码。若新增其他敏感字段，考虑用元数据驱动替代硬编码。
+function formatConfigForDisplay(config) {
+    const display = JSON.parse(JSON.stringify(config));
+    if (display.ai?.apiKey) {
+        display.ai.apiKey = maskSensitive(display.ai.apiKey);
+    }
+    return display;
+}
+/**
+ * 将字符串值按目标类型转换
+ */
+function coerceValue(raw, meta) {
+    switch (meta.type) {
+        case 'boolean':
+            if (raw === 'true')
+                return true;
+            if (raw === 'false')
+                return false;
+            throw new Error(`Invalid boolean value: "${raw}" (expected: true | false)`);
+        case 'number': {
+            const num = Number(raw);
+            if (raw.trim() === '' || !Number.isFinite(num) || num < 0) {
+                throw new Error(`Invalid number value: "${raw}" (expected non-negative finite number)`);
+            }
+            return num;
+        }
+        case 'enum':
+            if (!meta.values?.includes(raw)) {
+                throw new Error(`Invalid value: "${raw}" (expected: ${meta.values?.join(' | ')})`);
+            }
+            return raw;
+        case 'string':
+        default:
+            return raw;
+    }
+}
+/**
+ * 按点分路径设置深层值
+ *
+ * 例如 setByPath(obj, 'ai.model', 'gemini-2.5-flash')
+ * → obj.ai.model = 'gemini-2.5-flash'
+ */
+function setByPath(obj, dotPath, value) {
+    const parts = dotPath.split('.');
+    // 顶层字段直接设置
+    if (parts.length === 1) {
+        obj[parts[0]] = value;
+        return;
+    }
+    // 嵌套字段：确保中间对象存在
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (typeof current[key] !== 'object' || current[key] === null) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/**
+ * 代理配置命令
+ */
+function configProxy(url, options) {
+    const config = (0, config_1.readConfig)();
+    // 清除代理
+    if (options?.clear) {
+        delete config.proxy;
+        (0, config_1.writeConfig)(config);
+        logger_1.logger.info('Proxy cleared');
+        return;
+    }
+    // 设置代理
+    if (url) {
+        config.proxy = url;
+        (0, config_1.writeConfig)(config);
+        logger_1.logger.info(`Proxy set to: ${url}`);
+        logger_1.logger.detail(`Config file: ${(0, config_1.getConfigPath)()}`);
+        return;
+    }
+    // 查看代理
+    if (config.proxy) {
+        logger_1.logger.info(`Current proxy: ${config.proxy}`);
+    }
+    else {
+        logger_1.logger.info('No proxy configured');
+        logger_1.logger.detail('Use: v2er config proxy <url>');
+    }
+}
+/**
+ * 查看配置
+ *
+ * 无参数显示完整配置，传 group 显示指定分组。
+ */
+function configShow(group) {
+    const config = (0, config_1.getConfig)();
+    const display = formatConfigForDisplay(config);
+    // 指定分组
+    if (group) {
+        // proxy 作为特殊的顶层字段
+        if (group === 'proxy') {
+            if (display.proxy) {
+                logger_1.logger.info(`[proxy] ${display.proxy}`);
+            }
+            else {
+                logger_1.logger.info('[proxy] (not set)');
+            }
+            return;
+        }
+        if (!CONFIG_GROUPS.includes(group)) {
+            logger_1.logger.error(`Unknown config group: "${group}"`);
+            logger_1.logger.detail(`Available groups: proxy, ${CONFIG_GROUPS.join(', ')}`);
+            return;
+        }
+        const groupConfig = display[group];
+        logger_1.logger.info(`[${group}]`);
+        console.log(JSON.stringify(groupConfig, null, 2));
+        return;
+    }
+    // 全量显示
+    console.log(JSON.stringify(display, null, 2));
+    logger_1.logger.detail(`\nConfig file: ${(0, config_1.getConfigPath)()}`);
+}
+/**
+ * 设置配置项
+ *
+ * 支持点分路径，自动类型转换和枚举校验。
+ *
+ * 示例：
+ *   configSet('ai.model', 'gemini-2.5-flash')
+ *   configSet('data.keepRaw', 'true')
+ *   configSet('log.level', 'debug')
+ */
+function configSet(dotPath, rawValue) {
+    // 路径白名单校验
+    const meta = CONFIG_PATHS[dotPath];
+    if (!meta) {
+        logger_1.logger.error(`Unknown config path: "${dotPath}"`);
+        logger_1.logger.detail('Available paths:');
+        for (const path of Object.keys(CONFIG_PATHS)) {
+            logger_1.logger.detail(`  ${path}`);
+        }
+        return;
+    }
+    // 类型转换 + 枚举校验
+    let value;
+    try {
+        value = coerceValue(rawValue, meta);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger_1.logger.error(message);
+        return;
+    }
+    // 读取 → 设置 → 写入
+    const config = (0, config_1.readConfig)();
+    setByPath(config, dotPath, value);
+    (0, config_1.writeConfig)(config);
+    // 敏感值掩码显示
+    const displayValue = dotPath.endsWith('apiKey') ? maskSensitive(String(value)) : String(value);
+    logger_1.logger.info(`Set ${dotPath} = ${displayValue}`);
+}
+/**
+ * 重置配置
+ *
+ * 无参数清空整个配置文件（恢复全部默认值）。
+ * 传 group 只清除指定分组。
+ *
+ * 示例：
+ *   configReset()         → 清空所有用户配置
+ *   configReset('ai')     → 仅清除 ai 分组
+ */
+function configReset(group) {
+    // 指定分组
+    if (group) {
+        // 支持 proxy 作为特殊的顶层字段
+        if (group === 'proxy') {
+            const config = (0, config_1.readConfig)();
+            delete config.proxy;
+            (0, config_1.writeConfig)(config);
+            logger_1.logger.info('Reset: proxy');
+            return;
+        }
+        if (!CONFIG_GROUPS.includes(group)) {
+            logger_1.logger.error(`Unknown config group: "${group}"`);
+            logger_1.logger.detail(`Available groups: proxy, ${CONFIG_GROUPS.join(', ')}`);
+            return;
+        }
+        const config = (0, config_1.readConfig)();
+        delete config[group];
+        (0, config_1.writeConfig)(config);
+        logger_1.logger.info(`Reset: ${group}`);
+        return;
+    }
+    // 全部清空
+    (0, config_1.writeConfig)({});
+    logger_1.logger.info('All configuration reset to defaults');
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/commands/fetch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * fetch 命令 — 抓取 V2EX 用户数据并持久化
+ *
+ * 调用 V2EX use-cases 获取 profile + topics detail + replies，
+ * 组装为 RawUserData 结构后写入 raw.json。
+ */
+import type { StepRunResult } from '../workflow/types';
+import type { FetchCommandOptions } from '../types';
+/**
+ * 执行 fetch 命令
+ */
+export declare function runFetch(username: string, options: FetchCommandOptions): Promise<StepRunResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/cli/commands/fetch.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * fetch 命令 — 抓取 V2EX 用户数据并持久化
+ *
+ * 调用 V2EX use-cases 获取 profile + topics detail + replies，
+ * 组装为 RawUserData 结构后写入 raw.json。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFetch = runFetch;
+const v2ex_1 = require("../../core/v2ex");
+const storage_1 = require("../../infra/storage");
+const logger_1 = require("../../infra/logger");
+const recovery_1 = require("../workflow/recovery");
+const utils_1 = require("../utils");
+// -- 内部工具 ----------------------------------------------------------------
+/**
+ * 打印抓取摘要
+ */
+function printSummary(profileOk, topicsResult, replies) {
+    logger_1.logger.section('=== 抓取摘要 ===');
+    logger_1.logger.detail(`Profile: ${profileOk ? 'OK' : 'Failed'}`);
+    if (topicsResult) {
+        if (topicsResult.isHidden) {
+            logger_1.logger.detail('Topics: Hidden');
+        }
+        else {
+            const failed = topicsResult.failedTopics > 0 ? ` (${topicsResult.failedTopics} failed)` : '';
+            logger_1.logger.detail(`Topics: ${topicsResult.fetchedTopics}/${topicsResult.totalTopics}${failed}`);
+        }
+    }
+    if (replies) {
+        const failed = replies.failedPages > 0 ? ` (${replies.failedPages} failed)` : '';
+        logger_1.logger.detail(`Replies: ${replies.data.length}${failed}`);
+    }
+}
+// -- 命令入口 ----------------------------------------------------------------
+/**
+ * 执行 fetch 命令
+ */
+async function runFetch(username, options) {
+    // 缓存检查
+    if (!options.force) {
+        const existing = (0, storage_1.readDataFile)(username, 'raw');
+        if (existing) {
+            logger_1.logger.info(`已存在 ${username} 的抓取数据，使用 --force 强制重新抓取`);
+            return {
+                step: 'fetch',
+                status: 'skipped',
+                message: 'raw.json 已存在，跳过抓取',
+            };
+        }
+    }
+    logger_1.logger.info(`\n抓取用户数据: ${username}`);
+    // 默认两者都抓取，除非显式指定了其中之一
+    const fetchTopics = options.topics || !options.replies;
+    const fetchReplies = options.replies || !options.topics;
+    let profile = null;
+    let topicsResult = null;
+    let replies = null;
+    // 1. 获取用户资料
+    logger_1.logger.section('获取用户资料...');
+    profile = await (0, v2ex_1.getUserProfile)(username, {
+        events: (0, utils_1.createFetchEvents)('获取资料'),
+    });
+    if (profile) {
+        logger_1.logger.success(`注册于 ${profile.joinDate}`);
+        if (profile.dailyRanking) {
+            logger_1.logger.detail(`活跃排名: #${profile.dailyRanking}`);
+        }
+    }
+    else {
+        logger_1.logger.error('获取用户资料失败');
+        return {
+            step: 'fetch',
+            status: 'failed',
+            reasonCode: 'FETCH_PROFILE_FAILED',
+            message: '获取用户资料失败',
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('FETCH_PROFILE_FAILED', { username }),
+        };
+    }
+    // 2. 获取帖子详情
+    if (fetchTopics) {
+        logger_1.logger.section('获取帖子详情...');
+        topicsResult = await (0, v2ex_1.getAllUserTopicsDetail)(username, {
+            events: (0, utils_1.createFetchEvents)('获取帖子'),
+        });
+        if (topicsResult.isHidden) {
+            logger_1.logger.detail('帖子列表被用户隐藏');
+        }
+        else {
+            logger_1.logger.success(`${topicsResult.fetchedTopics} 篇帖子`);
+            if (topicsResult.failedTopics > 0) {
+                logger_1.logger.detail(`(${topicsResult.failedTopics} 篇获取失败)`);
+            }
+        }
+    }
+    // 3. 获取回复
+    if (fetchReplies) {
+        logger_1.logger.section('获取回复...');
+        replies = await (0, v2ex_1.getAllUserReplies)(username, {
+            events: (0, utils_1.createFetchEvents)('获取回复'),
+        });
+        logger_1.logger.success(`${replies.data.length} 条回复`);
+        if (replies.failedPages > 0) {
+            logger_1.logger.detail(`(${replies.failedPages} 页获取失败)`);
+        }
+    }
+    // 4. 组装 RawUserData 并持久化
+    const rawData = {
+        profile,
+        topics: topicsResult?.topics ?? [],
+        replies: replies?.data ?? [],
+        isTopicsHidden: topicsResult?.isHidden ?? false,
+    };
+    (0, storage_1.writeDataFile)(username, 'raw', rawData);
+    if (!options.pipeline) {
+        logger_1.logger.success('数据已保存');
+        printSummary(!!profile, topicsResult, replies);
+    }
+    const failedTopics = topicsResult?.failedTopics ?? 0;
+    const failedPages = replies?.failedPages ?? 0;
+    const isPartial = failedTopics > 0 || failedPages > 0;
+    if (isPartial) {
+        return {
+            step: 'fetch',
+            status: 'partial',
+            reasonCode: 'FETCH_PARTIAL_FAILED',
+            message: '抓取已完成，但存在部分页面失败',
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('FETCH_PARTIAL_FAILED', { username }),
+            meta: {
+                failedTopics,
+                failedPages,
+                // TODO(ia319): 在实现 --retry 后补充真实失败页索引 [2026-02-14]
+                failedPageIndices: [],
+            },
+        };
+    }
+    return {
+        step: 'fetch',
+        status: 'success',
+        message: '抓取完成',
+        meta: {
+            fetchedTopics: topicsResult?.fetchedTopics ?? 0,
+            fetchedReplies: replies?.data.length ?? 0,
+        },
+    };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI 命令导出
+ */
+export { runFetch } from './fetch';
+export { runAnalyze } from './analyze';
+export { runAi } from './ai';
+export { runShow } from './show';
+export { runPipeline } from './run';
+export { configProxy, configShow, configSet, configReset } from './config';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * CLI 命令导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configReset = exports.configSet = exports.configShow = exports.configProxy = exports.runPipeline = exports.runShow = exports.runAi = exports.runAnalyze = exports.runFetch = void 0;
+var fetch_1 = require("./fetch");
+Object.defineProperty(exports, "runFetch", { enumerable: true, get: function () { return fetch_1.runFetch; } });
+var analyze_1 = require("./analyze");
+Object.defineProperty(exports, "runAnalyze", { enumerable: true, get: function () { return analyze_1.runAnalyze; } });
+var ai_1 = require("./ai");
+Object.defineProperty(exports, "runAi", { enumerable: true, get: function () { return ai_1.runAi; } });
+var show_1 = require("./show");
+Object.defineProperty(exports, "runShow", { enumerable: true, get: function () { return show_1.runShow; } });
+var run_1 = require("./run");
+Object.defineProperty(exports, "runPipeline", { enumerable: true, get: function () { return run_1.runPipeline; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "configProxy", { enumerable: true, get: function () { return config_1.configProxy; } });
+Object.defineProperty(exports, "configShow", { enumerable: true, get: function () { return config_1.configShow; } });
+Object.defineProperty(exports, "configSet", { enumerable: true, get: function () { return config_1.configSet; } });
+Object.defineProperty(exports, "configReset", { enumerable: true, get: function () { return config_1.configReset; } });
+//# sourceMappingURL=index.js.map

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 主命令 `v2er <username>` 入口
+ *
+ * 职责：
+ * 1. 将 Commander 解析的选项转换为 RunWorkflowOptions
+ * 2. 调用 orchestrator 执行一键工作流
+ * 3. 根据执行结果设置 process.exitCode
+ */
+import type { RunCommandOptions } from '../types';
+import type { RunWorkflowOptions } from '../workflow/types';
+/**
+ * 将 Commander 解析的 CLI 选项转化为 orchestrator 所需的类型安全选项。
+ *
+ * 处理 Commander optional value 的特殊行为：
+ * - `--model gemini-2.5-pro` → 直接透传字符串
+ * - `--model`（无值）→ Commander 设为 true，此处暂按 undefined 处理（Task 7 接入交互选择）
+ */
+export declare function resolveWorkflowOptions(username: string, options: RunCommandOptions): RunWorkflowOptions;
+/**
+ * `v2er <username>` 主命令执行入口，由 cli/index.ts 注册调用。
+ */
+export declare function runPipeline(username: string, options: RunCommandOptions): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * 主命令 `v2er <username>` 入口
+ *
+ * 职责：
+ * 1. 将 Commander 解析的选项转换为 RunWorkflowOptions
+ * 2. 调用 orchestrator 执行一键工作流
+ * 3. 根据执行结果设置 process.exitCode
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkflowOptions = resolveWorkflowOptions;
+exports.runPipeline = runPipeline;
+const logger_1 = require("../../infra/logger");
+const error_1 = require("../utils/error");
+const orchestrator_1 = require("../workflow/orchestrator");
+/**
+ * 将 Commander 解析的 CLI 选项转化为 orchestrator 所需的类型安全选项。
+ *
+ * 处理 Commander optional value 的特殊行为：
+ * - `--model gemini-2.5-pro` → 直接透传字符串
+ * - `--model`（无值）→ Commander 设为 true，此处暂按 undefined 处理（Task 7 接入交互选择）
+ */
+function resolveWorkflowOptions(username, options) {
+    const model = typeof options.model === 'string' ? options.model : undefined;
+    const thinkingLevel = typeof options.thinkingLevel === 'string' ? options.thinkingLevel : undefined;
+    return {
+        username,
+        force: options.force,
+        model,
+        thinkingLevel,
+        verbose: options.verbose,
+    };
+}
+/**
+ * `v2er <username>` 主命令执行入口，由 cli/index.ts 注册调用。
+ */
+async function runPipeline(username, options) {
+    try {
+        if (options.verbose) {
+            logger_1.logger.setLevel('debug');
+        }
+        const workflowOptions = resolveWorkflowOptions(username, options);
+        const outcome = await (0, orchestrator_1.runWorkflow)(workflowOptions);
+        process.exitCode = outcome.exitCode;
+    }
+    catch (error) {
+        const { message } = (0, error_1.extractErrorDetails)(error);
+        logger_1.logger.error(`工作流执行失败: ${message}`);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/commands/show.d.ts

@@ -0,0 +1,13 @@
+/**
+ * show 命令 — 展示 AI 分析结果
+ *
+ * 读取 result.json，以结构化格式输出到终端。
+ * 支持 --json 原始输出和 --brief 简略版。
+ */
+import type { ShowCommandOptions } from '../types';
+import type { StepRunResult } from '../workflow/types';
+/**
+ * 执行 show 命令
+ */
+export declare function runShow(username: string, options: ShowCommandOptions): Promise<StepRunResult>;
+//# sourceMappingURL=show.d.ts.map