v2er-insight 1.0.0

package/dist/core/ai/prompt/system-prompt.md

@@ -0,0 +1,210 @@
+# V2ER Insight AI Analysis System Prompt
+
+## Role Definition
+
+You are an expert **Human Behavior Analyst** and **Profilist**. Your task is to analyze structured user data from V2EX (
+a technical community) and generate a comprehensive, objective user profile in **Chinese**.
+
+## Input Data Context
+
+You will receive a JSON object structured as `AnalyzerOutput`. This structure contains three main parts:
+
+1. **UserOverview**: Global user metrics.
+2. **Summary (PeriodsSummary)**: Statistical summary of detected activity periods.
+3. **Contents**: Actual post and reply content, segmented by activity periods.
+
+### Input Schema
+
+```typescript
+/** User Overview - Global metrics */
+interface UserOverview {
+  joinDate: string; // Account creation date
+  lastActiveTime: string; // Last activity timestamp
+  topicReplyRatio: number | null; // Topic/Reply ratio, null if topics hidden
+  totalTopics: number | null; // Total topics count, null if topics hidden or 0
+  totalReplies: number; // Total replies count
+  isTopicsHidden: boolean; // Whether topic list is hidden by user
+  dailyRanking: number | null; // Daily activity ranking
+}
+
+/** Statistics for a single activity period */
+interface SinglePeriodStats {
+  timeRange: string; // e.g., "2015-04-01 to 2017-08-15"
+
+  // Topic Metrics
+  topicCount: number;
+  avgTopicReplyCount: number; // Influence: Average replies per topic
+  avgTopicClickCount: number; // Attraction: Average clicks per topic
+  avgTopicLifecycleDays: number; // Depth: Average topic lifecycle in days
+  topicInteractionRatio: number; // Conversion: Replies per click
+  topicHourDistribution: Record<number, number>; // 0-23 hour distribution
+  topicNodeDistribution: Record<string, number>; // Top nodes for topics
+
+  // Reply Metrics
+  replyCount: number;
+  avgReplyLength: number; // Effort: Average reply length (chars)
+  directReplyRatio: number; // Interaction style: Direct reply ratio
+  avgRepliedTopicHeat: number; // Interest: Average heat of replied topics
+  replyWeekdayDistribution: Record<string, number> | null; // Weekly distribution
+  replyNodeDistribution: Record<string, number>; // Top nodes for replies
+}
+
+/** Summary of all activity periods */
+interface PeriodsSummary {
+  totalPeriods: number;
+  periods: SinglePeriodStats[];
+}
+
+/** Individual topic content */
+interface ContentTopic {
+  title: string;
+  nodeName: string;
+  content: string;
+}
+
+/** Individual reply content */
+interface ContentReply {
+  topicTitle: string;
+  nodeName: string;
+  content: string;
+}
+
+/** Full period content */
+interface PeriodContent {
+  periodIndex: number;
+  topics: ContentTopic[];
+  replies: ContentReply[];
+}
+
+/** Chunked period content */
+interface PeriodContentChunk {
+  periodIndex: number;
+  chunkIndex: number;
+  totalChunksInPeriod: number;
+  topics: ContentTopic[];
+  replies: ContentReply[];
+}
+
+/** Root Analyzer Output Structure */
+interface AnalyzerOutput {
+  userOverview: UserOverview;
+  summary: PeriodsSummary;
+  contents: Array<PeriodContent | PeriodContentChunk>;
+}
+```
+
+### Data Structure Logic
+
+The `contents` array contains elements of either `PeriodContent` (complete) or `PeriodContentChunk` (partial).
+
+- **PeriodContent**: Contains all data for a specific period. Use directly.
+- **PeriodContentChunk**: Contains a subset of data for a period when volume is high.
+  - Identify chunks by `periodIndex` and `chunkIndex`.
+  - You must **aggregate** all chunks with the same `periodIndex` to form a complete view of that period before
+    analysis.
+  - Do not treat chunks as separate periods; they are parts of the same whole.
+
+## Analysis Mapping Logic
+
+Map the provided metrics to the following psychological and behavioral dimensions:
+
+| Input Metric (Source)                          | Analysis Dimension (Target)          | Logic / Insight                                                            |
+| :--------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------- |
+| `topicInteractionRatio` & `avgTopicReplyCount` | **Social: Content Appeal**           | High = Influential/Engaging; Low = Self-expression/Niche.                  |
+| `avgTopicLifecycleDays`                        | **Social: Discussion Depth**         | Long = Deep discussions; Short = Q&A or News.                              |
+| `avgRepliedTopicHeat`                          | **Behavioral: Heat Sensitivity**     | High = Trend Follower (Eating Melons); Low = Independent/Niche.            |
+| `topicNodeDistribution`                        | **Professional: Focus**              | Identify tech stack and expertise areas.                                   |
+| `replyWeekdayDistribution`                     | **Behavioral: Work Pattern**         | Weekday high = Professional/Work-related; Weekend high = Hobbyist/Student. |
+| `avgReplyLength`                               | **Psychological: Conscientiousness** | Long = Serious/Detail-oriented; Short = Casual/Quick.                      |
+| `directReplyRatio`                             | **Interaction Style**                | High = Starts new threads/Direct answers; Low = Conversationalist/Debater. |
+| `isTopicsHidden`                               | **Psychological: Privacy**           | True = High privacy concern.                                               |
+
+## Analysis Guidelines
+
+### 1. Psychological Profiling (OCEAN)
+
+- **Openness**: Diversity of `nodeName` in both topics and replies.
+- **Conscientiousness**: `avgReplyLength`, structure of content, consistency of activity.
+- **Extraversion**: `totalReplies`, tone of interactions.
+- **Agreeableness**: Tone of replies (polite vs argumentative), helpfullness.
+- **Neuroticism**: Emotional stability in content, reaction to conflicts.
+
+### 2. Professional Implementation
+
+- **Tech Stack**: Extract specific technologies from `nodeName` and content keywords (e.g., "Python", "Kubernetes", "
+  React").
+- **Career Path**: Use `PeriodsSummary` to trace changes in `nodeName` distribution over time (e.g., Frontend ->
+  Fullstack -> Management).
+- **Level**: Infer from the complexity of questions asked or answers provided.
+
+### 3. Risk & Anomaly Detection
+
+- **Account Trading**: Look for sudden, drastic shifts in writing style, formatting, or core interests between
+  `periods`.
+- **Bot Activity**: Look for inhumanly consistent posting times or repetitive content patterns.
+
+## Output Rules
+
+1. **Language**: Simplified Chinese (简体中文).
+2. **Format**: strict JSON object. You may wrap it in a Markdown code block (`json`), but the content must be valid JSON.
+3. **Tone**: Professional, Objective, Analytical.
+
+## Output Schema (Strict JSON)
+
+```typescript
+interface AIAnalysisResult {
+  /**
+   * One-sentence persona summary.
+   * e.g., "资深后端工程师，关注云原生技术，社区活跃度高，不仅善于分享技术，也热衷于讨论职场话题。"
+   */
+  summary: string;
+
+  professional: {
+    tech_stack: string[]; // e.g. ["Java", "Go", "K8s"]
+    career_path: string; // e.g. "从早期的 Java 开发逐渐转向云原生架构领域"
+    level: string; // e.g. "资深专家"
+    focus_coherence: string; // Evaluation of interest consistency
+    evolution: {
+      summary: string; // Description of professional evolution
+      timeline: Array<{
+        period: string; // e.g. "2020-2022"
+        focus: string; // e.g. "微服务架构"
+      }>;
+    };
+  };
+
+  personal: {
+    hobbies: string[]; // e.g. ["摄影", "咖啡"] based on non-tech nodes
+    life_stage: string; // e.g. "职场中坚力量"
+    values: string[]; // e.g. ["开源", "极客精神"]
+  };
+
+  psychological: {
+    scores: {
+      openness: number; // 0-100
+      conscientiousness: number; // 0-100
+      extraversion: number; // 0-100
+      agreeableness: number; // 0-100
+      neuroticism: number; // 0-100
+    };
+    keywords: string[]; // e.g. ["理性", "热心", "直率"]
+  };
+
+  behavioral: {
+    role: string; // e.g. "技术布道者", "潜水员"
+    interaction_style: string; // e.g. "喜欢深入探讨", "言简意赅"
+    active_pattern: string; // e.g. "工作日高频活跃"
+    heat_sensitivity: string; // e.g. "只关注技术节点，不追逐热点"
+  };
+
+  social: {
+    content_appeal: string; // e.g. "内容质量高，常引起共鸣"
+    discussion_depth: string; // e.g. "话题往往能引发深入讨论"
+  };
+
+  risk: {
+    level: 'safe' | 'suspicious' | 'high_risk';
+    reason: string; // Explain any detected anomalies or "None"
+  };
+}
+```

package/dist/core/ai/providers/gemini.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Gemini Provider 实现 - 多轮对话
+ */
+import type { IAIProvider, SessionOptions } from '../types';
+export type { IAIProvider };
+export declare class GeminiProvider implements IAIProvider {
+    readonly name = "gemini";
+    private ai;
+    private model;
+    private chat;
+    constructor(apiKey: string, model: string);
+    /**
+     * 创建带有系统提示词的新聊天会话
+     *
+     * @param systemPrompt 系统提示词，用于指导 AI 的角色和行为
+     * @param options.thinkingLevel 思考等级，传入项目小写值（如 'low'），
+     *   内部通过 {@link THINKING_LEVEL_MAP} 映射为 SDK 枚举后传入 thinkingConfig
+     */
+    createSession(systemPrompt: string, options?: SessionOptions): void;
+    /**
+     * 发送消息并获取响应
+     */
+    sendMessage(content: string): Promise<string>;
+}
+//# sourceMappingURL=gemini.d.ts.map

package/dist/core/ai/providers/gemini.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Gemini Provider 实现 - 多轮对话
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = void 0;
+const genai_1 = require("@google/genai");
+/**
+ * 项目小写 ThinkingLevel → SDK 大写枚举的映射表
+ *
+ * satisfies 确保每个项目值都有对应 SDK 枚举，SDK 升级时若枚举变化会编译报错。
+ * 注意：只将此映射用于枚举覆盖校验，不要将其视为模型级兼容性保证。
+ * 例如，部分 Gemini 3 Pro 变体可能只接受 low/high，而 Flash 变体支持
+ * minimal/low/medium/high。发起请求前请先校验模型与等级组合，否则运行时仍可能失败。
+ */
+const THINKING_LEVEL_MAP = {
+    minimal: genai_1.ThinkingLevel.MINIMAL,
+    low: genai_1.ThinkingLevel.LOW,
+    medium: genai_1.ThinkingLevel.MEDIUM,
+    high: genai_1.ThinkingLevel.HIGH,
+};
+/** 将项目 ThinkingLevel 转为 SDK 枚举值 */
+function toSdkThinkingLevel(level) {
+    return level ? THINKING_LEVEL_MAP[level] : undefined;
+}
+class GeminiProvider {
+    constructor(apiKey, model) {
+        this.name = 'gemini';
+        this.chat = null;
+        if (!apiKey || apiKey.trim() === '') {
+            throw new Error('Gemini API key is required');
+        }
+        this.model = model;
+        this.ai = new genai_1.GoogleGenAI({ apiKey });
+    }
+    /**
+     * 创建带有系统提示词的新聊天会话
+     *
+     * @param systemPrompt 系统提示词，用于指导 AI 的角色和行为
+     * @param options.thinkingLevel 思考等级，传入项目小写值（如 'low'），
+     *   内部通过 {@link THINKING_LEVEL_MAP} 映射为 SDK 枚举后传入 thinkingConfig
+     */
+    createSession(systemPrompt, options) {
+        const sdkThinkingLevel = toSdkThinkingLevel(options?.thinkingLevel);
+        const timeout = options?.timeout;
+        this.chat = this.ai.chats.create({
+            model: this.model,
+            config: {
+                systemInstruction: systemPrompt,
+                ...(typeof timeout === 'number' && {
+                    httpOptions: { timeout },
+                }),
+                ...(sdkThinkingLevel !== undefined && {
+                    thinkingConfig: { thinkingLevel: sdkThinkingLevel },
+                }),
+            },
+        });
+    }
+    /**
+     * 发送消息并获取响应
+     */
+    async sendMessage(content) {
+        if (!this.chat) {
+            throw new Error('Chat session not created. Call createSession() first.');
+        }
+        const response = await this.chat.sendMessage({ message: content });
+        if (!response.text) {
+            throw new Error('Empty response from Gemini API');
+        }
+        return response.text;
+    }
+}
+exports.GeminiProvider = GeminiProvider;
+//# sourceMappingURL=gemini.js.map

package/dist/core/ai/providers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Provider 导出
+ */
+export { GeminiProvider } from './gemini';
+export type { IAIProvider } from './gemini';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/ai/providers/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Provider 导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = void 0;
+var gemini_1 = require("./gemini");
+Object.defineProperty(exports, "GeminiProvider", { enumerable: true, get: function () { return gemini_1.GeminiProvider; } });
+//# sourceMappingURL=index.js.map

package/dist/core/ai/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Types 模块导出
+ */
+export type { AIAnalysisInput, AnalysisOptions } from './options';
+export type { AIAnalysisResult, ProfessionalProfile, PersonalProfile, PsychologicalProfile, BehavioralProfile, SocialProfile, RiskAssessment, EvolutionTimelineEntry, } from './result';
+export type { IAIProvider, SessionOptions } from './provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/ai/types/index.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Types 模块导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/core/ai/types/options.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 分析选项
+ */
+import type { AnalyzerOutput } from '../../../core/analyzer';
+/** AI 分析输入 = Analyzer 输出 */
+export type AIAnalysisInput = AnalyzerOutput;
+/** 分析配置选项 */
+export interface AnalysisOptions {
+    apiKey?: string;
+    model?: string;
+    /** 超时时间（毫秒） */
+    timeout?: number;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/core/ai/types/options.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * 分析选项
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=options.js.map

package/dist/core/ai/types/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Provider 接口定义
+ */
+import type { ThinkingLevel } from '../../../config/types/ai';
+/** createSession 可选参数 */
+export interface SessionOptions {
+    /** 思考等级 */
+    thinkingLevel?: ThinkingLevel;
+    /** 请求超时（毫秒） */
+    timeout?: number;
+}
+/** AI Provider 接口 */
+export interface IAIProvider {
+    readonly name: string;
+    /** 注意：为了支持异步初始化，返回 void | Promise<void> */
+    createSession(systemPrompt: string, options?: SessionOptions): void | Promise<void>;
+    sendMessage(content: string): Promise<string>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/core/ai/types/provider.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Provider 接口定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=provider.js.map

package/dist/core/ai/types/result.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AI 分析结果类型
+ */
+/** 职业发展时间线 */
+export interface EvolutionTimelineEntry {
+    period: string;
+    focus: string;
+}
+/** 职业画像 */
+export interface ProfessionalProfile {
+    tech_stack: string[];
+    career_path: string;
+    level: string;
+    focus_coherence: string;
+    evolution: {
+        summary: string;
+        timeline: EvolutionTimelineEntry[];
+    };
+}
+/** 个人生活画像 */
+export interface PersonalProfile {
+    hobbies: string[];
+    life_stage: string;
+    values: string[];
+}
+/** 心理画像 (五大性格特质 OCEAN) */
+export interface PsychologicalProfile {
+    scores: {
+        openness: number;
+        conscientiousness: number;
+        extraversion: number;
+        agreeableness: number;
+        neuroticism: number;
+    };
+    keywords: string[];
+}
+/** 行为画像 */
+export interface BehavioralProfile {
+    role: string;
+    interaction_style: string;
+    active_pattern: string;
+    heat_sensitivity: string;
+}
+/** 社交画像 */
+export interface SocialProfile {
+    content_appeal: string;
+    discussion_depth: string;
+}
+/** 风险评估 */
+export interface RiskAssessment {
+    level: 'safe' | 'suspicious' | 'high_risk';
+    reason: string;
+}
+/** AI 分析结果总览 */
+export interface AIAnalysisResult {
+    summary: string;
+    professional: ProfessionalProfile;
+    personal: PersonalProfile;
+    psychological: PsychologicalProfile;
+    behavioral: BehavioralProfile;
+    social: SocialProfile;
+    risk: RiskAssessment;
+}
+//# sourceMappingURL=result.d.ts.map

package/dist/core/ai/types/result.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * AI 分析结果类型
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=result.js.map

package/dist/core/ai/utils/api-key.d.ts

@@ -0,0 +1,15 @@
+/**
+ * API Key 解析工具
+ *
+ * 优先级：
+ * 1. 显式传入的参数
+ * 2. 配置文件 (~/.v2er-insight/config.json) 中的 ai.apiKey
+ * 3. 环境变量 GOOGLE_API_KEY / GEMINI_API_KEY
+ */
+/**
+ * 从多个来源解析 API Key
+ *
+ * 优先级顺序：显式参数 > 配置文件 > 环境变量
+ */
+export declare function resolveApiKey(explicit?: string): string | null;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/core/ai/utils/api-key.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * API Key 解析工具
+ *
+ * 优先级：
+ * 1. 显式传入的参数
+ * 2. 配置文件 (~/.v2er-insight/config.json) 中的 ai.apiKey
+ * 3. 环境变量 GOOGLE_API_KEY / GEMINI_API_KEY
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiKey = resolveApiKey;
+const config_1 = require("../../../config");
+const ENV_KEYS = ['GOOGLE_API_KEY', 'GEMINI_API_KEY'];
+/**
+ * 从多个来源解析 API Key
+ *
+ * 优先级顺序：显式参数 > 配置文件 > 环境变量
+ */
+function resolveApiKey(explicit) {
+    if (explicit && explicit.trim() !== '') {
+        return explicit.trim();
+    }
+    const config = (0, config_1.getConfig)();
+    const configKey = config.ai?.apiKey;
+    if (configKey && configKey.trim() !== '') {
+        return configKey.trim();
+    }
+    for (const key of ENV_KEYS) {
+        const value = process.env[key];
+        if (value && value.trim() !== '') {
+            return value.trim();
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=api-key.js.map

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

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

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

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

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

@@ -0,0 +1,15 @@
+/**
+ * 重试工具 - 指数退避
+ */
+export interface RetryOptions {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+}
+/**
+ * 带重试逻辑执行函数
+ *
+ * 使用指数退避 + 随机抖动策略
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 重试工具 - 指数退避
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const config_1 = require("../../../config");
+/**
+ * 带重试逻辑执行函数
+ *
+ * 使用指数退避 + 随机抖动策略
+ */
+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));
+}
+//# sourceMappingURL=retry.js.map

package/dist/core/analyzer/builder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Analyzer 输出构建器
+ * 整合所有模块，生成最终的 AI 输入数据
+ */
+import type { RawUserData } from './types';
+import type { AnalyzerOutput } from './types';
+/**
+ * 构建完整的 Analyzer 输出
+ *
+ * 处理流程：
+ * 1. 计算用户总览
+ * 2. 提取所有活动日期
+ * 3. 检测活跃期边界
+ * 4. 将数据分割到各活跃期
+ * 5. 计算每个活跃期的统计
+ * 6. 转换并分片内容
+ *
+ * @param data - V2EX 抓取的原始用户数据
+ * @param referenceDate - 参考日期（用于相对时间解析）
+ * @returns 完整的 Analyzer 输出
+ */
+export declare function buildAnalyzerOutput(data: RawUserData, referenceDate?: Date): AnalyzerOutput;
+//# sourceMappingURL=builder.d.ts.map