aifastdb-devplan 1.2.6 → 1.3.8

package/dist/dev-plan-graph-store.js

@@ -15,9 +15,43 @@
  * - Entity 类型: devplan-project, devplan-doc, devplan-main-task, devplan-sub-task, devplan-module
  * - Relation 类型: has_document, has_main_task, has_sub_task, module_has_task, module_has_doc
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DevPlanGraphStore = void 0;
 const aifastdb_1 = require("aifastdb");
+const path = __importStar(require("path"));
 // ============================================================================
 // Constants
 // ============================================================================
@@ -37,6 +71,7 @@ const RT = {
     MODULE_HAS_TASK: 'module_has_task',
     MODULE_HAS_DOC: 'module_has_doc',
     TASK_HAS_DOC: 'task_has_doc',
+    DOC_HAS_CHILD: 'doc_has_child',
 };
 // ============================================================================
 // Helper
@@ -67,19 +102,85 @@ class DevPlanGraphStore {
     constructor(projectName, config) {
         /** 缓存的项目根实体 ID */
         this.projectEntityId = null;
+        /** VibeSynapse 实例（用于 Embedding 生成），仅启用语义搜索时可用 */
+        this.synapse = null;
+        /** 语义搜索是否成功初始化 */
+        this.semanticSearchReady = false;
         this.projectName = projectName;
-        this.graph = new aifastdb_1.SocialGraphV2({
+        // 构建 SocialGraphV2 配置
+        const graphConfig = {
             path: config.graphPath,
             shardCount: config.shardCount || 4,
             walEnabled: true,
             mode: 'balanced',
             shardNames: ['entities', 'relations', 'index', 'meta'],
-        });
-        // 恢复 WAL 数据
+        };
+        // 如果启用语义搜索，配置 SocialGraphV2 的向量搜索
+        const dimension = config.embeddingDimension || 384;
+        if (config.enableSemanticSearch) {
+            graphConfig.vectorSearch = {
+                dimension,
+                m: 16,
+                efConstruction: 200,
+                efSearch: 50,
+                maxElements: 100000,
+                shardCount: 1,
+            };
+        }
+        this.graph = new aifastdb_1.SocialGraphV2(graphConfig);
+        // 恢复 WAL 数据（包括向量 WAL）
         this.graph.recover();
+        // 初始化 VibeSynapse（用于 Embedding 生成）
+        if (config.enableSemanticSearch) {
+            this.initSynapse(config.graphPath, dimension);
+        }
         // 确保项目根实体存在
         this.ensureProjectEntity();
     }
+    /**
+     * 初始化 VibeSynapse Embedding 引擎
+     *
+     * 使用 Candle MiniLM (384维) 作为默认模型，支持零配置离线使用。
+     * 初始化失败时降级为纯字面搜索（graceful degradation）。
+     */
+    initSynapse(graphPath, dimension) {
+        try {
+            const synapsePath = path.resolve(graphPath, '..', 'synapse-data');
+            this.synapse = new aifastdb_1.VibeSynapse({
+                storage: synapsePath,
+                dimension,
+                perception: {
+                    engineType: 'candle',
+                    modelId: 'sentence-transformers/all-MiniLM-L6-v2',
+                    autoDownload: true,
+                },
+            });
+            // 验证 perception engine 是否真正可用
+            if (!this.synapse.hasPerception) {
+                console.warn('[DevPlan] VibeSynapse created but perception engine not available. ' +
+                    'Candle MiniLM may not be installed. Falling back to literal search.');
+                this.synapse = null;
+                this.semanticSearchReady = false;
+                return;
+            }
+            // 测试 embed 是否可用（dry run）
+            try {
+                this.synapse.embed('test');
+                this.semanticSearchReady = true;
+                console.log('[DevPlan] Semantic search initialized (Candle MiniLM)');
+            }
+            catch {
+                console.warn('[DevPlan] VibeSynapse embed() dry-run failed. Falling back to literal search.');
+                this.synapse = null;
+                this.semanticSearchReady = false;
+            }
+        }
+        catch (e) {
+            console.warn(`[DevPlan] Failed to initialize VibeSynapse for semantic search: ${e instanceof Error ? e.message : String(e)}. Falling back to literal search.`);
+            this.synapse = null;
+            this.semanticSearchReady = false;
+        }
+    }
     // ==========================================================================
     // Project Entity
     // ==========================================================================
@@ -147,6 +248,19 @@ class DevPlanGraphStore {
     // ==========================================================================
     entityToDevPlanDoc(e) {
         const p = e.properties;
+        // 获取 parentDoc：从属性读取
+        const parentDoc = p.parentDoc || undefined;
+        // 获取 childDocs：通过 DOC_HAS_CHILD 出向关系查询
+        const childDocRels = this.getOutRelations(e.id, RT.DOC_HAS_CHILD);
+        const childDocs = childDocRels.length > 0
+            ? childDocRels.map((rel) => {
+                const childEntity = this.graph.getEntity(rel.target);
+                if (!childEntity)
+                    return undefined;
+                const cp = childEntity.properties;
+                return sectionKey(cp.section, cp.subSection || undefined);
+            }).filter((k) => k !== undefined)
+            : undefined;
         return {
             id: e.id,
             projectName: this.projectName,
@@ -158,6 +272,8 @@ class DevPlanGraphStore {
             relatedSections: p.relatedSections || [],
             moduleId: p.moduleId || undefined,
             relatedTaskIds: p.relatedTaskIds || [],
+            parentDoc,
+            childDocs,
             createdAt: p.createdAt || e.created_at,
             updatedAt: p.updatedAt || e.updated_at,
         };
@@ -177,6 +293,7 @@ class DevPlanGraphStore {
             totalSubtasks: p.totalSubtasks || 0,
             completedSubtasks: p.completedSubtasks || 0,
             status: p.status || 'pending',
+            order: p.order != null ? p.order : undefined,
             createdAt: p.createdAt || e.created_at,
             updatedAt: p.updatedAt || e.updated_at,
             completedAt: p.completedAt || null,
@@ -194,6 +311,7 @@ class DevPlanGraphStore {
             relatedFiles: p.relatedFiles || [],
             description: p.description || undefined,
             status: p.status || 'pending',
+            order: p.order != null ? p.order : undefined,
             createdAt: p.createdAt || e.created_at,
             updatedAt: p.updatedAt || e.updated_at,
             completedAt: p.completedAt || null,
@@ -238,6 +356,8 @@ class DevPlanGraphStore {
         const now = Date.now();
         const version = input.version || '1.0.0';
         const finalModuleId = input.moduleId || existing?.moduleId;
+        // 确定最终的 parentDoc 值（显式传入 > 已有值）
+        const finalParentDoc = input.parentDoc !== undefined ? input.parentDoc : existing?.parentDoc;
         if (existing) {
             // 更新已有文档
             const finalRelatedTaskIds = input.relatedTaskIds || existing.relatedTaskIds || [];
@@ -250,6 +370,7 @@ class DevPlanGraphStore {
                     relatedSections: input.relatedSections || [],
                     relatedTaskIds: finalRelatedTaskIds,
                     moduleId: finalModuleId || null,
+                    parentDoc: finalParentDoc || null,
                     updatedAt: now,
                 },
             });
@@ -257,6 +378,8 @@ class DevPlanGraphStore {
             if (finalModuleId && finalModuleId !== existing.moduleId) {
                 this.updateModuleDocRelation(existing.id, existing.moduleId, finalModuleId);
             }
+            // 更新 parentDoc 关系（DOC_HAS_CHILD）
+            this.updateParentDocRelation(existing.id, existing.parentDoc, finalParentDoc);
             // 更新 task -> doc 关系
             if (finalRelatedTaskIds.length) {
                 // 删除旧的 TASK_HAS_DOC 入向关系（指向本文档的）
@@ -272,6 +395,8 @@ class DevPlanGraphStore {
                     }
                 }
             }
+            // 语义搜索：自动为更新的文档生成 Embedding 并索引
+            this.autoIndexDocument(existing.id, input.title, input.content);
             this.graph.flush();
             return existing.id;
         }
@@ -286,11 +411,23 @@ class DevPlanGraphStore {
             relatedSections: input.relatedSections || [],
             relatedTaskIds: input.relatedTaskIds || [],
             moduleId: finalModuleId || null,
+            parentDoc: finalParentDoc || null,
             createdAt: now,
             updatedAt: now,
         });
-        // 创建 project -> doc 关系
-        this.graph.putRelation(this.getProjectId(), entity.id, RT.HAS_DOCUMENT);
+        // 子文档不直接连接项目节点，仅通过 doc_has_child 连接父文档
+        if (finalParentDoc) {
+            // 有 parentDoc → 创建 DOC_HAS_CHILD 关系（parent -> child），不创建 project -> doc
+            const [parentSection, parentSubSection] = finalParentDoc.split('|');
+            const parentEntity = this.findDocEntityBySection(parentSection, parentSubSection || undefined);
+            if (parentEntity) {
+                this.graph.putRelation(parentEntity.id, entity.id, RT.DOC_HAS_CHILD);
+            }
+        }
+        else {
+            // 无 parentDoc → 创建 project -> doc 关系（顶级文档）
+            this.graph.putRelation(this.getProjectId(), entity.id, RT.HAS_DOCUMENT);
+        }
         // 如果有模块关联，创建 module -> doc 关系
         if (finalModuleId) {
             const modEntity = this.findEntityByProp(ET.MODULE, 'moduleId', finalModuleId);
@@ -307,6 +444,8 @@ class DevPlanGraphStore {
                 }
             }
         }
+        // 语义搜索：自动为新文档生成 Embedding 并索引
+        this.autoIndexDocument(entity.id, input.title, input.content);
         this.graph.flush();
         return entity.id;
     }
@@ -341,16 +480,135 @@ class DevPlanGraphStore {
         });
     }
     searchSections(query, limit = 10) {
-        const queryLower = query.toLowerCase();
-        return this.listSections()
-            .filter((doc) => doc.content.toLowerCase().includes(queryLower) ||
-            doc.title.toLowerCase().includes(queryLower))
-            .slice(0, limit);
+        // 默认使用 hybrid 模式（语义+字面），无语义搜索时回退字面
+        const mode = this.semanticSearchReady ? 'hybrid' : 'literal';
+        return this.searchSectionsAdvanced(query, { mode, limit }).map(({ score, ...doc }) => doc);
+    }
+    /**
+     * 高级搜索：支持 literal / semantic / hybrid 三种模式
+     *
+     * - literal: 纯字面匹配（标题+内容包含查询词）
+     * - semantic: 纯语义搜索（embed(query) → searchEntitiesByVector）
+     * - hybrid: 字面+语义 RRF 融合排序
+     *
+     * 当 VibeSynapse 不可用时，semantic/hybrid 模式自动降级为 literal。
+     */
+    searchSectionsAdvanced(query, options) {
+        const mode = options?.mode || 'hybrid';
+        const limit = options?.limit || 10;
+        const minScore = options?.minScore || 0;
+        // ---- Literal Search ----
+        const literalResults = this.literalSearch(query);
+        // ---- If no semantic search or literal-only mode ----
+        if (mode === 'literal' || !this.semanticSearchReady || !this.synapse) {
+            return literalResults.slice(0, limit).map((doc) => ({ ...doc, score: undefined }));
+        }
+        // ---- Semantic Search ----
+        let semanticHits = [];
+        try {
+            const embedding = this.synapse.embed(query);
+            semanticHits = this.graph.searchEntitiesByVector(embedding, limit * 2, ET.DOC);
+        }
+        catch (e) {
+            console.warn(`[DevPlan] Semantic search failed: ${e instanceof Error ? e.message : String(e)}`);
+            // 降级为字面搜索
+            return literalResults.slice(0, limit).map((doc) => ({ ...doc, score: undefined }));
+        }
+        if (mode === 'semantic') {
+            // 纯语义模式：直接返回语义搜索结果
+            const docs = [];
+            for (const hit of semanticHits) {
+                if (minScore > 0 && hit.score < minScore)
+                    continue;
+                const entity = this.graph.getEntity(hit.entityId);
+                if (entity && entity.properties?.projectName === this.projectName) {
+                    docs.push({ ...this.entityToDevPlanDoc(entity), score: hit.score });
+                }
+                if (docs.length >= limit)
+                    break;
+            }
+            return docs;
+        }
+        // ---- Hybrid Mode: RRF Fusion ----
+        return this.rrfFusion(semanticHits, literalResults, limit, minScore);
+    }
+    /**
+     * 重建所有文档的向量索引
+     *
+     * 适用于：首次启用语义搜索、模型切换、索引损坏修复。
+     */
+    rebuildIndex() {
+        const startTime = Date.now();
+        const docs = this.listSections();
+        let indexed = 0;
+        let failed = 0;
+        const failedDocIds = [];
+        if (!this.semanticSearchReady || !this.synapse) {
+            return {
+                total: docs.length,
+                indexed: 0,
+                failed: docs.length,
+                durationMs: Date.now() - startTime,
+                failedDocIds: docs.map((d) => d.id),
+            };
+        }
+        for (const doc of docs) {
+            try {
+                const text = `${doc.title}\n${doc.content}`;
+                const embedding = this.synapse.embed(text);
+                this.graph.indexEntity(doc.id, embedding);
+                indexed++;
+            }
+            catch (e) {
+                failed++;
+                failedDocIds.push(doc.id);
+            }
+        }
+        this.graph.flush();
+        return {
+            total: docs.length,
+            indexed,
+            failed,
+            durationMs: Date.now() - startTime,
+            failedDocIds: failedDocIds.length > 0 ? failedDocIds : undefined,
+        };
+    }
+    /**
+     * 检查语义搜索是否可用
+     */
+    isSemanticSearchEnabled() {
+        return this.semanticSearchReady;
     }
     deleteSection(section, subSection) {
         const existing = this.getSection(section, subSection);
         if (!existing)
             return false;
+        // 断开 DOC_HAS_CHILD 入向关系（从父文档指向本文档的）
+        const parentRels = this.getInRelations(existing.id, RT.DOC_HAS_CHILD);
+        for (const rel of parentRels) {
+            this.graph.deleteRelation(rel.id);
+        }
+        // 断开 DOC_HAS_CHILD 出向关系（本文档指向子文档的），子文档的 parentDoc 属性清空
+        const childRels = this.getOutRelations(existing.id, RT.DOC_HAS_CHILD);
+        for (const rel of childRels) {
+            this.graph.deleteRelation(rel.id);
+            // 清除子文档的 parentDoc 属性
+            const childEntity = this.graph.getEntity(rel.target);
+            if (childEntity) {
+                this.graph.updateEntity(childEntity.id, {
+                    properties: { parentDoc: null },
+                });
+            }
+        }
+        // 语义搜索：删除文档对应的向量索引
+        if (this.semanticSearchReady) {
+            try {
+                this.graph.removeEntityVector(existing.id);
+            }
+            catch {
+                // 向量可能不存在，忽略错误
+            }
+        }
         this.graph.deleteEntity(existing.id);
         this.graph.flush();
         return true;
@@ -364,6 +622,8 @@ class DevPlanGraphStore {
             throw new Error(`Main task "${input.taskId}" already exists for project "${this.projectName}"`);
         }
         const now = Date.now();
+        // 如果未指定 order，自动分配为当前最大 order + 1
+        const order = input.order != null ? input.order : this.getNextMainTaskOrder();
         const entity = this.graph.addEntity(input.title, ET.MAIN_TASK, {
             projectName: this.projectName,
             taskId: input.taskId,
@@ -376,6 +636,7 @@ class DevPlanGraphStore {
             totalSubtasks: 0,
             completedSubtasks: 0,
             status: 'pending',
+            order,
             createdAt: now,
             updatedAt: now,
             completedAt: null,
@@ -426,6 +687,7 @@ class DevPlanGraphStore {
         const now = Date.now();
         const completedAt = finalStatus === 'completed' ? (existing.completedAt || now) : null;
         const finalModuleId = input.moduleId || existing.moduleId;
+        const finalOrder = input.order != null ? input.order : existing.order;
         this.graph.updateEntity(existing.id, {
             name: input.title,
             properties: {
@@ -436,6 +698,7 @@ class DevPlanGraphStore {
                 relatedSections: input.relatedSections || existing.relatedSections || [],
                 moduleId: finalModuleId || null,
                 status: finalStatus,
+                order: finalOrder,
                 updatedAt: now,
                 completedAt,
             },
@@ -480,7 +743,8 @@ class DevPlanGraphStore {
         if (filter?.moduleId) {
             entities = entities.filter((e) => e.properties.moduleId === filter.moduleId);
         }
-        return entities.map((e) => this.entityToMainTask(e));
+        const tasks = entities.map((e) => this.entityToMainTask(e));
+        return this.sortByOrder(tasks);
     }
     updateMainTaskStatus(taskId, status) {
         const mainTask = this.getMainTask(taskId);
@@ -512,6 +776,8 @@ class DevPlanGraphStore {
             throw new Error(`Parent main task "${input.parentTaskId}" not found for project "${this.projectName}"`);
         }
         const now = Date.now();
+        // 如果未指定 order，自动分配为当前父任务下最大 order + 1
+        const order = input.order != null ? input.order : this.getNextSubTaskOrder(input.parentTaskId);
         const entity = this.graph.addEntity(input.title, ET.SUB_TASK, {
             projectName: this.projectName,
             taskId: input.taskId,
@@ -521,6 +787,7 @@ class DevPlanGraphStore {
             relatedFiles: input.relatedFiles || [],
             description: input.description || '',
             status: 'pending',
+            order,
             createdAt: now,
             updatedAt: now,
             completedAt: null,
@@ -542,6 +809,7 @@ class DevPlanGraphStore {
                 throw new Error(`Parent main task "${input.parentTaskId}" not found for project "${this.projectName}"`);
             }
             const now = Date.now();
+            const order = input.order != null ? input.order : this.getNextSubTaskOrder(input.parentTaskId);
             const entity = this.graph.addEntity(input.title, ET.SUB_TASK, {
                 projectName: this.projectName,
                 taskId: input.taskId,
@@ -551,6 +819,7 @@ class DevPlanGraphStore {
                 relatedFiles: input.relatedFiles || [],
                 description: input.description || '',
                 status: targetStatus,
+                order,
                 createdAt: now,
                 updatedAt: now,
                 completedAt: targetStatus === 'completed' ? now : null,
@@ -571,10 +840,12 @@ class DevPlanGraphStore {
             }
         }
         // 检查是否有实质变化
+        const newOrder = input.order != null ? input.order : existing.order;
         if (existing.title === input.title &&
             existing.description === (input.description || '') &&
             existing.status === finalStatus &&
-            existing.estimatedHours === (input.estimatedHours || 0)) {
+            existing.estimatedHours === (input.estimatedHours || 0) &&
+            existing.order === newOrder) {
             return existing;
         }
         const now = Date.now();
@@ -587,6 +858,7 @@ class DevPlanGraphStore {
                 relatedFiles: input.relatedFiles || existing.relatedFiles || [],
                 description: input.description || existing.description || '',
                 status: finalStatus,
+                order: newOrder,
                 updatedAt: now,
                 completedAt,
             },
@@ -605,7 +877,8 @@ class DevPlanGraphStore {
         if (filter?.status) {
             entities = entities.filter((e) => e.properties.status === filter.status);
         }
-        return entities.map((e) => this.entityToSubTask(e));
+        const tasks = entities.map((e) => this.entityToSubTask(e));
+        return this.sortByOrder(tasks);
     }
     updateSubTaskStatus(taskId, status, options) {
         const subTask = this.getSubTask(taskId);
@@ -693,6 +966,7 @@ class DevPlanGraphStore {
                 title: mt.title,
                 priority: mt.priority,
                 status: mt.status,
+                order: mt.order,
                 total: subs.length,
                 completed: subCompleted,
                 percent: subs.length > 0 ? Math.round((subCompleted / subs.length) * 100) : 0,
@@ -908,6 +1182,45 @@ class DevPlanGraphStore {
         return tasks;
     }
     // ==========================================================================
+    // Document Hierarchy (文档层级关系)
+    // ==========================================================================
+    /**
+     * 获取文档的直接子文档列表（通过 DOC_HAS_CHILD 出向关系）
+     */
+    getChildDocs(section, subSection) {
+        const docEntity = this.findDocEntityBySection(section, subSection);
+        if (!docEntity)
+            return [];
+        const rels = this.getOutRelations(docEntity.id, RT.DOC_HAS_CHILD);
+        const children = [];
+        for (const rel of rels) {
+            const childEntity = this.graph.getEntity(rel.target);
+            if (childEntity) {
+                children.push(this.entityToDevPlanDoc(childEntity));
+            }
+        }
+        return children;
+    }
+    /**
+     * 获取文档树（递归，含所有后代文档）
+     */
+    getDocTree(section, subSection) {
+        const doc = this.getSection(section, subSection);
+        if (!doc)
+            return null;
+        return this.buildDocTree(doc);
+    }
+    /**
+     * 递归构建文档树
+     */
+    buildDocTree(doc) {
+        const children = this.getChildDocs(doc.section, doc.subSection);
+        return {
+            doc,
+            children: children.map((child) => this.buildDocTree(child)),
+        };
+    }
+    // ==========================================================================
     // Utility
     // ==========================================================================
     sync() {
@@ -1042,13 +1355,32 @@ class DevPlanGraphStore {
                         section: doc.section,
                         subSection: doc.subSection,
                         version: doc.version,
+                        parentDoc: doc.parentDoc || null,
+                        childDocs: doc.childDocs || [],
                     },
                 });
-                edges.push({
-                    from: this.getProjectId(),
-                    to: doc.id,
-                    label: RT.HAS_DOCUMENT,
-                });
+                // 子文档不连接项目节点，仅通过 doc_has_child 连接父文档
+                if (!doc.parentDoc) {
+                    edges.push({
+                        from: this.getProjectId(),
+                        to: doc.id,
+                        label: RT.HAS_DOCUMENT,
+                    });
+                }
+                // doc_has_child 关系（文档 → 子文档）
+                if (doc.childDocs?.length) {
+                    const docEntity = this.findDocEntityBySection(doc.section, doc.subSection);
+                    if (docEntity) {
+                        const childRels = this.getOutRelations(docEntity.id, RT.DOC_HAS_CHILD);
+                        for (const rel of childRels) {
+                            edges.push({
+                                from: doc.id,
+                                to: rel.target,
+                                label: RT.DOC_HAS_CHILD,
+                            });
+                        }
+                    }
+                }
             }
         }
         // 模块节点
@@ -1124,6 +1456,46 @@ class DevPlanGraphStore {
     // ==========================================================================
     // Private Helpers
     // ==========================================================================
+    /**
+     * 获取下一个主任务的 order 值（当前最大 order + 1）
+     */
+    getNextMainTaskOrder() {
+        const entities = this.findEntitiesByType(ET.MAIN_TASK);
+        let maxOrder = 0;
+        for (const e of entities) {
+            const o = e.properties.order;
+            if (typeof o === 'number' && o > maxOrder) {
+                maxOrder = o;
+            }
+        }
+        return maxOrder + 1;
+    }
+    /**
+     * 获取下一个子任务的 order 值（当前父任务下最大 order + 1）
+     */
+    getNextSubTaskOrder(parentTaskId) {
+        const entities = this.findEntitiesByType(ET.SUB_TASK).filter((e) => e.properties.parentTaskId === parentTaskId);
+        let maxOrder = 0;
+        for (const e of entities) {
+            const o = e.properties.order;
+            if (typeof o === 'number' && o > maxOrder) {
+                maxOrder = o;
+            }
+        }
+        return maxOrder + 1;
+    }
+    /**
+     * 按 order 字段排序（order 为空的排到最后，order 相同则按 createdAt 排）
+     */
+    sortByOrder(items) {
+        return items.sort((a, b) => {
+            const oa = a.order != null ? a.order : Number.MAX_SAFE_INTEGER;
+            const ob = b.order != null ? b.order : Number.MAX_SAFE_INTEGER;
+            if (oa !== ob)
+                return oa - ob;
+            return a.createdAt - b.createdAt;
+        });
+    }
     refreshMainTaskCounts(mainTaskId) {
         const mainTask = this.getMainTask(mainTaskId);
         if (!mainTask)
@@ -1194,6 +1566,45 @@ class DevPlanGraphStore {
             }
         }
     }
+    /**
+     * 更新文档的父文档关系（DOC_HAS_CHILD）
+     *
+     * 移除旧的父文档关系，建立新的父文档关系。
+     */
+    updateParentDocRelation(docEntityId, oldParentDoc, newParentDoc) {
+        const projectId = this.getProjectId();
+        // 移除旧的父文档关系（入向 DOC_HAS_CHILD）
+        if (oldParentDoc) {
+            const [oldSection, oldSub] = oldParentDoc.split('|');
+            const oldParentEntity = this.findDocEntityBySection(oldSection, oldSub || undefined);
+            if (oldParentEntity) {
+                const rel = this.graph.getRelationBetween(oldParentEntity.id, docEntityId);
+                if (rel)
+                    this.graph.deleteRelation(rel.id);
+            }
+        }
+        // 建立新的父文档关系
+        if (newParentDoc) {
+            const [newSection, newSub] = newParentDoc.split('|');
+            const newParentEntity = this.findDocEntityBySection(newSection, newSub || undefined);
+            if (newParentEntity) {
+                this.graph.putRelation(newParentEntity.id, docEntityId, RT.DOC_HAS_CHILD);
+            }
+            // 从顶级变为子文档 → 移除 project -> doc 的 has_document 关系
+            if (!oldParentDoc) {
+                const hasDocRels = this.getInRelations(docEntityId, RT.HAS_DOCUMENT);
+                for (const rel of hasDocRels) {
+                    if (rel.source === projectId) {
+                        this.graph.deleteRelation(rel.id);
+                    }
+                }
+            }
+        }
+        else if (oldParentDoc && !newParentDoc) {
+            // 从子文档变为顶级 → 添加 project -> doc 关系
+            this.graph.putRelation(projectId, docEntityId, RT.HAS_DOCUMENT);
+        }
+    }
     getCurrentGitCommit() {
         try {
             const { execSync } = require('child_process');
@@ -1226,6 +1637,83 @@ class DevPlanGraphStore {
         const empty = total - filled;
         return `[${'█'.repeat(filled)}${'░'.repeat(empty)}]`;
     }
+    // ==========================================================================
+    // Semantic Search Helpers
+    // ==========================================================================
+    /**
+     * 自动为文档生成 Embedding 并索引到 SocialGraphV2 向量搜索层
+     *
+     * 将 title + content 拼接后生成 Embedding，以 entity.id 为 key 存入 HNSW 索引。
+     * 失败时仅输出警告，不影响文档保存。
+     */
+    autoIndexDocument(entityId, title, content) {
+        if (!this.semanticSearchReady || !this.synapse)
+            return;
+        try {
+            const text = `${title}\n${content}`;
+            const embedding = this.synapse.embed(text);
+            this.graph.indexEntity(entityId, embedding);
+        }
+        catch (e) {
+            console.warn(`[DevPlan] Failed to index document ${entityId}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * 字面搜索（标题/内容包含查询词）
+     */
+    literalSearch(query) {
+        const queryLower = query.toLowerCase();
+        return this.listSections().filter((doc) => doc.content.toLowerCase().includes(queryLower) ||
+            doc.title.toLowerCase().includes(queryLower));
+    }
+    /**
+     * RRF (Reciprocal Rank Fusion) 融合排序
+     *
+     * 将语义搜索和字面搜索的结果通过 RRF 公式融合：
+     *   score(d) = Σ 1/(k + rank_i(d))
+     * 其中 k=60 是标准 RRF 常数。
+     */
+    rrfFusion(semanticHits, literalResults, limit, minScore) {
+        const RRF_K = 60;
+        const rrfScores = new Map();
+        const docMap = new Map();
+        // 语义搜索结果贡献
+        for (let i = 0; i < semanticHits.length; i++) {
+            const hit = semanticHits[i];
+            const rrf = 1 / (RRF_K + i + 1);
+            rrfScores.set(hit.entityId, (rrfScores.get(hit.entityId) || 0) + rrf);
+        }
+        // 字面搜索结果贡献
+        for (let i = 0; i < literalResults.length; i++) {
+            const doc = literalResults[i];
+            const rrf = 1 / (RRF_K + i + 1);
+            rrfScores.set(doc.id, (rrfScores.get(doc.id) || 0) + rrf);
+            docMap.set(doc.id, doc);
+        }
+        // 按 RRF 评分排序
+        const sorted = Array.from(rrfScores.entries())
+            .sort((a, b) => b[1] - a[1]);
+        // 组装结果
+        const results = [];
+        for (const [id, score] of sorted) {
+            if (minScore > 0 && score < minScore)
+                continue;
+            if (results.length >= limit)
+                break;
+            // 优先从 docMap 获取（字面搜索已解析过的），否则从图中获取
+            let doc = docMap.get(id);
+            if (!doc) {
+                const entity = this.graph.getEntity(id);
+                if (entity && entity.properties?.projectName === this.projectName) {
+                    doc = this.entityToDevPlanDoc(entity);
+                }
+            }
+            if (doc) {
+                results.push({ ...doc, score });
+            }
+        }
+        return results;
+    }
 }
 exports.DevPlanGraphStore = DevPlanGraphStore;
 //# sourceMappingURL=dev-plan-graph-store.js.map