v2er-insight 1.0.0

package/README.md

@@ -0,0 +1,215 @@
+# V2ER Insight
+
+V2EX 用户画像深度分析工具。通过自动化抓取数据、统计解析及 AI 语言模型建模，构建多维度的用户行为与心理画像。
+
+## 核心流程 (Pipe Flow)
+
+本项目采用管道化设计，目前通过以下步骤逐步生成深度报告：
+**Fetch** (抓取) → **Analyze** (统计) → **AI** (建模) → **Show** (展示)
+
+## 快速开始
+
+按顺序完成以下步骤：
+
+1. 安装 CLI 包
+
+```bash
+npm install -g v2er-insight
+# 或
+pnpm add -g v2er-insight
+```
+
+2. 配置 Gemini API Key
+
+```bash
+v2er config set ai.apiKey <your_gemini_api_key>
+```
+
+3. 设置代理（可选，建议在受限网络下启用）
+
+```bash
+v2er config proxy http://127.0.0.1:7890
+```
+
+4. 执行一键分析
+
+```bash
+v2er <username>
+```
+
+## CLI 命令
+
+### 一键分析（推荐）
+
+从零到报告，一条命令完成全流程：
+
+```bash
+v2er <username>
+```
+
+| 选项                       | 说明                                                               |
+| -------------------------- | ------------------------------------------------------------------ |
+| `--force`                  | 强制重新抓取（忽略本地缓存）                                       |
+| `--model [name]`           | 指定 AI 模型（默认: `gemini-3-pro-preview`）                       |
+| `--thinking-level [level]` | 指定思考等级（默认: `high`，可选 `minimal`/`low`/`medium`/`high`） |
+| `-v, --verbose`            | 显示调试输出                                                       |
+
+智能跳过：管道执行时，若 `raw.json` 已存在则跳过抓取步骤（analyze 和 ai 每次重新执行）。`--force` 忽略缓存从头开始。
+
+---
+
+### 分步执行
+
+### 1. 数据抓取 (Fetch)
+
+抓取指定用户的个人资料、帖子内容及所有回复。
+
+```bash
+v2er fetch <username> [选项]
+```
+
+| 选项        | 说明                                  |
+| ----------- | ------------------------------------- |
+| `--topics`  | 仅抓取话题                            |
+| `--replies` | 仅抓取回复                            |
+| `--force`   | 强制重新抓取（忽略本地 `.json` 缓存） |
+
+### 2. 统计分析 (Analyze)
+
+对抓取的原始数据进行加工，计算活跃周期、发帖频率、节点分布等指标。
+
+- 分析结果文档定义：[docs/analyzer-output/output-schema.md](docs/analyzer-output/output-schema.md)
+
+```bash
+v2er analyze <username>
+```
+
+### 3. AI 画像建模 (AI)
+
+目前仅支持 **Google Gemini** 服务。
+调用 AI 模型，基于统计结果进行多维度心理、行为及社交建模，生成分析报告。
+
+- 核心提示词所在位置：[docs/prompt.md](docs/prompt.md)
+- 分析维度详细说明：[docs/ai-result/result-schema.md](docs/ai-result/result-schema.md)
+
+```bash
+v2er ai <username> [选项]
+```
+
+| 选项                       | 说明                                                               |
+| -------------------------- | ------------------------------------------------------------------ |
+| `--model [name]`           | 指定 Gemini 模型（默认: `gemini-3-pro-preview`）                   |
+| `--thinking-level [level]` | 指定思考等级（默认: `high`，可选 `minimal`/`low`/`medium`/`high`） |
+
+### 4. 报告展示 (Show)
+
+以结构化的格式展示最终的分析报告，包含 OCEAN 五维性格雷达图（字符模拟）。
+
+```bash
+v2er show <username> [选项]
+```
+
+| 选项      | 说明                           |
+| --------- | ------------------------------ |
+| `--brief` | 简略版输出（仅摘要及核心指标） |
+| `--json`  | 输出 AI 返回的原始 JSON 数据   |
+
+### 5. 配置管理 (Config)
+
+- **group**: 配置分组名，可选 `ai`、`fetch`、`analyzer`、`data`、`log`、`proxy`
+- **path**: 点分路径，如 `ai.model`、`log.level`、`data.keepRaw`
+- **value**: 配置值，自动进行类型转换（字符串/数字/布尔）和枚举校验
+
+```bash
+# 查看
+v2er config show                            # 查看全部配置（apiKey 自动掩码）
+v2er config show ai                         # 查看 ai 分组
+
+# 设置
+v2er config set ai.model gemini-2.5-flash   # 切换模型
+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 reset                           # 重置全部为默认值
+v2er config reset ai                        # 仅重置 ai 分组
+
+# 代理快捷方式
+v2er config proxy http://127.0.0.1:7890     # 设置代理
+v2er config proxy                           # 查看代理
+v2er config proxy --clear                   # 清除代理
+```
+
+---
+
+## 详细配置说明
+
+配置文件位于 `~/.v2er-insight/config.json`，可通过 `v2er config set` 或手动编辑。
+
+### 1. API Key 解析顺序
+
+AI 模块通过以下优先级依次尝试读取 Gemini API Key：
+
+- `~/.v2er-insight/config.json` 中的 `ai.apiKey` 字段
+- 环境变量 `GOOGLE_API_KEY`
+- 环境变量 `GEMINI_API_KEY`
+
+### 2. 代理读取逻辑 (Proxy)
+
+程序按以下优先级确定请求使用的代理（Fetcher 和 AI 模块共用同一优先级）：
+
+1. 配置文件 (`~/.v2er-insight/config.json`) 中的 `proxy` 字段
+2. 系统环境变量 `HTTPS_PROXY`
+3. 系统环境变量 `HTTP_PROXY`
+
+若以上均未配置，则尝试直接连接。
+
+### 3. 参数优先级与默认值来源
+
+配置解析关系：显式参数 > `~/.v2er-insight/config.json` > [src/config/defaults.ts](src/config/defaults.ts)（特例：`proxy` / `apiKey` 还会读取环境变量）。
+
+### 4. 技术实现细节
+
+- 日志系统：采用级别过滤（Error/Warn/Info/Debug），支持带进度的章节式输出。
+- 代理驱动（双通道）：
+  - **Fetcher**（V2EX 数据抓取）：`https-proxy-agent` + Axios `httpsAgent`
+  - **AI**（Gemini API 调用）：`undici` `ProxyAgent` + `setGlobalDispatcher`（原生 `fetch()` 代理）
+- 数据本地化：数据存储于 `~/.v2er-insight/data/{username}/` 下。
+- 环境要求：Node.js >= 20.18.1（undici 7.x 要求）。
+
+---
+
+## 开发
+
+### 安装与构建
+
+```bash
+pnpm install
+pnpm run build
+```
+
+### 开发模式（直接运行源码）
+
+```bash
+npx ts-node -r tsconfig-paths/register src/cli/index.ts <command> <username>
+```
+
+### 质量检查
+
+```bash
+pnpm run check:types    # TypeScript 类型检查
+pnpm run lint           # ESLint 代码规范
+pnpm run test           # Vitest 单元测试（单次）
+pnpm run dev            # Vitest 监听模式
+pnpm run ci             # 完整 CI（类型 + lint + 格式 + 测试）
+```
+
+---
+
+### 安全与隐私
+
+- 文件权限：在 Linux/Mac 系统上，程序创建的配置文件权限为 `0600`（仅当前用户读写）。
+- 隐私保护：建议避免在配置文件中直接存储包含明文凭据的代理 URL。
+- Windows 用户建议：手动检查 `~/.v2er-insight/config.json` 的访问控制列表 (ACL)，确保其安全性。

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

@@ -0,0 +1,13 @@
+/**
+ * ai 命令 — 调用 AI 分析用户数据
+ *
+ * 读取 analyzed.json，构建多轮对话消息序列，
+ * 通过 GeminiProvider 发送至 AI，解析响应后写入 result.json。
+ */
+import type { AiCommandOptions } from '../types';
+import type { StepRunResult } from '../workflow/types';
+/**
+ * 执行 ai 命令
+ */
+export declare function runAi(username: string, options: AiCommandOptions): Promise<StepRunResult>;
+//# sourceMappingURL=ai.d.ts.map

package/dist/cli/commands/ai.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * ai 命令 — 调用 AI 分析用户数据
+ *
+ * 读取 analyzed.json，构建多轮对话消息序列，
+ * 通过 GeminiProvider 发送至 AI，解析响应后写入 result.json。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAi = runAi;
+const ai_1 = require("../../core/ai");
+const config_1 = require("../../config");
+const storage_1 = require("../../infra/storage");
+const logger_1 = require("../../infra/logger");
+const recovery_1 = require("../workflow/recovery");
+const error_1 = require("../utils/error");
+/**
+ * 执行 ai 命令
+ */
+async function runAi(username, options) {
+    // 读取分析数据
+    const analyzed = (0, storage_1.readDataFile)(username, 'analyzed');
+    if (!analyzed) {
+        logger_1.logger.error(`未找到 ${username} 的分析数据`);
+        logger_1.logger.info('请先运行: v2er analyze <username>');
+        return {
+            step: 'ai',
+            status: 'failed',
+            reasonCode: 'AI_INPUT_MISSING',
+            message: '缺少 analyzed.json，无法执行 AI 分析',
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('AI_INPUT_MISSING', { username }),
+        };
+    }
+    // 解析 API Key
+    const apiKey = (0, ai_1.resolveApiKey)();
+    if (!apiKey) {
+        logger_1.logger.error('未找到 API Key');
+        logger_1.logger.info('请通过以下方式之一配置:');
+        logger_1.logger.detail('1. 环境变量: GOOGLE_API_KEY 或 GEMINI_API_KEY');
+        logger_1.logger.detail('2. 配置文件: v2er config ai.apiKey <key>');
+        return {
+            step: 'ai',
+            status: 'failed',
+            reasonCode: 'AI_API_KEY_MISSING',
+            message: '缺少 API Key，无法发起 AI 请求',
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('AI_API_KEY_MISSING', { username }),
+        };
+    }
+    const config = (0, config_1.getConfig)();
+    // Commander 将 --model [name] 无值时解析为 true；
+    // 字符串时直接使用，否则回退到配置/默认值（后续支持交互选择时替换此逻辑）
+    const model = typeof options.model === 'string'
+        ? options.model
+        : (config.ai?.model ?? 'gemini-3-pro-preview');
+    // 同上：--thinking-level [level] 无值时为 true，字符串时直接使用
+    const rawThinkingLevel = typeof options.thinkingLevel === 'string' ? options.thinkingLevel : config.ai?.thinkingLevel;
+    // 校验 thinkingLevel 合法性
+    if (rawThinkingLevel && !config_1.THINKING_LEVELS.includes(rawThinkingLevel)) {
+        logger_1.logger.error(`无效的思考等级: "${rawThinkingLevel}"`);
+        logger_1.logger.info(`可选值: ${config_1.THINKING_LEVELS.join(' | ')}`);
+        return {
+            step: 'ai',
+            status: 'failed',
+            reasonCode: 'AI_INVALID_THINKING_LEVEL',
+            message: `无效的 thinkingLevel: ${rawThinkingLevel}`,
+            recoverable: false,
+            recoverActions: (0, recovery_1.getRecoveryActions)('AI_INVALID_THINKING_LEVEL', { username }),
+        };
+    }
+    // 注意：先完成上方白名单校验，再使用该类型断言。
+    // TODO: 使用 type guard 替换断言式收窄 [2026-02-18]
+    const thinkingLevel = rawThinkingLevel;
+    logger_1.logger.info(`\nAI 分析: ${username} (模型: ${model})`);
+    if (thinkingLevel) {
+        logger_1.logger.detail(`思考等级: ${thinkingLevel}`);
+    }
+    // 构建消息序列
+    const sequence = (0, ai_1.buildMessageSequence)(analyzed);
+    const totalMessages = sequence.messages.length + 1; // +1 for finalPrompt
+    // 创建 Provider
+    const provider = new ai_1.GeminiProvider(apiKey, model);
+    const retryOptions = {
+        maxRetries: config.ai?.maxRetries,
+        baseDelay: config.ai?.baseDelay,
+        maxDelay: config.ai?.maxDelay,
+    };
+    try {
+        // 初始化会话
+        await provider.createSession(sequence.systemPrompt, {
+            thinkingLevel,
+            timeout: config.ai?.timeout,
+        });
+        // 逐条发送数据消息
+        logger_1.logger.section('发送数据至 AI...');
+        let messageIndex = 0;
+        for (const message of sequence.messages) {
+            logger_1.logger.progress(messageIndex, totalMessages, '发送消息');
+            await (0, ai_1.withRetry)(() => provider.sendMessage(message), retryOptions);
+            messageIndex++;
+        }
+        // 发送最终分析请求
+        logger_1.logger.progress(sequence.messages.length, totalMessages, '请求分析');
+        const rawResponse = await (0, ai_1.withRetry)(() => provider.sendMessage(sequence.finalPrompt), retryOptions);
+        // 解析响应
+        const { data: result, warnings } = (0, ai_1.parseResponse)(rawResponse);
+        if (warnings.length > 0) {
+            logger_1.logger.section('AI 响应警告:');
+            for (const warning of warnings) {
+                logger_1.logger.warn(`  ${warning}`);
+            }
+        }
+        // 持久化结果
+        (0, storage_1.writeDataFile)(username, 'result', result);
+        // 清理过期中间数据
+        const cleaned = (0, storage_1.cleanExpiredData)(username);
+        if (!options.pipeline) {
+            logger_1.logger.success('分析结果已保存');
+            if (cleaned.length > 0) {
+                logger_1.logger.detail(`已清理中间数据: ${cleaned.join(', ')}`);
+            }
+        }
+        return {
+            step: 'ai',
+            status: 'success',
+            message: 'AI 分析完成',
+            meta: {
+                model,
+                warningCount: warnings.length,
+                cleanedFiles: cleaned,
+            },
+        };
+    }
+    catch (error) {
+        const { message, raw } = (0, error_1.extractErrorDetails)(error);
+        if (!options.pipeline) {
+            logger_1.logger.error(`AI 分析失败: ${message}`);
+            logger_1.logger.debug(raw);
+        }
+        return {
+            step: 'ai',
+            status: 'failed',
+            reasonCode: 'AI_PROVIDER_FAILED',
+            message: `AI 分析失败: ${message}`,
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('AI_PROVIDER_FAILED', { username }),
+            meta: {
+                rawError: raw,
+            },
+        };
+    }
+}
+//# sourceMappingURL=ai.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * analyze 命令 — 分析已抓取的用户数据
+ *
+ * 读取 raw.json，执行 Analyzer，输出 analyzed.json。
+ */
+import type { StepRunResult } from '../workflow/types';
+/**
+ * 执行 analyze 命令
+ */
+export declare function runAnalyze(username: string, options?: {
+    pipeline?: boolean;
+}): Promise<StepRunResult>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/cli/commands/analyze.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * analyze 命令 — 分析已抓取的用户数据
+ *
+ * 读取 raw.json，执行 Analyzer，输出 analyzed.json。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAnalyze = runAnalyze;
+const analyzer_1 = require("../../core/analyzer");
+const storage_1 = require("../../infra/storage");
+const logger_1 = require("../../infra/logger");
+const recovery_1 = require("../workflow/recovery");
+/**
+ * 打印分析统计摘要
+ */
+function printStats(output) {
+    const { userOverview, summary } = output;
+    logger_1.logger.section('=== 分析摘要 ===');
+    logger_1.logger.detail(`注册时间: ${userOverview.joinDate}`);
+    logger_1.logger.detail(`最后活跃: ${userOverview.lastActiveTime}`);
+    if (userOverview.totalTopics !== null) {
+        logger_1.logger.detail(`帖子总数: ${userOverview.totalTopics}`);
+    }
+    logger_1.logger.detail(`回复总数: ${userOverview.totalReplies}`);
+    if (userOverview.topicReplyRatio !== null) {
+        logger_1.logger.detail(`帖/回比: ${userOverview.topicReplyRatio.toFixed(2)}`);
+    }
+    logger_1.logger.detail(`活跃期数: ${summary.totalPeriods}`);
+    logger_1.logger.detail(`内容分片: ${output.contents.length}`);
+}
+/**
+ * 执行 analyze 命令
+ */
+async function runAnalyze(username, options = {}) {
+    // 读取原始数据
+    const rawData = (0, storage_1.readDataFile)(username, 'raw');
+    if (!rawData) {
+        logger_1.logger.error(`未找到 ${username} 的抓取数据`);
+        logger_1.logger.info('请先运行: v2er fetch <username>');
+        return {
+            step: 'analyze',
+            status: 'failed',
+            reasonCode: 'ANALYZE_INPUT_MISSING',
+            message: '缺少 raw.json，无法执行分析',
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('ANALYZE_INPUT_MISSING', { username }),
+        };
+    }
+    logger_1.logger.info(`\n分析用户数据: ${username}`);
+    try {
+        const output = (0, analyzer_1.buildAnalyzerOutput)(rawData);
+        (0, storage_1.writeDataFile)(username, 'analyzed', output);
+        if (!options.pipeline) {
+            logger_1.logger.success('分析结果已保存');
+            printStats(output);
+        }
+        return {
+            step: 'analyze',
+            status: 'success',
+            message: '分析完成',
+            meta: {
+                totalPeriods: output.summary.totalPeriods,
+                contentChunks: output.contents.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger_1.logger.error(`分析失败: ${message}`);
+        return {
+            step: 'analyze',
+            status: 'failed',
+            reasonCode: 'ANALYZE_FAILED',
+            message: `分析失败: ${message}`,
+            recoverable: true,
+            recoverActions: (0, recovery_1.getRecoveryActions)('ANALYZE_FAILED', { username }),
+        };
+    }
+}
+//# sourceMappingURL=analyze.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * config 命令
+ *
+ * 提供配置的查看、设置和代理管理功能。
+ * 所有配置持久化到 ~/.v2er-insight/config.json。
+ */
+interface ConfigProxyOptions {
+    clear?: boolean;
+}
+/**
+ * 代理配置命令
+ */
+export declare function configProxy(url?: string, options?: ConfigProxyOptions): void;
+/**
+ * 查看配置
+ *
+ * 无参数显示完整配置，传 group 显示指定分组。
+ */
+export declare function configShow(group?: string): void;
+/**
+ * 设置配置项
+ *
+ * 支持点分路径，自动类型转换和枚举校验。
+ *
+ * 示例：
+ *   configSet('ai.model', 'gemini-2.5-flash')
+ *   configSet('data.keepRaw', 'true')
+ *   configSet('log.level', 'debug')
+ */
+export declare function configSet(dotPath: string, rawValue: string): void;
+/**
+ * 重置配置
+ *
+ * 无参数清空整个配置文件（恢复全部默认值）。
+ * 传 group 只清除指定分组。
+ *
+ * 示例：
+ *   configReset()         → 清空所有用户配置
+ *   configReset('ai')     → 仅清除 ai 分组
+ */
+export declare function configReset(group?: string): void;
+export {};
+//# sourceMappingURL=config.d.ts.map