@ppdocs/mcp 2.6.24 → 2.6.26

package/dist/storage/types.d.ts

@@ -51,9 +51,11 @@ export interface NodeData {
     testRules?: string[];
     reviewRules?: string[];
     codeStyle?: string[];
+    unitTests?: string[];
     createdAt?: string;
     updatedAt?: string;
     lastAccessedAt?: string;
+    lastSyncAt?: string;
     versions?: VersionRecord[];
     bugfixes?: BugfixRecord[];
 }

package/dist/tools/index.js

@@ -1,6 +1,7 @@
 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 }] };
@@ -36,11 +37,27 @@ 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);
+        }
         return wrap(projectId, 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);
+            }
+        }
         return wrap(projectId, success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
     });
     // 3. 更新节点
@@ -64,17 +81,18 @@ export function registerTools(server, projectId, _user) {
             version: z.number(),
             date: z.string(),
             changes: z.string()
-        })).optional().describe('版本记录'),
+        })).optional().describe('版本记录(0.1起始,AI控制递增)'),
         bugfixes: z.array(z.object({
             id: z.string(),
             date: z.string(),
             issue: z.string(),
             solution: z.string(),
             impact: z.string().optional()
-        })).optional().describe('修复记录')
+        })).optional().describe('修复记录'),
+        lastSyncAt: z.string().optional().describe('代码↔图谱最后同步时间(ISO时间戳)')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const { nodeId, tags, relatedFiles, versions, bugfixes, path, ...rest } = decoded;
+        const { nodeId, tags, relatedFiles, versions, bugfixes, path, lastSyncAt, ...rest } = decoded;
         // 根节点必须使用 kg_update_root 更新
         if (nodeId === 'root') {
             return wrap(projectId, '❌ 根节点请使用 kg_update_root 方法更新');
@@ -91,7 +109,18 @@ export function registerTools(server, projectId, _user) {
             updates.bugfixes = bugfixes;
         if (path !== undefined)
             updates.path = path;
+        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);
+            }
+        }
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
     });
     // 3.5 更新根节点 (项目介绍)
@@ -141,22 +170,109 @@ export function registerTools(server, projectId, _user) {
         const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '操作失败');
     });
-    // 5. 搜索节点
-    server.tool('kg_search', '关键词搜索节点,按命中率排序返回。空白关键词[""]返回全部节点', {
-        keywords: z.array(z.string()).describe('关键词列表(OR逻辑),空白[""]返回全部'),
-        limit: z.number().optional().describe('返回数量(默认10)')
+    // 5. 搜索节点 (混合检索: 向量语义 + 关键词)
+    server.tool('kg_search', '智能搜索节点(语义+关键词混合)。支持中英文语义匹配，空白关键词[""]返回全部节点', {
+        keywords: z.array(z.string()).describe('搜索词列表，支持语义匹配(如"登录"可找到auth)'),
+        limit: z.number().optional().describe('返回数量(默认10)'),
+        mode: z.enum(['hybrid', 'keyword', 'semantic']).optional().describe('搜索模式: hybrid=混合(默认), keyword=仅关键词, semantic=仅语义')
     }, async (args) => {
-        const results = await storage.searchNodes(projectId, args.keywords, args.limit || 10);
-        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 || '',
-            hitRate: `${Math.round(r.score)}%`
+        const limit = args.limit || 10;
+        const mode = args.mode || 'hybrid';
+        const query = args.keywords.filter(k => k.trim()).join(' ');
+        // 空白关键词返回全部
+        if (!query) {
+            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 || '',
+                hitRate: `${Math.round(r.score)}%`
+            }));
+            return wrap(projectId, `${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 => ({
+                id: r.node.id,
+                title: r.node.title,
+                tags: r.node.categories || [],
+                status: r.node.status,
+                summary: r.node.summary || '',
+                score: r.score / 100 // 归一化到 0-1
+            }));
+        }
+        // 获取语义结果
+        let semanticResults = [];
+        if (mode === 'hybrid' || mode === 'semantic') {
+            try {
+                semanticResults = await vector.semanticSearch(projectId, query, limit * 2);
+            }
+            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
+                    });
+                }
+            }
+        }
+        // 计算综合得分并排序
+        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 json = JSON.stringify(output, null, 2);
-        return wrap(projectId, `${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
+        return wrap(projectId, `${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
     });
     // 5.5 列出所有标签
     server.tool('kg_list_tags', '获取所有节点使用过的标签列表(去重)', {}, async () => {
@@ -524,4 +640,24 @@ export function registerTools(server, projectId, _user) {
         };
         return wrap(projectId, 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} 个节点`);
+    });
+    // 17. 查看索引状态
+    server.tool('kg_index_stats', '查看向量索引状态', {}, async () => {
+        const stats = await vector.getIndexStats(projectId);
+        return wrap(projectId, JSON.stringify({
+            ...stats,
+            tip: stats.count === 0 ? '索引为空，请运行 kg_build_index 构建索引' : '索引正常'
+        }, null, 2));
+    });
 }

package/dist/vector/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 向量检索服务 - 基于 transformers.js 的语义搜索
+ * @version 0.1
+ */
+interface VectorSearchResult {
+    id: string;
+    title: string;
+    similarity: number;
+}
+/**
+ * 添加或更新节点向量
+ */
+export declare function upsertNode(projectId: string, nodeId: string, title: string, description: string, categories?: string[]): Promise<void>;
+/**
+ * 删除节点向量
+ */
+export declare function removeNode(projectId: string, nodeId: string): Promise<void>;
+/**
+ * 向量语义搜索
+ */
+export declare function semanticSearch(projectId: string, query: string, limit?: number): Promise<VectorSearchResult[]>;
+/**
+ * 批量构建索引 (用于初始化或重建)
+ */
+export declare function buildIndex(projectId: string, nodes: Array<{
+    id: string;
+    title: string;
+    description: string;
+    categories?: string[];
+}>): Promise<number>;
+/**
+ * 检查索引状态
+ */
+export declare function getIndexStats(projectId: string): Promise<{
+    count: number;
+    model: string;
+    dimension: number;
+    loaded: boolean;
+}>;
+/**
+ * 预加载模型 (可选, 用于启动时预热)
+ */
+export declare function preloadModel(): Promise<void>;
+export {};

package/dist/vector/index.js

@@ -0,0 +1,203 @@
+/**
+ * 向量检索服务 - 基于 transformers.js 的语义搜索
+ * @version 0.1
+ */
+import { pipeline } from '@xenova/transformers';
+import * as fs from 'fs';
+import * as path from 'path';
+// 模型配置
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2'; // 23MB, 384维, 中英双语
+const VECTOR_DIM = 384;
+// 单例模式
+let extractor = null;
+let isLoading = false;
+let loadPromise = null;
+// 内存索引 (projectId -> entries)
+const vectorIndex = new Map();
+/**
+ * 加载嵌入模型 (懒加载, 首次调用时下载)
+ */
+async function getExtractor() {
+    if (extractor)
+        return extractor;
+    if (isLoading && loadPromise) {
+        return loadPromise;
+    }
+    isLoading = true;
+    console.log('[Vector] Loading embedding model...');
+    loadPromise = pipeline('feature-extraction', MODEL_NAME, {
+        quantized: true, // 使用量化版本，更小更快
+    });
+    extractor = await loadPromise;
+    isLoading = false;
+    console.log('[Vector] Model loaded successfully');
+    return extractor;
+}
+/**
+ * 文本转向量
+ */
+async function embed(text) {
+    const ext = await getExtractor();
+    const output = await ext(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+}
+/**
+ * 计算余弦相似度
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+}
+/**
+ * 获取索引文件路径
+ */
+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');
+}
+/**
+ * 加载持久化索引
+ */
+async function loadIndex(projectId) {
+    // 先检查内存
+    if (vectorIndex.has(projectId)) {
+        return vectorIndex.get(projectId);
+    }
+    // 尝试从文件加载
+    const indexPath = getIndexPath(projectId);
+    try {
+        if (fs.existsSync(indexPath)) {
+            const data = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+            vectorIndex.set(projectId, data.entries || []);
+            console.log(`[Vector] Loaded ${data.entries?.length || 0} entries from disk`);
+            return data.entries || [];
+        }
+    }
+    catch (e) {
+        console.warn('[Vector] Failed to load index:', e);
+    }
+    vectorIndex.set(projectId, []);
+    return [];
+}
+/**
+ * 保存索引到磁盘
+ */
+async function saveIndex(projectId) {
+    const entries = vectorIndex.get(projectId) || [];
+    const indexPath = getIndexPath(projectId);
+    try {
+        const dir = path.dirname(indexPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(indexPath, JSON.stringify({
+            version: 1,
+            model: MODEL_NAME,
+            dimension: VECTOR_DIM,
+            updatedAt: new Date().toISOString(),
+            entries
+        }, null, 2));
+        console.log(`[Vector] Saved ${entries.length} entries to disk`);
+    }
+    catch (e) {
+        console.warn('[Vector] Failed to save index:', e);
+    }
+}
+/**
+ * 添加或更新节点向量
+ */
+export async function upsertNode(projectId, nodeId, title, description, categories = []) {
+    const entries = await loadIndex(projectId);
+    // 合并可搜索文本
+    const searchableText = `${title} ${description} ${categories.join(' ')}`;
+    const embedding = await embed(searchableText);
+    // 查找现有条目
+    const existingIndex = entries.findIndex(e => e.id === nodeId);
+    const entry = { id: nodeId, title, embedding };
+    if (existingIndex >= 0) {
+        entries[existingIndex] = entry;
+    }
+    else {
+        entries.push(entry);
+    }
+    vectorIndex.set(projectId, entries);
+    await saveIndex(projectId);
+}
+/**
+ * 删除节点向量
+ */
+export async function removeNode(projectId, nodeId) {
+    const entries = await loadIndex(projectId);
+    const filtered = entries.filter(e => e.id !== nodeId);
+    vectorIndex.set(projectId, filtered);
+    await saveIndex(projectId);
+}
+/**
+ * 向量语义搜索
+ */
+export async function semanticSearch(projectId, query, limit = 10) {
+    const entries = await loadIndex(projectId);
+    if (entries.length === 0) {
+        console.log('[Vector] Index is empty, skipping semantic search');
+        return [];
+    }
+    // 查询向量化
+    const queryEmbedding = await embed(query);
+    // 计算相似度
+    const results = entries.map(entry => ({
+        id: entry.id,
+        title: entry.title,
+        similarity: cosineSimilarity(queryEmbedding, entry.embedding)
+    }));
+    // 排序并返回 top-k
+    results.sort((a, b) => b.similarity - a.similarity);
+    return results.slice(0, limit);
+}
+/**
+ * 批量构建索引 (用于初始化或重建)
+ */
+export async function buildIndex(projectId, nodes) {
+    console.log(`[Vector] Building index for ${nodes.length} nodes...`);
+    const entries = [];
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const searchableText = `${node.title} ${node.description} ${(node.categories || []).join(' ')}`;
+        const embedding = await embed(searchableText);
+        entries.push({ id: node.id, title: node.title, embedding });
+        if ((i + 1) % 10 === 0) {
+            console.log(`[Vector] Processed ${i + 1}/${nodes.length}`);
+        }
+    }
+    vectorIndex.set(projectId, entries);
+    await saveIndex(projectId);
+    console.log(`[Vector] Index built with ${entries.length} entries`);
+    return entries.length;
+}
+/**
+ * 检查索引状态
+ */
+export async function getIndexStats(projectId) {
+    const entries = await loadIndex(projectId);
+    return {
+        count: entries.length,
+        model: MODEL_NAME,
+        dimension: VECTOR_DIM,
+        loaded: extractor !== null
+    };
+}
+/**
+ * 预加载模型 (可选, 用于启动时预热)
+ */
+export async function preloadModel() {
+    await getExtractor();
+}

package/package.json

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

package/templates/commands/pp/sync.md

@@ -6,7 +6,9 @@
 | **代码即真理** | 代码与图谱冲突时以 Git 状态为准，强制覆写；禁止保留幽灵节点 |
 | **拓扑优先** | Types → Utils → Services → UI，底层未建不创建上层 |
 | **引用强约束** | relatedFiles 精确锚定物理路径；signature 为代码唯一标识符 |
-| **版本追踪** | 重要变更时自动追加 versions 记录 |
+| **版本追踪** | 版本号以 0.1 起始，每次同步有变动必须更新版本号 (AI控制递增) |
+| **版本一致性** | 同步完成后更新 lastSyncAt，用于检测代码↔图谱是否同步 |
+| **标签完整性** | 每节点 ≥3 个分类标签，标签由AI管理 |
 
 ---
 
@@ -19,19 +21,32 @@
 
 ---
 
-## 标准流程
+## 标准流程 (5步)
 
-### Step 1: 任务初始化 + 变更检测
+### Step 1: 变更检测
 ```
 task_create({ title:"KG同步", goals:["检测变更","更新节点","验证覆盖"], related_nodes:["root"] })
 
 recent模式: git diff --name-only HEAD~3
 all模式: Glob src/**/*.{ts,tsx}
+
+⭐ kg_search([""]) 一次获取全部现有节点 (替代逐个search)
+```
+
+**版本一致性检测** ⭐新增:
 ```
+对每个有 relatedFiles 的节点:
+1. 获取文件 mtime (通过 Bash stat 或 fs.statSync)
+2. 对比节点的 lastSyncAt
+3. mtime > lastSyncAt → 标记为 [OUTDATED] 需同步
+4. lastSyncAt 不存在 → 标记为 [UNTRACKED] 从未同步
+```
+
 **输出变更清单**:
 ```
 ├─ 🟢 [NEW] src/services/Payment.ts (待创建)
 ├─ 🟡 [MOD] src/utils/format.ts (待更新)
+├─ 🟠 [OUTDATED] src/hooks/useAuth.ts (代码已改，图谱未同步)
 └─ 🔴 [DEL] src/legacy/old.ts (待废弃)
 ```
 等待用户确认 `OK`
@@ -39,13 +54,21 @@ all模式: Glob src/**/*.{ts,tsx}
 ### Step 2: 依赖解析 + 拓扑排序
 解析 import 语句 → 构建依赖树 → 拓扑排序确保底层先处理
 
+### Step 2.5: 标签完整性预检 ⭐新增
+```
+kg_list_tags() → 获取现有标签词库 (91个标签)
+检查待处理节点:
+  - 标签 < 3 → 自动补全建议
+  - 使用现有标签词库保持一致性
+```
+
 ### Step 3: 原子化执行
 对每个文件:
 ```
 1. 读取源码 → 提取 signature/imports/comments
-2. kg_search(signature) → 检测现有节点
+2. 从 Step1 缓存查找现有节点 (无需再次kg_search)
 3. 执行写入:
-   - NEW: kg_create_node (全字段 + relatedFiles)
+   - NEW: kg_create_node (全字段 + relatedFiles + ⚠️tags≥3)
    - MOD: kg_update_node (变动字段 + 追加 versions)
    - DEL: kg_update_node(status:"deprecated") 或 kg_delete_node
 4. 每5个文件: task_add_log(progress, "已处理 N/M")
@@ -58,20 +81,43 @@ all模式: Glob src/**/*.{ts,tsx}
 kg_update_node({
   nodeId: "xxx",
   description: "新描述",
+  lastSyncAt: new Date().toISOString(),  // ⭐ 更新同步时间戳
   versions: [...现有versions, {
-    version: 现有max+1,
+    version: 上一版本 + 0.1,  // ⭐ 0.1起始，AI控制递增
     date: "ISO时间",
     changes: "本次变更摘要"
   }]
 })
 ```
 
-### Step 4: 校验 + 交付
+**代码版本注释** (源码文件头部):
+```typescript
+// @version 0.1
+// 或 JSDoc 格式
+/**
+ * @version 0.1
+ */
 ```
-1. 统计覆盖率
+
+**同步时间戳规则** ⭐新增:
+```
+NEW: kg_create_node 后自动设置 lastSyncAt = now
+MOD: kg_update_node 时必须传 lastSyncAt = now
+OUTDATED: 仅更新 lastSyncAt (无需改 description/versions)
+```
+
+### Step 4: 关系校验 ⭐优化
+```
+1. kg_read_node(nodeId, depth=1) 批量校验上下游关系
 2. kg_list_nodes({maxEdges:0}) 检查孤立节点
 3. 检查断链 (dependencies 指向不存在的 signature)
-4. task_complete({
+```
+
+### Step 5: 交付报告 ⭐增强
+```
+1. 统计覆盖率
+2. kg_list_tags() 输出标签分布
+3. task_complete({
      summary: "同步完成...",
      difficulties: ["遇到的困难"],
      solutions: ["采用的方案"],
@@ -87,19 +133,36 @@ kg_update_node({
 | 更新节点 | 12 | ✅ |
 | 废弃节点 | 1 | ⚠️ |
 | 版本追加 | 8 | ✅ |
+| 标签补全 | 5 | ✅ |
+| 同步时间戳更新 | 15 | ✅ |
+| 版本一致率 | 100% | 🟢 |
 | 覆盖率 | 98.5% | 🟢 |
+| 标签总数 | 91 | 📊 |
 
 建议: git add . && git commit -m "chore: sync kg"
 ```
 
 ---
 
+## MCP 工具速查 ⭐新增
+
+| 工具 | 用途 | 示例 |
+|:---|:---|:---|
+| `kg_search([""])` | 获取全部节点 | 变更检测时一次拉取 |
+| `kg_list_tags` | 标签词库 | 保持标签一致性 |
+| `kg_read_node(id, depth=1)` | 含关系的详情 | 校验上下游 |
+| `kg_list_nodes({maxEdges:0})` | 孤立节点 | 发现断链 |
+| `kg_list_nodes` | 含summary列表 | 覆盖率报告 |
+
+---
+
 ## 异常处理
 | 场景 | 反应 |
 |:---|:---|
 | git status 不干净 | 警告 + 询问是否强制继续 |
 | kg_search 返回多个同名节点 | 暂停，列出候选请求人工绑定 |
 | 文件解析失败 | task_add_log(issue) + 标记 Skipped，不中断队列 |
+| 标签不足3个 | 自动从词库补全，记录日志 |
 
 ---
 
@@ -110,3 +173,6 @@ kg_update_node({
 | 文件路径 | relatedFiles | 相对项目根 (如 `src/utils/auth.ts`) |
 | export 函数/类 | signature | 标识符名 (如 `AuthService`) |
 | JSDoc/Comments | description | 优先注释，无则代码生成摘要 |
+| 功能分类 | tags | ≥3个，使用 kg_list_tags 词库 |
+| 同步时间 | lastSyncAt | 每次同步完成时设为当前 ISO 时间戳 |
+| `// @version 0.1` | versions[].version | 代码文件头注释，0.1起始 |

package/dist/storage/fileStorage.d.ts

@@ -1,41 +0,0 @@
-import type { NodeData, Project, SearchResult, PathResult, BugfixRecord } from './types.js';
-export declare function listProjects(): Promise<Project[]>;
-export declare function ensureProject(projectId: string): Promise<Project>;
-export declare function createProject(name: string): Promise<Project>;
-export declare function getChangeMarkerTime(projectId: string): Promise<number>;
-export declare function listNodes(projectId: string): Promise<NodeData[]>;
-export declare function getNode(projectId: string, nodeId: string): Promise<NodeData | null>;
-type CreateNodeInput = Omit<NodeData, 'id' | 'x' | 'y'> & {
-    x?: number;
-    y?: number;
-};
-export declare function createNode(projectId: string, node: CreateNodeInput): Promise<NodeData>;
-export declare function updateNode(projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
-export declare function deleteNode(projectId: string, nodeId: string): Promise<boolean>;
-export declare function lockNode(projectId: string, nodeId: string, locked: boolean): Promise<NodeData | null>;
-export declare function searchNodes(projectId: string, keywords: string[], limit?: number): Promise<SearchResult[]>;
-export declare function findPath(projectId: string, startId: string, endId: string): Promise<PathResult | null>;
-export interface OrphanNode {
-    id: string;
-    title: string;
-    type: string;
-    status: string;
-}
-export interface RelationNode {
-    nodeId: string;
-    title: string;
-    description: string;
-    edgeType: string;
-    direction: 'outgoing' | 'incoming';
-}
-/** 查找孤立节点（没有任何边连接的节点） */
-export declare function findOrphans(projectId: string): Promise<OrphanNode[]>;
-/** 查询节点关系网（所有直接连接的节点） */
-export declare function getRelations(projectId: string, nodeId: string): Promise<RelationNode[]>;
-/** 添加错误修复记录到节点 */
-export declare function addBugfix(projectId: string, nodeId: string, bugfix: {
-    issue: string;
-    solution: string;
-    impact?: string;
-}): Promise<BugfixRecord | null>;
-export {};

package/dist/storage/fileStorage.js

@@ -1,458 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { homedir } from 'os';
-import lockfile from 'proper-lockfile';
-const DATA_DIR = path.join(homedir(), '.ppdocs');
-// 文件锁配置
-const LOCK_OPTIONS = {
-    stale: 10000, // 锁超时 10秒 (防止死锁)
-    retries: {
-        retries: 5, // 最多重试 5 次
-        minTimeout: 100, // 最小等待 100ms
-        maxTimeout: 500 // 最大等待 500ms
-    }
-};
-async function ensureDir(dir) {
-    await fs.mkdir(dir, { recursive: true });
-}
-async function readJSON(filePath, defaultValue) {
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch {
-        return defaultValue;
-    }
-}
-// 带文件锁的写入 (防止并发数据丢失)
-async function writeJSON(filePath, data) {
-    await ensureDir(path.dirname(filePath));
-    // 确保文件存在 (lockfile 需要文件存在)
-    try {
-        await fs.access(filePath);
-    }
-    catch {
-        await fs.writeFile(filePath, '{}');
-    }
-    let release = null;
-    try {
-        release = await lockfile.lock(filePath, LOCK_OPTIONS);
-        await fs.writeFile(filePath, JSON.stringify(data, null, 2));
-    }
-    finally {
-        if (release)
-            await release();
-    }
-}
-// ============ 项目操作 ============
-export async function listProjects() {
-    const filePath = path.join(DATA_DIR, 'projects.json');
-    return readJSON(filePath, []);
-}
-export async function ensureProject(projectId) {
-    const projects = await listProjects();
-    const existing = projects.find(p => p.id === projectId);
-    if (existing)
-        return existing;
-    // 创建新项目
-    const project = { id: projectId, name: projectId, updatedAt: new Date().toISOString() };
-    projects.push(project);
-    await writeJSON(path.join(DATA_DIR, 'projects.json'), projects);
-    // 创建根节点
-    const rootNode = {
-        id: 'root',
-        title: projectId,
-        type: 'intro',
-        status: 'complete',
-        x: 0, y: 0, // 根节点为坐标原点
-        locked: true,
-        isOrigin: true,
-        signature: projectId,
-        categories: ['logic'], // 与 Frontend/Rust 统一
-        description: `# ${projectId}\n\n项目根节点`,
-        dependencies: []
-    };
-    const meta = { projectId, projectName: projectId, updatedAt: project.updatedAt, edges: [] };
-    const projectDir = path.join(DATA_DIR, 'projects', projectId);
-    await writeJSON(path.join(projectDir, 'meta.json'), meta);
-    await writeJSON(path.join(projectDir, 'nodes', 'root.json'), rootNode);
-    return project;
-}
-export async function createProject(name) {
-    const id = `project-${Date.now()}`;
-    return ensureProject(id);
-}
-// 自动计算边 (基于 dependencies.name 匹配 signature)
-function computeAutoEdges(nodes) {
-    const signatureList = [];
-    nodes.forEach(n => {
-        if (n.signature) {
-            signatureList.push({ sig: n.signature.toLowerCase(), id: n.id });
-        }
-    });
-    const edges = [];
-    const edgeSet = new Set();
-    nodes.forEach(node => {
-        node.dependencies?.forEach(dep => {
-            const depName = dep.name.toLowerCase();
-            const match = signatureList.find(s => s.sig.startsWith(depName));
-            if (match && match.id !== node.id) {
-                const key = `${node.id}->${match.id}`;
-                if (!edgeSet.has(key)) {
-                    edgeSet.add(key);
-                    edges.push({ source: node.id, target: match.id, type: 'uses' });
-                }
-            }
-        });
-    });
-    return edges;
-}
-function calculateAutoPosition(nodes, dependencies) {
-    const root = nodes.find(n => n.isOrigin);
-    if (!root)
-        return { x: 200, y: 200 };
-    // 无依赖 → 随机环绕 root
-    if (!dependencies?.length) {
-        const angle = Math.random() * 2 * Math.PI;
-        const radius = 200 + Math.random() * 100;
-        return {
-            x: Math.round(root.x + Math.cos(angle) * radius),
-            y: Math.round(root.y + Math.sin(angle) * radius)
-        };
-    }
-    // 找距 root 最远的依赖节点作为 parent
-    let parent = null;
-    let maxDist = -1;
-    for (const dep of dependencies) {
-        const depName = dep.name.toLowerCase();
-        const match = nodes.find(n => n.signature?.toLowerCase().startsWith(depName));
-        if (match) {
-            const dist = Math.hypot(match.x - root.x, match.y - root.y);
-            if (dist > maxDist) {
-                maxDist = dist;
-                parent = match;
-            }
-        }
-    }
-    // 无匹配依赖 → 随机环绕 root
-    if (!parent) {
-        const angle = Math.random() * 2 * Math.PI;
-        const radius = 200 + Math.random() * 100;
-        return {
-            x: Math.round(root.x + Math.cos(angle) * radius),
-            y: Math.round(root.y + Math.sin(angle) * radius)
-        };
-    }
-    // 计算方向向量 (root → parent)
-    let dx = parent.x - root.x;
-    let dy = parent.y - root.y;
-    const len = Math.hypot(dx, dy);
-    if (len < 10) {
-        const angle = Math.random() * 2 * Math.PI;
-        dx = Math.cos(angle);
-        dy = Math.sin(angle);
-    }
-    else {
-        dx /= len;
-        dy /= len;
-    }
-    // 新位置 = parent + 方向 * 150 (加小随机偏移防重叠)
-    const offset = 150 + (Math.random() - 0.5) * 30;
-    const angleOffset = (Math.random() - 0.5) * 0.3;
-    const cos = Math.cos(angleOffset), sin = Math.sin(angleOffset);
-    return {
-        x: Math.round(parent.x + (dx * cos - dy * sin) * offset),
-        y: Math.round(parent.y + (dx * sin + dy * cos) * offset)
-    };
-}
-// ============ 节点操作 ============
-function getNodePath(projectId, nodeId) {
-    return path.join(DATA_DIR, 'projects', projectId, 'nodes', `${nodeId}.json`);
-}
-function getMetaPath(projectId) {
-    return path.join(DATA_DIR, 'projects', projectId, 'meta.json');
-}
-function getChangeMarkerPath(projectId) {
-    return path.join(DATA_DIR, 'projects', projectId, '.changed');
-}
-// 更新变更标记 (前端用于检测 MCP 变更)
-async function touchChangeMarker(projectId) {
-    const markerPath = getChangeMarkerPath(projectId);
-    await ensureDir(path.dirname(markerPath));
-    await fs.writeFile(markerPath, Date.now().toString());
-}
-// 获取变更标记时间戳 (前端轮询用)
-export async function getChangeMarkerTime(projectId) {
-    const markerPath = getChangeMarkerPath(projectId);
-    try {
-        const content = await fs.readFile(markerPath, 'utf-8');
-        return parseInt(content, 10) || 0;
-    }
-    catch {
-        return 0;
-    }
-}
-// 更新节点的最后访问时间 (触发前端发光效果)
-async function touchNode(projectId, nodeId) {
-    const nodePath = getNodePath(projectId, nodeId);
-    try {
-        const node = await readJSON(nodePath, null);
-        if (node) {
-            node.lastAccessedAt = new Date().toISOString();
-            await writeJSON(nodePath, node);
-        }
-    }
-    catch { /* ignore */ }
-}
-// 批量更新访问时间 (同时更新变更标记)
-async function touchNodes(projectId, nodeIds) {
-    await Promise.all(nodeIds.map(id => touchNode(projectId, id)));
-    await touchChangeMarker(projectId);
-}
-export async function listNodes(projectId) {
-    const nodesDir = path.join(DATA_DIR, 'projects', projectId, 'nodes');
-    try {
-        const files = await fs.readdir(nodesDir);
-        const nodes = [];
-        for (const file of files) {
-            if (file.endsWith('.json')) {
-                const node = await readJSON(path.join(nodesDir, file), null);
-                if (node)
-                    nodes.push(node);
-            }
-        }
-        return nodes;
-    }
-    catch {
-        return [];
-    }
-}
-export async function getNode(projectId, nodeId) {
-    return readJSON(getNodePath(projectId, nodeId), null);
-}
-export async function createNode(projectId, node) {
-    const id = `node-${Date.now()}`;
-    const now = new Date().toISOString();
-    // 自动布局: 未指定位置时计算
-    let x = node.x;
-    let y = node.y;
-    if (x === undefined || y === undefined) {
-        const nodes = await listNodes(projectId);
-        const pos = calculateAutoPosition(nodes, node.dependencies || []);
-        x = pos.x;
-        y = pos.y;
-    }
-    const fullNode = {
-        ...node,
-        id,
-        x,
-        y,
-        updatedAt: now,
-        versions: [{ version: 1, date: now, changes: '初始创建' }],
-        bugfixes: []
-    };
-    await writeJSON(getNodePath(projectId, id), fullNode);
-    await touchChangeMarker(projectId);
-    return fullNode;
-}
-export async function updateNode(projectId, nodeId, updates) {
-    const node = await readJSON(getNodePath(projectId, nodeId), null);
-    if (!node)
-        return null;
-    if (node.locked && !('locked' in updates))
-        return null; // 锁定节点只能改locked
-    const now = new Date().toISOString();
-    // 自动检测变更字段
-    const changes = [];
-    if (updates.title !== undefined && updates.title !== node.title)
-        changes.push('标题');
-    if (updates.description !== undefined && updates.description !== node.description)
-        changes.push('描述');
-    if (updates.status !== undefined && updates.status !== node.status)
-        changes.push('状态');
-    if (updates.categories !== undefined && JSON.stringify(updates.categories) !== JSON.stringify(node.categories))
-        changes.push('分类');
-    if (updates.dependencies !== undefined && JSON.stringify(updates.dependencies) !== JSON.stringify(node.dependencies))
-        changes.push('依赖');
-    if (updates.signature !== undefined && updates.signature !== node.signature)
-        changes.push('签名');
-    // 合并更新
-    const updated = { ...node, ...updates, updatedAt: now };
-    // 有变更时自动追加版本记录
-    if (changes.length > 0) {
-        const currentVersion = node.versions?.[0]?.version || 0;
-        const newVersion = {
-            version: currentVersion + 1,
-            date: now,
-            changes: `更新: ${changes.join(', ')}`
-        };
-        updated.versions = [newVersion, ...(node.versions || [])].slice(0, 10);
-    }
-    await writeJSON(getNodePath(projectId, nodeId), updated);
-    await touchChangeMarker(projectId);
-    return updated;
-}
-export async function deleteNode(projectId, nodeId) {
-    const node = await getNode(projectId, nodeId);
-    if (!node || node.isOrigin || node.locked)
-        return false;
-    try {
-        await fs.unlink(getNodePath(projectId, nodeId));
-        await touchChangeMarker(projectId);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export async function lockNode(projectId, nodeId, locked) {
-    const node = await getNode(projectId, nodeId);
-    if (!node || node.isOrigin)
-        return null;
-    const updated = { ...node, locked };
-    await writeJSON(getNodePath(projectId, nodeId), updated);
-    await touchChangeMarker(projectId);
-    return updated;
-}
-// ============ 搜索 ============
-export async function searchNodes(projectId, keywords, limit = 20) {
-    const nodes = await listNodes(projectId);
-    const results = [];
-    for (const node of nodes) {
-        let score = 0;
-        const matches = [];
-        const lowerKeywords = keywords.map(k => k.toLowerCase());
-        for (const keyword of lowerKeywords) {
-            if (node.title?.toLowerCase().includes(keyword)) {
-                score += 3;
-                matches.push(`title: ${node.title}`);
-            }
-            if (node.signature?.toLowerCase().includes(keyword)) {
-                score += 2;
-                matches.push(`signature: ${node.signature}`);
-            }
-            if (node.categories?.some(t => t.toLowerCase().includes(keyword))) {
-                score += 2.5;
-                matches.push(`categories: ${node.categories.join(', ')}`);
-            }
-            if (node.description?.toLowerCase().includes(keyword)) {
-                score += 1;
-                matches.push('description');
-            }
-        }
-        if (score > 0)
-            results.push({ node, score, matches: [...new Set(matches)] });
-    }
-    const finalResults = results.sort((a, b) => b.score - a.score).slice(0, limit);
-    // 触发发光效果
-    await touchNodes(projectId, finalResults.map(r => r.node.id));
-    return finalResults;
-}
-// ============ 路径查找 (BFS) ============
-export async function findPath(projectId, startId, endId) {
-    const nodes = await listNodes(projectId);
-    const edges = computeAutoEdges(nodes);
-    const nodeMap = new Map(nodes.map(n => [n.id, n]));
-    if (!nodeMap.has(startId) || !nodeMap.has(endId))
-        return null;
-    // 建立邻接表 (双向)
-    const adj = new Map();
-    for (const edge of edges) {
-        if (!adj.has(edge.source))
-            adj.set(edge.source, []);
-        if (!adj.has(edge.target))
-            adj.set(edge.target, []);
-        adj.get(edge.source).push({ nodeId: edge.target, edge });
-        adj.get(edge.target).push({ nodeId: edge.source, edge });
-    }
-    // BFS
-    const visited = new Set([startId]);
-    const queue = [{ nodeId: startId, path: [startId], edges: [] }];
-    while (queue.length > 0) {
-        const { nodeId, path, edges: pathEdges } = queue.shift();
-        if (nodeId === endId) {
-            // 触发发光效果
-            await touchNodes(projectId, path);
-            return { path: path.map(id => nodeMap.get(id)), edges: pathEdges };
-        }
-        for (const { nodeId: nextId, edge } of adj.get(nodeId) || []) {
-            if (!visited.has(nextId)) {
-                visited.add(nextId);
-                queue.push({ nodeId: nextId, path: [...path, nextId], edges: [...pathEdges, edge] });
-            }
-        }
-    }
-    return null;
-}
-/** 查找孤立节点（没有任何边连接的节点） */
-export async function findOrphans(projectId) {
-    const nodes = await listNodes(projectId);
-    const edges = computeAutoEdges(nodes);
-    // 收集所有有边连接的节点ID
-    const connected = new Set();
-    for (const edge of edges) {
-        connected.add(edge.source);
-        connected.add(edge.target);
-    }
-    // 过滤出孤立节点
-    return nodes
-        .filter(n => !connected.has(n.id))
-        .map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status }));
-}
-/** 查询节点关系网（所有直接连接的节点） */
-export async function getRelations(projectId, nodeId) {
-    const nodes = await listNodes(projectId);
-    const edges = computeAutoEdges(nodes);
-    const nodeMap = new Map(nodes.map(n => [n.id, n]));
-    const relations = [];
-    for (const edge of edges) {
-        let relatedId = null;
-        let direction = null;
-        if (edge.source === nodeId) {
-            relatedId = edge.target;
-            direction = 'outgoing';
-        }
-        else if (edge.target === nodeId) {
-            relatedId = edge.source;
-            direction = 'incoming';
-        }
-        if (relatedId && direction) {
-            const node = nodeMap.get(relatedId);
-            if (node) {
-                relations.push({
-                    nodeId: relatedId,
-                    title: node.title,
-                    description: node.description.slice(0, 100),
-                    edgeType: edge.type,
-                    direction
-                });
-            }
-        }
-    }
-    // 触发发光效果 (当前节点 + 所有关联节点)
-    const touchList = [nodeId, ...relations.map(r => r.nodeId)];
-    await touchNodes(projectId, touchList);
-    return relations;
-}
-// ============ 错误修复记录 ============
-/** 添加错误修复记录到节点 */
-export async function addBugfix(projectId, nodeId, bugfix) {
-    const node = await getNode(projectId, nodeId);
-    if (!node || node.locked)
-        return null;
-    const newBugfix = {
-        id: `bug-${Date.now()}`,
-        date: new Date().toISOString(),
-        issue: bugfix.issue,
-        solution: bugfix.solution,
-        impact: bugfix.impact
-    };
-    const updated = {
-        ...node,
-        bugfixes: [newBugfix, ...(node.bugfixes || [])].slice(0, 20), // 保留最近 20 条
-        updatedAt: new Date().toISOString()
-    };
-    await writeJSON(getNodePath(projectId, nodeId), updated);
-    await touchChangeMarker(projectId);
-    return newBugfix;
-}