@ppdocs/mcp 2.6.27 → 2.6.29

package/dist/tools/helpers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * MCP 工具辅助函数
+ * 提取自 index.ts，避免重复代码
+ */
+import type { NodeData } from '../storage/types.js';
+/**
+ * 包装返回结果为 MCP 格式
+ */
+export declare function wrap(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+interface RelationItem {
+    id: string;
+    title: string;
+    edge: string;
+}
+/**
+ * 递归获取节点的上下游关系
+ */
+export declare function fetchRelations(projectId: string, nodeId: string, maxDepth: number): Promise<{
+    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 输出
+ */
+export declare function formatNodeMarkdown(node: NodeData): string[];
+/**
+ * 格式化关系输出
+ */
+export declare function formatRelationsMarkdown(outgoing: RelationItem[], incoming: RelationItem[]): string[];
+interface TreeNode {
+    name: string;
+    type: 'folder' | 'node';
+    nodeId?: string;
+    status?: string;
+    children?: TreeNode[];
+}
+/**
+ * 构建目录树结构
+ */
+export declare function buildDirectoryTree(nodes: NodeData[]): TreeNode;
+/**
+ * 格式化树为文本
+ */
+export declare function formatTreeText(tree: TreeNode): string;
+/**
+ * 统计树中的节点数
+ */
+export declare function countTreeNodes(tree: TreeNode): number;
+export {};

package/dist/tools/helpers.js

@@ -0,0 +1,263 @@
+/**
+ * MCP 工具辅助函数
+ * 提取自 index.ts，避免重复代码
+ */
+import * as storage from '../storage/httpClient.js';
+// ==================== 通用包装 ====================
+/**
+ * 包装返回结果为 MCP 格式
+ */
+export function wrap(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * 递归获取节点的上下游关系
+ */
+export async function fetchRelations(projectId, nodeId, maxDepth) {
+    const visited = new Set();
+    const outgoing = [];
+    const incoming = [];
+    async function recurse(currentNodeId, currentDepth, direction) {
+        if (currentDepth > maxDepth || visited.has(`${currentNodeId}-${direction}`))
+            return;
+        visited.add(`${currentNodeId}-${direction}`);
+        const relations = await storage.getRelations(projectId, currentNodeId);
+        for (const r of relations) {
+            if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
+                if (!outgoing.some(o => o.id === r.nodeId)) {
+                    outgoing.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
+                    await recurse(r.nodeId, currentDepth + 1, 'outgoing');
+                }
+            }
+            if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
+                if (!incoming.some(i => i.id === r.nodeId)) {
+                    incoming.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
+                    await recurse(r.nodeId, currentDepth + 1, 'incoming');
+                }
+            }
+        }
+    }
+    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 输出
+ */
+export function formatNodeMarkdown(node) {
+    const lines = [];
+    // 基础信息
+    lines.push(`## ${node.title}\n`);
+    if (node.summary) {
+        lines.push(`> ${node.summary}\n`);
+    }
+    lines.push('**基础信息**');
+    lines.push(`| 字段 | 值 |`);
+    lines.push(`|:---|:---|`);
+    lines.push(`| ID | ${node.id} |`);
+    lines.push(`| 类型 | ${node.type} |`);
+    lines.push(`| 状态 | ${node.status} |`);
+    lines.push(`| 签名 | ${node.signature} |`);
+    if (node.categories && node.categories.length > 0) {
+        lines.push(`| 标签 | ${node.categories.join(', ')} |`);
+    }
+    lines.push('');
+    // 关联文件
+    if (node.relatedFiles && node.relatedFiles.length > 0) {
+        lines.push('**关联文件**');
+        node.relatedFiles.forEach((f) => lines.push(`- ${f}`));
+        lines.push('');
+    }
+    // 依赖关系
+    if (node.dependencies && node.dependencies.length > 0) {
+        lines.push('**依赖关系**');
+        node.dependencies.forEach((d) => lines.push(`- ${d.name}: ${d.description}`));
+        lines.push('');
+    }
+    // 描述内容
+    if (node.description) {
+        lines.push('**描述内容**');
+        lines.push(node.description);
+        lines.push('');
+    }
+    // 更新历史
+    if (node.versions && node.versions.length > 0) {
+        lines.push('**更新历史**');
+        lines.push('| 版本 | 日期 | 变更 |');
+        lines.push('|:---|:---|:---|');
+        node.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
+        lines.push('');
+    }
+    // 修复历史
+    if (node.bugfixes && node.bugfixes.length > 0) {
+        lines.push('**修复历史**');
+        lines.push('| ID | 日期 | 问题 | 方案 |');
+        lines.push('|:---|:---|:---|:---|');
+        node.bugfixes.forEach((b) => lines.push(`| ${b.id} | ${b.date} | ${b.issue} | ${b.solution} |`));
+        lines.push('');
+    }
+    return lines;
+}
+/**
+ * 格式化关系输出
+ */
+export function formatRelationsMarkdown(outgoing, incoming) {
+    const lines = [];
+    if (outgoing.length > 0 || incoming.length > 0) {
+        lines.push('**上下游关系**');
+        if (outgoing.length > 0) {
+            lines.push(`- 依赖 (${outgoing.length}): ${outgoing.map(o => o.title).join(', ')}`);
+        }
+        if (incoming.length > 0) {
+            lines.push(`- 被依赖 (${incoming.length}): ${incoming.map(i => i.title).join(', ')}`);
+        }
+        lines.push('');
+    }
+    return lines;
+}
+/**
+ * 构建目录树结构
+ */
+export function buildDirectoryTree(nodes) {
+    const root = { name: '/', type: 'folder', children: [] };
+    // 过滤掉根节点
+    const docNodes = nodes.filter(n => !n.isOrigin && n.id !== 'root');
+    for (const node of docNodes) {
+        const pathSegments = (node.path || '').split('/').filter(Boolean);
+        let current = root;
+        // 遍历路径段，创建目录结构
+        for (const segment of pathSegments) {
+            if (!current.children)
+                current.children = [];
+            let child = current.children.find(c => c.name === segment && c.type === 'folder');
+            if (!child) {
+                child = { name: segment, type: 'folder', children: [] };
+                current.children.push(child);
+            }
+            current = child;
+        }
+        // 添加节点
+        if (!current.children)
+            current.children = [];
+        current.children.push({
+            name: node.title,
+            type: 'node',
+            nodeId: node.id,
+            status: node.status
+        });
+    }
+    // 递归排序 (目录在前，节点在后)
+    sortTree(root);
+    return root;
+}
+function sortTree(node) {
+    if (!node.children)
+        return;
+    node.children.sort((a, b) => {
+        if (a.type === 'folder' && b.type !== 'folder')
+            return -1;
+        if (a.type !== 'folder' && b.type === 'folder')
+            return 1;
+        return a.name.localeCompare(b.name, 'zh-CN');
+    });
+    for (const child of node.children) {
+        if (child.type === 'folder')
+            sortTree(child);
+    }
+}
+/**
+ * 格式化树为文本
+ */
+export function formatTreeText(tree) {
+    function format(node, prefix = '', isLast = true) {
+        const lines = [];
+        const connector = isLast ? '└── ' : '├── ';
+        const childPrefix = isLast ? '    ' : '│   ';
+        if (node.name !== '/') {
+            const icon = node.type === 'folder' ? '📁' : '📄';
+            const status = node.status ? ` [${node.status}]` : '';
+            lines.push(`${prefix}${connector}${icon} ${node.name}${status}`);
+        }
+        if (node.children) {
+            for (let i = 0; i < node.children.length; i++) {
+                const child = node.children[i];
+                const childIsLast = i === node.children.length - 1;
+                const newPrefix = node.name === '/' ? '' : prefix + childPrefix;
+                lines.push(...format(child, newPrefix, childIsLast));
+            }
+        }
+        return lines;
+    }
+    return format(tree).join('\n');
+}
+/**
+ * 统计树中的节点数
+ */
+export function countTreeNodes(tree) {
+    let count = 0;
+    function traverse(node) {
+        if (node.type === 'node')
+            count++;
+        if (node.children) {
+            node.children.forEach(traverse);
+        }
+    }
+    traverse(tree);
+    return count;
+}

package/dist/tools/index.js

@@ -2,10 +2,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';
-// 辅助函数: 包装返回结果
-function wrap(_projectId, text) {
-    return { content: [{ type: 'text', text }] };
-}
+import * as vectorManager from '../vector/manager.js';
+import { wrap, fetchRelations, mergeSearchResults, 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个分类标签', {
@@ -44,7 +42,7 @@ export function registerTools(server, projectId, _user) {
         catch (e) {
             console.warn('[kg_create_node] Vector index update failed:', e);
         }
-        return wrap(projectId, JSON.stringify(node, null, 2));
+        return wrap(JSON.stringify(node, null, 2));
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
@@ -58,7 +56,7 @@ export function registerTools(server, projectId, _user) {
                 console.warn('[kg_delete_node] Vector index removal failed:', e);
             }
         }
-        return wrap(projectId, success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
+        return wrap(success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
     });
     // 3. 更新节点
     server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)。⚠️ 更新tags时至少提供3个分类标签', {
@@ -95,7 +93,7 @@ export function registerTools(server, projectId, _user) {
         const { nodeId, tags, relatedFiles, versions, bugfixes, path, lastSyncAt, ...rest } = decoded;
         // 根节点必须使用 kg_update_root 更新
         if (nodeId === 'root') {
-            return wrap(projectId, '❌ 根节点请使用 kg_update_root 方法更新');
+            return wrap('❌ 根节点请使用 kg_update_root 方法更新');
         }
         // API 参数转换
         let updates = { ...rest };
@@ -121,7 +119,7 @@ export function registerTools(server, projectId, _user) {
                 console.warn('[kg_update_node] Vector index update failed:', e);
             }
         }
-        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
+        return wrap(node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
     });
     // 3.5 更新根节点 (项目介绍)
     server.tool('kg_update_root', '更新项目介绍(根节点描述，锁定时不可更新)', {
@@ -130,13 +128,13 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
         if (decoded.title === undefined && decoded.description === undefined) {
-            return wrap(projectId, '❌ 请至少提供 title 或 description');
+            return wrap('❌ 请至少提供 title 或 description');
         }
         const node = await storage.updateRoot(projectId, {
             title: decoded.title,
             description: decoded.description
         });
-        return wrap(projectId, node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
+        return wrap(node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
     });
     // 3.6 获取项目规则 (独立方法，按需调用)
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
@@ -159,25 +157,25 @@ export function registerTools(server, projectId, _user) {
         const decoded = decodeObjectStrings(args);
         const success = await storage.saveRules(projectId, decoded.ruleType, decoded.rules);
         if (!success) {
-            return wrap(projectId, '❌ 保存失败');
+            return wrap('❌ 保存失败');
         }
-        return wrap(projectId, `✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
+        return wrap(`✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
     });
     // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
     server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
         nodeId: z.string().describe('节点ID')
     }, async (args) => {
         const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
-        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '操作失败');
+        return wrap(node ? JSON.stringify(node, null, 2) : '操作失败');
     });
     // 5. 搜索节点 (混合检索: 向量语义 + 关键词)
     server.tool('kg_search', '智能搜索节点(语义+关键词混合)。支持中英文语义匹配，空白关键词[""]返回全部节点', {
-        keywords: z.array(z.string()).describe('搜索词列表，支持语义匹配(如"登录"可找到auth)'),
+        keywords: z.array(z.string()).describe('搜索词列表(⚠️建议3个以上关键词提高准确率)，支持语义匹配(如"登录"可找到auth)'),
         limit: z.number().optional().describe('返回数量(默认10)'),
         mode: z.enum(['hybrid', 'keyword', 'semantic']).optional().describe('搜索模式: hybrid=混合(默认), keyword=仅关键词, semantic=仅语义')
     }, async (args) => {
         const limit = args.limit || 10;
-        const mode = args.mode || 'hybrid';
+        const mode = (args.mode || 'hybrid');
         const query = args.keywords.filter(k => k.trim()).join(' ');
         // 空白关键词返回全部
         if (!query) {
@@ -190,7 +188,7 @@ export function registerTools(server, projectId, _user) {
                 summary: r.node.summary || '',
                 hitRate: `${Math.round(r.score)}%`
             }));
-            return wrap(projectId, `${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
+            return wrap(`${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
         }
         // 获取关键词结果
         let keywordResults = [];
@@ -202,77 +200,46 @@ export function registerTools(server, projectId, _user) {
                 tags: r.node.categories || [],
                 status: r.node.status,
                 summary: r.node.summary || '',
-                score: r.score / 100 // 归一化到 0-1
+                score: r.score / 100
             }));
         }
-        // 获取语义结果
+        // 获取语义结果 (需补全节点信息)
         let semanticResults = [];
         if (mode === 'hybrid' || mode === 'semantic') {
             try {
-                semanticResults = await vector.semanticSearch(projectId, query, limit * 2);
+                // 自动检测索引状态，缺失/不匹配则自动构建
+                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, falling back to keyword:', e);
-            }
-        }
-        // 融合排序 (混合模式)
-        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 {
-                // 需要获取节点详情
-                const node = await storage.getNode(projectId, r.id);
-                if (node) {
-                    scoreMap.set(r.id, {
-                        id: r.id,
-                        title: r.title,
-                        tags: node.categories || [],
-                        status: node.status,
-                        summary: node.summary || '',
-                        keywordScore: 0,
-                        semanticScore: r.similarity
-                    });
-                }
+                console.warn('[kg_search] Semantic search failed:', e);
             }
         }
-        // 计算综合得分并排序
-        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);
-        const output = 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'
-        }));
+        // 融合排序
+        const output = mergeSearchResults(keywordResults, semanticResults, mode, limit);
         const json = JSON.stringify(output, null, 2);
-        return wrap(projectId, `${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
+        return wrap(`${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
     });
     // 5.5 列出所有标签
     server.tool('kg_list_tags', '获取所有节点使用过的标签列表(去重)', {}, async () => {
@@ -284,7 +251,7 @@ export function registerTools(server, projectId, _user) {
             }
         }
         const tags = Array.from(tagSet).sort();
-        return wrap(projectId, JSON.stringify({ total: tags.length, tags }, null, 2));
+        return wrap(JSON.stringify({ total: tags.length, tags }, null, 2));
     });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
@@ -293,13 +260,13 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const result = await storage.findPath(projectId, args.startId, args.endId);
         if (!result)
-            return wrap(projectId, '未找到路径');
+            return wrap('未找到路径');
         const output = {
             pathLength: result.path.length,
             nodes: result.path.map(n => ({ id: n.id, title: n.title, type: n.type })),
             edges: result.edges.map(e => ({ from: e.source, to: e.target, type: e.type }))
         };
-        return wrap(projectId, JSON.stringify(output, null, 2));
+        return wrap(JSON.stringify(output, null, 2));
     });
     // 7. 列出节点 (支持过滤)
     server.tool('kg_list_nodes', '列出节点，支持按状态/连接数过滤。maxEdges=0 可查孤立节点', {
@@ -312,7 +279,7 @@ export function registerTools(server, projectId, _user) {
             : undefined;
         const nodes = await storage.listNodes(projectId, filter);
         const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked, summary: n.summary || '' }));
-        return wrap(projectId, JSON.stringify(output, null, 2));
+        return wrap(JSON.stringify(output, null, 2));
     });
     // 8. 查询节点关系网 (支持多层)
     server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)，支持多层查询', {
@@ -320,35 +287,11 @@ export function registerTools(server, projectId, _user) {
         depth: z.number().min(1).max(3).optional().describe('查询层数(默认1，最大3)')
     }, async (args) => {
         const maxDepth = Math.min(args.depth || 1, 3);
-        const visited = new Set();
-        const outgoing = [];
-        const incoming = [];
-        // 递归获取关系
-        async function fetchRelations(nodeId, currentDepth, direction) {
-            if (currentDepth > maxDepth || visited.has(`${nodeId}-${direction}`))
-                return;
-            visited.add(`${nodeId}-${direction}`);
-            const relations = await storage.getRelations(projectId, nodeId);
-            for (const r of relations) {
-                if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
-                    if (!outgoing.some(o => o.id === r.nodeId)) {
-                        outgoing.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
-                        await fetchRelations(r.nodeId, currentDepth + 1, 'outgoing');
-                    }
-                }
-                if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
-                    if (!incoming.some(i => i.id === r.nodeId)) {
-                        incoming.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
-                        await fetchRelations(r.nodeId, currentDepth + 1, 'incoming');
-                    }
-                }
-            }
-        }
-        await fetchRelations(args.nodeId, 1, 'both');
+        const { outgoing, incoming } = await fetchRelations(projectId, args.nodeId, maxDepth);
         if (outgoing.length === 0 && incoming.length === 0) {
-            return wrap(projectId, '该节点没有任何连线');
+            return wrap('该节点没有任何连线');
         }
-        return wrap(projectId, JSON.stringify({ outgoing, incoming }, null, 2));
+        return wrap(JSON.stringify({ outgoing, incoming }, null, 2));
     });
     // 9. 读取单个节点详情
     server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)，可选包含上下游关系', {
@@ -357,171 +300,25 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const node = await storage.getNode(projectId, args.nodeId);
         if (!node) {
-            return wrap(projectId, '节点不存在');
-        }
-        // 构建结构化输出
-        const lines = [];
-        // 基础信息
-        lines.push(`## ${node.title}\n`);
-        if (node.summary) {
-            lines.push(`> ${node.summary}\n`);
-        }
-        lines.push('**基础信息**');
-        lines.push(`| 字段 | 值 |`);
-        lines.push(`|:---|:---|`);
-        lines.push(`| ID | ${node.id} |`);
-        lines.push(`| 类型 | ${node.type} |`);
-        lines.push(`| 状态 | ${node.status} |`);
-        lines.push(`| 签名 | ${node.signature} |`);
-        if (node.categories && node.categories.length > 0) {
-            lines.push(`| 标签 | ${node.categories.join(', ')} |`);
-        }
-        lines.push('');
-        // 关联文件
-        if (node.relatedFiles && node.relatedFiles.length > 0) {
-            lines.push('**关联文件**');
-            node.relatedFiles.forEach(f => lines.push(`- ${f}`));
-            lines.push('');
-        }
-        // 依赖关系
-        if (node.dependencies && node.dependencies.length > 0) {
-            lines.push('**依赖关系**');
-            node.dependencies.forEach(d => lines.push(`- ${d.name}: ${d.description}`));
-            lines.push('');
-        }
-        // 描述内容
-        if (node.description) {
-            lines.push('**描述内容**');
-            lines.push(node.description);
-            lines.push('');
-        }
-        // 更新历史
-        if (node.versions && node.versions.length > 0) {
-            lines.push('**更新历史**');
-            lines.push('| 版本 | 日期 | 变更 |');
-            lines.push('|:---|:---|:---|');
-            node.versions.forEach(v => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
-            lines.push('');
-        }
-        // 修复历史
-        if (node.bugfixes && node.bugfixes.length > 0) {
-            lines.push('**修复历史**');
-            lines.push('| ID | 日期 | 问题 | 方案 |');
-            lines.push('|:---|:---|:---|:---|');
-            node.bugfixes.forEach(b => lines.push(`| ${b.id} | ${b.date} | ${b.issue} | ${b.solution} |`));
-            lines.push('');
+            return wrap('节点不存在');
         }
+        // 格式化节点基础信息
+        const lines = formatNodeMarkdown(node);
         // 上下游关系 (depth > 0 时获取)
         const depth = args.depth || 0;
         if (depth > 0) {
-            const visited = new Set();
-            const outgoing = [];
-            const incoming = [];
-            async function fetchRelations(nodeId, currentDepth, direction) {
-                if (currentDepth > depth || visited.has(`${nodeId}-${direction}`))
-                    return;
-                visited.add(`${nodeId}-${direction}`);
-                const relations = await storage.getRelations(projectId, nodeId);
-                for (const r of relations) {
-                    if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
-                        if (!outgoing.some(o => o.id === r.nodeId)) {
-                            outgoing.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
-                            await fetchRelations(r.nodeId, currentDepth + 1, 'outgoing');
-                        }
-                    }
-                    if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
-                        if (!incoming.some(i => i.id === r.nodeId)) {
-                            incoming.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
-                            await fetchRelations(r.nodeId, currentDepth + 1, 'incoming');
-                        }
-                    }
-                }
-            }
-            await fetchRelations(args.nodeId, 1, 'both');
-            if (outgoing.length > 0 || incoming.length > 0) {
-                lines.push('**上下游关系**');
-                if (outgoing.length > 0) {
-                    lines.push(`- 依赖 (${outgoing.length}): ${outgoing.map(o => o.title).join(', ')}`);
-                }
-                if (incoming.length > 0) {
-                    lines.push(`- 被依赖 (${incoming.length}): ${incoming.map(i => i.title).join(', ')}`);
-                }
-                lines.push('');
-            }
+            const { outgoing, incoming } = await fetchRelations(projectId, args.nodeId, depth);
+            lines.push(...formatRelationsMarkdown(outgoing, incoming));
         }
-        return wrap(projectId, lines.join('\n'));
+        return wrap(lines.join('\n'));
     });
     // 10. 获取知识库树状图
     server.tool('kg_get_tree', '获取知识库的目录树结构(按 path 分组)', {}, async () => {
         const nodes = await storage.listNodes(projectId);
-        const root = { name: '/', type: 'folder', children: [] };
-        // 过滤掉根节点
-        const docNodes = nodes.filter(n => !n.isOrigin && n.id !== 'root');
-        for (const node of docNodes) {
-            const pathSegments = (node.path || '').split('/').filter(Boolean);
-            let current = root;
-            // 遍历路径段，创建目录结构
-            for (const segment of pathSegments) {
-                if (!current.children)
-                    current.children = [];
-                let child = current.children.find(c => c.name === segment && c.type === 'folder');
-                if (!child) {
-                    child = { name: segment, type: 'folder', children: [] };
-                    current.children.push(child);
-                }
-                current = child;
-            }
-            // 添加节点
-            if (!current.children)
-                current.children = [];
-            current.children.push({
-                name: node.title,
-                type: 'node',
-                nodeId: node.id,
-                status: node.status
-            });
-        }
-        // 递归排序 (目录在前，节点在后)
-        function sortTree(node) {
-            if (!node.children)
-                return;
-            node.children.sort((a, b) => {
-                if (a.type === 'folder' && b.type !== 'folder')
-                    return -1;
-                if (a.type !== 'folder' && b.type === 'folder')
-                    return 1;
-                return a.name.localeCompare(b.name, 'zh-CN');
-            });
-            for (const child of node.children) {
-                if (child.type === 'folder')
-                    sortTree(child);
-            }
-        }
-        sortTree(root);
-        // 格式化为文本树
-        function formatTree(node, prefix = '', isLast = true) {
-            const lines = [];
-            const connector = isLast ? '└── ' : '├── ';
-            const childPrefix = isLast ? '    ' : '│   ';
-            if (node.name !== '/') {
-                const icon = node.type === 'folder' ? '📁' : '📄';
-                const status = node.status ? ` [${node.status}]` : '';
-                lines.push(`${prefix}${connector}${icon} ${node.name}${status}`);
-            }
-            if (node.children) {
-                const children = node.children;
-                for (let i = 0; i < children.length; i++) {
-                    const child = children[i];
-                    const childIsLast = i === children.length - 1;
-                    const newPrefix = node.name === '/' ? '' : prefix + childPrefix;
-                    lines.push(...formatTree(child, newPrefix, childIsLast));
-                }
-            }
-            return lines;
-        }
-        const treeText = formatTree(root).join('\n');
-        const summary = `共 ${docNodes.length} 个节点\n\n${treeText}`;
-        return wrap(projectId, summary);
+        const tree = buildDirectoryTree(nodes);
+        const treeText = formatTreeText(tree);
+        const nodeCount = countTreeNodes(tree);
+        return wrap(`共 ${nodeCount} 个节点\n\n${treeText}`);
     });
     // ===================== 任务管理工具 =====================
     // 11. 创建任务
@@ -539,7 +336,7 @@ export function registerTools(server, projectId, _user) {
             goals: decoded.goals || [],
             related_nodes: decoded.related_nodes
         }, _user);
-        return wrap(projectId, JSON.stringify(task, null, 2));
+        return wrap(JSON.stringify(task, null, 2));
     });
     // 11. 列出任务
     server.tool('task_list', '列出任务(active=进行中,archived=已归档)', {
@@ -554,7 +351,7 @@ export function registerTools(server, projectId, _user) {
             created_at: t.created_at,
             last_log: t.last_log
         }));
-        return wrap(projectId, JSON.stringify(output, null, 2));
+        return wrap(JSON.stringify(output, null, 2));
     });
     // 12. 获取任务详情
     server.tool('task_get', '获取任务完整信息(含全部日志)', {
@@ -562,9 +359,9 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const task = await storage.getTask(projectId, args.taskId);
         if (!task) {
-            return wrap(projectId, '任务不存在');
+            return wrap('任务不存在');
         }
-        return wrap(projectId, JSON.stringify(task, null, 2));
+        return wrap(JSON.stringify(task, null, 2));
     });
     // 13. 添加任务日志
     server.tool('task_add_log', '记录任务进展/问题/方案/参考', {
@@ -576,9 +373,9 @@ export function registerTools(server, projectId, _user) {
         const decodedContent = decodeUnicodeEscapes(args.content);
         const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, decodedContent);
         if (!task) {
-            return wrap(projectId, '添加失败(任务不存在或已归档)');
+            return wrap('添加失败(任务不存在或已归档)');
         }
-        return wrap(projectId, `日志已添加，任务共有 ${task.logs.length} 条日志`);
+        return wrap(`日志已添加，任务共有 ${task.logs.length} 条日志`);
     });
     // 14. 完成任务
     server.tool('task_complete', '完成任务并归档,填写经验总结', {
@@ -600,9 +397,9 @@ export function registerTools(server, projectId, _user) {
         });
         const task = await storage.completeTask(projectId, args.taskId, decoded);
         if (!task) {
-            return wrap(projectId, '完成失败(任务不存在或已归档)');
+            return wrap('完成失败(任务不存在或已归档)');
         }
-        return wrap(projectId, `任务已完成归档: ${task.title}`);
+        return wrap(`任务已完成归档: ${task.title}`);
     });
     // 15. 查询文件关联的节点
     server.tool('kg_find_by_file', '查询哪些节点绑定了指定文件(删除/重命名前检查)', {
@@ -638,26 +435,25 @@ export function registerTools(server, projectId, _user) {
                 ? `⚠️ 该文件被 ${boundBy.length} 个节点引用，删除前请更新节点`
                 : '✅ 该文件无 KG 引用，可安全操作'
         };
-        return wrap(projectId, JSON.stringify(result, null, 2));
+        return wrap(JSON.stringify(result, null, 2));
     });
     // ===================== 向量索引管理 =====================
     // 16. 构建向量索引
     server.tool('kg_build_index', '构建/重建向量语义索引(首次使用或索引损坏时调用)', {}, async () => {
-        const nodes = await storage.listNodes(projectId);
-        const count = await vector.buildIndex(projectId, nodes.map(n => ({
-            id: n.id,
-            title: n.title,
-            description: n.description,
-            categories: n.categories
-        })));
-        return wrap(projectId, `✅ 向量索引构建完成，共 ${count} 个节点`);
+        const count = await vectorManager.rebuildIndex(projectId);
+        return wrap(`✅ 向量索引构建完成，共 ${count} 个节点`);
     });
     // 17. 查看索引状态
     server.tool('kg_index_stats', '查看向量索引状态', {}, async () => {
         const stats = await vector.getIndexStats(projectId);
-        return wrap(projectId, JSON.stringify({
+        const rebuildCheck = await vectorManager.needsRebuild(projectId);
+        return wrap(JSON.stringify({
             ...stats,
-            tip: stats.count === 0 ? '索引为空，请运行 kg_build_index 构建索引' : '索引正常'
+            needsRebuild: rebuildCheck.needed,
+            rebuildReason: rebuildCheck.reason,
+            tip: rebuildCheck.needed
+                ? `索引需要重建，原因: ${rebuildCheck.reason}`
+                : '索引正常 (搜索时会自动检测并重建)'
         }, null, 2));
     });
 }

package/dist/vector/index.d.ts

@@ -1,12 +1,24 @@
 /**
  * 向量检索服务 - 基于 transformers.js 的语义搜索
- * @version 0.1
+ * @version 0.2
  */
+interface VectorConfig {
+    model: string;
+    quantized: boolean;
+}
+/**
+ * 获取向量配置 (从 ~/.ppdocs/config/vector.json 读取)
+ */
+export declare function getVectorConfig(): VectorConfig;
 interface VectorSearchResult {
     id: string;
     title: string;
     similarity: number;
 }
+/**
+ * 获取索引文件路径
+ */
+export declare function getIndexPath(projectId: string): string;
 /**
  * 添加或更新节点向量
  */

package/dist/vector/index.js

@@ -1,13 +1,32 @@
 /**
  * 向量检索服务 - 基于 transformers.js 的语义搜索
- * @version 0.1
+ * @version 0.2
  */
 import { pipeline } from '@xenova/transformers';
 import * as fs from 'fs';
 import * as path from 'path';
-// 模型配置
-const MODEL_NAME = 'Xenova/multilingual-e5-small'; // 120MB, 384维, 100+语言(含中文)
+// 默认模型配置
+const DEFAULT_MODEL = 'Xenova/multilingual-e5-small';
 const VECTOR_DIM = 384;
+// 当前加载的模型名
+let currentModel = null;
+/**
+ * 获取向量配置 (从 ~/.ppdocs/config/vector.json 读取)
+ */
+export function getVectorConfig() {
+    const baseDir = process.env.PPDOCS_DATA_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '', '.ppdocs');
+    const configPath = path.join(baseDir, 'config', 'vector.json');
+    try {
+        if (fs.existsSync(configPath)) {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            return JSON.parse(content);
+        }
+    }
+    catch (e) {
+        console.warn('[Vector] Failed to load config:', e);
+    }
+    return { model: DEFAULT_MODEL, quantized: true };
+}
 // 单例模式
 let extractor = null;
 let isLoading = false;
@@ -18,15 +37,19 @@ const vectorIndex = new Map();
  * 加载嵌入模型 (懒加载, 首次调用时下载)
  */
 async function getExtractor() {
-    if (extractor)
+    const config = getVectorConfig();
+    // 如果模型变更，重新加载
+    if (extractor && currentModel === config.model) {
         return extractor;
-    if (isLoading && loadPromise) {
+    }
+    if (isLoading && loadPromise && currentModel === config.model) {
         return loadPromise;
     }
     isLoading = true;
-    console.log('[Vector] Loading embedding model...');
-    loadPromise = pipeline('feature-extraction', MODEL_NAME, {
-        quantized: true, // 使用量化版本，更小更快
+    currentModel = config.model;
+    console.log(`[Vector] Loading embedding model: ${config.model}...`);
+    loadPromise = pipeline('feature-extraction', config.model, {
+        quantized: config.quantized,
     });
     extractor = await loadPromise;
     isLoading = false;
@@ -61,7 +84,7 @@ function cosineSimilarity(a, b) {
 /**
  * 获取索引文件路径
  */
-function getIndexPath(projectId) {
+export function getIndexPath(projectId) {
     const baseDir = process.env.PPDOCS_DATA_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '', '.ppdocs');
     return path.join(baseDir, 'projects', projectId, 'vector-index.json');
 }
@@ -100,9 +123,10 @@ async function saveIndex(projectId) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
+        const config = getVectorConfig();
         fs.writeFileSync(indexPath, JSON.stringify({
             version: 1,
-            model: MODEL_NAME,
+            model: config.model,
             dimension: VECTOR_DIM,
             updatedAt: new Date().toISOString(),
             entries
@@ -188,9 +212,10 @@ export async function buildIndex(projectId, nodes) {
  */
 export async function getIndexStats(projectId) {
     const entries = await loadIndex(projectId);
+    const config = getVectorConfig();
     return {
         count: entries.length,
-        model: MODEL_NAME,
+        model: config.model,
         dimension: VECTOR_DIM,
         loaded: extractor !== null
     };

package/dist/vector/manager.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 向量索引管理器
+ * 负责自动检测、重建索引逻辑
+ * @version 0.1
+ */
+interface RebuildReason {
+    needed: boolean;
+    reason: 'missing' | 'model_mismatch' | 'empty' | 'none';
+}
+interface RebuildResult {
+    projectId: string;
+    count: number;
+    reason: string;
+}
+/**
+ * 检测索引是否需要重建
+ */
+export declare function needsRebuild(projectId: string): Promise<RebuildReason>;
+/**
+ * 强制重建项目索引
+ */
+export declare function rebuildIndex(projectId: string): Promise<number>;
+/**
+ * 确保索引存在 (自动检测 + 按需构建)
+ */
+export declare function ensureIndex(projectId: string): Promise<void>;
+/**
+ * 重建所有项目索引
+ */
+export declare function rebuildAllIndexes(): Promise<RebuildResult[]>;
+/**
+ * 获取所有项目的索引状态
+ */
+export declare function getAllIndexStats(): Promise<Array<{
+    projectId: string;
+    status: RebuildReason;
+    nodeCount: number;
+}>>;
+export {};

package/dist/vector/manager.js

@@ -0,0 +1,166 @@
+/**
+ * 向量索引管理器
+ * 负责自动检测、重建索引逻辑
+ * @version 0.1
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as vectorCore from './index.js';
+// ==================== 检测函数 ====================
+/**
+ * 检测索引是否需要重建
+ */
+export async function needsRebuild(projectId) {
+    const indexPath = vectorCore.getIndexPath(projectId);
+    const config = vectorCore.getVectorConfig();
+    // 1. 索引文件不存在
+    if (!fs.existsSync(indexPath)) {
+        return { needed: true, reason: 'missing' };
+    }
+    // 2. 读取索引元数据
+    try {
+        const data = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+        // 3. 模型不匹配
+        if (data.model !== config.model) {
+            return { needed: true, reason: 'model_mismatch' };
+        }
+        // 4. 索引为空
+        if (!data.entries || data.entries.length === 0) {
+            return { needed: true, reason: 'empty' };
+        }
+        return { needed: false, reason: 'none' };
+    }
+    catch {
+        // 读取失败视为需要重建
+        return { needed: true, reason: 'missing' };
+    }
+}
+// ==================== 重建函数 ====================
+/**
+ * 获取节点数据 (用于重建索引)
+ */
+async function fetchNodesForIndex(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');
+    if (!fs.existsSync(nodesDir)) {
+        console.log(`[VectorManager] No nodes directory found for project ${projectId}`);
+        return [];
+    }
+    const nodes = [];
+    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;
+                nodes.push({
+                    id: node.id,
+                    title: node.title || '',
+                    description: node.description || '',
+                    categories: node.categories || node.tags || []
+                });
+            }
+            catch {
+                // 跳过无法解析的文件
+            }
+        }
+    }
+    catch (e) {
+        console.warn(`[VectorManager] Failed to read nodes:`, e);
+    }
+    return nodes;
+}
+/**
+ * 强制重建项目索引
+ */
+export async function rebuildIndex(projectId) {
+    console.log(`[VectorManager] Rebuilding index for project: ${projectId}`);
+    const nodes = await fetchNodesForIndex(projectId);
+    if (nodes.length === 0) {
+        console.log(`[VectorManager] No nodes to index`);
+        return 0;
+    }
+    return vectorCore.buildIndex(projectId, nodes);
+}
+/**
+ * 确保索引存在 (自动检测 + 按需构建)
+ */
+export async function ensureIndex(projectId) {
+    const check = await needsRebuild(projectId);
+    if (check.needed) {
+        console.log(`[VectorManager] Auto-rebuilding index, reason: ${check.reason}`);
+        await rebuildIndex(projectId);
+    }
+}
+// ==================== 批量操作 ====================
+/**
+ * 获取所有项目 ID
+ */
+function listAllProjects() {
+    const baseDir = process.env.PPDOCS_DATA_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '', '.ppdocs');
+    const projectsDir = path.join(baseDir, 'projects');
+    if (!fs.existsSync(projectsDir)) {
+        return [];
+    }
+    try {
+        return fs.readdirSync(projectsDir)
+            .filter(name => {
+            const stat = fs.statSync(path.join(projectsDir, name));
+            return stat.isDirectory() && name.startsWith('project-');
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 重建所有项目索引
+ */
+export async function rebuildAllIndexes() {
+    const projects = listAllProjects();
+    console.log(`[VectorManager] Rebuilding indexes for ${projects.length} projects...`);
+    const results = [];
+    for (const projectId of projects) {
+        try {
+            const check = await needsRebuild(projectId);
+            const count = await rebuildIndex(projectId);
+            results.push({
+                projectId,
+                count,
+                reason: check.reason
+            });
+            console.log(`[VectorManager] Project ${projectId}: ${count} nodes indexed`);
+        }
+        catch (e) {
+            console.error(`[VectorManager] Failed to rebuild ${projectId}:`, e);
+            results.push({
+                projectId,
+                count: 0,
+                reason: 'error'
+            });
+        }
+    }
+    console.log(`[VectorManager] All indexes rebuilt`);
+    return results;
+}
+/**
+ * 获取所有项目的索引状态
+ */
+export async function getAllIndexStats() {
+    const projects = listAllProjects();
+    const stats = [];
+    for (const projectId of projects) {
+        const status = await needsRebuild(projectId);
+        const indexStats = await vectorCore.getIndexStats(projectId);
+        stats.push({
+            projectId,
+            status,
+            nodeCount: indexStats.count
+        });
+    }
+    return stats;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.6.27",
+  "version": "2.6.29",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",