mcp-probe-kit 3.0.12 → 3.0.13

package/build/tools/code_insight.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { parseArgs, getString, getNumber, getBoolean } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
@@ -70,12 +71,149 @@ function summarizeExecutions(executions) {
     return executions
         .map((item) => {
         if (item.ok) {
-            return `- ✅ ${item.tool}: ${(item.text || "已返回结果").replace(/\s+/g, " ").slice(0, 180)}`;
+            const suffix = item.status ? ` [${item.status}]` : "";
+            return `- ✅ ${item.tool}${suffix}: ${(item.text || "已返回结果").replace(/\s+/g, " ").slice(0, 180)}`;
         }
         return `- ⚠️ ${item.tool}: ${(item.error || "调用失败").replace(/\s+/g, " ").slice(0, 180)}`;
     })
         .join("\n");
 }
+export function deriveCodeInsightStatus(result) {
+    if (!result.available) {
+        return "degraded";
+    }
+    if (result.ambiguities.length > 0) {
+        return "ambiguous";
+    }
+    const successfulStatuses = result.executions
+        .filter((item) => item.ok)
+        .map((item) => item.status)
+        .filter((item) => Boolean(item));
+    if (successfulStatuses.length > 0 && successfulStatuses.every((item) => item === "not_found")) {
+        return "not_found";
+    }
+    return "ok";
+}
+function formatStatusLabel(status) {
+    switch (status) {
+        case "ambiguous":
+            return "歧义";
+        case "degraded":
+            return "降级";
+        case "not_found":
+            return "未找到";
+        default:
+            return "可用";
+    }
+}
+function formatAmbiguities(ambiguities) {
+    if (ambiguities.length === 0) {
+        return "";
+    }
+    return ambiguities
+        .map((ambiguity) => {
+        const lines = [`- ${ambiguity.tool}: ${ambiguity.message || "存在多个候选符号"}`];
+        for (const candidate of ambiguity.candidates.slice(0, 5)) {
+            const parts = [
+                typeof candidate.uid === "string" ? `uid=${candidate.uid}` : "",
+                typeof candidate.name === "string" ? `name=${candidate.name}` : "",
+                typeof candidate.file_path === "string" ? `file_path=${candidate.file_path}` : "",
+            ].filter(Boolean);
+            lines.push(`  - ${parts.join(" | ") || JSON.stringify(candidate)}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n");
+}
+function createProjectDocsPlan(projectRoot, docsDirName, docsSnapshot) {
+    const docsDir = path.dirname(docsSnapshot.markdownFilePath);
+    return {
+        docsDir,
+        projectContextFilePath: toPosixPath(path.join(path.resolve(projectRoot), docsDirName, "project-context.md")),
+        latestMarkdownFilePath: toPosixPath(path.join(docsDir, "latest.md")),
+        latestJsonFilePath: toPosixPath(path.join(docsDir, "latest.json")),
+        archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
+        archiveJsonFilePath: docsSnapshot.jsonFilePath,
+        navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
+`,
+        devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
+`,
+    };
+}
+export function buildCodeInsightDelegatedPlan(input) {
+    if (!input.showPlan) {
+        return undefined;
+    }
+    if (input.status === "ambiguous" && input.ambiguities.length > 0) {
+        return {
+            mode: "delegated",
+            kind: "ambiguity",
+            steps: [
+                {
+                    id: "inspect-candidates",
+                    action: "阅读本次返回的 candidates，确认目标符号对应的 uid 或 file_path",
+                    note: "若存在同名符号，优先使用 uid；需要限定文件时使用 file_path",
+                },
+                {
+                    id: "rerun-with-disambiguate",
+                    action: "重新调用 code_insight，并显式传入 uid 或 file_path 完成消歧",
+                },
+                {
+                    id: "resume-analysis",
+                    action: "消歧后再继续 context/impact 分析，必要时再决定是否保存到 docs/graph-insights",
+                },
+            ],
+        };
+    }
+    if (!input.projectDocs) {
+        return undefined;
+    }
+    const projectContextExists = fs.existsSync(input.projectDocs.projectContextFilePath);
+    return {
+        mode: "delegated",
+        kind: "docs",
+        steps: [
+            {
+                id: "ensure-project-context",
+                action: projectContextExists
+                    ? `确认 ${input.projectDocs.projectContextFilePath} 已存在并可更新`
+                    : `检查 ${input.projectDocs.projectContextFilePath} 是否存在；若不存在，先调用 init_project_context 生成项目上下文索引`,
+                outputs: [input.projectDocs.projectContextFilePath],
+                note: projectContextExists
+                    ? "已有项目上下文，可直接补充图谱入口"
+                    : "只有 project-context.md 存在，后续图谱文档入口才可持续复用",
+            },
+            {
+                id: "save-latest-md",
+                action: `将本次 code_insight 的文本分析结果写入 ${input.projectDocs.latestMarkdownFilePath}`,
+                outputs: [input.projectDocs.latestMarkdownFilePath],
+            },
+            {
+                id: "save-archive-md",
+                action: `将本次 code_insight 的文本分析结果归档到 ${input.projectDocs.archiveMarkdownFilePath}`,
+                outputs: [input.projectDocs.archiveMarkdownFilePath],
+            },
+            {
+                id: "save-latest-json",
+                action: `将本次 code_insight 的 structuredContent 写入 ${input.projectDocs.latestJsonFilePath}`,
+                outputs: [input.projectDocs.latestJsonFilePath],
+                note: "建议保留完整结构化结果，便于后续 AI 继续读取",
+            },
+            {
+                id: "save-archive-json",
+                action: `将本次 code_insight 的 structuredContent 归档到 ${input.projectDocs.archiveJsonFilePath}`,
+                outputs: [input.projectDocs.archiveJsonFilePath],
+            },
+            {
+                id: "update-project-context-index",
+                action: `更新 ${input.projectDocs.projectContextFilePath}，在“## 📚 文档导航”加入图谱文档入口，并在“## 💡 开发时查看对应文档”加入代码图谱洞察链接`,
+                outputs: [input.projectDocs.projectContextFilePath],
+                note: `建议插入内容:\n${input.projectDocs.navigationSnippet}\n${input.projectDocs.devGuideSnippet}`,
+            },
+        ],
+    };
+}
 export function resolveCodeInsightQuery(input) {
     const finalTarget = input.target || ((input.mode === "context" || input.mode === "impact") ? input.input : "");
     const finalQuery = input.query
@@ -91,18 +229,23 @@ export async function codeInsight(args, context) {
                 mode: "auto",
                 query: "",
                 target: "",
+                uid: "",
+                file_path: "",
                 repo: "",
                 goal: "",
                 task_context: "",
                 direction: "",
                 max_depth: 3,
                 include_tests: false,
+                include_content: false,
             },
             primaryField: "input",
             fieldAliases: {
                 mode: ["m", "模式"],
                 query: ["q", "keyword", "关键词"],
                 target: ["symbol", "name", "目标符号"],
+                uid: ["symbol_uid", "候选uid"],
+                file_path: ["filePath", "filepath", "文件路径"],
                 repo: ["repository", "仓库"],
                 project_root: ["projectRoot", "project_path", "path", "dir", "directory", "项目路径", "项目根目录"],
                 docs_dir: ["docsDir", "docs", "文档目录"],
@@ -111,11 +254,16 @@ export async function codeInsight(args, context) {
                 direction: ["dir", "方向"],
                 max_depth: ["depth", "maxDepth", "最大深度"],
                 include_tests: ["includeTests", "包含测试"],
+                include_content: ["includeContent", "包含代码"],
+                save_to_docs: ["saveToDocs", "保存到文档"],
+                delegated_plan: ["delegatedPlan", "生成计划"],
             },
         });
         const mode = normalizeMode(getString(parsedArgs.mode, "auto"));
         const query = getString(parsedArgs.query);
         const target = getString(parsedArgs.target);
+        const uid = getString(parsedArgs.uid);
+        const filePath = getString(parsedArgs.file_path);
         const repo = getString(parsedArgs.repo);
         const projectRoot = getString(parsedArgs.project_root);
         const docsDirName = getString(parsedArgs.docs_dir) || "docs";
@@ -124,6 +272,8 @@ export async function codeInsight(args, context) {
         const direction = normalizeDirection(getString(parsedArgs.direction));
         const maxDepth = Math.max(1, getNumber(parsedArgs.max_depth, 3));
         const includeTests = getBoolean(parsedArgs.include_tests, false);
+        const includeContent = getBoolean(parsedArgs.include_content, false);
+        const saveToDocs = getBoolean(parsedArgs.save_to_docs, Boolean(projectRoot || parsedArgs.docs_dir));
         const input = getString(parsedArgs.input);
         const { finalQuery, finalTarget } = resolveCodeInsightQuery({
             mode,
@@ -136,6 +286,8 @@ export async function codeInsight(args, context) {
             mode,
             query: finalQuery,
             target: finalTarget,
+            uid: uid || undefined,
+            filePath: filePath || undefined,
             repo: repo || undefined,
             projectRoot: projectRoot || undefined,
             goal: goal || undefined,
@@ -143,19 +295,25 @@ export async function codeInsight(args, context) {
             direction,
             maxDepth,
             includeTests,
+            includeContent,
             signal: context?.signal,
         });
+        const status = deriveCodeInsightStatus(result);
+        const showDelegatedPlan = getBoolean(parsedArgs.delegated_plan, saveToDocs || status === "ambiguous");
         const executionSummary = summarizeExecutions(result.executions.map((item) => ({
             tool: item.tool,
             ok: item.ok,
             text: item.text,
             error: item.error,
+            status: item.status,
         })));
+        const ambiguityText = formatAmbiguities(result.ambiguities);
         const message = `# code_insight 图谱分析结果
 
-状态: ${result.available ? "可用" : "降级"}
+状态: ${formatStatusLabel(status)}
 模式: ${result.modeRequested} -> ${result.modeResolved}
 来源: ${result.provider}
+启动策略: ${result.launcherStrategy}
 工作区: ${result.workspaceMode}
 源目录: ${result.sourceRoot}
 
@@ -165,9 +323,10 @@ ${result.summary}
 执行详情:
 ${executionSummary}
 
+${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
 ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.trim();
         const structured = {
-            status: result.available ? "ok" : "degraded",
+            status,
             provider: result.provider,
             mode: {
                 requested: result.modeRequested,
@@ -177,85 +336,57 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
             warnings: result.warnings,
             executions: result.executions,
             repo: result.repo || null,
+            launcherStrategy: result.launcherStrategy,
+            ambiguities: result.ambiguities,
             workspaceMode: result.workspaceMode,
             sourceRoot: result.sourceRoot,
             analysisRoot: result.analysisRoot,
             pathMapped: result.pathMapped,
         };
+        const docsProjectRoot = saveToDocs ? (projectRoot || result.sourceRoot) : "";
         const docsSnapshot = buildProjectDocsOutputs({
-            projectRoot: projectRoot || result.sourceRoot,
+            projectRoot: docsProjectRoot,
             docsDirName,
             mode,
             structured,
         });
-        let projectDocs;
-        let persistencePlan;
-        if (docsSnapshot) {
-            const docsDir = path.dirname(docsSnapshot.markdownFilePath);
-            projectDocs = {
-                docsDir,
-                projectContextFilePath: toPosixPath(path.join(path.resolve(projectRoot || result.sourceRoot), docsDirName, "project-context.md")),
-                latestMarkdownFilePath: toPosixPath(path.join(docsDir, "latest.md")),
-                latestJsonFilePath: toPosixPath(path.join(docsDir, "latest.json")),
-                archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
-                archiveJsonFilePath: docsSnapshot.jsonFilePath,
-                navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
-最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
-`,
-                devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
-`,
-            };
+        const projectDocs = docsSnapshot
+            ? createProjectDocsPlan(docsProjectRoot, docsDirName, docsSnapshot)
+            : undefined;
+        if (projectDocs) {
             structured.projectDocs = projectDocs;
-            structured.nextAction = `请按 delegated plan 落盘图谱文档，并更新 ${projectDocs.projectContextFilePath} 的索引入口`;
-            persistencePlan = {
-                mode: "delegated",
-                steps: [
-                    {
-                        id: "ensure-project-context",
-                        action: `检查 ${projectDocs.projectContextFilePath} 是否存在；若不存在，先调用 init_project_context 生成项目上下文索引`,
-                        outputs: [projectDocs.projectContextFilePath],
-                        note: "只有 project-context.md 存在，后续图谱文档入口才可持续复用",
-                    },
-                    {
-                        id: "save-latest-md",
-                        action: `将本次 code_insight 的文本分析结果写入 ${projectDocs.latestMarkdownFilePath}`,
-                        outputs: [projectDocs.latestMarkdownFilePath],
-                    },
-                    {
-                        id: "save-archive-md",
-                        action: `将本次 code_insight 的文本分析结果归档到 ${projectDocs.archiveMarkdownFilePath}`,
-                        outputs: [projectDocs.archiveMarkdownFilePath],
-                    },
-                    {
-                        id: "save-latest-json",
-                        action: `将本次 code_insight 的 structuredContent 写入 ${projectDocs.latestJsonFilePath}`,
-                        outputs: [projectDocs.latestJsonFilePath],
-                        note: "建议保留完整结构化结果，便于后续 AI 继续读取",
-                    },
-                    {
-                        id: "save-archive-json",
-                        action: `将本次 code_insight 的 structuredContent 归档到 ${projectDocs.archiveJsonFilePath}`,
-                        outputs: [projectDocs.archiveJsonFilePath],
-                    },
-                    {
-                        id: "update-project-context-index",
-                        action: `更新 ${projectDocs.projectContextFilePath}，在“## 📚 文档导航”加入图谱文档入口，并在“## 💡 开发时查看对应文档”加入代码图谱洞察链接`,
-                        outputs: [projectDocs.projectContextFilePath],
-                        note: `建议插入内容:\n${projectDocs.navigationSnippet}\n${projectDocs.devGuideSnippet}`,
-                    },
-                ],
-            };
-            structured.plan = persistencePlan;
         }
-        return okStructured(projectDocs && persistencePlan
+        const delegatedPlan = buildCodeInsightDelegatedPlan({
+            status,
+            ambiguities: result.ambiguities,
+            projectDocs,
+            showPlan: showDelegatedPlan,
+        });
+        if (delegatedPlan) {
+            structured.plan = delegatedPlan;
+        }
+        structured.nextAction = delegatedPlan?.kind === "ambiguity"
+            ? "请先选择 uid 或 file_path 重新调用 code_insight 完成消歧"
+            : projectDocs
+                ? `请按 delegated plan 落盘图谱文档，并更新 ${projectDocs.projectContextFilePath} 的索引入口`
+                : null;
+        return okStructured(delegatedPlan
             ? `${renderOrchestrationHeader({
                 tool: "code_insight",
-                goal: "完成图谱分析后，将结果按 delegated plan 落盘到 docs/graph-insights",
-                tasks: [
-                    "先消费本次 code_insight 返回的分析结果",
-                    "严格按 delegated plan 将 Markdown / JSON 保存到指定路径",
-                    "不要只口头总结而不写文件",
-                ],
+                goal: delegatedPlan.kind === "ambiguity"
+                    ? "先完成符号消歧，再继续图谱分析"
+                    : "完成图谱分析后，将结果按 delegated plan 落盘到 docs/graph-insights",
+                tasks: delegatedPlan.kind === "ambiguity"
+                    ? [
+                        "先阅读本次 code_insight 返回的 candidates",
+                        "使用 uid 或 file_path 重新调用 code_insight",
+                        "消歧完成后再继续后续分析或文档保存",
+                    ]
+                    : [
+                        "先消费本次 code_insight 返回的分析结果",
+                        "严格按 delegated plan 将 Markdown / JSON 保存到指定路径",
+                        "不要只口头总结而不写文件",
+                    ],
                 notes: [
                     `工作区模式: ${result.workspaceMode}`,
                     `来源目录: ${result.sourceRoot}`,
@@ -263,13 +394,15 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
             })}${message}
 
 ## delegated plan
-${renderPlanSteps(persistencePlan.steps)}
+${renderPlanSteps(delegatedPlan.steps)}
 
-后续操作:
+${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
 - 请先确保 ${projectDocs.projectContextFilePath} 可用，并把图谱入口挂到该索引中
 - 请将本次分析保存到 ${projectDocs.latestMarkdownFilePath}
 - 如需归档，请额外保存到 ${projectDocs.archiveMarkdownFilePath}
-- 如需结构化副本，请保存 JSON 到 ${projectDocs.latestJsonFilePath} 或 ${projectDocs.archiveJsonFilePath}`
+- 如需结构化副本，请保存 JSON 到 ${projectDocs.latestJsonFilePath} 或 ${projectDocs.archiveJsonFilePath}` : `后续操作:
+- 请先从 candidates 中选定唯一符号
+- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}`
             : message, structured);
     }
     catch (error) {

package/docs/i18n/en.json

@@ -87,6 +87,14 @@
         "noteText": "Need to manually run",
         "updateText": "to update version"
       },
+      "windowsGraph": {
+        "title": "Windows Notes for Graph Tools",
+        "description": "Graph-aware tools may have a slower first run on Windows because GitNexus is started through npx by default.",
+        "item1": "The first cold start may take 20+ seconds while npx checks or downloads dependencies.",
+        "item2": "Some GitNexus dependencies use tree-sitter native modules and may require Visual Studio Build Tools.",
+        "item3": "If your MCP client supports env, prefer a preinstalled gitnexus CLI and raise GitNexus timeouts.",
+        "exampleTitle": "Example using a preinstalled gitnexus CLI:"
+      },
       "source": {
         "title": "Build from Source",
         "description": "Build from source code, suitable for developers:",
@@ -165,6 +173,18 @@
         "step2": "If below v16, please upgrade Node.js",
         "step3": "Clear cache and reinstall:",
         "step4": "Check if configuration file JSON format is correct"
+      },
+      "q3": {
+        "title": "Issue 3: Graph-aware tools are slow or time out on first run on Windows",
+        "affected": "Affected tools:",
+        "error": "Typical error:",
+        "reasons": "Common causes:",
+        "reason1": "`npx -y gitnexus@latest mcp` may spend 20+ seconds checking or downloading dependencies on cold start.",
+        "reason2": "GitNexus depends on tree-sitter native modules, which may require Visual Studio Build Tools on Windows.",
+        "solution": "Recommended actions:",
+        "step1": "Install Visual Studio Build Tools with the C++ workload.",
+        "step2": "Retry once after dependencies finish installing so the first cold start is not mistaken for steady-state latency.",
+        "step3": "If your client supports env, prefer a preinstalled gitnexus CLI and raise MCP_GITNEXUS_CONNECT_TIMEOUT_MS plus MCP_GITNEXUS_TIMEOUT_MS."
       }
     },
     "common": {

package/docs/i18n/ja.json

@@ -87,6 +87,14 @@
         "noteText": "手動で実行する必要があります",
         "updateText": "バージョンを更新"
       },
+      "windowsGraph": {
+        "title": "Windows 向けグラフツール補足",
+        "description": "グラフ関連ツールは、GitNexus を既定で npx 経由で起動するため、Windows では初回起動が遅くなる場合があります。",
+        "item1": "初回のコールドスタートでは、npx が依存関係を確認またはダウンロードするため 20 秒以上かかることがあります。",
+        "item2": "GitNexus の一部依存関係は tree-sitter ネイティブモジュールを使用しており、Windows では Visual Studio Build Tools が必要になる場合があります。",
+        "item3": "MCP クライアントが env をサポートしている場合は、プリインストール済みの gitnexus CLI を優先し、GitNexus のタイムアウトを引き上げてください。",
+        "exampleTitle": "プリインストール済み gitnexus CLI を使う設定例："
+      },
       "source": {
         "title": "ソースからビルド",
         "description": "ソースコードからビルド、開発者向け：",
@@ -165,6 +173,18 @@
         "step2": "v16未満の場合、Node.jsをアップグレードしてください",
         "step3": "キャッシュをクリアして再インストール：",
         "step4": "設定ファイルのJSON形式が正しいか確認"
+      },
+      "q3": {
+        "title": "問題3：Windows でグラフツールの初回起動が遅い、またはタイムアウトする",
+        "affected": "影響を受けるツール：",
+        "error": "典型的なエラー：",
+        "reasons": "よくある原因：",
+        "reason1": "`npx -y gitnexus@latest mcp` はコールドスタートのため、初回は依存関係の確認やダウンロードに 20 秒以上かかることがあります。",
+        "reason2": "GitNexus が依存する tree-sitter ネイティブモジュールは、Windows で Visual Studio Build Tools を必要とする場合があります。",
+        "solution": "推奨対応：",
+        "step1": "C++ ワークロード付きの Visual Studio Build Tools をインストールしてください。",
+        "step2": "依存関係のインストール完了後にもう一度実行し、初回のコールドスタートを通常レイテンシと混同しないでください。",
+        "step3": "クライアントが env をサポートしている場合は、プリインストール済みの gitnexus CLI を優先し、MCP_GITNEXUS_CONNECT_TIMEOUT_MS と MCP_GITNEXUS_TIMEOUT_MS を引き上げてください。"
       }
     },
     "common": {

package/docs/i18n/ko.json

@@ -87,6 +87,14 @@
         "noteText": "수동으로 실행 필요",
         "updateText": "버전 업데이트"
       },
+      "windowsGraph": {
+        "title": "Windows 그래프 도구 안내",
+        "description": "그래프 관련 도구는 기본적으로 GitNexus 를 npx 로 시작하므로 Windows 에서 첫 실행이 느릴 수 있습니다.",
+        "item1": "첫 콜드 스타트에서는 npx 가 의존성을 확인하거나 다운로드하므로 20초 이상 걸릴 수 있습니다.",
+        "item2": "GitNexus 의 일부 의존성은 tree-sitter 네이티브 모듈을 사용하며 Windows 에서는 Visual Studio Build Tools 가 필요할 수 있습니다.",
+        "item3": "MCP 클라이언트가 env 를 지원하면, 미리 설치한 gitnexus CLI 를 우선 사용하고 GitNexus 타임아웃을 늘리세요.",
+        "exampleTitle": "미리 설치한 gitnexus CLI 를 사용하는 구성 예시:"
+      },
       "source": {
         "title": "소스에서 빌드",
         "description": "소스 코드에서 빌드, 개발자용：",
@@ -165,6 +173,18 @@
         "step2": "v16 미만인 경우 Node.js를 업그레이드하세요",
         "step3": "캐시 지우기 및 재설치：",
         "step4": "구성 파일 JSON 형식이 올바른지 확인"
+      },
+      "q3": {
+        "title": "문제 3：Windows 에서 그래프 도구의 첫 실행이 느리거나 시간 초과됨",
+        "affected": "영향받는 도구：",
+        "error": "대표 오류：",
+        "reasons": "주요 원인：",
+        "reason1": "`npx -y gitnexus@latest mcp` 는 콜드 스타트이므로 첫 실행 시 의존성 확인 또는 다운로드에 20초 이상 걸릴 수 있습니다.",
+        "reason2": "GitNexus 가 의존하는 tree-sitter 네이티브 모듈은 Windows 에서 Visual Studio Build Tools 가 필요할 수 있습니다.",
+        "solution": "권장 조치：",
+        "step1": "C++ 워크로드가 포함된 Visual Studio Build Tools 를 설치하세요.",
+        "step2": "의존성 설치가 끝난 뒤 다시 한 번 실행해서 첫 콜드 스타트를 정상 지연과 구분하세요.",
+        "step3": "클라이언트가 env 를 지원하면 미리 설치한 gitnexus CLI 를 우선 사용하고 MCP_GITNEXUS_CONNECT_TIMEOUT_MS 와 MCP_GITNEXUS_TIMEOUT_MS 를 늘리세요."
       }
     },
     "common": {

package/docs/i18n/zh-CN.json

@@ -87,6 +87,14 @@
         "noteText": "需要手动运行",
         "updateText": "更新版本"
       },
+      "windowsGraph": {
+        "title": "Windows 图谱工具特别说明",
+        "description": "图谱相关工具在 Windows 上首次运行可能更慢，因为 GitNexus 默认通过 npx 启动。",
+        "item1": "首次冷启动时，npx 可能检查或下载依赖，耗时可能超过 20 秒。",
+        "item2": "GitNexus 的部分依赖使用 tree-sitter 原生模块，在 Windows 上可能需要 Visual Studio Build Tools。",
+        "item3": "如果 MCP 客户端支持 env，优先使用预装的 gitnexus CLI，并适当增大 GitNexus 超时。",
+        "exampleTitle": "使用预装 gitnexus CLI 的配置示例："
+      },
       "source": {
         "title": "源码编译",
         "description": "从源码编译安装，适合开发者：",
@@ -165,6 +173,18 @@
         "step2": "如果低于 v16，请升级 Node.js",
         "step3": "清理缓存并重新安装：",
         "step4": "检查配置文件 JSON 格式是否正确"
+      },
+      "q3": {
+        "title": "问题 3：Windows 下图谱工具首次启动很慢或超时",
+        "affected": "受影响工具：",
+        "error": "典型错误：",
+        "reasons": "常见原因：",
+        "reason1": "`npx -y gitnexus@latest mcp` 冷启动时可能花 20 秒以上检查或下载依赖。",
+        "reason2": "GitNexus 依赖的 tree-sitter 原生模块在 Windows 上可能需要 Visual Studio Build Tools。",
+        "solution": "建议处理：",
+        "step1": "安装带 C++ 工作负载的 Visual Studio Build Tools。",
+        "step2": "依赖安装完成后重试一次，避免把首次冷启动误判为稳定耗时。",
+        "step3": "如果客户端支持 env，优先使用预装的 gitnexus CLI，并增大 MCP_GITNEXUS_CONNECT_TIMEOUT_MS 与 MCP_GITNEXUS_TIMEOUT_MS。"
       }
     },
     "common": {

package/docs/pages/getting-started.html

@@ -308,9 +308,39 @@ npm run build</code></pre>
                                 <strong data-i18n="gettingStarted.step1.source.note">注意：</strong><span data-i18n="gettingStarted.step1.source.noteText">修改代码后需要重新运行</span> <code class="bg-gray-200 px-1 rounded text-xs">npm run build</code> <span data-i18n="gettingStarted.step1.source.compileText">编译</span>
                             </div>
                         </div>
-                    </div>
-                </div>
-            </section>
+                    </div>
+
+                    <div class="mt-5 p-4 bg-blue-50 border-l-4 border-blue-500 rounded-r text-sm text-text-primary">
+                        <h3 class="font-semibold mb-2" data-i18n="gettingStarted.step1.windowsGraph.title">Windows Notes for Graph Tools</h3>
+                        <p class="mb-2 text-text-secondary" data-i18n="gettingStarted.step1.windowsGraph.description">Graph-aware tools may have a slower first run on Windows because GitNexus is started through npx by default.</p>
+                        <ul class="list-disc list-inside space-y-1 mb-3">
+                            <li data-i18n="gettingStarted.step1.windowsGraph.item1">The first cold start may take 20+ seconds while npx checks or downloads dependencies.</li>
+                            <li data-i18n="gettingStarted.step1.windowsGraph.item2">Some GitNexus dependencies use tree-sitter native modules and may require Visual Studio Build Tools.</li>
+                            <li data-i18n="gettingStarted.step1.windowsGraph.item3">If your MCP client supports env, prefer a preinstalled gitnexus CLI and raise GitNexus timeouts.</li>
+                        </ul>
+                        <p class="mb-2" data-i18n="gettingStarted.step1.windowsGraph.exampleTitle">Example using a preinstalled gitnexus CLI:</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">JSON</span>
+                                <button onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors">📋</button>
+                            </div>
+                            <pre class="code-block p-3 text-sm text-slate-200 overflow-x-auto"><code>{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "mcp-probe-kit",
+      "env": {
+        "MCP_GITNEXUS_COMMAND": "gitnexus",
+        "MCP_GITNEXUS_ARGS": "mcp",
+        "MCP_GITNEXUS_CONNECT_TIMEOUT_MS": "30000",
+        "MCP_GITNEXUS_TIMEOUT_MS": "45000"
+      }
+    }
+  }
+}</code></pre>
+                        </div>
+                    </div>
+                </div>
+            </section>
 
             <!-- Step 2: 配置文件位置 -->
             <section class="bg-white rounded-xl border border-border p-4 sm:p-6 mb-6 shadow-sm">
@@ -493,9 +523,9 @@ npm run build</code></pre>
                 </div>
 
                 <!-- 问题 2 -->
-                <div class="border border-border rounded-lg overflow-hidden">
-                    <button onclick="toggleFaq('faq2')" class="w-full px-4 py-3 bg-bg-page flex items-center justify-between text-left hover:bg-gray-100 transition-colors">
-                        <span class="font-medium text-text-primary" data-i18n="gettingStarted.faq.q2.title">问题 2：MCP 服务器连接失败</span>
+                <div class="border border-border rounded-lg overflow-hidden">
+                    <button onclick="toggleFaq('faq2')" class="w-full px-4 py-3 bg-bg-page flex items-center justify-between text-left hover:bg-gray-100 transition-colors">
+                        <span class="font-medium text-text-primary" data-i18n="gettingStarted.faq.q2.title">问题 2：MCP 服务器连接失败</span>
                         <svg class="w-5 h-5 text-text-tertiary transition-transform" id="faq2-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                             <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
                         </svg>
@@ -523,10 +553,41 @@ npm run build</code></pre>
                                 </div>
                             </li>
                             <li data-i18n="gettingStarted.faq.q2.step4">检查配置文件 JSON 格式是否正确</li>
-                        </ol>
-                    </div>
-                </div>
-            </section>
+                        </ol>
+                    </div>
+                </div>
+
+                <div class="border border-border rounded-lg overflow-hidden mt-4">
+                    <button onclick="toggleFaq('faq3')" class="w-full px-4 py-3 bg-bg-page flex items-center justify-between text-left hover:bg-gray-100 transition-colors">
+                        <span class="font-medium text-text-primary" data-i18n="gettingStarted.faq.q3.title">问题 3：Windows 下图谱工具首次启动很慢或超时</span>
+                        <svg class="w-5 h-5 text-text-tertiary transition-transform" id="faq3-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
+                        </svg>
+                    </button>
+                    <div id="faq3-content" class="hidden p-4 border-t border-border">
+                        <div class="p-3 bg-yellow-50 border-l-3 border-yellow-500 rounded-r text-sm text-text-primary mb-3">
+                            <strong data-i18n="gettingStarted.faq.q3.affected">Affected tools:</strong>
+                            <div class="mt-1"><code class="bg-gray-200 px-1 rounded text-xs">code_insight</code>, <code class="bg-gray-200 px-1 rounded text-xs">start_feature</code>, <code class="bg-gray-200 px-1 rounded text-xs">start_bugfix</code>, <code class="bg-gray-200 px-1 rounded text-xs">init_project_context</code></div>
+                        </div>
+                        <div class="p-3 bg-red-50 border-l-3 border-red-500 rounded-r text-sm text-text-primary mb-3">
+                            <strong data-i18n="gettingStarted.faq.q3.error">Typical error:</strong>
+                            <pre class="code-block mt-2 text-xs text-slate-200 bg-slate-900 p-2 rounded overflow-x-auto"><code>gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use
+gyp ERR! find VS - missing any VC++ toolset</code></pre>
+                        </div>
+                        <p class="text-sm text-text-primary mb-2"><strong data-i18n="gettingStarted.faq.q3.reasons">Common causes:</strong></p>
+                        <ul class="list-disc list-inside space-y-1 text-sm text-text-primary mb-3">
+                            <li data-i18n="gettingStarted.faq.q3.reason1">npx -y gitnexus@latest mcp may spend 20+ seconds checking or downloading dependencies on cold start.</li>
+                            <li data-i18n="gettingStarted.faq.q3.reason2">GitNexus depends on tree-sitter native modules, which may require Visual Studio Build Tools on Windows.</li>
+                        </ul>
+                        <p class="text-sm text-text-primary mb-2"><strong data-i18n="gettingStarted.faq.q3.solution">Recommended actions:</strong></p>
+                        <ol class="list-decimal list-inside space-y-2 text-sm text-text-primary">
+                            <li data-i18n="gettingStarted.faq.q3.step1">Install Visual Studio Build Tools with the C++ workload.</li>
+                            <li data-i18n="gettingStarted.faq.q3.step2">Retry once after dependencies finish installing so the first cold start is not mistaken for steady-state latency.</li>
+                            <li data-i18n="gettingStarted.faq.q3.step3">If your client supports env, prefer a preinstalled gitnexus CLI and raise MCP_GITNEXUS_CONNECT_TIMEOUT_MS plus MCP_GITNEXUS_TIMEOUT_MS.</li>
+                        </ol>
+                    </div>
+                </div>
+            </section>
 
             <!-- Footer -->
             <footer class="text-center text-sm text-text-tertiary py-4 border-t border-border">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.0.12",
+  "version": "3.0.13",
   "description": "AI-Powered Development Toolkit - MCP Server with 22 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",