@ppdocs/mcp 3.2.35 → 3.2.36

package/dist/tools/flowchart.js

@@ -1,597 +1,549 @@
-/**
- * 🔀 kg_flowchart — 逻辑流程图批量操作
- * AI 一次提交所有节点+边, 后端原子处理, 返回孤立检测结果
- */
 import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
 import { decodeObjectStrings } from '../utils.js';
 import { wrap, safeTool } from './shared.js';
 const NodeSchema = z.object({
-    id: z.string().describe('节点唯一ID'),
-    label: z.string().describe('节点标签'),
-    description: z.string().optional().describe('节点描述'),
-    nodeType: z.string().optional().describe('节点类型: super|process|data|entry'),
-    domain: z.string().optional().describe('领域: frontend|backend|mcp|system|infra'),
-    input: z.array(z.string()).optional(),
-    output: z.array(z.string()).optional(),
-    affiliation: z.string().optional().describe('父节点ID, 默认root'),
+    id: z.string().describe('node id'),
+    label: z.string().describe('node label'),
+    description: z.string().optional().describe('node description'),
+    nodeType: z.string().optional().describe('node type: super|process|data|entry'),
+    domain: z.string().optional().describe('domain: frontend|backend|mcp|system|infra'),
+    input: z.array(z.string()).optional().describe('input list'),
+    output: z.array(z.string()).optional().describe('output list'),
+    affiliation: z.string().optional().describe('parent node id, default root'),
+    subFlowchart: z.string().optional().describe('optional sub-chart id'),
 });
 const EdgeSchema = z.object({
-    from: z.string().describe('起点节点ID'),
-    to: z.string().describe('终点节点ID'),
-    label: z.string().optional().describe('连线标签'),
-    edgeType: z.string().optional().describe('类型: call|event|data|reference'),
+    from: z.string().describe('from node id'),
+    to: z.string().describe('to node id'),
+    label: z.string().optional().describe('edge label'),
+    edgeType: z.string().optional().describe('edge type: call|event|data|reference'),
 });
-export function registerFlowchartTools(server, ctx) {
+function ensureArray(value) {
+    return Array.isArray(value) ? [...value] : [];
+}
+function ensureNodeShape(node) {
+    return {
+        ...node,
+        input: ensureArray(node.input),
+        output: ensureArray(node.output),
+        boundDocs: ensureArray(node.boundDocs),
+        boundFiles: ensureArray(node.boundFiles),
+        boundDirs: ensureArray(node.boundDirs),
+        boundTasks: ensureArray(node.boundTasks),
+        docEntries: Array.isArray(node.docEntries) ? [...node.docEntries] : [],
+        versions: Array.isArray(node.versions) ? [...node.versions] : [],
+    };
+}
+function buildNode(input) {
+    const now = new Date().toISOString();
+    return {
+        id: input.id,
+        label: input.label,
+        description: input.description ?? '',
+        nodeType: input.nodeType ?? 'process',
+        domain: input.domain ?? 'system',
+        input: ensureArray(input.input),
+        output: ensureArray(input.output),
+        affiliation: input.affiliation ?? 'root',
+        boundDocs: [],
+        boundFiles: [],
+        boundDirs: [],
+        boundTasks: [],
+        subFlowchart: input.subFlowchart || null,
+        docEntries: [],
+        versions: [{ version: 'v1.0', date: now, changes: 'initial' }],
+        lastUpdated: now,
+        lastQueried: '',
+    };
+}
+function buildEdge(input) {
+    return {
+        from: input.from,
+        to: input.to,
+        label: input.label ?? null,
+        edgeType: input.edgeType ?? 'call',
+    };
+}
+function formatNodeLine(node) {
+    const docCount = node.boundDocs?.length ?? 0;
+    const taskCount = node.boundTasks?.length ?? 0;
+    const fileCount = (node.boundFiles?.length ?? 0) + (node.boundDirs?.length ?? 0);
+    const badges = [
+        docCount > 0 ? `docs=${docCount}` : '',
+        taskCount > 0 ? `tasks=${taskCount}` : '',
+        fileCount > 0 ? `files=${fileCount}` : '',
+        node.subFlowchart ? `sub=${node.subFlowchart}` : '',
+    ].filter(Boolean);
+    const suffix = badges.length > 0 ? ` | ${badges.join(' ')}` : '';
+    return `- ${node.label} [${node.id}] (${node.nodeType ?? 'process'}/${node.domain ?? 'system'})${suffix}`;
+}
+function formatEdgeLine(edge) {
+    const label = edge.label ? ` [${edge.label}]` : '';
+    const type = edge.edgeType ? ` (${edge.edgeType})` : '';
+    return `- ${edge.from} -> ${edge.to}${label}${type}`;
+}
+function appendDocEntry(node, summary, content) {
+    const nextNode = ensureNodeShape(node);
+    const entries = nextNode.docEntries ?? [];
+    let nextVer = 0.1;
+    if (entries.length > 0) {
+        const last = entries[entries.length - 1]?.version ?? '';
+        const parsed = Number.parseFloat(last.replace(/^v/, ''));
+        if (!Number.isNaN(parsed)) {
+            nextVer = Math.round((parsed + 0.1) * 10) / 10;
+        }
+    }
+    entries.push({
+        version: `v${nextVer.toFixed(1)}`,
+        date: new Date().toISOString(),
+        summary: summary.replace(/\\n/g, '\n'),
+        content: content.replace(/\\n/g, '\n'),
+    });
+    nextNode.docEntries = entries;
+    return { node: nextNode, version: `v${nextVer.toFixed(1)}` };
+}
+function collectNeighborLayers(chart, startNodeId, maxDepth) {
+    const nodeMap = new Map(chart.nodes.map((node) => [node.id, node]));
+    const visited = new Set([startNodeId]);
+    let frontier = [startNodeId];
+    const layers = [];
+    for (let depth = 1; depth <= maxDepth; depth += 1) {
+        const layer = [];
+        const nextFrontier = [];
+        for (const currentId of frontier) {
+            for (const edge of chart.edges) {
+                if (edge.from === currentId && !visited.has(edge.to)) {
+                    visited.add(edge.to);
+                    nextFrontier.push(edge.to);
+                    const node = nodeMap.get(edge.to);
+                    layer.push(`- ${node?.label ?? edge.to} [${edge.to}]${edge.label ? ` (${edge.label})` : ''}${edge.edgeType ? ` [${edge.edgeType}]` : ''}`);
+                }
+                if (edge.to === currentId && !visited.has(edge.from)) {
+                    visited.add(edge.from);
+                    nextFrontier.push(edge.from);
+                    const node = nodeMap.get(edge.from);
+                    layer.push(`- ${node?.label ?? edge.from} [${edge.from}]${edge.label ? ` (${edge.label})` : ''}${edge.edgeType ? ` [${edge.edgeType}]` : ''}`);
+                }
+            }
+        }
+        if (layer.length === 0) {
+            break;
+        }
+        layers.push(layer);
+        frontier = nextFrontier;
+    }
+    return layers;
+}
+export function registerFlowchartTools(server, _ctx) {
     const client = () => getClient();
-    server.tool('kg_flowchart', '🔀 逻辑流程图(关系型知识锚点) — action: list|get|get_node(★爆炸式上下文)|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart', {
-        action: z.enum(['list', 'get', 'get_node', 'update_node', 'delete_node', 'batch_add', 'bind', 'unbind', 'orphans', 'health', 'create_chart', 'delete_chart'])
-            .describe('操作类型'),
-        chartId: z.string().optional()
-            .describe('流程图ID (默认"main")'),
-        nodeId: z.string().optional()
-            .describe('节点ID (get_node/update_node/delete_node/bind/unbind)'),
-        // get_node 爆炸扩展控制 (全部默认开启, AI可选择性关闭)
-        expand: z.number().optional()
-            .describe('get_node: 连线扩展层数(默认3, 0=不扩展)'),
-        includeDocs: z.boolean().optional()
-            .describe('get_node: 显示绑定的参考文档摘要(默认true)'),
-        includeTasks: z.boolean().optional()
-            .describe('get_node: 显示绑定的任务摘要(默认true)'),
-        includeFiles: z.boolean().optional()
-            .describe('get_node: 显示绑定的代码文件(默认true)'),
-        includeDoc: z.boolean().optional()
-            .describe('get_node: 显示节点技术文档(默认true)'),
-        // update_node 更新字段
-        label: z.string().optional().describe('update_node: 新标签'),
-        description: z.string().optional().describe('update_node: 新描述'),
-        nodeType: z.string().optional().describe('update_node: 新类型'),
-        domain: z.string().optional().describe('update_node: 新领域'),
-        input: z.array(z.string()).optional().describe('update_node: 新输入 / bind的源代码文件'),
-        output: z.array(z.string()).optional().describe('update_node: 新输出'),
-        subFlowchart: z.string().optional().describe('update_node: bind sub-chart ID / auto-set on create_chart'),
-        title: z.string().optional().describe('create_chart: sub-chart title'),
-        parentChart: z.string().optional().describe('create_chart: parent chart ID (default main)'),
-        parentNode: z.string().optional().describe('create_chart: mount to parent node ID'),
-        // update_node: append doc entry
-        docSummary: z.string().optional().describe('update_node: doc summary (one-line)'),
-        docContent: z.string().optional().describe('update_node: doc content (full markdown)'),
-        // get_node: doc display control
-        fullDoc: z.boolean().optional().describe('get_node: show ALL doc entries in full (default false, only latest full)'),
-        // bind/unbind
-        files: z.array(z.string()).optional()
-            .describe('源代码文件路径 (bind/unbind)'),
-        dirs: z.array(z.string()).optional()
-            .describe('源代码目录路径 (bind/unbind)'),
-        docs: z.array(z.string()).optional()
-            .describe('知识文档路径 (bind/unbind)'),
-        tasks: z.array(z.string()).optional()
-            .describe('任务ID (bind/unbind)'),
-        // batch_add
-        nodes: z.array(NodeSchema).optional()
-            .describe('批量添加的节点数组 (batch_add)'),
-        edges: z.array(EdgeSchema).optional()
-            .describe('批量添加的边数组 (batch_add)'),
+    server.tool('kg_flowchart', 'Logical flowchart operations: list|get|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart', {
+        action: z
+            .enum(['list', 'get', 'get_node', 'update_node', 'delete_node', 'batch_add', 'bind', 'unbind', 'orphans', 'health', 'create_chart', 'delete_chart'])
+            .describe('action type'),
+        chartId: z.string().optional().describe('chart id, default main'),
+        nodeId: z.string().optional().describe('node id for get_node/update_node/delete_node/bind/unbind'),
+        expand: z.number().optional().describe('get_node expansion depth, default 3'),
+        includeDocs: z.boolean().optional().describe('show bound docs in get_node, default true'),
+        includeTasks: z.boolean().optional().describe('show bound tasks in get_node, default true'),
+        includeFiles: z.boolean().optional().describe('show bound files in get_node, default true'),
+        includeDoc: z.boolean().optional().describe('show node docEntries in get_node, default true'),
+        label: z.string().optional().describe('update_node label'),
+        description: z.string().optional().describe('update_node description'),
+        nodeType: z.string().optional().describe('update_node node type'),
+        domain: z.string().optional().describe('update_node domain'),
+        input: z.array(z.string()).optional().describe('update_node input list'),
+        output: z.array(z.string()).optional().describe('update_node output list'),
+        subFlowchart: z.string().optional().describe('update_node sub chart id, pass empty string to clear'),
+        title: z.string().optional().describe('create_chart title'),
+        parentChart: z.string().optional().describe('create_chart parent chart id, default main'),
+        parentNode: z.string().optional().describe('create_chart parent node id'),
+        docSummary: z.string().optional().describe('update_node doc summary'),
+        docContent: z.string().optional().describe('update_node doc content'),
+        fullDoc: z.boolean().optional().describe('get_node show all docEntries in full'),
+        files: z.array(z.string()).optional().describe('bind/unbind file paths'),
+        dirs: z.array(z.string()).optional().describe('bind/unbind directory paths'),
+        docs: z.array(z.string()).optional().describe('bind/unbind doc paths'),
+        tasks: z.array(z.string()).optional().describe('bind/unbind task ids'),
+        nodes: z.array(NodeSchema).optional().describe('batch_add/create_chart nodes'),
+        edges: z.array(EdgeSchema).optional().describe('batch_add/create_chart edges'),
     }, async (args) => safeTool(async () => {
         const decoded = decodeObjectStrings(args);
         switch (decoded.action) {
             case 'list': {
-                const charts = await client().listFlowcharts();
-                if (!charts || charts.length === 0)
-                    return wrap('📋 暂无流程图');
-                const list = charts
-                    .map(c => `• ${c.title} [${c.id}] — ${c.nodeCount}节点 ${c.edgeCount}连线`)
-                    .join('\n');
-                return wrap(`📋 流程图列表:\n\n${list}`);
+                const charts = (await client().listFlowcharts());
+                if (!charts || charts.length === 0) {
+                    return wrap('No flowcharts found.');
+                }
+                const lines = ['Flowcharts:', '', ...charts.map((chart) => {
+                        const parent = chart.parentChart ? ` parent=${chart.parentChart}` : '';
+                        return `- ${chart.title} [${chart.id}] ${chart.nodeCount} nodes / ${chart.edgeCount} edges${parent}`;
+                    })];
+                return wrap(lines.join('\n'));
             }
             case 'get': {
                 const chartId = decoded.chartId || 'main';
-                const chart = await client().getFlowchart(chartId);
-                if (!chart)
-                    return wrap(`❌ 流程图 "${chartId}" 不存在`);
-                const nodes = chart.nodes || [];
-                const edges = chart.edges || [];
+                const chart = (await client().getFlowchart(chartId));
+                if (!chart) {
+                    return wrap(`Flowchart not found: ${chartId}`);
+                }
                 const lines = [
-                    `📊 ${chart.title || chartId} [${chartId}]`,
-                    chart.parentChart ? `↩ 父图: ${chart.parentChart}` : '',
-                    ``,
-                    `### 节点 (${nodes.length})`,
-                    ...nodes.map((n) => `  • ${n.label} [${n.id}] (${n.nodeType}/${n.domain}) ${n.boundDocs?.length ? `📄${n.boundDocs.length}` : ''} ${n.boundTasks?.length ? `📝${n.boundTasks.length}` : ''} ${n.boundFiles?.length ? `📂${n.boundFiles.length}` : ''}`),
-                    ``,
-                    `### 连线 (${edges.length})`,
-                    ...edges.map((e) => `  ${e.from} →${e.label ? `[${e.label}]` : ''} ${e.to}`),
-                ].filter(Boolean);
+                    `Flowchart: ${chart.title} [${chart.id}]`,
+                    chart.parentChart ? `Parent chart: ${chart.parentChart}` : '',
+                    chart.parentNode ? `Parent node: ${chart.parentNode}` : '',
+                    '',
+                    `Nodes (${chart.nodes.length}):`,
+                    ...chart.nodes.map(formatNodeLine),
+                    '',
+                    `Edges (${chart.edges.length}):`,
+                    ...chart.edges.map(formatEdgeLine),
+                ].filter((line) => line.length > 0);
                 return wrap(lines.join('\n'));
             }
             case 'get_node': {
                 const chartId = decoded.chartId || 'main';
-                if (!decoded.nodeId)
-                    return wrap('❌ get_node 需要 nodeId');
-                const chart = await client().getFlowchart(chartId);
-                if (!chart)
-                    return wrap(`❌ 流程图 "${chartId}" 不存在`);
-                const allNodes = chart.nodes || [];
-                const allEdges = chart.edges || [];
-                const target = allNodes.find((n) => n.id === decoded.nodeId);
-                if (!target)
-                    return wrap(`❌ 节点 "${decoded.nodeId}" 不存在于 "${chartId}"`);
-                // 扩展参数 (全部默认开启)
-                const expandDepth = decoded.expand !== undefined ? Number(decoded.expand) : 3;
+                if (!decoded.nodeId) {
+                    return wrap('get_node requires nodeId.');
+                }
+                const chart = (await client().getFlowchart(chartId));
+                if (!chart) {
+                    return wrap(`Flowchart not found: ${chartId}`);
+                }
+                const target = chart.nodes.find((node) => node.id === decoded.nodeId);
+                if (!target) {
+                    return wrap(`Node not found: ${decoded.nodeId} in ${chartId}`);
+                }
+                const node = ensureNodeShape(target);
+                const expandDepth = decoded.expand ?? 3;
                 const showDocs = decoded.includeDocs !== false;
                 const showTasks = decoded.includeTasks !== false;
                 const showFiles = decoded.includeFiles !== false;
                 const showDoc = decoded.includeDoc !== false;
-                const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
-                const lines = [];
-                // ======== 节点基础信息 ========
-                lines.push(`🔍 节点详情: ${target.label} [${target.id}]`);
-                lines.push(`类型: ${target.nodeType || 'process'} | 领域: ${target.domain || 'system'}`);
-                if (target.description)
-                    lines.push(`📝 ${target.description}`);
-                if (target.input?.length)
-                    lines.push(`📥 输入: ${target.input.join(', ')}`);
-                if (target.output?.length)
-                    lines.push(`📤 输出: ${target.output.join(', ')}`);
-                if (target.subFlowchart)
-                    lines.push(`📂 子流程图: ${target.subFlowchart}`);
-                if (target.lastUpdated)
-                    lines.push(`🕐 最后更新: ${target.lastUpdated}`);
+                const lines = [
+                    `Node: ${node.label} [${node.id}]`,
+                    `Type: ${node.nodeType ?? 'process'} | Domain: ${node.domain ?? 'system'}`,
+                ];
+                if (node.description) {
+                    lines.push(`Description: ${node.description}`);
+                }
+                if (node.input && node.input.length > 0) {
+                    lines.push(`Input: ${node.input.join(', ')}`);
+                }
+                if (node.output && node.output.length > 0) {
+                    lines.push(`Output: ${node.output.join(', ')}`);
+                }
+                if (node.subFlowchart) {
+                    lines.push(`Sub flowchart: ${node.subFlowchart}`);
+                }
+                if (node.lastUpdated) {
+                    lines.push(`Last updated: ${node.lastUpdated}`);
+                }
+                if (node.lastQueried) {
+                    lines.push(`Last queried: ${node.lastQueried}`);
+                }
                 lines.push('');
-                // ======== node doc entries ========
-                if (showDoc && target.docEntries?.length) {
-                    const entries = target.docEntries;
-                    const showFullAll = decoded.fullDoc === true;
-                    lines.push(`### 📖 Node Documentation (${entries.length} entries)`);
-                    for (let i = 0; i < entries.length; i++) {
-                        const e = entries[i];
-                        const isLatest = i === entries.length - 1;
-                        if (isLatest || showFullAll) {
-                            lines.push(`\n**${e.version}** (${e.date})${isLatest ? ' ★LATEST' : ''}`);
-                            lines.push(`> ${e.summary}`);
-                            lines.push(e.content);
+                if (showDoc && node.docEntries && node.docEntries.length > 0) {
+                    lines.push(`Node docs (${node.docEntries.length}):`);
+                    const showAll = decoded.fullDoc === true;
+                    node.docEntries.forEach((entry, index) => {
+                        const isLatest = index === node.docEntries.length - 1;
+                        if (isLatest || showAll) {
+                            lines.push(`- ${entry.version} ${entry.date}${isLatest ? ' latest' : ''}`);
+                            lines.push(`  summary: ${entry.summary}`);
+                            lines.push(...entry.content.split('\n').map((line) => `  ${line}`));
                         }
                         else {
-                            lines.push(`  ${e.version} (${e.date}): ${e.summary}`);
+                            lines.push(`- ${entry.version} ${entry.date}: ${entry.summary}`);
                         }
-                    }
+                    });
                     lines.push('');
                 }
-                // ======== 爆炸扩展: N层关联节点 ========
                 if (expandDepth > 0) {
-                    const visited = new Set([target.id]);
-                    let frontier = [target.id];
-                    const layerResults = [];
-                    for (let depth = 1; depth <= expandDepth; depth++) {
-                        const nextFrontier = [];
-                        const layerLines = [];
-                        for (const currentId of frontier) {
-                            // 出边
-                            for (const e of allEdges) {
-                                if (e.from === currentId && !visited.has(e.to)) {
-                                    visited.add(e.to);
-                                    nextFrontier.push(e.to);
-                                    const neighbor = nodeMap.get(e.to);
-                                    const label = neighbor?.label || e.to;
-                                    layerLines.push(`  → ${label} [${e.to}] ${e.label ? `(${e.label})` : ''} ${e.edgeType ? `[${e.edgeType}]` : ''}`);
-                                }
-                                // 入边
-                                if (e.to === currentId && !visited.has(e.from)) {
-                                    visited.add(e.from);
-                                    nextFrontier.push(e.from);
-                                    const neighbor = nodeMap.get(e.from);
-                                    const label = neighbor?.label || e.from;
-                                    layerLines.push(`  ← ${label} [${e.from}] ${e.label ? `(${e.label})` : ''} ${e.edgeType ? `[${e.edgeType}]` : ''}`);
-                                }
-                            }
-                        }
-                        if (layerLines.length > 0)
-                            layerResults.push(layerLines);
-                        frontier = nextFrontier;
-                        if (frontier.length === 0)
-                            break;
-                    }
-                    if (layerResults.length > 0) {
-                        lines.push(`### 🔗 关联节点 (扩展${layerResults.length}层, 共${visited.size - 1}个)`);
-                        layerResults.forEach((layer, i) => {
-                            lines.push(`**L${i + 1}** (${layer.length}个):`);
-                            lines.push(...layer);
+                    const layers = collectNeighborLayers(chart, node.id, expandDepth);
+                    if (layers.length > 0) {
+                        lines.push(`Linked nodes (${layers.length} layers):`);
+                        layers.forEach((layer, index) => {
+                            lines.push(`L${index + 1}:`);
+                            lines.push(...layer.map((item) => `  ${item}`));
                         });
                         lines.push('');
                     }
                 }
-                // ======== 绑定的参考文档 ========
-                if (showDocs && target.boundDocs?.length) {
-                    lines.push(`### 📄 绑定参考文档 (${target.boundDocs.length})`);
-                    for (const docPath of target.boundDocs) {
-                        try {
-                            const doc = await client().getDoc(docPath);
-                            if (doc) {
-                                lines.push(`  📄 ${docPath} — ${doc.summary || '无摘要'}`);
-                                if (doc.status)
-                                    lines.push(`     状态: ${doc.status}`);
-                            }
-                            else {
-                                lines.push(`  📄 ${docPath} (未找到)`);
-                            }
-                        }
-                        catch {
-                            lines.push(`  📄 ${docPath}`);
-                        }
-                    }
+                if (showDocs && node.boundDocs && node.boundDocs.length > 0) {
+                    lines.push(`Bound docs (${node.boundDocs.length}):`);
+                    node.boundDocs.forEach((docPath) => lines.push(`- ${docPath}`));
                     lines.push('');
                 }
-                // ======== 绑定的任务 ========
-                if (showTasks && target.boundTasks?.length) {
-                    lines.push(`### 📝 绑定任务 (${target.boundTasks.length})`);
-                    for (const taskId of target.boundTasks) {
+                if (showTasks && node.boundTasks && node.boundTasks.length > 0) {
+                    lines.push(`Bound tasks (${node.boundTasks.length}):`);
+                    for (const taskId of node.boundTasks) {
                         try {
-                            const task = await client().getTask(taskId);
+                            const task = (await client().getTask(taskId));
                             if (task) {
-                                lines.push(`  📝 [${taskId}] ${task.title} — ${task.status}`);
+                                lines.push(`- [${taskId}] ${task.title ?? ''} ${task.status ? `(${task.status})` : ''}`.trim());
                             }
                             else {
-                                lines.push(`  📝 [${taskId}] (未找到)`);
+                                lines.push(`- [${taskId}]`);
                             }
                         }
                         catch {
-                            lines.push(`  📝 [${taskId}]`);
+                            lines.push(`- [${taskId}]`);
                         }
                     }
                     lines.push('');
                 }
-                // ======== 绑定的代码文件 ========
                 if (showFiles) {
-                    const files = target.boundFiles || [];
-                    const dirs = target.boundDirs || [];
-                    if (files.length + dirs.length > 0) {
-                        lines.push(`### 📂 绑定代码 (${files.length}文件 ${dirs.length}目录)`);
-                        for (const f of files)
-                            lines.push(`  📄 ${f}`);
-                        for (const d of dirs)
-                            lines.push(`  📁 ${d}`);
+                    const files = node.boundFiles ?? [];
+                    const dirs = node.boundDirs ?? [];
+                    if (files.length > 0 || dirs.length > 0) {
+                        lines.push(`Bound code (${files.length} files / ${dirs.length} dirs):`);
+                        files.forEach((filePath) => lines.push(`- file: ${filePath}`));
+                        dirs.forEach((dirPath) => lines.push(`- dir: ${dirPath}`));
                         lines.push('');
                     }
                 }
-                // ======== 版本历史 ========
-                if (target.versions?.length) {
-                    lines.push(`### 📋 版本历史 (${target.versions.length})`);
-                    for (const v of target.versions.slice(-5)) {
-                        lines.push(`  v${v.version} (${v.date}): ${v.changes}`);
-                    }
+                if (node.versions && node.versions.length > 0) {
+                    lines.push(`Versions (${node.versions.length}):`);
+                    node.versions.slice(-5).forEach((version) => {
+                        lines.push(`- ${version.version} ${version.date}: ${version.changes}`);
+                    });
                 }
-                return wrap(lines.join('\n'));
+                return wrap(lines.join('\n').trim());
             }
             case 'update_node': {
                 const chartId = decoded.chartId || 'main';
-                if (!decoded.nodeId)
-                    return wrap('❌ update_node 需要 nodeId');
-                const chart = await client().getFlowchart(chartId);
-                if (!chart)
-                    return wrap(`❌ 流程图 "${chartId}" 不存在`);
-                const node = (chart.nodes || []).find((n) => n.id === decoded.nodeId);
-                if (!node)
-                    return wrap(`❌ 节点 "${decoded.nodeId}" 不存在`);
+                if (!decoded.nodeId) {
+                    return wrap('update_node requires nodeId.');
+                }
+                const chart = (await client().getFlowchart(chartId));
+                if (!chart) {
+                    return wrap(`Flowchart not found: ${chartId}`);
+                }
+                const rawNode = chart.nodes.find((node) => node.id === decoded.nodeId);
+                if (!rawNode) {
+                    return wrap(`Node not found: ${decoded.nodeId}`);
+                }
+                let nextNode = ensureNodeShape(rawNode);
                 const changes = [];
                 if (decoded.label !== undefined) {
-                    node.label = decoded.label;
+                    nextNode.label = decoded.label;
                     changes.push('label');
                 }
                 if (decoded.description !== undefined) {
-                    node.description = decoded.description;
+                    nextNode.description = decoded.description;
                     changes.push('description');
                 }
                 if (decoded.nodeType !== undefined) {
-                    node.nodeType = decoded.nodeType;
+                    nextNode.nodeType = decoded.nodeType;
                     changes.push('nodeType');
                 }
                 if (decoded.domain !== undefined) {
-                    node.domain = decoded.domain;
+                    nextNode.domain = decoded.domain;
                     changes.push('domain');
                 }
                 if (decoded.input !== undefined) {
-                    node.input = decoded.input;
+                    nextNode.input = [...decoded.input];
                     changes.push('input');
                 }
                 if (decoded.output !== undefined) {
-                    node.output = decoded.output;
+                    nextNode.output = [...decoded.output];
                     changes.push('output');
                 }
                 if (decoded.subFlowchart !== undefined) {
-                    node.subFlowchart = decoded.subFlowchart;
+                    nextNode.subFlowchart = decoded.subFlowchart || null;
                     changes.push('subFlowchart');
                 }
-                // append doc entry
                 if (decoded.docSummary || decoded.docContent) {
                     if (!decoded.docSummary || !decoded.docContent) {
-                        return wrap('\u274c update_node: docSummary and docContent must both be provided');
+                        return wrap('update_node requires both docSummary and docContent when updating docs.');
                     }
-                    const docEntries = node.docEntries || [];
-                    // auto-increment version: v0.1, v0.2, ...
-                    let nextVer = 0.1;
-                    if (docEntries.length > 0) {
-                        const lastVer = docEntries[docEntries.length - 1].version;
-                        const num = parseFloat(lastVer.replace('v', ''));
-                        if (!isNaN(num))
-                            nextVer = Math.round((num + 0.1) * 10) / 10;
-                    }
-                    // normalize escaped newlines from AI clients (e.g. "\\n" → actual newline)
-                    const normalizedContent = decoded.docContent.replace(/\\n/g, '\n');
-                    const normalizedSummary = decoded.docSummary.replace(/\\n/g, '\n');
-                    docEntries.push({
-                        version: `v${nextVer.toFixed(1)}`,
-                        date: new Date().toISOString(),
-                        summary: normalizedSummary,
-                        content: normalizedContent,
-                    });
-                    node.docEntries = docEntries;
-                    changes.push(`docEntries(v${nextVer.toFixed(1)})`);
-                }
-                if (changes.length === 0)
-                    return wrap('ℹ️ 无变更 — 请提供要更新的字段');
-                node.lastUpdated = new Date().toISOString();
-                await client().saveFlowchart(chartId, chart);
-                return wrap(`✅ 节点已更新: ${node.label} [${chartId}/${decoded.nodeId}]\n更新字段: ${changes.join(', ')}`);
+                    const result = appendDocEntry(nextNode, decoded.docSummary, decoded.docContent);
+                    nextNode = result.node;
+                    changes.push(`docEntries(${result.version})`);
+                }
+                if (changes.length === 0) {
+                    return wrap('No fields were updated.');
+                }
+                await client().updateFlowchartNode(chartId, decoded.nodeId, nextNode, `MCP update: ${changes.join(', ')}`);
+                return wrap(`Node updated: ${nextNode.label} [${chartId}/${decoded.nodeId}]\nFields: ${changes.join(', ')}`);
             }
             case 'delete_node': {
                 const chartId = decoded.chartId || 'main';
-                if (!decoded.nodeId)
-                    return wrap('❌ delete_node 需要 nodeId');
-                // 原子调用: DELETE /flowcharts/:chartId/nodes/:nodeId (后端自动清理关联边)
+                if (!decoded.nodeId) {
+                    return wrap('delete_node requires nodeId.');
+                }
                 await client().deleteFlowchartNode(chartId, decoded.nodeId);
-                return wrap(`✅ 节点已删除 [${chartId}/${decoded.nodeId}]`);
+                return wrap(`Node deleted: [${chartId}/${decoded.nodeId}]`);
             }
             case 'batch_add': {
                 const chartId = decoded.chartId || 'main';
                 if (!decoded.nodes || decoded.nodes.length === 0) {
-                    return wrap('❌ batch_add 需要 nodes 数组');
-                }
-                // 自动填充默认值 — AI 只需填 id+label+description
-                const fullNodes = decoded.nodes.map((n) => ({
-                    id: n.id,
-                    label: n.label,
-                    nodeType: n.nodeType || 'process',
-                    domain: n.domain || 'system',
-                    input: n.input || [],
-                    output: n.output || [],
-                    description: n.description || '',
-                    affiliation: n.affiliation || 'root',
-                    boundDocs: [],
-                    boundFiles: [],
-                    boundDirs: [],
-                    boundTasks: [],
-                    subFlowchart: n.subFlowchart || null,
-                    position: null,
-                    versions: [{ version: 'v1.0', date: new Date().toISOString(), changes: 'initial' }],
-                    lastUpdated: new Date().toISOString(),
-                    lastQueried: '',
-                }));
-                const fullEdges = (decoded.edges || []).map((e) => ({
-                    from: e.from,
-                    to: e.to,
-                    label: e.label || null,
-                    edgeType: e.edgeType || 'call',
-                }));
-                const result = await client().batchAddToFlowchart(chartId, fullNodes, fullEdges);
-                // 构建报告
-                let report = `✅ 批量操作完成 [${chartId}]\n`;
-                report += `  添加: ${result.addedNodes.length}节点 ${result.addedEdges}连线\n`;
+                    return wrap('batch_add requires nodes.');
+                }
+                const result = (await client().batchAddToFlowchart(chartId, decoded.nodes.map(buildNode), (decoded.edges ?? []).map(buildEdge)));
+                const lines = [
+                    `Batch add finished: [${chartId}]`,
+                    `Added nodes: ${result.addedNodes.length}`,
+                    `Added edges: ${result.addedEdges}`,
+                ];
                 if (result.failedNodes.length > 0) {
-                    report += `\n❌ 失败节点:\n`;
-                    result.failedNodes.forEach(([id, reason]) => {
-                        report += `  • ${id}: ${reason}\n`;
-                    });
+                    lines.push('', 'Failed nodes:');
+                    result.failedNodes.forEach(([nodeId, reason]) => lines.push(`- ${nodeId}: ${reason}`));
                 }
                 if (result.failedEdges.length > 0) {
-                    report += `\n❌ 失败连线:\n`;
-                    result.failedEdges.forEach(([from, to, reason]) => {
-                        report += `  • ${from} → ${to}: ${reason}\n`;
-                    });
+                    lines.push('', 'Failed edges:');
+                    result.failedEdges.forEach(([from, to, reason]) => lines.push(`- ${from} -> ${to}: ${reason}`));
                 }
                 if (result.orphanedNodes.length > 0) {
-                    report += `\n⚠️ 孤立节点 (无任何连线):\n`;
-                    result.orphanedNodes.forEach(id => {
-                        report += `  • ${id}\n`;
-                    });
+                    lines.push('', 'Orphaned nodes:');
+                    result.orphanedNodes.forEach((nodeId) => lines.push(`- ${nodeId}`));
                 }
                 else {
-                    report += `\n✅ 无孤立节点`;
+                    lines.push('', 'Orphaned nodes: none');
                 }
-                return wrap(report);
+                return wrap(lines.join('\n'));
             }
             case 'orphans': {
-                const orphans = await client().getFlowchartOrphans();
+                const orphans = (await client().getFlowchartOrphans());
                 if (!orphans || orphans.length === 0) {
-                    return wrap('✅ 无孤立文档 — 所有文档均已绑定到流程图节点');
+                    return wrap('No orphan reference docs reported by backend.');
                 }
-                const list = orphans
-                    .map(o => `• ${o.docPath}${o.docSummary ? ` — ${o.docSummary}` : ''}`)
-                    .join('\n');
-                return wrap(`⚠️ 发现 ${orphans.length} 个孤立文档 (未绑定到任何流程图节点):\n\n${list}\n\n💡 使用 kg_doc(update, bindTo: "节点ID") 绑定`);
+                const lines = ['Orphan reference docs:', '', ...orphans.map((item) => `- ${item.docPath}${item.docSummary ? ` | ${item.docSummary}` : ''}`)];
+                return wrap(lines.join('\n'));
             }
             case 'health': {
-                const health = await client().getFlowchartHealth();
-                if (!health || health.length === 0) {
-                    return wrap('📊 暂无节点健康数据');
-                }
-                const items = health;
-                const stale = items.filter(h => h.status === 'stale');
-                const active = items.filter(h => h.status === 'active');
-                const normal = items.filter(h => h.status === 'normal');
-                let report = `📊 知识冷热分布 (${items.length}节点):\n`;
-                report += `  🟢 active (7天内查询): ${active.length}\n`;
-                report += `  🟡 normal (30天内): ${normal.length}\n`;
-                report += `  🔴 stale (30天+未查询): ${stale.length}\n`;
+                const items = (await client().getFlowchartHealth());
+                if (!items || items.length === 0) {
+                    return wrap('No flowchart health data reported by backend.');
+                }
+                const stale = items.filter((item) => item.status === 'stale');
+                const normal = items.filter((item) => item.status === 'normal');
+                const active = items.filter((item) => item.status === 'active');
+                const lines = [
+                    `Node health: ${items.length} nodes`,
+                    `active: ${active.length}`,
+                    `normal: ${normal.length}`,
+                    `stale: ${stale.length}`,
+                ];
                 if (stale.length > 0) {
-                    report += `\n🔴 冷知识节点:\n`;
-                    stale.forEach(h => {
-                        report += `  • ${h.nodeLabel} [${h.chartId}/${h.nodeId}] — ${h.daysSinceQuery}天未查询\n`;
-                    });
+                    lines.push('', 'Stale nodes:');
+                    stale.forEach((item) => lines.push(`- ${item.nodeLabel} [${item.chartId}/${item.nodeId}] ${item.daysSinceQuery} days`));
                 }
-                return wrap(report);
+                return wrap(lines.join('\n'));
             }
             case 'bind':
             case 'unbind': {
                 const chartId = decoded.chartId || 'main';
-                if (!decoded.nodeId)
-                    return wrap(`❌ ${decoded.action} 需要 nodeId`);
-                const chart = await client().getFlowchart(chartId);
-                if (!chart)
-                    return wrap(`❌ 流程图 "${chartId}" 不存在`);
-                const node = chart.nodes?.find((n) => n.id === decoded.nodeId);
-                if (!node)
-                    return wrap(`❌ 节点 "${decoded.nodeId}" 不存在于流程图 "${chartId}"`);
+                if (!decoded.nodeId) {
+                    return wrap(`${decoded.action} requires nodeId.`);
+                }
+                const chart = (await client().getFlowchart(chartId));
+                if (!chart) {
+                    return wrap(`Flowchart not found: ${chartId}`);
+                }
+                const rawNode = chart.nodes.find((node) => node.id === decoded.nodeId);
+                if (!rawNode) {
+                    return wrap(`Node not found: ${decoded.nodeId} in ${chartId}`);
+                }
+                const node = ensureNodeShape(rawNode);
                 const isBind = decoded.action === 'bind';
                 const changes = [];
-                const modify = (items, field, label) => {
-                    if (!items || items.length === 0)
+                const mutate = (incoming, field, label) => {
+                    const items = incoming ?? [];
+                    if (items.length === 0) {
                         return;
-                    if (!node[field])
-                        node[field] = [];
+                    }
+                    const current = new Set(node[field] ?? []);
                     if (isBind) {
                         let added = 0;
                         for (const item of items) {
-                            if (!node[field].includes(item)) {
-                                node[field].push(item);
-                                added++;
+                            if (!current.has(item)) {
+                                current.add(item);
+                                added += 1;
                             }
                         }
-                        if (added > 0)
+                        if (added > 0) {
                             changes.push(`+${added} ${label}`);
+                        }
                     }
                     else {
-                        const before = node[field].length;
-                        node[field] = node[field].filter((x) => !items.includes(x));
-                        const removed = before - node[field].length;
-                        if (removed > 0)
+                        let removed = 0;
+                        for (const item of items) {
+                            if (current.delete(item)) {
+                                removed += 1;
+                            }
+                        }
+                        if (removed > 0) {
                             changes.push(`-${removed} ${label}`);
+                        }
                     }
+                    node[field] = [...current];
                 };
-                modify(decoded.files, 'boundFiles', '文件');
-                modify(decoded.dirs, 'boundDirs', '目录');
-                modify(decoded.docs, 'boundDocs', '文档');
-                modify(decoded.tasks, 'boundTasks', '任务');
+                mutate(decoded.files, 'boundFiles', 'files');
+                mutate(decoded.dirs, 'boundDirs', 'dirs');
+                mutate(decoded.docs, 'boundDocs', 'docs');
+                mutate(decoded.tasks, 'boundTasks', 'tasks');
                 if (changes.length === 0) {
-                    return wrap(`ℹ️ 无变更 — 请提供 files/dirs/docs/tasks 参数`);
-                }
-                await client().saveFlowchart(chartId, chart);
-                // P2: 双向同步 — 更新参考文档的 adoptedBy
-                const docsList = decoded.docs;
-                if (docsList && docsList.length > 0) {
-                    const nodeId = decoded.nodeId;
-                    for (const docPath of docsList) {
-                        try {
-                            const doc = await client().getDoc(docPath);
-                            if (!doc?.content)
-                                continue;
-                            const content = doc.content;
-                            // 解析 frontmatter
-                            if (!content.startsWith('---'))
-                                continue;
-                            const endIdx = content.indexOf('---', 3);
-                            if (endIdx === -1)
-                                continue;
-                            const yaml = content.slice(3, endIdx);
-                            const body = content.slice(endIdx + 3);
-                            // 提取现有 adoptedBy
-                            const adoptedMatch = yaml.match(/adoptedBy:\s*\[(.*?)\]/);
-                            let adopted = [];
-                            if (adoptedMatch) {
-                                adopted = adoptedMatch[1].split(',').map(s => s.trim()).filter(Boolean);
-                            }
-                            // 修改 adoptedBy
-                            if (isBind) {
-                                if (!adopted.includes(nodeId))
-                                    adopted.push(nodeId);
-                            }
-                            else {
-                                adopted = adopted.filter(id => id !== nodeId);
-                            }
-                            // 重建 frontmatter
-                            const newAdoptedLine = `adoptedBy: [${adopted.join(', ')}]`;
-                            let newYaml;
-                            if (adoptedMatch) {
-                                newYaml = yaml.replace(/adoptedBy:\s*\[.*?\]/, newAdoptedLine);
-                            }
-                            else {
-                                newYaml = yaml.trimEnd() + '\n' + newAdoptedLine + '\n';
-                            }
-                            const newContent = `---${newYaml}---${body}`;
-                            await client().updateDoc(docPath, { content: newContent });
-                        }
-                        catch { /* 单个文档同步失败不阻断 */ }
-                    }
+                    return wrap('No bindings changed.');
                 }
-                const icon = isBind ? '🔗' : '⛓️';
-                return wrap(`${icon} ${isBind ? '绑定' : '解绑'}完成 [${decoded.nodeId}]: ${changes.join(', ')}`);
+                await client().updateFlowchartNode(chartId, decoded.nodeId, node, `${isBind ? 'Bind' : 'Unbind'} resources: ${changes.join(', ')}`);
+                return wrap(`${isBind ? 'Bound' : 'Unbound'} resources for [${decoded.nodeId}]: ${changes.join(', ')}`);
             }
             case 'create_chart': {
                 const newChartId = decoded.chartId;
-                if (!newChartId)
-                    return wrap('❌ create_chart 需要 chartId (子图ID)');
-                if (newChartId === 'main')
-                    return wrap('❌ 不能创建 main，主图已存在');
-                // 检查是否已存在
-                const existing = await client().getFlowchart(newChartId);
-                if (existing)
-                    return wrap(`❌ 流程图 "${newChartId}" 已存在`);
-                const pChart = decoded.parentChart || 'main';
-                const pNode = decoded.parentNode;
-                // 构建子图数据
-                const subChartData = {
+                if (!newChartId) {
+                    return wrap('create_chart requires chartId.');
+                }
+                if (newChartId === 'main') {
+                    return wrap('create_chart cannot create main.');
+                }
+                const existing = (await client().getFlowchart(newChartId));
+                if (existing) {
+                    return wrap(`Flowchart already exists: ${newChartId}`);
+                }
+                const parentChartId = decoded.parentChart || 'main';
+                const subChart = {
                     id: newChartId,
                     title: decoded.title || newChartId,
-                    parentNode: pNode || null,
-                    parentChart: pChart,
-                    nodes: [],
-                    edges: [],
+                    parentNode: decoded.parentNode || null,
+                    parentChart: parentChartId,
+                    nodes: (decoded.nodes ?? []).map(buildNode),
+                    edges: (decoded.edges ?? []).map(buildEdge),
                 };
-                // 如果提供了 nodes/edges，填充进去
-                if (decoded.nodes && decoded.nodes.length > 0) {
-                    subChartData.nodes = decoded.nodes.map((n) => ({
-                        id: n.id, label: n.label,
-                        nodeType: n.nodeType || 'process', domain: n.domain || 'system',
-                        input: n.input || [], output: n.output || [],
-                        description: n.description || '', affiliation: n.affiliation || 'root',
-                        boundDocs: [], boundFiles: [], boundDirs: [], boundTasks: [],
-                        subFlowchart: null, position: null,
-                        versions: [{ version: 'v1.0', date: new Date().toISOString(), changes: 'initial' }],
-                        lastUpdated: new Date().toISOString(), lastQueried: '',
-                    }));
-                }
-                if (decoded.edges && decoded.edges.length > 0) {
-                    subChartData.edges = decoded.edges.map(e => ({
-                        from: e.from, to: e.to, label: e.label || null, edgeType: e.edgeType || 'call',
-                    }));
-                }
-                // 保存子图
-                await client().saveFlowchart(newChartId, subChartData);
-                // 自动更新父节点的 subFlowchart 引用
-                if (pNode) {
-                    const parentChart = await client().getFlowchart(pChart);
+                await client().saveFlowchart(newChartId, subChart);
+                let parentMessage = `Parent chart: ${parentChartId}`;
+                if (decoded.parentNode) {
+                    const parentChart = (await client().getFlowchart(parentChartId));
                     if (parentChart) {
-                        const parentNodeObj = (parentChart.nodes || []).find((n) => n.id === pNode);
-                        if (parentNodeObj) {
-                            parentNodeObj.subFlowchart = newChartId;
-                            parentNodeObj.lastUpdated = new Date().toISOString();
-                            await client().saveFlowchart(pChart, parentChart);
+                        const parentNode = parentChart.nodes.find((node) => node.id === decoded.parentNode);
+                        if (parentNode) {
+                            const updatedParent = ensureNodeShape(parentNode);
+                            updatedParent.subFlowchart = newChartId;
+                            await client().updateFlowchartNode(parentChartId, decoded.parentNode, updatedParent, `Attach sub flowchart ${newChartId}`);
+                            parentMessage = `Parent chart: ${parentChartId} | Parent node: ${decoded.parentNode}`;
                         }
+                        else {
+                            parentMessage = `Parent chart: ${parentChartId} | Parent node not found: ${decoded.parentNode}`;
+                        }
+                    }
+                    else {
+                        parentMessage = `Parent chart not found: ${parentChartId}`;
                     }
                 }
-                const nodeCount = subChartData.nodes.length;
-                return wrap(`✅ 子图已创建: ${decoded.title || newChartId} [${newChartId}]\n父图: ${pChart}${pNode ? ` → 节点: ${pNode}` : ''}\n初始: ${nodeCount}节点`);
+                return wrap(`Sub chart created: ${subChart.title} [${newChartId}]\n${parentMessage}\nInitial nodes: ${subChart.nodes.length}\nInitial edges: ${subChart.edges.length}`);
             }
             case 'delete_chart': {
-                const chartId = decoded.chartId;
-                if (!chartId)
-                    return wrap('❌ delete_chart 需要 chartId');
-                if (chartId === 'main')
-                    return wrap('❌ 不能删除主图 main');
-                // 后端自动级联: 清父节点引用 + 删子图的子图
-                await client().deleteFlowchart(chartId);
-                return wrap(`✅ 流程图已删除 [${chartId}] (子图已级联清理)`);
+                if (!decoded.chartId) {
+                    return wrap('delete_chart requires chartId.');
+                }
+                if (decoded.chartId === 'main') {
+                    return wrap('delete_chart cannot remove main.');
+                }
+                await client().deleteFlowchart(decoded.chartId);
+                return wrap(`Flowchart deleted: [${decoded.chartId}]`);
             }
             default:
-                return wrap(`❌ 未知 action: ${decoded.action}`);
+                return wrap(`Unknown action: ${String(decoded.action)}`);
         }
     }));
 }