mcp-probe-kit 3.0.16 → 3.0.17

package/build/tools/init_project_context.js

@@ -2,6 +2,7 @@ import { parseArgs, getString } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { detectProjectType } from "../lib/project-detector.js";
+import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
 import * as fs from 'fs';
 import * as path from 'path';
 /**
@@ -138,21 +139,21 @@ function generateDevGuide(docs) {
             result += `\n### ${category}\n${items.join('\n')}\n`;
         }
     }
-    result += `\n### 理解代码图谱
-- **代码图谱洞察**: [latest.md](./graph-insights/latest.md) - 需要快速理解模块依赖、调用链、影响面时优先查看
+    result += `\n### 理解代码图谱
+- **代码图谱洞察**: [latest.md](./graph-insights/latest.md) - 需要快速理解模块依赖、调用链、影响面时优先查看
 `;
     return result || '\n### 开发指南\n查看上面的文档导航，根据需要选择对应的文档。\n';
 }
 /**
  * 生成项目上下文文档指导
  */
-async function generateProjectContext(docsDir, projectRoot = process.cwd()) {
+async function generateProjectContext(docsDir, projectRoot) {
     try {
         // 检测项目类型
-        const detection = detectProjectType(projectRoot);
-        const projectInfo = getProjectInfo(projectRoot);
+        const resolvedRoot = resolveWorkspaceRoot(projectRoot);
+        const detection = detectProjectType(resolvedRoot);
+        const projectInfo = getProjectInfo(resolvedRoot);
         const docs = getDocumentList(detection.category);
-        const resolvedRoot = path.resolve(projectRoot);
         const projectContextPath = toPosixPath(path.join(resolvedRoot, docsDir, 'project-context.md'));
         const projectContextExists = fs.existsSync(path.join(resolvedRoot, docsDir, 'project-context.md'));
         const graphDocsRoot = toPosixPath(path.join(resolvedRoot, docsDir, 'graph-insights'));
@@ -265,10 +266,10 @@ async function generateProjectContext(docsDir, projectRoot = process.cwd()) {
                 projectContextExists,
             },
         };
-        return okStructured(`${header}${guide}
-
-## delegated plan
-${renderPlanSteps(plan.steps)}
+        return okStructured(`${header}${guide}
+
+## delegated plan
+${renderPlanSteps(plan.steps)}
 `, structuredData, {
             schema: (await import("../schemas/output/project-tools.js")).ProjectContextSchema,
         });
@@ -284,59 +285,59 @@ ${renderPlanSteps(plan.steps)}
 function generateGuideText(detection, projectInfo, docs, docsDir, projectRoot, options) {
     const timestamp = new Date().toISOString();
     const projectContextExists = options?.projectContextExists === true;
-    return `# 项目上下文文档生成指导
-
-## 📊 项目信息
+    return `# 项目上下文文档生成指导
+
+## 📊 项目信息
 
 - **项目名称**: ${projectInfo.name}
 - **版本**: ${projectInfo.version}
 - **语言**: ${detection.language}
 - **框架**: ${detection.framework || '未检测到'}
 - **类型**: ${detection.category}
-- **置信度**: ${detection.confidence}%
-
-## 🔎 当前状态
-
-- **project-context.md**: ${projectContextExists ? '已存在（将保留，不覆盖）' : '不存在（需要生成）'}
-- **图谱文档**: 需要确保 ${docsDir}/graph-insights/latest.md 与 latest.json 可用
-
-## 📋 需要生成的文档
-
-请按照以下结构生成 **${docs.length + 1}** 个上下文文档，并为图谱文档预留入口：
-
-\`\`\`
-${docsDir}/
-├── project-context.md          # 索引文件（必须首先生成）
-└── project-context/            # 分类文档目录
-${docs.map(doc => `    ├── ${doc.file.padEnd(28)} # ${doc.title}`).join('\n')}
-\n${docsDir}/graph-insights/
-    ├── latest.md               # 最近一次 code_insight 的 Markdown 摘要
-    └── latest.json             # 最近一次 code_insight 的结构化结果
-\`\`\`
+- **置信度**: ${detection.confidence}%
+
+## 🔎 当前状态
+
+- **project-context.md**: ${projectContextExists ? '已存在（将保留，不覆盖）' : '不存在（需要生成）'}
+- **图谱文档**: 需要确保 ${docsDir}/graph-insights/latest.md 与 latest.json 可用
+
+## 📋 需要生成的文档
+
+请按照以下结构生成 **${docs.length + 1}** 个上下文文档，并为图谱文档预留入口：
+
+\`\`\`
+${docsDir}/
+├── project-context.md          # 索引文件（必须首先生成）
+└── project-context/            # 分类文档目录
+${docs.map(doc => `    ├── ${doc.file.padEnd(28)} # ${doc.title}`).join('\n')}
+\n${docsDir}/graph-insights/
+    ├── latest.md               # 最近一次 code_insight 的 Markdown 摘要
+    └── latest.json             # 最近一次 code_insight 的结构化结果
+\`\`\`
 
 ---
 
-## 🎯 生成步骤
-
+## 🎯 生成步骤
+
 ${projectContextExists
-        ? `### 已存在项目上下文（仅补图谱）
-
-检测到 \`${docsDir}/project-context.md\` 已存在：
-
-- **不要重写** 现有 \`${docsDir}/project-context.md\`
-- **不要重写** \`${docsDir}/project-context/\` 下已有分类文档
-- 直接调用 \`code_insight\` 补齐 \`${docsDir}/graph-insights/latest.md\` 与 \`${docsDir}/graph-insights/latest.json\`
-- 仅在 \`project-context.md\` 中补充或刷新图谱入口
-
----
+        ? `### 已存在项目上下文（仅补图谱）
+
+检测到 \`${docsDir}/project-context.md\` 已存在：
+
+- **不要重写** 现有 \`${docsDir}/project-context.md\`
+- **不要重写** \`${docsDir}/project-context/\` 下已有分类文档
+- 直接调用 \`code_insight\` 补齐 \`${docsDir}/graph-insights/latest.md\` 与 \`${docsDir}/graph-insights/latest.json\`
+- 仅在 \`project-context.md\` 中补充或刷新图谱入口
+
+---
 `
-        : ''}
-
-### 第一步：生成索引文件（最重要！）
+        : ''}
+
+### 第一步：生成索引文件（最重要！）
+
+**文件**: \`${docsDir}/project-context.md\`
 
-**文件**: \`${docsDir}/project-context.md\`
-
-这是项目上下文的**灵魂**，必须首先生成。它是所有文档的入口和导航中心。
+这是项目上下文的**灵魂**，必须首先生成。它是所有文档的入口和导航中心。
 
 **模板**:
 
@@ -356,20 +357,20 @@ ${projectContextExists
 | 类型 | ${detection.category} |
 | 描述 | ${projectInfo.description || '待补充'} |
 
-## 📚 文档导航
-
-${docs.map(doc => `### [${doc.title}](./project-context/${doc.file})
-${doc.purpose}
-`).join('\n')}
-### [代码图谱洞察](./graph-insights/latest.md)
-最近一次 code_insight 分析结果，包含模块依赖、调用链和影响面摘要
-
-## 🚀 快速开始
-
-1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
-2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
-3. 阅读 [代码图谱洞察](./graph-insights/latest.md) 快速理解模块依赖与调用链
-4. 根据需要查看具体的操作指南
+## 📚 文档导航
+
+${docs.map(doc => `### [${doc.title}](./project-context/${doc.file})
+${doc.purpose}
+`).join('\n')}
+### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含模块依赖、调用链和影响面摘要
+
+## 🚀 快速开始
+
+1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
+2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
+3. 阅读 [代码图谱洞察](./graph-insights/latest.md) 快速理解模块依赖与调用链
+4. 根据需要查看具体的操作指南
 
 ## 💡 开发时查看对应文档
 
@@ -382,43 +383,43 @@ ${generateDevGuide(docs)}
 *生成工具: MCP Probe Kit - init_project_context v2.1*
 \`\`\`
 
-${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**使用 fsWrite 创建此文件**'}
+${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**使用 fsWrite 创建此文件**'}
 
 ---
 
-### 第二步：生成分类文档
-
-${docs.map((doc, index) => generateDocTemplate(doc, index + 2, projectInfo, detection, docsDir)).join('\n\n---\n\n')}
+### 第二步：生成分类文档
+
+${docs.map((doc, index) => generateDocTemplate(doc, index + 2, projectInfo, detection, docsDir)).join('\n\n---\n\n')}
 
 ---
 
-## ✅ 完成标准
-
-请确认：
-
-- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `已使用 fsWrite 创建 **${docs.length + 1}** 个文件`}
-- [ ] 索引文件 \`project-context.md\` ${projectContextExists ? '已存在并保留' : '已创建（最重要！）'}
-- [ ] 索引文件已包含 \`graph-insights/latest.md\` 的入口
-- [ ] 所有文档都包含**真实的文件路径**（不是 [xxx] 占位符）
-- [ ] 所有文档都包含**实际的代码示例**（从项目中复制）
-- [ ] 所有步骤都具体可操作
-- [ ] 所有示例都来自项目实际代码
-
----
-
-## 🔄 完成文档骨架后立即执行
-
-1. 调用 \`code_insight\`
-\`\`\`json
-{
-  "mode": "auto",
-  "project_root": "${toPosixPath(projectRoot)}",
-  "docs_dir": "${docsDir}"
-}
-\`\`\`
-2. 严格执行 \`code_insight\` 返回的 delegated plan
-3. 确保 \`${docsDir}/graph-insights/latest.md\` 和 \`${docsDir}/graph-insights/latest.json\` 已写入
-4. 若已有旧图谱，按 delegated plan 归档时间戳版本
+## ✅ 完成标准
+
+请确认：
+
+- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `已使用 fsWrite 创建 **${docs.length + 1}** 个文件`}
+- [ ] 索引文件 \`project-context.md\` ${projectContextExists ? '已存在并保留' : '已创建（最重要！）'}
+- [ ] 索引文件已包含 \`graph-insights/latest.md\` 的入口
+- [ ] 所有文档都包含**真实的文件路径**（不是 [xxx] 占位符）
+- [ ] 所有文档都包含**实际的代码示例**（从项目中复制）
+- [ ] 所有步骤都具体可操作
+- [ ] 所有示例都来自项目实际代码
+
+---
+
+## 🔄 完成文档骨架后立即执行
+
+1. 调用 \`code_insight\`
+\`\`\`json
+{
+  "mode": "auto",
+  "project_root": "${toPosixPath(projectRoot)}",
+  "docs_dir": "${docsDir}"
+}
+\`\`\`
+2. 严格执行 \`code_insight\` 返回的 delegated plan
+3. 确保 \`${docsDir}/graph-insights/latest.md\` 和 \`${docsDir}/graph-insights/latest.json\` 已写入
+4. 若已有旧图谱，按 delegated plan 归档时间戳版本
 
 ---
 
@@ -733,13 +734,13 @@ ${template}
  */
 export async function initProjectContext(args) {
     let docsDir = DEFAULT_DOCS_DIR;
-    let projectRoot = process.cwd();
+    let projectRoot = resolveWorkspaceRoot();
     try {
         // 智能参数解析，支持自然语言输入
         const parsedArgs = parseArgs(args, {
             defaultValues: {
                 docs_dir: DEFAULT_DOCS_DIR,
-                project_root: process.cwd()
+                project_root: resolveWorkspaceRoot()
             },
             primaryField: "docs_dir",
             fieldAliases: {
@@ -748,7 +749,21 @@ export async function initProjectContext(args) {
             },
         });
         docsDir = getString(parsedArgs.docs_dir) || DEFAULT_DOCS_DIR;
-        projectRoot = getString(parsedArgs.project_root) || process.cwd();
+        projectRoot = getString(parsedArgs.project_root) || resolveWorkspaceRoot();
+        if (isLikelyProjectNamedRelativePath(projectRoot)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `拒绝执行项目上下文初始化：project_root 不能传带项目名的半相对路径，例如 ${projectRoot}。请改为传项目根目录绝对路径。`,
+                    }],
+                isError: true,
+                structuredContent: {
+                    error_code: "INVALID_PROJECT_ROOT",
+                    rejected_project_root: projectRoot,
+                    retry_hint: buildProjectRootRetryHint(projectRoot),
+                },
+            };
+        }
         // 生成项目上下文
         return await generateProjectContext(docsDir, projectRoot);
     }

package/build/tools/memorize_asset.d.ts

@@ -0,0 +1,7 @@
+export declare function memorizeAsset(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/memorize_asset.js

@@ -0,0 +1,66 @@
+import { parseArgs, getString, getNumber } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { createMemoryClient } from '../lib/memory-client.js';
+import { handleToolError } from '../utils/error-handler.js';
+export async function memorizeAsset(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                name: '',
+                type: 'code',
+                description: '',
+                summary: '',
+                content: '',
+                code_snippet: '',
+                file_path: '',
+                source_project: '',
+                source_path: '',
+                usage: '',
+                confidence: 0.7,
+            },
+            fieldAliases: {
+                code_snippet: ['code', 'snippet'],
+                file_path: ['path'],
+                source_project: ['project'],
+                source_path: ['source'],
+            },
+        });
+        const name = getString(parsed.name);
+        const type = getString(parsed.type) || 'code';
+        const description = getString(parsed.description);
+        const summary = getString(parsed.summary);
+        const content = getString(parsed.content) || getString(parsed.code_snippet);
+        const sourceProject = getString(parsed.source_project);
+        const sourcePath = getString(parsed.source_path) || getString(parsed.file_path);
+        const usage = getString(parsed.usage);
+        const confidence = getNumber(parsed.confidence, 0.7);
+        const tags = Array.isArray(parsed.tags) ? parsed.tags.filter((item) => typeof item === 'string') : [];
+        if (!name || !description || !summary || !content) {
+            throw new Error('缺少必填参数: name, description, summary, content/code_snippet');
+        }
+        const client = createMemoryClient();
+        if (!client.isEnabled()) {
+            return okStructured('记忆服务未开启，已跳过沉淀。', { enabled: false, stored: false });
+        }
+        const asset = await client.upsertAsset({
+            name,
+            type,
+            description,
+            summary,
+            content,
+            sourceProject: sourceProject || undefined,
+            sourcePath: sourcePath || undefined,
+            usage: usage || undefined,
+            confidence,
+            tags,
+        });
+        return okStructured(`已沉淀记忆资产: ${asset.name}`, {
+            enabled: true,
+            stored: true,
+            asset,
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'memorize_asset');
+    }
+}

package/build/tools/read_memory_asset.d.ts

@@ -0,0 +1,7 @@
+export declare function readMemoryAsset(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/read_memory_asset.js

@@ -0,0 +1,26 @@
+import { okStructured } from '../lib/response.js';
+import { createMemoryClient } from '../lib/memory-client.js';
+import { handleToolError } from '../utils/error-handler.js';
+export async function readMemoryAsset(args) {
+    try {
+        const assetId = typeof args?.asset_id === 'string' ? args.asset_id.trim() : '';
+        if (!assetId) {
+            throw new Error('缺少必填参数: asset_id');
+        }
+        const client = createMemoryClient();
+        if (!client.isReadEnabled()) {
+            return okStructured('记忆服务未开启，已跳过读取。', { enabled: false, asset: null });
+        }
+        const asset = await client.getAsset(assetId);
+        if (!asset) {
+            return okStructured(`未找到记忆资产: ${assetId}`, { enabled: true, asset: null });
+        }
+        return okStructured(`已读取记忆资产: ${asset.name}`, {
+            enabled: true,
+            asset,
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'read_memory_asset');
+    }
+}

package/build/tools/scan_and_extract_patterns.d.ts

@@ -0,0 +1,27 @@
+export declare function scanAndExtractPatterns(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+    structuredContent: {
+        error_code: string;
+        mode: string;
+        rejected_directory_path: string;
+        retry_hint: {
+            preferred: {
+                project_root: string;
+                directory_path: string;
+            };
+            fallback: {
+                directory_path: string;
+            };
+        };
+    };
+}>;