@ppdocs/mcp 2.6.30 → 2.7.1

package/dist/storage/httpClient.d.ts

@@ -54,6 +54,20 @@ export declare class PpdocsApiClient {
     completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
     getRulesApi(ruleType: string): Promise<string[]>;
     saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
+    vectorSearch(query: string, limit: number, mode: string): Promise<Array<{
+        id: string;
+        title: string;
+        score: number;
+        match_type: string;
+        keyword_score: number;
+        semantic_score: number;
+    }>>;
+    vectorStats(): Promise<{
+        model_downloaded: boolean;
+        model_loaded: boolean;
+        model_path: string;
+        index_count: number;
+    }>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listNodes(_projectId: string, filter?: ListNodesFilter): Promise<NodeData[]>;
@@ -96,3 +110,23 @@ export declare function addTaskLog(_projectId: string, taskId: string, logType:
 export declare function completeTask(_projectId: string, taskId: string, experience: TaskExperience): Promise<Task | null>;
 export declare function getRules(_projectId: string, ruleType: string): Promise<string[]>;
 export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;
+/** 向量搜索结果 */
+export interface VectorSearchResult {
+    id: string;
+    title: string;
+    score: number;
+    match_type: string;
+    keyword_score: number;
+    semantic_score: number;
+}
+/** 向量索引状态 */
+export interface VectorStats {
+    model_downloaded: boolean;
+    model_loaded: boolean;
+    model_path: string;
+    index_count: number;
+}
+/** 混合搜索 (关键词 + 语义) */
+export declare function vectorSearch(_projectId: string, query: string, limit: number, mode: 'hybrid' | 'keyword' | 'semantic'): Promise<VectorSearchResult[]>;
+/** 获取向量索引状态 */
+export declare function vectorStats(_projectId: string): Promise<VectorStats>;

package/dist/storage/httpClient.js

@@ -360,6 +360,16 @@ export class PpdocsApiClient {
             return false;
         }
     }
+    // ============ 向量搜索 API ============
+    async vectorSearch(query, limit, mode) {
+        return this.request('/vector/search', {
+            method: 'POST',
+            body: JSON.stringify({ query, limit, mode })
+        });
+    }
+    async vectorStats() {
+        return this.request('/vector/stats');
+    }
 }
 // ============ 模块级 API (兼容现有 tools/index.ts) ============
 let client = null;
@@ -429,3 +439,11 @@ export async function getRules(_projectId, ruleType) {
 export async function saveRules(_projectId, ruleType, rules) {
     return getClient().saveRulesApi(ruleType, rules);
 }
+/** 混合搜索 (关键词 + 语义) */
+export async function vectorSearch(_projectId, query, limit, mode) {
+    return getClient().vectorSearch(query, limit, mode);
+}
+/** 获取向量索引状态 */
+export async function vectorStats(_projectId) {
+    return getClient().vectorStats();
+}

package/dist/tools/helpers.d.ts

@@ -24,33 +24,6 @@ export declare function fetchRelations(projectId: string, nodeId: string, maxDep
     outgoing: RelationItem[];
     incoming: RelationItem[];
 }>;
-interface SearchResultItem {
-    id: string;
-    title: string;
-    tags: string[];
-    status: string;
-    summary: string;
-    score: string;
-    matchType: 'hybrid' | 'semantic' | 'keyword';
-}
-/**
- * 融合关键词和语义搜索结果
- */
-export declare function mergeSearchResults(keywordResults: Array<{
-    id: string;
-    title: string;
-    tags: string[];
-    status: string;
-    summary: string;
-    score: number;
-}>, semanticResults: Array<{
-    id: string;
-    title: string;
-    tags: string[];
-    status: string;
-    summary: string;
-    similarity: number;
-}>, mode: 'hybrid' | 'keyword' | 'semantic', limit: number): SearchResultItem[];
 /**
  * 格式化节点为 Markdown 输出
  */

package/dist/tools/helpers.js

@@ -40,62 +40,6 @@ export async function fetchRelations(projectId, nodeId, maxDepth) {
     await recurse(nodeId, 1, 'both');
     return { outgoing, incoming };
 }
-/**
- * 融合关键词和语义搜索结果
- */
-export function mergeSearchResults(keywordResults, semanticResults, mode, limit) {
-    const scoreMap = new Map();
-    // 合并关键词结果
-    for (const r of keywordResults) {
-        scoreMap.set(r.id, {
-            id: r.id,
-            title: r.title,
-            tags: r.tags,
-            status: r.status,
-            summary: r.summary,
-            keywordScore: r.score,
-            semanticScore: 0
-        });
-    }
-    // 合并语义结果
-    for (const r of semanticResults) {
-        const existing = scoreMap.get(r.id);
-        if (existing) {
-            existing.semanticScore = r.similarity;
-        }
-        else {
-            scoreMap.set(r.id, {
-                id: r.id,
-                title: r.title,
-                tags: r.tags,
-                status: r.status,
-                summary: r.summary,
-                keywordScore: 0,
-                semanticScore: r.similarity
-            });
-        }
-    }
-    // 计算综合得分并排序
-    const combined = Array.from(scoreMap.values()).map(item => {
-        // 混合权重: 语义 0.6 + 关键词 0.4
-        const finalScore = mode === 'keyword' ? item.keywordScore
-            : mode === 'semantic' ? item.semanticScore
-                : item.semanticScore * 0.6 + item.keywordScore * 0.4;
-        return { ...item, finalScore };
-    });
-    combined.sort((a, b) => b.finalScore - a.finalScore);
-    const topResults = combined.slice(0, limit);
-    return topResults.map(r => ({
-        id: r.id,
-        title: r.title,
-        tags: r.tags,
-        status: r.status,
-        summary: r.summary,
-        score: `${Math.round(r.finalScore * 100)}%`,
-        matchType: (r.keywordScore > 0 && r.semanticScore > 0 ? 'hybrid'
-            : r.semanticScore > 0 ? 'semantic' : 'keyword')
-    }));
-}
 // ==================== 节点格式化 ====================
 /**
  * 格式化节点为 Markdown 输出

package/dist/tools/index.js

@@ -1,9 +1,8 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
 import { decodeUnicodeEscapes, decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
-import * as vector from '../vector/index.js';
-import * as vectorManager from '../vector/manager.js';
-import { wrap, fetchRelations, mergeSearchResults, formatNodeMarkdown, formatRelationsMarkdown, buildDirectoryTree, formatTreeText, countTreeNodes } from './helpers.js';
+// 向量搜索已迁移至 Tauri 后端，通过 HTTP API 调用
+import { wrap, fetchRelations, formatNodeMarkdown, formatRelationsMarkdown, buildDirectoryTree, formatTreeText, countTreeNodes } from './helpers.js';
 export function registerTools(server, projectId, _user) {
     // 1. 创建节点
     server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍。⚠️ tags至少提供3个分类标签', {
@@ -35,27 +34,13 @@ export function registerTools(server, projectId, _user) {
             dependencies: decoded.dependencies || [],
             relatedFiles: decoded.relatedFiles || []
         });
-        // 自动更新向量索引
-        try {
-            await vector.upsertNode(projectId, node.id, node.title, node.description, node.categories);
-        }
-        catch (e) {
-            console.warn('[kg_create_node] Vector index update failed:', e);
-        }
+        // 向量索引由 Tauri 后端自动维护，MCP 不再手动更新
         return wrap(JSON.stringify(node, null, 2));
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
         const success = await storage.deleteNode(projectId, args.nodeId);
-        // 同步删除向量索引
-        if (success) {
-            try {
-                await vector.removeNode(projectId, args.nodeId);
-            }
-            catch (e) {
-                console.warn('[kg_delete_node] Vector index removal failed:', e);
-            }
-        }
+        // 向量索引由 Tauri 后端自动维护，MCP 不再手动删除
         return wrap(success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
     });
     // 3. 更新节点
@@ -110,15 +95,7 @@ export function registerTools(server, projectId, _user) {
         if (lastSyncAt !== undefined)
             updates.lastSyncAt = lastSyncAt;
         const node = await storage.updateNode(projectId, nodeId, updates);
-        // 自动更新向量索引 (标题或描述变更时)
-        if (node && (rest.title || rest.description || tags)) {
-            try {
-                await vector.upsertNode(projectId, node.id, node.title, node.description, node.categories);
-            }
-            catch (e) {
-                console.warn('[kg_update_node] Vector index update failed:', e);
-            }
-        }
+        // 向量索引由 Tauri 后端自动维护，MCP 不再手动更新
         return wrap(node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
     });
     // 3.5 更新根节点 (项目介绍)
@@ -190,56 +167,40 @@ export function registerTools(server, projectId, _user) {
             }));
             return wrap(`${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
         }
-        // 获取关键词结果
-        let keywordResults = [];
-        if (mode === 'hybrid' || mode === 'keyword') {
-            const kResults = await storage.searchNodes(projectId, args.keywords, limit * 2);
-            keywordResults = kResults.map(r => ({
+        // 调用 Tauri 后端混合搜索 API
+        try {
+            const results = await storage.vectorSearch(projectId, query, limit, mode);
+            // 补全节点信息 (tags, status, summary)
+            const output = [];
+            for (const r of results) {
+                const node = await storage.getNode(projectId, r.id);
+                output.push({
+                    id: r.id,
+                    title: r.title,
+                    tags: node?.categories || [],
+                    status: node?.status || 'incomplete',
+                    summary: node?.summary || '',
+                    score: `${Math.round(r.score)}%`,
+                    matchType: r.match_type
+                });
+            }
+            const json = JSON.stringify(output, null, 2);
+            return wrap(`${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
+        }
+        catch (e) {
+            // 后端搜索失败，降级为关键词搜索
+            console.warn('[kg_search] Vector search failed, fallback to keyword:', e);
+            const results = await storage.searchNodes(projectId, args.keywords, limit);
+            const output = results.map(r => ({
                 id: r.node.id,
                 title: r.node.title,
                 tags: r.node.categories || [],
                 status: r.node.status,
                 summary: r.node.summary || '',
-                score: r.score / 100
+                hitRate: `${Math.round(r.score)}%`
             }));
+            return wrap(`${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n⚠️ 语义搜索不可用，已降级为关键词搜索`);
         }
-        // 获取语义结果 (需补全节点信息)
-        let semanticResults = [];
-        if (mode === 'hybrid' || mode === 'semantic') {
-            try {
-                // 自动检测索引状态，缺失/不匹配则自动构建
-                await vectorManager.ensureIndex(projectId);
-                const rawSemantic = await vector.semanticSearch(projectId, query, limit * 2);
-                // 补全节点信息 (关键词结果中已有的复用，没有的获取)
-                const keywordMap = new Map(keywordResults.map(r => [r.id, r]));
-                for (const r of rawSemantic) {
-                    const existing = keywordMap.get(r.id);
-                    if (existing) {
-                        semanticResults.push({ ...existing, similarity: r.similarity });
-                    }
-                    else {
-                        const node = await storage.getNode(projectId, r.id);
-                        if (node) {
-                            semanticResults.push({
-                                id: r.id,
-                                title: r.title,
-                                tags: node.categories || [],
-                                status: node.status,
-                                summary: node.summary || '',
-                                similarity: r.similarity
-                            });
-                        }
-                    }
-                }
-            }
-            catch (e) {
-                console.warn('[kg_search] Semantic search failed:', e);
-            }
-        }
-        // 融合排序
-        const output = mergeSearchResults(keywordResults, semanticResults, mode, limit);
-        const json = JSON.stringify(output, null, 2);
-        return wrap(`${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
     });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
@@ -426,22 +387,25 @@ export function registerTools(server, projectId, _user) {
         return wrap(JSON.stringify(result, null, 2));
     });
     // ===================== 向量索引管理 =====================
-    // 16. 构建向量索引
-    server.tool('kg_build_index', '构建/重建向量语义索引(首次使用或索引损坏时调用)', {}, async () => {
-        const count = await vectorManager.rebuildIndex(projectId);
-        return wrap(`✅ 向量索引构建完成，共 ${count} 个节点`);
-    });
-    // 17. 查看索引状态
+    // 注意: 向量索引由 Tauri 后端自动维护，MCP 只提供只读查询
+    // 16. 查看索引状态 (只读)
     server.tool('kg_index_stats', '查看向量索引状态', {}, async () => {
-        const stats = await vector.getIndexStats(projectId);
-        const rebuildCheck = await vectorManager.needsRebuild(projectId);
-        return wrap(JSON.stringify({
-            ...stats,
-            needsRebuild: rebuildCheck.needed,
-            rebuildReason: rebuildCheck.reason,
-            tip: rebuildCheck.needed
-                ? `索引需要重建，原因: ${rebuildCheck.reason}`
-                : '索引正常 (搜索时会自动检测并重建)'
-        }, null, 2));
+        try {
+            const stats = await storage.vectorStats(projectId);
+            return wrap(JSON.stringify({
+                model_downloaded: stats.model_downloaded,
+                model_loaded: stats.model_loaded,
+                model_path: stats.model_path,
+                index_count: stats.index_count,
+                tip: '向量索引由软件端自动维护，节点增删改时自动更新'
+            }, null, 2));
+        }
+        catch (e) {
+            return wrap(JSON.stringify({
+                error: '无法获取索引状态',
+                message: String(e),
+                tip: '请确保软件端已启动'
+            }, null, 2));
+        }
     });
 }

package/dist/vector/manager.d.ts

@@ -1,11 +1,16 @@
 /**
- * 向量索引管理器
- * 负责自动检测、重建索引逻辑
- * @version 0.1
+ * 向量索引管理器 (已弃用)
+ *
+ * ⚠️ 自 v2.7.0 起，向量索引由 Tauri 后端自动维护
+ * 此模块保留仅用于向后兼容，不再被主动调用
+ *
+ * @deprecated 请使用 Tauri 后端的 vector 模块
+ * @version 0.2
  */
 interface RebuildReason {
     needed: boolean;
-    reason: 'missing' | 'model_mismatch' | 'empty' | 'none';
+    reason: 'missing' | 'model_mismatch' | 'empty' | 'count_mismatch' | 'none';
+    missingCount?: number;
 }
 interface RebuildResult {
     projectId: string;
@@ -21,7 +26,11 @@ export declare function needsRebuild(projectId: string): Promise<RebuildReason>;
  */
 export declare function rebuildIndex(projectId: string): Promise<number>;
 /**
- * 确保索引存在 (自动检测 + 按需构建)
+ * 增量同步缺失节点 (仅补漏，不全量重建)
+ */
+export declare function syncMissingNodes(projectId: string): Promise<number>;
+/**
+ * 确保索引存在 (自动检测 + 按需构建/增量补漏)
  */
 export declare function ensureIndex(projectId: string): Promise<void>;
 /**

package/dist/vector/manager.js

@@ -1,12 +1,46 @@
 /**
- * 向量索引管理器
- * 负责自动检测、重建索引逻辑
- * @version 0.1
+ * 向量索引管理器 (已弃用)
+ *
+ * ⚠️ 自 v2.7.0 起，向量索引由 Tauri 后端自动维护
+ * 此模块保留仅用于向后兼容，不再被主动调用
+ *
+ * @deprecated 请使用 Tauri 后端的 vector 模块
+ * @version 0.2
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as vectorCore from './index.js';
 // ==================== 检测函数 ====================
+/**
+ * 获取节点目录下的节点ID列表
+ */
+function getNodeIdsFromDisk(projectId) {
+    const baseDir = process.env.PPDOCS_DATA_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '', '.ppdocs');
+    const nodesDir = path.join(baseDir, 'projects', projectId, 'nodes');
+    const nodeIds = new Set();
+    if (!fs.existsSync(nodesDir))
+        return nodeIds;
+    try {
+        const files = fs.readdirSync(nodesDir).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(nodesDir, file), 'utf-8');
+                const node = JSON.parse(content);
+                // 跳过根节点
+                if (node.isOrigin || node.id === 'root')
+                    continue;
+                nodeIds.add(node.id);
+            }
+            catch {
+                // 跳过无法解析的文件
+            }
+        }
+    }
+    catch {
+        // 忽略读取错误
+    }
+    return nodeIds;
+}
 /**
  * 检测索引是否需要重建
  */
@@ -28,6 +62,13 @@ export async function needsRebuild(projectId) {
         if (!data.entries || data.entries.length === 0) {
             return { needed: true, reason: 'empty' };
         }
+        // 5. 检测节点数量不匹配 (新增)
+        const diskNodeIds = getNodeIdsFromDisk(projectId);
+        const indexedIds = new Set(data.entries.map(e => e.id));
+        const missingIds = [...diskNodeIds].filter(id => !indexedIds.has(id));
+        if (missingIds.length > 0) {
+            return { needed: true, reason: 'count_mismatch', missingCount: missingIds.length };
+        }
         return { needed: false, reason: 'none' };
     }
     catch {
@@ -87,11 +128,54 @@ export async function rebuildIndex(projectId) {
     return vectorCore.buildIndex(projectId, nodes);
 }
 /**
- * 确保索引存在 (自动检测 + 按需构建)
+ * 增量同步缺失节点 (仅补漏，不全量重建)
+ */
+export async function syncMissingNodes(projectId) {
+    const indexPath = vectorCore.getIndexPath(projectId);
+    // 读取当前索引
+    let indexedIds = new Set();
+    try {
+        if (fs.existsSync(indexPath)) {
+            const data = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+            indexedIds = new Set(data.entries.map(e => e.id));
+        }
+    }
+    catch {
+        // 索引损坏，需要全量重建
+        return rebuildIndex(projectId);
+    }
+    // 找出缺失的节点
+    const allNodes = await fetchNodesForIndex(projectId);
+    const missingNodes = allNodes.filter(n => !indexedIds.has(n.id));
+    if (missingNodes.length === 0) {
+        console.log(`[VectorManager] No missing nodes to sync`);
+        return 0;
+    }
+    console.log(`[VectorManager] Syncing ${missingNodes.length} missing nodes...`);
+    // 增量添加缺失节点
+    for (let i = 0; i < missingNodes.length; i++) {
+        const node = missingNodes[i];
+        await vectorCore.upsertNode(projectId, node.id, node.title, node.description, node.categories || []);
+        if ((i + 1) % 10 === 0) {
+            console.log(`[VectorManager] Synced ${i + 1}/${missingNodes.length}`);
+        }
+    }
+    console.log(`[VectorManager] Sync complete: ${missingNodes.length} nodes added`);
+    return missingNodes.length;
+}
+/**
+ * 确保索引存在 (自动检测 + 按需构建/增量补漏)
  */
 export async function ensureIndex(projectId) {
     const check = await needsRebuild(projectId);
-    if (check.needed) {
+    if (!check.needed)
+        return;
+    // count_mismatch 使用增量补漏，其他情况全量重建
+    if (check.reason === 'count_mismatch') {
+        console.log(`[VectorManager] Auto-syncing ${check.missingCount} missing nodes`);
+        await syncMissingNodes(projectId);
+    }
+    else {
         console.log(`[VectorManager] Auto-rebuilding index, reason: ${check.reason}`);
         await rebuildIndex(projectId);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.6.30",
+  "version": "2.7.1",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,6 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@xenova/transformers": "^2.17.2",
     "proper-lockfile": "^4.1.2",
     "zod": "^4.1.13"
   },