autosnippet 3.1.15 → 3.2.2

package/lib/infrastructure/database/migrations/002_add_tasks.js

@@ -0,0 +1,88 @@
+/**
+ * Migration 002: TaskGraph 任务表
+ *
+ * 新增 tasks 表 + task_dependencies 表 + task_events 表。
+ *
+ * 设计决策 D1: 独立 task_dependencies 表（不复用 knowledge_edges）
+ *   - 语义不同（任务依赖 vs 知识关系）
+ *   - 需要专门的索引优化就绪检测查询
+ *   - 避免与知识图谱互相污染
+ */
+export default function migrate(db) {
+  // ── tasks 表 ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id              TEXT PRIMARY KEY,
+      parent_id       TEXT,
+      child_seq       INTEGER DEFAULT 0,
+
+      title           TEXT NOT NULL,
+      description     TEXT DEFAULT '',
+      design          TEXT DEFAULT '',
+      acceptance      TEXT DEFAULT '',
+      notes           TEXT DEFAULT '',
+
+      status          TEXT NOT NULL DEFAULT 'open',
+      priority        INTEGER NOT NULL DEFAULT 2,
+      task_type       TEXT NOT NULL DEFAULT 'task',
+      close_reason    TEXT DEFAULT '',
+      content_hash    TEXT DEFAULT '',
+      fail_count      INTEGER DEFAULT 0,
+      last_fail_reason TEXT DEFAULT '',
+
+      assignee        TEXT DEFAULT '',
+      created_by      TEXT DEFAULT 'agent',
+
+      created_at      INTEGER NOT NULL,
+      updated_at      INTEGER NOT NULL,
+      closed_at       INTEGER,
+
+      metadata        TEXT DEFAULT '{}'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_tasks_status     ON tasks(status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_priority   ON tasks(priority);
+    CREATE INDEX IF NOT EXISTS idx_tasks_parent     ON tasks(parent_id);
+    CREATE INDEX IF NOT EXISTS idx_tasks_type       ON tasks(task_type);
+    CREATE INDEX IF NOT EXISTS idx_tasks_assignee   ON tasks(assignee);
+    CREATE INDEX IF NOT EXISTS idx_tasks_created    ON tasks(created_at);
+    CREATE INDEX IF NOT EXISTS idx_tasks_hash       ON tasks(content_hash);
+  `);
+
+  // ── task_dependencies 表 ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS task_dependencies (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id         TEXT NOT NULL,
+      depends_on_id   TEXT NOT NULL,
+      dep_type        TEXT NOT NULL DEFAULT 'blocks',
+      metadata        TEXT DEFAULT '{}',
+      created_at      INTEGER NOT NULL,
+      created_by      TEXT DEFAULT 'agent',
+
+      UNIQUE (task_id, depends_on_id, dep_type)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_td_task       ON task_dependencies(task_id);
+    CREATE INDEX IF NOT EXISTS idx_td_depends_on ON task_dependencies(depends_on_id);
+    CREATE INDEX IF NOT EXISTS idx_td_type       ON task_dependencies(dep_type);
+  `);
+
+  // ── task_events 审计表 ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS task_events (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id         TEXT NOT NULL,
+      event_type      TEXT NOT NULL,
+      actor           TEXT DEFAULT 'agent',
+      old_value       TEXT,
+      new_value       TEXT,
+      comment         TEXT,
+      created_at      INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_te_task    ON task_events(task_id);
+    CREATE INDEX IF NOT EXISTS idx_te_type    ON task_events(event_type);
+    CREATE INDEX IF NOT EXISTS idx_te_created ON task_events(created_at);
+  `);
+}

package/lib/injection/ServiceContainer.js

@@ -64,6 +64,12 @@ import { SnippetFactory } from '../service/snippet/SnippetFactory.js';
 import { SnippetInstaller } from '../service/snippet/SnippetInstaller.js';
 import { DimensionCopy } from '../shared/DimensionCopyRegistry.js';
 import { LanguageService } from '../shared/LanguageService.js';
+// ─── TaskGraph ────────────────────────────────────────
+import { TaskIdGenerator } from '../domain/task/TaskIdGenerator.js';
+import { TaskRepositoryImpl } from '../repository/task/TaskRepository.impl.js';
+import { TaskReadyEngine } from '../service/task/TaskReadyEngine.js';
+import { TaskKnowledgeBridge } from '../service/task/TaskKnowledgeBridge.js';
+import { TaskGraphService } from '../service/task/TaskGraphService.js';
 
 /**
  * DependencyInjection 容器
@@ -359,6 +365,15 @@ export class ServiceContainer {
       }
       return this.singletons.knowledgeSyncService;
     });
+
+    // TaskRepository (TaskGraph 持久化)
+    this.register('taskRepository', () => {
+      if (!this.singletons.taskRepository) {
+        const database = this.get('database');
+        this.singletons.taskRepository = new TaskRepositoryImpl(database);
+      }
+      return this.singletons.taskRepository;
+    });
   }
 
   /**
@@ -759,6 +774,49 @@ export class ServiceContainer {
       }
       return this.singletons.cursorDeliveryPipeline;
     });
+
+    // ─── TaskGraph Services ───────────────────────────
+    // TaskIdGenerator (短 Hash ID 生成器)
+    this.register('taskIdGenerator', () => {
+      if (!this.singletons.taskIdGenerator) {
+        const database = this.get('database');
+        this.singletons.taskIdGenerator = new TaskIdGenerator(database.getDb());
+      }
+      return this.singletons.taskIdGenerator;
+    });
+
+    // TaskReadyEngine (递归 CTE 就绪检测)
+    this.register('taskReadyEngine', () => {
+      if (!this.singletons.taskReadyEngine) {
+        const database = this.get('database');
+        this.singletons.taskReadyEngine = new TaskReadyEngine(database.getDb());
+      }
+      return this.singletons.taskReadyEngine;
+    });
+
+    // TaskKnowledgeBridge (任务 ↔ 知识桥接)
+    this.register('taskKnowledgeBridge', () => {
+      if (!this.singletons.taskKnowledgeBridge) {
+        const searchEngine = this.get('searchEngine');
+        this.singletons.taskKnowledgeBridge = new TaskKnowledgeBridge(searchEngine);
+      }
+      return this.singletons.taskKnowledgeBridge;
+    });
+
+    // TaskGraphService (任务图核心服务)
+    this.register('taskGraphService', () => {
+      if (!this.singletons.taskGraphService) {
+        const repository = this.get('taskRepository');
+        const readyEngine = this.get('taskReadyEngine');
+        const knowledgeBridge = this.get('taskKnowledgeBridge');
+        const auditLogger = this.get('auditLogger');
+        const idGenerator = this.get('taskIdGenerator');
+        this.singletons.taskGraphService = new TaskGraphService(
+          repository, readyEngine, knowledgeBridge, auditLogger, idGenerator
+        );
+      }
+      return this.singletons.taskGraphService;
+    });
   }
 
   /**

package/lib/repository/task/TaskRepository.impl.js

@@ -0,0 +1,398 @@
+import { Task } from '../../domain/task/Task.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+/**
+ * TaskRepositoryImpl — 任务实体 SQLite 持久化
+ *
+ * 直接操作 better-sqlite3 同步 API，方法签名保持 async 以对齐 DDD 接口约定。
+ * DB 列名 snake_case，实体属性 camelCase—— Task.fromRow() / _entityToRow() 负责映射。
+ */
+export class TaskRepositoryImpl {
+  /**
+   * @param {import('../../infrastructure/database/DatabaseConnection.js').default} database
+   */
+  constructor(database) {
+    this.db = database.getDb();
+    this.logger = Logger.getInstance();
+    this._prepareStatements();
+  }
+
+  /** @private 预编译常用语句 */
+  _prepareStatements() {
+    this._insertStmt = this.db.prepare(`
+      INSERT INTO tasks (
+        id, parent_id, child_seq,
+        title, description, design, acceptance, notes,
+        status, priority, task_type, close_reason, content_hash,
+        fail_count, last_fail_reason,
+        assignee, created_by,
+        created_at, updated_at, closed_at,
+        metadata
+      ) VALUES (
+        @id, @parent_id, @child_seq,
+        @title, @description, @design, @acceptance, @notes,
+        @status, @priority, @task_type, @close_reason, @content_hash,
+        @fail_count, @last_fail_reason,
+        @assignee, @created_by,
+        @created_at, @updated_at, @closed_at,
+        @metadata
+      )
+    `);
+
+    this._findByIdStmt = this.db.prepare('SELECT * FROM tasks WHERE id = ? LIMIT 1');
+
+    this._findByHashStmt = this.db.prepare(
+      "SELECT * FROM tasks WHERE content_hash = ? AND status != 'closed' LIMIT 1"
+    );
+
+    this._updateFieldsStmt = null; // 动态构建
+
+    this._deleteStmt = this.db.prepare('DELETE FROM tasks WHERE id = ?');
+
+    // ── 依赖相关 ──
+    this._addDepStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_id, dep_type, created_at, created_by)
+      VALUES (?, ?, ?, ?, 'agent')
+    `);
+
+    this._removeDepStmt = this.db.prepare(
+      'DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_id = ? AND dep_type = ?'
+    );
+
+    this._getDepsStmt = this.db.prepare(
+      'SELECT * FROM task_dependencies WHERE task_id = ? ORDER BY created_at'
+    );
+
+    this._getDependentsStmt = this.db.prepare(
+      'SELECT * FROM task_dependencies WHERE depends_on_id = ?'
+    );
+
+    this._getBlockersStmt = this.db.prepare(`
+      SELECT t.*
+      FROM task_dependencies td
+      JOIN tasks t ON td.depends_on_id = t.id
+      WHERE td.task_id = ?
+        AND td.dep_type IN ('blocks', 'waits-for')
+        AND t.status != 'closed'
+    `);
+
+    // ── 环检测 (递归 CTE) ──
+    this._reachableStmt = this.db.prepare(`
+      WITH RECURSIVE reachable(id, depth) AS (
+        SELECT depends_on_id, 1
+        FROM task_dependencies
+        WHERE task_id = ?
+          AND dep_type IN ('blocks', 'waits-for')
+
+        UNION ALL
+
+        SELECT td.depends_on_id, r.depth + 1
+        FROM task_dependencies td
+        JOIN reachable r ON td.task_id = r.id
+        WHERE td.dep_type IN ('blocks', 'waits-for')
+          AND r.depth < 50
+      )
+      SELECT 1 FROM reachable WHERE id = ? LIMIT 1
+    `);
+
+    // ── 事件审计 ──
+    this._logEventStmt = this.db.prepare(`
+      INSERT INTO task_events (task_id, event_type, actor, old_value, new_value, comment, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    // ── 统计 ──
+    this._statsStmt = this.db.prepare(`
+      SELECT
+        COUNT(*)                                           as total,
+        SUM(CASE WHEN status = 'open'        THEN 1 ELSE 0 END) as open,
+        SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
+        SUM(CASE WHEN status = 'closed'      THEN 1 ELSE 0 END) as closed,
+        SUM(CASE WHEN status = 'deferred'    THEN 1 ELSE 0 END) as deferred
+      FROM tasks
+    `);
+  }
+
+  // ═══ CRUD ═══════════════════════════════════════════
+
+  /**
+   * 创建任务
+   * @param {Task} task
+   * @returns {Task}
+   */
+  create(task) {
+    const row = this._entityToRow(task);
+    this._insertStmt.run(row);
+    return this.findById(task.id);
+  }
+
+  /**
+   * 按 ID 查询
+   * @param {string} id
+   * @returns {Task|null}
+   */
+  findById(id) {
+    const row = this._findByIdStmt.get(id);
+    return row ? Task.fromRow(row) : null;
+  }
+
+  /**
+   * 按内容哈希查询（去重用）
+   * @param {string} hash
+   * @returns {Task|null}
+   */
+  findByContentHash(hash) {
+    if (!hash) return null;
+    const row = this._findByHashStmt.get(hash);
+    return row ? Task.fromRow(row) : null;
+  }
+
+  /**
+   * 更新任务字段
+   * @param {string} id
+   * @param {object} fields — 部分字段 (camelCase)
+   * @returns {Task}
+   */
+  update(id, fields) {
+    const columnMap = {
+      status: 'status',
+      priority: 'priority',
+      assignee: 'assignee',
+      notes: 'notes',
+      description: 'description',
+      design: 'design',
+      acceptance: 'acceptance',
+      closeReason: 'close_reason',
+      closedAt: 'closed_at',
+      updatedAt: 'updated_at',
+      failCount: 'fail_count',
+      lastFailReason: 'last_fail_reason',
+      childSeq: 'child_seq',
+      metadata: 'metadata',
+    };
+
+    const setClauses = [];
+    const values = [];
+
+    for (const [key, value] of Object.entries(fields)) {
+      const col = columnMap[key];
+      if (!col) continue;
+      setClauses.push(`${col} = ?`);
+      values.push(key === 'metadata' ? JSON.stringify(value) : value);
+    }
+
+    if (setClauses.length === 0) return this.findById(id);
+
+    // 始终更新 updated_at
+    if (!fields.updatedAt) {
+      setClauses.push('updated_at = ?');
+      values.push(Math.floor(Date.now() / 1000));
+    }
+
+    values.push(id);
+    const sql = `UPDATE tasks SET ${setClauses.join(', ')} WHERE id = ?`;
+    this.db.prepare(sql).run(...values);
+
+    return this.findById(id);
+  }
+
+  /**
+   * 删除任务
+   * @param {string} id
+   * @returns {boolean}
+   */
+  delete(id) {
+    const result = this._deleteStmt.run(id);
+    return result.changes > 0;
+  }
+
+  /**
+   * 列表查询
+   * @param {object} filters — { status, taskType, assignee, parentId }
+   * @param {object} options — { limit, offset, orderBy }
+   * @returns {Task[]}
+   */
+  findAll(filters = {}, options = {}) {
+    const conditions = [];
+    const params = [];
+
+    if (filters.status) {
+      conditions.push('status = ?');
+      params.push(filters.status);
+    }
+    if (filters.taskType) {
+      conditions.push('task_type = ?');
+      params.push(filters.taskType);
+    }
+    if (filters.assignee) {
+      conditions.push('assignee = ?');
+      params.push(filters.assignee);
+    }
+    if (filters.parentId) {
+      conditions.push('parent_id = ?');
+      params.push(filters.parentId);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = Math.max(1, Math.min(options.limit || 50, 500));
+    const offset = Math.max(0, options.offset || 0);
+    const orderBy = _sanitizeOrderBy(options.orderBy);
+
+    const sql = `SELECT * FROM tasks ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`;
+    params.push(limit, offset);
+
+    const rows = this.db.prepare(sql).all(...params);
+    return rows.map((r) => Task.fromRow(r));
+  }
+
+  // ═══ 依赖管理 ═══════════════════════════════════════
+
+  /**
+   * 添加依赖
+   */
+  addDependency(taskId, dependsOnId, depType) {
+    this._addDepStmt.run(taskId, dependsOnId, depType, Math.floor(Date.now() / 1000));
+  }
+
+  /**
+   * 删除依赖
+   */
+  removeDependency(taskId, dependsOnId, depType) {
+    this._removeDepStmt.run(taskId, dependsOnId, depType);
+  }
+
+  /**
+   * 获取任务的所有依赖
+   */
+  getDependencies(taskId) {
+    return this._getDepsStmt.all(taskId);
+  }
+
+  /**
+   * 获取依赖此任务的所有任务
+   */
+  getDependents(dependsOnId) {
+    return this._getDependentsStmt.all(dependsOnId);
+  }
+
+  /**
+   * 获取阻塞某任务的所有任务（含任务详情）
+   */
+  getBlockers(taskId) {
+    return this._getBlockersStmt.all(taskId).map((r) => Task.fromRow(r));
+  }
+
+  /**
+   * 环检测：检查 fromId → toId 是否已有可达路径
+   * @param {string} fromId
+   * @param {string} toId
+   * @returns {boolean}
+   */
+  hasReachablePath(fromId, toId) {
+    const row = this._reachableStmt.get(fromId, toId);
+    return !!row;
+  }
+
+  // ═══ 事务支持 ═══════════════════════════════════════
+
+  /**
+   * 在事务中执行操作
+   * @param {Function} fn
+   * @returns {*}
+   */
+  inTransaction(fn) {
+    const txn = this.db.transaction(fn);
+    return txn();
+  }
+
+  // ═══ 统计 ═══════════════════════════════════════════
+
+  /**
+   * 获取任务统计
+   */
+  getStatistics() {
+    const row = this._statsStmt.get();
+    return {
+      total: row.total || 0,
+      open: row.open || 0,
+      in_progress: row.in_progress || 0,
+      closed: row.closed || 0,
+      deferred: row.deferred || 0,
+    };
+  }
+
+  // ═══ 事件审计 ═══════════════════════════════════════
+
+  /**
+   * 记录任务事件
+   */
+  logEvent(taskId, eventType, oldValue = null, newValue = null, comment = null, actor = 'agent') {
+    this._logEventStmt.run(
+      taskId,
+      eventType,
+      actor,
+      oldValue,
+      newValue,
+      comment,
+      Math.floor(Date.now() / 1000)
+    );
+  }
+
+  // ═══ 私有方法 ═══════════════════════════════════════
+
+  /**
+   * 实体 → DB 行 (camelCase → snake_case)
+   * @param {Task} task
+   * @returns {object}
+   */
+  _entityToRow(task) {
+    return {
+      id: task.id,
+      parent_id: task.parentId || null,
+      child_seq: task.childSeq || 0,
+      title: task.title,
+      description: task.description || '',
+      design: task.design || '',
+      acceptance: task.acceptance || '',
+      notes: task.notes || '',
+      status: task.status,
+      priority: task.priority ?? 2,
+      task_type: task.taskType || 'task',
+      close_reason: task.closeReason || '',
+      content_hash: task.contentHash || '',
+      fail_count: task.failCount || 0,
+      last_fail_reason: task.lastFailReason || '',
+      assignee: task.assignee || '',
+      created_by: task.createdBy || 'agent',
+      created_at: task.createdAt,
+      updated_at: task.updatedAt,
+      closed_at: task.closedAt || null,
+      metadata: JSON.stringify(task.metadata || {}),
+    };
+  }
+}
+
+// ═══ 内部工具 ═══════════════════════════════════════
+
+const ALLOWED_ORDER_FIELDS = new Set([
+  'priority', 'created_at', 'updated_at', 'status', 'title', 'task_type', 'closed_at',
+]);
+const ALLOWED_DIRECTIONS = new Set(['ASC', 'DESC']);
+
+/**
+ * orderBy 白名单校验，防止 SQL 注入
+ * @param {string} [orderBy]
+ * @returns {string}
+ */
+function _sanitizeOrderBy(orderBy) {
+  if (!orderBy) return 'priority ASC, created_at ASC';
+  return orderBy.split(',').map((clause) => {
+    const parts = clause.trim().split(/\s+/);
+    const field = parts[0];
+    if (!ALLOWED_ORDER_FIELDS.has(field)) return null;
+    const dir = ALLOWED_DIRECTIONS.has(parts[1]?.toUpperCase()) ? parts[1].toUpperCase() : 'ASC';
+    return `${field} ${dir}`;
+  }).filter(Boolean).join(', ') || 'priority ASC, created_at ASC';
+}
+
+export default TaskRepositoryImpl;

package/lib/service/cursor/AgentInstructionsGenerator.js

@@ -55,6 +55,7 @@ const MCP_TOOLS_SUMMARY = [
   { name: 'autosnippet_skill', desc: 'Skill management (list/load/create/update/delete/suggest)' },
   { name: 'autosnippet_save_document', desc: 'Save development document (auto-publish)' },
   { name: 'autosnippet_bootstrap', desc: 'Project cold-start & scan (knowledge/refine/scan)' },
+  { name: 'autosnippet_task', desc: 'TaskGraph lifecycle (prime/claim/close/ready/create/fail/defer)' },
   { name: 'autosnippet_health', desc: 'Service health & KB statistics' },
   { name: 'autosnippet_capabilities', desc: 'List all available MCP tools (self-discovery)' },
 ];
@@ -278,16 +279,19 @@ export class AgentInstructionsGenerator {
     // Key tools highlight for Claude
     lines.push('### Recommended Workflow', '');
     lines.push(
-      '1. **Before writing code**: `autosnippet_search({ query: "<topic>" })` to find relevant patterns'
+      '1. **Session start**: `autosnippet_task({ operation: "prime" })` — Restore task context'
     );
     lines.push(
-      '2. **Check compliance**: `autosnippet_guard({ code: "<your code>" })` before committing'
+      '2. **Before writing code**: `autosnippet_search({ query: "<topic>" })` to find relevant patterns'
     );
     lines.push(
-      '3. **Record knowledge**: `autosnippet_submit_knowledge({ ... })` when discovering reusable patterns'
+      '3. **Check compliance**: `autosnippet_guard({ code: "<your code>" })` before committing'
     );
     lines.push(
-      '4. **Confirm adoption**: `autosnippet_knowledge({ operation: "confirm_usage", id: "<id>" })`'
+      '4. **Complete task**: `autosnippet_task({ operation: "close", id: "<id>" })`'
+    );
+    lines.push(
+      '5. **Guard diagnostics**: Read ruleId → `autosnippet_search({ query: "<ruleId>" })` → fix'
     );
     lines.push('');
 
@@ -400,11 +404,26 @@ export class AgentInstructionsGenerator {
     return [
       '## Recommended Workflow',
       '',
-      '1. **Search first**: `autosnippet_search({ query: "<topic>" })` before writing code',
-      '2. **Check patterns**: Look for existing `@trigger` patterns before implementing',
-      '3. **Guard check**: `autosnippet_guard({ code: "<code>" })` to validate compliance',
-      '4. **Submit discoveries**: `autosnippet_submit_knowledge({ ... })` for reusable patterns',
-      '5. **Confirm adoption**: `autosnippet_knowledge({ operation: "confirm_usage" })`',
+      '### Session Start (ALWAYS)',
+      '1. `autosnippet_task({ operation: "prime" })` — Restore task context',
+      '',
+      '### Task Lifecycle',
+      '2. `autosnippet_task({ operation: "claim", id: "asd-xxx" })` — Start working',
+      '3. `autosnippet_search({ query: "<topic>" })` — Search knowledge before coding',
+      '4. **CODE** — Write the implementation',
+      '5. `autosnippet_guard({ code: "<code>" })` — Check compliance',
+      '6. `autosnippet_task({ operation: "close", id: "asd-xxx" })` — Complete',
+      '',
+      '### Guard Diagnostics Response',
+      'When editor shows diagnostics from "AutoSnippet Guard":',
+      '1. Read the `ruleId` from the diagnostic message',
+      '2. `autosnippet_search({ query: "<ruleId>" })` to find the Recipe',
+      '3. Apply the Recipe\'s `doClause` + `coreCode` to fix',
+      '4. Save and verify the diagnostic disappears',
+      '',
+      '### Context Pressure',
+      '- `_contextHint: CONTEXT_PRESSURE:WARNING` → Summarize completed work, then continue',
+      '- `_contextHint: CONTEXT_PRESSURE:CRITICAL` → Call `autosnippet_task({ operation: "prime" })` immediately',
       '',
     ];
   }