aifastdb 2.2.1 → 2.2.6

package/dist/dev-plan-store.js

@@ -89,13 +89,40 @@ function sectionImportance(section) {
 }
 /**
  * 获取默认的 DevPlan 存储基础路径
+ *
+ * 优先级：
+ * 1. AIFASTDB_DEVPLAN_PATH 环境变量（显式指定）
+ * 2. 项目内 .devplan/ 目录（天然跟随 Git 版本管理）
+ * 3. 回退到用户目录 ~/.aifastdb/dev-plans/（兜底）
  */
 function getDefaultBasePath() {
     if (process.env.AIFASTDB_DEVPLAN_PATH) {
         return process.env.AIFASTDB_DEVPLAN_PATH;
     }
+    // 尝试定位项目根目录（查找 .git 或 package.json 所在目录）
+    const projectRoot = findProjectRoot();
+    if (projectRoot) {
+        return path.join(projectRoot, '.devplan');
+    }
+    // 兜底：用户目录
     return path.join(os.homedir(), '.aifastdb', 'dev-plans');
 }
+/**
+ * 从当前工作目录向上查找项目根目录
+ * 通过 .git 目录或 package.json 文件来判断
+ */
+function findProjectRoot() {
+    const fs = require('fs');
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
 // ============================================================================
 // DevPlanStore Implementation
 // ============================================================================
@@ -111,6 +138,7 @@ class DevPlanStore {
         this.projectName = projectName;
         this.docStore = new native_1.EnhancedDocumentStore(config.documentPath, (0, document_store_1.documentStoreProductionConfig)());
         this.taskStore = new native_1.EnhancedDocumentStore(config.taskPath, (0, document_store_1.documentStoreProductionConfig)());
+        this.moduleStore = new native_1.EnhancedDocumentStore(config.modulePath, (0, document_store_1.documentStoreProductionConfig)());
     }
     // ==========================================================================
     // Document Section Operations
@@ -128,15 +156,20 @@ class DevPlanStore {
         }
         const version = input.version || '1.0.0';
         const now = Date.now();
+        const finalModuleId = input.moduleId || existing?.moduleId;
+        const tags = [
+            `plan:${this.projectName}`,
+            `section:${input.section}`,
+            ...(input.subSection ? [`sub:${input.subSection}`] : []),
+            `ver:${version}`,
+        ];
+        if (finalModuleId) {
+            tags.push(`module:${finalModuleId}`);
+        }
         const docInput = {
             content: input.content,
             contentType: native_2.ContentType.Text,
-            tags: [
-                `plan:${this.projectName}`,
-                `section:${input.section}`,
-                ...(input.subSection ? [`sub:${input.subSection}`] : []),
-                `ver:${version}`,
-            ],
+            tags,
             metadata: {
                 projectName: this.projectName,
                 section: input.section,
@@ -144,6 +177,7 @@ class DevPlanStore {
                 version,
                 subSection: input.subSection || null,
                 relatedSections: input.relatedSections || [],
+                moduleId: finalModuleId || null,
                 createdAt: existing?.createdAt || now,
                 updatedAt: now,
             },
@@ -172,8 +206,8 @@ class DevPlanStore {
         }
         if (filtered.length === 0)
             return null;
-        // 返回最新版本
-        const latest = filtered.sort((a, b) => b.createdAt - a.createdAt)[0];
+        // 返回最新版本（以 metadata.updatedAt 为判定依据）
+        const latest = filtered.sort((a, b) => this.getDocUpdatedAt(b) - this.getDocUpdatedAt(a))[0];
         return this.docToDevPlanDoc(latest);
     }
     /**
@@ -184,14 +218,14 @@ class DevPlanStore {
     listSections() {
         const planTag = `plan:${this.projectName}`;
         const docs = this.docStore.findByTag(planTag);
-        // 按 section+subSection 去重，保留最新版本
+        // 按 section+subSection 去重，保留最新版本（以 metadata.updatedAt 判定）
         const latestMap = new Map();
         for (const doc of docs) {
             const sectionTag = doc.tags.find((t) => t.startsWith('section:'));
             const subTag = doc.tags.find((t) => t.startsWith('sub:'));
             const key = `${sectionTag || 'unknown'}|${subTag || ''}`;
             const existing = latestMap.get(key);
-            if (!existing || doc.createdAt > existing.createdAt) {
+            if (!existing || this.getDocUpdatedAt(doc) > this.getDocUpdatedAt(existing)) {
                 latestMap.set(key, doc);
             }
         }
@@ -223,14 +257,14 @@ class DevPlanStore {
     searchSections(query, limit = 10) {
         const planTag = `plan:${this.projectName}`;
         const allDocs = this.docStore.findByTag(planTag);
-        // 按 section+subSection 去重，保留最新版本
+        // 按 section+subSection 去重，保留最新版本（以 metadata.updatedAt 判定）
         const latestMap = new Map();
         for (const doc of allDocs) {
             const sectionTag = doc.tags.find((t) => t.startsWith('section:'));
             const subTag = doc.tags.find((t) => t.startsWith('sub:'));
             const key = `${sectionTag || 'unknown'}|${subTag || ''}`;
             const existing = latestMap.get(key);
-            if (!existing || doc.createdAt > existing.createdAt) {
+            if (!existing || this.getDocUpdatedAt(doc) > this.getDocUpdatedAt(existing)) {
                 latestMap.set(key, doc);
             }
         }
@@ -275,20 +309,25 @@ class DevPlanStore {
             totalSubtasks: 0,
             completedSubtasks: 0,
         };
+        const tags = [
+            `plan:${this.projectName}`,
+            'type:main-task',
+            `mtask:${input.taskId}`,
+            `priority:${input.priority}`,
+            'status:pending',
+        ];
+        if (input.moduleId) {
+            tags.push(`module:${input.moduleId}`);
+        }
         const docInput = {
             content: JSON.stringify(taskData),
             contentType: native_2.ContentType.Text,
-            tags: [
-                `plan:${this.projectName}`,
-                'type:main-task',
-                `mtask:${input.taskId}`,
-                `priority:${input.priority}`,
-                'status:pending',
-            ],
+            tags,
             metadata: {
                 projectName: this.projectName,
                 taskId: input.taskId,
                 status: 'pending',
+                moduleId: input.moduleId || null,
                 createdAt: now,
                 updatedAt: now,
                 completedAt: null,
@@ -301,17 +340,111 @@ class DevPlanStore {
             id,
             projectName: this.projectName,
             ...taskData,
+            moduleId: input.moduleId,
             status: 'pending',
             createdAt: now,
             updatedAt: now,
             completedAt: null,
         };
     }
+    /**
+     * 幂等导入主任务（Upsert）
+     *
+     * - 如果主任务不存在 → 创建新任务
+     * - 如果主任务已存在 → 更新标题/描述/优先级等字段，但保留已有的更高级状态
+     *   （例如已完成的任务不会被重置为 pending）
+     * - updatedAt 保证严格递增，不会与历史版本重复
+     *
+     * @param input 主任务输入
+     * @param options.preserveStatus 若为 true（默认），则不覆盖已完成的状态
+     * @param options.status 导入时的目标状态（默认 pending）
+     * @returns 创建或更新后的主任务
+     */
+    upsertMainTask(input, options) {
+        const preserveStatus = options?.preserveStatus !== false; // 默认 true
+        const targetStatus = options?.status || 'pending';
+        const existing = this.getMainTask(input.taskId);
+        if (!existing) {
+            // 新建
+            const task = this.createMainTask(input);
+            // 如果目标状态不是 pending，更新状态
+            if (targetStatus !== 'pending') {
+                return this.updateMainTaskStatus(task.taskId, targetStatus) || task;
+            }
+            return task;
+        }
+        // 已存在 — 决定最终状态
+        let finalStatus = targetStatus;
+        if (preserveStatus) {
+            // 状态优先级: completed > in_progress > pending > cancelled
+            const statusPriority = {
+                cancelled: 0,
+                pending: 1,
+                in_progress: 2,
+                completed: 3,
+            };
+            if (statusPriority[existing.status] >= statusPriority[targetStatus]) {
+                finalStatus = existing.status; // 保留更高级状态
+            }
+        }
+        // 删除旧版本并确保时间戳递增
+        this.deleteAndEnsureTimestampAdvance(this.taskStore, existing.id);
+        const now = Date.now();
+        const completedAt = finalStatus === 'completed' ? (existing.completedAt || now) : null;
+        const finalModuleId = input.moduleId || existing.moduleId;
+        const taskData = {
+            taskId: input.taskId,
+            title: input.title,
+            priority: input.priority,
+            description: input.description || existing.description || '',
+            estimatedHours: input.estimatedHours || existing.estimatedHours || 0,
+            relatedSections: input.relatedSections || existing.relatedSections || [],
+            totalSubtasks: existing.totalSubtasks,
+            completedSubtasks: existing.completedSubtasks,
+        };
+        const tags = [
+            `plan:${this.projectName}`,
+            'type:main-task',
+            `mtask:${input.taskId}`,
+            `priority:${input.priority}`,
+            `status:${finalStatus}`,
+        ];
+        if (finalModuleId) {
+            tags.push(`module:${finalModuleId}`);
+        }
+        const docInput = {
+            content: JSON.stringify(taskData),
+            contentType: native_2.ContentType.Text,
+            tags,
+            metadata: {
+                projectName: this.projectName,
+                taskId: input.taskId,
+                status: finalStatus,
+                moduleId: finalModuleId || null,
+                createdAt: existing.createdAt,
+                updatedAt: now,
+                completedAt,
+            },
+            importance: input.priority === 'P0' ? 0.95 : input.priority === 'P1' ? 0.8 : 0.6,
+        };
+        const id = this.taskStore.put(docInput);
+        this.taskStore.flush();
+        return {
+            ...taskData,
+            id,
+            projectName: this.projectName,
+            moduleId: finalModuleId,
+            status: finalStatus,
+            createdAt: existing.createdAt,
+            updatedAt: now,
+            completedAt,
+        };
+    }
     /**
      * 获取主任务
      *
      * 由于 JSONL append-only 存储会保留历史版本，
-     * 需要按 created_at 降序取最新版本。
+     * 需要按 metadata.updatedAt 降序取最新版本。
      */
     getMainTask(taskId) {
         const tag = `mtask:${taskId}`;
@@ -319,8 +452,8 @@ class DevPlanStore {
             .filter((doc) => doc.tags.includes(`plan:${this.projectName}`));
         if (docs.length === 0)
             return null;
-        // 取最新版本（created_at 最大的）
-        const latest = docs.sort((a, b) => b.createdAt - a.createdAt)[0];
+        // 取最新版本（以 metadata.updatedAt 为判定依据）
+        const latest = docs.sort((a, b) => this.getDocUpdatedAt(b) - this.getDocUpdatedAt(a))[0];
         return this.docToMainTask(latest);
     }
     /**
@@ -341,6 +474,10 @@ class DevPlanStore {
             const priorityTag = `priority:${filter.priority}`;
             docs = docs.filter((doc) => doc.tags.includes(priorityTag));
         }
+        if (filter?.moduleId) {
+            const moduleTag = `module:${filter.moduleId}`;
+            docs = docs.filter((doc) => doc.tags.includes(moduleTag));
+        }
         return docs.map((doc) => this.docToMainTask(doc));
     }
     /**
@@ -363,20 +500,25 @@ class DevPlanStore {
             totalSubtasks: mainTask.totalSubtasks,
             completedSubtasks: mainTask.completedSubtasks,
         };
+        const tags = [
+            `plan:${this.projectName}`,
+            'type:main-task',
+            `mtask:${mainTask.taskId}`,
+            `priority:${mainTask.priority}`,
+            `status:${status}`,
+        ];
+        if (mainTask.moduleId) {
+            tags.push(`module:${mainTask.moduleId}`);
+        }
         const docInput = {
             content: JSON.stringify(taskData),
             contentType: native_2.ContentType.Text,
-            tags: [
-                `plan:${this.projectName}`,
-                'type:main-task',
-                `mtask:${mainTask.taskId}`,
-                `priority:${mainTask.priority}`,
-                `status:${status}`,
-            ],
+            tags,
             metadata: {
                 projectName: this.projectName,
                 taskId: mainTask.taskId,
                 status,
+                moduleId: mainTask.moduleId || null,
                 createdAt: mainTask.createdAt,
                 updatedAt: now,
                 completedAt,
@@ -455,10 +597,146 @@ class DevPlanStore {
             completedAt: null,
         };
     }
+    /**
+     * 幂等导入子任务（Upsert）
+     *
+     * - 如果子任务不存在 → 创建新子任务
+     * - 如果子任务已存在 → 更新标题/描述等字段，但保留已有的更高级状态
+     *   （例如已完成的任务不会被重置为 pending）
+     * - updatedAt 保证严格递增，不会与历史版本重复
+     *
+     * @param input 子任务输入
+     * @param options.preserveStatus 若为 true（默认），则不覆盖已完成的状态
+     * @param options.status 导入时的目标状态（默认 pending）
+     * @returns 创建或更新后的子任务
+     */
+    upsertSubTask(input, options) {
+        const preserveStatus = options?.preserveStatus !== false; // 默认 true
+        const targetStatus = options?.status || 'pending';
+        const existing = this.getSubTask(input.taskId);
+        if (!existing) {
+            // 新建（验证父任务存在）
+            const mainTask = this.getMainTask(input.parentTaskId);
+            if (!mainTask) {
+                throw new Error(`Parent main task "${input.parentTaskId}" not found for project "${this.projectName}"`);
+            }
+            const now = Date.now();
+            const taskData = {
+                taskId: input.taskId,
+                title: input.title,
+                estimatedHours: input.estimatedHours || 0,
+                relatedFiles: input.relatedFiles || [],
+                description: input.description || '',
+            };
+            const docInput = {
+                content: JSON.stringify(taskData),
+                contentType: native_2.ContentType.Text,
+                parentId: mainTask.id,
+                tags: [
+                    `plan:${this.projectName}`,
+                    'type:sub-task',
+                    `stask:${input.taskId}`,
+                    `parent:${input.parentTaskId}`,
+                    `status:${targetStatus}`,
+                ],
+                metadata: {
+                    projectName: this.projectName,
+                    taskId: input.taskId,
+                    parentTaskId: input.parentTaskId,
+                    status: targetStatus,
+                    createdAt: now,
+                    updatedAt: now,
+                    completedAt: targetStatus === 'completed' ? now : null,
+                },
+                importance: 0.7,
+            };
+            const id = this.taskStore.put(docInput);
+            this.refreshMainTaskCounts(input.parentTaskId);
+            this.taskStore.flush();
+            return {
+                id,
+                projectName: this.projectName,
+                ...taskData,
+                parentTaskId: input.parentTaskId,
+                status: targetStatus,
+                createdAt: now,
+                updatedAt: now,
+                completedAt: targetStatus === 'completed' ? now : null,
+            };
+        }
+        // 已存在 — 决定最终状态
+        let finalStatus = targetStatus;
+        if (preserveStatus) {
+            const statusPriority = {
+                cancelled: 0,
+                pending: 1,
+                in_progress: 2,
+                completed: 3,
+            };
+            if (statusPriority[existing.status] >= statusPriority[targetStatus]) {
+                finalStatus = existing.status;
+            }
+        }
+        // 检查是否有实质性变化（避免无意义的更新，减少历史版本膨胀）
+        if (existing.title === input.title &&
+            existing.description === (input.description || '') &&
+            existing.status === finalStatus &&
+            existing.estimatedHours === (input.estimatedHours || 0)) {
+            // 无变化，直接返回
+            return existing;
+        }
+        // 删除旧版本并确保时间戳递增
+        this.deleteAndEnsureTimestampAdvance(this.taskStore, existing.id);
+        const mainTask = this.getMainTask(input.parentTaskId);
+        const now = Date.now();
+        const completedAt = finalStatus === 'completed' ? (existing.completedAt || now) : null;
+        const taskData = {
+            taskId: input.taskId,
+            title: input.title,
+            estimatedHours: input.estimatedHours || existing.estimatedHours || 0,
+            relatedFiles: input.relatedFiles || existing.relatedFiles || [],
+            description: input.description || existing.description || '',
+        };
+        const docInput = {
+            content: JSON.stringify(taskData),
+            contentType: native_2.ContentType.Text,
+            parentId: mainTask?.id || undefined,
+            tags: [
+                `plan:${this.projectName}`,
+                'type:sub-task',
+                `stask:${input.taskId}`,
+                `parent:${input.parentTaskId}`,
+                `status:${finalStatus}`,
+            ],
+            metadata: {
+                projectName: this.projectName,
+                taskId: input.taskId,
+                parentTaskId: input.parentTaskId,
+                status: finalStatus,
+                createdAt: existing.createdAt,
+                updatedAt: now,
+                completedAt,
+                completedAtCommit: existing.completedAtCommit || null,
+                revertReason: existing.revertReason || null,
+            },
+            importance: 0.7,
+        };
+        const id = this.taskStore.put(docInput);
+        this.refreshMainTaskCounts(input.parentTaskId);
+        this.taskStore.flush();
+        return {
+            ...existing,
+            ...taskData,
+            id,
+            status: finalStatus,
+            updatedAt: now,
+            completedAt,
+        };
+    }
     /**
      * 获取子任务
      *
-     * 取同一 taskId 的最新版本。
+     * 取同一 taskId 的最新版本（以 metadata.updatedAt 判定）。
      */
     getSubTask(taskId) {
         const tag = `stask:${taskId}`;
@@ -466,8 +744,8 @@ class DevPlanStore {
             .filter((doc) => doc.tags.includes(`plan:${this.projectName}`));
         if (docs.length === 0)
             return null;
-        // 取最新版本
-        const latest = docs.sort((a, b) => b.createdAt - a.createdAt)[0];
+        // 取最新版本（以 metadata.updatedAt 为判定依据）
+        const latest = docs.sort((a, b) => this.getDocUpdatedAt(b) - this.getDocUpdatedAt(a))[0];
         return this.docToSubTask(latest);
     }
     /**
@@ -490,8 +768,11 @@ class DevPlanStore {
     }
     /**
      * 更新子任务状态
+     *
+     * @param options.completedAtCommit - 完成时的 Git commit hash（仅 status=completed 时有效）
+     * @param options.revertReason - 回退原因（仅 status 从 completed 变为 pending 时有效）
      */
-    updateSubTaskStatus(taskId, status) {
+    updateSubTaskStatus(taskId, status, options) {
         const subTask = this.getSubTask(taskId);
         if (!subTask)
             return null;
@@ -499,7 +780,11 @@ class DevPlanStore {
         const mainTask = this.getMainTask(subTask.parentTaskId);
         this.deleteAndEnsureTimestampAdvance(this.taskStore, subTask.id);
         const now = Date.now();
-        const completedAt = status === 'completed' ? now : subTask.completedAt;
+        const completedAt = status === 'completed' ? now : (status === 'pending' ? null : subTask.completedAt);
+        const completedAtCommit = status === 'completed'
+            ? (options?.completedAtCommit || subTask.completedAtCommit)
+            : (status === 'pending' ? undefined : subTask.completedAtCommit);
+        const revertReason = options?.revertReason || (status === 'pending' ? undefined : subTask.revertReason);
         const taskData = {
             taskId: subTask.taskId,
             title: subTask.title,
@@ -526,6 +811,8 @@ class DevPlanStore {
                 createdAt: subTask.createdAt,
                 updatedAt: now,
                 completedAt,
+                completedAtCommit: completedAtCommit || null,
+                revertReason: revertReason || null,
             },
             importance: 0.7,
         };
@@ -537,6 +824,8 @@ class DevPlanStore {
             status,
             updatedAt: now,
             completedAt,
+            completedAtCommit,
+            revertReason,
         };
     }
     // ==========================================================================
@@ -546,34 +835,40 @@ class DevPlanStore {
      * 完成子任务 — 核心自动化方法
      *
      * 自动处理：
-     * 1. 更新子任务状态为 completed，写入 completedAt 时间戳
-     * 2. 重新计算主任务的 completedSubtasks 计数
-     * 3. 如果全部子任务完成，自动标记主任务为 completed
-     * 4. 如果主任务完成，更新 milestones 文档
+     * 1. 获取当前 Git HEAD 的 short SHA 用于锚定
+     * 2. 更新子任务状态为 completed，写入 completedAt 时间戳和 completedAtCommit
+     * 3. 重新计算主任务的 completedSubtasks 计数
+     * 4. 如果全部子任务完成，自动标记主任务为 completed
+     * 5. 如果主任务完成，更新 milestones 文档
      */
     completeSubTask(taskId) {
-        // 1. 更新子任务
-        const updatedSubTask = this.updateSubTaskStatus(taskId, 'completed');
+        // 1. 获取当前 Git commit hash
+        const commitHash = this.getCurrentGitCommit();
+        // 2. 更新子任务（带 Git commit 锚定）
+        const updatedSubTask = this.updateSubTaskStatus(taskId, 'completed', {
+            completedAtCommit: commitHash,
+        });
         if (!updatedSubTask) {
             throw new Error(`Sub task "${taskId}" not found for project "${this.projectName}"`);
         }
-        // 2. 刷新主任务计数
+        // 3. 刷新主任务计数
         const updatedMainTask = this.refreshMainTaskCounts(updatedSubTask.parentTaskId);
         if (!updatedMainTask) {
             throw new Error(`Parent main task "${updatedSubTask.parentTaskId}" not found`);
         }
-        // 3. 检查主任务是否全部完成
+        // 4. 检查主任务是否全部完成
         const mainTaskCompleted = updatedMainTask.totalSubtasks > 0 &&
             updatedMainTask.completedSubtasks >= updatedMainTask.totalSubtasks;
         if (mainTaskCompleted && updatedMainTask.status !== 'completed') {
             const completedMain = this.updateMainTaskStatus(updatedSubTask.parentTaskId, 'completed');
             if (completedMain) {
-                // 4. 更新 milestones 文档（如果存在）
+                // 5. 更新 milestones 文档（如果存在）
                 this.autoUpdateMilestones(completedMain);
                 return {
                     subTask: updatedSubTask,
                     mainTask: completedMain,
                     mainTaskCompleted: true,
+                    completedAtCommit: commitHash,
                 };
             }
         }
@@ -581,6 +876,7 @@ class DevPlanStore {
             subTask: updatedSubTask,
             mainTask: updatedMainTask,
             mainTaskCompleted,
+            completedAtCommit: commitHash,
         };
     }
     /**
@@ -701,6 +997,196 @@ class DevPlanStore {
         return md;
     }
     // ==========================================================================
+    // Module Operations
+    // ==========================================================================
+    /**
+     * 创建功能模块
+     */
+    createModule(input) {
+        const existing = this.getModule(input.moduleId);
+        if (existing) {
+            throw new Error(`Module "${input.moduleId}" already exists for project "${this.projectName}"`);
+        }
+        const now = Date.now();
+        const status = input.status || 'active';
+        const moduleData = {
+            moduleId: input.moduleId,
+            name: input.name,
+            description: input.description || '',
+        };
+        const docInput = {
+            content: JSON.stringify(moduleData),
+            contentType: native_2.ContentType.Text,
+            tags: [
+                `plan:${this.projectName}`,
+                'type:module',
+                `module:${input.moduleId}`,
+                `status:${status}`,
+            ],
+            metadata: {
+                projectName: this.projectName,
+                moduleId: input.moduleId,
+                status,
+                createdAt: now,
+                updatedAt: now,
+            },
+            importance: 0.85,
+        };
+        const id = this.moduleStore.put(docInput);
+        this.moduleStore.flush();
+        return {
+            id,
+            projectName: this.projectName,
+            moduleId: input.moduleId,
+            name: input.name,
+            description: input.description,
+            status,
+            mainTaskCount: 0,
+            subTaskCount: 0,
+            completedSubTaskCount: 0,
+            docCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    /**
+     * 获取功能模块（含自动计算的 taskCount/docCount）
+     */
+    getModule(moduleId) {
+        const tag = `module:${moduleId}`;
+        const docs = this.moduleStore.findByTag(tag)
+            .filter((doc) => doc.tags.includes(`plan:${this.projectName}`));
+        if (docs.length === 0)
+            return null;
+        const latest = docs.sort((a, b) => this.getDocUpdatedAt(b) - this.getDocUpdatedAt(a))[0];
+        return this.docToModule(latest);
+    }
+    /**
+     * 列出所有功能模块
+     */
+    listModules(filter) {
+        let docs = this.moduleStore.findByTag(`plan:${this.projectName}`)
+            .filter((doc) => doc.tags.includes('type:module'));
+        // 按 moduleId 去重
+        const latestMap = new Map();
+        for (const doc of docs) {
+            const data = JSON.parse(doc.content);
+            const moduleId = data.moduleId;
+            if (!moduleId)
+                continue;
+            const existing = latestMap.get(moduleId);
+            if (!existing || this.getDocUpdatedAt(doc) > this.getDocUpdatedAt(existing)) {
+                latestMap.set(moduleId, doc);
+            }
+        }
+        docs = Array.from(latestMap.values());
+        if (filter?.status) {
+            const statusTag = `status:${filter.status}`;
+            docs = docs.filter((doc) => doc.tags.includes(statusTag));
+        }
+        return docs.map((doc) => this.docToModule(doc));
+    }
+    /**
+     * 更新功能模块
+     */
+    updateModule(moduleId, updates) {
+        const existing = this.getModule(moduleId);
+        if (!existing)
+            return null;
+        this.deleteAndEnsureTimestampAdvance(this.moduleStore, existing.id);
+        const now = Date.now();
+        const newName = updates.name || existing.name;
+        const newDescription = updates.description !== undefined ? updates.description : existing.description;
+        const newStatus = updates.status || existing.status;
+        const moduleData = {
+            moduleId,
+            name: newName,
+            description: newDescription || '',
+        };
+        const docInput = {
+            content: JSON.stringify(moduleData),
+            contentType: native_2.ContentType.Text,
+            tags: [
+                `plan:${this.projectName}`,
+                'type:module',
+                `module:${moduleId}`,
+                `status:${newStatus}`,
+            ],
+            metadata: {
+                projectName: this.projectName,
+                moduleId,
+                status: newStatus,
+                createdAt: existing.createdAt,
+                updatedAt: now,
+            },
+            importance: 0.85,
+        };
+        const id = this.moduleStore.put(docInput);
+        this.moduleStore.flush();
+        return {
+            id,
+            projectName: this.projectName,
+            moduleId,
+            name: newName,
+            description: newDescription,
+            status: newStatus,
+            mainTaskCount: existing.mainTaskCount,
+            subTaskCount: existing.subTaskCount,
+            completedSubTaskCount: existing.completedSubTaskCount,
+            docCount: existing.docCount,
+            createdAt: existing.createdAt,
+            updatedAt: now,
+        };
+    }
+    /**
+     * 删除功能模块
+     */
+    deleteModule(moduleId) {
+        const existing = this.getModule(moduleId);
+        if (!existing)
+            return false;
+        this.moduleStore.delete(existing.id);
+        this.moduleStore.flush();
+        return true;
+    }
+    /**
+     * 获取模块详情 — 包含关联的任务和文档
+     */
+    getModuleDetail(moduleId) {
+        const mod = this.getModule(moduleId);
+        if (!mod)
+            return null;
+        // 获取关联的主任务
+        const moduleTag = `module:${moduleId}`;
+        let taskDocs = this.taskStore.findByTag(moduleTag)
+            .filter((doc) => doc.tags.includes(`plan:${this.projectName}`) &&
+            doc.tags.includes('type:main-task'));
+        taskDocs = this.deduplicateByTaskId(taskDocs);
+        const mainTasks = taskDocs.map((doc) => this.docToMainTask(doc));
+        // 获取关联的所有子任务（通过主任务间接关联）
+        const subTasks = [];
+        for (const mt of mainTasks) {
+            const subs = this.listSubTasks(mt.taskId);
+            subTasks.push(...subs);
+        }
+        // 获取关联的文档
+        let docDocs = this.docStore.findByTag(moduleTag)
+            .filter((doc) => doc.tags.includes(`plan:${this.projectName}`));
+        // 按 section+subSection 去重
+        const latestDocMap = new Map();
+        for (const doc of docDocs) {
+            const sectionTag = doc.tags.find((t) => t.startsWith('section:'));
+            const subTag = doc.tags.find((t) => t.startsWith('sub:'));
+            const key = `${sectionTag || 'unknown'}|${subTag || ''}`;
+            const ex = latestDocMap.get(key);
+            if (!ex || this.getDocUpdatedAt(doc) > this.getDocUpdatedAt(ex)) {
+                latestDocMap.set(key, doc);
+            }
+        }
+        const documents = Array.from(latestDocMap.values()).map((doc) => this.docToDevPlanDoc(doc));
+        return { module: mod, mainTasks, subTasks, documents };
+    }
+    // ==========================================================================
     // Utility
     // ==========================================================================
     /**
@@ -709,6 +1195,7 @@ class DevPlanStore {
     sync() {
         this.docStore.flush();
         this.taskStore.flush();
+        this.moduleStore.flush();
     }
     /**
      * 获取项目名称
@@ -719,16 +1206,29 @@ class DevPlanStore {
     // ==========================================================================
     // Private Helpers
     // ==========================================================================
+    /**
+     * 获取文档的有效 updatedAt 时间戳。
+     *
+     * EnhancedDocumentStore 使用 append-only JSONL 存储，修改文档时实际上
+     * 是 delete 旧文档 + put 新文档。因此同一逻辑文档可能存在多个物理版本。
+     * 必须通过 metadata.updatedAt 来判断哪个是最新的"可用文档"，
+     * 其余的都是"历史文档"。
+     *
+     * 优先级：metadata.updatedAt > metadata.createdAt > doc.createdAt
+     */
+    getDocUpdatedAt(doc) {
+        return doc.metadata?.updatedAt || doc.metadata?.createdAt || doc.createdAt;
+    }
     /**
      * 确保当前时间戳严格大于参考时间戳。
      *
      * EnhancedDocumentStore 使用 append-only JSONL 存储，保留所有历史版本。
-     * deduplicateByTaskId 通过 MemoryNode.created_at 选择最新版本。
-     * 如果 delete+put 发生在同一毫秒内，新旧版本的 created_at 相同，
+     * 版本选择通过 metadata.updatedAt 判定最新文档。
+     * 如果 delete+put 发生在同一毫秒内，新旧版本的 updatedAt 相同，
      * 会导致去重时可能选中旧版本（如 pending 状态），造成状态丢失。
      *
      * 本方法在 delete 之后、put 之前调用，自旋等待直到时间戳前进，
-     * 从而保证新版本的 created_at 一定大于旧版本。
+     * 从而保证新版本的 updatedAt 一定大于旧版本。
      */
     ensureTimestampAfter(referenceTimestamp) {
         while (Date.now() <= referenceTimestamp) {
@@ -736,21 +1236,28 @@ class DevPlanStore {
         }
     }
     /**
-     * 删除文档并确保后续 put 的时间戳严格大于被删文档。
-     * 返回被删文档的 created_at，若文档不存在返回 0。
+     * 删除文档并确保后续 put 的 updatedAt 严格大于被删文档。
+     *
+     * 使用 metadata.updatedAt 作为参考时间戳（而非 doc.createdAt），
+     * 因为版本选择是基于 metadata.updatedAt 进行的。
      */
     deleteAndEnsureTimestampAdvance(store, id) {
         const deleted = store.delete(id);
         if (deleted) {
-            this.ensureTimestampAfter(deleted.createdAt);
+            // 以 metadata.updatedAt 为基准，确保新文档的 updatedAt 严格递增
+            const refTimestamp = this.getDocUpdatedAt(deleted);
+            this.ensureTimestampAfter(refTimestamp);
         }
     }
     /**
-     * 对同一 taskId 的多个历史版本做去重，仅保留最新版（created_at 最大）。
+     * 对同一 taskId 的多个历史版本做去重，仅保留最新版（metadata.updatedAt 最大）。
      *
      * 由于 EnhancedDocumentStore 使用 append-only JSONL 存储，
      * delete+put 操作会在文件中保留历史版本。重新加载时所有版本都会出现，
      * 因此需要在查询层面进行去重。
+     *
+     * 使用 metadata.updatedAt（而非 doc.createdAt）作为版本判定依据，
+     * 确保"最近更新时间"的文档才是可用文档，其余为历史文档。
      */
     deduplicateByTaskId(docs) {
         const latestMap = new Map();
@@ -760,7 +1267,7 @@ class DevPlanStore {
             if (!taskId)
                 continue;
             const existing = latestMap.get(taskId);
-            if (!existing || doc.createdAt > existing.createdAt) {
+            if (!existing || this.getDocUpdatedAt(doc) > this.getDocUpdatedAt(existing)) {
                 latestMap.set(taskId, doc);
             }
         }
@@ -771,6 +1278,8 @@ class DevPlanStore {
         const section = (sectionTag?.replace('section:', '') || 'custom');
         const subTag = doc.tags.find((t) => t.startsWith('sub:'));
         const subSection = subTag?.replace('sub:', '');
+        const moduleTag = doc.tags.find((t) => t.startsWith('module:'));
+        const moduleId = moduleTag?.replace('module:', '') || undefined;
         return {
             id: doc.id,
             projectName: this.projectName,
@@ -780,6 +1289,7 @@ class DevPlanStore {
             version: doc.metadata?.version || '1.0.0',
             subSection,
             relatedSections: doc.metadata?.relatedSections || [],
+            moduleId,
             createdAt: doc.metadata?.createdAt || doc.createdAt,
             updatedAt: doc.metadata?.updatedAt || doc.createdAt,
         };
@@ -788,6 +1298,8 @@ class DevPlanStore {
         const data = JSON.parse(doc.content);
         const statusTag = doc.tags.find((t) => t.startsWith('status:'));
         const status = (statusTag?.replace('status:', '') || 'pending');
+        const moduleTag = doc.tags.find((t) => t.startsWith('module:'));
+        const moduleId = moduleTag?.replace('module:', '') || undefined;
         return {
             id: doc.id,
             projectName: this.projectName,
@@ -797,6 +1309,7 @@ class DevPlanStore {
             description: data.description,
             estimatedHours: data.estimatedHours,
             relatedSections: data.relatedSections || [],
+            moduleId,
             totalSubtasks: data.totalSubtasks || 0,
             completedSubtasks: data.completedSubtasks || 0,
             status,
@@ -805,6 +1318,71 @@ class DevPlanStore {
             completedAt: doc.metadata?.completedAt || null,
         };
     }
+    docToModule(doc) {
+        const data = JSON.parse(doc.content);
+        const statusTag = doc.tags.find((t) => t.startsWith('status:'));
+        const status = (statusTag?.replace('status:', '') || 'active');
+        const moduleId = data.moduleId;
+        // 计算关联的主任务数（去重）
+        const moduleTag = `module:${moduleId}`;
+        const taskDocs = this.taskStore.findByTag(moduleTag)
+            .filter((d) => d.tags.includes(`plan:${this.projectName}`) &&
+            d.tags.includes('type:main-task'));
+        const uniqueTaskIds = new Set();
+        for (const td of taskDocs) {
+            try {
+                uniqueTaskIds.add(JSON.parse(td.content).taskId);
+            }
+            catch { }
+        }
+        // 计算关联的子任务数（遍历关联主任务下的所有子任务）
+        let subTaskCount = 0;
+        let completedSubTaskCount = 0;
+        for (const mainTaskId of uniqueTaskIds) {
+            const subDocs = this.taskStore.findByTag(`parent:${mainTaskId}`)
+                .filter((d) => d.tags.includes(`plan:${this.projectName}`) &&
+                d.tags.includes('type:sub-task'));
+            // 按 taskId 去重
+            const seenSubIds = new Set();
+            for (const sd of subDocs) {
+                try {
+                    const subData = JSON.parse(sd.content);
+                    if (seenSubIds.has(subData.taskId))
+                        continue;
+                    seenSubIds.add(subData.taskId);
+                    subTaskCount++;
+                    const subStatusTag = sd.tags.find((t) => t.startsWith('status:'));
+                    if (subStatusTag === 'status:completed') {
+                        completedSubTaskCount++;
+                    }
+                }
+                catch { }
+            }
+        }
+        // 计算关联的文档数（按 section+subSection 去重）
+        const docDocs = this.docStore.findByTag(moduleTag)
+            .filter((d) => d.tags.includes(`plan:${this.projectName}`));
+        const uniqueDocKeys = new Set();
+        for (const dd of docDocs) {
+            const st = dd.tags.find((t) => t.startsWith('section:'));
+            const sub = dd.tags.find((t) => t.startsWith('sub:'));
+            uniqueDocKeys.add(`${st || ''}|${sub || ''}`);
+        }
+        return {
+            id: doc.id,
+            projectName: this.projectName,
+            moduleId,
+            name: data.name,
+            description: data.description || undefined,
+            status,
+            mainTaskCount: uniqueTaskIds.size,
+            subTaskCount,
+            completedSubTaskCount,
+            docCount: uniqueDocKeys.size,
+            createdAt: doc.metadata?.createdAt || doc.createdAt,
+            updatedAt: doc.metadata?.updatedAt || doc.createdAt,
+        };
+    }
     docToSubTask(doc) {
         const data = JSON.parse(doc.content);
         const statusTag = doc.tags.find((t) => t.startsWith('status:'));
@@ -824,6 +1402,8 @@ class DevPlanStore {
             createdAt: doc.metadata?.createdAt || doc.createdAt,
             updatedAt: doc.metadata?.updatedAt || doc.createdAt,
             completedAt: doc.metadata?.completedAt || null,
+            completedAtCommit: doc.metadata?.completedAtCommit || undefined,
+            revertReason: doc.metadata?.revertReason || undefined,
         };
     }
     /**
@@ -851,20 +1431,25 @@ class DevPlanStore {
             totalSubtasks: subs.length,
             completedSubtasks: completedCount,
         };
+        const tags = [
+            `plan:${this.projectName}`,
+            'type:main-task',
+            `mtask:${mainTask.taskId}`,
+            `priority:${mainTask.priority}`,
+            `status:${mainTask.status}`,
+        ];
+        if (mainTask.moduleId) {
+            tags.push(`module:${mainTask.moduleId}`);
+        }
         const docInput = {
             content: JSON.stringify(taskData),
             contentType: native_2.ContentType.Text,
-            tags: [
-                `plan:${this.projectName}`,
-                'type:main-task',
-                `mtask:${mainTask.taskId}`,
-                `priority:${mainTask.priority}`,
-                `status:${mainTask.status}`,
-            ],
+            tags,
             metadata: {
                 projectName: this.projectName,
                 taskId: mainTask.taskId,
                 status: mainTask.status,
+                moduleId: mainTask.moduleId || null,
                 createdAt: mainTask.createdAt,
                 updatedAt: now,
                 completedAt: mainTask.completedAt,
@@ -901,6 +1486,118 @@ class DevPlanStore {
             relatedSections: milestonesDoc.relatedSections,
         });
     }
+    // ==========================================================================
+    // Git Integration (Git Commit 锚定 + 同步检查)
+    // ==========================================================================
+    /**
+     * 🆕 获取当前 Git HEAD 的 short SHA
+     *
+     * 在非 Git 仓库或 Git 不可用时返回 undefined，不阻断正常流程。
+     */
+    getCurrentGitCommit() {
+        try {
+            const { execSync } = require('child_process');
+            return execSync('git rev-parse --short HEAD', {
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'], // 静默 stderr
+            }).trim();
+        }
+        catch {
+            return undefined; // 非 Git 仓库或 Git 不可用
+        }
+    }
+    /**
+     * 🆕 检查 commit 是否是 target 的祖先
+     *
+     * 使用 `git merge-base --is-ancestor` 命令。
+     * 如果 commit 不存在或不可达，返回 false（视为需要回退）。
+     */
+    isAncestor(commit, target) {
+        try {
+            const { execSync } = require('child_process');
+            execSync(`git merge-base --is-ancestor ${commit} ${target}`, {
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return true; // exit code 0 = is ancestor
+        }
+        catch {
+            return false; // exit code 1 = not ancestor, or error
+        }
+    }
+    /**
+     * 🆕 回退子任务状态
+     *
+     * 将已完成的子任务回退为 pending，记录回退原因，
+     * 清空 completedAtCommit 和 completedAt。
+     * 同时刷新父主任务的计数。
+     */
+    revertSubTask(taskId, reason) {
+        const result = this.updateSubTaskStatus(taskId, 'pending', {
+            revertReason: reason,
+        });
+        if (result) {
+            // 刷新父主任务计数
+            this.refreshMainTaskCounts(result.parentTaskId);
+            // 如果父主任务被标记为 completed，也需要回退
+            const mainTask = this.getMainTask(result.parentTaskId);
+            if (mainTask && mainTask.status === 'completed') {
+                this.updateMainTaskStatus(result.parentTaskId, 'in_progress');
+            }
+        }
+        return result;
+    }
+    /**
+     * 🆕 同步检查所有已完成任务与 Git 历史的一致性
+     *
+     * 对每个 status=completed 且有 completedAtCommit 的子任务：
+     * 1. 检查 completedAtCommit 是否是当前 HEAD 的祖先
+     * 2. 如果不是（说明 Git 发生了回滚），回退任务状态为 pending
+     * 3. 记录 revertReason
+     *
+     * @param dryRun 如果为 true，只返回哪些任务会被回退，不实际修改数据
+     * @returns 同步结果，包含被回退的任务列表
+     */
+    syncWithGit(dryRun = false) {
+        const currentHead = this.getCurrentGitCommit();
+        if (!currentHead) {
+            return {
+                checked: 0,
+                reverted: [],
+                currentHead: 'unknown',
+                error: 'Git not available or not in a Git repository',
+            };
+        }
+        const mainTasks = this.listMainTasks();
+        const reverted = [];
+        let checked = 0;
+        for (const mt of mainTasks) {
+            const subs = this.listSubTasks(mt.taskId);
+            for (const sub of subs) {
+                if (sub.status !== 'completed' || !sub.completedAtCommit)
+                    continue;
+                checked++;
+                if (!this.isAncestor(sub.completedAtCommit, currentHead)) {
+                    const reason = `Commit ${sub.completedAtCommit} is not ancestor of HEAD ${currentHead}`;
+                    if (!dryRun) {
+                        this.revertSubTask(sub.taskId, reason);
+                    }
+                    reverted.push({
+                        taskId: sub.taskId,
+                        title: sub.title,
+                        parentTaskId: sub.parentTaskId,
+                        completedAtCommit: sub.completedAtCommit,
+                        reason: `Commit ${sub.completedAtCommit} not found in current branch (HEAD: ${currentHead})`,
+                    });
+                }
+            }
+        }
+        return { checked, reverted, currentHead };
+    }
+    // ==========================================================================
+    // Utilities
+    // ==========================================================================
     /**
      * 生成文本进度条
      */
@@ -919,13 +1616,22 @@ exports.DevPlanStore = DevPlanStore;
  * 为项目创建 DevPlanStore
  *
  * @param projectName - 项目名称
- * @param basePath - 存储基础路径（默认 ~/.aifastdb/dev-plans/）
+ * @param basePath - 存储基础路径（默认优先使用项目内 .devplan/，回退到 ~/.aifastdb/dev-plans/）
+ *
+ * 存储路径解析优先级：
+ * 1. 显式 basePath 参数
+ * 2. AIFASTDB_DEVPLAN_PATH 环境变量
+ * 3. 项目根目录/.devplan/（通过 .git 或 package.json 定位）
+ * 4. ~/.aifastdb/dev-plans/（兜底）
+ *
+ * 最终路径：{basePath}/{projectName}/documents.jsonl + tasks.jsonl
  */
 function createDevPlan(projectName, basePath) {
     const base = basePath || getDefaultBasePath();
     return new DevPlanStore(projectName, {
         documentPath: path.join(base, projectName, 'documents.jsonl'),
         taskPath: path.join(base, projectName, 'tasks.jsonl'),
+        modulePath: path.join(base, projectName, 'modules.jsonl'),
     });
 }
 /**