@ppdocs/mcp 2.6.19 → 2.6.20

package/dist/storage/httpClient.d.ts

@@ -52,6 +52,8 @@ 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>;
+    getRulesApi(ruleType: string): Promise<string[]>;
+    saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listNodes(_projectId: string, filter?: ListNodesFilter): Promise<NodeData[]>;
@@ -92,3 +94,5 @@ 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 getRules(_projectId: string, ruleType: string): Promise<string[]>;
+export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;

package/dist/storage/httpClient.js

@@ -339,6 +339,27 @@ export class PpdocsApiClient {
             return null;
         }
     }
+    // ============ 规则 API (独立文件存储) ============
+    async getRulesApi(ruleType) {
+        try {
+            return await this.request(`/rules/${ruleType}`);
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveRulesApi(ruleType, rules) {
+        try {
+            await this.request(`/rules/${ruleType}`, {
+                method: 'PUT',
+                body: JSON.stringify(rules)
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
 }
 // ============ 模块级 API (兼容现有 tools/index.ts) ============
 let client = null;
@@ -401,3 +422,10 @@ export async function addTaskLog(_projectId, taskId, logType, content) {
 export async function completeTask(_projectId, taskId, experience) {
     return getClient().completeTask(taskId, experience);
 }
+// ============ 规则管理 (独立文件存储) ============
+export async function getRules(_projectId, ruleType) {
+    return getClient().getRulesApi(ruleType);
+}
+export async function saveRules(_projectId, ruleType, rules) {
+    return getClient().saveRulesApi(ruleType, rules);
+}

package/dist/tools/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-import { decodeUnicodeEscapes, decodeObjectStrings, wrapResult, clearStyleCache, getRules, RULE_TYPE_LABELS } from '../utils.js';
+import { decodeUnicodeEscapes, decodeObjectStrings, wrapResult, getRules, RULE_TYPE_LABELS } from '../utils.js';
 // 辅助函数: 包装返回结果
 async function wrap(projectId, text) {
     const wrapped = await wrapResult(projectId, text);
@@ -90,33 +90,19 @@ export function registerTools(server, projectId, _user) {
         const node = await storage.updateNode(projectId, nodeId, updates);
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
     });
-    // 3.5 更新根节点 (专用方法，支持所有规则)
-    server.tool('kg_update_root', '更新根节点(项目规则，锁定时不可更新)', {
+    // 3.5 更新根节点 (项目介绍)
+    server.tool('kg_update_root', '更新项目介绍(根节点描述，锁定时不可更新)', {
         title: z.string().optional().describe('项目标题'),
-        description: z.string().optional().describe('项目描述(Markdown)'),
-        userStyles: z.array(z.string()).optional().describe('项目规则(字符串数组)'),
-        testRules: z.array(z.string()).optional().describe('测试规则(字符串数组)'),
-        reviewRules: z.array(z.string()).optional().describe('审查规则(字符串数组)'),
-        codeStyle: z.array(z.string()).optional().describe('编码风格(字符串数组)')
+        description: z.string().optional().describe('项目介绍(Markdown)')
     }, async (args) => {
-        // 空参数检查
-        const hasUpdate = args.title !== undefined || args.description !== undefined ||
-            args.userStyles !== undefined || args.testRules !== undefined ||
-            args.reviewRules !== undefined || args.codeStyle !== undefined;
-        if (!hasUpdate) {
-            return wrap(projectId, '❌ 请至少提供一个更新参数');
+        if (args.title === undefined && args.description === undefined) {
+            return wrap(projectId, '❌ 请至少提供 title 或 description');
         }
         const node = await storage.updateRoot(projectId, {
             title: args.title,
-            description: args.description,
-            userStyles: args.userStyles,
-            testRules: args.testRules,
-            reviewRules: args.reviewRules,
-            codeStyle: args.codeStyle
+            description: args.description
         });
-        if (node)
-            clearStyleCache();
-        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(根节点已锁定)');
+        return wrap(projectId, node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
     });
     // 3.6 获取项目规则 (独立方法，按需调用)
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
@@ -130,6 +116,18 @@ export function registerTools(server, projectId, _user) {
         }
         return { content: [{ type: 'text', text: rules }] };
     });
+    // 3.7 保存项目规则 (独立存储)
+    server.tool('kg_save_rules', '保存单个类型的项目规则(独立文件存储)', {
+        ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle'])
+            .describe('规则类型: userStyles=项目规则, testRules=测试规则, reviewRules=审查规则, codeStyle=编码风格'),
+        rules: z.array(z.string()).describe('规则数组')
+    }, async (args) => {
+        const success = await storage.saveRules(projectId, args.ruleType, args.rules);
+        if (!success) {
+            return wrap(projectId, '❌ 保存失败');
+        }
+        return wrap(projectId, `✅ ${RULE_TYPE_LABELS[args.ruleType]}已保存 (${args.rules.length} 条)`);
+    });
     // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
     server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
         nodeId: z.string().describe('节点ID')
@@ -425,4 +423,40 @@ export function registerTools(server, projectId, _user) {
         }
         return wrap(projectId, `任务已完成归档: ${task.title}`);
     });
+    // 15. 查询文件关联的节点
+    server.tool('kg_find_by_file', '查询哪些节点绑定了指定文件(删除/重命名前检查)', {
+        filePath: z.string().describe('文件相对路径，如 src/utils/format.ts')
+    }, async (args) => {
+        const nodes = await storage.listNodes(projectId);
+        const filePath = args.filePath.replace(/\\/g, '/'); // 统一为正斜杠
+        // 查找所有绑定了该文件的节点
+        const boundBy = [];
+        for (const node of nodes) {
+            if (node.relatedFiles && node.relatedFiles.length > 0) {
+                // 检查是否包含该文件 (支持部分匹配)
+                const hasFile = node.relatedFiles.some(f => {
+                    const normalizedF = f.replace(/\\/g, '/');
+                    return normalizedF === filePath ||
+                        normalizedF.endsWith('/' + filePath) ||
+                        filePath.endsWith('/' + normalizedF);
+                });
+                if (hasFile) {
+                    boundBy.push({
+                        id: node.id,
+                        title: node.title,
+                        type: node.type,
+                        status: node.status
+                    });
+                }
+            }
+        }
+        const result = {
+            file: filePath,
+            boundBy,
+            message: boundBy.length > 0
+                ? `⚠️ 该文件被 ${boundBy.length} 个节点引用，删除前请更新节点`
+                : '✅ 该文件无 KG 引用，可安全操作'
+        };
+        return wrap(projectId, JSON.stringify(result, null, 2));
+    });
 }

package/dist/utils.d.ts

@@ -4,7 +4,7 @@
 export type RuleType = 'userStyles' | 'testRules' | 'reviewRules' | 'codeStyle';
 export declare const RULE_TYPE_LABELS: Record<RuleType, string>;
 /**
- * 获取指定类型的规则
+ * 获取指定类型的规则 (从独立文件读取)
  */
 export declare function getRules(projectId: string, ruleType?: RuleType): Promise<string>;
 /**
@@ -12,7 +12,7 @@ export declare function getRules(projectId: string, ruleType?: RuleType): Promis
  */
 export declare function getRootStyle(projectId: string): Promise<string>;
 /**
- * 清除规则缓存 (当根节点更新时调用)
+ * 清除规则缓存 (保留接口兼容性，实际无需缓存)
  */
 export declare function clearStyleCache(): void;
 /**

package/dist/utils.js

@@ -9,9 +9,6 @@ export const RULE_TYPE_LABELS = {
     reviewRules: '审查规则',
     codeStyle: '编码风格',
 };
-// 缓存根节点 (避免每次调用都请求)
-let cachedRootNode = null;
-let cacheProjectId = null;
 /**
  * 将字符串数组格式化为 Markdown 列表
  */
@@ -21,32 +18,12 @@ function formatRulesList(rules) {
     return rules.map((s, i) => `${i + 1}. ${s}`).join('\n\n');
 }
 /**
- * 获取根节点数据 (带缓存)
- */
-async function getCachedRoot(projectId) {
-    if (cachedRootNode !== null && cacheProjectId === projectId) {
-        return cachedRootNode;
-    }
-    try {
-        const rootNode = await storage.getNode(projectId, 'root');
-        cachedRootNode = rootNode;
-        cacheProjectId = projectId;
-        return cachedRootNode;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * 获取指定类型的规则
+ * 获取指定类型的规则 (从独立文件读取)
  */
 export async function getRules(projectId, ruleType) {
-    const rootNode = await getCachedRoot(projectId);
-    if (!rootNode)
-        return '';
     // 如果指定了类型，只返回该类型
     if (ruleType) {
-        const rules = rootNode[ruleType];
+        const rules = await storage.getRules(projectId, ruleType);
         if (!rules || rules.length === 0)
             return '';
         return `[${RULE_TYPE_LABELS[ruleType]}]\n${formatRulesList(rules)}`;
@@ -54,7 +31,7 @@ export async function getRules(projectId, ruleType) {
     // 返回所有规则
     const allRules = [];
     for (const type of Object.keys(RULE_TYPE_LABELS)) {
-        const rules = rootNode[type];
+        const rules = await storage.getRules(projectId, type);
         if (rules && rules.length > 0) {
             allRules.push(`[${RULE_TYPE_LABELS[type]}]\n${formatRulesList(rules)}`);
         }
@@ -68,11 +45,10 @@ export async function getRootStyle(projectId) {
     return getRules(projectId, 'userStyles');
 }
 /**
- * 清除规则缓存 (当根节点更新时调用)
+ * 清除规则缓存 (保留接口兼容性，实际无需缓存)
  */
 export function clearStyleCache() {
-    cachedRootNode = null;
-    cacheProjectId = null;
+    // 独立文件存储无需缓存
 }
 /**
  * 包装工具返回结果 (不再自动注入规则，使用 kg_get_rules 按需获取)

package/package.json

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