@ppdocs/mcp 2.9.0 → 3.0.1

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-import type { DocData, DocNode, DocSearchResult, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
+import type { DocData, DocNode, DocSearchResult, Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, RuleMeta } from './types.js';
 interface TreeNode {
     path: string;
     name: string;
@@ -14,6 +14,7 @@ interface TreeNode {
 }
 export declare class PpdocsApiClient {
     private baseUrl;
+    private serverUrl;
     constructor(apiUrl: string);
     private request;
     listDocs(): Promise<DocNode[]>;
@@ -28,6 +29,11 @@ export declare class PpdocsApiClient {
     getTree(): Promise<TreeNode[]>;
     getRulesApi(ruleType: string): Promise<string[]>;
     saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
+    getRulesMeta(): Promise<Record<string, RuleMeta>>;
+    saveRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
+    crossGetRulesMeta(target: string): Promise<Record<string, RuleMeta>>;
+    getGlobalRulesMeta(): Promise<Record<string, RuleMeta>>;
+    saveGlobalRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string): Promise<Task | null>;
     createTask(task: {
@@ -37,12 +43,20 @@ export declare class PpdocsApiClient {
     }, creator: string): Promise<Task>;
     addTaskLog(taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
     completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
+    /** 创建项目 (公开路由，无需认证) */
+    createProject(id: string, name: string, description?: string, projectPath?: string): Promise<{
+        project: {
+            id: string;
+            name: string;
+        };
+        password: string;
+    }>;
     /** 列出所有可访问的项目 */
     crossListProjects(): Promise<{
         id: string;
         name: string;
         description: string;
-        updated_at: string;
+        updatedAt: string;
     }[]>;
     /** 跨项目: 列出文档 */
     crossListDocs(target: string): Promise<DocNode[]>;
@@ -54,6 +68,30 @@ export declare class PpdocsApiClient {
     crossGetDocsByStatus(target: string, statusList: string[]): Promise<DocNode[]>;
     /** 跨项目: 获取规则 */
     crossGetRules(target: string, ruleType: string): Promise<string[]>;
+    /** 列出项目文件 */
+    listFiles(dir?: string): Promise<FileInfo[]>;
+    /** 读取项目文件 */
+    readFile(filePath: string): Promise<string>;
+    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
+    downloadDir(dir: string): Promise<{
+        localPath: string;
+        fileCount: number;
+    }>;
+    /** 上传本地目录到中心服务器 (打包 zip → POST) */
+    uploadFiles(localDir: string, remoteDir?: string): Promise<{
+        fileCount: number;
+    }>;
+    /** 清空项目文件存储区 */
+    clearFiles(): Promise<void>;
+    /** 跨项目: 列出文件 */
+    crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
+    /** 跨项目: 读取文件 */
+    crossReadFile(target: string, filePath: string): Promise<string>;
+    /** 跨项目: 下载目录 */
+    crossDownloadDir(target: string, dir: string): Promise<{
+        localPath: string;
+        fileCount: number;
+    }>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listDocs(_projectId: string): Promise<DocNode[]>;
@@ -66,6 +104,11 @@ export declare function getDocsByStatus(_projectId: string, statusList: string[]
 export declare function getTree(_projectId: string): Promise<TreeNode[]>;
 export declare function getRules(_projectId: string, ruleType: string): Promise<string[]>;
 export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;
+export declare function getRulesMeta(): Promise<Record<string, RuleMeta>>;
+export declare function saveRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
+export declare function crossGetRulesMeta(target: string): Promise<Record<string, RuleMeta>>;
+export declare function getGlobalRulesMeta(): Promise<Record<string, RuleMeta>>;
+export declare function saveGlobalRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
 export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
 export declare function getTask(_projectId: string, taskId: string): Promise<Task | null>;
 export declare function createTask(_projectId: string, task: {
@@ -75,14 +118,37 @@ export declare function createTask(_projectId: string, task: {
 }, creator: string): Promise<Task>;
 export declare function addTaskLog(_projectId: string, taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
 export declare function completeTask(_projectId: string, taskId: string, experience: TaskExperience): Promise<Task | null>;
+export declare function createProject(id: string, name: string, description?: string, projectPath?: string): Promise<{
+    project: {
+        id: string;
+        name: string;
+    };
+    password: string;
+}>;
 export declare function crossListProjects(): Promise<{
     id: string;
     name: string;
     description: string;
-    updated_at: string;
+    updatedAt: string;
 }[]>;
 export declare function crossGetDoc(target: string, docPath: string): Promise<DocData | null>;
 export declare function crossGetTree(target: string): Promise<TreeNode[]>;
 export declare function crossGetDocsByStatus(target: string, statusList: string[]): Promise<DocNode[]>;
 export declare function crossGetRules(target: string, ruleType: string): Promise<string[]>;
+export declare function listFiles(dir?: string): Promise<FileInfo[]>;
+export declare function readFile(filePath: string): Promise<string>;
+export declare function downloadDir(dir: string): Promise<{
+    localPath: string;
+    fileCount: number;
+}>;
+export declare function crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
+export declare function crossReadFile(target: string, filePath: string): Promise<string>;
+export declare function crossDownloadDir(target: string, dir: string): Promise<{
+    localPath: string;
+    fileCount: number;
+}>;
+export declare function uploadFiles(localDir: string, remoteDir?: string): Promise<{
+    fileCount: number;
+}>;
+export declare function clearFiles(): Promise<void>;
 export type { TreeNode };

package/dist/storage/httpClient.js

@@ -4,6 +4,57 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
+// ============ 工具函数 ============
+/** 清理路径前缀斜杠 */
+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) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 60000);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        const os = await import('os');
+        const path = await import('path');
+        const fs = await import('fs');
+        const AdmZip = (await import('adm-zip')).default;
+        const tempDir = path.join(os.tmpdir(), `ppdocs-files-${Date.now()}`);
+        fs.mkdirSync(tempDir, { recursive: true });
+        const zip = new AdmZip(buffer);
+        zip.extractAllTo(tempDir, true);
+        let fileCount = 0;
+        const countFiles = (dirPath) => {
+            for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    countFiles(path.join(dirPath, entry.name));
+                else
+                    fileCount++;
+            }
+        };
+        countFiles(tempDir);
+        return { localPath: tempDir, fileCount };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error('Download timeout (60s)');
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 /** 从扁平文档列表构建目录树 */
 function buildTree(docs) {
     const root = [];
@@ -40,9 +91,12 @@ function buildTree(docs) {
 // API 客户端类
 export class PpdocsApiClient {
     baseUrl; // http://localhost:20001/api/projectId/password
+    serverUrl; // http://localhost:20001
     constructor(apiUrl) {
-        // 移除末尾斜杠
         this.baseUrl = apiUrl.replace(/\/$/, '');
+        // 从 /api/projectId/password 提取服务器根地址
+        const apiIndex = this.baseUrl.indexOf('/api/');
+        this.serverUrl = apiIndex > 0 ? this.baseUrl.substring(0, apiIndex) : this.baseUrl;
     }
     // ============ HTTP 请求工具 ============
     async request(path, options = {}) {
@@ -84,16 +138,13 @@ export class PpdocsApiClient {
     }
     async getDoc(docPath) {
         try {
-            // 移除开头的斜杠，API 路径会自动处理
-            const cleanPath = docPath.replace(/^\//, '');
-            return await this.request(`/docs/${cleanPath}`);
+            return await this.request(`/docs/${cleanPath(docPath)}`);
         }
         catch {
             return null;
         }
     }
     async createDoc(docPath, doc) {
-        const cleanPath = docPath.replace(/^\//, '');
         const payload = {
             summary: doc.summary || '',
             content: doc.content || '',
@@ -103,17 +154,15 @@ export class PpdocsApiClient {
                     changes: '初始创建'
                 }],
             bugfixes: doc.bugfixes || [],
-            status: doc.status || '已完成' // 默认状态
+            status: doc.status || '已完成'
         };
-        return this.request(`/docs/${cleanPath}`, {
+        return this.request(`/docs/${cleanPath(docPath)}`, {
             method: 'POST',
             body: JSON.stringify(payload)
         });
     }
     async updateDoc(docPath, updates) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            // 先获取现有文档
             const existing = await this.getDoc(docPath);
             if (!existing)
                 return null;
@@ -124,7 +173,7 @@ export class PpdocsApiClient {
                 bugfixes: updates.bugfixes ?? existing.bugfixes,
                 status: updates.status ?? existing.status ?? '已完成'
             };
-            return await this.request(`/docs/${cleanPath}`, {
+            return await this.request(`/docs/${cleanPath(docPath)}`, {
                 method: 'PUT',
                 body: JSON.stringify(payload)
             });
@@ -135,8 +184,7 @@ export class PpdocsApiClient {
     }
     async deleteDoc(docPath) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            await this.request(`/docs/${cleanPath}`, { method: 'DELETE' });
+            await this.request(`/docs/${cleanPath(docPath)}`, { method: 'DELETE' });
             return true;
         }
         catch {
@@ -182,6 +230,54 @@ export class PpdocsApiClient {
             return false;
         }
     }
+    async getRulesMeta() {
+        try {
+            return await this.request('/rules-meta');
+        }
+        catch {
+            return {};
+        }
+    }
+    async saveRulesMeta(meta) {
+        try {
+            await this.request('/rules-meta', {
+                method: 'PUT',
+                body: JSON.stringify(meta)
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async crossGetRulesMeta(target) {
+        try {
+            return await this.request(`/cross/${encodeURIComponent(target)}/rules-meta`);
+        }
+        catch {
+            return {};
+        }
+    }
+    async getGlobalRulesMeta() {
+        try {
+            return await this.request('/global-rules-meta');
+        }
+        catch {
+            return {};
+        }
+    }
+    async saveGlobalRulesMeta(meta) {
+        try {
+            await this.request('/global-rules-meta', {
+                method: 'PUT',
+                body: JSON.stringify(meta)
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';
@@ -232,6 +328,22 @@ export class PpdocsApiClient {
             return null;
         }
     }
+    // ============ 项目管理 ============
+    /** 创建项目 (公开路由，无需认证) */
+    async createProject(id, name, description, projectPath) {
+        const url = `${this.serverUrl}/api/projects`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id, name, description: description || '', project_path: projectPath || '' }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const json = await response.json();
+        return json.data;
+    }
     // ============ 跨项目只读访问 ============
     /** 列出所有可访问的项目 */
     async crossListProjects() {
@@ -244,8 +356,7 @@ export class PpdocsApiClient {
     /** 跨项目: 获取文档 */
     async crossGetDoc(target, docPath) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath}`);
+            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath(docPath)}`);
         }
         catch {
             return null;
@@ -272,6 +383,87 @@ export class PpdocsApiClient {
             return [];
         }
     }
+    // ============ 项目文件访问 ============
+    /** 列出项目文件 */
+    async listFiles(dir) {
+        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
+        return this.request(`/files${query}`);
+    }
+    /** 读取项目文件 */
+    async readFile(filePath) {
+        return this.request(`/files/${cleanPath(filePath)}`);
+    }
+    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
+    async downloadDir(dir) {
+        return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(dir)}`);
+    }
+    /** 上传本地目录到中心服务器 (打包 zip → POST) */
+    async uploadFiles(localDir, remoteDir) {
+        const fs = await import('fs');
+        const path = await import('path');
+        const AdmZip = (await import('adm-zip')).default;
+        if (!fs.existsSync(localDir) || !fs.statSync(localDir).isDirectory()) {
+            throw new Error(`本地目录不存在: ${localDir}`);
+        }
+        const zip = new AdmZip();
+        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(localDir, '');
+        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 };
+    }
+    /** 清空项目文件存储区 */
+    async clearFiles() {
+        const url = `${this.baseUrl}/files`;
+        const response = await fetch(url, { method: 'DELETE' });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+    }
+    // ============ 跨项目文件访问 (只读) ============
+    /** 跨项目: 列出文件 */
+    async crossListFiles(target, dir) {
+        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
+        return this.request(`/cross/${encodeURIComponent(target)}/files${query}`);
+    }
+    /** 跨项目: 读取文件 */
+    async crossReadFile(target, filePath) {
+        return this.request(`/cross/${encodeURIComponent(target)}/files/${cleanPath(filePath)}`);
+    }
+    /** 跨项目: 下载目录 */
+    async crossDownloadDir(target, dir) {
+        return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(dir)}`);
+    }
 }
 // ============ 模块级 API ============
 let client = null;
@@ -316,6 +508,21 @@ export async function getRules(_projectId, ruleType) {
 export async function saveRules(_projectId, ruleType, rules) {
     return getClient().saveRulesApi(ruleType, rules);
 }
+export async function getRulesMeta() {
+    return getClient().getRulesMeta();
+}
+export async function saveRulesMeta(meta) {
+    return getClient().saveRulesMeta(meta);
+}
+export async function crossGetRulesMeta(target) {
+    return getClient().crossGetRulesMeta(target);
+}
+export async function getGlobalRulesMeta() {
+    return getClient().getGlobalRulesMeta();
+}
+export async function saveGlobalRulesMeta(meta) {
+    return getClient().saveGlobalRulesMeta(meta);
+}
 // ============ 任务管理 ============
 export async function listTasks(_projectId, status) {
     return getClient().listTasks(status);
@@ -332,6 +539,10 @@ export async function addTaskLog(_projectId, taskId, logType, content) {
 export async function completeTask(_projectId, taskId, experience) {
     return getClient().completeTask(taskId, experience);
 }
+// ============ 项目管理 ============
+export async function createProject(id, name, description, projectPath) {
+    return getClient().createProject(id, name, description, projectPath);
+}
 // ============ 跨项目只读访问 ============
 export async function crossListProjects() {
     return getClient().crossListProjects();
@@ -348,3 +559,28 @@ export async function crossGetDocsByStatus(target, statusList) {
 export async function crossGetRules(target, ruleType) {
     return getClient().crossGetRules(target, ruleType);
 }
+// ============ 项目文件访问 ============
+export async function listFiles(dir) {
+    return getClient().listFiles(dir);
+}
+export async function readFile(filePath) {
+    return getClient().readFile(filePath);
+}
+export async function downloadDir(dir) {
+    return getClient().downloadDir(dir);
+}
+export async function crossListFiles(target, dir) {
+    return getClient().crossListFiles(target, dir);
+}
+export async function crossReadFile(target, filePath) {
+    return getClient().crossReadFile(target, filePath);
+}
+export async function crossDownloadDir(target, dir) {
+    return getClient().crossDownloadDir(target, dir);
+}
+export async function uploadFiles(localDir, remoteDir) {
+    return getClient().uploadFiles(localDir, remoteDir);
+}
+export async function clearFiles() {
+    return getClient().clearFiles();
+}

package/dist/storage/types.d.ts

@@ -44,6 +44,21 @@ export interface Project {
     name: string;
     description?: string;
     updatedAt: string;
+    createdAt?: string;
+    projectPath?: string;
+}
+export interface RuleMeta {
+    label: string;
+    keywords: string[];
+    min_hits: number;
+    always?: boolean;
+}
+export interface FileInfo {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    modifiedAt?: string;
 }
 export type TaskLogType = 'progress' | 'issue' | 'solution' | 'reference';
 export interface TaskLog {

package/dist/tools/helpers.d.ts

@@ -30,4 +30,8 @@ export declare function formatTreeText(tree: TreeNode[]): string;
  * 统计树中的文档数
  */
 export declare function countTreeDocs(tree: TreeNode[]): number;
+/**
+ * 格式化文件大小
+ */
+export declare function formatFileSize(bytes: number): string;
 export {};

package/dist/tools/helpers.js

@@ -81,3 +81,14 @@ export function countTreeDocs(tree) {
     traverse(tree);
     return count;
 }
+// ==================== 文件大小格式化 ====================
+/**
+ * 格式化文件大小
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/dist/tools/index.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
 import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
-import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs } from './helpers.js';
+import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs, formatFileSize } from './helpers.js';
 export function registerTools(server, projectId, _user) {
     // ===================== 跨项目访问 =====================
     // 0. 列出所有可访问的项目
@@ -21,6 +21,21 @@ export function registerTools(server, projectId, _user) {
             return wrap(`获取项目列表失败: ${String(e)}`);
         }
     });
+    // 0.1 创建项目
+    server.tool('kg_create_project', '创建新项目。返回项目ID和密码(密码用于MCP连接)', {
+        id: z.string().describe('项目ID(英文/数字/中文，如"my-app")'),
+        name: z.string().describe('项目名称'),
+        description: z.string().optional().describe('项目简介'),
+        projectPath: z.string().optional().describe('项目源码路径(本地绝对路径)'),
+    }, async (args) => {
+        try {
+            const result = await storage.createProject(args.id, args.name, args.description, args.projectPath);
+            return wrap(`✅ 项目创建成功\n\n- 项目ID: ${result.project.id}\n- 项目名: ${result.project.name}\n- 密码: ${result.password}\n\nMCP 连接地址: http://<服务器IP>:20001/api/${result.project.id}/${result.password}`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
     // ===================== 文档管理 =====================
     // 1. 创建文档
     server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
@@ -183,25 +198,29 @@ export function registerTools(server, projectId, _user) {
     });
     // 3.6 获取项目规则
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)。支持跨项目只读访问', {
-        ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests']).optional()
-            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部'),
+        ruleType: z.string().optional()
+            .describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)。不传则返回全部'),
         targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
     }, async (args) => {
         // 跨项目访问
         if (args.targetProject) {
+            const crossMeta = await storage.crossGetRulesMeta(args.targetProject);
             if (args.ruleType) {
                 const rules = await storage.crossGetRules(args.targetProject, args.ruleType);
                 if (rules.length === 0) {
-                    return { content: [{ type: 'text', text: `暂无${RULE_TYPE_LABELS[args.ruleType]}规则(项目: ${args.targetProject})` }] };
+                    const label = crossMeta[args.ruleType]?.label || args.ruleType;
+                    return { content: [{ type: 'text', text: `暂无${label}规则(项目: ${args.targetProject})` }] };
                 }
                 return { content: [{ type: 'text', text: `[跨项目: ${args.targetProject}]\n\n${rules.join('\n')}` }] };
             }
-            // 获取全部规则
+            // 获取全部规则 (从 meta 获取所有类型)
+            const types = Object.keys(crossMeta).length > 0 ? Object.keys(crossMeta) : Object.keys(RULE_TYPE_LABELS);
             const allRules = [];
-            for (const type of ['userStyles', 'codeStyle', 'reviewRules', 'testRules', 'unitTests']) {
+            for (const type of types) {
                 const rules = await storage.crossGetRules(args.targetProject, type);
                 if (rules.length > 0) {
-                    allRules.push(`## ${RULE_TYPE_LABELS[type]}\n${rules.join('\n')}`);
+                    const label = crossMeta[type]?.label || RULE_TYPE_LABELS[type] || type;
+                    allRules.push(`## ${label}\n${rules.join('\n')}`);
                 }
             }
             if (allRules.length === 0) {
@@ -210,17 +229,18 @@ export function registerTools(server, projectId, _user) {
             return { content: [{ type: 'text', text: `[跨项目: ${args.targetProject}]\n\n${allRules.join('\n\n')}` }] };
         }
         // 当前项目
-        const rules = await getRules(projectId, args.ruleType);
+        const rules = await getRules(projectId, args.ruleType || undefined);
         if (!rules || rules.trim() === '') {
-            const typeName = args.ruleType ? RULE_TYPE_LABELS[args.ruleType] : '项目';
+            const meta = await storage.getRulesMeta();
+            const typeName = args.ruleType ? (meta[args.ruleType]?.label || args.ruleType) : '项目';
             return { content: [{ type: 'text', text: `暂无${typeName}规则` }] };
         }
         return { content: [{ type: 'text', text: rules }] };
     });
     // 3.7 保存项目规则
     server.tool('kg_save_rules', '保存单个类型的项目规则(独立文件存储)', {
-        ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests'])
-            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则'),
+        ruleType: z.string()
+            .describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)'),
         rules: z.array(z.string()).describe('规则数组')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
@@ -228,7 +248,87 @@ export function registerTools(server, projectId, _user) {
         if (!success) {
             return wrap('❌ 保存失败');
         }
-        return wrap(`✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
+        const meta = await storage.getRulesMeta();
+        const label = meta[decoded.ruleType]?.label || decoded.ruleType;
+        return wrap(`✅ ${label}已保存 (${decoded.rules.length} 条)`);
+    });
+    // 3.8 获取规则触发配置
+    server.tool('kg_get_rules_meta', '获取规则触发配置(所有类型的标签、关键词、触发数)。用于查看/编辑 hooks 触发条件', {}, async () => {
+        try {
+            const meta = await storage.getRulesMeta();
+            if (Object.keys(meta).length === 0) {
+                return wrap('暂无规则配置');
+            }
+            const lines = Object.entries(meta).map(([type, m]) => {
+                const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
+                const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
+                return `- **${m.label}** (${type}): ${trigger}`;
+            });
+            return wrap(`规则触发配置:\n\n${lines.join('\n')}`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 3.9 保存规则触发配置
+    server.tool('kg_save_rules_meta', '保存规则触发配置(标签、关键词、触发数)。支持新增自定义规则类型', {
+        meta: z.record(z.string(), z.object({
+            label: z.string().describe('规则显示名称'),
+            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
+            min_hits: z.number().default(1).describe('最低触发关键词数'),
+            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
+        })).describe('规则类型 → 触发配置的映射')
+    }, async (args) => {
+        try {
+            const decoded = decodeObjectStrings(args.meta);
+            const success = await storage.saveRulesMeta(decoded);
+            if (!success) {
+                return wrap('❌ 保存失败');
+            }
+            return wrap(`✅ 规则触发配置已保存 (${Object.keys(decoded).length} 个类型)`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 3.10 获取全局默认规则触发配置
+    server.tool('kg_get_global_rules_meta', '获取全局默认规则触发配置(新项目创建时继承此配置)', {}, async () => {
+        try {
+            const meta = await storage.getGlobalRulesMeta();
+            if (Object.keys(meta).length === 0) {
+                return wrap('暂无全局默认规则配置');
+            }
+            const lines = Object.entries(meta).map(([type, m]) => {
+                const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
+                const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
+                return `- **${m.label}** (${type}): ${trigger}`;
+            });
+            return wrap(`全局默认规则触发配置:\n\n${lines.join('\n')}`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 3.11 保存全局默认规则触发配置
+    server.tool('kg_save_global_rules_meta', '保存全局默认规则触发配置(新项目创建时继承此配置)。支持新增自定义规则类型', {
+        meta: z.record(z.string(), z.object({
+            label: z.string().describe('规则显示名称'),
+            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
+            min_hits: z.number().default(1).describe('最低触发关键词数'),
+            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
+        })).describe('规则类型 → 触发配置的映射')
+    }, async (args) => {
+        try {
+            const decoded = decodeObjectStrings(args.meta);
+            const success = await storage.saveGlobalRulesMeta(decoded);
+            if (!success) {
+                return wrap('❌ 保存失败');
+            }
+            return wrap(`✅ 全局默认规则触发配置已保存 (${Object.keys(decoded).length} 个类型)`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
     });
     // 5. 读取单个文档详情
     server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问', {
@@ -393,4 +493,85 @@ export function registerTools(server, projectId, _user) {
         }
         return wrap(`✅ 任务已归档: ${task.title}`);
     });
+    // ===================== 项目文件访问 =====================
+    // 上传本地目录到中心服务器
+    server.tool('project_upload', '上传本地项目目录到中心服务器(打包zip上传，自动排除node_modules/.git等)。上传后其他客户端可通过跨项目访问下载', {
+        localDir: z.string().describe('本地目录的绝对路径(如"/home/user/project/src")'),
+        remoteDir: z.string().optional().describe('上传到服务器的目标子目录(如"src")，不填则上传到根目录'),
+    }, async (args) => {
+        try {
+            const result = await storage.uploadFiles(args.localDir, args.remoteDir);
+            return wrap(`✅ 上传成功\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}\n\n其他客户端可通过 project_read_file / project_download_dir 访问`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 清空项目文件存储区
+    server.tool('project_clear_files', '清空当前项目在中心服务器上的文件存储区', {}, async () => {
+        try {
+            await storage.clearFiles();
+            return wrap('✅ 文件存储已清空');
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 列出项目文件
+    server.tool('project_list_files', '列出项目源码目录下的文件。需要先上传文件或项目已关联源码目录', {
+        dir: z.string().optional().describe('子目录路径(如"src/components")，不填则列出根目录'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, async (args) => {
+        try {
+            const files = args.targetProject
+                ? await storage.crossListFiles(args.targetProject, args.dir)
+                : await storage.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 ? `[跨项目: ${args.targetProject}]\n\n` : '';
+            const dirLabel = args.dir || '/';
+            return wrap(`${prefix}📂 ${dirLabel} (${files.length} 项)\n\n${lines.join('\n')}`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 读取项目文件
+    server.tool('project_read_file', '读取项目源码文件内容(文本，限制1MB)。需要先上传文件或项目已关联源码目录', {
+        path: z.string().describe('文件路径(如"src/main.ts")'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, async (args) => {
+        try {
+            const content = args.targetProject
+                ? await storage.crossReadFile(args.targetProject, args.path)
+                : await storage.readFile(args.path);
+            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
+            return wrap(`${prefix}📄 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
+    // 下载项目目录 (zip → 自动解压)
+    server.tool('project_download_dir', '下载项目源码目录(自动打包zip并解压到本地临时目录)。需要先上传文件或项目已关联源码目录', {
+        dir: z.string().describe('目录路径(如"src")'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, async (args) => {
+        try {
+            const result = args.targetProject
+                ? await storage.crossDownloadDir(args.targetProject, args.dir)
+                : await storage.downloadDir(args.dir);
+            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
+            return wrap(`${prefix}✅ 目录已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}\n\n可直接读取该路径下的文件`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
 }

package/dist/utils.d.ts

@@ -1,12 +1,12 @@
 /**
  * MCP Server 工具函数
  */
-export type RuleType = 'userStyles' | 'testRules' | 'reviewRules' | 'codeStyle' | 'unitTests';
-export declare const RULE_TYPE_LABELS: Record<RuleType, string>;
+export type RuleType = string;
+export declare const RULE_TYPE_LABELS: Record<string, string>;
 /**
- * 获取指定类型的规则 (从独立文件读取)
+ * 获取指定类型的规则 (动态: 从 meta 获取标签)
  */
-export declare function getRules(projectId: string, ruleType?: RuleType): Promise<string>;
+export declare function getRules(projectId: string, ruleType?: string): Promise<string>;
 /**
  * 解码 Unicode 转义序列
  * 将 \uXXXX 格式的转义序列转换为实际字符

package/dist/utils.js

@@ -2,14 +2,16 @@
  * MCP Server 工具函数
  */
 import * as storage from './storage/httpClient.js';
-// 规则类型显示名
-export const RULE_TYPE_LABELS = {
+// 默认规则类型标签 (fallback)
+const DEFAULT_LABELS = {
     userStyles: '用户沟通规则',
     codeStyle: '编码风格规则',
     reviewRules: '代码审查规则',
     testRules: '错误分析规则',
     unitTests: '代码测试规则',
 };
+// 兼容导出
+export const RULE_TYPE_LABELS = DEFAULT_LABELS;
 /**
  * 将字符串数组格式化为 Markdown 列表
  */
@@ -19,22 +21,25 @@ function formatRulesList(rules) {
     return rules.map((s, i) => `${i + 1}. ${s}`).join('\n\n');
 }
 /**
- * 获取指定类型的规则 (从独立文件读取)
+ * 获取指定类型的规则 (动态: 从 meta 获取标签)
  */
 export async function getRules(projectId, ruleType) {
-    // 如果指定了类型，只返回该类型
+    const meta = await storage.getRulesMeta();
     if (ruleType) {
         const rules = await storage.getRules(projectId, ruleType);
         if (!rules || rules.length === 0)
             return '';
-        return `[${RULE_TYPE_LABELS[ruleType]}]\n${formatRulesList(rules)}`;
+        const label = meta[ruleType]?.label || DEFAULT_LABELS[ruleType] || ruleType;
+        return `[${label}]\n${formatRulesList(rules)}`;
     }
-    // 返回所有规则
+    // 返回所有规则 (从 meta 获取所有类型)
+    const types = Object.keys(meta).length > 0 ? Object.keys(meta) : Object.keys(DEFAULT_LABELS);
     const allRules = [];
-    for (const type of Object.keys(RULE_TYPE_LABELS)) {
+    for (const type of types) {
         const rules = await storage.getRules(projectId, type);
         if (rules && rules.length > 0) {
-            allRules.push(`[${RULE_TYPE_LABELS[type]}]\n${formatRulesList(rules)}`);
+            const label = meta[type]?.label || DEFAULT_LABELS[type] || type;
+            allRules.push(`[${label}]\n${formatRulesList(rules)}`);
         }
     }
     return allRules.join('\n\n---\n\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.9.0",
+  "version": "3.0.1",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -30,12 +30,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "proper-lockfile": "^4.1.2",
+    "adm-zip": "^0.5.16",
     "zod": "^4.1.13"
   },
   "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
     "@types/node": "^22.0.0",
-    "@types/proper-lockfile": "^4.1.4",
     "typescript": "^5.7.0"
   }
 }

package/templates/hooks/hook.py

@@ -1,71 +1,46 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """
-Claude Code Hook - 关键词触发 + API 动态获取规则
+Claude Code Hook - 动态规则触发
+从服务器获取触发配置 (rules-meta) → 关键词匹配 → 叠加获取规则
+兼容 Python 2.7+ / 3.x，支持 Windows / macOS / Linux
 """
 
+from __future__ import print_function, unicode_literals
+
 import io
 import json
 import os
 import sys
-import urllib.request
 
-# Windows 编码修复
-sys.stdin = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8", errors="replace")
-sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
-sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+# HTTP 库兼容
+try:
+    from urllib.request import Request, urlopen
+except ImportError:
+    from urllib2 import Request, urlopen
+
+# Windows 编码修复 (仅 Windows + Python 3 + 有 buffer 属性时)
+if sys.platform == "win32" and hasattr(sys.stdin, "buffer"):
+    try:
+        sys.stdin = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8", errors="replace")
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+    except Exception:
+        pass
 
 
 # ╔══════════════════════════════════════════════════════════════╗
-# ║  配置区                                                       ║
+# ║  绕过词                                                       ║
 # ╚══════════════════════════════════════════════════════════════╝
 
-# 关键词规则 (触发关键词 → 请求对应规则类型)
-RULES = [
-    {
-        "keywords": ["bug","修复","错误","报错","失败","异常","严重","存在","还是","有"],
-        "min_hits": 2,
-        "rule_type": "testRules",  # 错误分析规则
-        "label": "错误分析规则",
-    },
-    {
-        "keywords": ["审查", "审核", "review", "检查"],
-        "min_hits": 1,
-        "rule_type": "reviewRules",  # 审查规则
-        "label": "代码审查规则",
-    },
-    {
-        "keywords": ["编码", "风格", "格式", "命名", "编写", "开始", "代码"],
-        "min_hits": 2,
-        "rule_type": "codeStyle",  # 编码风格
-        "label": "编码风格规则",
-    },
-    {
-        "keywords": ["开始", "进行", "准备", "测试", "单元", "用例", "test", "覆盖率"],
-        "min_hits": 2,
-        "rule_type": "unitTests",  # 代码测试
-        "label": "代码测试规则",
-    },
-]
-
-# 绕过词列表
 BYPASS = [
-    "补充",
-    "确定",
-    "确认",
-    "继续",
-    "好的",
-    "可以",
-    "ok",
-    "yes",
-    "hi",
-    "hello",
-    "你好",
+    "补充", "确定", "确认", "继续", "好的", "可以",
+    "ok", "yes", "hi", "hello", "你好",
 ]
 
 
 # ╔══════════════════════════════════════════════════════════════╗
-# ║  API 请求函数                                                  ║
+# ║  API 请求                                                      ║
 # ╚══════════════════════════════════════════════════════════════╝
 
 
@@ -75,25 +50,42 @@ def load_ppdocs_config():
     if not os.path.exists(config_path):
         return None
     try:
-        with open(config_path, "r", encoding="utf-8") as f:
+        with io.open(config_path, "r", encoding="utf-8") as f:
             return json.load(f)
-    except:
+    except Exception:
         return None
 
 
-def fetch_rules(api_base: str, project_id: str, key: str, rule_type: str) -> list:
-    """通过 HTTP API 获取指定类型的规则"""
-    url = f"{api_base}/api/{project_id}/{key}/rules/{rule_type}"
+def api_get(api_base, project_id, key, path):
+    """通用 GET 请求"""
+    url = "%s/api/%s/%s%s" % (api_base, project_id, key, path)
+    resp = None
     try:
-        req = urllib.request.Request(url, method="GET")
+        req = Request(url)
         req.add_header("Content-Type", "application/json")
-        with urllib.request.urlopen(req, timeout=3) as resp:
-            data = json.loads(resp.read().decode("utf-8"))
-            if data.get("success") and data.get("data"):
-                return data["data"]
-    except:
+        resp = urlopen(req, timeout=3)
+        data = json.loads(resp.read().decode("utf-8"))
+        if data.get("success") and data.get("data") is not None:
+            return data["data"]
+    except Exception:
         pass
-    return []
+    finally:
+        if resp is not None:
+            try:
+                resp.close()
+            except Exception:
+                pass
+    return None
+
+
+def fetch_rules_meta(api_base, project_id, key):
+    """获取规则触发配置"""
+    return api_get(api_base, project_id, key, "/rules-meta") or {}
+
+
+def fetch_rules(api_base, project_id, key, rule_type):
+    """获取指定类型的规则内容"""
+    return api_get(api_base, project_id, key, "/rules/" + rule_type) or []
 
 
 # ╔══════════════════════════════════════════════════════════════╗
@@ -101,27 +93,32 @@ def fetch_rules(api_base: str, project_id: str, key: str, rule_type: str) -> lis
 # ╚══════════════════════════════════════════════════════════════╝
 
 
-def count_hits(text: str, keywords: list) -> int:
+def count_hits(text, keywords):
     """计算关键词命中数量"""
     return sum(1 for kw in keywords if kw.lower() in text)
 
 
-def match_rule(text: str):
-    """匹配规则，返回 (rule, matched)"""
-    for rule in RULES:
-        hits = count_hits(text, rule["keywords"])
-        if hits >= rule.get("min_hits", 1):
-            return rule, True
-    return None, False
+def match_all(text, meta):
+    """匹配所有触发的规则类型，返回 [(rule_type, label), ...]"""
+    matched = []
+    for rule_type, config in meta.items():
+        if config.get("always"):
+            matched.append((rule_type, config.get("label", rule_type)))
+            continue
+        keywords = config.get("keywords", [])
+        min_hits = config.get("min_hits", 1)
+        if keywords and count_hits(text, keywords) >= min_hits:
+            matched.append((rule_type, config.get("label", rule_type)))
+    return matched
 
 
-def format_rules(items: list, label: str) -> str:
+def format_rules(items, label):
     """格式化规则输出"""
     if not items:
         return ""
-    lines = [f"# {label}\n"]
+    lines = ["# %s\n" % label]
     for item in items:
-        lines.append(f"- {item}")
+        lines.append("- %s" % item)
     return "\n".join(lines)
 
 
@@ -132,8 +129,9 @@ def format_rules(items: list, label: str) -> str:
 
 def main():
     try:
-        data = json.load(sys.stdin)
-    except:
+        raw = sys.stdin.read()
+        data = json.loads(raw)
+    except Exception:
         return
 
     if data.get("hook_event_name") != "UserPromptSubmit":
@@ -163,19 +161,22 @@ def main():
     if not project_id or not key:
         return
 
-    output_parts = []
+    # 从服务器获取触发配置
+    meta = fetch_rules_meta(api_base, project_id, key)
+    if not meta:
+        return
 
-    # 1. 强制获取 userStyles (用户沟通规则)
-    user_styles = fetch_rules(api_base, project_id, key, "userStyles")
-    if user_styles:
-        output_parts.append(format_rules(user_styles, "用户沟通规则"))
-
-    # 2. 根据关键词匹配额外规则
-    rule, matched = match_rule(user_input_lower)
-    if matched and rule["rule_type"] != "userStyles":
-        extra_rules = fetch_rules(api_base, project_id, key, rule["rule_type"])
-        if extra_rules:
-            output_parts.append(format_rules(extra_rules, rule["label"]))
+    # 匹配所有触发的规则
+    matched = match_all(user_input_lower, meta)
+    if not matched:
+        return
+
+    # 叠加获取所有命中的规则内容
+    output_parts = []
+    for rule_type, label in matched:
+        rules = fetch_rules(api_base, project_id, key, rule_type)
+        if rules:
+            output_parts.append(format_rules(rules, label))
 
     # 输出
     if output_parts: