@ppdocs/mcp 3.9.1 → 3.12.0

package/dist/cli.js

@@ -90,7 +90,7 @@ function showHelp() {
 ppdocs MCP CLI
 
 Commands:
-  init    Full setup: .ppdocs + templates + MCP registration
+  init    Full setup: .ppdocs + templates + MCP registration (Claude/Codex/OpenCode/Gemini)
   bind    Lightweight: only create .ppdocs (for adding projects to existing MCP)
 
 Usage:
@@ -270,6 +270,13 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         for (const pair of envPairs) {
             args.push(envFlag, pair);
         }
+        // macOS/Linux: 必须注入 PATH，否则 Claude Code 启动 MCP 时可能找不到 npx/node
+        // (Claude Code 进程的 PATH 通常不含 /opt/homebrew/bin 等 Homebrew/nvm 路径)
+        if (process.platform !== 'win32') {
+            const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
+            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
+            args.push(envFlag, `PATH=${fullPath}`);
+        }
         args.push(serverName, '--', 'npx', '-y', '@ppdocs/mcp@latest');
         const result = spawnSync(cli, args, { stdio: 'inherit', shell: true });
         if (result.status !== 0)
@@ -303,6 +310,24 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
             console.log(`⚠️  Codex MCP registration failed`);
         }
     }
+    // OpenCode CLI (opencode mcp add 支持 -e 环境变量注入)
+    if (commandExists('opencode')) {
+        detected.push('OpenCode');
+        try {
+            execSilent(`opencode mcp remove ${serverName}`);
+            mcpAdd('opencode', '-e');
+        }
+        catch {
+            // fallback: 写入 ~/.opencode/mcp.json
+            try {
+                const opencodeConfig = path.join(os.homedir(), '.opencode', 'mcp.json');
+                createMcpConfigAt(opencodeConfig, apiUrl, { user, projectRoot: cwd });
+            }
+            catch {
+                console.log(`⚠️  OpenCode MCP registration failed`);
+            }
+        }
+    }
     // Gemini CLI (gemini mcp add 不支持 --env，直接写 settings.json)
     if (commandExists('gemini') && !skipGemini) {
         detected.push('Gemini');
@@ -315,7 +340,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         }
     }
     if (detected.length === 0) {
-        console.log(`ℹ️  No AI CLI detected (claude/codex/gemini), creating .mcp.json for manual config`);
+        console.log(`ℹ️  No AI CLI detected (claude/codex/opencode/gemini), creating .mcp.json for manual config`);
         return false;
     }
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);

package/dist/config.d.ts

@@ -12,4 +12,5 @@ export interface PpdocsConfig {
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
 /** 生成随机用户名 */
 export declare function generateUser(): string;
+export declare function generateAgentId(): string;
 export declare function loadConfig(): Promise<PpdocsConfig | null>;

package/dist/config.js

@@ -10,6 +10,20 @@ export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
     return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
 }
+/**
+ * 生成唯一 agentId (每个 MCP 进程实例一个)
+ * 格式: "a-{4位随机}" — 简短且足够区分同机多实例
+ * 进程级单例: 同一进程内多次调用返回相同值
+ */
+let _cachedAgentId = null;
+export function generateAgentId() {
+    if (!_cachedAgentId) {
+        const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+        const rand = Array.from({ length: 4 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+        _cachedAgentId = `a-${rand}`;
+    }
+    return _cachedAgentId;
+}
 // ============ 配置读取 ============
 function readEnvConfig() {
     const apiUrl = process.env.PPDOCS_API_URL;
@@ -20,7 +34,7 @@ function readEnvConfig() {
         apiUrl,
         projectId: match?.[1] || 'unknown',
         user: process.env.PPDOCS_USER || generateUser(),
-        agentId: process.env.PPDOCS_AGENT_ID || 'default',
+        agentId: process.env.PPDOCS_AGENT_ID || generateAgentId(),
         source: 'env',
     };
 }
@@ -49,7 +63,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(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || 'default', 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 || generateAgentId(), source: 'file' };
     }
     catch {
         return null;

package/dist/index.js

@@ -14,11 +14,56 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerTools } from './tools/index.js';
 import { initClient } from './storage/httpClient.js';
 import { runCli } from './cli.js';
-import { loadConfig } from './config.js';
+import { loadConfig, generateAgentId } from './config.js';
 // 从 package.json 读取版本号
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 const VERSION = pkg.version;
+/** 启动时连通性检查 — 非阻塞，3秒超时，结果输出到 stderr 供调试 */
+async function checkConnectivity(apiUrl) {
+    // Node.js 18+ 内置 fetch; 旧版本跳过检查
+    if (typeof globalThis.fetch !== 'function') {
+        console.error(`[connectivity] ⏭️  fetch unavailable (Node.js < 18), skipping connectivity check`);
+        return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    try {
+        const response = await fetch(apiUrl, { signal: controller.signal });
+        if (response.ok) {
+            console.error(`[connectivity] ✅ ppdocs server reachable`);
+        }
+        else {
+            console.error(`[connectivity] ⚠️  ppdocs server responded HTTP ${response.status} — check API key/project ID`);
+        }
+    }
+    catch (err) {
+        const apiHost = apiUrl.replace(/\/api\/.*$/, '');
+        if (err instanceof Error && err.name === 'AbortError') {
+            console.error(`[connectivity] ❌ Connection TIMEOUT (3s) to ${apiHost}`);
+            console.error(`[connectivity]    Possible causes:`);
+            console.error(`[connectivity]    1. ppdocs desktop app is not running on the target machine`);
+            console.error(`[connectivity]    2. Firewall blocking port (check Windows Firewall inbound rules)`);
+            console.error(`[connectivity]    3. IP address changed (re-run init with correct --api)`);
+            console.error(`[connectivity]    4. Not on the same network`);
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('ECONNREFUSED')) {
+                console.error(`[connectivity] ❌ Connection REFUSED to ${apiHost}`);
+                console.error(`[connectivity]    ppdocs desktop app is not running, or port is wrong`);
+            }
+            else {
+                console.error(`[connectivity] ❌ Cannot reach ${apiHost}: ${msg}`);
+            }
+        }
+        console.error(`[connectivity]    API URL: ${apiUrl}`);
+        console.error(`[connectivity]    MCP will still start — tools will fail until server is reachable`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 // 检查是否为 CLI 命令
 const args = process.argv.slice(2);
 if (args.length > 0) {
@@ -32,14 +77,16 @@ async function main() {
     // 有配置 → 自动初始化 (环境变量 / .ppdocs)
     if (config) {
         initClient(config.apiUrl);
-        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user}`);
+        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
+        // 启动时连通性检查 (非阻塞, 3秒超时)
+        checkConnectivity(config.apiUrl).catch(() => { });
     }
     else {
         console.error(`ppdocs MCP v${VERSION} | ⏳ 等待 kg_init 初始化项目上下文...`);
     }
     const projectId = config?.projectId || 'pending';
     const user = config?.user || 'agent';
-    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || 'default';
+    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId();
     const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
     registerTools(server, projectId, user, agentId, (newProjectId, newApiUrl) => {
         console.error(`[kg_init] 项目已切换: ${newProjectId}`);

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
-import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference } from './types.js';
+import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference, FetchResult, FileImportResult, Pitfall, PitfallSummary } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     private serverUrl;
@@ -31,6 +31,27 @@ export declare class PpdocsApiClient {
     readReferenceFile(path: string): Promise<string>;
     /** 复制本地文件到参考文件库, 返回相对路径列表 */
     copyReferenceFiles(paths: string[], targetDir?: string): Promise<string[]>;
+    /** 从 URL 拉取文档内容并保存为参考 */
+    fetchRefUrl(url: string, refId?: string): Promise<FetchResult>;
+    /** 导入本地文件内容到参考系统 */
+    importLocalFile(refId: string, sourcePath: string): Promise<FileImportResult>;
+    listPitfalls(): Promise<PitfallSummary[]>;
+    getPitfall(pitfallId: string): Promise<Pitfall | null>;
+    createPitfall(input: {
+        title: string;
+        category?: string;
+        symptom?: string;
+        root_cause?: string;
+        solution?: string;
+        prevention?: string;
+        severity?: string;
+        related_nodes?: string[];
+        source_task?: string;
+        tags?: string[];
+    }): Promise<Pitfall>;
+    savePitfall(pitfall: Pitfall): Promise<boolean>;
+    deletePitfall(pitfallId: string): Promise<boolean>;
+    searchPitfalls(query: string, status?: string, category?: string): Promise<PitfallSummary[]>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string, mode?: 'smart' | 'full'): Promise<Task | null>;
     createTask(task: {

package/dist/storage/httpClient.js

@@ -168,6 +168,56 @@ export class PpdocsApiClient {
             body: JSON.stringify({ paths, target_dir: targetDir }),
         });
     }
+    /** 从 URL 拉取文档内容并保存为参考 */
+    async fetchRefUrl(url, refId) {
+        return this.request('/refs/fetch-url', {
+            method: 'POST',
+            body: JSON.stringify({ url, ref_id: refId }),
+        });
+    }
+    /** 导入本地文件内容到参考系统 */
+    async importLocalFile(refId, sourcePath) {
+        return this.request('/refs/import-file', {
+            method: 'POST',
+            body: JSON.stringify({ ref_id: refId, source_path: sourcePath }),
+        });
+    }
+    // ============ 踩坑经验 API ============
+    async listPitfalls() {
+        return this.request('/pitfalls');
+    }
+    async getPitfall(pitfallId) {
+        try {
+            return await this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async createPitfall(input) {
+        return this.request('/pitfalls', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async savePitfall(pitfall) {
+        await this.request(`/pitfalls/${encodeURIComponent(pitfall.id)}`, {
+            method: 'PUT',
+            body: JSON.stringify(pitfall),
+        });
+        return true;
+    }
+    async deletePitfall(pitfallId) {
+        return this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`, {
+            method: 'DELETE',
+        });
+    }
+    async searchPitfalls(query, status, category) {
+        return this.request('/pitfalls/search', {
+            method: 'POST',
+            body: JSON.stringify({ query, status, category }),
+        });
+    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';

package/dist/storage/types.d.ts

@@ -45,6 +45,41 @@ export interface Reference {
     adoptedBy: AdoptedNode[];
     createdAt: string;
     updatedAt: string;
+    sourceUrl?: string;
+    fetchHistory?: FetchRecord[];
+    fileImportHistory?: FileImportRecord[];
+}
+export interface FetchRecord {
+    fetchedAt: string;
+    url: string;
+    title: string;
+    contentFile: string;
+    contentLength: number;
+    contentPreview: string;
+}
+export interface FetchResult {
+    refId: string;
+    title: string;
+    contentFile: string;
+    contentLength: number;
+    contentPreview: string;
+    fetchCount: number;
+}
+export interface FileImportRecord {
+    importedAt: string;
+    sourcePath: string;
+    storedFile: string;
+    contentLength: number;
+    contentPreview: string;
+    fileType: string;
+}
+export interface FileImportResult {
+    refId: string;
+    sourcePath: string;
+    storedFile: string;
+    contentLength: number;
+    contentPreview: string;
+    importCount: number;
 }
 export interface FileInfo {
     name: string;
@@ -95,3 +130,30 @@ export interface TaskSummary {
     updated_at: string;
     last_log?: string;
 }
+export interface Pitfall {
+    id: string;
+    title: string;
+    category: string;
+    symptom: string;
+    root_cause: string;
+    solution: string;
+    prevention: string;
+    related_nodes: string[];
+    source_task?: string;
+    severity: string;
+    status: string;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+export interface PitfallSummary {
+    id: string;
+    title: string;
+    category: string;
+    severity: string;
+    status: string;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+}

package/dist/tools/discussion.js

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

package/dist/tools/flowchart.js

@@ -318,6 +318,7 @@ function findDirectedPath(chart, fromId, toId) {
 export function registerFlowchartTools(server, _ctx) {
     const client = () => getClient();
     server.tool('kg_flowchart', '🔀 逻辑流程图 — 项目知识图谱的核心。每个节点代表一个模块/函数/概念，节点可绑定文件、内嵌版本化文档。\n' +
+        '★★ 编码前必须先设计：用 batch_add/update_node 在流程图中设计逻辑并验证每个节点正确后才能编码。执行 kg_workflow(id:"design-first") 查看完整工作流 ★★\n' +
         '⚡ 开始任何任务前必须先查图谱：search 搜关键词 → get_node 看详情 → 有 subFlowchart 则递归下探。\n' +
         '📝 完成修改后必须回写：bind 绑定文件 → update_node 更新描述和文档 → 新模块用 batch_add。\n' +
         'actions: list|get|search|get_relations|find_path|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart', {
@@ -380,6 +381,9 @@ export function registerFlowchartTools(server, _ctx) {
                 if (chart.parentChart) {
                     lines.push(`parent: ${chart.parentChart}${chart.parentNode ? `/${chart.parentNode}` : ''}`);
                 }
+                if (chart.projectBrief) {
+                    lines.push('', chart.projectBrief);
+                }
                 // Mermaid 流程图
                 lines.push('', '```mermaid', 'graph TD');
                 // 节点声明

package/dist/tools/index.d.ts

@@ -1,11 +1,11 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 8 个子模块
+ * 15 个工具, 9 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
- * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
+ * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref, kg_pitfall (5个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)

package/dist/tools/index.js

@@ -1,11 +1,11 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 8 个子模块
+ * 15 个工具, 9 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
- * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
+ * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref, kg_pitfall (5个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)
@@ -20,6 +20,7 @@ import { registerTaskTools } from './tasks.js';
 import { registerFileTools } from './files.js';
 import { registerDiscussionTools } from './discussion.js';
 import { registerReferenceTools } from './refs.js';
+import { registerPitfallTools } from './pitfalls.js';
 import { registerAnalyzerTools } from './analyzer.js';
 import { registerMeetingTools } from './meeting.js';
 import { registerFlowchartTools } from './flowchart.js';
@@ -38,6 +39,7 @@ export function registerTools(server, projectId, user, agentId, onProjectChange)
     registerFileTools(server);
     registerDiscussionTools(server, ctx);
     registerReferenceTools(server);
+    registerPitfallTools(server);
     // 🔬 代码分析
     registerAnalyzerTools(server, ctx);
     // 🏛️ 多AI协作

package/dist/tools/init.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
 import { initClient } from '../storage/httpClient.js';
+import { generateAgentId } from '../config.js';
 import { wrap, safeTool } from './shared.js';
 // 当前会话的 API URL (用于幂等检查)
 let currentApiUrl = null;
@@ -74,7 +75,8 @@ export function registerInitTool(server, ctx, onProjectChange) {
         // 4. 更新共享上下文 — 所有工具立刻获得新 projectId
         ctx.projectId = config.projectId;
         ctx.user = config.user;
-        ctx.agentId = process.env.PPDOCS_AGENT_ID || 'default';
+        // agentId: 优先环境变量 > 保留当前值(进程启动时已生成)
+        ctx.agentId = process.env.PPDOCS_AGENT_ID || ctx.agentId || generateAgentId();
         // 5. 通知主进程
         onProjectChange(config.projectId, config.apiUrl);
         return wrap(`✅ 项目上下文已初始化\n\n` +

package/dist/tools/kg_status.d.ts

@@ -1,5 +1,6 @@
 /**
  * 📊 kg_status — 项目速览仪表盘
+ * 一次调用返回项目全貌：摘要、核心模块、活跃任务、快速导航
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/kg_status.js

@@ -1,32 +1,56 @@
 /**
  * 📊 kg_status — 项目速览仪表盘
+ * 一次调用返回项目全貌：摘要、核心模块、活跃任务、快速导航
  */
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';
 export function registerStatusTool(server, ctx) {
     const client = () => getClient();
     server.tool('kg_status', '📊 项目速览仪表盘 — 一键了解项目健康。返回: 流程图节点数、活跃任务数、最近变更。每次对话开始建议首先调用', {}, async () => safeTool(async () => {
-        const [charts, activeTasks, discussions] = await Promise.all([
+        const [charts, activeTasks, discussions, mainChart] = await Promise.all([
             client().listFlowcharts(),
             client().listTasks('active'),
             client().discussionList().catch(() => []),
+            client().getFlowchart('main').catch(() => null),
         ]);
         const nodeCount = charts.reduce((sum, c) => sum + (c.nodeCount || 0), 0);
         const activeDiscussions = discussions.filter((d) => d.status === 'active');
         const lines = [
-            `📊 项目速览 [${ctx.projectId}]`,
-            `🆔 身份: ${ctx.user}${ctx.agentId !== 'default' ? ':' + ctx.agentId : ''}`,
-            ``,
-            `🔀 流程图: ${charts.length} 张 | 📦 节点: ${nodeCount} 个`,
-            `📝 活跃任务: ${activeTasks.length} 个`,
-            `📨 活跃讨论: ${activeDiscussions.length} 个`,
+            `# 项目速览 [${ctx.projectId}]`,
+            `身份: ${ctx.user}:${ctx.agentId}`,
         ];
+        // --- Project Brief ---
+        if (mainChart?.projectBrief) {
+            lines.push('', '## 项目简介', mainChart.projectBrief);
+        }
+        // --- 核心模块 (从 main 图提取) ---
+        if (mainChart?.nodes && mainChart.nodes.length > 0) {
+            lines.push('', '## 核心模块');
+            for (const node of mainChart.nodes) {
+                const badges = [];
+                if (node.subFlowchart)
+                    badges.push(`▶${node.subFlowchart}`);
+                const fileCount = (node.boundFiles?.length ?? 0) + (node.boundDirs?.length ?? 0);
+                if (fileCount > 0)
+                    badges.push(`files=${fileCount}`);
+                const docCount = node.docEntries?.length ?? 0;
+                if (docCount > 0)
+                    badges.push(`docs=${docCount}`);
+                const suffix = badges.length > 0 ? ` [${badges.join(' ')}]` : '';
+                const desc = node.description ? ` — ${node.description.slice(0, 80)}` : '';
+                lines.push(`- **${node.label}** \`${node.id}\`${desc}${suffix}`);
+            }
+        }
+        // --- 当前状态 ---
+        lines.push('', '## 当前状态', `- 流程图: ${charts.length} 张 | 节点: ${nodeCount} 个`, `- 活跃任务: ${activeTasks.length} 个`, `- 活跃讨论: ${activeDiscussions.length} 个`);
         if (activeTasks.length > 0) {
-            lines.push(``, `🔧 进行中的任务:`);
+            lines.push('', '### 进行中的任务');
             for (const t of activeTasks.slice(0, 5)) {
-                lines.push(`  - ${t.title} (${t.id})`);
+                lines.push(`- ${t.title} (\`${t.id}\`)`);
             }
         }
+        // --- 快速导航 ---
+        lines.push('', '## 快速导航', '- `kg_flowchart(get, "main")` — 查看完整架构图', '- `kg_flowchart(get_node, "节点ID", expand:2)` — 深入某个模块', '- `kg_workflow()` — 查看可用工作流', '- `kg_task(get)` — 查看活跃任务详情');
         return wrap(lines.join('\n'));
     }));
 }

package/dist/tools/pitfalls.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 💡 kg_pitfall — 踩坑经验管理
+ * 记录项目中遇到的问题、根因和解决方案，避免重复踩坑
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPitfallTools(server: McpServer): void;