@f2a/openclaw-f2a 0.2.20

package/dist/task-guard.d.ts

@@ -0,0 +1,159 @@
+/**
+ * F2A Task Guard
+ * 轻量级任务安全检查和评审
+ */
+import type { TaskRequest, TaskAnnouncement, ReputationEntry } from './types.js';
+export interface TaskGuardRule {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    severity: 'info' | 'warn' | 'block';
+    check: (task: TaskRequest | TaskAnnouncement, context: TaskGuardContext) => TaskGuardResult;
+}
+/**
+ * 任务安全检查上下文
+ *
+ * 提供任务检查所需的上下文信息，包括请求者信誉、黑白名单状态、
+ * 近期请求频率等，用于安全规则判断任务是否应该被接受或拒绝。
+ *
+ * @example
+ * ```typescript
+ * const context: TaskGuardContext = {
+ *   requesterReputation: {
+ *     peerId: 'f2a-peer-xxx',
+ *     score: 85,
+ *     successfulTasks: 42,
+ *     failedTasks: 2,
+ *     // ...其他字段
+ *   },
+ *   isWhitelisted: true,
+ *   isBlacklisted: false,
+ *   recentTaskCount: 3,
+ *   config: DEFAULT_TASK_GUARD_CONFIG
+ * };
+ *
+ * // 使用上下文进行任务检查
+ * const report = taskGuard.check(task, context);
+ * if (!report.passed) {
+ *   console.warn('任务被安全规则拒绝:', report.blocks);
+ * }
+ * ```
+ */
+export interface TaskGuardContext {
+    /** 请求者的信誉信息（可选，新 peer 可能没有） */
+    requesterReputation?: ReputationEntry;
+    /** 请求者是否在白名单中 */
+    isWhitelisted: boolean;
+    /** 请求者是否在黑名单中 */
+    isBlacklisted: boolean;
+    /** 近期（1分钟内）的任务请求数量 */
+    recentTaskCount: number;
+    /** 任务守卫配置 */
+    config: TaskGuardConfig;
+}
+export interface TaskGuardConfig {
+    enabled: boolean;
+    requireConfirmationForDangerous: boolean;
+    maxTasksPerMinute: number;
+    blockedKeywords: string[];
+    dangerousPatterns: RegExp[];
+    minReputationForDangerous: number;
+    /** 持久化目录路径，用于存储 rate limiting 状态。不设置则不持久化 */
+    persistDir?: string;
+    /** 持久化保存间隔（毫秒），默认 30000 (30秒) */
+    persistIntervalMs?: number;
+}
+export interface TaskGuardResult {
+    passed: boolean;
+    severity: 'info' | 'warn' | 'block';
+    ruleId: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface TaskGuardReport {
+    taskId: string;
+    passed: boolean;
+    results: TaskGuardResult[];
+    warnings: TaskGuardResult[];
+    blocks: TaskGuardResult[];
+    requiresConfirmation: boolean;
+    timestamp: number;
+}
+export declare const DEFAULT_TASK_GUARD_CONFIG: TaskGuardConfig;
+export declare class TaskGuard {
+    private config;
+    private rules;
+    private recentTasks;
+    /** 清理阈值：当条目数超过此值时触发清理 */
+    private cleanupThreshold;
+    /** 上次清理时间戳 */
+    private lastCleanupTime;
+    /** 定时清理间隔（毫秒） */
+    private cleanupIntervalMs;
+    /** 持久化文件路径 */
+    private persistFilePath;
+    /** 持久化定时器 */
+    private persistTimer;
+    /** 是否有未保存的更改 */
+    private hasUnsavedChanges;
+    constructor(config?: Partial<TaskGuardConfig>);
+    /**
+     * 初始化持久化
+     */
+    private initPersistence;
+    /**
+     * 加载已保存的状态
+     */
+    private loadPersistedState;
+    /**
+     * 保存状态到文件
+     */
+    private saveState;
+    /**
+     * 仅在有未保存更改时保存
+     */
+    private saveStateIfNeeded;
+    /**
+     * 手动保存当前状态
+     */
+    forceSave(): void;
+    /**
+     * 关闭持久化（停止定时器并保存最后状态）
+     */
+    shutdown(): void;
+    /**
+     * 检查任务
+     */
+    check(task: TaskRequest | TaskAnnouncement, context?: Partial<TaskGuardContext>): TaskGuardReport;
+    /**
+     * 快速检查（只返回是否通过）
+     */
+    quickCheck(task: TaskRequest | TaskAnnouncement, context?: Partial<TaskGuardContext>): boolean;
+    /**
+     * 添加自定义规则
+     */
+    addRule(rule: TaskGuardRule): void;
+    /**
+     * 启用/禁用规则
+     */
+    setRuleEnabled(ruleId: string, enabled: boolean): void;
+    /**
+     * 更新配置
+     */
+    updateConfig(config: Partial<TaskGuardConfig>): void;
+    private createDefaultRules;
+    private isDangerousTask;
+    private getRecentTaskCount;
+    private recordTask;
+    /**
+     * 条件触发清理：当条目数超过阈值或距上次清理超过间隔时执行
+     */
+    private maybeCleanup;
+    /**
+     * 清理过期的 recentTasks 条目，防止内存泄漏
+     */
+    private cleanupRecentTasks;
+}
+export declare const taskGuard: TaskGuard;
+//# sourceMappingURL=task-guard.d.ts.map

package/dist/task-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-guard.d.ts","sourceRoot":"","sources":["../src/task-guard.ts"],"names":[],"mappings":"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"}