@ppdocs/mcp 2.6.19 → 2.6.21

package/dist/cli.js

@@ -232,12 +232,10 @@ function copyDirRecursive(src, dest) {
         }
     }
 }
-/** 生成跨平台的 hooks 配置 */
+/** 生成跨平台的 hooks 配置 (调用 python hook.py) */
 function generateHooksConfig() {
-    const isWindows = process.platform === 'win32';
-    const command = isWindows
-        ? 'type ".claude\\hooks\\SystemPrompt.md"'
-        : 'cat ".claude/hooks/SystemPrompt.md"';
+    // hook.py 支持关键词动态匹配，比静态读取 MD 更灵活
+    const command = 'python .claude/hooks/hook.py';
     return {
         hooks: {
             UserPromptSubmit: [

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);
@@ -21,18 +21,19 @@ export function registerTools(server, projectId, _user) {
         })).optional().describe('依赖列表(自动生成连线)'),
         relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组，如 ["src/auth.ts"]')
     }, async (args) => {
+        const decoded = decodeObjectStrings(args);
         const node = await storage.createNode(projectId, {
-            title: args.title,
-            type: args.type,
+            title: decoded.title,
+            type: decoded.type,
             status: 'incomplete',
-            description: args.description || '',
+            description: decoded.description || '',
             // x, y 不传递，由 httpClient 智能计算位置
             locked: false,
-            signature: args.signature || args.title,
-            categories: args.tags,
-            path: args.path,
-            dependencies: args.dependencies || [],
-            relatedFiles: args.relatedFiles || []
+            signature: decoded.signature || decoded.title,
+            categories: decoded.tags,
+            path: decoded.path,
+            dependencies: decoded.dependencies || [],
+            relatedFiles: decoded.relatedFiles || []
         });
         return wrap(projectId, JSON.stringify(node, null, 2));
     });
@@ -70,7 +71,8 @@ export function registerTools(server, projectId, _user) {
             impact: z.string().optional()
         })).optional().describe('修复记录')
     }, async (args) => {
-        const { nodeId, tags, relatedFiles, versions, bugfixes, path, ...rest } = args;
+        const decoded = decodeObjectStrings(args);
+        const { nodeId, tags, relatedFiles, versions, bugfixes, path, ...rest } = decoded;
         // 根节点必须使用 kg_update_root 更新
         if (nodeId === 'root') {
             return wrap(projectId, '❌ 根节点请使用 kg_update_root 方法更新');
@@ -90,38 +92,25 @@ 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, '❌ 请至少提供一个更新参数');
+        const decoded = decodeObjectStrings(args);
+        if (decoded.title === undefined && decoded.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
+            title: decoded.title,
+            description: decoded.description
         });
-        if (node)
-            clearStyleCache();
-        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(根节点已锁定)');
+        return wrap(projectId, node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
     });
     // 3.6 获取项目规则 (独立方法，按需调用)
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
-        ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle']).optional()
-            .describe('规则类型: userStyles=项目规则, testRules=测试规则, reviewRules=审查规则, codeStyle=编码风格。不传则返回全部')
+        ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests']).optional()
+            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部')
     }, async (args) => {
         const rules = await getRules(projectId, args.ruleType);
         if (!rules || rules.trim() === '') {
@@ -130,6 +119,19 @@ 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', 'unitTests'])
+            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则'),
+        rules: z.array(z.string()).describe('规则数组')
+    }, async (args) => {
+        const decoded = decodeObjectStrings(args);
+        const success = await storage.saveRules(projectId, decoded.ruleType, decoded.rules);
+        if (!success) {
+            return wrap(projectId, '❌ 保存失败');
+        }
+        return wrap(projectId, `✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
+    });
     // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
     server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
         nodeId: z.string().describe('节点ID')
@@ -425,4 +427,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

@@ -1,10 +1,10 @@
 /**
  * MCP Server 工具函数
  */
-export type RuleType = 'userStyles' | 'testRules' | 'reviewRules' | 'codeStyle';
+export type RuleType = 'userStyles' | 'testRules' | 'reviewRules' | 'codeStyle' | 'unitTests';
 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

@@ -4,14 +4,12 @@
 import * as storage from './storage/httpClient.js';
 // 规则类型显示名
 export const RULE_TYPE_LABELS = {
-    userStyles: '项目规则',
-    testRules: '测试规则',
-    reviewRules: '审查规则',
-    codeStyle: '编码风格',
+    userStyles: '用户沟通规则',
+    codeStyle: '编码风格规则',
+    reviewRules: '代码审查规则',
+    testRules: '错误分析规则',
+    unitTests: '代码测试规则',
 };
-// 缓存根节点 (避免每次调用都请求)
-let cachedRootNode = null;
-let cacheProjectId = null;
 /**
  * 将字符串数组格式化为 Markdown 列表
  */
@@ -21,32 +19,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 +32,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 +46,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.21",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",

package/templates/hooks/hook.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Claude Code Hook - 关键词触发 + API 动态获取规则
+"""
+
+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")
+
+
+# ╔══════════════════════════════════════════════════════════════╗
+# ║  配置区                                                       ║
+# ╚══════════════════════════════════════════════════════════════╝
+
+# 关键词规则 (触发关键词 → 请求对应规则类型)
+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",
+    "你好",
+]
+
+
+# ╔══════════════════════════════════════════════════════════════╗
+# ║  API 请求函数                                                  ║
+# ╚══════════════════════════════════════════════════════════════╝
+
+
+def load_ppdocs_config():
+    """读取 .ppdocs 配置"""
+    config_path = os.path.join(os.getcwd(), ".ppdocs")
+    if not os.path.exists(config_path):
+        return None
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except:
+        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}"
+    try:
+        req = urllib.request.Request(url, method="GET")
+        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:
+        pass
+    return []
+
+
+# ╔══════════════════════════════════════════════════════════════╗
+# ║  匹配逻辑                                                      ║
+# ╚══════════════════════════════════════════════════════════════╝
+
+
+def count_hits(text: str, keywords: list) -> int:
+    """计算关键词命中数量"""
+    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 format_rules(items: list, label: str) -> str:
+    """格式化规则输出"""
+    if not items:
+        return ""
+    lines = [f"# {label}\n"]
+    for item in items:
+        lines.append(f"- {item}")
+    return "\n".join(lines)
+
+
+# ╔══════════════════════════════════════════════════════════════╗
+# ║  主入口                                                        ║
+# ╚══════════════════════════════════════════════════════════════╝
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except:
+        return
+
+    if data.get("hook_event_name") != "UserPromptSubmit":
+        return
+
+    user_input = data.get("prompt", "").strip()
+    if not user_input:
+        return
+
+    user_input_lower = user_input.lower()
+
+    # 短输入包含绕过词 → 跳过
+    if len(user_input) <= 15:
+        for word in BYPASS:
+            if word.lower() in user_input_lower:
+                return
+
+    # 读取配置
+    config = load_ppdocs_config()
+    if not config:
+        return
+
+    api_base = config.get("api", "http://localhost:20001")
+    project_id = config.get("projectId", "")
+    key = config.get("key", "")
+
+    if not project_id or not key:
+        return
+
+    output_parts = []
+
+    # 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"]))
+
+    # 输出
+    if output_parts:
+        print("\n\n".join(output_parts))
+
+
+if __name__ == "__main__":
+    main()