autosnippet 3.3.4 → 3.3.6

package/dist/lib/service/evolution/ProposalExecutor.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ProposalExecutor — 到期自动执行引擎
+ *
+ * 核心职责：
+ *   1. 扫描所有 observing 状态的 Proposal，检查是否到期
+ *   2. 到期 → 收集观察期表现数据 → 评估执行判据
+ *   3. 通过 → 执行操作（merge/deprecate/enhance/...）
+ *   4. 不通过 → 拒绝 Proposal，Recipe 恢复原状态
+ *
+ * 触发时机：UiStartupTasks Stage 5
+ *
+ * 安全边界：
+ *   - Agent 只做分析，ProposalExecutor 做执行
+ *   - merge/enhance 执行后 Recipe → staging（走正常路径）
+ *   - contradiction/reorganize 始终等开发者确认（不自动执行）
+ *   - 到期无判据 → expired
+ */
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
+import type { ProposalRepository, ProposalType } from '../../repository/evolution/ProposalRepository.js';
+import type { ContentPatcher } from './ContentPatcher.js';
+import type { RecipeLifecycleSupervisor } from './RecipeLifecycleSupervisor.js';
+interface DatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): Record<string, unknown>[];
+        get(...params: unknown[]): Record<string, unknown> | undefined;
+        run(...params: unknown[]): {
+            changes: number;
+        };
+    };
+}
+export interface ProposalExecutionResult {
+    executed: {
+        id: string;
+        type: ProposalType;
+        targetRecipeId: string;
+    }[];
+    rejected: {
+        id: string;
+        type: ProposalType;
+        reason: string;
+    }[];
+    expired: {
+        id: string;
+        type: ProposalType;
+    }[];
+    skipped: {
+        id: string;
+        type: ProposalType;
+        reason: string;
+    }[];
+}
+export declare class ProposalExecutor {
+    #private;
+    constructor(db: DatabaseLike, repo: ProposalRepository, options?: {
+        signalBus?: SignalBus;
+        contentPatcher?: ContentPatcher;
+        supervisor?: RecipeLifecycleSupervisor;
+    });
+    /**
+     * 定期调用（UiStartupTasks Stage 5）
+     *
+     * 扫描所有到期 Proposal → 评估 → 执行/拒绝/过期
+     */
+    checkAndExecute(): ProposalExecutionResult;
+}
+export {};

package/dist/lib/service/evolution/ProposalExecutor.js

@@ -0,0 +1,424 @@
+/**
+ * ProposalExecutor — 到期自动执行引擎
+ *
+ * 核心职责：
+ *   1. 扫描所有 observing 状态的 Proposal，检查是否到期
+ *   2. 到期 → 收集观察期表现数据 → 评估执行判据
+ *   3. 通过 → 执行操作（merge/deprecate/enhance/...）
+ *   4. 不通过 → 拒绝 Proposal，Recipe 恢复原状态
+ *
+ * 触发时机：UiStartupTasks Stage 5
+ *
+ * 安全边界：
+ *   - Agent 只做分析，ProposalExecutor 做执行
+ *   - merge/enhance 执行后 Recipe → staging（走正常路径）
+ *   - contradiction/reorganize 始终等开发者确认（不自动执行）
+ *   - 到期无判据 → expired
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+/* ────────────────────── Constants ────────────────────── */
+/** 高风险类型：需开发者确认，不自动执行 */
+const HIGH_RISK_TYPES = new Set(['contradiction', 'reorganize']);
+/** 超过此天数未操作的 pending Proposal 自动过期 */
+const PENDING_EXPIRY_DAYS = 14;
+/* ────────────────────── Class ────────────────────── */
+export class ProposalExecutor {
+    #db;
+    #repo;
+    #signalBus;
+    #contentPatcher;
+    #supervisor;
+    #logger = Logger.getInstance();
+    constructor(db, repo, options = {}) {
+        this.#db = db;
+        this.#repo = repo;
+        this.#signalBus = options.signalBus ?? null;
+        this.#contentPatcher = options.contentPatcher ?? null;
+        this.#supervisor = options.supervisor ?? null;
+    }
+    /**
+     * 定期调用（UiStartupTasks Stage 5）
+     *
+     * 扫描所有到期 Proposal → 评估 → 执行/拒绝/过期
+     */
+    checkAndExecute() {
+        const result = {
+            executed: [],
+            rejected: [],
+            expired: [],
+            skipped: [],
+        };
+        // 1. 处理到期的 observing Proposal
+        const expiredObserving = this.#repo.findExpiredObserving();
+        for (const proposal of expiredObserving) {
+            if (HIGH_RISK_TYPES.has(proposal.type)) {
+                // 高风险类型跳过自动执行
+                result.skipped.push({
+                    id: proposal.id,
+                    type: proposal.type,
+                    reason: 'high-risk type requires developer confirmation',
+                });
+                continue;
+            }
+            this.#processExpiredProposal(proposal, result);
+        }
+        // 2. 清理超期未操作的 pending Proposal
+        this.#expireOldPending(result);
+        if (result.executed.length > 0 || result.rejected.length > 0 || result.expired.length > 0) {
+            this.#logger.info(`[ProposalExecutor] checkAndExecute complete: ` +
+                `executed=${result.executed.length}, rejected=${result.rejected.length}, expired=${result.expired.length}`);
+        }
+        return result;
+    }
+    /* ═══════════════════ Internal ═══════════════════ */
+    #processExpiredProposal(proposal, result) {
+        const metrics = this.#collectRecipeMetrics(proposal.targetRecipeId);
+        const snapshot = this.#extractSnapshot(proposal);
+        switch (proposal.type) {
+            case 'merge':
+            case 'enhance':
+                this.#executeMergeOrEnhance(proposal, metrics, snapshot, result);
+                break;
+            case 'supersede':
+                this.#executeSupersede(proposal, metrics, snapshot, result);
+                break;
+            case 'deprecate':
+                this.#executeDeprecate(proposal, metrics, snapshot, result);
+                break;
+            case 'correction':
+                this.#executeCorrection(proposal, metrics, result);
+                break;
+            default:
+                result.skipped.push({
+                    id: proposal.id,
+                    type: proposal.type,
+                    reason: `unhandled type: ${proposal.type}`,
+                });
+        }
+    }
+    /* ── merge / enhance ── */
+    #executeMergeOrEnhance(proposal, metrics, snapshot, result) {
+        // 执行判据：
+        //   - 目标 Recipe 在观察期内无 FP rate 异常飙升
+        //   - 目标 Recipe 在观察期内仍有使用
+        const fpOk = metrics.ruleFalsePositiveRate < 0.4;
+        const hasUsage = metrics.guardHits > 0 || metrics.searchHits > 0;
+        if (fpOk && hasUsage) {
+            // 通过 → evolving → ContentPatcher → staging（重走 Grace Period）
+            this.#transitionRecipe(proposal.targetRecipeId, 'evolving', 'proposal-attach', proposal.id);
+            const patchResult = this.#tryApplyPatch(proposal, 'agent-suggestion');
+            if (patchResult?.skipped || (!patchResult?.success && patchResult !== null)) {
+                // Patch 跳过或失败 → 回退到 active，避免无变更进入 staging 导致空进化循环
+                this.#transitionRecipe(proposal.targetRecipeId, 'active', 'content-patch-complete', proposal.id);
+                const skipInfo = patchResult?.skipReason ? `: ${patchResult.skipReason}` : '';
+                this.#repo.markExecuted(proposal.id, `观察期合格但 patch 未生效${skipInfo}, 回退 active`);
+            }
+            else {
+                this.#transitionRecipe(proposal.targetRecipeId, 'staging', 'content-patch-complete', proposal.id);
+                const patchInfo = patchResult?.success
+                    ? `, patched=[${patchResult.fieldsPatched.join(',')}]`
+                    : '';
+                this.#repo.markExecuted(proposal.id, `观察期表现合格: FP=${(metrics.ruleFalsePositiveRate * 100).toFixed(0)}%, hits=${metrics.guardHits + metrics.searchHits}${patchInfo}`);
+            }
+            result.executed.push({
+                id: proposal.id,
+                type: proposal.type,
+                targetRecipeId: proposal.targetRecipeId,
+            });
+            this.#emitSignal(proposal, 'executed');
+        }
+        else {
+            // 不通过 → Recipe 恢复原状态
+            this.#restoreRecipe(proposal.targetRecipeId);
+            this.#repo.markRejected(proposal.id, `观察期表现不达标: FP=${(metrics.ruleFalsePositiveRate * 100).toFixed(0)}%, hasUsage=${hasUsage}`);
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: fpOk ? 'no usage during observation' : 'FP rate too high',
+            });
+            this.#emitSignal(proposal, 'rejected');
+        }
+    }
+    /* ── supersede ── */
+    #executeSupersede(proposal, metrics, snapshot, result) {
+        // 新 Recipe 必须已到达 active
+        const newRecipeId = proposal.relatedRecipeIds[0];
+        if (!newRecipeId) {
+            this.#repo.markRejected(proposal.id, 'no related new recipe specified');
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: 'no related new recipe',
+            });
+            return;
+        }
+        const newRecipe = this.#getRecipeLifecycle(newRecipeId);
+        if (newRecipe?.lifecycle !== 'active') {
+            // 新 Recipe 尚未 active → 跳过，等下次检查
+            result.skipped.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: `new recipe ${newRecipeId} not yet active (lifecycle: ${newRecipe?.lifecycle ?? 'unknown'})`,
+            });
+            return;
+        }
+        // 对比新旧 Recipe 的使用数据
+        const newMetrics = this.#collectRecipeMetrics(newRecipeId);
+        const oldUsage = metrics.guardHits + metrics.searchHits;
+        const newUsage = newMetrics.guardHits + newMetrics.searchHits;
+        if (newUsage >= oldUsage * 0.5 || oldUsage === 0) {
+            // 新 Recipe 表现足够 → 旧 Recipe → decaying，建立 deprecated_by
+            this.#transitionRecipe(proposal.targetRecipeId, 'decaying', 'proposal-execution', proposal.id);
+            this.#createDeprecatedByEdge(newRecipeId, proposal.targetRecipeId);
+            this.#repo.markExecuted(proposal.id, `supersede executed: new usage=${newUsage}, old usage=${oldUsage}`);
+            result.executed.push({
+                id: proposal.id,
+                type: proposal.type,
+                targetRecipeId: proposal.targetRecipeId,
+            });
+            this.#emitSignal(proposal, 'executed');
+        }
+        else {
+            // 新 Recipe 表现不足 → 拒绝
+            this.#restoreRecipe(proposal.targetRecipeId);
+            this.#repo.markRejected(proposal.id, `new recipe usage (${newUsage}) < 50% of old (${oldUsage})`);
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: 'new recipe insufficient usage',
+            });
+            this.#emitSignal(proposal, 'rejected');
+        }
+    }
+    /* ── deprecate ── */
+    #executeDeprecate(proposal, metrics, snapshot, result) {
+        const currentDecay = metrics.decayScore;
+        const snapshotDecay = snapshot?.decayScore ?? currentDecay;
+        // 观察期内 decayScore 有回升 → 拒绝
+        if (currentDecay > snapshotDecay + 10) {
+            this.#restoreRecipe(proposal.targetRecipeId);
+            this.#repo.markRejected(proposal.id, `decayScore recovered: ${snapshotDecay} → ${currentDecay}`);
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: 'decay score recovered during observation',
+            });
+            this.#emitSignal(proposal, 'rejected');
+            return;
+        }
+        // 无回升 → 根据 decayScore 决定操作
+        if (currentDecay <= 19) {
+            // 死亡 → 直接 deprecated
+            this.#transitionRecipe(proposal.targetRecipeId, 'deprecated', 'proposal-execution', proposal.id);
+            this.#repo.markExecuted(proposal.id, `deprecated (dead): decayScore=${currentDecay}`);
+        }
+        else if (currentDecay <= 40) {
+            // 严重 → decaying
+            this.#transitionRecipe(proposal.targetRecipeId, 'decaying', 'proposal-execution', proposal.id);
+            this.#repo.markExecuted(proposal.id, `decaying (severe): decayScore=${currentDecay}`);
+        }
+        else {
+            // 衰退减缓 → 拒绝
+            this.#restoreRecipe(proposal.targetRecipeId);
+            this.#repo.markRejected(proposal.id, `decayScore above threshold (${currentDecay}), not critical enough`);
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: `decayScore (${currentDecay}) not critical`,
+            });
+            this.#emitSignal(proposal, 'rejected');
+            return;
+        }
+        result.executed.push({
+            id: proposal.id,
+            type: proposal.type,
+            targetRecipeId: proposal.targetRecipeId,
+        });
+        this.#emitSignal(proposal, 'executed');
+    }
+    /* ── correction ── */
+    #executeCorrection(proposal, metrics, result) {
+        // correction 低风险，到期直接执行（Recipe → evolving → patch → staging 重新审核）
+        const hasUsage = metrics.guardHits > 0 || metrics.searchHits > 0;
+        if (hasUsage) {
+            this.#transitionRecipe(proposal.targetRecipeId, 'evolving', 'proposal-attach', proposal.id);
+            const patchResult = this.#tryApplyPatch(proposal, 'correction');
+            if (patchResult?.skipped || (!patchResult?.success && patchResult !== null)) {
+                // Patch 跳过或失败 → 回退到 active
+                this.#transitionRecipe(proposal.targetRecipeId, 'active', 'content-patch-complete', proposal.id);
+                const skipInfo = patchResult?.skipReason ? `: ${patchResult.skipReason}` : '';
+                this.#repo.markExecuted(proposal.id, `correction patch 未生效${skipInfo}, 回退 active`);
+            }
+            else {
+                this.#transitionRecipe(proposal.targetRecipeId, 'staging', 'content-patch-complete', proposal.id);
+                const patchInfo = patchResult?.success
+                    ? `, patched=[${patchResult.fieldsPatched.join(',')}]`
+                    : '';
+                this.#repo.markExecuted(proposal.id, `correction applied, recipe → evolving → staging for re-review${patchInfo}`);
+            }
+            result.executed.push({
+                id: proposal.id,
+                type: proposal.type,
+                targetRecipeId: proposal.targetRecipeId,
+            });
+            this.#emitSignal(proposal, 'executed');
+        }
+        else {
+            this.#repo.markRejected(proposal.id, 'no usage during observation, correction unnecessary');
+            result.rejected.push({
+                id: proposal.id,
+                type: proposal.type,
+                reason: 'no usage',
+            });
+            this.#emitSignal(proposal, 'rejected');
+        }
+    }
+    /* ── expired pending cleanup ── */
+    #expireOldPending(result) {
+        const cutoff = Date.now() - PENDING_EXPIRY_DAYS * 24 * 60 * 60 * 1000;
+        const oldPending = this.#repo.find({
+            status: 'pending',
+            expiredBefore: cutoff,
+        });
+        for (const proposal of oldPending) {
+            this.#repo.markExpired(proposal.id);
+            result.expired.push({
+                id: proposal.id,
+                type: proposal.type,
+            });
+        }
+    }
+    /* ═══════════════════ DB Helpers ═══════════════════ */
+    #collectRecipeMetrics(recipeId) {
+        const row = this.#db
+            .prepare(`SELECT stats, quality FROM knowledge_entries WHERE id = ?`)
+            .get(recipeId);
+        if (!row) {
+            return {
+                guardHits: 0,
+                searchHits: 0,
+                hitsLast30d: 0,
+                decayScore: 0,
+                ruleFalsePositiveRate: 0,
+                quality: 0,
+            };
+        }
+        const stats = safeJsonParse(row.stats, {});
+        const quality = safeJsonParse(row.quality, {});
+        return {
+            guardHits: stats.guardHits ?? 0,
+            searchHits: stats.searchHits ?? 0,
+            hitsLast30d: stats.hitsLast30d ?? 0,
+            decayScore: stats.decayScore ?? 50,
+            ruleFalsePositiveRate: stats.ruleFalsePositiveRate ?? 0,
+            quality: quality.overall ?? 0,
+        };
+    }
+    #extractSnapshot(proposal) {
+        for (const ev of proposal.evidence) {
+            if (ev.snapshotAt && ev.metrics) {
+                const m = ev.metrics;
+                return {
+                    guardHits: m.guardHits ?? 0,
+                    searchHits: m.searchHits ?? 0,
+                    hitsLast30d: m.hitsLast30d ?? 0,
+                    decayScore: m.decayScore ?? 50,
+                    ruleFalsePositiveRate: m.ruleFalsePositiveRate ?? 0,
+                    quality: m.quality?.overall ?? 0,
+                };
+            }
+        }
+        return null;
+    }
+    #getRecipeLifecycle(recipeId) {
+        const row = this.#db
+            .prepare(`SELECT lifecycle FROM knowledge_entries WHERE id = ?`)
+            .get(recipeId);
+        return row ?? null;
+    }
+    #transitionRecipe(recipeId, newLifecycle, trigger = 'proposal-execution', proposalId) {
+        if (this.#supervisor) {
+            const result = this.#supervisor.transition({
+                recipeId,
+                targetState: newLifecycle,
+                trigger,
+                proposalId,
+                operatorId: 'system',
+            });
+            if (!result.success) {
+                this.#logger.warn(`[ProposalExecutor] Supervisor rejected transition ${recipeId} → ${newLifecycle}: ${result.error}`);
+                // Fallback to raw DB update for backward compatibility
+                this.#db
+                    .prepare(`UPDATE knowledge_entries SET lifecycle = ?, updatedAt = ? WHERE id = ?`)
+                    .run(newLifecycle, Date.now(), recipeId);
+            }
+        }
+        else {
+            this.#db
+                .prepare(`UPDATE knowledge_entries SET lifecycle = ?, updatedAt = ? WHERE id = ?`)
+                .run(newLifecycle, Date.now(), recipeId);
+        }
+    }
+    #restoreRecipe(recipeId) {
+        // 恢复到 active（evolving/decaying → active）
+        const current = this.#getRecipeLifecycle(recipeId);
+        if (current && (current.lifecycle === 'evolving' || current.lifecycle === 'decaying')) {
+            this.#transitionRecipe(recipeId, 'active');
+        }
+    }
+    /**
+     * 尝试通过 ContentPatcher 应用 Proposal 中的 suggestedChanges
+     * 降级容忍：无 ContentPatcher 或 patch 失败时返回 null/skipped，不阻塞状态转移
+     */
+    #tryApplyPatch(proposal, patchSource) {
+        if (!this.#contentPatcher) {
+            return null;
+        }
+        try {
+            return this.#contentPatcher.applyProposal(proposal, patchSource);
+        }
+        catch (err) {
+            this.#logger.warn(`[ProposalExecutor] ContentPatcher failed for proposal ${proposal.id}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    #createDeprecatedByEdge(newRecipeId, oldRecipeId) {
+        const now = Date.now();
+        try {
+            this.#db
+                .prepare(`INSERT OR IGNORE INTO knowledge_edges (from_id, from_type, to_id, to_type, relation, weight, metadata_json, created_at, updated_at)
+           VALUES (?, 'recipe', ?, 'recipe', 'deprecated_by', 1.0, '{}', ?, ?)`)
+                .run(newRecipeId, oldRecipeId, now, now);
+        }
+        catch {
+            // knowledge_edges 表可能不存在（降级容忍）
+        }
+    }
+    /* ═══════════════════ Signal ═══════════════════ */
+    #emitSignal(proposal, action) {
+        if (!this.#signalBus) {
+            return;
+        }
+        this.#signalBus.send('lifecycle', 'ProposalExecutor', proposal.confidence, {
+            target: proposal.targetRecipeId,
+            metadata: {
+                proposalId: proposal.id,
+                proposalType: proposal.type,
+                action,
+                source: proposal.source,
+            },
+        });
+    }
+}
+/* ────────────────────── Util ────────────────────── */
+function safeJsonParse(json, fallback) {
+    if (!json) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/lib/service/evolution/RecipeLifecycleSupervisor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * RecipeLifecycleSupervisor — 统一状态转移管理层
+ *
+ * 核心职责：
+ *   1. Guard 前置检查 — 验证转移是否合法（VALID_TRANSITIONS + 扩展条件）
+ *   2. Entry/Exit Actions — 进入/离开状态的固定副作用
+ *   3. Event 记录 — 每次转移记录为不可变 TransitionEvent
+ *   4. 超时监控 — 中间态超时自动处理
+ *   5. 健康摘要 — 全局状态分布与卡死检测
+ *
+ * 所有状态变更建议通过 Supervisor，目前作为可选增强层存在。
+ * 不改变现有 ProposalExecutor/StagingManager 的内部逻辑，
+ * 而是在它们之上提供审计、超时检查和健康监控。
+ *
+ * 触发时机：UiStartupTasks Stage 6（新增）
+ *
+ * @module service/evolution/RecipeLifecycleSupervisor
+ */
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
+import type { LifecycleHealthSummary, TimeoutCheckResult, TransitionEvent, TransitionRequest, TransitionResult } from '../../types/evolution.js';
+interface DatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): Record<string, unknown>[];
+        get(...params: unknown[]): Record<string, unknown> | undefined;
+        run(...params: unknown[]): {
+            changes: number;
+        };
+    };
+}
+export declare class RecipeLifecycleSupervisor {
+    #private;
+    constructor(db: DatabaseLike, options?: {
+        signalBus?: SignalBus;
+    });
+    /**
+     * 执行状态转移 — 统一入口
+     *
+     * 1. 获取当前状态
+     * 2. Guard 检查（合法转移 + 扩展条件）
+     * 3. Exit Action（离开旧状态）
+     * 4. 更新 lifecycle
+     * 5. Entry Action（进入新状态）
+     * 6. 记录 TransitionEvent
+     * 7. 发射信号
+     */
+    transition(request: TransitionRequest): TransitionResult;
+    /**
+     * 检查中间态超时 + 自动处理
+     *
+     * 处理范围:
+     *   - evolving > 7d → active（回退）
+     *   - decaying > 30d → deprecated
+     */
+    checkTimeouts(): TimeoutCheckResult;
+    /**
+     * 查询 Recipe 的转移历史
+     */
+    getTransitionHistory(recipeId: string, limit?: number): TransitionEvent[];
+    /**
+     * 获取全局状态健康摘要
+     */
+    getHealthSummary(): LifecycleHealthSummary;
+}
+export {};