principles-disciple 1.127.0 → 1.129.0

package/dist/core/evolution-engine.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Evolution Engine V2.0 - MVP
+ *
+ * 成长驱动的进化积分系统，替代惩罚驱动的 Trust Engine。
+ *
+ * 核心原则：
+ * 1. 起点0分，只能增加，不扣分
+ * 2. 失败记录教训，不扣分
+ * 3. 同类任务失败后首次成功 = 双倍奖励（1小时冷却）
+ * 4. 高等级做低级任务积分衰减
+ * 5. 原子写入防止并发损坏
+ */
+import type { EvolutionScorecard, EvolutionStats, EvolutionConfig, TaskDifficulty, TierDefinition, GateDecision, ToolCallContext } from './evolution-types.js';
+import { EvolutionTier } from './evolution-types.js';
+export declare class EvolutionEngine {
+    private readonly scorecard;
+    private readonly workspaceDir;
+    private readonly stateDir;
+    private readonly config;
+    private readonly storagePath;
+    constructor(workspaceDir: string, config?: Partial<EvolutionConfig>);
+    /** 获取当前积分 */
+    getPoints(): number;
+    /** 获取可用积分 */
+    getAvailablePoints(): number;
+    /** 获取当前等级 */
+    getTier(): EvolutionTier;
+    /** 获取当前等级定义 */
+    getTierDefinition(): TierDefinition;
+    /** 获取完整积分卡 */
+    getScorecard(): EvolutionScorecard;
+    /** 获取统计信息 */
+    getStats(): EvolutionStats;
+    /** 获取状态摘要 */
+    getStatusSummary(): {
+        tier: EvolutionTier;
+        tierName: string;
+        totalPoints: number;
+        availablePoints: number;
+        permissions: import("@principles/core/runtime-v2").TierPermissions;
+        stats: EvolutionStats;
+        nextTier: {
+            tier: EvolutionTier;
+            name: string;
+            pointsNeeded: number;
+        } | null;
+    };
+    recordSuccess(toolName: string, options?: {
+        filePath?: string;
+        difficulty?: TaskDifficulty;
+        reason?: string;
+        sessionId?: string;
+    }): {
+        pointsAwarded: number;
+        isDoubleReward: boolean;
+        newTier?: EvolutionTier;
+    };
+    recordFailure(toolName: string, options?: {
+        filePath?: string;
+        difficulty?: TaskDifficulty;
+        reason?: string;
+        sessionId?: string;
+    }): {
+        pointsAwarded: number;
+        lessonRecorded: boolean;
+    };
+    /** 工具调用前检查 */
+    beforeToolCall(context: ToolCallContext): GateDecision;
+    private calculatePoints;
+    private getDifficultyPenalty;
+    private canReceiveDoubleReward;
+    private checkAndApplyPromotion;
+    private static inferDifficulty;
+    private static computeTaskHash;
+    private createEvent;
+    private addEvent;
+    private loadOrCreateScorecard;
+    private createNewScorecard;
+    /** 持久化评分卡（含锁保护） */
+    private saveScorecard;
+    /** Per-instance retry queue (P0 fix: was static, causing cross-instance race) */
+    private retryQueue;
+    private retryTimer;
+    /** 调度重试保存 */
+    private scheduleRetrySave;
+    /** 处理重试队列 */
+    private processRetryQueue;
+    /** 无锁快速保存（用于重试） */
+    private saveScorecardImmediate;
+    private generateId;
+    dispose(): void;
+}
+/** 获取指定 workspace 的引擎实例 */
+export declare function getEvolutionEngine(workspaceDir: string): EvolutionEngine;
+export declare function disposeEvolutionEngine(workspaceDir: string): void;
+export declare function disposeAllEvolutionEngines(): void;
+/** 记录成功（便捷函数） */
+export declare function recordEvolutionSuccess(workspaceDir: string, toolName: string, options?: {
+    filePath?: string;
+    difficulty?: TaskDifficulty;
+    reason?: string;
+    sessionId?: string;
+}): {
+    pointsAwarded: number;
+    isDoubleReward: boolean;
+    newTier?: EvolutionTier;
+};
+/** 记录失败（便捷函数） */
+export declare function recordEvolutionFailure(workspaceDir: string, toolName: string, options?: {
+    filePath?: string;
+    difficulty?: TaskDifficulty;
+    reason?: string;
+    sessionId?: string;
+}): {
+    pointsAwarded: number;
+    lessonRecorded: boolean;
+};
+/** Gate 检查（便捷函数） */
+export declare function checkEvolutionGate(workspaceDir: string, context: ToolCallContext): GateDecision;

package/dist/core/evolution-engine.js

@@ -0,0 +1,460 @@
+/**
+ * Evolution Engine V2.0 - MVP
+ *
+ * 成长驱动的进化积分系统，替代惩罚驱动的 Trust Engine。
+ *
+ * 核心原则：
+ * 1. 起点0分，只能增加，不扣分
+ * 2. 失败记录教训，不扣分
+ * 3. 同类任务失败后首次成功 = 双倍奖励（1小时冷却）
+ * 4. 高等级做低级任务积分衰减
+ * 5. 原子写入防止并发损坏
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolvePdPath } from './paths.js';
+import { withLock } from '../utils/file-lock.js';
+import { CONSTRUCTIVE_TOOLS, EXPLORATORY_TOOLS, HIGH_RISK_TOOLS, } from '../constants/tools.js';
+import { EvolutionTier, DEFAULT_EVOLUTION_CONFIG, TIER_DEFINITIONS, TASK_DIFFICULTY_CONFIG, getTierDefinition, getTierByPoints, } from './evolution-types.js';
+// ===== 主引擎 =====
+export class EvolutionEngine {
+    scorecard;
+    workspaceDir;
+    stateDir;
+    config;
+    storagePath;
+    constructor(workspaceDir, config) {
+        this.workspaceDir = workspaceDir;
+        this.stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
+        this.config = { ...DEFAULT_EVOLUTION_CONFIG, ...config };
+        this.storagePath = path.join(this.stateDir, 'evolution-scorecard.json');
+        this.scorecard = this.loadOrCreateScorecard();
+    }
+    // ===== 公共 API =====
+    /** 获取当前积分 */
+    getPoints() {
+        return this.scorecard.totalPoints;
+    }
+    /** 获取可用积分 */
+    getAvailablePoints() {
+        return this.scorecard.availablePoints;
+    }
+    /** 获取当前等级 */
+    getTier() {
+        return this.scorecard.currentTier;
+    }
+    /** 获取当前等级定义 */
+    getTierDefinition() {
+        return getTierDefinition(this.scorecard.currentTier);
+    }
+    /** 获取完整积分卡 */
+    getScorecard() {
+        return { ...this.scorecard };
+    }
+    /** 获取统计信息 */
+    getStats() {
+        return { ...this.scorecard.stats };
+    }
+    /** 获取状态摘要 */
+    getStatusSummary() {
+        const tierDef = this.getTierDefinition();
+        const nextTierDef = TIER_DEFINITIONS[this.scorecard.currentTier]; // undefined if max
+        return {
+            tier: this.scorecard.currentTier,
+            tierName: tierDef.name,
+            totalPoints: this.scorecard.totalPoints,
+            availablePoints: this.scorecard.availablePoints,
+            permissions: tierDef.permissions,
+            stats: this.scorecard.stats,
+            nextTier: nextTierDef ? {
+                tier: nextTierDef.tier,
+                name: nextTierDef.name,
+                pointsNeeded: nextTierDef.requiredPoints - this.scorecard.totalPoints,
+            } : null,
+        };
+    }
+    // ===== 记录成功 =====
+    recordSuccess(toolName, options) {
+        // 探索性工具成功不给积分，只重置失败记录
+        if (EXPLORATORY_TOOLS.has(toolName)) {
+            const taskHash = EvolutionEngine.computeTaskHash(toolName, options?.filePath);
+            this.scorecard.recentFailureHashes.delete(taskHash);
+            this.saveScorecard();
+            return { pointsAwarded: 0, isDoubleReward: false };
+        }
+        const difficulty = options?.difficulty || EvolutionEngine.inferDifficulty(toolName);
+        const taskHash = EvolutionEngine.computeTaskHash(toolName, options?.filePath);
+        // 计算积分
+        let points = this.calculatePoints(difficulty, taskHash);
+        const isDoubleReward = points > TASK_DIFFICULTY_CONFIG[difficulty].basePoints;
+        // 更新积分
+        this.scorecard.totalPoints += points;
+        this.scorecard.availablePoints += points;
+        // 更新统计
+        this.scorecard.stats.totalSuccesses++;
+        this.scorecard.stats.consecutiveSuccesses++;
+        this.scorecard.stats.consecutiveFailures = 0;
+        this.scorecard.stats.pointsByDifficulty[difficulty] += points;
+        if (isDoubleReward) {
+            this.scorecard.stats.doubleRewardsEarned++;
+            this.scorecard.lastDoubleRewardTime = new Date().toISOString();
+        }
+        // 清除失败记录
+        this.scorecard.recentFailureHashes.delete(taskHash);
+        // 记录事件
+        const event = this.createEvent('success', taskHash, difficulty, toolName, options?.filePath, options?.reason, points, isDoubleReward, options?.sessionId);
+        this.addEvent(event);
+        // 检查升级
+        const newTier = this.checkAndApplyPromotion();
+        this.saveScorecard();
+        return { pointsAwarded: points, isDoubleReward, newTier };
+    }
+    // ===== 记录失败 =====
+    recordFailure(toolName, options) {
+        // 探索性工具失败：记录但几乎不影响
+        if (EXPLORATORY_TOOLS.has(toolName)) {
+            const event = this.createEvent('failure', EvolutionEngine.computeTaskHash(toolName, options?.filePath), 'trivial', toolName, options?.filePath, options?.reason, 0, false, options?.sessionId);
+            this.addEvent(event);
+            this.saveScorecard();
+            return { pointsAwarded: 0, lessonRecorded: true };
+        }
+        const difficulty = options?.difficulty || EvolutionEngine.inferDifficulty(toolName);
+        const taskHash = EvolutionEngine.computeTaskHash(toolName, options?.filePath);
+        // 失败不扣分，但记录教训（用于后续双倍奖励）
+        this.scorecard.recentFailureHashes.set(taskHash, new Date().toISOString());
+        // 更新统计
+        this.scorecard.stats.totalFailures++;
+        this.scorecard.stats.consecutiveFailures++;
+        this.scorecard.stats.consecutiveSuccesses = 0;
+        // 记录事件（0分）
+        const event = this.createEvent('failure', taskHash, difficulty, toolName, options?.filePath, options?.reason, 0, false, options?.sessionId);
+        this.addEvent(event);
+        this.saveScorecard();
+        return { pointsAwarded: 0, lessonRecorded: true };
+    }
+    // ===== Gate 集成 =====
+    /** 工具调用前检查 */
+    beforeToolCall(context) {
+        const tierDef = this.getTierDefinition();
+        const perms = tierDef.permissions;
+        // 风险路径检查
+        if (context.isRiskPath && !perms.allowRiskPath) {
+            return {
+                allowed: false,
+                reason: `Tier ${this.scorecard.currentTier} (${tierDef.name}) 未解锁风险路径权限`,
+                currentTier: this.scorecard.currentTier,
+            };
+        }
+        // 高风险工具检查（不包括子智能体，它们有单独控制）
+        if (HIGH_RISK_TOOLS.has(context.toolName) && !perms.allowRiskPath) {
+            return {
+                allowed: false,
+                reason: `Tier ${this.scorecard.currentTier} (${tierDef.name}) 未解锁高风险工具权限`,
+                currentTier: this.scorecard.currentTier,
+            };
+        }
+        // 子智能体检查
+        if (context.toolName === 'sessions_spawn' && !perms.allowSubagentSpawn) {
+            return {
+                allowed: false,
+                reason: `Tier ${this.scorecard.currentTier} (${tierDef.name}) 未解锁子智能体权限`,
+                currentTier: this.scorecard.currentTier,
+            };
+        }
+        return { allowed: true, currentTier: this.scorecard.currentTier };
+    }
+    // ===== 积分计算 =====
+    calculatePoints(difficulty, taskHash) {
+        const { basePoints } = TASK_DIFFICULTY_CONFIG[difficulty];
+        // 难度衰减
+        const penalty = this.getDifficultyPenalty(difficulty);
+        let points = Math.max(1, Math.floor(basePoints * penalty));
+        // 双倍奖励检查
+        if (this.canReceiveDoubleReward(taskHash)) {
+            points *= 2;
+        }
+        return points;
+    }
+    getDifficultyPenalty(difficulty) {
+        const tier = this.scorecard.currentTier;
+        const dc = this.config.difficultyPenalty;
+        if (tier >= EvolutionTier.Tree) {
+            if (difficulty === 'trivial')
+                return dc.tier4Trivial;
+            if (difficulty === 'normal')
+                return dc.tier4Normal;
+        }
+        if (tier >= EvolutionTier.Forest) {
+            if (difficulty === 'trivial')
+                return dc.tier5Trivial;
+            if (difficulty === 'normal')
+                return dc.tier5Normal;
+        }
+        return 1.0;
+    }
+    canReceiveDoubleReward(taskHash) {
+        // 必须有该任务的失败记录
+        if (!this.scorecard.recentFailureHashes.has(taskHash)) {
+            return false;
+        }
+        // 冷却检查：1小时内最多1次双倍奖励
+        if (this.scorecard.lastDoubleRewardTime) {
+            const elapsed = Date.now() - new Date(this.scorecard.lastDoubleRewardTime).getTime();
+            if (elapsed < this.config.doubleRewardCooldownMs) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // ===== 等级晋升 =====
+    checkAndApplyPromotion() {
+        const newTier = getTierByPoints(this.scorecard.totalPoints);
+        if (newTier > this.scorecard.currentTier) {
+            const previousTier = this.scorecard.currentTier;
+            this.scorecard.currentTier = newTier;
+            this.scorecard.stats.tierPromotions++;
+            console.log(`[Evolution] 🎉 Tier promotion: ${previousTier} → ${newTier} (${getTierDefinition(newTier).name})`);
+            return newTier;
+        }
+        return undefined;
+    }
+    // ===== 任务难度推断 =====
+    static inferDifficulty(toolName) {
+        if (HIGH_RISK_TOOLS.has(toolName))
+            return 'hard';
+        if (CONSTRUCTIVE_TOOLS.has(toolName))
+            return 'normal';
+        return 'trivial';
+    }
+    // ===== 任务哈希 =====
+    static computeTaskHash(toolName, filePath) {
+        const normalizedPath = filePath ? path.normalize(filePath) : '_nofile';
+        return `${toolName}:${normalizedPath}`;
+    }
+    // ===== 事件管理 =====
+    createEvent(type, taskHash, difficulty, toolName, filePath, reason, points, isDoubleReward, sessionId) {
+        return {
+            id: this.generateId(),
+            timestamp: new Date().toISOString(),
+            type,
+            taskHash,
+            taskDifficulty: difficulty,
+            toolName,
+            filePath,
+            reason,
+            pointsAwarded: points,
+            isDoubleReward,
+            sessionId,
+        };
+    }
+    addEvent(event) {
+        this.scorecard.recentEvents.push(event);
+        // 限制事件数量
+        if (this.scorecard.recentEvents.length > this.config.maxRecentEvents) {
+            this.scorecard.recentEvents.shift();
+        }
+    }
+    // ===== 存储 =====
+    loadOrCreateScorecard() {
+        // 尝试从文件加载
+        if (fs.existsSync(this.storagePath)) {
+            try {
+                const raw = fs.readFileSync(this.storagePath, 'utf8');
+                const data = JSON.parse(raw);
+                if (data.version === '2.0') {
+                    // 恢复 Map 类型
+                    if (data.recentFailureHashes && Array.isArray(data.recentFailureHashes)) {
+                        data.recentFailureHashes = new Map(data.recentFailureHashes);
+                    }
+                    else if (!data.recentFailureHashes) {
+                        data.recentFailureHashes = new Map();
+                    }
+                    return data;
+                }
+            }
+            catch (e) {
+                console.error(`[Evolution] Failed to parse scorecard at ${this.storagePath}. Creating new.`, e);
+            }
+        }
+        // 创建新的积分卡
+        return this.createNewScorecard();
+    }
+    createNewScorecard() {
+        const now = new Date().toISOString();
+        return {
+            version: '2.0',
+            agentId: 'default',
+            totalPoints: 0,
+            availablePoints: 0,
+            currentTier: EvolutionTier.Seed,
+            recentFailureHashes: new Map(),
+            stats: {
+                totalSuccesses: 0,
+                totalFailures: 0,
+                consecutiveSuccesses: 0,
+                consecutiveFailures: 0,
+                doubleRewardsEarned: 0,
+                tierPromotions: 0,
+                pointsByDifficulty: { trivial: 0, normal: 0, hard: 0 },
+            },
+            recentEvents: [],
+            lastUpdated: now,
+        };
+    }
+    /** 持久化评分卡（含锁保护） */
+    saveScorecard() {
+        this.scorecard.lastUpdated = new Date().toISOString();
+        // 确保目录存在
+        const dir = path.dirname(this.storagePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // 序列化（Map 转 Array）
+        const serializable = {
+            ...this.scorecard,
+            recentFailureHashes: Array.from(this.scorecard.recentFailureHashes.entries()),
+        };
+        const tempPath = `${this.storagePath}.tmp.${Date.now()}.${process.pid}`;
+        try {
+            withLock(this.storagePath, () => {
+                fs.writeFileSync(tempPath, JSON.stringify(serializable, null, 2), 'utf8');
+                // fsync 确保数据落盘
+                const fd = fs.openSync(tempPath, 'r+');
+                fs.fsyncSync(fd);
+                fs.closeSync(fd);
+                // 原子重命名
+                fs.renameSync(tempPath, this.storagePath);
+            }, {
+                lockSuffix: '.lock',
+                lockStaleMs: 30_000,
+            });
+        }
+        catch (e) {
+            console.error(`[Evolution] Failed to save scorecard: ${String(e)}`);
+            this.scheduleRetrySave();
+            /* eslint-disable @typescript-eslint/no-unused-vars -- Reason: intentionally ignored - cleanup failure should not mask original error */
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch (_e) {
+                // Cleanup failure intentionally ignored - should not mask original error
+            }
+        }
+    }
+    /** Per-instance retry queue (P0 fix: was static, causing cross-instance race) */
+    retryQueue = [];
+    retryTimer = null;
+    /** 调度重试保存 */
+    scheduleRetrySave() {
+        // 每个引擎只保留最新数据
+        this.retryQueue = this.retryQueue.filter(item => item.engine !== this);
+        this.retryQueue.push({ engine: this, data: { ...this.scorecard } });
+        // 启动重试定时器（每个实例独立）
+        if (!this.retryTimer) {
+            this.retryTimer = setTimeout(() => {
+                this.processRetryQueue();
+            }, 1000);
+            this.retryTimer.unref(); // Don't keep process alive for retry
+        }
+    }
+    /** 处理重试队列 */
+    processRetryQueue() {
+        this.retryTimer = null;
+        const latestByEngine = new Map();
+        for (const item of this.retryQueue) {
+            latestByEngine.set(item.engine, item.data);
+        }
+        this.retryQueue = [];
+        for (const [engine, data] of latestByEngine) {
+            try {
+                engine.saveScorecardImmediate(data);
+                console.log(`[Evolution] Retry save succeeded for ${engine.workspaceDir}`);
+            }
+            catch (e) {
+                console.error(`[Evolution] Retry save failed: ${String(e)}`);
+                engine.scheduleRetrySave(); // 每个引擎独立重试
+            }
+        }
+    }
+    /** 无锁快速保存（用于重试） */
+    saveScorecardImmediate(data) {
+        const serializable = {
+            ...this.scorecard,
+            ...data,
+            recentFailureHashes: Array.from(this.scorecard.recentFailureHashes.entries()),
+        };
+        const tempPath = `${this.storagePath}.tmp.retry.${Date.now()}.${process.pid}`;
+        withLock(this.storagePath, () => {
+            try {
+                fs.writeFileSync(tempPath, JSON.stringify(serializable, null, 2), 'utf8');
+                const fd = fs.openSync(tempPath, 'r');
+                fs.fsyncSync(fd);
+                fs.closeSync(fd);
+                fs.renameSync(tempPath, this.storagePath);
+            }
+            catch (error) {
+                // Clean up temp file on failure
+                try {
+                    if (fs.existsSync(tempPath)) {
+                        fs.unlinkSync(tempPath);
+                    }
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
+        }, {
+            lockSuffix: '.lock',
+            lockStaleMs: 30_000,
+        });
+    }
+    // ===== 工具方法 =====
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+    dispose() {
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        this.retryQueue = [];
+    }
+}
+// ===== 便捷函数 =====
+// 使用 Map 按 workspace 隔离实例，避免多 workspace 场景状态串扰
+const _instances = new Map();
+/** 获取指定 workspace 的引擎实例 */
+export function getEvolutionEngine(workspaceDir) {
+    const resolved = path.resolve(workspaceDir);
+    if (!_instances.has(resolved)) {
+        _instances.set(resolved, new EvolutionEngine(resolved));
+    }
+    return _instances.get(resolved);
+}
+export function disposeEvolutionEngine(workspaceDir) {
+    const resolved = path.resolve(workspaceDir);
+    const instance = _instances.get(resolved);
+    if (!instance)
+        return;
+    instance.dispose();
+    _instances.delete(resolved);
+}
+export function disposeAllEvolutionEngines() {
+    for (const instance of _instances.values()) {
+        instance.dispose();
+    }
+    _instances.clear();
+}
+/** 记录成功（便捷函数） */
+export function recordEvolutionSuccess(workspaceDir, toolName, options) {
+    return getEvolutionEngine(workspaceDir).recordSuccess(toolName, options);
+}
+/** 记录失败（便捷函数） */
+export function recordEvolutionFailure(workspaceDir, toolName, options) {
+    return getEvolutionEngine(workspaceDir).recordFailure(toolName, options);
+}
+/** Gate 检查（便捷函数） */
+export function checkEvolutionGate(workspaceDir, context) {
+    return getEvolutionEngine(workspaceDir).beforeToolCall(context);
+}