skyloom 1.13.5 → 1.13.7

package/src/core/file_checkpoint.ts

@@ -0,0 +1,136 @@
+/**
+ * 文件级检查点 — snapshot files before agents mutate them; /rewind restores.
+ *
+ * Every chat turn / task opens a checkpoint "turn". Before write_file /
+ * edit_file / delete_file executes, the target's current content (or its
+ * absence) is snapshotted — first touch per path per turn wins, so a rewind
+ * restores the state from *before* the turn began. Lets users hand agents
+ * risky changes and undo them in one command, without involving git.
+ *
+ * Deliberately session-scoped and in-memory (like Claude Code checkpoints):
+ * not a git replacement, and `run_bash` side effects cannot be rewound.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getLogger } from './logger';
+
+const log = getLogger('checkpoint');
+
+interface FileSnapshot {
+  /** Absolute path. */
+  path: string;
+  /** Content before the turn, or null if the file did not exist. */
+  content: string | null;
+}
+
+export interface CheckpointTurn {
+  id: number;
+  label: string;
+  at: Date;
+  snapshots: Map<string, FileSnapshot>;
+}
+
+const MAX_TURNS = 50;
+const MAX_FILE_BYTES = 2 * 1024 * 1024; // skip snapshotting monsters
+const MUTATING_TOOL_RE = /^(write_file|edit_file|delete_file)$/;
+
+class FileCheckpointStore {
+  private turns: CheckpointTurn[] = [];
+  private current: CheckpointTurn | null = null;
+  private seq = 0;
+
+  /** Open a new turn; subsequent snapshots attach to it. */
+  beginTurn(label: string): void {
+    // An empty previous turn is replaced, not stacked.
+    if (this.current && this.current.snapshots.size === 0) {
+      this.turns.pop();
+    }
+    this.current = { id: ++this.seq, label: label.slice(0, 60), at: new Date(), snapshots: new Map() };
+    this.turns.push(this.current);
+    if (this.turns.length > MAX_TURNS) this.turns.shift();
+  }
+
+  /** Snapshot a path before mutation (first touch per turn wins). */
+  snapshot(rawPath: string): void {
+    if (!this.current) this.beginTurn('(implicit)');
+    const abs = path.resolve(rawPath);
+    if (this.current!.snapshots.has(abs)) return;
+    let content: string | null = null;
+    try {
+      if (fs.existsSync(abs)) {
+        const stat = fs.statSync(abs);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
+        content = fs.readFileSync(abs, 'utf-8');
+      }
+    } catch (e) {
+      log.warn('snapshot_failed', { path: abs, error: String(e) });
+      return;
+    }
+    this.current!.snapshots.set(abs, { path: abs, content });
+  }
+
+  /** Should this tool call be snapshotted? Returns the path to snapshot. */
+  pathToSnapshot(toolName: string, args: Record<string, any>): string | null {
+    if (!MUTATING_TOOL_RE.test(toolName)) return null;
+    const p = args?.path;
+    return typeof p === 'string' && p.trim() ? p : null;
+  }
+
+  /** Turns that actually captured changes, newest first. */
+  list(): Array<{ id: number; label: string; at: Date; files: string[] }> {
+    return this.turns
+      .filter(t => t.snapshots.size > 0)
+      .map(t => ({ id: t.id, label: t.label, at: t.at, files: [...t.snapshots.keys()] }))
+      .reverse();
+  }
+
+  /**
+   * Restore the last `count` non-empty turns (newest backwards). When the
+   * same file appears in several turns, the oldest snapshot wins — that is
+   * the state from before the earliest rewound turn.
+   */
+  rewind(count: number = 1): { restored: string[]; deleted: string[]; turns: number } {
+    const nonEmpty = this.turns.filter(t => t.snapshots.size > 0);
+    const target = nonEmpty.slice(-count);
+    if (target.length === 0) return { restored: [], deleted: [], turns: 0 };
+
+    // oldest-first iteration: later assignments overwrite, so the oldest
+    // snapshot per path ends up in the map
+    const finalState = new Map<string, FileSnapshot>();
+    for (let i = target.length - 1; i >= 0; i--) {
+      for (const snap of target[i].snapshots.values()) finalState.set(snap.path, snap);
+    }
+
+    const restored: string[] = [];
+    const deleted: string[] = [];
+    for (const snap of finalState.values()) {
+      try {
+        if (snap.content === null) {
+          if (fs.existsSync(snap.path)) { fs.unlinkSync(snap.path); deleted.push(snap.path); }
+        } else {
+          fs.mkdirSync(path.dirname(snap.path), { recursive: true });
+          fs.writeFileSync(snap.path, snap.content, 'utf-8');
+          restored.push(snap.path);
+        }
+      } catch (e) {
+        log.warn('rewind_failed', { path: snap.path, error: String(e) });
+      }
+    }
+
+    // Rewound turns are consumed.
+    const ids = new Set(target.map(t => t.id));
+    this.turns = this.turns.filter(t => !ids.has(t.id));
+    if (this.current && ids.has(this.current.id)) this.current = null;
+    return { restored, deleted, turns: target.length };
+  }
+
+  /** Test/reset hook. */
+  clear(): void { this.turns = []; this.current = null; }
+}
+
+let _store: FileCheckpointStore | null = null;
+export function getFileCheckpoints(): FileCheckpointStore {
+  if (!_store) _store = new FileCheckpointStore();
+  return _store;
+}

package/src/core/filter.ts

@@ -1,103 +1,103 @@
-/**
- * 输出过滤模块 — sensitive information sanitization.
- *
- * Before agent responses reach the user (or are persisted),
- * scan for and redact sensitive patterns like API keys,
- * tokens, passwords, PII, and internal paths.
- */
-
-/* ═══════════════════════════════════════
-   Detection patterns — compiled once at module load
-   ═══════════════════════════════════════ */
-const SENSITIVE_PATTERNS: Array<[RegExp, string]> = [
-  // API keys & tokens
-  [/sk-[a-zA-Z0-9]{32,}/g, "[REDACTED:API_KEY]"],
-  [/(?:api_key|apikey|secret_key|access_token|auth_token)\s*[:=]\s*["']?[^\s"']{8,}["']?/gi, "$1: [REDACTED]"],
-  [/ghp_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
-  [/gho_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
-
-  // AWS credentials
-  [/AKIA[0-9A-Z]{16}/g, "[REDACTED:AWS_KEY]"],
-  [/(?:aws_access_key_id|aws_secret_access_key)\s*[:=]\s*["']?[^\s"']+/gi, "$1: [REDACTED]"],
-
-  // Passwords
-  [/(?:password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, "$1: [REDACTED]"],
-  [/(?:密码|口令)\s*[:=]\s*["']?[^\s"']{2,}["']?/g, "$1: [已脱敏]"],
-
-  // Connection strings
-  [/(?:mongodb|postgres|mysql|redis):\/\/[^\s]+/g, "[REDACTED:DB_URI]"],
-  [/(?:jdbc|odbc):[^\s]+/g, "[REDACTED:DB_URI]"],
-
-  // Private keys
-  [/-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END .*?PRIVATE KEY-----/g, "[REDACTED:PRIVATE_KEY]"],
-
-  // IP addresses (local only)
-  [/192\.168\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
-  [/10\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
-  [/172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
-
-  // File paths
-  [/(?:\/etc\/(?:passwd|shadow|hosts|sudoers))/g, "[REDACTED:SYSTEM_PATH]"],
-];
-
-/* Email masking (function-based, handled separately) */
-const EMAIL_RE = /([a-zA-Z0-9._%+-]{3,})@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/g;
-
-
-/* ═══════════════════════════════════════
-   Filter function
-   ═══════════════════════════════════════ */
-export interface FilterResult {
-  clean: string;
-  redacted: boolean;
-  count: number;
-  details: string[];
-}
-
-export function filterOutput(text: string): FilterResult {
-  if (!text) return { clean: "", redacted: false, count: 0, details: [] };
-
-  let clean = text;
-  let count = 0;
-  const details: string[] = [];
-
-  // Email masking (function-based replacement)
-  let emailCount = 0;
-  clean = clean.replace(EMAIL_RE, (full, user, domain) => {
-    emailCount++;
-    return (user as string).slice(0, 2) + "***@" + (domain as string);
-  });
-  if (emailCount > 0) {
-    count += emailCount;
-    details.push(`Masked ${emailCount}x email addresses`);
-  }
-
-  for (const [pattern, replacement] of SENSITIVE_PATTERNS) {
-    const matches = clean.match(pattern);
-    if (matches) {
-      count += matches.length;
-      if (typeof replacement === "string") {
-        details.push(`Redacted ${matches.length}x ${pattern.source.slice(0, 30)}`);
-      } else {
-        details.push(`Masked ${matches.length}x email addresses`);
-      }
-      clean = clean.replace(pattern, replacement as string);
-    }
-  }
-
-  return { clean, redacted: count > 0, count, details };
-}
-
-/* ═══════════════════════════════════════
-   Quick check — is filtering needed?
-   ═══════════════════════════════════════ */
-export function needsFiltering(text: string): boolean {
-  if (!text) return false;
-  // Quick scan with the most common patterns
-  if (/sk-[a-zA-Z0-9]{32,}/.test(text)) return true;
-  if (/api_key.*[:=]/.test(text)) return true;
-  if (/password.*[:=]/.test(text)) return true;
-  if (/-----BEGIN.*PRIVATE KEY-----/.test(text)) return true;
-  if (EMAIL_RE.test(text)) return true;
-  return false;
-}
+/**
+ * 输出过滤模块 — sensitive information sanitization.
+ *
+ * Before agent responses reach the user (or are persisted),
+ * scan for and redact sensitive patterns like API keys,
+ * tokens, passwords, PII, and internal paths.
+ */
+
+/* ═══════════════════════════════════════
+   Detection patterns — compiled once at module load
+   ═══════════════════════════════════════ */
+const SENSITIVE_PATTERNS: Array<[RegExp, string]> = [
+  // API keys & tokens
+  [/sk-[a-zA-Z0-9]{32,}/g, "[REDACTED:API_KEY]"],
+  [/(?:api_key|apikey|secret_key|access_token|auth_token)\s*[:=]\s*["']?[^\s"']{8,}["']?/gi, "$1: [REDACTED]"],
+  [/ghp_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
+  [/gho_[a-zA-Z0-9]{36}/g, "[REDACTED:GITHUB_TOKEN]"],
+
+  // AWS credentials
+  [/AKIA[0-9A-Z]{16}/g, "[REDACTED:AWS_KEY]"],
+  [/(?:aws_access_key_id|aws_secret_access_key)\s*[:=]\s*["']?[^\s"']+/gi, "$1: [REDACTED]"],
+
+  // Passwords
+  [/(?:password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, "$1: [REDACTED]"],
+  [/(?:密码|口令)\s*[:=]\s*["']?[^\s"']{2,}["']?/g, "$1: [已脱敏]"],
+
+  // Connection strings
+  [/(?:mongodb|postgres|mysql|redis):\/\/[^\s]+/g, "[REDACTED:DB_URI]"],
+  [/(?:jdbc|odbc):[^\s]+/g, "[REDACTED:DB_URI]"],
+
+  // Private keys
+  [/-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END .*?PRIVATE KEY-----/g, "[REDACTED:PRIVATE_KEY]"],
+
+  // IP addresses (local only)
+  [/192\.168\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+  [/10\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+  [/172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}/g, "[REDACTED:LAN_IP]"],
+
+  // File paths
+  [/(?:\/etc\/(?:passwd|shadow|hosts|sudoers))/g, "[REDACTED:SYSTEM_PATH]"],
+];
+
+/* Email masking (function-based, handled separately) */
+const EMAIL_RE = /([a-zA-Z0-9._%+-]{3,})@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/g;
+
+
+/* ═══════════════════════════════════════
+   Filter function
+   ═══════════════════════════════════════ */
+export interface FilterResult {
+  clean: string;
+  redacted: boolean;
+  count: number;
+  details: string[];
+}
+
+export function filterOutput(text: string): FilterResult {
+  if (!text) return { clean: "", redacted: false, count: 0, details: [] };
+
+  let clean = text;
+  let count = 0;
+  const details: string[] = [];
+
+  // Email masking (function-based replacement)
+  let emailCount = 0;
+  clean = clean.replace(EMAIL_RE, (full, user, domain) => {
+    emailCount++;
+    return (user as string).slice(0, 2) + "***@" + (domain as string);
+  });
+  if (emailCount > 0) {
+    count += emailCount;
+    details.push(`Masked ${emailCount}x email addresses`);
+  }
+
+  for (const [pattern, replacement] of SENSITIVE_PATTERNS) {
+    const matches = clean.match(pattern);
+    if (matches) {
+      count += matches.length;
+      if (typeof replacement === "string") {
+        details.push(`Redacted ${matches.length}x ${pattern.source.slice(0, 30)}`);
+      } else {
+        details.push(`Masked ${matches.length}x email addresses`);
+      }
+      clean = clean.replace(pattern, replacement as string);
+    }
+  }
+
+  return { clean, redacted: count > 0, count, details };
+}
+
+/* ═══════════════════════════════════════
+   Quick check — is filtering needed?
+   ═══════════════════════════════════════ */
+export function needsFiltering(text: string): boolean {
+  if (!text) return false;
+  // Quick scan with the most common patterns
+  if (/sk-[a-zA-Z0-9]{32,}/.test(text)) return true;
+  if (/api_key.*[:=]/.test(text)) return true;
+  if (/password.*[:=]/.test(text)) return true;
+  if (/-----BEGIN.*PRIVATE KEY-----/.test(text)) return true;
+  if (EMAIL_RE.test(text)) return true;
+  return false;
+}

package/src/core/graph.ts

@@ -1,156 +1,156 @@
-/**
- * 简易知识图谱 — entity-relation storage in SQLite.
- *
- * Lightweight triple store: (subject, predicate, object) with metadata.
- * Used for: project info, tool preferences, dependency relationships.
- *
- * Schema:
- *   CREATE TABLE triples (subj, pred, obj, agent, ts, meta)
- *
- * Queries:
- *   - Find all relations for an entity
- *   - Find all entities matching a predicate
- *   - Transitive closure (2-hop max for performance)
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { USER_CONFIG_DIR } from "./config";
-import { getLogger } from "./logger";
-
-const log = getLogger("graph");
-
-/* ═══════════════════════════════════════
-   Triple store — in-memory + optional persistence
-   ═══════════════════════════════════════ */
-interface Triple {
-  subj: string;
-  pred: string;
-  obj: string;
-  agent: string;
-  ts: string;
-  meta?: Record<string, string>;
-}
-
-export class KnowledgeGraph {
-  private triples: Triple[] = [];
-  private indexPath: string;
-
-  constructor(name: string = "default") {
-    this.indexPath = path.join(USER_CONFIG_DIR, `kg_${name}.json`);
-    this.load();
-  }
-
-  /** Add a fact: (subject, predicate, object). */
-  add(subj: string, pred: string, obj: string, agent: string = "system", meta?: Record<string, string>): void {
-    // Deduplicate
-    const exists = this.triples.find(t => t.subj === subj && t.pred === pred && t.obj === obj);
-    if (exists) { exists.ts = new Date().toISOString(); if (meta) exists.meta = { ...exists.meta, ...meta }; return; }
-
-    this.triples.push({ subj, pred, obj, agent, ts: new Date().toISOString(), meta });
-    if (this.triples.length > 5000) this.triples.splice(0, this.triples.length - 5000);
-    this.save();
-  }
-
-  /** Find all facts about an entity. */
-  about(entity: string, limit: number = 20): Triple[] {
-    return this.triples.filter(t => t.subj === entity || t.obj === entity).slice(-limit);
-  }
-
-  /** Find all subjects matching a predicate. */
-  byPredicate(pred: string): Triple[] {
-    return this.triples.filter(t => t.pred === pred);
-  }
-
-  /** Find all objects for a subject-predicate pair. */
-  find(subj: string, pred: string): Triple[] {
-    return this.triples.filter(t => t.subj === subj && t.pred === pred);
-  }
-
-  /** Transitive expansion: 2-hop from a starting entity. */
-  expand(entity: string, maxDepth: number = 2): Triple[] {
-    const seen = new Set<Triple>();
-    const queue = [entity];
-    for (let depth = 0; depth < maxDepth && queue.length > 0; depth++) {
-      const current = queue.shift()!;
-      const facts = this.about(current, 10);
-      for (const f of facts) {
-        if (seen.has(f)) continue;
-        seen.add(f);
-        if (f.subj === current && !queue.includes(f.obj)) queue.push(f.obj);
-        if (f.obj === current && !queue.includes(f.subj)) queue.push(f.subj);
-      }
-    }
-    return Array.from(seen);
-  }
-
-  /** Remove a fact. */
-  remove(subj: string, pred: string, obj: string): void {
-    this.triples = this.triples.filter(t => !(t.subj === subj && t.pred === pred && t.obj === obj));
-    this.save();
-  }
-
-  /** Search for entities or predicates containing a keyword. */
-  search(keyword: string, limit: number = 15): Triple[] {
-    const k = keyword.toLowerCase();
-    return this.triples.filter(t => t.subj.toLowerCase().includes(k) || t.pred.toLowerCase().includes(k) || t.obj.toLowerCase().includes(k)).slice(-limit);
-  }
-
-  /** Format facts as readable text. */
-  format(entity?: string): string {
-    const facts = entity ? this.about(entity) : this.triples.slice(-30);
-    if (facts.length === 0) return "(no facts)";
-    const bySubj = new Map<string, string[]>();
-    for (const f of facts) {
-      if (!bySubj.has(f.subj)) bySubj.set(f.subj, []);
-      bySubj.get(f.subj)!.push(`${f.pred} → ${f.obj}`);
-    }
-    const lines: string[] = [];
-    for (const [subj, preds] of bySubj) {
-      lines.push(`**${subj}**: ${preds.join(", ")}`);
-    }
-    return lines.join("\n");
-  }
-
-  get size(): number { return this.triples.length; }
-
-  private save(): void {
-    try {
-      const dir = path.dirname(this.indexPath);
-      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(this.indexPath, JSON.stringify(this.triples.slice(-2000)), "utf-8");
-    } catch (e) { log.warn("kg_save_failed", { error: String(e) }); }
-  }
-
-  private load(): void {
-    try {
-      if (fs.existsSync(this.indexPath)) {
-        this.triples = JSON.parse(fs.readFileSync(this.indexPath, "utf-8"));
-      }
-    } catch { this.triples = []; }
-  }
-}
-
-/* ── Auto-extract facts from conversation ── */
-const RELATION_PATTERNS: Array<[RegExp, string]> = [
-  [/(\w+) (?:是|为|属于|使用|用|用到了|采用) (.+?)(?:[。，,.\n]|$)/g, "is"],
-  [/(\w+) (?:版本|version|v) (?:是|为)? ?(\d[\d.]*)/gi, "version"],
-  [/(\w+) (?:depends|依赖|需要|requires) (\w+)/gi, "depends_on"],
-  [/(\w+) (?:config|配置) (?:为|是)? (.+?)(?:[。，,.\n]|$)/gi, "config"],
-  [/(\w+) (?:file|path|文件|路径) (?:在|为|at) (.+?)(?:[。，,.\n]|$)/gi, "located_at"],
-];
-
-export function extractFacts(text: string, agent: string): Array<[string, string, string]> {
-  const facts: Array<[string, string, string]> = [];
-  for (const [pattern, pred] of RELATION_PATTERNS) {
-    let match;
-    while ((match = pattern.exec(text)) !== null) {
-      const subj = match[1].trim().toLowerCase();
-      const obj = match[2].trim();
-      if (subj.length >= 2 && obj.length >= 2 && subj !== obj) {
-        facts.push([subj, pred, obj]);
-      }
-    }
-  }
-  return facts;
-}
+/**
+ * 简易知识图谱 — entity-relation storage in SQLite.
+ *
+ * Lightweight triple store: (subject, predicate, object) with metadata.
+ * Used for: project info, tool preferences, dependency relationships.
+ *
+ * Schema:
+ *   CREATE TABLE triples (subj, pred, obj, agent, ts, meta)
+ *
+ * Queries:
+ *   - Find all relations for an entity
+ *   - Find all entities matching a predicate
+ *   - Transitive closure (2-hop max for performance)
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { USER_CONFIG_DIR } from "./config";
+import { getLogger } from "./logger";
+
+const log = getLogger("graph");
+
+/* ═══════════════════════════════════════
+   Triple store — in-memory + optional persistence
+   ═══════════════════════════════════════ */
+interface Triple {
+  subj: string;
+  pred: string;
+  obj: string;
+  agent: string;
+  ts: string;
+  meta?: Record<string, string>;
+}
+
+export class KnowledgeGraph {
+  private triples: Triple[] = [];
+  private indexPath: string;
+
+  constructor(name: string = "default") {
+    this.indexPath = path.join(USER_CONFIG_DIR, `kg_${name}.json`);
+    this.load();
+  }
+
+  /** Add a fact: (subject, predicate, object). */
+  add(subj: string, pred: string, obj: string, agent: string = "system", meta?: Record<string, string>): void {
+    // Deduplicate
+    const exists = this.triples.find(t => t.subj === subj && t.pred === pred && t.obj === obj);
+    if (exists) { exists.ts = new Date().toISOString(); if (meta) exists.meta = { ...exists.meta, ...meta }; return; }
+
+    this.triples.push({ subj, pred, obj, agent, ts: new Date().toISOString(), meta });
+    if (this.triples.length > 5000) this.triples.splice(0, this.triples.length - 5000);
+    this.save();
+  }
+
+  /** Find all facts about an entity. */
+  about(entity: string, limit: number = 20): Triple[] {
+    return this.triples.filter(t => t.subj === entity || t.obj === entity).slice(-limit);
+  }
+
+  /** Find all subjects matching a predicate. */
+  byPredicate(pred: string): Triple[] {
+    return this.triples.filter(t => t.pred === pred);
+  }
+
+  /** Find all objects for a subject-predicate pair. */
+  find(subj: string, pred: string): Triple[] {
+    return this.triples.filter(t => t.subj === subj && t.pred === pred);
+  }
+
+  /** Transitive expansion: 2-hop from a starting entity. */
+  expand(entity: string, maxDepth: number = 2): Triple[] {
+    const seen = new Set<Triple>();
+    const queue = [entity];
+    for (let depth = 0; depth < maxDepth && queue.length > 0; depth++) {
+      const current = queue.shift()!;
+      const facts = this.about(current, 10);
+      for (const f of facts) {
+        if (seen.has(f)) continue;
+        seen.add(f);
+        if (f.subj === current && !queue.includes(f.obj)) queue.push(f.obj);
+        if (f.obj === current && !queue.includes(f.subj)) queue.push(f.subj);
+      }
+    }
+    return Array.from(seen);
+  }
+
+  /** Remove a fact. */
+  remove(subj: string, pred: string, obj: string): void {
+    this.triples = this.triples.filter(t => !(t.subj === subj && t.pred === pred && t.obj === obj));
+    this.save();
+  }
+
+  /** Search for entities or predicates containing a keyword. */
+  search(keyword: string, limit: number = 15): Triple[] {
+    const k = keyword.toLowerCase();
+    return this.triples.filter(t => t.subj.toLowerCase().includes(k) || t.pred.toLowerCase().includes(k) || t.obj.toLowerCase().includes(k)).slice(-limit);
+  }
+
+  /** Format facts as readable text. */
+  format(entity?: string): string {
+    const facts = entity ? this.about(entity) : this.triples.slice(-30);
+    if (facts.length === 0) return "(no facts)";
+    const bySubj = new Map<string, string[]>();
+    for (const f of facts) {
+      if (!bySubj.has(f.subj)) bySubj.set(f.subj, []);
+      bySubj.get(f.subj)!.push(`${f.pred} → ${f.obj}`);
+    }
+    const lines: string[] = [];
+    for (const [subj, preds] of bySubj) {
+      lines.push(`**${subj}**: ${preds.join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+
+  get size(): number { return this.triples.length; }
+
+  private save(): void {
+    try {
+      const dir = path.dirname(this.indexPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(this.indexPath, JSON.stringify(this.triples.slice(-2000)), "utf-8");
+    } catch (e) { log.warn("kg_save_failed", { error: String(e) }); }
+  }
+
+  private load(): void {
+    try {
+      if (fs.existsSync(this.indexPath)) {
+        this.triples = JSON.parse(fs.readFileSync(this.indexPath, "utf-8"));
+      }
+    } catch { this.triples = []; }
+  }
+}
+
+/* ── Auto-extract facts from conversation ── */
+const RELATION_PATTERNS: Array<[RegExp, string]> = [
+  [/(\w+) (?:是|为|属于|使用|用|用到了|采用) (.+?)(?:[。，,.\n]|$)/g, "is"],
+  [/(\w+) (?:版本|version|v) (?:是|为)? ?(\d[\d.]*)/gi, "version"],
+  [/(\w+) (?:depends|依赖|需要|requires) (\w+)/gi, "depends_on"],
+  [/(\w+) (?:config|配置) (?:为|是)? (.+?)(?:[。，,.\n]|$)/gi, "config"],
+  [/(\w+) (?:file|path|文件|路径) (?:在|为|at) (.+?)(?:[。，,.\n]|$)/gi, "located_at"],
+];
+
+export function extractFacts(text: string, agent: string): Array<[string, string, string]> {
+  const facts: Array<[string, string, string]> = [];
+  for (const [pattern, pred] of RELATION_PATTERNS) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const subj = match[1].trim().toLowerCase();
+      const obj = match[2].trim();
+      if (subj.length >= 2 && obj.length >= 2 && subj !== obj) {
+        facts.push([subj, pred, obj]);
+      }
+    }
+  }
+  return facts;
+}