principles-disciple 1.72.0 → 1.73.0

package/src/core/evolution-types.ts

@@ -1,476 +1,88 @@
 /**
  * Evolution Points System V2.0 - MVP
  *
- * Core Philosophy: Growth-driven替代Penalty-driven
- * - 起点0分，只能增加，不扣分
- * - 失败记录教训，不扣分
- * - 同类任务失败后首次成功 = 双倍奖励（1小时冷却）
- * - 5级成长路径：Seed → Forest
- */
-
-// V2 queue types require TaskKind/TaskPriority from trajectory-types
-import type { TaskKind, TaskPriority } from './trajectory-types.js';
-
-// ===== 等级定义 =====
-
- 
-export enum EvolutionTier {
-   
-  Seed = 1,      // 起步：150行 + 3文件 + 子智能体（现代 AI 能力已足够强）
-   
-  Sprout = 2,    // 成长：300行 + 5文件
-   
-  Sapling = 3,   // 独当：500行 + 10文件 + 风险路径
-   
-  Tree = 4,      // 专家：1000行 + 20文件
-   
-  Forest = 5     // 大师：完全自主
-}
-
-export interface TierPermissions {
-  maxLinesPerWrite: number;
-  maxFilesPerTask: number;
-  allowRiskPath: boolean;
-  allowSubagentSpawn: boolean;
-}
-
-export interface TierDefinition {
-  tier: EvolutionTier;
-  name: string;
-  requiredPoints: number;
-  permissions: TierPermissions;
-}
-
-export const TIER_DEFINITIONS: readonly TierDefinition[] = [
-  // 2026-03-28: 大幅放宽限制，现代 AI 能力已很强
-  // Seed: 从 20 行提升到 150 行，允许 3 文件，允许子智能体
-  { tier: EvolutionTier.Seed,    name: 'Seed',    requiredPoints: 0,    permissions: { maxLinesPerWrite: 150,  maxFilesPerTask: 3,  allowRiskPath: false, allowSubagentSpawn: true  }},
-  // Sprout: 中等规模开发
-  { tier: EvolutionTier.Sprout,  name: 'Sprout',  requiredPoints: 50,   permissions: { maxLinesPerWrite: 300,  maxFilesPerTask: 5,  allowRiskPath: false, allowSubagentSpawn: true  }},
-  // Sapling: 较大规模开发，可访问风险路径（需 PLAN）
-  { tier: EvolutionTier.Sapling, name: 'Sapling', requiredPoints: 200,  permissions: { maxLinesPerWrite: 500,  maxFilesPerTask: 10, allowRiskPath: true,  allowSubagentSpawn: true  }},
-  // Tree: 大型重构
-  { tier: EvolutionTier.Tree,    name: 'Tree',    requiredPoints: 500,  permissions: { maxLinesPerWrite: 1000, maxFilesPerTask: 20, allowRiskPath: true,  allowSubagentSpawn: true  }},
-  // Forest: 完全自主
-  { tier: EvolutionTier.Forest,  name: 'Forest',  requiredPoints: 1000, permissions: { maxLinesPerWrite: Infinity, maxFilesPerTask: Infinity, allowRiskPath: true, allowSubagentSpawn: true }},
-] as const;
-
-export function getTierDefinition(tier: EvolutionTier): TierDefinition {
-  return TIER_DEFINITIONS[tier - 1];
-}
-
-export function getTierByPoints(totalPoints: number): EvolutionTier {
-  // 从高到低检查，找到最高匹配等级
-  for (let i = TIER_DEFINITIONS.length - 1; i >= 0; i--) {
-    if (totalPoints >= TIER_DEFINITIONS[i].requiredPoints) {
-      return TIER_DEFINITIONS[i].tier;
-    }
-  }
-  return EvolutionTier.Seed;
-}
-
-// ===== 任务难度 =====
-
-export type TaskDifficulty = 'trivial' | 'normal' | 'hard';
-
-export interface TaskDifficultyConfig {
-  basePoints: number;
-  description: string;
-}
-
-export const TASK_DIFFICULTY_CONFIG: Record<TaskDifficulty, TaskDifficultyConfig> = {
-  trivial: { basePoints: 1,  description: '简单任务：读取、搜索、状态查询' },
-  normal:  { basePoints: 3,  description: '常规任务：单文件编辑、测试编写' },
-  hard:    { basePoints: 8,  description: '困难任务：多文件重构、架构变更' },
-} as const;
-
-// ===== 进化事件 =====
-
-export type EvolutionEventType = 'success' | 'failure';
-
-export interface EvolutionEvent {
-  id: string;                    // 事件 ID (UUID)
-  timestamp: string;             // ISO 8601
-  type: EvolutionEventType;
-  taskHash: string;              // 任务唯一哈希 (工具名 + 文件路径)
-  taskDifficulty: TaskDifficulty;
-  toolName?: string;
-  filePath?: string;
-  reason?: string;               // 人类可读原因
-  pointsAwarded: number;         // 本次获得积分 (>=0)
-  isDoubleReward: boolean;       // 是否双倍奖励
-  sessionId?: string;
-}
-
-// ===== 积分卡 =====
-
-export interface EvolutionScorecard {
-  version: '2.0';
-  agentId: string;
-  
-  // 双积分模型
-  totalPoints: number;           // 历史累计（用于等级计算）
-  availablePoints: number;       // 可用积分（可用于能力消耗）
-  
-  // 当前等级
-  currentTier: EvolutionTier;
-  
-  // 防刷分状态
-  lastDoubleRewardTime?: string; // 上次双倍奖励时间（冷却用）
-  recentFailureHashes: Map<string, string>;  // taskHash → 失败时间戳
-  
-  // 统计
-  stats: EvolutionStats;
-  
-  // 事件历史（最近N条）
-  recentEvents: EvolutionEvent[];
-  
-  lastUpdated: string;
-}
-
-export interface EvolutionStats {
-  totalSuccesses: number;
-  totalFailures: number;
-  consecutiveSuccesses: number;
-  consecutiveFailures: number;
-  doubleRewardsEarned: number;
-  tierPromotions: number;
-  pointsByDifficulty: Record<TaskDifficulty, number>;
-}
-
-// ===== 存储结构 =====
-
-export interface EvolutionStorage {
-  scorecard: EvolutionScorecard;
-  archivedStats: {
-    totalEventsProcessed: number;
-    pointsFromTrivial: number;
-    pointsFromNormal: number;
-    pointsFromHard: number;
-  };
-}
-
-// ===== 配置 =====
-
-export interface EvolutionConfig {
-  /** 双倍奖励冷却时间（毫秒），默认1小时 */
-  doubleRewardCooldownMs: number;
-  
-  /** 保存的最近事件数量，默认50 */
-  maxRecentEvents: number;
-  
-  /** 高等级做低级任务的积分衰减系数 */
-  difficultyPenalty: {
-    tier4Trivial: number;   // Tree级做trivial任务的系数
-    tier4Normal: number;    // Tree级做normal任务的系数
-    tier5Trivial: number;   // Forest级做trivial任务的系数
-    tier5Normal: number;    // Forest级做normal任务的系数
-  };
-}
-
-export const DEFAULT_EVOLUTION_CONFIG: EvolutionConfig = {
-  doubleRewardCooldownMs: 60 * 60 * 1000,  // 1小时
-  maxRecentEvents: 50,
-  difficultyPenalty: {
-    tier4Trivial: 0.1,
-    tier4Normal: 0.5,
-    tier5Trivial: 0.1,
-    tier5Normal: 0.5,
-  },
-};
-
-// ===== 事件归档 =====
-
-export interface ArchivedEventStats {
-  totalEventsProcessed: number;
-  pointsFromTrivial: number;
-  pointsFromNormal: number;
-  pointsFromHard: number;
-}
-
-// ===== Gate 集成接口 =====
-
-export interface GateDecision {
-  allowed: boolean;
-  reason?: string;
-  currentTier?: EvolutionTier;
-  requiredTier?: EvolutionTier;
-}
-
-export interface ToolCallContext {
-  toolName: string;
-  filePath?: string;
-  content?: string;        // 写入的内容（用于行数检查）
-  lineCount?: number;      // 显式行数（如果已知）
-  isRiskPath?: boolean;
-}
-
-// ===== 升级事件 =====
-
-export interface TierPromotionEvent {
-  previousTier: EvolutionTier;
-  newTier: EvolutionTier;
-  totalPoints: number;
-  timestamp: string;
-  newPermissions: TierPermissions;
-}
-
-
-// ===== Evolution Loop Schema =====
-
-export type PrincipleStatus = 'candidate' | 'probation' | 'active' | 'deprecated';
-
-/**
- * Evaluability classification — determines whether a P_xxx principle can enter
- * automatic nocturnal targeting.
+ * Canonical definitions moved to @principles/core/runtime-v2/evolution/
+ * This file re-exports everything for backward compatibility.
  *
- * - deterministic:    Machine-checkable via deterministic rules/tool detectors
- * - weak_heuristic:  Checkable via heuristic signals, may have false positives
- * - manual_only:     No machine-checkable detector — stays in prompts only
- */
-export type PrincipleEvaluatorLevel = 'deterministic' | 'weak_heuristic' | 'manual_only';
-
-/**
- * Shared alias for PrincipleEvaluatorLevel — used by modules that reference
- * the same evaluability classification without direct coupling to evolution-types.
- * @deprecated Use PrincipleEvaluatorLevel directly. This alias exists for
- * backwards compatibility with principle-training-state.ts.
- */
-export type Evaluability = PrincipleEvaluatorLevel;
-
-/**
- * Structured detector metadata for P_xxx principles.
- * Allows the principle to enter automatic nocturnal targeting.
- *
- * If any required field is missing, the principle defaults to 'manual_only'.
- */
-export interface PrincipleDetectorSpec {
-  /** Topic/scenario tags where this detector applies */
-  applicabilityTags: string[];
-  /** Evidence that the principle was followed */
-  positiveSignals: string[];
-  /** Evidence that the principle was violated */
-  negativeSignals: string[];
-  /** Tool call sequences that indicate the principle is relevant */
-  toolSequenceHints: string[][];
-  /** Confidence in the detector's signal quality */
-  confidence: 'high' | 'medium' | 'low';
-}
-
-/**
- * Validates that a detector metadata object has all required fields with non-empty values.
- * Used as defense-in-depth before accepting detectorMetadata for auto-trainable principles.
- */
-export function isCompleteDetectorMetadata(
-  meta: unknown
-): meta is PrincipleDetectorSpec {
-  if (!meta || typeof meta !== 'object') return false;
-  const m = meta as Record<string, unknown>;
-  const VALID_CONFIDENCE = ['high', 'medium', 'low'] as const;
-  if (
-    typeof m.confidence !== 'string' ||
-    !(VALID_CONFIDENCE as readonly string[]).includes(m.confidence)
-  ) {
-    return false;
-  }
-  const nonEmptyStringArray = (arr: unknown): boolean =>
-    Array.isArray(arr) &&
-    arr.length > 0 &&
-    arr.every((s) => typeof s === 'string' && s.length > 0);
-  return (
-    nonEmptyStringArray(m.applicabilityTags) &&
-    nonEmptyStringArray(m.positiveSignals) &&
-    nonEmptyStringArray(m.negativeSignals)
-  );
-}
-
-export interface Principle {
-  id: string;
-  version: number;
-  text: string;
-  source: {
-    painId: string;
-    painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
-    timestamp: string;
-  };
-  trigger: string;
-  action: string;
-  guardrails?: string[];
-  contextTags: string[];
-  validation: {
-    successCount: number;
-    conflictCount: number;
-  };
-  status: PrincipleStatus;
-  feedbackScore: number;
-  usageCount: number;
-  createdAt: string;
-  activatedAt?: string;
-  deprecatedAt?: string;
-  /**
-   * Evaluability classification. Defaults to 'manual_only' if not set.
-   * Principles with 'manual_only' evaluability cannot enter automatic
-   * nocturnal targeting.
-   */
-  evaluability: PrincipleEvaluatorLevel;
-  /**
-   * Structured detector metadata. If present and valid, the principle
-   * may be auto-trainable (deterministic / weak_heuristic).
-   * Absent or malformed = 'manual_only' evaluability.
-   */
-   detectorMetadata?: PrincipleDetectorSpec;
-  /** Highly abstracted principle text suitable for PRINCIPLES.md */
-  abstractedPrinciple?: string;
-  /** Associated core axiom (e.g., "T-01") */
-  coreAxiomId?: string;
-
-  // ── Principle-Tree metadata (Phase 1, optional) ──
-
-  /**
-   * Principle priority level.
-   * P0 = critical safety/data integrity, P1 = process/quality, P2 = style/preference.
-   * Defaults to 'P1' if not set.
-   */
-  priority?: 'P0' | 'P1' | 'P2';
-
-  /**
-   * Principle scope: 'general' applies everywhere, 'domain' is area-specific.
-   * Defaults to 'general' if not set.
-   */
-  scope?: 'general' | 'domain';
-
-  /**
-   * Domain name when scope === 'domain'.
-   * Examples: 'file_operations', 'api_calls', 'config_management'.
-   */
-  domain?: string;
-
-  /**
-   * Suggested rules that would concretely implement this principle.
-   * Populated by diagnostician analysis, stored for future Rule layer implementation.
-   */
-  suggestedRules?: PrincipleSuggestedRule[];
-
-  /**
-   * Value metrics — auto-calculated from pain prevention tracking.
-   * Only populated when metrics have been computed.
-   */
-  valueMetrics?: PrincipleValueMetricsSnapshot;
-}
-
-/**
- * A suggested rule that could implement a principle.
- * Populated by the diagnostician during principle extraction.
- * This is advisory only — no enforcement until Rule layer is implemented.
- */
-export interface PrincipleSuggestedRule {
-  name: string;
-  type: 'hook' | 'gate' | 'skill' | 'test' | 'prompt';
-  triggerCondition: string;
-  enforcement: 'block' | 'warn' | 'log';
-  action: string;
-  implementationHint?: string;
-}
-
-/**
- * Snapshot of value metrics for a principle.
- * Calculated periodically from pain signal matching.
+ * NOTE: Principle → EvolutionPrinciple, PrincipleStatus → EvolutionPrincipleStatus
+ *       to avoid collision with runtime-v2/types/principle-schema.ts Principle.
+ *       Backward-compatible aliases are provided below.
  */
-export interface PrincipleValueMetricsSnapshot {
-  painPreventedCount: number;
-  lastPainPreventedAt?: string;
-  calculatedAt: string;
-}
-
-export type EvolutionLoopEventType =
-  | 'pain_detected'
-  | 'candidate_created'
-  | 'principle_promoted'
-  | 'principle_deprecated'
-  | 'principle_rolled_back'
-  | 'circuit_breaker_opened'
-  | 'legacy_import';
-
-export interface PainDetectedData {
-  painId: string;
-  painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
-  source: string;
-  reason: string;
-  score?: number;
-  sessionId?: string;
-  agentId?: string;  // 用于定位 JSONL 路径: ~/.openclaw/agents/{agentId}/sessions/{sessionId}.jsonl
-  taskId?: string;
-  traceId?: string;
-}
-
-export interface CandidateCreatedData {
-  painId: string;
-  principleId: string;
-  trigger: string;
-  action: string;
-  status: 'candidate';
-  /** Pain type that generated this candidate — preserved on replay */
-  painType?: 'tool_failure' | 'subagent_error' | 'user_frustration';
-  /** Optional evaluability — defaults to 'manual_only' if omitted */
-  evaluability?: PrincipleEvaluatorLevel;
-  /** Optional detector metadata — absent = manual_only */
-  detectorMetadata?: PrincipleDetectorSpec;
-  /** Optional abstracted principle title (≤40 chars) — preserved on replay */
-  abstractedPrinciple?: string;
-  /** Associated core axiom (e.g., "T-01") */
-  coreAxiomId?: string;
-}
-
-export interface PrinciplePromotedData {
-  principleId: string;
-  from: 'candidate' | 'probation';
-  to: 'probation' | 'active';
-  reason: string;
-  successCount?: number;
-}
 
-export interface PrincipleDeprecatedData {
-  principleId: string;
-  reason: string;
-  triggeredBy: 'auto' | 'manual';
-}
-
-export interface PrincipleRolledBackData {
-  principleId: string;
-  reason: string;
-  triggeredBy: 'user_command' | 'auto_conflict';
-  blacklistPattern?: string;
-  relatedPainId?: string;
-}
-
-export interface CircuitBreakerOpenedData {
-  taskId: string;
-  painId: string;
-  failCount: number;
-  reason: string;
-  requireHuman: boolean;
-  nextRetryAt?: string;
-}
-
-export interface LegacyImportData {
-  sourceFile: string;
-  content: string;
-  contentHash?: string;
-}
+import type { TaskKind, TaskPriority } from './trajectory-types.js';
 
-export type EvolutionLoopEvent =
-  | { ts: string; type: 'pain_detected'; data: PainDetectedData }
-  | { ts: string; type: 'pain_recorded'; data: PainDetectedData }
-  | { ts: string; type: 'candidate_created'; data: CandidateCreatedData }
-  | { ts: string; type: 'principle_promoted'; data: PrinciplePromotedData }
-  | { ts: string; type: 'principle_deprecated'; data: PrincipleDeprecatedData }
-  | { ts: string; type: 'principle_rolled_back'; data: PrincipleRolledBackData }
-  | { ts: string; type: 'circuit_breaker_opened'; data: CircuitBreakerOpenedData }
-  | { ts: string; type: 'legacy_import'; data: LegacyImportData };
+import type {
+  EvolutionPrinciple as EvolutionPrincipleType,
+  EvolutionPrincipleStatus as EvolutionPrincipleStatusType,
+  EvolutionPrincipleSuggestedRule as EvolutionPrincipleSuggestedRuleType,
+  EvolutionPrincipleValueMetricsSnapshot as EvolutionPrincipleValueMetricsSnapshotType,
+  EvolutionPainDetectedData as EvolutionPainDetectedDataType,
+} from '@principles/core/runtime-v2';
+
+export {
+  EvolutionTier,
+  TIER_DEFINITIONS,
+  getTierDefinition,
+  getTierByPoints,
+  TASK_DIFFICULTY_CONFIG,
+  DEFAULT_EVOLUTION_CONFIG,
+  isCompleteDetectorMetadata,
+} from '@principles/core/runtime-v2';
+
+export type {
+  TierPermissions,
+  TierDefinition,
+  TaskDifficulty,
+  TaskDifficultyConfig,
+  EvolutionEventType,
+  EvolutionEvent,
+  EvolutionScorecard,
+  EvolutionStats,
+  EvolutionStorage,
+  EvolutionConfig,
+  ArchivedEventStats,
+  GateDecision,
+  ToolCallContext,
+  TierPromotionEvent,
+  EvolutionPrincipleStatus,
+  PrincipleEvaluatorLevel,
+  Evaluability,
+  PrincipleDetectorSpec,
+  EvolutionPrinciple,
+  EvolutionPrincipleSuggestedRule,
+  EvolutionPrincipleValueMetricsSnapshot,
+  EvolutionLoopEventType,
+  EvolutionPainDetectedData,
+  CandidateCreatedData,
+  PrinciplePromotedData,
+  PrincipleDeprecatedData,
+  PrincipleRolledBackData,
+  CircuitBreakerOpenedData,
+  LegacyImportData,
+  EvolutionLoopEvent,
+} from '@principles/core/runtime-v2';
+
+// ── Backward-compatible aliases ──────────────────────────────────────────────
+
+/** @deprecated Use EvolutionPrinciple instead. Alias for backward compatibility. */
+export type Principle = EvolutionPrincipleType;
+
+/** @deprecated Use EvolutionPrincipleStatus instead. Alias for backward compatibility. */
+export type PrincipleStatus = EvolutionPrincipleStatusType;
+
+/** @deprecated Use EvolutionPrincipleSuggestedRule instead. Alias for backward compatibility. */
+export type PrincipleSuggestedRule = EvolutionPrincipleSuggestedRuleType;
+
+/** @deprecated Use EvolutionPrincipleValueMetricsSnapshot instead. Alias for backward compatibility. */
+export type PrincipleValueMetricsSnapshot = EvolutionPrincipleValueMetricsSnapshotType;
+
+/** @deprecated Use EvolutionPainDetectedData instead. Alias for backward compatibility. */
+export type PainDetectedData = EvolutionPainDetectedDataType;
+
+// ── V2 Queue Types (kept in plugin — depends on trajectory-types) ────────────
 
-// V2 Queue Types (moved from evolution-worker.ts for shared use)
 export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
-export type TaskResolution = 'marker_detected' | 'auto_completed_timeout' | 'failed_max_retries' | 'runtime_unavailable' | 'canceled' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'stub_fallback' | 'skipped_thin_violation' | 'success' | 'failure' | 'skipped' | 'noise_classified';
+export type TaskResolution = 'marker_detected' | 'auto_completed_timeout' | 'failed_max_retries' | 'runtime_unavailable' | 'canceled' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'stub_fallback' | 'skipped_thin_violation' | 'success' | 'failure' | 'skipped' | 'noise_classified' | 'retired';
 
 export interface EvolutionQueueItem {
   id: string;

package/src/core/file-store.ts

@@ -0,0 +1,80 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFileSync } from '../utils/io.js';
+
+/**
+ * FileStore — generic interface for atomic JSON file persistence.
+ *
+ * Encapsulates the common "read JSON → modify → atomic write" pattern
+ * used throughout core modules. Implementations handle:
+ * - Missing file → default data
+ * - Malformed file → default data (graceful degradation)
+ * - Atomic writes via temp + rename
+ */
+export interface FileStore<T> {
+  /** Load data from file, returning defaults if missing or corrupt. */
+  load(): T;
+
+  /** Atomically write data to file. */
+  save(data: T): void;
+
+  /**
+   * Read-modify-write cycle.
+   * The mutate function receives current data and may modify it in place.
+   * The modified data is saved automatically after fn completes.
+   * If fn throws, the write is aborted and the file is unchanged.
+   *
+   * Returns the value returned by fn (useful for extracting computed results).
+   *
+   * NOTE: This method is NOT thread-safe. Caller must ensure no concurrent
+   * writes to the same file — use withLock() or equivalent to serialize access.
+   */
+  mutate<R>(fn: (data: T) => R): R;
+}
+
+/**
+ * JSON-backed FileStore implementation.
+ *
+ * Uses atomicWriteFileSync for crash-safe writes.
+ * Handles missing/corrupt files by returning the provided default factory result.
+ */
+export class JsonFileStore<T extends object> implements FileStore<T> {
+  private readonly filePath: string;
+  private readonly defaultFactory: () => T;
+
+  constructor(filePath: string, defaultFactory: () => T) {
+    this.filePath = filePath;
+    this.defaultFactory = defaultFactory;
+  }
+
+  load(): T {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        return this.defaultFactory();
+      }
+      const raw = fs.readFileSync(this.filePath, 'utf8');
+      if (!raw) {
+        return this.defaultFactory();
+      }
+      return JSON.parse(raw) as T;
+    } catch {
+      console.warn(`[JsonFileStore] File corrupt or unreadable, using defaults: ${this.filePath}`);
+      return this.defaultFactory();
+    }
+  }
+
+  save(data: T): void {
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    atomicWriteFileSync(this.filePath, JSON.stringify(data, null, 2));
+  }
+
+  mutate<R>(fn: (data: T) => R): R {
+    const current = this.load();
+    const result = fn(current);
+    this.save(current);
+    return result;
+  }
+}