@ppdocs/mcp 2.6.4 → 2.6.6

package/dist/cli.js

@@ -135,39 +135,50 @@ function commandExists(cmd) {
         return false;
     }
 }
+/** 静默执行命令 (忽略错误) */
+function execSilent(cmd) {
+    try {
+        execSync(cmd, { stdio: 'ignore' });
+    }
+    catch { /* ignore */ }
+}
 /** 自动检测 AI CLI 并注册 MCP */
 function autoRegisterMcp(apiUrl, user) {
     const detected = [];
+    const serverName = 'ppdocs-kg';
     // 检测 Claude CLI
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            const cmd = `claude mcp add ppdocs-kg -e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user} -- npx -y @ppdocs/mcp@latest`;
             console.log(`✅ Detected Claude CLI, registering MCP...`);
+            execSilent(`claude mcp remove ${serverName}`);
+            const cmd = `claude mcp add ${serverName} -e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user} -- npx -y @ppdocs/mcp@latest`;
             execSync(cmd, { stdio: 'inherit' });
         }
         catch (e) {
             console.log(`⚠️  Claude MCP registration failed: ${e}`);
         }
     }
-    // 检测 Codex CLI (OpenAI)
+    // 检测 Codex CLI (OpenAI) - 使用 --env 而非 -e
     if (commandExists('codex')) {
         detected.push('Codex');
         try {
-            const cmd = `codex mcp add ppdocs-kg -e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user} -- npx -y @ppdocs/mcp@latest`;
             console.log(`✅ Detected Codex CLI, registering MCP...`);
+            execSilent(`codex mcp remove ${serverName}`);
+            const cmd = `codex mcp add ${serverName} --env PPDOCS_API_URL=${apiUrl} --env PPDOCS_USER=${user} -- npx -y @ppdocs/mcp@latest`;
             execSync(cmd, { stdio: 'inherit' });
         }
         catch (e) {
             console.log(`⚠️  Codex MCP registration failed: ${e}`);
         }
     }
-    // 检测 Gemini CLI
+    // 检测 Gemini CLI - 命令在位置参数，-e 在后面
     if (commandExists('gemini')) {
         detected.push('Gemini');
         try {
-            const cmd = `gemini mcp add ppdocs-kg -e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user} -- npx -y @ppdocs/mcp@latest`;
             console.log(`✅ Detected Gemini CLI, registering MCP...`);
+            execSilent(`gemini mcp remove ${serverName}`);
+            const cmd = `gemini mcp add ${serverName} "npx -y @ppdocs/mcp@latest" -e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user}`;
             execSync(cmd, { stdio: 'inherit' });
         }
         catch (e) {

package/dist/storage/httpClient.d.ts

@@ -13,6 +13,11 @@ export declare class PpdocsApiClient {
     getNode(nodeId: string): Promise<NodeData | null>;
     createNode(node: Partial<NodeData>): Promise<NodeData>;
     updateNode(nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
+    updateRoot(updates: {
+        title?: string;
+        description?: string;
+        userStyles?: string[];
+    }): Promise<NodeData | null>;
     deleteNode(nodeId: string): Promise<boolean>;
     lockNode(nodeId: string, locked: boolean): Promise<NodeData | null>;
     searchNodes(keywords: string[], limit?: number): Promise<SearchResult[]>;
@@ -51,6 +56,11 @@ export declare function listNodes(_projectId: string): Promise<NodeData[]>;
 export declare function getNode(_projectId: string, nodeId: string): Promise<NodeData | null>;
 export declare function createNode(_projectId: string, node: Partial<NodeData>): Promise<NodeData>;
 export declare function updateNode(_projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
+export declare function updateRoot(_projectId: string, updates: {
+    title?: string;
+    description?: string;
+    userStyles?: string[];
+}): Promise<NodeData | null>;
 export declare function deleteNode(_projectId: string, nodeId: string): Promise<boolean>;
 export declare function lockNode(_projectId: string, nodeId: string, locked: boolean): Promise<NodeData | null>;
 export declare function searchNodes(_projectId: string, keywords: string[], limit?: number): Promise<SearchResult[]>;

package/dist/storage/httpClient.js

@@ -4,6 +4,59 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
+// ============ 智能定位算法 ============
+const SMART_NODE_GAP = 180;
+const SMART_SEARCH_RADIUS = 10;
+/**
+ * 计算新节点的智能位置 (关联中心 + 螺旋搜索空位)
+ */
+function computeSmartPosition(deps, nodes) {
+    // 1. 找关联节点
+    const related = [];
+    if (deps && deps.length > 0) {
+        const depNames = deps.map(d => d.name.toLowerCase());
+        nodes.forEach(n => {
+            if (n.signature && depNames.some(name => n.signature.toLowerCase().startsWith(name))) {
+                related.push(n);
+            }
+        });
+    }
+    // 2. 计算中心点
+    let cx, cy;
+    if (related.length > 0) {
+        cx = related.reduce((s, n) => s + n.x, 0) / related.length;
+        cy = related.reduce((s, n) => s + n.y, 0) / related.length + SMART_NODE_GAP;
+    }
+    else {
+        const root = nodes.find(n => n.isOrigin);
+        cx = root?.x ?? 0;
+        cy = (root?.y ?? 0) + SMART_NODE_GAP;
+    }
+    // 3. 碰撞检测
+    const collides = (x, y) => nodes.some(n => Math.abs(n.x - x) < SMART_NODE_GAP && Math.abs(n.y - y) < SMART_NODE_GAP * 0.6);
+    if (!collides(cx, cy))
+        return { x: Math.round(cx), y: Math.round(cy) };
+    // 4. 螺旋搜索
+    const dirs = [[1, 0], [0, 1], [-1, 0], [0, -1]];
+    let x = cx, y = cy, step = 1, dir = 0, steps = 0, turns = 0;
+    for (let i = 0; i < SMART_SEARCH_RADIUS * SMART_SEARCH_RADIUS * 4; i++) {
+        x += dirs[dir][0] * SMART_NODE_GAP;
+        y += dirs[dir][1] * SMART_NODE_GAP * 0.6;
+        steps++;
+        if (!collides(x, y))
+            return { x: Math.round(x), y: Math.round(y) };
+        if (steps >= step) {
+            steps = 0;
+            dir = (dir + 1) % 4;
+            if (++turns >= 2) {
+                turns = 0;
+                step++;
+            }
+        }
+    }
+    const maxX = Math.max(...nodes.map(n => n.x), 0);
+    return { x: Math.round(maxX + SMART_NODE_GAP), y: Math.round(cy) };
+}
 // API 客户端类
 export class PpdocsApiClient {
     baseUrl; // http://localhost:20001/api/projectId/password
@@ -58,20 +111,29 @@ export class PpdocsApiClient {
         }
     }
     async createNode(node) {
-        // 自动布局: 未指定位置时服务端会计算
+        // 智能定位: 计算新节点位置
+        let x = node.x ?? 0;
+        let y = node.y ?? 0;
+        // 如果未指定位置，自动计算
+        if (node.x === undefined && node.y === undefined) {
+            const existingNodes = await this.listNodes();
+            const pos = computeSmartPosition(node.dependencies, existingNodes);
+            x = pos.x;
+            y = pos.y;
+        }
         const payload = {
             id: '', // 服务端自动生成
             title: node.title || '',
             type: node.type || 'logic',
             status: node.status || 'incomplete',
-            x: node.x ?? 0,
-            y: node.y ?? 0,
+            x,
+            y,
             locked: false,
             signature: node.signature || node.title || '',
             categories: node.categories || [],
             description: node.description || '',
             dependencies: node.dependencies || [],
-            relatedFiles: [],
+            relatedFiles: node.relatedFiles || [],
             createdAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
             lastAccessedAt: new Date().toISOString(),
@@ -103,6 +165,31 @@ export class PpdocsApiClient {
             return null;
         }
     }
+    async updateRoot(updates) {
+        // 专用根节点更新，支持 userStyles
+        const root = await this.getNode('root');
+        if (!root)
+            return null;
+        if (root.locked)
+            return null; // 锁定时拒绝
+        // 构建更新载荷 (只传入有值的字段)
+        const payload = { updatedAt: new Date().toISOString() };
+        if (updates.title !== undefined)
+            payload.title = updates.title;
+        if (updates.description !== undefined)
+            payload.description = updates.description;
+        if (updates.userStyles !== undefined)
+            payload.userStyles = updates.userStyles;
+        try {
+            return await this.request('/nodes/root', {
+                method: 'PUT',
+                body: JSON.stringify({ ...root, ...payload })
+            });
+        }
+        catch {
+            return null;
+        }
+    }
     async deleteNode(nodeId) {
         try {
             await this.request(`/nodes/${nodeId}`, { method: 'DELETE' });
@@ -187,7 +274,6 @@ export class PpdocsApiClient {
         }
     }
     async createTask(task, creator) {
-        const now = new Date().toISOString();
         const payload = {
             title: task.title,
             creator,
@@ -249,6 +335,9 @@ export async function createNode(_projectId, node) {
 export async function updateNode(_projectId, nodeId, updates) {
     return getClient().updateNode(nodeId, updates);
 }
+export async function updateRoot(_projectId, updates) {
+    return getClient().updateRoot(updates);
+}
 export async function deleteNode(_projectId, nodeId) {
     return getClient().deleteNode(nodeId);
 }

package/dist/storage/types.d.ts

@@ -45,6 +45,7 @@ export interface NodeData {
     dataOutput?: DataRef;
     dependencies: Dependency[];
     relatedFiles?: string[];
+    userStyles?: string[];
     createdAt?: string;
     updatedAt?: string;
     lastAccessedAt?: string;

package/dist/tools/index.js

@@ -1,5 +1,11 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
+import { decodeUnicodeEscapes, decodeObjectStrings, wrapResult, clearStyleCache } from '../utils.js';
+// 辅助函数: 包装返回结果
+async function wrap(projectId, text) {
+    const wrapped = await wrapResult(projectId, text);
+    return { content: [{ type: 'text', text: wrapped }] };
+}
 export function registerTools(server, projectId, _user) {
     // 1. 创建节点
     server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
@@ -19,20 +25,19 @@ export function registerTools(server, projectId, _user) {
             type: args.type,
             status: 'incomplete',
             description: args.description || '',
-            x: 0, // 服务端自动布局
-            y: 0,
+            // x, y 不传递，由 httpClient 智能计算位置
             locked: false,
             signature: args.signature || args.title,
             categories: args.tags || [],
             dependencies: args.dependencies || [],
             relatedFiles: args.relatedFiles || []
         });
-        return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
+        return wrap(projectId, JSON.stringify(node, null, 2));
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
         const success = await storage.deleteNode(projectId, args.nodeId);
-        return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
+        return wrap(projectId, success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
     });
     // 3. 更新节点
     server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)', {
@@ -49,6 +54,10 @@ export function registerTools(server, projectId, _user) {
         relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组')
     }, async (args) => {
         const { nodeId, tags, relatedFiles, ...rest } = args;
+        // 根节点必须使用 kg_update_root 更新
+        if (nodeId === 'root') {
+            return wrap(projectId, '❌ 根节点请使用 kg_update_root 方法更新');
+        }
         // API 参数 tags 转换为内部字段 categories
         let updates = { ...rest };
         if (tags !== undefined)
@@ -56,14 +65,33 @@ export function registerTools(server, projectId, _user) {
         if (relatedFiles !== undefined)
             updates.relatedFiles = relatedFiles;
         const node = await storage.updateNode(projectId, nodeId, updates);
-        return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)' }] };
+        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
+    });
+    // 3.5 更新根节点 (专用方法，支持 userStyles)
+    server.tool('kg_update_root', '更新根节点(项目规则，锁定时不可更新)', {
+        title: z.string().optional().describe('项目标题'),
+        description: z.string().optional().describe('项目描述(Markdown)'),
+        userStyles: z.array(z.string()).optional().describe('项目规则列表(字符串数组，每条一个规则)')
+    }, async (args) => {
+        // 空参数检查
+        if (args.title === undefined && args.description === undefined && args.userStyles === undefined) {
+            return wrap(projectId, '❌ 请至少提供一个更新参数(title/description/userStyles)');
+        }
+        const node = await storage.updateRoot(projectId, {
+            title: args.title,
+            description: args.description,
+            userStyles: args.userStyles
+        });
+        if (node)
+            clearStyleCache();
+        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(根节点已锁定)');
     });
     // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
     server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
         nodeId: z.string().describe('节点ID')
     }, async (args) => {
         const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
-        return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '操作失败' }] };
+        return wrap(projectId, node ? JSON.stringify(node, null, 2) : '操作失败');
     });
     // 5. 搜索节点
     server.tool('kg_search', '关键词搜索节点,按相关度排序返回', {
@@ -75,7 +103,7 @@ export function registerTools(server, projectId, _user) {
             id: r.node.id, title: r.node.title, type: r.node.type,
             status: r.node.status, score: r.score.toFixed(1), matches: r.matches
         }));
-        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        return wrap(projectId, JSON.stringify(output, null, 2));
     });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
@@ -84,44 +112,63 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const result = await storage.findPath(projectId, args.startId, args.endId);
         if (!result)
-            return { content: [{ type: 'text', text: '未找到路径' }] };
+            return wrap(projectId, '未找到路径');
         const output = {
             pathLength: result.path.length,
             nodes: result.path.map(n => ({ id: n.id, title: n.title, type: n.type })),
             edges: result.edges.map(e => ({ from: e.source, to: e.target, type: e.type }))
         };
-        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        return wrap(projectId, JSON.stringify(output, null, 2));
     });
     // 7. 列出所有节点
     server.tool('kg_list_nodes', '列出项目全部节点概览', {}, async () => {
         const nodes = await storage.listNodes(projectId);
         const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked }));
-        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        return wrap(projectId, JSON.stringify(output, null, 2));
     });
     // 8. 查找孤立节点
     server.tool('kg_find_orphans', '查找无连线的孤立节点(用于清理)', {}, async () => {
         const orphans = await storage.findOrphans(projectId);
         if (orphans.length === 0) {
-            return { content: [{ type: 'text', text: '没有孤立节点' }] };
+            return wrap(projectId, '没有孤立节点');
         }
-        return { content: [{ type: 'text', text: JSON.stringify(orphans, null, 2) }] };
+        return wrap(projectId, JSON.stringify(orphans, null, 2));
     });
-    // 9. 查询节点关系网
-    server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)', {
-        nodeId: z.string().describe('节点ID')
+    // 9. 查询节点关系网 (支持多层)
+    server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)，支持多层查询', {
+        nodeId: z.string().describe('节点ID'),
+        depth: z.number().min(1).max(3).optional().describe('查询层数(默认1，最大3)')
     }, async (args) => {
-        const relations = await storage.getRelations(projectId, args.nodeId);
-        if (relations.length === 0) {
-            return { content: [{ type: 'text', text: '该节点没有任何连线' }] };
+        const maxDepth = Math.min(args.depth || 1, 3);
+        const visited = new Set();
+        const outgoing = [];
+        const incoming = [];
+        // 递归获取关系
+        async function fetchRelations(nodeId, currentDepth, direction) {
+            if (currentDepth > maxDepth || visited.has(`${nodeId}-${direction}`))
+                return;
+            visited.add(`${nodeId}-${direction}`);
+            const relations = await storage.getRelations(projectId, nodeId);
+            for (const r of relations) {
+                if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
+                    if (!outgoing.some(o => o.id === r.nodeId)) {
+                        outgoing.push({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType, depth: currentDepth });
+                        await fetchRelations(r.nodeId, currentDepth + 1, 'outgoing');
+                    }
+                }
+                if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
+                    if (!incoming.some(i => i.id === r.nodeId)) {
+                        incoming.push({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType, depth: currentDepth });
+                        await fetchRelations(r.nodeId, currentDepth + 1, 'incoming');
+                    }
+                }
+            }
         }
-        // 分组显示
-        const outgoing = relations.filter(r => r.direction === 'outgoing');
-        const incoming = relations.filter(r => r.direction === 'incoming');
-        const output = {
-            outgoing: outgoing.map(r => ({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType })),
-            incoming: incoming.map(r => ({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType }))
-        };
-        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        await fetchRelations(args.nodeId, 1, 'both');
+        if (outgoing.length === 0 && incoming.length === 0) {
+            return wrap(projectId, '该节点没有任何连线');
+        }
+        return wrap(projectId, JSON.stringify({ outgoing, incoming }, null, 2));
     });
     // ===================== 任务管理工具 =====================
     // 10. 创建任务
@@ -131,13 +178,15 @@ export function registerTools(server, projectId, _user) {
         goals: z.array(z.string()).optional().describe('目标清单'),
         related_nodes: z.array(z.string()).optional().describe('关联节点ID')
     }, async (args) => {
+        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
+        const decoded = decodeObjectStrings(args);
         const task = await storage.createTask(projectId, {
-            title: args.title,
-            description: args.description,
-            goals: args.goals || [],
-            related_nodes: args.related_nodes
+            title: decoded.title,
+            description: decoded.description,
+            goals: decoded.goals || [],
+            related_nodes: decoded.related_nodes
         }, _user);
-        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+        return wrap(projectId, JSON.stringify(task, null, 2));
     });
     // 11. 列出任务
     server.tool('task_list', '列出任务(active=进行中,archived=已归档)', {
@@ -152,7 +201,7 @@ export function registerTools(server, projectId, _user) {
             created_at: t.created_at,
             last_log: t.last_log
         }));
-        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        return wrap(projectId, JSON.stringify(output, null, 2));
     });
     // 12. 获取任务详情
     server.tool('task_get', '获取任务完整信息(含全部日志)', {
@@ -160,9 +209,9 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const task = await storage.getTask(projectId, args.taskId);
         if (!task) {
-            return { content: [{ type: 'text', text: '任务不存在' }] };
+            return wrap(projectId, '任务不存在');
         }
-        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+        return wrap(projectId, JSON.stringify(task, null, 2));
     });
     // 13. 添加任务日志
     server.tool('task_add_log', '记录任务进展/问题/方案/参考', {
@@ -170,11 +219,13 @@ export function registerTools(server, projectId, _user) {
         log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型'),
         content: z.string().describe('日志内容(Markdown)')
     }, async (args) => {
-        const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, args.content);
+        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
+        const decodedContent = decodeUnicodeEscapes(args.content);
+        const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, decodedContent);
         if (!task) {
-            return { content: [{ type: 'text', text: '添加失败(任务不存在或已归档)' }] };
+            return wrap(projectId, '添加失败(任务不存在或已归档)');
         }
-        return { content: [{ type: 'text', text: `日志已添加，任务共有 ${task.logs.length} 条日志` }] };
+        return wrap(projectId, `日志已添加，任务共有 ${task.logs.length} 条日志`);
     });
     // 14. 完成任务
     server.tool('task_complete', '完成任务并归档,填写经验总结', {
@@ -187,15 +238,17 @@ export function registerTools(server, projectId, _user) {
             url: z.string().optional()
         })).optional().describe('参考资料')
     }, async (args) => {
-        const task = await storage.completeTask(projectId, args.taskId, {
+        // 解码 Unicode 转义 (修复 MCP 传参中文乱码)
+        const decoded = decodeObjectStrings({
             summary: args.summary,
             difficulties: args.difficulties || [],
             solutions: args.solutions || [],
             references: args.references || []
         });
+        const task = await storage.completeTask(projectId, args.taskId, decoded);
         if (!task) {
-            return { content: [{ type: 'text', text: '完成失败(任务不存在或已归档)' }] };
+            return wrap(projectId, '完成失败(任务不存在或已归档)');
         }
-        return { content: [{ type: 'text', text: `任务已完成归档: ${task.title}` }] };
+        return wrap(projectId, `任务已完成归档: ${task.title}`);
     });
 }

package/dist/utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP Server 工具函数
+ */
+/**
+ * 获取根节点的用户风格
+ */
+export declare function getRootStyle(projectId: string): Promise<string>;
+/**
+ * 清除风格缓存 (当根节点更新时调用)
+ */
+export declare function clearStyleCache(): void;
+/**
+ * 包装工具返回结果 (注入用户风格)
+ */
+export declare function wrapResult(projectId: string, result: string): Promise<string>;
+/**
+ * 解码 Unicode 转义序列
+ * 将 \uXXXX 格式的转义序列转换为实际字符
+ * 用于修复 MCP SDK 传参时中文被转义的问题
+ */
+export declare function decodeUnicodeEscapes(str: string): string;
+/**
+ * 递归解码对象中所有字符串的 Unicode 转义
+ */
+export declare function decodeObjectStrings<T>(obj: T): T;

package/dist/utils.js

@@ -0,0 +1,90 @@
+/**
+ * MCP Server 工具函数
+ */
+import * as storage from './storage/httpClient.js';
+// 缓存根节点风格 (避免每次调用都请求)
+let cachedRootStyle = null;
+let cacheProjectId = null;
+/**
+ * 将 userStyles 字符串数组格式化为 Markdown 列表
+ */
+function formatUserStyles(styles) {
+    if (!styles || styles.length === 0)
+        return '';
+    return styles.map(s => `- ${s}`).join('\n');
+}
+/**
+ * 获取根节点的用户风格
+ */
+export async function getRootStyle(projectId) {
+    // 缓存命中
+    if (cachedRootStyle !== null && cacheProjectId === projectId) {
+        return cachedRootStyle;
+    }
+    try {
+        const rootNode = await storage.getNode(projectId, 'root');
+        if (!rootNode) {
+            cachedRootStyle = '';
+            cacheProjectId = projectId;
+            return '';
+        }
+        // 使用 userStyles 字符串数组
+        if (rootNode.userStyles && rootNode.userStyles.length > 0) {
+            cachedRootStyle = formatUserStyles(rootNode.userStyles);
+        }
+        else {
+            cachedRootStyle = '';
+        }
+        cacheProjectId = projectId;
+        return cachedRootStyle;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 清除风格缓存 (当根节点更新时调用)
+ */
+export function clearStyleCache() {
+    cachedRootStyle = null;
+    cacheProjectId = null;
+}
+/**
+ * 包装工具返回结果 (注入用户风格)
+ */
+export async function wrapResult(projectId, result) {
+    const style = await getRootStyle(projectId);
+    if (!style || style.trim() === '') {
+        return result;
+    }
+    return `[项目规则]\n${style}\n\n---\n[结果]\n${result}`;
+}
+/**
+ * 解码 Unicode 转义序列
+ * 将 \uXXXX 格式的转义序列转换为实际字符
+ * 用于修复 MCP SDK 传参时中文被转义的问题
+ */
+export function decodeUnicodeEscapes(str) {
+    if (!str)
+        return str;
+    return str.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/**
+ * 递归解码对象中所有字符串的 Unicode 转义
+ */
+export function decodeObjectStrings(obj) {
+    if (typeof obj === 'string') {
+        return decodeUnicodeEscapes(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => decodeObjectStrings(item));
+    }
+    if (obj && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = decodeObjectStrings(value);
+        }
+        return result;
+    }
+    return obj;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.6.4",
+  "version": "2.6.6",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -12,13 +12,22 @@
     "build": "tsc",
     "start": "node dist/index.js"
   },
-  "keywords": ["mcp", "claude", "knowledge-graph", "ppdocs"],
+  "keywords": [
+    "mcp",
+    "claude",
+    "knowledge-graph",
+    "ppdocs"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/ppdocs/ppdocs"
   },
   "license": "MIT",
-  "files": ["dist", "templates", "README.md"],
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "proper-lockfile": "^4.1.2",

package/templates/hooks/SystemPrompt.md

@@ -1,16 +1,35 @@
 ---
-description: 全周期智能开发：图表化沟通、知识库驱动、用户确认制
+description: 全周期智能开发：ASCII图表沟通、知识库驱动、用户确认制
 role: 资深全栈架构师 & 知识库维护者
 ---
 
 # 核心原则
-1. **沟通优先**: 图表化自然语言沟通，编码前不生成代码，只描述抽象逻辑
+1. **沟通优先**: ASCII图表 + 表格沟通，编码前不生成代码，只描述抽象逻辑
 2. **知识驱动**: 任何修改必须先查知识库(理论)再看代码(实际)，双重验证
 3. **用户确认**: 方案展示、执行、完成均需用户明确确认
 4. **经验沉淀**: 踩坑必记录，通过必总结，知识库持续进化
 
 # 图表化沟通规范
-与用户交流使用 **Mermaid图表 + 表格**，禁止大段文字，仅执行阶段输出代码。
+与用户交流使用 **ASCII流程图 + 表格**，禁止大段文字和Mermaid，仅执行阶段输出代码。
+
+## ASCII图表示例
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│  输入   │────▶│  处理   │────▶│  输出   │
+└─────────┘     └─────────┘     └─────────┘
+                    │
+                    ▼
+              ┌───────────┐
+              │ 是否成功? │
+              └─────┬─────┘
+                    │
+           ┌────────┴────────┐
+           │ 是              │ 否
+           ▼                 ▼
+      ┌────────┐        ┌────────┐
+      │ 完成   │        │ 重试   │
+      └────────┘        └────────┘
+```
 
 # 工作流程
 
@@ -33,18 +52,14 @@ role: 资深全栈架构师 & 知识库维护者
 | 文件/模块 | 当前状态 | 改动后 | 变更说明 |
 |:---|:---|:---|:---|
 | src/auth.ts | Session认证 | JWT认证 | 无状态，易扩展 |
-| src/store.ts | 无 | 新增TokenStore | 管理令牌刷新 |
-
-### 逻辑流程对比 (必须)
-```mermaid
-flowchart LR
-    subgraph 当前
-        A1[登录] --> B1[创建Session] --> C1[存Cookie]
-    end
-    subgraph 改动后
-        A2[登录] --> B2[签发JWT] --> C2[存LocalStorage]
-        C2 --> D2[自动刷新]
-    end
+
+### 逻辑流程对比 (必须，使用ASCII)
+```
+【当前流程】                    【改动后】
+登录 ──▶ 创建Session ──▶ 存Cookie    登录 ──▶ 签发JWT ──▶ 存Storage
+                                                    │
+                                                    ▼
+                                               自动刷新
 ```
 
 ### 影响范围
@@ -53,7 +68,6 @@ flowchart LR
 | 修改文件 | `auth.ts`, `api.ts` |
 | 新增文件 | `tokenStore.ts` |
 | 删除文件 | `sessionManager.ts` |
-| 依赖变更 | 新增 `jsonwebtoken` |
 
 ### 风险评估
 | 风险点 | 等级 | 应对措施 |
@@ -63,7 +77,7 @@ flowchart LR
 **模拟验证**: 脑中推演流程图，检查死逻辑/边界遗漏，无误后展示
 
 ## ④ 用户确认
-展示完整方案后，等待用户回复 **"确认"/"OK"** 才执行。用户可提修改意见迭代方案。
+展示完整方案后，等待用户回复 **"确认"/"OK"** 才执行。
 
 ## ⑤ 执行编码
 遵守：复用已有组件、物理删除旧代码、单文件≤150行。每完成子任务 `task_add_log(progress)`
@@ -72,7 +86,6 @@ flowchart LR
 提供测试命令协助验证。**不通过时**：
 1. `task_add_log(issue)` 记录失败原因
 2. `task_add_log(solution)` 记录修复方案
-3. 知识库记录避免重复踩坑
 
 ## ⑦ 任务完成
 测试通过后等用户确认 **"验收通过"**，然后：
@@ -82,6 +95,6 @@ flowchart LR
 # 禁止事项
 - 未经确认擅自修改代码
 - 跳过知识库直接改代码
-- 沟通时输出大段代码
+- 沟通时输出大段代码或Mermaid
 - 方案不展示对比图表
 - 任务未完成开始新任务