principles-disciple 1.127.0 → 1.129.0

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

@@ -0,0 +1,137 @@
+/**
+ * EvolutionLogger - 进化流程日志服务
+ *
+ * 提供两层日志：
+ * - 技术层：结构化 JSON，包含 trace_id、stage、metadata
+ * - 用户层：中文摘要，便于小白用户理解
+ *
+ * 日志写入两个地方：
+ * 1. SYSTEM_LOG (system.jsonl) - 技术细节
+ * 2. evolution_events 表 (SQLite) - 结构化查询
+ */
+import type { TrajectoryDatabase } from './trajectory.js';
+export type EvolutionStage = 'pain_detected' | 'queued' | 'started' | 'analyzing' | 'principle_generated' | 'completed' | 'failed';
+export type EvolutionLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface EvolutionLogEntry {
+    traceId: string;
+    stage: EvolutionStage;
+    level: EvolutionLogLevel;
+    message: string;
+    summary: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+    taskId?: string;
+    sessionId?: string;
+}
+export interface EvolutionLogInput {
+    traceId: string;
+    stage: EvolutionStage;
+    level?: EvolutionLogLevel;
+    message: string;
+    summary: string;
+    metadata?: Record<string, unknown>;
+    taskId?: string;
+    sessionId?: string;
+}
+export declare const STAGE_LABELS: Record<EvolutionStage, string>;
+export declare const STAGE_COLORS: Record<EvolutionStage, string>;
+/**
+ * 创建新的 trace_id
+ * 格式: ev_{timestamp}_{random}
+ * 使用 crypto.randomBytes 确保不可预测性
+ */
+export declare function createTraceId(): string;
+/**
+ * EvolutionLogger 类
+ * 管理进化流程的日志记录
+ */
+export declare class EvolutionLogger {
+    private readonly workspaceDir;
+    private readonly trajectory;
+    constructor(workspaceDir: string, trajectory?: TrajectoryDatabase);
+    /**
+     * 记录进化事件
+     * 同时写入 SYSTEM_LOG 和 evolution_events 表
+     */
+    log(input: EvolutionLogInput): void;
+    /**
+     * 记录 pain_detected 事件
+     */
+    logPainDetected(params: {
+        traceId: string;
+        source: string;
+        reason: string;
+        score: number;
+        toolName?: string;
+        filePath?: string;
+        sessionId?: string;
+    }): void;
+    /**
+     * 记录 queued 事件
+     */
+    logQueued(params: {
+        traceId: string;
+        taskId: string;
+        score: number;
+        source: string;
+        reason: string;
+    }): void;
+    /**
+     * 记录 started 事件
+     */
+    logStarted(params: {
+        traceId: string;
+        taskId: string;
+    }): void;
+    /**
+     * 记录 analyzing 事件
+     */
+    logAnalyzing(params: {
+        traceId: string;
+        taskId: string;
+        analysisType?: string;
+    }): void;
+    /**
+     * 记录 principle_generated 事件
+     */
+    logPrincipleGenerated(params: {
+        traceId: string;
+        taskId: string;
+        principleId: string;
+        principleText: string;
+    }): void;
+    /**
+     * 记录 completed 事件
+     */
+    logCompleted(params: {
+        traceId: string;
+        taskId: string;
+        resolution: 'marker_detected' | 'auto_completed_timeout' | 'manual' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'diagnostician_timeout' | 'noise_classified' | 'duplicate' | 'serverDuplicate';
+        durationMs?: number;
+        principlesGenerated?: number;
+    }): void;
+    /**
+     * 记录 failed 事件
+     */
+    logFailed(params: {
+        traceId: string;
+        taskId: string;
+        error: string;
+        stack?: string;
+    }): void;
+}
+/**
+ * 获取 EvolutionLogger 实例（单例）
+ *
+ * 注意：带 trajectory 和不带 trajectory 的请求会返回不同的实例，
+ * 因为 trajectory 影响事件持久化行为。
+ */
+export declare function getEvolutionLogger(workspaceDir: string, trajectory?: TrajectoryDatabase): EvolutionLogger;
+/**
+ * 清理指定 workspace 的 logger 缓存
+ */
+export declare function disposeEvolutionLogger(workspaceDir: string): boolean;
+/**
+ * 清理所有 logger 缓存（用于测试或进程退出）
+ */
+export declare function disposeAllEvolutionLoggers(): void;

package/dist/core/evolution-logger.js

@@ -0,0 +1,261 @@
+/**
+ * EvolutionLogger - 进化流程日志服务
+ *
+ * 提供两层日志：
+ * - 技术层：结构化 JSON，包含 trace_id、stage、metadata
+ * - 用户层：中文摘要，便于小白用户理解
+ *
+ * 日志写入两个地方：
+ * 1. SYSTEM_LOG (system.jsonl) - 技术细节
+ * 2. evolution_events 表 (SQLite) - 结构化查询
+ */
+import { randomBytes } from 'crypto';
+import { SystemLogger } from './system-logger.js';
+// 阶段对应的中文标签
+export const STAGE_LABELS = {
+    pain_detected: '痛点检测',
+    queued: '加入队列',
+    started: '开始处理',
+    analyzing: '分析中',
+    principle_generated: '原则生成',
+    completed: '完成',
+    failed: '失败',
+};
+// 阶段对应的颜色（用于 UI）
+export const STAGE_COLORS = {
+    pain_detected: '#ef4444', // 红色
+    queued: '#f59e0b', // 橙色
+    started: '#3b82f6', // 蓝色
+    analyzing: '#8b5cf6', // 紫色
+    principle_generated: '#10b981', // 绿色
+    completed: '#22c55e', // 绿色
+    failed: '#dc2626', // 深红色
+};
+/**
+ * 创建新的 trace_id
+ * 格式: ev_{timestamp}_{random}
+ * 使用 crypto.randomBytes 确保不可预测性
+ */
+export function createTraceId() {
+    const timestamp = Date.now().toString(36);
+    const random = randomBytes(3).toString('hex');
+    return `ev_${timestamp}_${random}`;
+}
+/**
+ * EvolutionLogger 类
+ * 管理进化流程的日志记录
+ */
+export class EvolutionLogger {
+    workspaceDir;
+    trajectory;
+    constructor(workspaceDir, trajectory) {
+        this.workspaceDir = workspaceDir;
+        this.trajectory = trajectory || null;
+    }
+    /**
+     * 记录进化事件
+     * 同时写入 SYSTEM_LOG 和 evolution_events 表
+     */
+    log(input) {
+        const entry = {
+            ...input,
+            level: input.level || 'info',
+            timestamp: new Date().toISOString(),
+        };
+        // 1. 写入 SYSTEM_LOG (技术细节)
+        SystemLogger.log(this.workspaceDir, 'EVOLUTION', JSON.stringify({
+            traceId: entry.traceId,
+            stage: entry.stage,
+            level: entry.level,
+            message: entry.message,
+            taskId: entry.taskId,
+            sessionId: entry.sessionId,
+            metadata: entry.metadata,
+        }));
+        // 2. 写入 evolution_events 表 (如果有 trajectory)
+        if (this.trajectory) {
+            try {
+                this.trajectory.recordEvolutionEvent({
+                    traceId: entry.traceId,
+                    taskId: entry.taskId,
+                    stage: entry.stage,
+                    level: entry.level,
+                    message: entry.message,
+                    summary: entry.summary,
+                    metadata: entry.metadata,
+                    createdAt: entry.timestamp,
+                });
+            }
+            catch (err) {
+                // Database write failure doesn't affect main flow, but log for diagnostics
+                console.error(`[EvolutionLogger] Failed to write to trajectory: ${String(err)}`);
+            }
+        }
+    }
+    /**
+     * 记录 pain_detected 事件
+     */
+    logPainDetected(params) {
+        this.log({
+            traceId: params.traceId,
+            stage: 'pain_detected',
+            level: 'info',
+            message: `Pain detected: ${params.source} - ${params.reason}`,
+            summary: `检测到痛点：${params.source} - ${params.reason}`,
+            metadata: {
+                score: params.score,
+                toolName: params.toolName,
+                filePath: params.filePath,
+            },
+            sessionId: params.sessionId,
+        });
+    }
+    /**
+     * 记录 queued 事件
+     */
+    logQueued(params) {
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'queued',
+            level: 'info',
+            message: `Task ${params.taskId} enqueued with score ${params.score}`,
+            summary: `任务 ${params.taskId} 已加入进化队列，优先级分数 ${params.score}`,
+            metadata: {
+                score: params.score,
+                source: params.source,
+                reason: params.reason,
+            },
+        });
+    }
+    /**
+     * 记录 started 事件
+     */
+    logStarted(params) {
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'started',
+            level: 'info',
+            message: `Task ${params.taskId} started processing`,
+            summary: `任务 ${params.taskId} 开始处理，Diagnostician 正在分析...`,
+        });
+    }
+    /**
+     * 记录 analyzing 事件
+     */
+    logAnalyzing(params) {
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'analyzing',
+            level: 'info',
+            message: `Task ${params.taskId} analysis started`,
+            summary: `任务 ${params.taskId} 正在分析根因...`,
+            metadata: {
+                analysisType: params.analysisType,
+            },
+        });
+    }
+    /**
+     * 记录 principle_generated 事件
+     */
+    logPrincipleGenerated(params) {
+        const truncatedText = params.principleText.length > 100
+            ? params.principleText.substring(0, 100) + '...'
+            : params.principleText;
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'principle_generated',
+            level: 'info',
+            message: `Principle ${params.principleId} generated for task ${params.taskId}`,
+            summary: `生成新原则：${truncatedText}`,
+            metadata: {
+                principleId: params.principleId,
+                principleText: params.principleText,
+            },
+        });
+    }
+    /**
+     * 记录 completed 事件
+     */
+    logCompleted(params) {
+        let summary;
+        if (params.resolution === 'marker_detected' || params.resolution === 'late_marker_principle_created') {
+            summary = `任务 ${params.taskId} 完成，已生成 ${params.principlesGenerated || 0} 条原则`;
+        }
+        else if (params.resolution === 'auto_completed_timeout' || params.resolution === 'diagnostician_timeout' || params.resolution === 'late_marker_no_principle') {
+            summary = `任务 ${params.taskId} 超时自动完成`;
+        }
+        else if (params.resolution === 'noise_classified' || params.resolution === 'duplicate' || params.resolution === 'serverDuplicate') {
+            summary = `任务 ${params.taskId} 分类为噪音/重复，已过滤`;
+        }
+        else {
+            summary = `任务 ${params.taskId} 已完成`;
+        }
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'completed',
+            level: params.resolution === 'auto_completed_timeout' ? 'warn' : 'info',
+            message: `Task ${params.taskId} completed with resolution: ${params.resolution}`,
+            summary,
+            metadata: {
+                resolution: params.resolution,
+                durationMs: params.durationMs,
+                principlesGenerated: params.principlesGenerated,
+            },
+        });
+    }
+    /**
+     * 记录 failed 事件
+     */
+    logFailed(params) {
+        this.log({
+            traceId: params.traceId,
+            taskId: params.taskId,
+            stage: 'failed',
+            level: 'error',
+            message: `Task ${params.taskId} failed: ${params.error}`,
+            summary: `任务 ${params.taskId} 失败：${params.error}`,
+            metadata: {
+                error: params.error,
+                stack: params.stack,
+            },
+        });
+    }
+}
+// 单例缓存：键格式为 "workspaceDir" 或 "workspaceDir::with_trajectory"
+const loggerCache = new Map();
+/**
+ * 获取 EvolutionLogger 实例（单例）
+ *
+ * 注意：带 trajectory 和不带 trajectory 的请求会返回不同的实例，
+ * 因为 trajectory 影响事件持久化行为。
+ */
+export function getEvolutionLogger(workspaceDir, trajectory) {
+    // 缓存键区分是否带 trajectory，避免持久化行为不一致
+    const cacheKey = trajectory ? `${workspaceDir}::with_trajectory` : workspaceDir;
+    const cached = loggerCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const logger = new EvolutionLogger(workspaceDir, trajectory);
+    loggerCache.set(cacheKey, logger);
+    return logger;
+}
+/**
+ * 清理指定 workspace 的 logger 缓存
+ */
+export function disposeEvolutionLogger(workspaceDir) {
+    const plain = loggerCache.delete(workspaceDir);
+    const withTrajectory = loggerCache.delete(`${workspaceDir}::with_trajectory`);
+    return plain || withTrajectory;
+}
+/**
+ * 清理所有 logger 缓存（用于测试或进程退出）
+ */
+export function disposeAllEvolutionLoggers() {
+    loggerCache.clear();
+}

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

@@ -0,0 +1,5 @@
+export interface MigrationResult {
+    importedEvents: number;
+    streamPath: string;
+}
+export declare function migrateLegacyEvolutionData(workspaceDir: string): MigrationResult;

package/dist/core/evolution-migration.js

@@ -0,0 +1,65 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { stableContentHash } from './evolution-reducer.js';
+import { SystemLogger } from './system-logger.js';
+function appendEvent(streamPath, event) {
+    fs.appendFileSync(streamPath, `${JSON.stringify(event)}\n`, 'utf8');
+}
+function loadImportedHashes(streamPath, workspaceDir) {
+    if (!fs.existsSync(streamPath))
+        return new Set();
+    const raw = fs.readFileSync(streamPath, 'utf8').trim();
+    if (!raw)
+        return new Set();
+    const hashes = new Set();
+    for (const line of raw.split('\n')) {
+        try {
+            const event = JSON.parse(line);
+            if (event.type !== 'legacy_import')
+                continue;
+            const hash = event.data.contentHash;
+            if (typeof hash === 'string')
+                hashes.add(hash);
+        }
+        catch (e) {
+            SystemLogger.log(workspaceDir, 'MIGRATION_WARN', `skip malformed line: ${String(e)}`);
+        }
+    }
+    return hashes;
+}
+export function migrateLegacyEvolutionData(workspaceDir) {
+    const streamPath = path.join(workspaceDir, 'memory', 'evolution.jsonl');
+    fs.mkdirSync(path.dirname(streamPath), { recursive: true });
+    const candidates = [
+        path.join(workspaceDir, 'memory', 'ISSUE_LOG.md'),
+        path.join(workspaceDir, 'memory', 'DECISIONS.md'),
+        path.join(workspaceDir, '.principles', 'PRINCIPLES.md'),
+    ];
+    const existingHashes = loadImportedHashes(streamPath, workspaceDir);
+    let importedEvents = 0;
+    for (const sourceFile of candidates) {
+        if (!fs.existsSync(sourceFile)) {
+            continue;
+        }
+        const content = fs.readFileSync(sourceFile, 'utf8').trim();
+        if (!content) {
+            continue;
+        }
+        const contentHash = stableContentHash(`${sourceFile}:${content}`);
+        if (existingHashes.has(contentHash)) {
+            continue;
+        }
+        appendEvent(streamPath, {
+            ts: new Date().toISOString(),
+            type: 'legacy_import',
+            data: {
+                sourceFile: path.relative(workspaceDir, sourceFile),
+                content,
+                contentHash,
+            },
+        });
+        importedEvents += 1;
+        existingHashes.add(contentHash);
+    }
+    return { importedEvents, streamPath };
+}

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

@@ -0,0 +1,124 @@
+import type { EvolutionLoopEvent, Principle, PrincipleDetectorSpec, PrincipleEvaluatorLevel, PrincipleSuggestedRule } from './evolution-types.js';
+export interface EvolutionReducer {
+    emit(_event: EvolutionLoopEvent): void;
+    emitSync(_event: EvolutionLoopEvent): void;
+    getEventLog(): EvolutionLoopEvent[];
+    getCandidatePrinciples(): Principle[];
+    getProbationPrinciples(): Principle[];
+    getActivePrinciples(): Principle[];
+    getPrincipleById(_id: string): Principle | null;
+    promote(_principleId: string, _reason?: string): void;
+    deprecate(_principleId: string, _reason: string): void;
+    rollbackPrinciple(_principleId: string, _reason: string): void;
+    recordProbationFeedback(_principleId: string, _success: boolean): void;
+    /**
+     * Creates a new principle with generalized trigger/action from diagnostician.
+     * Called after diagnostician analysis to create principle directly.
+     */
+    createPrincipleFromDiagnosis(params: {
+        painId: string;
+        painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+        triggerPattern: string;
+        action: string;
+        source: string;
+        evaluability?: PrincipleEvaluatorLevel;
+        detectorMetadata?: PrincipleDetectorSpec;
+        /** Highly abstracted principle text — if absent, falls back to action-based title */
+        abstractedPrinciple?: string;
+        /** Associated core axiom (e.g., "T-01") */
+        coreAxiomId?: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        scope?: 'general' | 'domain';
+        domain?: string;
+        suggestedRules?: PrincipleSuggestedRule[];
+    }): string | null;
+    getStats(): {
+        candidateCount: number;
+        probationCount: number;
+        activeCount: number;
+        deprecatedCount: number;
+        lastPromotedAt: string | null;
+    };
+}
+export declare class EvolutionReducerImpl implements EvolutionReducer {
+    private readonly streamPath;
+    private readonly lockTargetPath;
+    private readonly blacklistPath;
+    private readonly principlesPath;
+    private readonly workspaceDir;
+    private readonly stateDir;
+    private readonly memoryEvents;
+    private readonly principles;
+    private readonly failureStreak;
+    private lastPromotedAt;
+    private isReplaying;
+    /** Registered pain_detected callbacks (e.g., PainSignalBridge). */
+    private readonly _painCallbacks;
+    constructor(opts: {
+        workspaceDir: string;
+        stateDir?: string;
+    });
+    emit(event: EvolutionLoopEvent): void;
+    emitSync(event: EvolutionLoopEvent): void;
+    /**
+     * Register a callback for 'pain_detected' events.
+     * The callback is invoked synchronously within emitSync() after applyEvent completes.
+     * HG-4: Callbacks are fire-and-forget from the emitSync perspective.
+     */
+    on(callback: (event: EvolutionLoopEvent) => void): void;
+    getEventLog(): EvolutionLoopEvent[];
+    getCandidatePrinciples(): Principle[];
+    getProbationPrinciples(): Principle[];
+    getActivePrinciples(): Principle[];
+    getPrincipleById(id: string): Principle | null;
+    promote(principleId: string, reason?: string): void;
+    deprecate(principleId: string, reason: string): void;
+    rollbackPrinciple(principleId: string, reason: string): void;
+    recordProbationFeedback(principleId: string, success: boolean): void;
+    /**
+     * Creates a new principle with generalized trigger/action from diagnostician.
+     * Called after diagnostician analysis to create principle directly (no intermediate overfitted principle).
+     * @returns the new principle ID, or null if creation failed
+     */
+    createPrincipleFromDiagnosis(params: {
+        painId: string;
+        painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+        triggerPattern: string;
+        action: string;
+        source: string;
+        evaluability?: PrincipleEvaluatorLevel;
+        detectorMetadata?: PrincipleDetectorSpec;
+        abstractedPrinciple?: string;
+        coreAxiomId?: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        scope?: 'general' | 'domain';
+        domain?: string;
+        suggestedRules?: PrincipleSuggestedRule[];
+    }): string | null;
+    private syncPrincipleToFile;
+    private static detectPrincipleLanguage;
+    private static formatPrincipleForFile;
+    getStats(): {
+        candidateCount: number;
+        probationCount: number;
+        activeCount: number;
+        deprecatedCount: number;
+        lastPromotedAt: string | null;
+    };
+    private ensureDirs;
+    private loadFromStream;
+    private applyEvent;
+    private onCandidateCreated;
+    private onPrinciplePromoted;
+    private onPrincipleDeprecated;
+    private onPrincipleRolledBack;
+    private onPainDetected;
+    private updateFailureStreakFromPain;
+    private nextPrincipleId;
+    private getByStatus;
+    private sweepExpiredProbation;
+    private persistBlacklist;
+    private loadBlacklist;
+    private isBlacklisted;
+}
+export declare function stableContentHash(input: string): string;