@ppdocs/mcp 2.7.1 → 2.8.0

package/dist/tools/index.js

@@ -1,105 +1,75 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-import { decodeUnicodeEscapes, decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
-// 向量搜索已迁移至 Tauri 后端，通过 HTTP API 调用
-import { wrap, fetchRelations, formatNodeMarkdown, formatRelationsMarkdown, buildDirectoryTree, formatTreeText, countTreeNodes } from './helpers.js';
+import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
+import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs } from './helpers.js';
 export function registerTools(server, projectId, _user) {
-    // 1. 创建节点
-    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍。⚠️ tags至少提供3个分类标签', {
-        title: z.string().describe('节点标题'),
-        type: z.enum(['logic', 'data', 'intro']).describe('节点类型(logic/data/intro)'),
-        description: z.string().describe('Markdown描述(用Mermaid流程图+表格,禁止纯文字)'),
-        path: z.string().min(1).describe('目录路径(必填,如"/前端/组件")'),
-        tags: z.array(z.string()).min(3).describe('⚠️ 分类标签(必填,至少3个)'),
-        signature: z.string().optional().describe('唯一签名(用于依赖匹配,默认=title)'),
-        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
-        dependencies: z.array(z.object({
-            name: z.string().describe('目标节点的signature'),
-            description: z.string().describe('依赖说明')
-        })).optional().describe('依赖列表(自动生成连线)'),
-        relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组，如 ["src/auth.ts"]')
+    // ===================== 文档管理 =====================
+    // 1. 创建文档
+    server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
+        path: z.string().min(1).describe('完整文档路径(如"/前端/组件/Modal")'),
+        summary: z.string().optional().describe('一句话简介'),
+        content: z.string().describe('Markdown内容')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const node = await storage.createNode(projectId, {
-            title: decoded.title,
-            type: decoded.type,
-            status: 'incomplete',
-            description: decoded.description || '',
+        const doc = await storage.createDoc(projectId, decoded.path, {
             summary: decoded.summary || '',
-            // x, y 不传递，由 httpClient 智能计算位置
-            locked: false,
-            signature: decoded.signature || decoded.title,
-            categories: decoded.tags,
-            path: decoded.path,
-            dependencies: decoded.dependencies || [],
-            relatedFiles: decoded.relatedFiles || []
+            content: decoded.content,
+            versions: [{
+                    version: 0.1,
+                    date: new Date().toISOString(),
+                    changes: '初始创建'
+                }],
+            bugfixes: []
         });
-        // 向量索引由 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);
-        // 向量索引由 Tauri 后端自动维护，MCP 不再手动删除
-        return wrap(success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
-    });
-    // 3. 更新节点
-    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)。⚠️ 更新tags时至少提供3个分类标签', {
-        nodeId: z.string().describe('节点ID'),
-        title: z.string().optional().describe('新标题'),
-        signature: z.string().optional().describe('新签名'),
-        description: z.string().optional().describe('新描述(Markdown)'),
-        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
-        path: z.string().optional().describe('目录路径(如"/前端/组件")'),
-        x: z.number().optional().describe('X坐标'),
-        y: z.number().optional().describe('Y坐标'),
-        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态'),
-        tags: z.array(z.string()).min(3).optional().describe('⚠️ 分类标签(更新时至少3个)'),
-        dependencies: z.array(z.object({
-            name: z.string(),
-            description: z.string()
-        })).optional().describe('依赖列表'),
-        relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组'),
+        return wrap(`✅ 文档已创建: ${decoded.path}\n\n${JSON.stringify(doc, null, 2)}`);
+    });
+    // 2. 删除文档
+    server.tool('kg_delete_node', '删除文档(根文档不可删除)', { nodeId: z.string().describe('文档路径') }, async (args) => {
+        const success = await storage.deleteDoc(projectId, args.nodeId);
+        return wrap(success ? '删除成功' : '删除失败(文档不存在或是根文档)');
+    });
+    // 3. 更新文档
+    server.tool('kg_update_node', '更新文档内容', {
+        nodeId: z.string().describe('文档路径'),
+        summary: z.string().optional().describe('一句话简介'),
+        content: z.string().optional().describe('Markdown内容'),
         versions: z.array(z.object({
             version: z.number(),
             date: z.string(),
             changes: z.string()
-        })).optional().describe('版本记录(0.1起始,AI控制递增)'),
+        })).optional().describe('版本记录'),
         bugfixes: z.array(z.object({
-            id: z.string(),
             date: z.string(),
             issue: z.string(),
-            solution: z.string(),
-            impact: z.string().optional()
-        })).optional().describe('修复记录'),
-        lastSyncAt: z.string().optional().describe('代码↔图谱最后同步时间(ISO时间戳)')
+            solution: z.string()
+        })).optional().describe('修复记录')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const { nodeId, tags, relatedFiles, versions, bugfixes, path, lastSyncAt, ...rest } = decoded;
-        // 根节点必须使用 kg_update_root 更新
-        if (nodeId === 'root') {
-            return wrap('❌ 根节点请使用 kg_update_root 方法更新');
-        }
-        // API 参数转换
-        let updates = { ...rest };
-        if (tags !== undefined)
-            updates.categories = tags;
-        if (relatedFiles !== undefined)
-            updates.relatedFiles = relatedFiles;
+        const { nodeId, summary, content, versions, bugfixes } = decoded;
+        // 根文档必须使用 kg_update_root 更新
+        if (nodeId === '/' || nodeId === '_root') {
+            return wrap('❌ 根文档请使用 kg_update_root 方法更新');
+        }
+        // 获取现有文档
+        const existing = await storage.getDoc(projectId, nodeId);
+        if (!existing) {
+            return wrap('更新失败(文档不存在)');
+        }
+        // 构建更新内容
+        const updates = {};
+        if (summary !== undefined)
+            updates.summary = summary;
+        if (content !== undefined)
+            updates.content = content;
         if (versions !== undefined)
             updates.versions = versions;
         if (bugfixes !== undefined)
             updates.bugfixes = bugfixes;
-        if (path !== undefined)
-            updates.path = path;
-        if (lastSyncAt !== undefined)
-            updates.lastSyncAt = lastSyncAt;
-        const node = await storage.updateNode(projectId, nodeId, updates);
-        // 向量索引由 Tauri 后端自动维护，MCP 不再手动更新
-        return wrap(node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
+        const doc = await storage.updateDoc(projectId, nodeId, updates);
+        return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
     });
-    // 3.5 更新根节点 (项目介绍)
-    server.tool('kg_update_root', '更新项目介绍(根节点描述，锁定时不可更新)', {
+    // 3.5 更新根文档 (项目介绍)
+    server.tool('kg_update_root', '更新项目介绍(根文档)', {
         title: z.string().optional().describe('项目标题'),
         description: z.string().optional().describe('项目介绍(Markdown)')
     }, async (args) => {
@@ -107,13 +77,19 @@ export function registerTools(server, projectId, _user) {
         if (decoded.title === undefined && decoded.description === undefined) {
             return wrap('❌ 请至少提供 title 或 description');
         }
-        const node = await storage.updateRoot(projectId, {
-            title: decoded.title,
-            description: decoded.description
-        });
-        return wrap(node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
+        const existing = await storage.getDoc(projectId, '/');
+        if (!existing) {
+            return wrap('更新失败(根文档不存在)');
+        }
+        const updates = {};
+        if (decoded.title !== undefined)
+            updates.summary = decoded.title;
+        if (decoded.description !== undefined)
+            updates.content = decoded.description;
+        const doc = await storage.updateDoc(projectId, '/', updates);
+        return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
     });
-    // 3.6 获取项目规则 (独立方法，按需调用)
+    // 3.6 获取项目规则
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
         ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests']).optional()
             .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部')
@@ -125,7 +101,7 @@ export function registerTools(server, projectId, _user) {
         }
         return { content: [{ type: 'text', text: rules }] };
     });
-    // 3.7 保存项目规则 (独立存储)
+    // 3.7 保存项目规则
     server.tool('kg_save_rules', '保存单个类型的项目规则(独立文件存储)', {
         ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests'])
             .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则'),
@@ -138,274 +114,121 @@ export function registerTools(server, projectId, _user) {
         }
         return wrap(`✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
     });
-    // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
-    server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
-        nodeId: z.string().describe('节点ID')
+    // 5. 读取单个文档详情
+    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)', {
+        nodeId: z.string().describe('文档路径')
     }, async (args) => {
-        const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
-        return wrap(node ? JSON.stringify(node, null, 2) : '操作失败');
-    });
-    // 5. 搜索节点 (混合检索: 向量语义 + 关键词)
-    server.tool('kg_search', '智能搜索节点(语义+关键词混合)。支持中英文语义匹配，空白关键词[""]返回全部节点', {
-        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 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(`${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
+        const doc = await storage.getDoc(projectId, args.nodeId);
+        if (!doc) {
+            return wrap('文档不存在');
         }
-        // 调用 Tauri 后端混合搜索 API
+        // 格式化文档
+        const lines = formatDocMarkdown(doc, args.nodeId);
+        return wrap(lines.join('\n'));
+    });
+    // 10. 获取知识库树状图
+    server.tool('kg_get_tree', '获取知识库的目录树结构(按 path 分组)', {}, async () => {
         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 tree = await storage.getTree(projectId);
+            if (tree && tree.length > 0) {
+                const treeText = formatTreeText(tree);
+                const docCount = countTreeDocs(tree);
+                return wrap(`共 ${docCount} 个文档\n\n${treeText}`);
             }
-            const json = JSON.stringify(output, null, 2);
-            return wrap(`${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n🔍 搜索模式: ${mode}`);
+            return wrap('知识库为空');
         }
         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 || '',
-                hitRate: `${Math.round(r.score)}%`
-            }));
-            return wrap(`${JSON.stringify(output, null, 2)}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情\n⚠️ 语义搜索不可用，已降级为关键词搜索`);
-        }
-    });
-    // 6. 路径查找
-    server.tool('kg_find_path', '查找两节点间的依赖路径', {
-        startId: z.string().describe('起点节点ID'),
-        endId: z.string().describe('终点节点ID')
-    }, async (args) => {
-        const result = await storage.findPath(projectId, args.startId, args.endId);
-        if (!result)
-            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(JSON.stringify(output, null, 2));
-    });
-    // 7. 列出节点 (支持过滤)
-    server.tool('kg_list_nodes', '列出节点，支持按状态/连接数过滤。maxEdges=0 可查孤立节点', {
-        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态过滤'),
-        minEdges: z.number().optional().describe('最小连接数(含)'),
-        maxEdges: z.number().optional().describe('最大连接数(含)，0=孤立节点')
-    }, async (args) => {
-        const filter = (args.status || args.minEdges !== undefined || args.maxEdges !== undefined)
-            ? { status: args.status, minEdges: args.minEdges, maxEdges: args.maxEdges }
-            : 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(JSON.stringify(output, null, 2));
-    });
-    // 8. 查询节点关系网 (支持多层)
-    server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)，支持多层查询', {
-        nodeId: z.string().describe('节点ID'),
-        depth: z.number().min(1).max(3).optional().describe('查询层数(默认1，最大3)')
-    }, async (args) => {
-        const maxDepth = Math.min(args.depth || 1, 3);
-        const { outgoing, incoming } = await fetchRelations(projectId, args.nodeId, maxDepth);
-        if (outgoing.length === 0 && incoming.length === 0) {
-            return wrap('该节点没有任何连线');
+            return wrap(JSON.stringify({
+                error: '无法获取知识库结构',
+                message: String(e),
+                tip: '请确保软件端已启动'
+            }, null, 2));
         }
-        return wrap(JSON.stringify({ outgoing, incoming }, null, 2));
     });
-    // 9. 读取单个节点详情
-    server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)，可选包含上下游关系', {
-        nodeId: z.string().describe('节点ID'),
-        depth: z.number().min(0).max(3).optional().describe('关系查询层数(0=不含关系，1-3=含上下游关系，默认0)')
-    }, async (args) => {
-        const node = await storage.getNode(projectId, args.nodeId);
-        if (!node) {
-            return wrap('节点不存在');
-        }
-        // 格式化节点基础信息
-        const lines = formatNodeMarkdown(node);
-        // 上下游关系 (depth > 0 时获取)
-        const depth = args.depth || 0;
-        if (depth > 0) {
-            const { outgoing, incoming } = await fetchRelations(projectId, args.nodeId, depth);
-            lines.push(...formatRelationsMarkdown(outgoing, incoming));
-        }
-        return wrap(lines.join('\n'));
-    });
-    // 10. 获取知识库树状图
-    server.tool('kg_get_tree', '获取知识库的目录树结构(按 path 分组)', {}, async () => {
-        const nodes = await storage.listNodes(projectId);
-        const tree = buildDirectoryTree(nodes);
-        const treeText = formatTreeText(tree);
-        const nodeCount = countTreeNodes(tree);
-        return wrap(`共 ${nodeCount} 个节点\n\n${treeText}`);
-    });
-    // ===================== 任务管理工具 =====================
-    // 11. 创建任务
-    server.tool('task_create', '创建开发任务,记录目标和关联节点', {
+    // ===================== 任务管理 =====================
+    // 7. 创建任务
+    server.tool('task_create', '创建开发任务', {
         title: z.string().describe('任务标题'),
         description: z.string().describe('任务描述(Markdown)'),
-        goals: z.array(z.string()).optional().describe('目标清单'),
-        related_nodes: z.array(z.string()).optional().describe('关联节点ID')
+        goals: z.array(z.string()).optional().describe('目标清单')
     }, async (args) => {
-        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
         const decoded = decodeObjectStrings(args);
         const task = await storage.createTask(projectId, {
             title: decoded.title,
             description: decoded.description,
-            goals: decoded.goals || [],
-            related_nodes: decoded.related_nodes
+            goals: decoded.goals || []
         }, _user);
         return wrap(JSON.stringify(task, null, 2));
     });
-    // 11. 列出任务
-    server.tool('task_list', '列出任务(active=进行中,archived=已归档)', {
-        status: z.enum(['active', 'archived']).optional().describe('状态筛选')
-    }, async (args) => {
-        const tasks = await storage.listTasks(projectId, args.status);
-        const output = tasks.map(t => ({
+    // 8. 读取任务
+    server.tool('task_get', '读取任务详情(按名字搜索，支持当前任务和历史任务)', {
+        title: z.string().describe('任务名称(模糊匹配)'),
+        status: z.enum(['active', 'archived', 'all']).optional().describe('状态筛选: active=进行中, archived=已归档, all=全部(默认)')
+    }, async (args) => {
+        const status = args.status || 'all';
+        const searchTitle = args.title.toLowerCase();
+        // 获取任务列表
+        let tasks;
+        if (status === 'all') {
+            const [active, archived] = await Promise.all([
+                storage.listTasks(projectId, 'active'),
+                storage.listTasks(projectId, 'archived')
+            ]);
+            tasks = [...active, ...archived];
+        }
+        else {
+            tasks = await storage.listTasks(projectId, status);
+        }
+        // 按名字模糊匹配
+        const matched = tasks.filter(t => t.title.toLowerCase().includes(searchTitle));
+        if (matched.length === 0) {
+            return wrap(`未找到匹配 "${args.title}" 的任务`);
+        }
+        // 如果只有一个匹配，返回完整详情
+        if (matched.length === 1) {
+            const task = await storage.getTask(projectId, matched[0].id);
+            return wrap(task ? JSON.stringify(task, null, 2) : '任务详情获取失败');
+        }
+        // 多个匹配，返回列表让用户选择
+        const list = matched.map(t => ({
             id: t.id,
             title: t.title,
             status: t.status,
             creator: t.creator,
-            created_at: t.created_at,
-            last_log: t.last_log
+            created_at: t.created_at
         }));
-        return wrap(JSON.stringify(output, null, 2));
-    });
-    // 12. 获取任务详情
-    server.tool('task_get', '获取任务完整信息(含全部日志)', {
-        taskId: z.string().describe('任务ID')
-    }, async (args) => {
-        const task = await storage.getTask(projectId, args.taskId);
-        if (!task) {
-            return wrap('任务不存在');
-        }
-        return wrap(JSON.stringify(task, null, 2));
+        return wrap(`找到 ${matched.length} 个匹配任务:\n${JSON.stringify(list, null, 2)}\n\n请提供更精确的任务名称`);
     });
-    // 13. 添加任务日志
-    server.tool('task_add_log', '记录任务进展/问题/方案/参考', {
+    // 9. 更新任务
+    server.tool('task_update', '更新任务(添加进展日志)', {
         taskId: z.string().describe('任务ID'),
-        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型'),
+        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型: progress=进展, issue=问题, solution=方案, reference=参考'),
         content: z.string().describe('日志内容(Markdown)')
     }, async (args) => {
-        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
-        const decodedContent = decodeUnicodeEscapes(args.content);
-        const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, decodedContent);
+        const decoded = decodeObjectStrings(args);
+        const task = await storage.addTaskLog(projectId, args.taskId, decoded.log_type, decoded.content);
         if (!task) {
-            return wrap('添加失败(任务不存在或已归档)');
+            return wrap('更新失败(任务不存在或已归档)');
         }
-        return wrap(`日志已添加，任务共有 ${task.logs.length} 条日志`);
+        return wrap(`✅ 日志已添加，任务共有 ${task.logs.length} 条日志`);
     });
-    // 14. 完成任务
-    server.tool('task_complete', '完成任务并归档,填写经验总结', {
+    // 10. 归档任务
+    server.tool('task_archive', '归档任务(完成并填写经验总结)', {
         taskId: z.string().describe('任务ID'),
         summary: z.string().describe('经验总结(Markdown)'),
         difficulties: z.array(z.string()).optional().describe('遇到的困难'),
-        solutions: z.array(z.string()).optional().describe('解决方案'),
-        references: z.array(z.object({
-            title: z.string(),
-            url: z.string().optional()
-        })).optional().describe('参考资料')
+        solutions: z.array(z.string()).optional().describe('解决方案')
     }, async (args) => {
-        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
-        const decoded = decodeObjectStrings({
-            summary: args.summary,
-            difficulties: args.difficulties || [],
-            solutions: args.solutions || [],
-            references: args.references || []
+        const decoded = decodeObjectStrings(args);
+        const task = await storage.completeTask(projectId, args.taskId, {
+            summary: decoded.summary,
+            difficulties: decoded.difficulties || [],
+            solutions: decoded.solutions || [],
+            references: []
         });
-        const task = await storage.completeTask(projectId, args.taskId, decoded);
         if (!task) {
-            return wrap('完成失败(任务不存在或已归档)');
-        }
-        return wrap(`任务已完成归档: ${task.title}`);
-    });
-    // 15. 查询文件关联的节点
-    server.tool('kg_find_by_file', '查询哪些节点绑定了指定文件(删除/重命名前检查)', {
-        filePath: z.string().describe('文件相对路径，如 src/utils/format.ts')
-    }, async (args) => {
-        const nodes = await storage.listNodes(projectId);
-        const filePath = args.filePath.replace(/\\/g, '/'); // 统一为正斜杠
-        // 查找所有绑定了该文件的节点
-        const boundBy = [];
-        for (const node of nodes) {
-            if (node.relatedFiles && node.relatedFiles.length > 0) {
-                // 检查是否包含该文件 (支持部分匹配)
-                const hasFile = node.relatedFiles.some(f => {
-                    const normalizedF = f.replace(/\\/g, '/');
-                    return normalizedF === filePath ||
-                        normalizedF.endsWith('/' + filePath) ||
-                        filePath.endsWith('/' + normalizedF);
-                });
-                if (hasFile) {
-                    boundBy.push({
-                        id: node.id,
-                        title: node.title,
-                        type: node.type,
-                        status: node.status
-                    });
-                }
-            }
-        }
-        const result = {
-            file: filePath,
-            boundBy,
-            message: boundBy.length > 0
-                ? `⚠️ 该文件被 ${boundBy.length} 个节点引用，删除前请更新节点`
-                : '✅ 该文件无 KG 引用，可安全操作'
-        };
-        return wrap(JSON.stringify(result, null, 2));
-    });
-    // ===================== 向量索引管理 =====================
-    // 注意: 向量索引由 Tauri 后端自动维护，MCP 只提供只读查询
-    // 16. 查看索引状态 (只读)
-    server.tool('kg_index_stats', '查看向量索引状态', {}, async () => {
-        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));
+            return wrap('归档失败(任务不存在或已归档)');
         }
+        return wrap(`✅ 任务已归档: ${task.title}`);
     });
 }

package/package.json

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

package/templates/commands/pp/DiagnosticProtocol.md

@@ -0,0 +1,82 @@
+# 🔍 "Deep-Trace" Diagnostic Protocol (深层溯源诊断协议)
+
+核心理念：**先在宏观地图（图谱）上定位，再在微观战场（代码）上排查，绝不盲目翻看代码。**
+
+---
+
+### 1.第一阶段：知识锚定 (Knowledge Anchoring) ⚓️
+🔹 **核心目标**：在动手之前，通过 PPDocs 明确“正确应该是什么样”。
+✏️ **动作**：
+*   **查询图谱**：输入问题关键词，提取标准业务逻辑。
+*   **建立基准**：以图谱中的描述作为“真理标准 (Truth)”。
+× **禁区**：
+*   禁止在未查询图谱前，直接跳入代码库阅读（防止陷入细节泥潭）。
+
+### 2.第二阶段：抽象映射 (Abstract Mapping) 🗺️
+🔹 **核心目标**：利用链式思维 (CoT)，绘制高层级逻辑流。
+✏️ **动作**：
+*   **绘制流程**：忽略实现细节，仅画出模块间的输入/输出流转（数据流）。
+*   **可视化**：生成 ASCII 或 Mermaid 流程图，展示当前链路。
+*   **标记疑点**：在流程图上圈出逻辑可能断裂的节点。
+
+### 3.第三阶段：靶点锁定 (Target Locking) 🎯
+🔹 **核心目标**：将问题范围从“整个项目”缩小到“单一节点”。
+✏️ **动作**：
+*   **定位区域**：确定问题具体发生在 PPDocs 的哪个 `Node`（节点）或 `Edge`（连线）上。
+*   **隔离上下文**：只关注该节点的前置依赖（Pre-requisites）和后置影响（Post-effects）。
+
+### 4.第三阶段：双层取证 (Dual-Layer Forensics) 🕵️
+🔹 **核心目标**：对比“理论（图谱）”与“现实（代码）”的差异。
+✏️ **动作**：
+*   **左眼看图谱**：阅读 PPDocs 中该节点的逻辑定义。
+*   **右眼看代码**：审查该节点对应的实际代码实现。
+*   **寻找裂痕**：
+    *   🔴 **代码错误 (Bug)**：图谱逻辑正确，代码实现错误。
+    *   🟠 **设计缺陷 (Design Flaw)**：代码符合图谱，但结果依然错误（图谱本身逻辑有误）。
+    *   🟡 **文档脱节 (Sync Issue)**：代码逻辑正确且有效，但图谱未记载（需同步）。
+
+### 5.第五阶段：分析结案 (Verdict) 📝
+🔹 **核心目标**：输出可执行的诊断报告。
+✏️ **动作**：
+*   输出标准化的**《问题诊断报告》**。
+*   **流转**：将报告作为输入，传递给 **[任务方案生成工作流]** 进行修复。
+
+---
+
+### 📊 诊断逻辑可视化图解 (ASCII)
+
+```text
+       +-------------------------+
+       |   🚨 问题触发 (Issue)    |
+       +------------+------------+
+                    |
+                    v
+       +------------+------------+
+       |  ⚓️ 知识锚定 (PPDocs)   | <--- 获取标准逻辑 (Truth)
+       +------------+------------+
+                    |
+                    v
+           [ 🗺️ 抽象逻辑层 ]
+       +-------------------------+
+       |   Step1 -> Step2 ...    | (绘制链式流程)
+       |           |             |
+       |         [ ? ] <---------+--- 🎯 锁定可疑节点
+       +-----------+-------------+
+                   |
+                   v
+       +-----------+-------------+
+       |  🕵️ 双层取证 (Compare)   |
+       +-----+-------------+-----+
+             |             |
+       (📜 PPDocs) vs (💻 Code)
+             |             |
+             +------+------+
+                    |
+                    v
+            /-------+-------\
+           /    根本原因?    \
+          v                   v
+  +--------------+     +--------------+
+  | 🐛 代码 Bug   |     | 📐 设计/文档错 |
+  | (Fix Code)   |     | (Fix Graph)  |
+  +--------------+     +--------------+