@ppdocs/mcp 3.2.38 → 3.4.0

package/dist/index.js

@@ -45,21 +45,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // [M2 修复] beacon 变量提升到外部，支持优雅关闭
-    let beacon = null;
-    // 启动后台代码同步引擎 (Code Beacon) — 仅在有配置时启动
-    if (config) {
-        try {
-            const { SyncBeacon } = await import('./sync/beacon.js');
-            beacon = new SyncBeacon(process.cwd(), config.projectId);
-            beacon.start();
-        }
-        catch (err) {
-            console.error(`[Code Beacon] Failed to start:`, err);
-        }
-    }
-    // 优雅关闭：进程退出时停止 watcher，防止上传截断
-    const shutdown = () => { beacon?.stop(); process.exit(0); };
+    const shutdown = () => { process.exit(0); };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }

package/dist/storage/httpClient.d.ts

@@ -29,6 +29,8 @@ export declare class PpdocsApiClient {
     saveReference(reference: Reference): Promise<boolean>;
     deleteReference(refId: string): Promise<boolean>;
     readReferenceFile(path: string): Promise<string>;
+    /** 复制本地文件到参考文件库, 返回相对路径列表 */
+    copyReferenceFiles(paths: string[], targetDir?: string): Promise<string[]>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string, mode?: 'smart' | 'full'): Promise<Task | null>;
     createTask(task: {
@@ -67,14 +69,6 @@ export declare class PpdocsApiClient {
         localPath: string;
         fileCount: number;
     }>;
-    /** 上传本地目录或单文件到中心服务器 (打包 zip → POST) */
-    uploadFiles(localPath: string, remoteDir?: string): Promise<{
-        fileCount: number;
-    }>;
-    /** 上传已打包好的 zip 数据到本项目 files/ (供 Code Beacon 使用) */
-    uploadRawZip(zipData: Buffer | Uint8Array | any, remoteDir?: string): Promise<{
-        fileCount: number;
-    }>;
     /** 跨项目: 列出文件 */
     crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
     /** 跨项目: 读取文件 */
@@ -126,10 +120,6 @@ export declare class PpdocsApiClient {
         localPath: string;
         fileCount: number;
     }>;
-    /** 上传本地目录或单文件到公共文件池 */
-    publicFilesUpload(localPath: string, remoteDir?: string): Promise<{
-        fileCount: number;
-    }>;
     meetingJoin(agentId: string, agentType: string): Promise<unknown>;
     meetingLeave(agentId: string): Promise<unknown>;
     meetingPost(agentId: string, content: string, msgType?: string): Promise<unknown>;

package/dist/storage/httpClient.js

@@ -9,11 +9,6 @@
 function cleanPath(p) {
     return p.replace(/^\//, '');
 }
-/** 排除的目录 (与 Rust 端 EXCLUDED_DIRS 保持一致) */
-const EXCLUDED_DIRS = new Set([
-    'node_modules', '.git', 'target', 'dist', 'build', '.next',
-    '__pycache__', '.venv', 'venv', '.idea', '.vs', '.vscode',
-]);
 /** 下载 zip 并解压到指定目录或 temp 目录 */
 async function fetchAndExtractZip(url, localPath) {
     const controller = new AbortController();
@@ -157,6 +152,13 @@ export class PpdocsApiClient {
     async readReferenceFile(path) {
         return this.request(`/refs/files/${cleanPath(path)}`);
     }
+    /** 复制本地文件到参考文件库, 返回相对路径列表 */
+    async copyReferenceFiles(paths, targetDir = '.') {
+        return this.request('/refs/copy-in', {
+            method: 'POST',
+            body: JSON.stringify({ paths, target_dir: targetDir }),
+        });
+    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';
@@ -288,74 +290,6 @@ export class PpdocsApiClient {
     async download(remotePath, localPath) {
         return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(remotePath)}`, localPath);
     }
-    /** 上传本地目录或单文件到中心服务器 (打包 zip → POST) */
-    async uploadFiles(localPath, remoteDir) {
-        const fs = await import('fs');
-        const path = await import('path');
-        const AdmZip = (await import('adm-zip')).default;
-        if (!fs.existsSync(localPath)) {
-            throw new Error(`本地路径不存在: ${localPath}`);
-        }
-        const zip = new AdmZip();
-        const stat = fs.statSync(localPath);
-        if (stat.isDirectory()) {
-            const addDir = (dirPath, zipPath) => {
-                for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
-                    if (entry.name.startsWith('.'))
-                        continue;
-                    const fullPath = path.join(dirPath, entry.name);
-                    if (entry.isDirectory()) {
-                        if (EXCLUDED_DIRS.has(entry.name))
-                            continue;
-                        addDir(fullPath, zipPath ? `${zipPath}/${entry.name}` : entry.name);
-                    }
-                    else {
-                        if (fs.statSync(fullPath).size > 10_485_760)
-                            continue;
-                        zip.addLocalFile(fullPath, zipPath || undefined);
-                    }
-                }
-            };
-            addDir(localPath, '');
-        }
-        else {
-            if (stat.size > 10_485_760)
-                throw new Error('文件超过 10MB 限制');
-            zip.addLocalFile(localPath);
-        }
-        const buffer = zip.toBuffer();
-        if (buffer.length > 104_857_600) {
-            throw new Error('打包后超过 100MB 限制，请缩小目录范围');
-        }
-        const query = remoteDir ? `?dir=${encodeURIComponent(remoteDir)}` : '';
-        const response = await fetch(`${this.baseUrl}/files${query}`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/octet-stream' },
-            body: new Uint8Array(buffer),
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
-        }
-        const result = await response.json();
-        return { fileCount: result.data?.fileCount || 0 };
-    }
-    // ============ 直接上传已打包的 ZIP ============
-    /** 上传已打包好的 zip 数据到本项目 files/ (供 Code Beacon 使用) */
-    async uploadRawZip(zipData, remoteDir) {
-        const query = remoteDir ? `?dir=${encodeURIComponent(remoteDir)}` : '';
-        const response = await fetch(`${this.baseUrl}/files${query}`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/octet-stream' },
-            body: Buffer.isBuffer(zipData) ? new Uint8Array(zipData) : zipData,
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
-        }
-        const result = await response.json();
-        return { fileCount: result.data?.fileCount || 0 };
-    }
     // ============ 跨项目文件访问 (只读) ============
     /** 跨项目: 列出文件 */
     async crossListFiles(target, dir) {
@@ -493,58 +427,6 @@ export class PpdocsApiClient {
     async publicFilesDownload(remotePath, localPath) {
         return fetchAndExtractZip(`${this.serverUrl}/api/public-files/download/${cleanPath(remotePath)}`, localPath);
     }
-    /** 上传本地目录或单文件到公共文件池 */
-    async publicFilesUpload(localPath, remoteDir) {
-        const fs = await import('fs');
-        const path = await import('path');
-        const AdmZip = (await import('adm-zip')).default;
-        if (!fs.existsSync(localPath)) {
-            throw new Error(`本地路径不存在: ${localPath}`);
-        }
-        const zip = new AdmZip();
-        const stat = fs.statSync(localPath);
-        if (stat.isDirectory()) {
-            const addDir = (dirPath, zipPath) => {
-                for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
-                    if (entry.name.startsWith('.'))
-                        continue;
-                    const fullPath = path.join(dirPath, entry.name);
-                    if (entry.isDirectory()) {
-                        if (EXCLUDED_DIRS.has(entry.name))
-                            continue;
-                        addDir(fullPath, zipPath ? `${zipPath}/${entry.name}` : entry.name);
-                    }
-                    else {
-                        if (fs.statSync(fullPath).size > 10_485_760)
-                            continue;
-                        zip.addLocalFile(fullPath, zipPath || undefined);
-                    }
-                }
-            };
-            addDir(localPath, '');
-        }
-        else {
-            if (stat.size > 10_485_760)
-                throw new Error('文件超过 10MB 限制');
-            zip.addLocalFile(localPath);
-        }
-        const buffer = zip.toBuffer();
-        if (buffer.length > 104_857_600) {
-            throw new Error('打包后超过 100MB 限制');
-        }
-        const query = remoteDir ? `?dir=${encodeURIComponent(remoteDir)}` : '';
-        const response = await fetch(`${this.serverUrl}/api/public-files/upload${query}`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/octet-stream' },
-            body: new Uint8Array(buffer),
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
-        }
-        const result = await response.json();
-        return { fileCount: result.data?.fileCount || 0 };
-    }
     // ============ 多AI协作会议 ============
     async meetingJoin(agentId, agentType) {
         return this.request('/meeting/join', {

package/dist/tools/discussion.js

@@ -103,9 +103,9 @@ function formatDetailView(d) {
 }
 export function registerDiscussionTools(server, ctx) {
     const client = () => getClient();
-    server.tool('kg_discuss', '💬 跨项目讨论 — action: list|read|create|reply|complete|close|delete|history。权限: 仅成员可读写，仅发起人可删除/归档', {
-        action: z.enum(['list', 'read', 'create', 'reply', 'complete', 'close', 'delete', 'history'])
-            .describe('操作类型'),
+    server.tool('kg_discuss', '💬 跨项目讨论 — action 可选: 省略时无 id/ids 则列出讨论，有 id/ids 则读取详情。亦可显式指定 list|read|create|reply|complete|close|delete|history。权限: 仅成员可读写，仅发起人可删除/归档', {
+        action: z.enum(['list', 'read', 'create', 'reply', 'complete', 'close', 'delete', 'history']).optional()
+            .describe('操作类型（可选：省略时根据 id/ids 自动为 read，否则为 list）'),
         id: z.string().optional()
             .describe('讨论哈希ID (read/reply/complete/close/delete)'),
         ids: z.array(z.string()).optional()
@@ -128,7 +128,13 @@ export function registerDiscussionTools(server, ctx) {
         const decoded = decodeObjectStrings(args);
         const me = sender(ctx);
         const myPid = ctx.projectId;
-        switch (decoded.action) {
+        // 智能默认：未指定 action 时，有 id/ids → read，否则 → list
+        let action = decoded.action;
+        if (!action) {
+            const hasIds = Boolean(decoded.id) || (Array.isArray(decoded.ids) && decoded.ids.length > 0);
+            action = hasIds ? 'read' : 'list';
+        }
+        switch (action) {
             // ============ 公开操作 ============
             case 'list': {
                 const active = await client().discussionList();
@@ -249,7 +255,7 @@ export function registerDiscussionTools(server, ctx) {
                 return wrap(`✅ 讨论已删除 (ID: ${decoded.id})`);
             }
             default:
-                return wrap(`❌ 未知 action: ${decoded.action}`);
+                return wrap(`❌ 未知 action: ${action}`);
         }
     }));
 }

package/dist/tools/files.d.ts

@@ -1,7 +1,6 @@
 /**
- * 📁 kg_files (5→1)
- * 合并: project_list_files, project_read_file, project_upload, project_download
- * + 公共文件池: public_list, public_read, public_upload, public_download, public_delete
+ * 📁 kg_files — 文件浏览/读取/下载 (上传已移除，全部本地化)
+ * 公共文件池: public_list, public_read, public_download, public_delete, public_mkdir, public_rename
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerFileTools(server: McpServer): void;

package/dist/tools/files.js

@@ -1,26 +1,21 @@
 /**
- * 📁 kg_files (5→1)
- * 合并: project_list_files, project_read_file, project_upload, project_download
- * + 公共文件池: public_list, public_read, public_upload, public_download, public_delete
+ * 📁 kg_files — 文件浏览/读取/下载 (上传已移除，全部本地化)
+ * 公共文件池: public_list, public_read, public_download, public_delete, public_mkdir, public_rename
  */
 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('kg_files', '📁 项目文件操作 — 浏览目录、读取文件、上传下载。action: list(目录浏览)|read(读取文件)|upload(上传)|download(下载文件)|public_list(公共文件池浏览)|public_read(读取公共文件)|public_upload(上传到公共池)|public_download(下载公共文件)|public_delete(删除公共文件)|public_mkdir(创建公共池子目录)|public_rename(重命名公共文件)', {
-        action: z.enum(['list', 'read', 'upload', 'download', 'public_list', 'public_read', 'public_upload', 'public_download', 'public_delete', 'public_mkdir', 'public_rename'])
+    server.tool('kg_files', '📁 项目文件操作 — 浏览目录、读取文件、下载。action: list(目录浏览)|read(读取文件)|download(下载文件)|public_list(公共文件池浏览)|public_read(读取公共文件)|public_download(下载公共文件)|public_delete(删除公共文件)|public_mkdir(创建公共池子目录)|public_rename(重命名公共文件)', {
+        action: z.enum(['list', 'read', 'download', 'public_list', 'public_read', 'public_download', 'public_delete', 'public_mkdir', 'public_rename'])
             .describe('操作类型'),
         path: z.string().optional()
             .describe('文件路径 (read/download/public_read/public_download/public_delete/public_mkdir, 如"src/main.ts")'),
         dir: z.string().optional()
             .describe('子目录路径 (list/public_list, 如"src/components")'),
-        localDir: z.string().optional()
-            .describe('本地路径(目录或单文件) (upload/public_upload)'),
         localPath: z.string().optional()
             .describe('本地保存路径 (download/public_download)'),
-        remoteDir: z.string().optional()
-            .describe('远程目标子目录 (upload/public_upload)'),
         newName: z.string().optional()
             .describe('新名称 (public_rename)'),
         targetProject: z.string().optional()
@@ -51,12 +46,6 @@ export function registerFileTools(server) {
                 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');
@@ -85,12 +74,6 @@ export function registerFileTools(server) {
                 const content = await client().publicFilesRead(args.path);
                 return wrap(`📦 公共文件 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
             }
-            case 'public_upload': {
-                if (!args.localDir)
-                    return wrap('❌ public_upload 需要 localDir');
-                const result = await client().publicFilesUpload(args.localDir, args.remoteDir);
-                return wrap(`✅ 已上传到公共文件池\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}`);
-            }
             case 'public_download': {
                 if (!args.path)
                     return wrap('❌ public_download 需要 path');

package/dist/tools/refs.js

@@ -91,6 +91,11 @@ export function registerReferenceTools(server) {
                     return wrap('❌ save 需要 title');
                 const existing = await client().getReference(decoded.id);
                 const now = new Date().toISOString();
+                // 直接传递原始路径给后端, Rust save_reference 会自动:
+                // 1. 检测绝对路径文件
+                // 2. 复制到公共文件池/外部参考/{项目名}/
+                // 3. 复制到 ref-files/ (供 read_file API 读取)
+                // 4. 替换为相对路径保存
                 await client().saveReference({
                     id: decoded.id,
                     title: decoded.title,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "3.2.38",
+  "version": "3.4.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -33,15 +33,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "adm-zip": "^0.5.16",
-    "archiver": "^7.0.1",
-    "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
-    "@types/archiver": "^7.0.0",
-    "@types/chokidar": "^1.7.5",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"

package/dist/sync/beacon.d.ts

@@ -1,26 +0,0 @@
-export declare class SyncBeacon {
-    private cwd;
-    private projectId;
-    private debounceMs;
-    private watcher;
-    private isSyncing;
-    private pendingSync;
-    private debounceTimer;
-    constructor(cwd: string, projectId: string, debounceMs?: number);
-    /**
-     * 启动同步引擎
-     */
-    start(): void;
-    /**
-     * 停止同步引擎
-     */
-    stop(): void;
-    /**
-     * 触发同步计算
-     */
-    private triggerSync;
-    /**
-     * 核心: 打包并推送全量快照
-     */
-    private performSync;
-}

package/dist/sync/beacon.js

@@ -1,186 +0,0 @@
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import archiver from 'archiver';
-import * as chokidar from 'chokidar';
-import { getClient } from '../storage/httpClient.js';
-// 需要排除的大文件/敏感目录
-const EXCLUDED_DIRS = [
-    'node_modules',
-    '.git',
-    '.next',
-    'dist',
-    'build',
-    'out',
-    'target',
-    '__pycache__',
-    '.venv',
-    'venv',
-    '.idea',
-    '.vscode',
-    '.vs',
-    '.ppdocs',
-    '.cursor',
-    '.claude',
-    '.gemini',
-];
-export class SyncBeacon {
-    cwd;
-    projectId;
-    debounceMs;
-    watcher = null;
-    isSyncing = false;
-    pendingSync = false;
-    debounceTimer = null;
-    constructor(cwd, projectId, debounceMs = 15000 // 默认 15 秒防抖
-    ) {
-        this.cwd = cwd;
-        this.projectId = projectId;
-        this.debounceMs = debounceMs;
-    }
-    /**
-     * 启动同步引擎
-     */
-    start() {
-        if (this.watcher)
-            return;
-        console.error(`[Code Beacon] Started monitoring project: ${this.projectId}`);
-        // [M1 修复] 首次启动延迟 3 秒，让 MCP 工具注册和事件循环先稳定
-        setTimeout(() => this.triggerSync(), 3000);
-        // 配置监听器
-        this.watcher = chokidar.watch(this.cwd, {
-            ignored: (filePath) => {
-                const basename = path.basename(filePath);
-                if (EXCLUDED_DIRS.includes(basename))
-                    return true;
-                if (basename.startsWith('.') && basename !== '.env.example' && !filePath.includes('.cursorrules') && !filePath.includes('ppdocs.md'))
-                    return true;
-                return false;
-            },
-            persistent: true,
-            ignoreInitial: true,
-        });
-        // 绑定事件
-        const scheduleSync = (evt, p) => {
-            if (this.debounceTimer) {
-                clearTimeout(this.debounceTimer);
-            }
-            this.debounceTimer = setTimeout(() => {
-                console.error(`[Code Beacon] Changes detected (${evt}: ${path.basename(p)}), scheduling sync...`);
-                this.triggerSync();
-            }, this.debounceMs);
-        };
-        this.watcher
-            .on('add', (p) => scheduleSync('add', p))
-            .on('change', (p) => scheduleSync('change', p))
-            .on('unlink', (p) => scheduleSync('delete', p))
-            .on('unlinkDir', (p) => scheduleSync('delete dir', p));
-    }
-    /**
-     * 停止同步引擎
-     */
-    stop() {
-        if (this.debounceTimer) {
-            clearTimeout(this.debounceTimer);
-            this.debounceTimer = null;
-        }
-        if (this.watcher) {
-            this.watcher.close();
-            this.watcher = null;
-            console.error(`[Code Beacon] Stopped monitoring project: ${this.projectId}`);
-        }
-    }
-    /**
-     * 触发同步计算
-     */
-    async triggerSync() {
-        if (this.isSyncing) {
-            this.pendingSync = true;
-            return;
-        }
-        this.isSyncing = true;
-        this.pendingSync = false;
-        try {
-            await this.performSync();
-        }
-        catch (error) {
-            console.error(`[Code Beacon] Sync error:`, error);
-        }
-        finally {
-            this.isSyncing = false;
-            if (this.pendingSync) {
-                this.triggerSync();
-            }
-        }
-    }
-    /**
-     * 核心: 打包并推送全量快照
-     */
-    async performSync() {
-        // [C3 修复] getClient() 在未初始化时 throw，不会返回 null
-        let client;
-        try {
-            client = getClient();
-        }
-        catch {
-            console.warn('[Code Beacon] API Client not ready, skipping sync.');
-            return;
-        }
-        return new Promise((resolve, reject) => {
-            try {
-                // 使用系统临时目录存放打包文件，避免 .ppdocs（是配置文件非目录）冲突
-                const tmpFile = path.join(os.tmpdir(), `beacon-${this.projectId}-${Date.now()}.zip`);
-                const output = fs.createWriteStream(tmpFile);
-                const archive = archiver('zip', {
-                    zlib: { level: 3 } // 低压缩率，追求速度
-                });
-                // [C1 修复] 监听 WriteStream 的 error 事件，防止 Node 进程崩溃
-                output.on('error', (err) => {
-                    console.error('[Code Beacon] WriteStream error:', err);
-                    reject(err);
-                });
-                output.on('close', async () => {
-                    try {
-                        const data = await fs.promises.readFile(tmpFile);
-                        // [C2 修复] 使用本项目标准上传接口，而非 crossUploadFiles
-                        await client.uploadRawZip(data);
-                        console.error(`[Code Beacon] Snapshot synced: ${archive.pointer()} bytes`);
-                    }
-                    catch (e) {
-                        console.error('[Code Beacon] Upload failed:', e);
-                    }
-                    finally {
-                        try {
-                            if (fs.existsSync(tmpFile))
-                                fs.promises.unlink(tmpFile);
-                        }
-                        catch { }
-                        resolve();
-                    }
-                });
-                archive.on('error', (err) => {
-                    reject(err);
-                });
-                archive.pipe(output);
-                // 遍历所有非隐藏、非排除的文件打包
-                archive.glob('**/*', {
-                    cwd: this.cwd,
-                    ignore: [
-                        ...EXCLUDED_DIRS.map(d => `${d}/**`),
-                        '.ppdocs',
-                        '.*'
-                    ],
-                    dot: false
-                });
-                // [A2 修复] 排除 .env（敏感凭证），仅包含安全的 IDE 配置
-                if (fs.existsSync(path.join(this.cwd, '.cursorrules'))) {
-                    archive.file(path.join(this.cwd, '.cursorrules'), { name: '.cursorrules' });
-                }
-                archive.finalize();
-            }
-            catch (err) {
-                reject(err);
-            }
-        });
-    }
-}