@ppdocs/mcp 3.1.9 → 3.2.0

package/dist/tools/docs.js

@@ -1,7 +1,7 @@
 /**
- * 文档管理工具 (7个)
- * kg_create_node, kg_delete_node, kg_update_node, kg_read_node,
- * kg_get_tree, kg_get_docs_by_status, kg_copy_node
+ * 📄 kg_doc (5合1) + 🏗️ kg_tree (2合1)
+ * 合并: kg_create_node, kg_delete_node, kg_update_node, kg_read_node, kg_copy_node
+ *       kg_get_tree, kg_get_docs_by_status
  */
 import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
@@ -9,52 +9,24 @@ import { decodeObjectStrings } from '../utils.js';
 import { wrap, safeTool, crossPrefix, formatDocMarkdown, formatTreeText, countTreeDocs } from './shared.js';
 export function registerDocTools(server, projectId) {
     const client = () => getClient();
-    // 创建文档
-    server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
-        path: z.string().min(1).describe('完整文档路径(如"/前端/组件/Modal")'),
-        summary: z.string().optional().describe('一句话简介'),
-        content: z.string().describe('Markdown内容'),
-        status: z.string().optional().describe('文档状态(默认"已完成")')
-    }, async (args) => safeTool(async () => {
-        const d = decodeObjectStrings(args);
-        const doc = await client().createDoc(d.path, {
-            summary: d.summary || '',
-            content: d.content,
-            versions: [{ version: 0.1, date: new Date().toISOString(), changes: '初始创建' }],
-            bugfixes: [],
-            status: d.status || '已完成'
-        });
-        return wrap(`✅ 文档已创建: ${d.path}\n\n${JSON.stringify(doc, null, 2)}`);
-    }));
-    // 删除文档或目录 (支持批量)
-    server.tool('kg_delete_node', '删除文档或目录(支持批量，根不可删除，目录会递归删除)', { nodeId: z.union([z.string(), z.array(z.string())]).describe('文档路径或路径数组') }, async (args) => safeTool(async () => {
-        const paths = Array.isArray(args.nodeId) ? args.nodeId : [args.nodeId];
-        const results = [];
-        for (const p of paths) {
-            results.push({ path: p, success: await client().deleteDoc(p) });
-        }
-        const successCount = results.filter(r => r.success).length;
-        if (paths.length === 1) {
-            return wrap(results[0].success ? '删除成功' : '删除失败(文档不存在或是根文档)');
-        }
-        const failedPaths = results.filter(r => !r.success).map(r => r.path);
-        let msg = `✅ 批量删除完成: ${successCount}/${paths.length} 成功`;
-        if (failedPaths.length > 0)
-            msg += `\n❌ 失败: ${failedPaths.join(', ')}`;
-        return wrap(msg);
-    }));
-    // 更新文档 (支持单个/批量)
-    server.tool('kg_update_node', '更新文档内容。【单个模式】nodeId+字段；【批量模式】仅传updates数组。两种模式二选一', {
-        nodeId: z.string().optional().describe('【单个模式】文档路径，如"/前端/组件/Button"'),
-        summary: z.string().optional().describe('【单个模式】一句话简介'),
-        content: z.string().optional().describe('【单个模式】Markdown内容'),
-        status: z.string().optional().describe('【单个模式】文档状态'),
+    // ========== kg_doc: 文档 CRUD 统一入口 ==========
+    server.tool('kg_doc', '📄 知识文档操作 — 创建、读取、更新、删除、复制文档。action: create(创建)|read(读取)|update(更新)|delete(删除)|batch_update(批量更新)|copy(跨项目复制)', {
+        action: z.enum(['create', 'read', 'update', 'delete', 'batch_update', 'copy'])
+            .describe('操作类型'),
+        path: z.string().optional()
+            .describe('文档路径(如"/前端/组件/Modal")。create/read/update/delete 必填'),
+        content: z.string().optional()
+            .describe('Markdown内容 (create/update)'),
+        summary: z.string().optional()
+            .describe('一句话简介 (create/update)'),
+        status: z.string().optional()
+            .describe('文档状态 (create/update, 默认"已完成")'),
         versions: z.array(z.object({
             version: z.number(), date: z.string(), changes: z.string()
-        })).optional().describe('【单个模式】版本记录数组'),
+        })).optional().describe('版本记录 (update)'),
         bugfixes: z.array(z.object({
             date: z.string(), issue: z.string(), solution: z.string()
-        })).optional().describe('【单个模式】修复记录数组'),
+        })).optional().describe('修复记录 (update)'),
         updates: z.array(z.object({
             nodeId: z.string().describe('文档路径'),
             summary: z.string().optional(),
@@ -66,83 +38,201 @@ export function registerDocTools(server, projectId) {
             bugfixes: z.array(z.object({
                 date: z.string(), issue: z.string(), solution: z.string()
             })).optional()
-        })).optional().describe('【批量模式】更新数组，每项包含nodeId和要更新的字段')
+        })).optional().describe('批量更新数组 (batch_update)'),
+        targetProject: z.string().optional()
+            .describe('跨项目读取时的目标项目ID (read)'),
+        sourceProject: z.string().optional()
+            .describe('复制源项目ID (copy)'),
+        sourcePath: z.union([z.string(), z.array(z.string())]).optional()
+            .describe('复制源路径 (copy, 单个或数组)'),
+        targetPath: z.string().optional()
+            .describe('复制目标路径前缀 (copy)'),
     }, async (args) => safeTool(async () => {
-        const decoded = decodeObjectStrings(args);
-        // 批量更新模式
-        if (decoded.updates && Array.isArray(decoded.updates)) {
-            const results = [];
-            for (const item of decoded.updates) {
-                if (item.nodeId === '/' || item.nodeId === '_root') {
-                    results.push({ path: item.nodeId, success: false });
-                    continue;
-                }
-                const existing = await client().getDoc(item.nodeId);
-                if (!existing) {
-                    results.push({ path: item.nodeId, success: false });
-                    continue;
+        const d = decodeObjectStrings(args);
+        switch (d.action) {
+            // ---- CREATE ----
+            case 'create': {
+                if (!d.path)
+                    return wrap('❌ create 需要 path');
+                if (!d.content)
+                    return wrap('❌ create 需要 content');
+                const doc = await client().createDoc(d.path, {
+                    summary: d.summary || '',
+                    content: d.content,
+                    versions: [{ version: 0.1, date: new Date().toISOString(), changes: '初始创建' }],
+                    bugfixes: [],
+                    status: d.status || '已完成'
+                });
+                return wrap(`✅ 文档已创建: ${d.path}\n\n${JSON.stringify(doc, null, 2)}`);
+            }
+            // ---- READ ----
+            case 'read': {
+                if (!d.path)
+                    return wrap('❌ read 需要 path');
+                const doc = d.targetProject
+                    ? await client().crossGetDoc(d.targetProject, d.path)
+                    : await client().getDoc(d.path);
+                if (!doc)
+                    return wrap(d.targetProject ? `文档不存在(项目: ${d.targetProject})` : '文档不存在');
+                const lines = formatDocMarkdown(doc, d.path);
+                return wrap(d.targetProject ? crossPrefix(d.targetProject) + lines.join('\n') : lines.join('\n'));
+            }
+            // ---- UPDATE ----
+            case 'update': {
+                if (!d.path)
+                    return wrap('❌ update 需要 path');
+                if (d.path === '/' || d.path === '_root') {
+                    // 根文档更新
+                    const existing = await client().getDoc('/');
+                    if (!existing)
+                        return wrap('更新失败(根文档不存在)');
+                    const updates = {};
+                    if (d.summary !== undefined)
+                        updates.summary = d.summary;
+                    if (d.content !== undefined)
+                        updates.content = d.content;
+                    const upd = await client().updateDoc('/', updates);
+                    return wrap(upd ? '✅ 项目介绍已更新' : '更新失败');
                 }
+                const existing = await client().getDoc(d.path);
+                if (!existing)
+                    return wrap('更新失败(文档不存在)');
                 const updates = {};
-                if (item.summary !== undefined)
-                    updates.summary = item.summary;
-                if (item.content !== undefined)
-                    updates.content = item.content;
-                if (item.status !== undefined)
-                    updates.status = item.status;
-                if (item.versions !== undefined)
-                    updates.versions = item.versions;
-                if (item.bugfixes !== undefined)
-                    updates.bugfixes = item.bugfixes;
-                const doc = await client().updateDoc(item.nodeId, updates);
-                results.push({ path: item.nodeId, success: !!doc });
+                if (d.summary !== undefined)
+                    updates.summary = d.summary;
+                if (d.content !== undefined)
+                    updates.content = d.content;
+                if (d.status !== undefined)
+                    updates.status = d.status;
+                if (d.versions !== undefined)
+                    updates.versions = d.versions;
+                if (d.bugfixes !== undefined)
+                    updates.bugfixes = d.bugfixes;
+                const doc = await client().updateDoc(d.path, updates);
+                return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
+            }
+            // ---- DELETE ----
+            case 'delete': {
+                if (!d.path)
+                    return wrap('❌ delete 需要 path');
+                const paths = Array.isArray(d.path) ? d.path : [d.path];
+                const results = [];
+                for (const p of paths) {
+                    results.push({ path: p, success: await client().deleteDoc(p) });
+                }
+                if (paths.length === 1) {
+                    return wrap(results[0].success ? '删除成功' : '删除失败(文档不存在或是根文档)');
+                }
+                const ok = results.filter(r => r.success).length;
+                const failed = results.filter(r => !r.success).map(r => r.path);
+                let msg = `✅ 批量删除: ${ok}/${paths.length} 成功`;
+                if (failed.length > 0)
+                    msg += `\n❌ 失败: ${failed.join(', ')}`;
+                return wrap(msg);
+            }
+            // ---- BATCH UPDATE ----
+            case 'batch_update': {
+                if (!d.updates || !Array.isArray(d.updates))
+                    return wrap('❌ batch_update 需要 updates 数组');
+                const results = [];
+                for (const item of d.updates) {
+                    if (item.nodeId === '/' || item.nodeId === '_root') {
+                        results.push({ path: item.nodeId, success: false });
+                        continue;
+                    }
+                    const existing = await client().getDoc(item.nodeId);
+                    if (!existing) {
+                        results.push({ path: item.nodeId, success: false });
+                        continue;
+                    }
+                    const upd = {};
+                    if (item.summary !== undefined)
+                        upd.summary = item.summary;
+                    if (item.content !== undefined)
+                        upd.content = item.content;
+                    if (item.status !== undefined)
+                        upd.status = item.status;
+                    if (item.versions !== undefined)
+                        upd.versions = item.versions;
+                    if (item.bugfixes !== undefined)
+                        upd.bugfixes = item.bugfixes;
+                    const doc = await client().updateDoc(item.nodeId, upd);
+                    results.push({ path: item.nodeId, success: !!doc });
+                }
+                const ok = results.filter(r => r.success).length;
+                const failed = results.filter(r => !r.success).map(r => r.path);
+                let msg = `✅ 批量更新: ${ok}/${d.updates.length} 成功`;
+                if (failed.length > 0)
+                    msg += `\n❌ 失败: ${failed.join(', ')}`;
+                return wrap(msg);
+            }
+            // ---- COPY ----
+            case 'copy': {
+                if (!d.sourceProject)
+                    return wrap('❌ copy 需要 sourceProject');
+                if (!d.sourcePath)
+                    return wrap('❌ copy 需要 sourcePath');
+                const paths = Array.isArray(d.sourcePath) ? d.sourcePath : [d.sourcePath];
+                const results = [];
+                for (const srcPath of paths) {
+                    try {
+                        const doc = await client().crossGetDoc(d.sourceProject, srcPath);
+                        if (!doc) {
+                            results.push({ path: srcPath, success: false, error: '源文档不存在' });
+                            continue;
+                        }
+                        const destPath = d.targetPath
+                            ? `${d.targetPath.replace(/\/$/, '')}${srcPath}`
+                            : srcPath;
+                        const existing = await client().getDoc(destPath);
+                        if (existing) {
+                            await client().updateDoc(destPath, { summary: doc.summary, content: doc.content });
+                        }
+                        else {
+                            await client().createDoc(destPath, { summary: doc.summary, content: doc.content, status: doc.status });
+                        }
+                        results.push({ path: destPath, success: true });
+                    }
+                    catch (e) {
+                        results.push({ path: srcPath, success: false, error: String(e) });
+                    }
+                }
+                const ok = results.filter(r => r.success).length;
+                if (paths.length === 1) {
+                    return wrap(results[0].success
+                        ? `✅ 已复制: ${results[0].path}\n来源: [${d.sourceProject}] ${paths[0]}`
+                        : `❌ 复制失败: ${results[0].error}`);
+                }
+                const failed = results.filter(r => !r.success);
+                let msg = `✅ 批量复制: ${ok}/${paths.length} 成功`;
+                if (failed.length > 0)
+                    msg += `\n❌ 失败:\n${failed.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
+                return wrap(msg);
             }
-            const successCount = results.filter(r => r.success).length;
-            const failedPaths = results.filter(r => !r.success).map(r => r.path);
-            let msg = `✅ 批量更新完成: ${successCount}/${decoded.updates.length} 成功`;
-            if (failedPaths.length > 0)
-                msg += `\n❌ 失败: ${failedPaths.join(', ')}`;
-            return wrap(msg);
+            default:
+                return wrap(`❌ 未知 action: ${d.action}`);
         }
-        // 单个更新模式
-        const { nodeId, summary, content, status, versions, bugfixes } = decoded;
-        if (!nodeId)
-            return wrap('❌ 请提供 nodeId（单个模式）或 updates 数组（批量模式）');
-        if (nodeId === '/' || nodeId === '_root')
-            return wrap('❌ 根文档请使用 kg_update_root 方法更新');
-        const existing = await client().getDoc(nodeId);
-        if (!existing)
-            return wrap('更新失败(文档不存在)');
-        const updates = {};
-        if (summary !== undefined)
-            updates.summary = summary;
-        if (content !== undefined)
-            updates.content = content;
-        if (status !== undefined)
-            updates.status = status;
-        if (versions !== undefined)
-            updates.versions = versions;
-        if (bugfixes !== undefined)
-            updates.bugfixes = bugfixes;
-        const doc = await client().updateDoc(nodeId, updates);
-        return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
     }));
-    // 读取单个文档详情
-    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        nodeId: z.string().describe('文档路径'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => safeTool(async () => {
-        const doc = args.targetProject
-            ? await client().crossGetDoc(args.targetProject, args.nodeId)
-            : await client().getDoc(args.nodeId);
-        if (!doc)
-            return wrap(args.targetProject ? `文档不存在(项目: ${args.targetProject})` : '文档不存在');
-        const lines = formatDocMarkdown(doc, args.nodeId);
-        return wrap(args.targetProject ? crossPrefix(args.targetProject) + lines.join('\n') : lines.join('\n'));
-    }));
-    // 获取知识库树状图
-    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
+    // ========== kg_tree: 知识全景图 ==========
+    server.tool('kg_tree', '🏗️ 项目知识全景图 ★最快了解项目的方式★ 获取完整知识库目录树(含文档数统计)。传 statusFilter 可筛选特定状态文档。建议任何操作前先调用获取全局视图', {
+        statusFilter: z.array(z.string()).optional()
+            .describe('按状态筛选(如["未完成","待修复"])，不传则展示全景目录树'),
+        targetProject: z.string().optional()
+            .describe('跨项目查看，填目标项目ID或名称'),
     }, async (args) => safeTool(async () => {
+        // 状态筛选模式
+        if (args.statusFilter && args.statusFilter.length > 0) {
+            const docs = args.targetProject
+                ? await client().crossGetDocsByStatus(args.targetProject, args.statusFilter)
+                : await client().getDocsByStatus(args.statusFilter);
+            if (docs.length === 0) {
+                return wrap(`未找到状态为 [${args.statusFilter.join(', ')}] 的文档${args.targetProject ? `(项目: ${args.targetProject})` : ''}`);
+            }
+            const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
+            const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+            return wrap(`${prefix}找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
+        }
+        // 全景目录树模式
         const tree = args.targetProject
             ? await client().crossGetTree(args.targetProject)
             : await client().getTree();
@@ -154,64 +244,4 @@ export function registerDocTools(server, projectId) {
         const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
         return wrap(`${prefix}共 ${docCount} 个文档\n\n${treeText}`);
     }));
-    // 按状态筛选文档
-    server.tool('kg_get_docs_by_status', '获取指定状态的文档列表。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        statusList: z.array(z.string()).describe('状态列表(如["未完成","待修复"])'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => safeTool(async () => {
-        const docs = args.targetProject
-            ? await client().crossGetDocsByStatus(args.targetProject, args.statusList)
-            : await client().getDocsByStatus(args.statusList);
-        if (docs.length === 0) {
-            return wrap(`未找到状态为 [${args.statusList.join(', ')}] 的文档${args.targetProject ? `(项目: ${args.targetProject})` : ''}`);
-        }
-        const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
-        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-        return wrap(`${prefix}找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
-    }));
-    // 跨项目复制文档
-    server.tool('kg_copy_node', '从其他项目复制文档到当前项目。支持单个或批量复制，可指定新路径。用于跨项目协作：拉取别的项目的知识文档到当前项目', {
-        sourceProject: z.string().describe('源项目ID或名称(从kg_list_projects获取)'),
-        sourcePath: z.union([z.string(), z.array(z.string())]).describe('源文档路径(单个或数组)'),
-        targetPath: z.string().optional().describe('目标路径前缀(如"/参考/项目B")。不填则保持原路径'),
-    }, async (args) => safeTool(async () => {
-        const decoded = decodeObjectStrings(args);
-        const paths = Array.isArray(decoded.sourcePath) ? decoded.sourcePath : [decoded.sourcePath];
-        const results = [];
-        for (const srcPath of paths) {
-            try {
-                const doc = await client().crossGetDoc(decoded.sourceProject, srcPath);
-                if (!doc) {
-                    results.push({ path: srcPath, success: false, error: '源文档不存在' });
-                    continue;
-                }
-                const destPath = decoded.targetPath
-                    ? `${decoded.targetPath.replace(/\/$/, '')}${srcPath}`
-                    : srcPath;
-                const existing = await client().getDoc(destPath);
-                if (existing) {
-                    await client().updateDoc(destPath, { summary: doc.summary, content: doc.content });
-                }
-                else {
-                    await client().createDoc(destPath, { summary: doc.summary, content: doc.content, status: doc.status });
-                }
-                results.push({ path: destPath, success: true });
-            }
-            catch (e) {
-                results.push({ path: srcPath, success: false, error: String(e) });
-            }
-        }
-        const successCount = results.filter(r => r.success).length;
-        if (paths.length === 1) {
-            return wrap(results[0].success
-                ? `✅ 已复制文档: ${results[0].path}\n\n来源: [${decoded.sourceProject}] ${paths[0]}`
-                : `❌ 复制失败: ${results[0].error}`);
-        }
-        const failedItems = results.filter(r => !r.success);
-        let msg = `✅ 批量复制完成: ${successCount}/${paths.length} 成功`;
-        if (failedItems.length > 0) {
-            msg += `\n❌ 失败:\n${failedItems.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
-        }
-        return wrap(msg);
-    }));
 }

package/dist/tools/files.d.ts

@@ -1,7 +1,7 @@
 /**
- * 项目文件访问工具 (5个)
- * project_upload, project_clear_files, project_list_files,
- * project_read_file, project_download
+ * 📁 kg_files (5→1)
+ * 合并: project_list_files, project_read_file, project_upload, project_download
+ * 删除: project_clear_files (危险操作)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerFileTools(server: McpServer): void;

package/dist/tools/files.js

@@ -1,66 +1,71 @@
 /**
- * 项目文件访问工具 (5个)
- * project_upload, project_clear_files, project_list_files,
- * project_read_file, project_download
+ * 📁 kg_files (5→1)
+ * 合并: project_list_files, project_read_file, project_upload, project_download
+ * 删除: project_clear_files (危险操作)
  */
 import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool, crossPrefix, formatFileSize } from './shared.js';
 export function registerFileTools(server) {
     const client = () => getClient();
-    // 上传本地目录到中心服务器
-    server.tool('project_upload', '上传本地项目目录到中心服务器(打包zip上传，自动排除node_modules/.git等)。上传后其他客户端可通过跨项目访问下载', {
-        localDir: z.string().describe('本地目录的绝对路径(如"/home/user/project/src")'),
-        remoteDir: z.string().optional().describe('上传到服务器的目标子目录(如"src")，不填则上传到根目录'),
+    server.tool('kg_files', '📁 项目文件操作 — 浏览目录、读取文件、上传下载。action: list(目录浏览)|read(读取文件)|upload(上传目录)|download(下载文件)', {
+        action: z.enum(['list', 'read', 'upload', 'download'])
+            .describe('操作类型'),
+        path: z.string().optional()
+            .describe('文件路径 (read/download, 如"src/main.ts")'),
+        dir: z.string().optional()
+            .describe('子目录路径 (list, 如"src/components")'),
+        localDir: z.string().optional()
+            .describe('本地目录绝对路径 (upload)'),
+        localPath: z.string().optional()
+            .describe('本地保存路径 (download)'),
+        remoteDir: z.string().optional()
+            .describe('远程目标子目录 (upload)'),
+        targetProject: z.string().optional()
+            .describe('跨项目操作的目标项目ID'),
     }, async (args) => safeTool(async () => {
-        const result = await client().uploadFiles(args.localDir, args.remoteDir);
-        return wrap(`✅ 上传成功\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}\n\n其他客户端可通过 project_read_file / project_download 访问`);
-    }));
-    // 清空项目文件存储区
-    server.tool('project_clear_files', '清空当前项目在中心服务器上的文件存储区', {}, async () => safeTool(async () => {
-        await client().clearFiles();
-        return wrap('✅ 文件存储已清空');
-    }));
-    // 列出项目文件
-    server.tool('project_list_files', '浏览项目源码目录结构(仅列出文件名和大小，不读内容)。目标项目需已上传文件或关联源码目录。跨项目时先用kg_list_projects获取项目ID。查看文件内容请用project_read_file', {
-        dir: z.string().optional().describe('子目录路径(如"src/components")，不填则列出根目录'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => safeTool(async () => {
-        const files = args.targetProject
-            ? await client().crossListFiles(args.targetProject, args.dir)
-            : await client().listFiles(args.dir);
-        if (files.length === 0)
-            return wrap('目录为空');
-        const lines = files.map(f => {
-            const icon = f.isDir ? '📁' : '📄';
-            const size = f.isDir ? '' : ` (${formatFileSize(f.size)})`;
-            return `${icon} ${f.name}${size}`;
-        });
-        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-        const dirLabel = args.dir || '/';
-        return wrap(`${prefix}📂 ${dirLabel} (${files.length} 项)\n\n${lines.join('\n')}`);
-    }));
-    // 读取项目文件
-    server.tool('project_read_file', '读取单个源码文件的文本内容(限1MB)。适合查看具体代码实现。跨项目时先用kg_list_projects获取项目ID。浏览目录结构请用project_list_files', {
-        path: z.string().describe('文件路径(如"src/main.ts")'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => safeTool(async () => {
-        const content = args.targetProject
-            ? await client().crossReadFile(args.targetProject, args.path)
-            : await client().readFile(args.path);
-        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-        return wrap(`${prefix}📄 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
-    }));
-    // 下载项目文件或目录
-    server.tool('project_download', '下载项目源码到本地(自动识别文件/目录，打包zip解压)。目标项目需已上传文件或关联源码目录。跨项目时先用kg_list_projects获取项目ID', {
-        remotePath: z.string().describe('远程路径，可以是目录(如"src")或单个文件(如"src/main.ts")'),
-        localPath: z.string().optional().describe('本地保存路径(不填则保存到系统临时目录，目录不存在会自动创建)'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => safeTool(async () => {
-        const result = args.targetProject
-            ? await client().crossDownload(args.targetProject, args.remotePath, args.localPath)
-            : await client().download(args.remotePath, args.localPath);
-        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-        return wrap(`${prefix}✅ 已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}`);
+        switch (args.action) {
+            case 'list': {
+                const files = args.targetProject
+                    ? await client().crossListFiles(args.targetProject, args.dir)
+                    : await client().listFiles(args.dir);
+                if (files.length === 0)
+                    return wrap('目录为空');
+                const lines = files.map(f => {
+                    const icon = f.isDir ? '📁' : '📄';
+                    const size = f.isDir ? '' : ` (${formatFileSize(f.size)})`;
+                    return `${icon} ${f.name}${size}`;
+                });
+                const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+                const dirLabel = args.dir || '/';
+                return wrap(`${prefix}📂 ${dirLabel} (${files.length} 项)\n\n${lines.join('\n')}`);
+            }
+            case 'read': {
+                if (!args.path)
+                    return wrap('❌ read 需要 path');
+                const content = args.targetProject
+                    ? await client().crossReadFile(args.targetProject, args.path)
+                    : await client().readFile(args.path);
+                const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+                return wrap(`${prefix}📄 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
+            }
+            case 'upload': {
+                if (!args.localDir)
+                    return wrap('❌ upload 需要 localDir');
+                const result = await client().uploadFiles(args.localDir, args.remoteDir);
+                return wrap(`✅ 上传成功\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}`);
+            }
+            case 'download': {
+                if (!args.path)
+                    return wrap('❌ download 需要 path');
+                const result = args.targetProject
+                    ? await client().crossDownload(args.targetProject, args.path, args.localPath)
+                    : await client().download(args.path, args.localPath);
+                const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+                return wrap(`${prefix}✅ 已下载\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}`);
+            }
+            default:
+                return wrap(`❌ 未知 action: ${args.action}`);
+        }
     }));
 }

package/dist/tools/index.d.ts

@@ -1,6 +1,11 @@
 /**
  * MCP 工具注册入口
- * 将 25 个工具拆分为 5 个子模块，统一在此注册
+ * 精简后: 12 个工具, 5 个子模块
+ *
+ * 📊 导航:     kg_status, kg_tree          (2个)
+ * 📚 知识:     kg_doc, kg_projects, kg_rules (3个)
+ * 📝 工作流:   kg_task, kg_files, kg_discuss (3个)
+ * 🔬 代码分析: code_scan, code_query, code_impact, code_context (4个)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerTools(server: McpServer, projectId: string, user: string): void;

package/dist/tools/index.js

@@ -1,16 +1,31 @@
 /**
  * MCP 工具注册入口
- * 将 25 个工具拆分为 5 个子模块，统一在此注册
+ * 精简后: 12 个工具, 5 个子模块
+ *
+ * 📊 导航:     kg_status, kg_tree          (2个)
+ * 📚 知识:     kg_doc, kg_projects, kg_rules (3个)
+ * 📝 工作流:   kg_task, kg_files, kg_discuss (3个)
+ * 🔬 代码分析: code_scan, code_query, code_impact, code_context (4个)
  */
+import { registerStatusTool } from './kg_status.js';
 import { registerDocTools } from './docs.js';
+import { registerProjectTools } from './projects.js';
 import { registerRuleTools } from './rules.js';
 import { registerTaskTools } from './tasks.js';
 import { registerFileTools } from './files.js';
-import { registerProjectTools } from './projects.js';
+import { registerDiscussionTools } from './discussion.js';
+import { registerAnalyzerTools } from './analyzer.js';
 export function registerTools(server, projectId, user) {
-    registerProjectTools(server, projectId);
+    // 📊 导航 (kg_status + kg_tree在docs中)
+    registerStatusTool(server, projectId);
+    // 📚 知识 (kg_doc + kg_tree + kg_projects + kg_rules)
     registerDocTools(server, projectId);
+    registerProjectTools(server, projectId);
     registerRuleTools(server, projectId);
+    // 📝 工作流 (kg_task + kg_files + kg_discuss)
     registerTaskTools(server, projectId, user);
     registerFileTools(server);
+    registerDiscussionTools(server, projectId);
+    // 🔬 代码分析 (不变)
+    registerAnalyzerTools(server, projectId);
 }

package/dist/tools/kg_status.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 📊 kg_status — 项目速览仪表盘 (新增)
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerStatusTool(server: McpServer, projectId: string): void;