@ppdocs/mcp 3.7.1 → 3.8.0

package/dist/cli.js

@@ -137,7 +137,7 @@ export async function runCli(args) {
 /** 轻量绑定: 仅创建 .ppdocs, 不注册 MCP 不安装模板 */
 function bindProject(opts) {
     writePpdocsConfig(process.cwd(), opts);
-    console.log(`\n🔗 Project bound: ${opts.project}\n   AI will auto-connect via kg_init when opening this directory.\n`);
+    console.log(`\n🔗 Project bound: ${opts.project}\n   AI will auto-connect when opening this directory.\n`);
 }
 /** 写入 .ppdocs 配置文件 (init + bind 复用) */
 function writePpdocsConfig(cwd, opts) {
@@ -199,7 +199,7 @@ async function initProject(opts) {
         }
     }
     // 自动检测并注册 MCP (如果已写入 Antigravity 配置，跳过 gemini CLI 注册避免冲突)
-    const registered = autoRegisterMcp(detectedIdes.includes('antigravity'));
+    const registered = autoRegisterMcp(cwd, apiUrl, opts.user || generateUser(), detectedIdes.includes('antigravity'));
     // 如果没有检测到任何 AI CLI，并且也没有检测到配置文件夹，创建 .mcp.json 作为备用
     if (!registered && !hasIdeDir) {
         createMcpJson(cwd, apiUrl, opts.user);
@@ -254,27 +254,29 @@ function execSilent(cmd) {
     }
     catch { /* ignore */ }
 }
-/** 自动检测 AI CLI 并注册全局 MCP (不注入 env，支持多项目通过 kg_init 切换) */
-function autoRegisterMcp(skipGemini = false) {
+/** 自动检测 AI CLI 并注册全局 MCP，直接注入项目环境变量实现开箱即用 */
+function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
     const addCmd = `-- npx -y @ppdocs/mcp@latest`;
-    // Claude CLI (幂等：已注册则跳过)
+    const envPairs = [
+        `PPDOCS_API_URL=${apiUrl}`,
+        `PPDOCS_USER=${user}`,
+        `PPDOCS_PROJECT_ROOT=${cwd}`,
+    ];
+    const claudeEnvArgs = envPairs.map((pair) => `-e ${JSON.stringify(pair)}`).join(' ');
+    const codexEnvArgs = envPairs.map((pair) => `--env ${JSON.stringify(pair)}`).join(' ');
+    // Claude CLI
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            const list = execSync(`claude mcp list`, { encoding: 'utf-8' });
-            if (list.includes(serverName)) {
-                console.log(`✅ Claude MCP already configured`);
-            }
-            else {
-                execSync(`claude mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
-            }
+            execSilent(`claude mcp remove ${serverName}`);
+            execSync(`claude mcp add ${claudeEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
         }
         catch {
             try {
                 execSilent(`claude mcp remove ${serverName}`);
-                execSync(`claude mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
+                execSync(`claude mcp add ${claudeEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
             }
             catch {
                 console.log(`⚠️  Claude MCP registration failed`);
@@ -286,7 +288,7 @@ function autoRegisterMcp(skipGemini = false) {
         detected.push('Codex');
         try {
             execSilent(`codex mcp remove ${serverName}`);
-            execSync(`codex mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
+            execSync(`codex mcp add ${codexEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
         }
         catch {
             console.log(`⚠️  Codex MCP registration failed`);
@@ -310,7 +312,7 @@ function autoRegisterMcp(skipGemini = false) {
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);
     return true;
 }
-/** 在指定路径创建或更新 mcp.json 配置，注入 PPDOCS_API_URL 环境变量实现启动即就绪 */
+/** 在指定路径创建或更新 mcp.json 配置，注入 PPDOCS_* 环境变量实现启动即就绪 */
 function createMcpConfigAt(mcpPath, apiUrl, options) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
@@ -333,6 +335,8 @@ function createMcpConfigAt(mcpPath, apiUrl, options) {
         env.PPDOCS_API_URL = apiUrl;
         if (options?.user)
             env.PPDOCS_USER = options.user;
+        if (options?.projectRoot)
+            env.PPDOCS_PROJECT_ROOT = options.projectRoot;
     }
     const ppdocsServer = isWindows
         ? { command: 'cmd', args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'], ...(Object.keys(env).length > 0 && { env }) }
@@ -351,7 +355,7 @@ function createMcpConfigAt(mcpPath, apiUrl, options) {
 }
 /** 创建 .mcp.json (手动配置备用) */
 function createMcpJson(cwd, apiUrl, user) {
-    createMcpConfigAt(path.join(cwd, '.mcp.json'), apiUrl, { user });
+    createMcpConfigAt(path.join(cwd, '.mcp.json'), apiUrl, { user, projectRoot: cwd });
 }
 /** 递归复制目录 */
 function copyDirRecursive(src, dest) {
@@ -400,6 +404,8 @@ function generateMcpPermissions() {
         'kg_ref',
         // 流程图
         'kg_flowchart',
+        // 文档查询
+        'kg_doc',
         // 协作
         'kg_meeting',
         // 代码分析
@@ -485,7 +491,7 @@ function installGlobalRules(cwd, filename) {
 }
 /** 安装 Cursor 模板 */
 function installCursorTemplates(cwd, apiUrl, user) {
-    createMcpConfigAt(path.join(cwd, '.cursor', 'mcp.json'), apiUrl, { user });
+    createMcpConfigAt(path.join(cwd, '.cursor', 'mcp.json'), apiUrl, { user, projectRoot: cwd });
     // 2. 生成 .cursor/rules/ppdocs.md (官方标准, .cursorrules 已废弃)
     const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
     if (!fs.existsSync(cursorRulesDir)) {
@@ -578,7 +584,7 @@ function installWorkflows(cwd, extraDirs = []) {
 /** 安装 Antigravity (Gemini IDE) 模板 */
 function installAntigravityTemplates(cwd, apiUrl, user) {
     // Antigravity 由 gemini CLI 注册 env，文件配置不注入避免冲突
-    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true, user });
+    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true, user, projectRoot: cwd });
     // 2. 生成 GEMINI.md 全局规则 (Gemini CLI 官方标准)
     installGlobalRules(cwd, 'GEMINI.md');
     // 3. Antigravity 全局 workflows 目录 (额外安装目标)
@@ -592,7 +598,7 @@ function installAntigravityTemplates(cwd, apiUrl, user) {
 }
 /** 安装 Kiro 模板 */
 function installKiroTemplates(cwd, apiUrl, user) {
-    createMcpConfigAt(path.join(cwd, '.kiro', 'settings', 'mcp.json'), apiUrl, { user });
+    createMcpConfigAt(path.join(cwd, '.kiro', 'settings', 'mcp.json'), apiUrl, { user, projectRoot: cwd });
     // 2. 生成 Kiro Steering 文件 (官方标准: .kiro/steering/ 而非 rules/)
     const steeringDir = path.join(cwd, '.kiro', 'steering');
     if (!fs.existsSync(steeringDir)) {

package/dist/config.js

@@ -24,9 +24,26 @@ function readEnvConfig() {
         source: 'env',
     };
 }
+function findPpdocsFile(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const configPath = path.join(currentDir, PPDOCS_CONFIG_FILE);
+        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
+            return configPath;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
 function readPpdocsFile() {
-    const configPath = path.join(process.cwd(), '.ppdocs');
-    if (!fs.existsSync(configPath))
+    const hintedRoot = process.env.PPDOCS_PROJECT_ROOT;
+    const configPath = hintedRoot
+        ? path.join(path.resolve(hintedRoot), PPDOCS_CONFIG_FILE)
+        : findPpdocsFile();
+    if (!configPath || !fs.existsSync(configPath))
         return null;
     try {
         const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

package/dist/storage/httpClient.js

@@ -9,6 +9,17 @@
 function cleanPath(p) {
     return p.replace(/^\//, '');
 }
+async function readErrorMessage(response) {
+    const statusLine = `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}`;
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const payload = await response.json().catch(() => null);
+        const detail = payload?.error || payload?.message;
+        return detail ? `${statusLine}: ${detail}` : statusLine;
+    }
+    const text = (await response.text().catch(() => '')).trim();
+    return text ? `${statusLine}: ${text}` : statusLine;
+}
 /** 下载 zip 并解压到指定目录或 temp 目录 */
 async function fetchAndExtractZip(url, localPath) {
     const controller = new AbortController();
@@ -16,8 +27,7 @@ async function fetchAndExtractZip(url, localPath) {
     try {
         const response = await fetch(url, { signal: controller.signal });
         if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
+            throw new Error(await readErrorMessage(response));
         }
         const buffer = Buffer.from(await response.arrayBuffer());
         const os = await import('os');
@@ -75,8 +85,7 @@ export class PpdocsApiClient {
                 }
             });
             if (!response.ok) {
-                const error = await response.json().catch(() => ({ error: response.statusText }));
-                throw new Error(error.error || `HTTP ${response.status}`);
+                throw new Error(await readErrorMessage(response));
             }
             const json = await response.json();
             if (!json.success) {
@@ -250,7 +259,7 @@ export class PpdocsApiClient {
     async updateFlowchartNode(chartId, nodeId, node, changeDesc) {
         return this.request(`/flowcharts/${chartId}/nodes/${nodeId}`, {
             method: 'PUT',
-            body: JSON.stringify({ node, change_desc: changeDesc || 'MCP update' })
+            body: JSON.stringify({ node, changeDesc: changeDesc || 'MCP update' })
         });
     }
     /** 原子删除单个节点 (后端自动清理关联边) */
@@ -469,9 +478,10 @@ export function initClient(apiUrl) {
 }
 export function getClient() {
     if (!client) {
-        throw new Error('❌ 项目未初始化！请先调用 kg_init 工具绑定项目上下文。\n\n' +
-            '用法: kg_init({ projectPath: "项目根目录绝对路径" })\n' +
-            '该目录下需存在 .ppdocs 配置文件。');
+        throw new Error('❌ MCP 未连接！请检查:\n' +
+            '1. 环境变量 PPDOCS_API_URL 是否已设置\n' +
+            '2. 或当前目录下是否存在 .ppdocs 配置文件\n\n' +
+            '重新运行: npx @ppdocs/mcp init -p <projectId> -k <key>');
     }
     return client;
 }

package/dist/tools/doc_query.js

@@ -92,13 +92,17 @@ export function registerDocQueryTools(server, _ctx) {
                     .slice(0, decoded.limit ?? 10);
                 if (matches.length === 0)
                     return wrap(`No docs matched: ${rawQuery}`);
-                const rows = matches.map(({ chart, node }) => {
+                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;
-                    const summary = latest ? latest.summary.substring(0, 50) : (node.description?.substring(0, 50) || '');
-                    return `| ${node.label} | ${chart.id}/${node.id} | ${docCount} | ${latest ? shortDate(latest.date).slice(5) : '-'} | ${summary} |`;
-                }).join('\n');
-                return wrap(`Doc search: "${rawQuery}" (${matches.length} results)\n\n| 节点 | 图谱 | 文档数 | 日期 | 摘要 |\n|:-----|:-----|:-------|:-----|:-----|\n${rows}`);
+                    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
@@ -109,43 +113,30 @@ export function registerDocQueryTools(server, _ctx) {
                     .map((n) => ({ chart, node: n })));
                 if (nodesWithDocs.length === 0)
                     return wrap('No nodes with documentation found.');
-                const rows = nodesWithDocs.map(({ chart, node }) => {
+                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 summary = latest ? latest.summary.substring(0, 50) : '';
-                    return `| ${node.label} | ${chart.id}/${node.id} | ${docCount} | ${latest ? shortDate(latest.date).slice(5) : '-'} | ${summary} |`;
-                }).join('\n');
-                return wrap(`Documented nodes: ${nodesWithDocs.length}\n\n| 节点 | 图谱 | 文档数 | 日期 | 摘要 |\n|:-----|:-----|:-------|:-----|:-----|\n${rows}`);
+                    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.');
-                let chart = null;
-                let foundChartId = decoded.chartId || '';
-                if (foundChartId) {
-                    chart = (await getClient().getFlowchart(foundChartId));
-                }
-                else {
-                    // 不指定 chartId 时自动搜全部图
-                    const all = await loadAllCharts();
-                    for (const c of all) {
-                        if (c.nodes.some(n => n.id === decoded.nodeId)) {
-                            chart = c;
-                            foundChartId = c.id;
-                            break;
-                        }
-                    }
-                }
+                const chartId = decoded.chartId || 'main';
+                const chart = (await getClient().getFlowchart(chartId));
                 if (!chart)
-                    return wrap(`Node not found: ${decoded.nodeId}${decoded.chartId ? ` in ${decoded.chartId}` : ' (searched all charts)'}`);
+                    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 ${foundChartId}`);
+                    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} [${foundChartId}/${decoded.nodeId}]`);
+                        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];
@@ -171,7 +162,7 @@ export function registerDocQueryTools(server, _ctx) {
                     return wrap(lines.join('\n'));
                 }
                 // 默认: 返回当前文档 (description + 最新 docEntry)
-                const lines = [`## ${node.label} [${foundChartId}/${node.id}]`, ''];
+                const lines = [`## ${node.label} [${chartId}/${node.id}]`, ''];
                 if (node.description) {
                     lines.push(node.description, '');
                 }

package/dist/tools/flowchart.js

@@ -162,7 +162,6 @@ function buildTopologyTree(chart) {
 function appendDocEntry(node, summary, content) {
     const nextNode = ensureNodeShape(node);
     const entries = nextNode.docEntries ?? [];
-    const version = `v${entries.length + 1}.0`;
     entries.push({
         date: new Date().toISOString(),
         summary: summary.replace(/\\n/g, '\n'),
@@ -170,7 +169,7 @@ function appendDocEntry(node, summary, content) {
     });
     nextNode.docEntries = entries;
     nextNode.lastUpdated = new Date().toISOString();
-    return { node: nextNode, version };
+    return nextNode;
 }
 function collectNeighborLayers(chart, startNodeId, maxDepth) {
     const nodeMap = new Map(chart.nodes.map((node) => [node.id, node]));
@@ -364,10 +363,8 @@ export function registerFlowchartTools(server, _ctx) {
                     return wrap('No flowcharts found.');
                 }
                 const lines = ['Flowcharts:', '', ...charts.map((chart) => {
-                        const parent = chart.parentChart
-                            ? ` ← ${chart.parentChart}${chart.parentNode ? `/${chart.parentNode}` : ''}`
-                            : '';
-                        return `- ${chart.title} [${chart.id}] ${chart.nodeCount}n/${chart.edgeCount}e${parent}`;
+                        const parent = chart.parentChart ? ` parent=${chart.parentChart}` : '';
+                        return `- ${chart.title} [${chart.id}] ${chart.nodeCount} nodes / ${chart.edgeCount} edges${parent}`;
                     })];
                 return wrap(lines.join('\n'));
             }
@@ -396,27 +393,26 @@ export function registerFlowchartTools(server, _ctx) {
                     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 meta = `${n.nodeType ?? 'process'}/${n.domain ?? 'system'}`;
+                    const badges = [];
+                    const fileCount = (n.boundFiles?.length ?? 0) + (n.boundDirs?.length ?? 0);
+                    if (fileCount > 0)
+                        badges.push(`files=${fileCount}`);
+                    if (n.boundTasks?.length)
+                        badges.push(`tasks=${n.boundTasks.length}`);
+                    const docCount = n.docEntries?.length ?? 0;
+                    if (docCount > 0)
+                        badges.push(`docs=${docCount}`);
+                    if (n.subFlowchart)
+                        badges.push(`▶${n.subFlowchart}`);
+                    const suffix = badges.length > 0 ? ` [${badges.join(' ')}]` : '';
+                    const desc = n.description
+                        ? `\n  > ${n.description.slice(0, 120)}${n.description.length > 120 ? '…' : ''}`
                         : '';
-                    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} |`);
+                    lines.push(`- **${n.label}** \`${n.id}\` (${meta})${suffix}${desc}`);
                 }
                 return wrap(lines.join('\n'));
             }
@@ -663,7 +659,6 @@ export function registerFlowchartTools(server, _ctx) {
                         dirs.forEach((dirPath) => lines.push(`- ${dirPath}/`));
                     }
                 }
-                // Versions 已由 docEntries 历史替代，不再输出
                 return wrap(lines.join('\n').trim());
             }
             case 'update_node': {
@@ -688,9 +683,8 @@ export function registerFlowchartTools(server, _ctx) {
                 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 = appendDocEntry(nextNode, '[auto] description更新前快照', nextNode.description);
+                        changes.push('docArchive');
                     }
                     nextNode.description = decoded.description;
                     changes.push('description');
@@ -719,9 +713,8 @@ export function registerFlowchartTools(server, _ctx) {
                     if (!decoded.docSummary || !decoded.docContent) {
                         return wrap('update_node requires both docSummary and docContent when updating docs.');
                     }
-                    const result = appendDocEntry(nextNode, decoded.docSummary, decoded.docContent);
-                    nextNode = result.node;
-                    changes.push(`docEntries(${result.version})`);
+                    nextNode = appendDocEntry(nextNode, decoded.docSummary, decoded.docContent);
+                    changes.push('docEntries');
                 }
                 if (changes.length === 0) {
                     return wrap('No fields were updated.');

package/dist/tools/init.js

@@ -14,10 +14,24 @@ import { initClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';
 // 当前会话的 API URL (用于幂等检查)
 let currentApiUrl = null;
+function findPpdocsPathFrom(dir) {
+    let currentDir = path.resolve(dir);
+    while (true) {
+        const configPath = path.join(currentDir, '.ppdocs');
+        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
+            return configPath;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
 /** 尝试从指定目录读取 .ppdocs 配置 */
 function readPpdocsFrom(dir) {
-    const configPath = path.join(dir, '.ppdocs');
-    if (!fs.existsSync(configPath))
+    const configPath = findPpdocsPathFrom(dir);
+    if (!configPath)
         return null;
     try {
         const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

package/package.json

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

package/templates/AGENT.md

@@ -3,7 +3,7 @@
 ## 0. ????
 
 ```text
-kg_init()                 -> ????
+kg_init()                 -> optional fallback when auto-connect is missing
 kg_status()               -> ???????
 kg_task(action:"get")     -> ?? active ??
 kg_discuss(action:"list") -> ???????

package/templates/commands/pp/init.md

@@ -27,7 +27,7 @@
 
 ### Phase 0: 环境准备
 ```
-kg_init()                   → 连接项目上下文
+kg_init()                   → 仅在自动连接失效时手动兜底
 kg_status()                 → 查看仪表盘 (流程图/任务/状态)
 kg_flowchart(action:"list") → 已有流程图列表
 kg_flowchart(action:"get")  → 主图结构总览

package/templates/commands/pp/sync.md

@@ -29,7 +29,7 @@
 
 **1.1 获取图谱现状**
 ```
-kg_init()                        → 确保项目连接
+kg_init()                        → 仅在自动连接失效时手动兜底
 kg_flowchart(action:"list")      → 所有流程图
 kg_flowchart(action:"get")       → 主图节点+连线
 kg_flowchart(action:"search", query:"关键词") → 快速定位相关节点

package/templates/cursorrules.md

@@ -3,7 +3,7 @@
 ## 0. ????
 
 ```text
-kg_init()                 -> ????
+kg_init()                 -> optional fallback when auto-connect is missing
 kg_status()               -> ???????
 kg_task(action:"get")     -> ?? active ??
 kg_discuss(action:"list") -> ???????

package/templates/kiro-rules/ppdocs.md

@@ -3,7 +3,7 @@
 ## 0. ????
 
 ```text
-kg_init()                 -> ????
+kg_init()                 -> optional fallback when auto-connect is missing
 kg_status()               -> ???????
 kg_task(action:"get")     -> ?? active ??
 kg_discuss(action:"list") -> ???????