@ai-setting/roy-agent-core 1.0.0

package/src/env/task/storage/sqlite-task-store.ts

@@ -0,0 +1,903 @@
+/**
+ * @fileoverview SQLite Task Store
+ * 
+ * SQLite-based implementation of TaskStore.
+ * Uses Bun's built-in bun:sqlite module for persistence.
+ * 
+ * 参考 Session SQLiteStore 实现模式：
+ * - 使用 bun:sqlite 内置模块
+ * - 内存缓存提高性能
+ * - 默认路径：~/.local/share/roy-agent/tasks.db
+ */
+
+import { join } from "path";
+import type {
+  Task,
+  TaskOperation,
+  TaskTag,
+  CreateTaskOptions,
+  UpdateTaskOptions,
+  ListTasksOptions,
+  CreateOperationOptions,
+  ListOperationsOptions,
+} from "../types";
+import type { ListTagsOptions, SearchTagsOptions } from "../tag-service";
+import { createLogger } from "../../log-trace/logger";
+
+const logger = createLogger("task:store");
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Get default data directory for task storage
+ */
+function getDefaultDataDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+  return join(home, ".local", "share");
+}
+
+/**
+ * Get default database path for task storage
+ */
+function getDefaultTaskDbPath(): string {
+  return join(getDefaultDataDir(), "roy-agent", "tasks.db");
+}
+
+// ============================================================================
+// TaskStore Interface
+// ============================================================================
+
+export interface TaskStore {
+  // ========== Task CRUD ==========
+  createTask(options: CreateTaskOptions): Promise<Task>;
+  getTask(id: number): Promise<Task | undefined>;
+  updateTask(id: number, options: UpdateTaskOptions): Promise<Task | undefined>;
+  deleteTask(id: number): Promise<boolean>;
+  listTasks(options?: ListTasksOptions): Promise<Task[]>;
+  
+  // ========== Operation CRUD ==========
+  createOperation(options: CreateOperationOptions): Promise<TaskOperation>;
+  getOperation(id: number): Promise<TaskOperation | undefined>;
+  updateOperation(id: number, updates: { actionTitle?: string; actionDescription?: string }): Promise<TaskOperation | undefined>;
+  deleteOperation(id: number): Promise<boolean>;
+  listOperations(options: ListOperationsOptions): Promise<TaskOperation[]>;
+  
+  // ========== Tag CRUD ==========
+  createTag(name: string): Promise<TaskTag>;
+  getTag(id: number): Promise<TaskTag | undefined>;
+  getTagByName(name: string): Promise<TaskTag | undefined>;
+  listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+  searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+  deleteTag(id: number): Promise<boolean>;
+  
+  // ========== Tag 与 Task 关联 ==========
+  addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+  removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+  getTagsForTask(taskId: number): Promise<TaskTag[]>;
+  getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+  updateTaskTags(taskId: number, tagNames: string[]): Promise<void>;
+  
+  // ========== 检索能力（核心改造）==========
+  /** Search tasks by keywords (tags, description, goals, operations) */
+  searchTasksByKeywords(keywords: string[], options?: { limit?: number; excludeTaskId?: number }): Promise<Task[]>;
+  /** Find similar tasks using new keywords search */
+  findSimilarTasksByKeywords(keywords: string[], options?: { limit?: number; excludeTaskId?: number }): Promise<Task[]>;
+  
+  // ========== 检索能力（向后兼容）==========
+  findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+  searchTasks(query: string, limit?: number): Promise<Task[]>;
+  
+  // ========== 生命周期 ==========
+  close(): void;
+}
+
+// ============================================================================
+// SQLiteTaskStore
+// ============================================================================
+
+/**
+ * SQLite-based Task Store
+ * 
+ * 参考 Session SQLiteStore 实现模式：
+ * - 使用 bun:sqlite 内置模块
+ * - 内存缓存提高性能
+ * - 默认路径：~/.local/share/roy-agent/tasks.db
+ */
+export class SQLiteTaskStore implements TaskStore {
+  private db: any = null;
+  private dbPath: string;
+  private initialized = false;
+
+  // 内存缓存（与 SessionStore 模式一致）
+  private tasksCache = new Map<number, Task>();
+  private operationsCache = new Map<number, TaskOperation[]>();
+
+  constructor(dbPath?: string) {
+    this.dbPath = dbPath || getDefaultTaskDbPath();
+  }
+
+  // ========================================================================
+  // Initialization
+  // ========================================================================
+
+  private async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // 使用 Bun 内置的 bun:sqlite
+    const { Database } = require("bun:sqlite");
+
+    // 确保目录存在
+    if (this.dbPath !== ":memory:") {
+      const fs = require("fs");
+      const path = require("path");
+      const dir = path.dirname(this.dbPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+
+    this.db = new Database(this.dbPath);
+
+    // 创建表（与 SessionStore 风格一致）
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS task (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title TEXT NOT NULL,
+        description TEXT DEFAULT '',
+        status TEXT DEFAULT 'todo',
+        priority TEXT DEFAULT 'medium',
+        progress INTEGER DEFAULT 0,
+        current_status TEXT DEFAULT '',
+        goals_and_expected_deliverables TEXT DEFAULT '',
+        parent_task_id INTEGER,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        due_date TEXT,
+        tags TEXT
+      )
+    `);
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS task_operation (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id INTEGER NOT NULL,
+        session_id TEXT NOT NULL,
+        action_type TEXT NOT NULL,
+        action_title TEXT NOT NULL,
+        action_description TEXT DEFAULT '',
+        timestamp INTEGER NOT NULL,
+        md_path TEXT,
+        FOREIGN KEY (task_id) REFERENCES task(id) ON DELETE CASCADE
+      )
+    `);
+
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_task_operation_task_id ON task_operation(task_id)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_task_operation_session_id ON task_operation(session_id)");
+
+    // Tag 池表
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS task_tag (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL UNIQUE,
+        created_at INTEGER NOT NULL,
+        task_count INTEGER DEFAULT 0
+      )
+    `);
+
+    // Tag 与 Task 关联表
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS task_tag_relation (
+        task_id INTEGER NOT NULL,
+        tag_id INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (task_id, tag_id),
+        FOREIGN KEY (task_id) REFERENCES task(id) ON DELETE CASCADE,
+        FOREIGN KEY (tag_id) REFERENCES task_tag(id) ON DELETE CASCADE
+      )
+    `);
+
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_task_tag_relation_tag_id ON task_tag_relation(tag_id)");
+
+    this.initialized = true;
+    logger.info(`TaskStore initialized at ${this.dbPath}`);
+  }
+
+  // ========================================================================
+  // Task CRUD
+  // ========================================================================
+
+  async createTask(options: CreateTaskOptions): Promise<Task> {
+    await this.initialize();
+    
+    const now = Date.now();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO task (title, description, priority, parent_task_id, 
+        goals_and_expected_deliverables, due_date, tags, status, 
+        current_status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 'todo', '', ?, ?)
+    `);
+    
+    const result = stmt.run(
+      options.title,
+      options.description || "",
+      options.priority || "medium",
+      options.parent_task_id || null,
+      options.goals_and_expected_deliverables || "",
+      options.due_date || null,
+      options.tags ? JSON.stringify(options.tags) : null,
+      now,
+      now
+    );
+    
+    const task = await this.getTask(result.lastInsertRowid as number);
+    if (task) {
+      this.tasksCache.set(task.id, task);
+      return task;
+    }
+    throw new Error("Failed to create task");
+  }
+
+  async getTask(id: number): Promise<Task | undefined> {
+    await this.initialize();
+    
+    // 检查缓存
+    if (this.tasksCache.has(id)) {
+      return this.tasksCache.get(id);
+    }
+    
+    const stmt = this.db.prepare("SELECT * FROM task WHERE id = ?");
+    const row = stmt.get(id) as any;
+    if (!row) return undefined;
+    
+    const task = this.rowToTask(row);
+    this.tasksCache.set(id, task);
+    return task;
+  }
+
+  async updateTask(id: number, options: UpdateTaskOptions): Promise<Task | undefined> {
+    await this.initialize();
+    
+    const task = await this.getTask(id);
+    if (!task) return undefined;
+    
+    const updates: string[] = [];
+    const values: any[] = [];
+    
+    if (options.title !== undefined) { updates.push("title = ?"); values.push(options.title); }
+    if (options.description !== undefined) { updates.push("description = ?"); values.push(options.description); }
+    if (options.status !== undefined) { updates.push("status = ?"); values.push(options.status); }
+    if (options.priority !== undefined) { updates.push("priority = ?"); values.push(options.priority); }
+    if (options.progress !== undefined) { updates.push("progress = ?"); values.push(options.progress); }
+    if (options.current_status !== undefined) { updates.push("current_status = ?"); values.push(options.current_status); }
+    if (options.goals_and_expected_deliverables !== undefined) { updates.push("goals_and_expected_deliverables = ?"); values.push(options.goals_and_expected_deliverables); }
+    if (options.due_date !== undefined) { updates.push("due_date = ?"); values.push(options.due_date); }
+    if (options.tags !== undefined) { updates.push("tags = ?"); values.push(JSON.stringify(options.tags)); }
+    
+    if (updates.length === 0) return task;
+    
+    updates.push("updated_at = ?");
+    values.push(Date.now());
+    values.push(id);
+    
+    const stmt = this.db.prepare(`UPDATE task SET ${updates.join(", ")} WHERE id = ?`);
+    stmt.run(...values);
+    
+    // 清除缓存
+    this.tasksCache.delete(id);
+    
+    return this.getTask(id);
+  }
+
+  async deleteTask(id: number): Promise<boolean> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("DELETE FROM task WHERE id = ?");
+    const result = stmt.run(id);
+    
+    if (result.changes > 0) {
+      this.tasksCache.delete(id);
+      this.operationsCache.delete(id);
+    }
+    
+    return result.changes > 0;
+  }
+
+  async listTasks(options?: ListTasksOptions): Promise<Task[]> {
+    await this.initialize();
+    
+    let sql = "SELECT * FROM task WHERE 1=1";
+    const params: any[] = [];
+    
+    if (options?.status) { sql += " AND status = ?"; params.push(options.status); }
+    if (options?.priority) { sql += " AND priority = ?"; params.push(options.priority); }
+    if (options?.parent_task_id !== undefined) { sql += " AND parent_task_id = ?"; params.push(options.parent_task_id); }
+    
+    sql += " ORDER BY updated_at DESC";
+    
+    if (options?.limit) { sql += " LIMIT ?"; params.push(options.limit); }
+    if (options?.offset) { sql += " OFFSET ?"; params.push(options.offset); }
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(...params) as any[];
+    
+    return rows.map(row => {
+      const task = this.rowToTask(row);
+      this.tasksCache.set(task.id, task);
+      return task;
+    });
+  }
+
+  // ========================================================================
+  // Operation CRUD
+  // ========================================================================
+
+  async createOperation(options: CreateOperationOptions): Promise<TaskOperation> {
+    await this.initialize();
+    
+    const now = Date.now();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO task_operation (task_id, session_id, action_type, action_title, 
+        action_description, timestamp, md_path)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const result = stmt.run(
+      options.taskId,
+      options.sessionId,
+      options.actionType,
+      options.actionTitle,
+      options.actionDescription || "",
+      now,
+      options.mdPath || null
+    );
+    
+    // 清除操作缓存
+    this.operationsCache.delete(options.taskId);
+    
+    const operation = await this.getOperation(result.lastInsertRowid as number);
+    if (!operation) {
+      throw new Error("Failed to create operation");
+    }
+    return operation;
+  }
+
+  async getOperation(id: number): Promise<TaskOperation | undefined> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("SELECT * FROM task_operation WHERE id = ?");
+    const row = stmt.get(id) as any;
+    if (!row) return undefined;
+    return this.rowToOperation(row);
+  }
+
+  async updateOperation(id: number, updates: { actionTitle?: string; actionDescription?: string }): Promise<TaskOperation | undefined> {
+    await this.initialize();
+    
+    const op = await this.getOperation(id);
+    if (!op) return undefined;
+    
+    const setClauses: string[] = [];
+    const values: any[] = [];
+    
+    if (updates.actionTitle !== undefined) { setClauses.push("action_title = ?"); values.push(updates.actionTitle); }
+    if (updates.actionDescription !== undefined) { setClauses.push("action_description = ?"); values.push(updates.actionDescription); }
+    
+    if (setClauses.length === 0) return op;
+    
+    const stmt = this.db.prepare(`UPDATE task_operation SET ${setClauses.join(", ")} WHERE id = ?`);
+    stmt.run(...values, id);
+    
+    // 清除缓存
+    this.operationsCache.delete(op.taskId);
+    
+    return this.getOperation(id);
+  }
+
+  async deleteOperation(id: number): Promise<boolean> {
+    await this.initialize();
+    
+    const op = await this.getOperation(id);
+    if (!op) return false;
+    
+    const stmt = this.db.prepare("DELETE FROM task_operation WHERE id = ?");
+    const result = stmt.run(id);
+    
+    if (result.changes > 0) {
+      this.operationsCache.delete(op.taskId);
+    }
+    
+    return result.changes > 0;
+  }
+
+  async listOperations(options: ListOperationsOptions): Promise<TaskOperation[]> {
+    await this.initialize();
+    
+    // 检查缓存
+    const cacheKey = options.taskId;
+    if (!this.operationsCache.has(cacheKey)) {
+      const stmt = this.db.prepare("SELECT * FROM task_operation WHERE task_id = ? ORDER BY timestamp DESC");
+      const rows = stmt.all(options.taskId) as any[];
+      this.operationsCache.set(cacheKey, rows.map(row => this.rowToOperation(row)));
+    }
+    
+    let ops = this.operationsCache.get(cacheKey)!;
+    
+    // 按 action_type 筛选
+    if (options.actionType) {
+      ops = ops.filter(op => op.actionType === options.actionType);
+    }
+    
+    // 分页
+    const offset = options.offset || 0;
+    const limit = options.limit || 20;
+    
+    return ops.slice(offset, offset + limit);
+  }
+
+  // ========================================================================
+  // Helpers
+  // ========================================================================
+
+  private rowToTask(row: any): Task {
+    return {
+      id: row.id,
+      title: row.title,
+      description: row.description,
+      status: row.status,
+      priority: row.priority,
+      progress: row.progress,
+      current_status: row.current_status,
+      goals_and_expected_deliverables: row.goals_and_expected_deliverables,
+      parent_task_id: row.parent_task_id || undefined,
+      createdAt: new Date(row.created_at).toISOString(),
+      updatedAt: new Date(row.updated_at).toISOString(),
+      due_date: row.due_date || undefined,
+      tags: row.tags ? JSON.parse(row.tags) : undefined,
+    };
+  }
+
+  private rowToOperation(row: any): TaskOperation {
+    return {
+      id: row.id,
+      taskId: row.task_id,
+      sessionId: row.session_id,
+      actionType: row.action_type,
+      actionTitle: row.action_title,
+      actionDescription: row.action_description,
+      timestamp: new Date(row.timestamp).toISOString(),
+      mdPath: row.md_path || undefined,
+    };
+  }
+
+  // ========================================================================
+  // Tag CRUD
+  // ========================================================================
+
+  async createTag(name: string): Promise<TaskTag> {
+    await this.initialize();
+    
+    const now = Date.now();
+    
+    // 检查是否已存在
+    const existing = await this.getTagByName(name);
+    if (existing) {
+      return existing;
+    }
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO task_tag (name, created_at, task_count)
+      VALUES (?, ?, 0)
+    `);
+    
+    const result = stmt.run(name, now);
+    
+    return {
+      id: result.lastInsertRowid as number,
+      name,
+      createdAt: new Date(now).toISOString(),
+      taskCount: 0,
+    };
+  }
+
+  async getTag(id: number): Promise<TaskTag | undefined> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("SELECT * FROM task_tag WHERE id = ?");
+    const row = stmt.get(id) as any;
+    if (!row) return undefined;
+    return this.rowToTag(row);
+  }
+
+  async getTagByName(name: string): Promise<TaskTag | undefined> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("SELECT * FROM task_tag WHERE name = ?");
+    const row = stmt.get(name) as any;
+    if (!row) return undefined;
+    return this.rowToTag(row);
+  }
+
+  async listTags(options?: ListTagsOptions): Promise<TaskTag[]> {
+    await this.initialize();
+    
+    let sql = "SELECT * FROM task_tag";
+    const params: any[] = [];
+    
+    // 排序
+    const orderBy = options?.orderBy || "count";
+    if (orderBy === "count") {
+      sql += " ORDER BY task_count DESC";
+    } else if (orderBy === "name") {
+      sql += " ORDER BY name ASC";
+    } else {
+      sql += " ORDER BY created_at DESC";
+    }
+    
+    // 分页
+    if (options?.limit) { sql += " LIMIT ?"; params.push(options.limit); }
+    if (options?.offset) { sql += " OFFSET ?"; params.push(options.offset); }
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(...params) as any[];
+    
+    return rows.map(row => this.rowToTag(row));
+  }
+
+  async searchTags(options: SearchTagsOptions): Promise<TaskTag[]> {
+    await this.initialize();
+    
+    const sql = `
+      SELECT * FROM task_tag 
+      WHERE name LIKE ? 
+      ORDER BY task_count DESC 
+      LIMIT ?
+    `;
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(`%${options.query}%`, options.limit || 20) as any[];
+    
+    return rows.map(row => this.rowToTag(row));
+  }
+
+  async deleteTag(id: number): Promise<boolean> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("DELETE FROM task_tag WHERE id = ?");
+    const result = stmt.run(id);
+    
+    return result.changes > 0;
+  }
+
+  // ========================================================================
+  // Tag 与 Task 关联
+  // ========================================================================
+
+  async addTagsToTask(taskId: number, tagIds: number[]): Promise<void> {
+    await this.initialize();
+    
+    const now = Date.now();
+    const stmt = this.db.prepare(`
+      INSERT OR IGNORE INTO task_tag_relation (task_id, tag_id, created_at)
+      VALUES (?, ?, ?)
+    `);
+    
+    for (const tagId of tagIds) {
+      stmt.run(taskId, tagId, now);
+      
+      // 更新 task_count
+      this.db.run(`
+        UPDATE task_tag SET task_count = task_count + 1 WHERE id = ?
+      `, tagId);
+    }
+    
+    // 更新 task.tags JSON 字段
+    await this.syncTaskTagsJson(taskId);
+  }
+
+  async removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void> {
+    await this.initialize();
+    
+    const stmt = this.db.prepare("DELETE FROM task_tag_relation WHERE task_id = ? AND tag_id = ?");
+    
+    for (const tagId of tagIds) {
+      stmt.run(taskId, tagId);
+      
+      // 减少 task_count
+      this.db.run(`
+        UPDATE task_tag SET task_count = MAX(0, task_count - 1) WHERE id = ?
+      `, tagId);
+    }
+    
+    // 更新 task.tags JSON 字段
+    await this.syncTaskTagsJson(taskId);
+  }
+
+  async getTagsForTask(taskId: number): Promise<TaskTag[]> {
+    await this.initialize();
+    
+    const sql = `
+      SELECT t.* FROM task_tag t
+      INNER JOIN task_tag_relation r ON t.id = r.tag_id
+      WHERE r.task_id = ?
+      ORDER BY t.name ASC
+    `;
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(taskId) as any[];
+    
+    return rows.map(row => this.rowToTag(row));
+  }
+
+  async getTaskIdsByTags(tagNames: string[]): Promise<number[]> {
+    await this.initialize();
+    
+    if (tagNames.length === 0) return [];
+    
+    const placeholders = tagNames.map(() => "?").join(", ");
+    const sql = `
+      SELECT DISTINCT r.task_id FROM task_tag_relation r
+      INNER JOIN task_tag t ON r.tag_id = t.id
+      WHERE t.name IN (${placeholders})
+    `;
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(...tagNames) as any[];
+    
+    return rows.map(row => row.task_id);
+  }
+
+  async updateTaskTags(taskId: number, tagNames: string[]): Promise<void> {
+    await this.initialize();
+    
+    // 先删除所有关联
+    const currentTags = await this.getTagsForTask(taskId);
+    if (currentTags.length > 0) {
+      await this.removeTagsFromTask(taskId, currentTags.map(t => t.id));
+    }
+    
+    // 再添加新关联
+    const tagIds: number[] = [];
+    for (const name of tagNames) {
+      let tag = await this.getTagByName(name);
+      if (!tag) {
+        tag = await this.createTag(name);
+      }
+      tagIds.push(tag.id);
+    }
+    
+    if (tagIds.length > 0) {
+      await this.addTagsToTask(taskId, tagIds);
+    }
+  }
+
+  // ========================================================================
+  // 检索能力（核心改造）
+  // ========================================================================
+
+  /**
+   * Search tasks by keywords list
+   * Searches in: tags (JSON), description, goals_and_expected_deliverables, operations
+   */
+  async searchTasksByKeywords(
+    keywords: string[],
+    options: { limit?: number; excludeTaskId?: number } = {}
+  ): Promise<Task[]> {
+    await this.initialize();
+
+    if (!keywords || keywords.length === 0) {
+      return [];
+    }
+
+    const { limit = 20, excludeTaskId } = options;
+    const tasks: Map<number, { task: Task; matchCount: number }> = new Map();
+
+    // 1. Search in task fields (tags JSON, description, goals)
+    let taskSql = "SELECT * FROM task WHERE 1=1";
+    const taskParams: any[] = [];
+
+    if (excludeTaskId) {
+      taskSql += " AND id != ?";
+      taskParams.push(excludeTaskId);
+    }
+
+    taskSql += " ORDER BY updated_at DESC LIMIT ?";
+    taskParams.push(limit * 2); // Get more to account for filtering
+
+    const taskRows = this.db.prepare(taskSql).all(...taskParams) as any[];
+
+    for (const row of taskRows) {
+      const task = this.rowToTask(row);
+      let matchCount = 0;
+
+      // Check title (case-insensitive)
+      if (task.title) {
+        const lowerTitle = task.title.toLowerCase();
+        for (const keyword of keywords) {
+          if (lowerTitle.includes(keyword.toLowerCase())) {
+            matchCount++;
+          }
+        }
+      }
+
+      // Check tags (JSON array) - higher weight
+      if (task.tags && Array.isArray(task.tags)) {
+        for (const keyword of keywords) {
+          const lowerKeyword = keyword.toLowerCase();
+          if (task.tags.some(tag => tag.toLowerCase().includes(lowerKeyword))) {
+            matchCount += 2; // Tags have higher weight
+          }
+        }
+      }
+
+      // Check description
+      if (task.description) {
+        const lowerDesc = task.description.toLowerCase();
+        for (const keyword of keywords) {
+          if (lowerDesc.includes(keyword.toLowerCase())) {
+            matchCount++;
+          }
+        }
+      }
+
+      // Check goals
+      if (task.goals_and_expected_deliverables) {
+        const lowerGoals = task.goals_and_expected_deliverables.toLowerCase();
+        for (const keyword of keywords) {
+          if (lowerGoals.includes(keyword.toLowerCase())) {
+            matchCount++;
+          }
+        }
+      }
+
+      if (matchCount > 0) {
+        tasks.set(task.id, { task, matchCount });
+      }
+    }
+
+    // 2. Search in operations
+    const allOps = this.db.prepare(
+      "SELECT DISTINCT task_id FROM task_operation WHERE 1=1"
+    ).all() as any[];
+
+    for (const opRow of allOps) {
+      const opSql = `
+        SELECT * FROM task_operation 
+        WHERE task_id = ? 
+          AND (action_title LIKE ? OR action_description LIKE ?)
+        LIMIT 10
+      `;
+
+      for (const keyword of keywords) {
+        const pattern = `%${keyword}%`;
+        const ops = this.db.prepare(opSql).all(opRow.task_id, pattern, pattern) as any[];
+
+        if (ops.length > 0) {
+          const taskRow = this.db.prepare("SELECT * FROM task WHERE id = ?").get(opRow.task_id) as any;
+          if (taskRow) {
+            const task = this.rowToTask(taskRow);
+            if (excludeTaskId && task.id === excludeTaskId) continue;
+
+            const existing = tasks.get(task.id);
+            if (existing) {
+              existing.matchCount += 2; // Operations also add weight
+            } else {
+              tasks.set(task.id, { task, matchCount: 2 });
+            }
+          }
+        }
+      }
+    }
+
+    // Sort by match count and return
+    const results = Array.from(tasks.values())
+      .sort((a, b) => b.matchCount - a.matchCount)
+      .slice(0, limit)
+      .map(item => item.task);
+
+    return results;
+  }
+
+  /**
+   * Find similar tasks by keywords
+   * Excludes the target task and sorts by relevance
+   * Default limit is 5 to keep prompt concise
+   */
+  async findSimilarTasksByKeywords(
+    keywords: string[],
+    options: { limit?: number; excludeTaskId?: number } = {}
+  ): Promise<Task[]> {
+    // Default to 5 for similar tasks search to keep prompt concise
+    const mergedOptions = { ...options, limit: options.limit ?? 5 };
+    return this.searchTasksByKeywords(keywords, mergedOptions);
+  }
+
+  // ========================================================================
+  // 检索能力（向后兼容）
+  // ========================================================================
+
+  async findSimilarTasks(taskId: number, limit: number = 5): Promise<Task[]> {
+    await this.initialize();
+    
+    // 获取当前 Task 的 Tags
+    const taskTags = await this.getTagsForTask(taskId);
+    if (taskTags.length === 0) {
+      return [];
+    }
+    
+    const tagIds = taskTags.map(t => t.id);
+    const placeholders = tagIds.map(() => "?").join(", ");
+    
+    // 查找有相同 Tag 的 Task（排除自己），按匹配数量排序
+    const sql = `
+      SELECT t.*, COUNT(r2.tag_id) as match_count
+      FROM task t
+      INNER JOIN task_tag_relation r ON t.id = r.task_id
+      INNER JOIN task_tag_relation r2 ON t.id = r2.task_id
+      WHERE r.tag_id IN (${placeholders})
+        AND t.id != ?
+      GROUP BY t.id
+      ORDER BY match_count DESC, t.updated_at DESC
+      LIMIT ?
+    `;
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(...tagIds, taskId, limit) as any[];
+    
+    return rows.map(row => this.rowToTask(row));
+  }
+
+  async searchTasks(query: string, limit: number = 20): Promise<Task[]> {
+    await this.initialize();
+    
+    const sql = `
+      SELECT * FROM task 
+      WHERE title LIKE ? OR description LIKE ?
+      ORDER BY updated_at DESC
+      LIMIT ?
+    `;
+    
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(`%${query}%`, `%${query}%`, limit) as any[];
+    
+    return rows.map(row => this.rowToTask(row));
+  }
+
+  // ========================================================================
+  // 私有方法
+  // ========================================================================
+
+  private rowToTag(row: any): TaskTag {
+    return {
+      id: row.id,
+      name: row.name,
+      createdAt: new Date(row.created_at).toISOString(),
+      taskCount: row.task_count,
+    };
+  }
+
+  private async syncTaskTagsJson(taskId: number): Promise<void> {
+    const tags = await this.getTagsForTask(taskId);
+    const tagNames = tags.map(t => t.name);
+    
+    const stmt = this.db.prepare("UPDATE task SET tags = ? WHERE id = ?");
+    stmt.run(tagNames.length > 0 ? JSON.stringify(tagNames) : null, taskId);
+    
+    // 清除缓存
+    this.tasksCache.delete(taskId);
+  }
+
+  async close(): Promise<void> {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+      this.initialized = false;
+    }
+  }
+}
+
+// 导出默认路径
+export { getDefaultTaskDbPath, getDefaultDataDir };