@f2a/network 0.1.2

package/src/core/reputation.ts

@@ -0,0 +1,576 @@
+/**
+ * F2A 信誉系统
+ * Phase 1: 基础信誉管理
+ */
+
+import { Logger } from '../utils/logger.js';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+export type ReputationLevel = 'restricted' | 'novice' | 'participant' | 'contributor' | 'core';
+
+export interface ReputationTier {
+  min: number;
+  max: number;
+  level: ReputationLevel;
+  title: string;
+  permissions: {
+    canPublish: boolean;
+    canExecute: boolean;
+    canReview: boolean;
+    publishPriority: number;
+    publishDiscount: number;
+  };
+}
+
+export interface ReputationEntry {
+  peerId: string;
+  score: number;
+  level: ReputationLevel;
+  lastUpdated: number;
+  history: ReputationEvent[];
+}
+
+export interface ReputationEvent {
+  type: 'task_success' | 'task_failure' | 'task_rejected' | 'review_given' | 'review_penalty' | 'initial';
+  delta: number;
+  timestamp: number;
+  reason?: string;
+  taskId?: string;
+}
+
+export interface ReputationConfig {
+  initialScore: number;
+  alpha: number;  // EWMA 平滑系数
+  minScore: number;
+  maxScore: number;
+  maxHistory: number;  // 历史记录上限
+  decayRate: number;   // 衰减率（每日衰减百分比，如 0.01 表示每天衰减 1%）
+  decayIntervalMs: number;  // 衰减检查间隔（毫秒）
+  maxLatency: number;  // 最大可接受的延迟（毫秒）
+}
+
+// ============================================================================
+// 持久化接口
+// ============================================================================
+
+export interface ReputationStorage {
+  save(entries: Map<string, ReputationEntry>): Promise<void>;
+  load(): Promise<Map<string, ReputationEntry>>;
+}
+
+// ============================================================================
+// 信誉等级定义
+// ============================================================================
+
+export const REPUTATION_TIERS: ReputationTier[] = [
+  {
+    min: 0,
+    max: 20,
+    level: 'restricted',
+    title: '受限者',
+    permissions: {
+      canPublish: false,
+      canExecute: true,
+      canReview: false,
+      publishPriority: 0,
+      publishDiscount: 1.0,
+    },
+  },
+  {
+    min: 20,
+    max: 40,
+    level: 'novice',
+    title: '新手',
+    permissions: {
+      canPublish: true,
+      canExecute: true,
+      canReview: false,
+      publishPriority: 1,
+      publishDiscount: 1.0,
+    },
+  },
+  {
+    min: 40,
+    max: 60,
+    level: 'participant',
+    title: '参与者',
+    permissions: {
+      canPublish: true,
+      canExecute: true,
+      canReview: true,
+      publishPriority: 2,
+      publishDiscount: 1.0,
+    },
+  },
+  {
+    min: 60,
+    max: 80,
+    level: 'contributor',
+    title: '贡献者',
+    permissions: {
+      canPublish: true,
+      canExecute: true,
+      canReview: true,
+      publishPriority: 3,
+      publishDiscount: 0.9,
+    },
+  },
+  {
+    min: 80,
+    max: 100,
+    level: 'core',
+    title: '核心成员',
+    permissions: {
+      canPublish: true,
+      canExecute: true,
+      canReview: true,
+      publishPriority: 5,
+      publishDiscount: 0.7,
+    },
+  },
+];
+
+// ============================================================================
+// 默认配置
+// ============================================================================
+
+const DEFAULT_CONFIG: ReputationConfig = {
+  initialScore: 70,
+  alpha: 0.3,
+  minScore: 0,
+  maxScore: 100,
+  maxHistory: 100,
+  decayRate: 0.01,           // 每天衰减 1%
+  decayIntervalMs: 24 * 60 * 60 * 1000,  // 每 24 小时检查一次
+  maxLatency: 300000,        // 最大可接受延迟 5 分钟
+};
+
+// ============================================================================
+// 信誉管理器
+// ============================================================================
+
+export class ReputationManager implements Disposable {
+  private config: ReputationConfig;
+  private entries: Map<string, ReputationEntry> = new Map();
+  private logger: Logger;
+  private decayTimer?: NodeJS.Timeout;
+  private disposed: boolean = false;
+
+  constructor(config: Partial<ReputationConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.logger = new Logger({ component: 'Reputation' });
+    
+    // 启动衰减定时器
+    if (this.config.decayRate > 0) {
+      this.startDecayTimer();
+    }
+  }
+
+  /**
+   * 实现 Disposable 接口
+   */
+  [Symbol.dispose](): void {
+    this.stop();
+  }
+
+  /**
+   * 停止定时器和清理资源
+   */
+  stop(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    
+    if (this.decayTimer) {
+      clearInterval(this.decayTimer);
+      this.decayTimer = undefined;
+    }
+  }
+
+  /**
+   * 启动衰减定时器
+   */
+  private startDecayTimer(): void {
+    this.decayTimer = setInterval(() => {
+      this.applyDecay();
+    }, this.config.decayIntervalMs);
+  }
+
+  /**
+   * 应用信誉衰减
+   * 每个节点的信誉分数按 decayRate 比例衰减
+   */
+  private applyDecay(): void {
+    const decayFactor = 1 - this.config.decayRate;
+    
+    for (const [peerId, entry] of this.entries) {
+      // 不衰减初始分数以下的值
+      if (entry.score > this.config.initialScore) {
+        const newScore = entry.score * decayFactor;
+        // 确保不低于初始分数
+        entry.score = Math.max(this.config.initialScore, newScore);
+        entry.level = this.getTier(entry.score).level;
+        entry.lastUpdated = Date.now();
+      }
+    }
+    
+    this.logger.debug('Applied reputation decay', { 
+      decayRate: this.config.decayRate,
+      entriesAffected: this.entries.size 
+    });
+  }
+
+  /**
+   * 获取节点信誉信息
+   * 如果节点不存在，会自动创建一个带有初始分数的条目
+   * @param peerId - 节点的唯一标识符
+   * @returns 节点的信誉条目，包含分数、等级和历史记录
+   */
+  getReputation(peerId: string): ReputationEntry {
+    if (!this.entries.has(peerId)) {
+      this.entries.set(peerId, this.createInitialEntry(peerId));
+    }
+    return this.entries.get(peerId)!;
+  }
+
+  /**
+   * 获取信誉等级信息
+   * 根据分数返回对应的信誉等级和权限配置
+   * @param score - 信誉分数 (0-100)
+   * @returns 对应的信誉等级配置
+   */
+  getTier(score: number): ReputationTier {
+    for (const tier of REPUTATION_TIERS) {
+      if (score >= tier.min && score < tier.max) {
+        return tier;
+      }
+    }
+    return REPUTATION_TIERS[REPUTATION_TIERS.length - 1]; // core
+  }
+
+  /**
+   * 检查节点是否具有指定权限
+   * @param peerId - 节点的唯一标识符
+   * @param permission - 要检查的权限类型：'publish'（发布）、'execute'（执行）、'review'（评审）
+   * @returns 如果节点具有该权限则返回 true，否则返回 false
+   */
+  hasPermission(peerId: string, permission: 'publish' | 'execute' | 'review'): boolean {
+    const entry = this.getReputation(peerId);
+    const tier = this.getTier(entry.score);
+
+    switch (permission) {
+      case 'publish':
+        return tier.permissions.canPublish;
+      case 'execute':
+        return tier.permissions.canExecute;
+      case 'review':
+        return tier.permissions.canReview;
+    }
+  }
+
+  /**
+   * 记录任务成功
+   * @param peerId 节点 ID
+   * @param taskId 任务 ID
+   * @param delta 分数变化量
+   * @param latency 响应延迟（毫秒），可选，用于未来优化
+   */
+  recordSuccess(peerId: string, taskId: string, delta: number = 10, latency?: number): void {
+    // 验证 latency 参数
+    if (latency !== undefined) {
+      if (typeof latency !== 'number' || !Number.isFinite(latency)) {
+        this.logger.warn('Invalid latency value, ignoring', { 
+          peerId: peerId.slice(0, 16), 
+          latency 
+        });
+        latency = undefined;
+      } else if (latency < 0) {
+        this.logger.warn('Negative latency value, treating as 0', { 
+          peerId: peerId.slice(0, 16), 
+          latency 
+        });
+        latency = 0;
+      } else if (latency > this.config.maxLatency) {
+        this.logger.warn('Latency exceeds max, capping', { 
+          peerId: peerId.slice(0, 16), 
+          latency,
+          maxLatency: this.config.maxLatency 
+        });
+        latency = this.config.maxLatency;
+      }
+    }
+    
+    const entry = this.getReputation(peerId);
+    const newScore = this.updateScoreEWMA(entry.score, delta);
+
+    entry.score = newScore;
+    entry.level = this.getTier(newScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'task_success',
+      delta,
+      timestamp: Date.now(),
+      taskId,
+    });
+
+    // 截断历史记录，防止无限增长
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.info('Reputation updated', {
+      peerId: peerId.slice(0, 16),
+      delta,
+      newScore,
+      level: entry.level,
+      latency
+    });
+  }
+
+  /**
+   * 记录任务失败
+   * 会降低节点的信誉分数
+   * @param peerId - 节点的唯一标识符
+   * @param taskId - 失败任务的 ID
+   * @param reason - 可选的失败原因描述
+   * @param delta - 分数变化量，默认为 -20
+   */
+  recordFailure(peerId: string, taskId: string, reason?: string, delta: number = -20): void {
+    const entry = this.getReputation(peerId);
+    const newScore = this.updateScoreEWMA(entry.score, delta);
+
+    entry.score = newScore;
+    entry.level = this.getTier(newScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'task_failure',
+      delta,
+      timestamp: Date.now(),
+      reason,
+      taskId,
+    });
+
+    // 截断历史记录
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.warn('Reputation decreased', {
+      peerId: peerId.slice(0, 16),
+      delta,
+      newScore,
+      level: entry.level,
+      reason,
+    });
+  }
+
+  /**
+   * 记录任务拒绝
+   * 当节点拒绝接受任务时调用，会轻微降低信誉分数
+   * @param peerId - 节点的唯一标识符
+   * @param taskId - 被拒绝任务的 ID
+   * @param reason - 可选的拒绝原因描述
+   * @param delta - 分数变化量，默认为 -5
+   */
+  recordRejection(peerId: string, taskId: string, reason?: string, delta: number = -5): void {
+    const entry = this.getReputation(peerId);
+    const newScore = this.updateScoreEWMA(entry.score, delta);
+
+    entry.score = newScore;
+    entry.level = this.getTier(newScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'task_rejected',
+      delta,
+      timestamp: Date.now(),
+      reason,
+      taskId,
+    });
+
+    // 截断历史记录
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.info('Reputation updated (rejection)', {
+      peerId: peerId.slice(0, 16),
+      delta,
+      newScore,
+    });
+  }
+
+  /**
+   * 记录评审奖励
+   * 当节点完成评审任务时调用，会提高信誉分数
+   * @param peerId - 节点的唯一标识符
+   * @param delta - 分数变化量，默认为 3
+   */
+  recordReviewReward(peerId: string, delta: number = 3): void {
+    const entry = this.getReputation(peerId);
+    const newScore = this.updateScoreEWMA(entry.score, delta);
+
+    entry.score = newScore;
+    entry.level = this.getTier(newScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'review_given',
+      delta,
+      timestamp: Date.now(),
+    });
+
+    // 截断历史记录
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.info('Review reward', {
+      peerId: peerId.slice(0, 16),
+      delta,
+      newScore,
+    });
+  }
+
+  /**
+   * 记录评审惩罚
+   * 当节点提供低质量评审或违规时调用，会降低信誉分数
+   * @param peerId - 节点的唯一标识符
+   * @param delta - 分数变化量，默认为 -5
+   * @param reason - 可选的惩罚原因描述
+   */
+  recordReviewPenalty(peerId: string, delta: number = -5, reason?: string): void {
+    const entry = this.getReputation(peerId);
+    const newScore = this.updateScoreEWMA(entry.score, delta);
+
+    entry.score = newScore;
+    entry.level = this.getTier(newScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'review_penalty',
+      delta,
+      timestamp: Date.now(),
+      reason,
+    });
+
+    // 截断历史记录
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.warn('Review penalty', {
+      peerId: peerId.slice(0, 16),
+      delta,
+      newScore,
+      reason,
+    });
+  }
+
+  /**
+   * 获取所有信誉条目
+   * 返回按分数从高到低排序的所有节点信誉信息
+   * @returns 排序后的信誉条目数组
+   */
+  getAllReputations(): ReputationEntry[] {
+    return Array.from(this.entries.values()).sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * 获取高信誉节点
+   * 返回分数达到指定阈值的节点列表，可用于评审任务分配
+   * @param minScore - 最低信誉分数阈值，默认为 50
+   * @returns 符合条件的信誉条目数组，按分数排序
+   */
+  getHighReputationNodes(minScore: number = 50): ReputationEntry[] {
+    return this.getAllReputations().filter(e => e.score >= minScore);
+  }
+
+  /**
+   * 获取节点的发布优先级
+   * 优先级越高，任务分配时越优先被考虑
+   * @param peerId - 节点的唯一标识符
+   * @returns 发布优先级 (0-5)
+   */
+  getPublishPriority(peerId: string): number {
+    const entry = this.getReputation(peerId);
+    return this.getTier(entry.score).permissions.publishPriority;
+  }
+
+  /**
+   * 获取节点的发布折扣
+   * 高信誉节点可享受更低的服务费用折扣
+   * @param peerId - 节点的唯一标识符
+   * @returns 发布折扣率 (0.7-1.0，数值越小折扣越大)
+   */
+  getPublishDiscount(peerId: string): number {
+    const entry = this.getReputation(peerId);
+    return this.getTier(entry.score).permissions.publishDiscount;
+  }
+
+  /**
+   * 设置节点的初始信誉分数
+   * 用于邀请机制设置被邀请者的初始分数，可覆盖默认初始分数
+   * @param peerId - 节点的唯一标识符
+   * @param score - 要设置的分数 (0-100)，会自动限制在有效范围内
+   */
+  setInitialScore(peerId: string, score: number): void {
+    const entry = this.getReputation(peerId);
+    const clampedScore = Math.max(this.config.minScore, Math.min(this.config.maxScore, score));
+    entry.score = clampedScore;
+    entry.level = this.getTier(clampedScore).level;
+    entry.lastUpdated = Date.now();
+    entry.history.push({
+      type: 'initial',
+      delta: clampedScore - this.config.initialScore,
+      timestamp: Date.now(),
+      reason: 'Set by invitation system'
+    });
+
+    // 截断历史记录
+    if (entry.history.length > this.config.maxHistory) {
+      entry.history = entry.history.slice(-this.config.maxHistory);
+    }
+
+    this.logger.info('Initial score set', {
+      peerId: peerId.slice(0, 16),
+      score: clampedScore,
+      level: entry.level
+    });
+  }
+
+  // ============================================================================
+  // 私有方法
+  // ============================================================================
+
+  /**
+   * 创建初始信誉条目
+   */
+  private createInitialEntry(peerId: string): ReputationEntry {
+    return {
+      peerId,
+      score: this.config.initialScore,
+      level: this.getTier(this.config.initialScore).level,
+      lastUpdated: Date.now(),
+      history: [
+        {
+          type: 'initial',
+          delta: 0,
+          timestamp: Date.now(),
+        },
+      ],
+    };
+  }
+
+  /**
+   * EWMA 分数更新
+   * newScore = α * observation + (1 - α) * currentScore
+   */
+  private updateScoreEWMA(currentScore: number, delta: number): number {
+    const observation = currentScore + delta;
+    const newScore = this.config.alpha * observation + (1 - this.config.alpha) * currentScore;
+    return Math.max(this.config.minScore, Math.min(this.config.maxScore, newScore));
+  }
+}
+
+// 默认导出
+export default ReputationManager;