@ppdocs/mcp 3.4.0 → 3.6.0

package/dist/config.d.ts

@@ -6,6 +6,7 @@ export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
     user: string;
+    agentId: string;
     source: 'env' | 'file';
 }
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";

package/dist/config.js

@@ -16,7 +16,13 @@ function readEnvConfig() {
     if (!apiUrl)
         return null;
     const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
-    return { apiUrl, projectId: match?.[1] || 'unknown', user: process.env.PPDOCS_USER || generateUser(), source: 'env' };
+    return {
+        apiUrl,
+        projectId: match?.[1] || 'unknown',
+        user: process.env.PPDOCS_USER || generateUser(),
+        agentId: process.env.PPDOCS_AGENT_ID || 'default',
+        source: 'env',
+    };
 }
 function readPpdocsFile() {
     const configPath = path.join(process.cwd(), '.ppdocs');
@@ -26,7 +32,7 @@ function readPpdocsFile() {
         const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
         if (!c.api || !c.projectId || !c.key)
             return null;
-        return { apiUrl: `${c.api}/api/${c.projectId}/${c.key}`, projectId: c.projectId, user: c.user || generateUser(), source: 'file' };
+        return { apiUrl: `${c.api}/api/${c.projectId}/${c.key}`, projectId: c.projectId, user: c.user || generateUser(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || 'default', source: 'file' };
     }
     catch {
         return null;

package/dist/index.js

@@ -39,8 +39,9 @@ async function main() {
     }
     const projectId = config?.projectId || 'pending';
     const user = config?.user || 'agent';
+    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || 'default';
     const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
-    registerTools(server, projectId, user, (newProjectId, newApiUrl) => {
+    registerTools(server, projectId, user, agentId, (newProjectId, newApiUrl) => {
         console.error(`[kg_init] 项目已切换: ${newProjectId}`);
     });
     const transport = new StdioServerTransport();

package/dist/tools/discussion.js

@@ -15,7 +15,9 @@ import { getClient } from '../storage/httpClient.js';
 import { decodeObjectStrings } from '../utils.js';
 import { wrap, safeTool } from './shared.js';
 function sender(ctx) {
-    return `${ctx.projectId}:${ctx.user}`;
+    return ctx.agentId && ctx.agentId !== 'default'
+        ? `${ctx.projectId}:${ctx.user}:${ctx.agentId}`
+        : `${ctx.projectId}:${ctx.user}`;
 }
 /** 提取 sender 中的 projectId */
 function senderProjectId(senderStr) {

package/dist/tools/doc_query.d.ts

@@ -0,0 +1,10 @@
+/**
+ * kg_doc — 文档查询视图
+ * 纯查询工具，数据来源为流程图节点的 docEntries + description
+ * 不创建独立文档，只是提供面向文档的查询入口
+ *
+ * read 默认返回当前文档，history=true 返回历史列表，index=N 返回指定历史条目
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpContext } from './shared.js';
+export declare function registerDocQueryTools(server: McpServer, _ctx: McpContext): void;

package/dist/tools/doc_query.js

@@ -0,0 +1,185 @@
+/**
+ * kg_doc — 文档查询视图
+ * 纯查询工具，数据来源为流程图节点的 docEntries + description
+ * 不创建独立文档，只是提供面向文档的查询入口
+ *
+ * read 默认返回当前文档，history=true 返回历史列表，index=N 返回指定历史条目
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { wrap, safeTool } from './shared.js';
+function normalizeText(value) {
+    return (value ?? '').trim().toLowerCase();
+}
+/** 文档专用评分 — 侧重 summary/content/description */
+function scoreDocMatch(node, terms) {
+    const description = normalizeText(node.description);
+    const entries = node.docEntries ?? [];
+    const allSummaries = entries.map((e) => e.summary).join(' ').toLowerCase();
+    const allContents = entries.map((e) => e.content).join(' ').toLowerCase();
+    const label = normalizeText(node.label);
+    let score = 0;
+    let matched = 0;
+    for (const term of terms) {
+        let hit = false;
+        if (allSummaries.includes(term)) {
+            score += 40;
+            hit = true;
+        }
+        if (allContents.includes(term)) {
+            score += 30;
+            hit = true;
+        }
+        if (description.includes(term)) {
+            score += 20;
+            hit = true;
+        }
+        if (label.includes(term)) {
+            score += 10;
+            hit = true;
+        }
+        if (hit)
+            matched += 1;
+    }
+    return matched === 0 ? 0 : score + matched * 50;
+}
+/** 加载所有流程图的完整数据 */
+async function loadAllCharts() {
+    const client = getClient();
+    const briefs = (await client.listFlowcharts());
+    const loaded = await Promise.all(briefs.map(async (b) => (await client.getFlowchart(b.id))));
+    return loaded.filter((c) => Boolean(c));
+}
+/** 格式化日期为简短形式 */
+function shortDate(iso) {
+    try {
+        return iso.slice(0, 10);
+    }
+    catch {
+        return iso;
+    }
+}
+export function registerDocQueryTools(server, _ctx) {
+    server.tool('kg_doc', '📘 文档查询视图 — 跨流程图搜索和阅读节点内嵌文档(docEntries + description)。纯查询，不创建独立文档。\n' +
+        '调用方式：search(query:"关键词") 全文搜索 | list 列出有文档的节点 | read(nodeId) 读取当前文档。\n' +
+        'read(nodeId, history:true) 查看历史列表(标题+日期) | read(nodeId, index:N) 读取第N条历史详情(0=最新)。\n' +
+        'actions: search(全文搜索)|list(文档列表)|read(读取文档,支持history/index参数)', {
+        action: z.enum(['search', 'list', 'read']).describe('操作类型 (Allowed: search, list, read)'),
+        query: z.string().optional().describe('搜索关键词 (search)'),
+        nodeId: z.string().optional().describe('节点ID (read)'),
+        chartId: z.string().optional().describe('限定流程图ID'),
+        history: z.boolean().optional().describe('read时传true返回历史列表(标题+日期)'),
+        index: z.number().optional().describe('read时指定历史条目序号(0=最新, 1=次新...)'),
+        limit: z.number().optional().describe('搜索结果限制, default 10'),
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        switch (decoded.action) {
+            case 'search': {
+                const rawQuery = decoded.query?.trim();
+                if (!rawQuery)
+                    return wrap('search requires query.');
+                const terms = rawQuery.toLowerCase().split(/\s+/).filter(Boolean);
+                const charts = decoded.chartId
+                    ? [(await getClient().getFlowchart(decoded.chartId))].filter((c) => Boolean(c))
+                    : await loadAllCharts();
+                const matches = charts
+                    .flatMap((chart) => chart.nodes
+                    .filter((n) => (n.docEntries && n.docEntries.length > 0) || n.description)
+                    .map((node) => ({ chart, node, score: scoreDocMatch(node, terms) })))
+                    .filter((m) => m.score > 0)
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, decoded.limit ?? 10);
+                if (matches.length === 0)
+                    return wrap(`No docs matched: ${rawQuery}`);
+                const lines = [`Doc search: "${rawQuery}" (${matches.length} results)`, ''];
+                for (const { chart, node } of matches) {
+                    const docCount = node.docEntries?.length ?? 0;
+                    const latest = docCount > 0 ? node.docEntries[docCount - 1] : null;
+                    lines.push(`- **${node.label}** [${chart.id}/${node.id}] history=${docCount}`);
+                    if (latest)
+                        lines.push(`  current: ${shortDate(latest.date)} — ${latest.summary}`);
+                    if (node.description)
+                        lines.push(`  desc: ${node.description.slice(0, 80)}${node.description.length > 80 ? '...' : ''}`);
+                }
+                return wrap(lines.join('\n'));
+            }
+            case 'list': {
+                const charts = decoded.chartId
+                    ? [(await getClient().getFlowchart(decoded.chartId))].filter((c) => Boolean(c))
+                    : await loadAllCharts();
+                const nodesWithDocs = charts.flatMap((chart) => chart.nodes
+                    .filter((n) => (n.docEntries && n.docEntries.length > 0) || n.description)
+                    .map((n) => ({ chart, node: n })));
+                if (nodesWithDocs.length === 0)
+                    return wrap('No nodes with documentation found.');
+                const lines = [`Documented nodes: ${nodesWithDocs.length}`, ''];
+                for (const { chart, node } of nodesWithDocs) {
+                    const docCount = node.docEntries?.length ?? 0;
+                    const latest = docCount > 0 ? node.docEntries[docCount - 1] : null;
+                    const latestInfo = latest ? ` | ${shortDate(latest.date)} ${latest.summary}` : '';
+                    lines.push(`- ${node.label} [${chart.id}/${node.id}] history=${docCount}${latestInfo}`);
+                }
+                return wrap(lines.join('\n'));
+            }
+            case 'read': {
+                if (!decoded.nodeId)
+                    return wrap('read requires nodeId.');
+                const chartId = decoded.chartId || 'main';
+                const chart = (await getClient().getFlowchart(chartId));
+                if (!chart)
+                    return wrap(`Flowchart not found: ${chartId}`);
+                const node = chart.nodes.find((n) => n.id === decoded.nodeId);
+                if (!node)
+                    return wrap(`Node not found: ${decoded.nodeId} in ${chartId}`);
+                const entries = node.docEntries ?? [];
+                // history=true → 列出历史记录(标题+日期)
+                if (decoded.history) {
+                    if (entries.length === 0)
+                        return wrap(`No history for ${node.label} [${chartId}/${decoded.nodeId}]`);
+                    const lines = [`## ${node.label} — history (${entries.length})`, ''];
+                    for (let i = entries.length - 1; i >= 0; i--) {
+                        const e = entries[i];
+                        const tag = i === entries.length - 1 ? ' (current)' : '';
+                        lines.push(`${entries.length - 1 - i}. ${shortDate(e.date)} — ${e.summary}${tag}`);
+                    }
+                    lines.push('', '_Use read(nodeId, index:N) to view specific entry._');
+                    return wrap(lines.join('\n'));
+                }
+                // index=N → 读取指定历史条目 (0=最新)
+                if (decoded.index !== undefined) {
+                    const idx = entries.length - 1 - decoded.index;
+                    if (idx < 0 || idx >= entries.length) {
+                        return wrap(`Index out of range: ${decoded.index} (total: ${entries.length})`);
+                    }
+                    const entry = entries[idx];
+                    const lines = [
+                        `## ${node.label} — #${decoded.index}`,
+                        `${shortDate(entry.date)} — ${entry.summary}`,
+                        '',
+                        entry.content,
+                    ];
+                    return wrap(lines.join('\n'));
+                }
+                // 默认: 返回当前文档 (description + 最新 docEntry)
+                const lines = [`## ${node.label} [${chartId}/${node.id}]`, ''];
+                if (node.description) {
+                    lines.push(node.description, '');
+                }
+                if (entries.length > 0) {
+                    const latest = entries[entries.length - 1];
+                    lines.push(`---`, `**${latest.summary}** (${shortDate(latest.date)})`, '', latest.content);
+                    if (entries.length > 1) {
+                        lines.push('', `_${entries.length - 1} older entries. Use read(nodeId, history:true) to browse._`);
+                    }
+                }
+                else if (!node.description) {
+                    lines.push('_No documentation._');
+                }
+                return wrap(lines.join('\n'));
+            }
+            default:
+                return wrap(`Unknown action: ${String(decoded.action)}`);
+        }
+    }));
+}

package/dist/tools/flowchart.js

@@ -32,7 +32,6 @@ function ensureNodeShape(node) {
         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) {
@@ -52,7 +51,6 @@ function buildNode(input) {
         boundTasks: [],
         subFlowchart: input.subFlowchart || null,
         docEntries: [],
-        versions: [{ version: 'v1.0', date: now, changes: 'initial' }],
         lastUpdated: now,
         lastQueried: '',
     };
@@ -81,27 +79,98 @@ function formatNodeLine(node) {
 function formatEdgeLine(edge) {
     const label = edge.label ? ` [${edge.label}]` : '';
     const type = edge.edgeType ? ` (${edge.edgeType})` : '';
-    return `- ${edge.from} -> ${edge.to}${label}${type}`;
+    return `- ${edge.from} → ${edge.to}${label}${type}`;
 }
+/** 紧凑节点格式 (用于 get 视图) — 含内联 doc 摘要 */
+function formatNodeCompact(node) {
+    const badges = [];
+    const fileCount = (node.boundFiles?.length ?? 0) + (node.boundDirs?.length ?? 0);
+    if (fileCount > 0)
+        badges.push(`files=${fileCount}`);
+    if (node.boundTasks?.length)
+        badges.push(`tasks=${node.boundTasks.length}`);
+    const docCount = node.docEntries?.length ?? 0;
+    if (docCount > 0)
+        badges.push(`docs=${docCount}`);
+    if (node.subFlowchart)
+        badges.push(`▶${node.subFlowchart}`);
+    const meta = `${node.nodeType ?? 'process'}/${node.domain ?? 'system'}`;
+    const suffix = badges.length > 0 ? ` [${badges.join(' ')}]` : '';
+    const desc = node.description ? `\n  > ${node.description.slice(0, 100)}${node.description.length > 100 ? '…' : ''}` : '';
+    const latestDoc = docCount > 0 ? `\n  doc: ${node.docEntries[docCount - 1].summary}` : '';
+    return `- **${node.label}** \`${node.id}\` (${meta})${suffix}${desc}${latestDoc}`;
+}
+/** 拓扑树 — DFS 从入度为0的节点开始, 展示调用结构 */
+function buildTopologyTree(chart) {
+    const nodeMap = new Map(chart.nodes.map((n) => [n.id, n]));
+    const inDegree = new Map();
+    for (const n of chart.nodes)
+        inDegree.set(n.id, 0);
+    for (const e of chart.edges) {
+        inDegree.set(e.to, (inDegree.get(e.to) ?? 0) + 1);
+    }
+    // 按 from 分组出边
+    const outEdges = new Map();
+    for (const e of chart.edges) {
+        if (!outEdges.has(e.from))
+            outEdges.set(e.from, []);
+        outEdges.get(e.from).push(e);
+    }
+    const roots = chart.nodes.filter((n) => (inDegree.get(n.id) ?? 0) === 0);
+    if (roots.length === 0)
+        return ['(no root nodes — graph may contain cycles)'];
+    const lines = [];
+    const visited = new Set();
+    function dfs(nodeId, indent) {
+        if (visited.has(nodeId)) {
+            lines.push(`${'  '.repeat(indent)}↺ ${nodeId} (cycle)`);
+            return;
+        }
+        visited.add(nodeId);
+        const node = nodeMap.get(nodeId);
+        const label = node ? node.label : nodeId;
+        lines.push(`${'  '.repeat(indent)}${indent === 0 ? '◆' : '├'} ${label} [${nodeId}]`);
+        const children = outEdges.get(nodeId) ?? [];
+        for (const edge of children) {
+            const edgeLabel = edge.label ? ` —${edge.label}→ ` : ' → ';
+            if (visited.has(edge.to)) {
+                const target = nodeMap.get(edge.to);
+                lines.push(`${'  '.repeat(indent + 1)}├${edgeLabel}↺ ${target?.label ?? edge.to}`);
+            }
+            else {
+                if (children.length > 1 || edge.label) {
+                    lines.push(`${'  '.repeat(indent + 1)}${edgeLabel.trim()}`);
+                }
+                dfs(edge.to, indent + 1);
+            }
+        }
+    }
+    for (const root of roots) {
+        dfs(root.id, 0);
+    }
+    // 未访问的孤立节点
+    const orphans = chart.nodes.filter((n) => !visited.has(n.id));
+    if (orphans.length > 0) {
+        lines.push('', '(orphans):');
+        for (const n of orphans) {
+            lines.push(`  ○ ${n.label} [${n.id}]`);
+        }
+    }
+    return lines;
+}
+/** 封装文档更新：自动将上一条归档，追加新条目 */
 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;
-        }
-    }
+    const version = `v${entries.length + 1}.0`;
     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)}` };
+    nextNode.lastUpdated = new Date().toISOString();
+    return { node: nextNode, version };
 }
 function collectNeighborLayers(chart, startNodeId, maxDepth) {
     const nodeMap = new Map(chart.nodes.map((node) => [node.id, node]));
@@ -295,8 +364,10 @@ export function registerFlowchartTools(server, _ctx) {
                     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}`;
+                        const parent = chart.parentChart
+                            ? ` ← ${chart.parentChart}${chart.parentNode ? `/${chart.parentNode}` : ''}`
+                            : '';
+                        return `- ${chart.title} [${chart.id}] ${chart.nodeCount}n/${chart.edgeCount}e${parent}`;
                     })];
                 return wrap(lines.join('\n'));
             }
@@ -307,16 +378,46 @@ export function registerFlowchartTools(server, _ctx) {
                     return wrap(`Flowchart not found: ${chartId}`);
                 }
                 const lines = [
-                    `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);
+                    `# ${chart.title} [${chart.id}]`,
+                ];
+                if (chart.parentChart) {
+                    lines.push(`parent: ${chart.parentChart}${chart.parentNode ? `/${chart.parentNode}` : ''}`);
+                }
+                // Mermaid 流程图
+                lines.push('', '```mermaid', 'graph TD');
+                // 节点声明
+                for (const n of chart.nodes) {
+                    const safeLabel = n.label.replace(/"/g, '#quot;');
+                    lines.push(`  ${n.id}["${safeLabel}"]`);
+                }
+                // 边
+                for (const e of chart.edges) {
+                    const arrow = e.label ? `-->|${e.label}|` : '-->';
+                    lines.push(`  ${e.from} ${arrow} ${e.to}`);
+                }
+                lines.push('```');
+                // 节点简介表 (MD table)
+                lines.push('', `## Nodes (${chart.nodes.length})`, '');
+                lines.push('| 节点 | 类型 | 简介 | 绑定文件 |');
+                lines.push('|:-----|:-----|:-----|:---------|');
+                for (const n of chart.nodes) {
+                    const nameCol = n.subFlowchart
+                        ? `**${n.label}** \`${n.id}\` ▶${n.subFlowchart}`
+                        : `**${n.label}** \`${n.id}\``;
+                    const typeCol = `${n.nodeType ?? 'process'}/${n.domain ?? 'system'}`;
+                    const descCol = n.description
+                        ? n.description.slice(0, 80).replace(/[\|\n]/g, ' ') + (n.description.length > 80 ? '…' : '')
+                        : '';
+                    const fileNames = [];
+                    for (const f of (n.boundFiles ?? [])) {
+                        fileNames.push(f.replace(/\\/g, '/').split('/').pop() ?? f);
+                    }
+                    for (const d of (n.boundDirs ?? [])) {
+                        fileNames.push(d.replace(/\\/g, '/').split('/').pop() + '/');
+                    }
+                    const fileCol = fileNames.length > 0 ? fileNames.join(', ') : '-';
+                    lines.push(`| ${nameCol} | ${typeCol} | ${descCol} | ${fileCol} |`);
+                }
                 return wrap(lines.join('\n'));
             }
             case 'search': {
@@ -463,63 +564,81 @@ export function registerFlowchartTools(server, _ctx) {
                 const showTasks = decoded.includeTasks !== false;
                 const showFiles = decoded.includeFiles !== false;
                 const showDoc = decoded.includeDoc !== false;
+                const relations = collectNodeRelations(chart, node.id);
                 const lines = [
-                    `Node: ${node.label} [${node.id}]`,
-                    `Type: ${node.nodeType ?? 'process'} | Domain: ${node.domain ?? 'system'}`,
+                    `## ${node.label} \`${node.id}\``,
+                    `${node.nodeType ?? 'process'} / ${node.domain ?? 'system'}`,
                 ];
                 if (node.description) {
-                    lines.push(`Description: ${node.description}`);
+                    lines.push('', '### Description');
+                    lines.push(...node.description.split('\n').map((l) => `> ${l}`));
                 }
                 if (node.input && node.input.length > 0) {
-                    lines.push(`Input: ${node.input.join(', ')}`);
+                    lines.push(`\nInput: ${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}`);
+                    lines.push(`Sub-chart: ▶ ${node.subFlowchart}`);
                 }
                 if (node.lastUpdated) {
-                    lines.push(`Last updated: ${node.lastUpdated}`);
-                }
-                if (node.lastQueried) {
-                    lines.push(`Last queried: ${node.lastQueried}`);
-                }
-                lines.push('');
-                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(`- ${entry.version} ${entry.date}: ${entry.summary}`);
-                        }
-                    });
-                    lines.push('');
+                    lines.push(`Updated: ${node.lastUpdated}`);
+                }
+                // 关系: →← 方向箭头
+                if (relations.incoming.length > 0 || relations.outgoing.length > 0) {
+                    lines.push('', '### Relations');
+                    for (const { edge, node: src } of relations.incoming) {
+                        const lbl = edge.label ? ` [${edge.label}]` : '';
+                        const typ = edge.edgeType ? ` (${edge.edgeType})` : '';
+                        lines.push(`← ${src?.label ?? edge.from} \`${edge.from}\`${lbl}${typ}`);
+                    }
+                    for (const { edge, node: tgt } of relations.outgoing) {
+                        const lbl = edge.label ? ` [${edge.label}]` : '';
+                        const typ = edge.edgeType ? ` (${edge.edgeType})` : '';
+                        lines.push(`→ ${tgt?.label ?? edge.to} \`${edge.to}\`${lbl}${typ}`);
+                    }
                 }
+                // 邻居展开
                 if (expandDepth > 0) {
                     const layers = collectNeighborLayers(chart, node.id, expandDepth);
                     if (layers.length > 0) {
-                        lines.push(`Linked nodes (${layers.length} layers):`);
+                        lines.push('', '### Neighbors');
                         layers.forEach((layer, index) => {
                             lines.push(`L${index + 1}:`);
                             lines.push(...layer.map((item) => `  ${item}`));
                         });
-                        lines.push('');
+                    }
+                }
+                // 内嵌文档
+                if (showDoc && node.docEntries && node.docEntries.length > 0) {
+                    lines.push('', `### Docs (${node.docEntries.length})`);
+                    const showAll = decoded.fullDoc === true;
+                    const latest = node.docEntries[node.docEntries.length - 1];
+                    // 当前文档 (最新)
+                    lines.push(`**${latest.summary}** (${latest.date.slice(0, 10)})`);
+                    lines.push(latest.content);
+                    // 历史记录
+                    if (node.docEntries.length > 1) {
+                        lines.push('', `History (${node.docEntries.length - 1}):`);
+                        for (let i = node.docEntries.length - 2; i >= 0; i--) {
+                            const entry = node.docEntries[i];
+                            if (showAll) {
+                                lines.push(`- ${entry.date.slice(0, 10)}: **${entry.summary}**`);
+                                lines.push(entry.content);
+                            }
+                            else {
+                                lines.push(`- ${entry.date.slice(0, 10)}: ${entry.summary}`);
+                            }
+                        }
                     }
                 }
                 if (showDocs && node.boundDocs && node.boundDocs.length > 0) {
-                    lines.push(`Bound docs (${node.boundDocs.length}):`);
+                    lines.push('', `### Bound docs (${node.boundDocs.length})`);
                     node.boundDocs.forEach((docPath) => lines.push(`- ${docPath}`));
-                    lines.push('');
                 }
                 if (showTasks && node.boundTasks && node.boundTasks.length > 0) {
-                    lines.push(`Bound tasks (${node.boundTasks.length}):`);
+                    lines.push('', `### Tasks (${node.boundTasks.length})`);
                     for (const taskId of node.boundTasks) {
                         try {
                             const task = (await client().getTask(taskId));
@@ -534,24 +653,17 @@ export function registerFlowchartTools(server, _ctx) {
                             lines.push(`- [${taskId}]`);
                         }
                     }
-                    lines.push('');
                 }
                 if (showFiles) {
                     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('');
+                        lines.push('', `### Code (${files.length} files / ${dirs.length} dirs)`);
+                        files.forEach((filePath) => lines.push(`- ${filePath}`));
+                        dirs.forEach((dirPath) => lines.push(`- ${dirPath}/`));
                     }
                 }
-                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}`);
-                    });
-                }
+                // Versions 已由 docEntries 历史替代，不再输出
                 return wrap(lines.join('\n').trim());
             }
             case 'update_node': {
@@ -574,6 +686,12 @@ export function registerFlowchartTools(server, _ctx) {
                     changes.push('label');
                 }
                 if (decoded.description !== undefined) {
+                    // 自动归档旧 description 到 docEntries
+                    if (nextNode.description && nextNode.description !== decoded.description) {
+                        const archiveResult = appendDocEntry(nextNode, '[auto] description更新前快照', nextNode.description);
+                        nextNode = archiveResult.node;
+                        changes.push(`docArchive(${archiveResult.version})`);
+                    }
                     nextNode.description = decoded.description;
                     changes.push('description');
                 }

package/dist/tools/index.d.ts

@@ -1,14 +1,15 @@
 /**
  * MCP 工具注册入口
- * 13 个工具, 7 个子模块
+ * 14 个工具, 8 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
  * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
+ * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)
  * 🏛️ 协作:    kg_meeting                                         (1个)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, user: string, onProjectChange?: (newProjectId: string, newApiUrl: string) => void): void;
+export declare function registerTools(server: McpServer, projectId: string, user: string, agentId: string, onProjectChange?: (newProjectId: string, newApiUrl: string) => void): void;

package/dist/tools/index.js

@@ -1,12 +1,13 @@
 /**
  * MCP 工具注册入口
- * 13 个工具, 7 个子模块
+ * 14 个工具, 8 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
  * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
+ * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)
  * 🏛️ 协作:    kg_meeting                                         (1个)
  */
@@ -22,8 +23,9 @@ import { registerReferenceTools } from './refs.js';
 import { registerAnalyzerTools } from './analyzer.js';
 import { registerMeetingTools } from './meeting.js';
 import { registerFlowchartTools } from './flowchart.js';
-export function registerTools(server, projectId, user, onProjectChange) {
-    const ctx = createContext(projectId, user);
+import { registerDocQueryTools } from './doc_query.js';
+export function registerTools(server, projectId, user, agentId, onProjectChange) {
+    const ctx = createContext(projectId, user, agentId);
     // 🔗 初始化
     registerInitTool(server, ctx, onProjectChange || (() => { }));
     // 📊 导航
@@ -42,4 +44,6 @@ export function registerTools(server, projectId, user, onProjectChange) {
     registerMeetingTools(server, ctx);
     // 🔀 流程图
     registerFlowchartTools(server, ctx);
+    // 📘 文档查询
+    registerDocQueryTools(server, ctx);
 }

package/dist/tools/init.js

@@ -60,6 +60,7 @@ export function registerInitTool(server, ctx, onProjectChange) {
         // 4. 更新共享上下文 — 所有工具立刻获得新 projectId
         ctx.projectId = config.projectId;
         ctx.user = config.user;
+        ctx.agentId = process.env.PPDOCS_AGENT_ID || 'default';
         // 5. 通知主进程
         onProjectChange(config.projectId, config.apiUrl);
         return wrap(`✅ 项目上下文已初始化\n\n` +

package/dist/tools/shared.d.ts

@@ -6,9 +6,10 @@
 export interface McpContext {
     projectId: string;
     user: string;
+    agentId: string;
 }
 /** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
-export declare function createContext(projectId: string, user: string): McpContext;
+export declare function createContext(projectId: string, user: string, agentId?: string): McpContext;
 export declare function wrap(text: string): {
     content: {
         type: "text";

package/dist/tools/shared.js

@@ -3,8 +3,8 @@
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
 /** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
-export function createContext(projectId, user) {
-    return { projectId, user };
+export function createContext(projectId, user, agentId = 'default') {
+    return { projectId, user, agentId };
 }
 // ==================== MCP 返回包装 ====================
 export function wrap(text) {

package/package.json

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