mcp-probe-kit 3.0.24 → 3.2.0

package/build/tools/check_deps.d.ts

@@ -0,0 +1,13 @@
+export declare function checkDeps(_args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/build/tools/check_deps.js

@@ -0,0 +1,204 @@
+// check_deps 工具实现（无参数）
+export async function checkDeps(_args) {
+    try {
+        const message = `请分析项目依赖的健康状况：
+
+---
+
+## 依赖分析步骤
+
+### 第一步：获取依赖信息
+
+执行以下命令：
+\`\`\`bash
+# 查看 package.json
+cat package.json
+
+# 检查过期依赖
+npm outdated
+
+# 检查安全漏洞
+npm audit
+
+# 查看依赖树
+npm list --depth=0
+
+# 分析包大小
+npm ls --prod --parseable | xargs du -sh
+\`\`\`
+
+### 第二步：依赖健康度检查
+
+**1️⃣ 版本检查**
+
+检查项：
+- [ ] 依赖版本是否过旧（> 1 年未更新）
+- [ ] 是否有 Major 版本更新可用
+- [ ] 是否使用了废弃的包
+- [ ] 版本锁定策略（^、~、固定版本）
+
+**2️⃣ 安全漏洞检查**
+
+分析 \`npm audit\` 结果：
+- 🔴 Critical：立即修复
+- 🟠 High：尽快修复
+- 🟡 Moderate：计划修复
+- 🟢 Low：可选修复
+
+**3️⃣ 依赖体积分析**
+
+检查项：
+- [ ] 单个依赖是否过大（> 10MB）
+- [ ] 是否有轻量级替代方案
+- [ ] Tree-shaking 优化机会
+- [ ] 是否可以按需导入
+
+**4️⃣ 依赖健康度评估**
+
+评估指标：
+- 维护状态（活跃/停止维护）
+- 社区活跃度（GitHub Stars/Issues）
+- 发布频率
+- 文档质量
+- TypeScript 支持
+
+**5️⃣ 未使用依赖检查**
+
+查找方法：
+\`\`\`bash
+# 使用 depcheck
+npx depcheck
+
+# 手动检查
+grep -r "from 'package-name'" src/
+\`\`\`
+
+---
+
+## 依赖分析报告
+
+### 📊 依赖统计
+
+**总体情况**：
+- Dependencies: X 个
+- DevDependencies: Y 个
+- 总大小: Z MB
+
+**版本分布**：
+- 最新版本: X 个
+- 需要更新: Y 个
+- 已废弃: Z 个
+
+### 🔴 严重问题
+
+**安全漏洞**：
+1. **package-name@version**
+   - 漏洞等级：Critical
+   - CVE 编号：CVE-2024-XXXX
+   - 影响：...
+   - 修复方案：升级到 version X.X.X
+   - 命令：\`npm install package-name@X.X.X\`
+
+**废弃包**：
+1. **package-name**
+   - 状态：已停止维护
+   - 最后更新：2020-01-01
+   - 替代方案：alternative-package
+   - 迁移指南：...
+
+### 🟡 建议更新
+
+**可用更新**：
+| 包名 | 当前版本 | 最新版本 | 类型 | 优先级 |
+|------|---------|---------|------|--------|
+| pkg1 | 1.0.0 | 2.0.0 | Major | 中 |
+| pkg2 | 1.5.0 | 1.8.0 | Minor | 低 |
+
+**更新建议**：
+1. **Major 更新**（需要测试）：
+   - \`npm install pkg1@2.0.0\`
+   - 查看 Breaking Changes
+
+2. **Minor/Patch 更新**（风险较低）：
+   - \`npm update\`
+
+### 🟢 优化建议
+
+**体积优化**：
+1. **large-package (15MB)**
+   - 建议：使用 tree-shaking
+   - 或替换为：lighter-alternative (2MB)
+   - 预计减少：13MB
+
+**未使用依赖**：
+1. unused-package
+   - 建议：移除
+   - 命令：\`npm uninstall unused-package\`
+
+**重复依赖**：
+1. package-name 存在多个版本
+   - 建议：统一版本
+   - 使用：\`npm dedupe\`
+
+---
+
+## 升级计划
+
+### 立即处理（本周）
+1. 修复 Critical/High 安全漏洞
+2. 移除未使用的依赖
+3. 更新 Patch 版本
+
+### 短期计划（本月）
+1. 更新 Minor 版本
+2. 替换废弃的包
+3. 优化依赖体积
+
+### 长期计划（本季度）
+1. 评估 Major 版本更新
+2. 重构依赖架构
+3. 定期审查依赖健康度
+
+---
+
+## 预防措施
+
+**最佳实践**：
+1. 使用 \`package-lock.json\` 锁定版本
+2. 定期运行 \`npm audit\`
+3. 使用 Dependabot 自动更新
+4. 评估新依赖前检查健康度
+5. 优先选择活跃维护的包
+
+**CI/CD 集成**：
+\`\`\`yaml
+# GitHub Actions 示例
+- name: Audit dependencies
+  run: npm audit --audit-level=moderate
+\`\`\`
+
+---
+
+现在请开始依赖分析，生成详细的分析报告和升级计划。`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: message,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ 依赖分析失败: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/build/tools/check_spec.d.ts

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

package/build/tools/check_spec.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs, getString } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { resolveWorkspaceRoot } from '../lib/workspace-root.js';
+import { validateSpecDocuments } from '../lib/spec-validator.js';
+/**
+ * check_spec 工具（P1「填写后校验」闸门）
+ *
+ * 读取 docs/specs/{feature_name}/{requirements,design,tasks}.md，
+ * 机械校验完整性。未通过则列出逐条待修项并要求补全后重跑，通过前不应进入实现。
+ */
+const DEFAULT_DOCS_DIR = 'docs';
+function readIfExists(filePath) {
+    try {
+        return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatIssue(issue) {
+    const tag = issue.severity === 'error' ? '必须修复' : '提醒';
+    return `- [${tag}] (${issue.file}) ${issue.message}`;
+}
+export async function checkSpec(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                feature_name: '',
+                docs_dir: DEFAULT_DOCS_DIR,
+            },
+            primaryField: 'feature_name',
+            fieldAliases: {
+                feature_name: ['name', 'feature', 'spec', '功能名', '功能名称', '规格'],
+                docs_dir: ['dir', 'output', '目录', '文档目录'],
+                project_root: ['projectRoot', 'project_path', 'projectPath', 'root', '项目路径', '项目根目录'],
+            },
+        });
+        const featureName = getString(parsed.feature_name);
+        const docsDir = getString(parsed.docs_dir) || DEFAULT_DOCS_DIR;
+        const projectRoot = resolveWorkspaceRoot(getString(parsed.project_root));
+        if (!featureName) {
+            throw new Error('请提供 feature_name（要校验的规格目录名，对应 docs/specs/<feature_name>/）');
+        }
+        const specDir = path.join(projectRoot, docsDir, 'specs', featureName);
+        const report = validateSpecDocuments({
+            requirements: readIfExists(path.join(specDir, 'requirements.md')),
+            design: readIfExists(path.join(specDir, 'design.md')),
+            tasks: readIfExists(path.join(specDir, 'tasks.md')),
+        });
+        const relDir = `${docsDir}/specs/${featureName}`;
+        const issueLines = report.issues.length > 0
+            ? report.issues.map(formatIssue).join('\n')
+            : '- 无';
+        const text = report.passed
+            ? `# ✅ 规格校验通过：${featureName}
+
+${report.summary}
+
+**需求清单**: ${report.frIds.join(', ') || '（未发现 FR）'}
+${report.warningCount > 0 ? `\n仍有 ${report.warningCount} 个提醒（非阻塞，建议处理）：\n${issueLines}\n` : ''}
+**下一步**: 规格已具备可实现性，可进入实现/估算阶段。`
+            : `# ❌ 规格校验未通过：${featureName}
+
+${report.summary}
+
+## 待修复（${relDir}）
+${issueLines}
+
+## 处理方式
+1. 按上述每一条补全 \`${relDir}/\` 下的 requirements.md / design.md / tasks.md
+2. **重新运行** \`check_spec\`（同样的 feature_name）直到通过
+3. **校验通过前不要开始写实现代码** —— 这是为了确保需求被完整实现，而不是写到一半才发现规格有缺口`;
+        return okStructured(text, report);
+    }
+    catch (error) {
+        return handleToolError(error, 'check_spec');
+    }
+}

package/build/tools/code_insight.js

@@ -136,10 +136,10 @@ function createProjectDocsPlan(layout, docsSnapshot) {
         latestJsonFilePath: layout.latestJsonPath,
         archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
         archiveJsonFilePath: docsSnapshot.jsonFilePath,
-        navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
-最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
+        navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
 `,
-        devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
+        devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
 `,
     };
 }
@@ -187,15 +187,15 @@ export function buildCodeInsightDelegatedPlan(input) {
     };
 }
 function renderUsageGuide() {
-    return `## 使用场景指南
-- 探索调用链: \`{ mode: "query", query: "login", goal: "理解登录认证流程" }\`
-- 深入函数上下文: \`{ mode: "context", target: "login", file_path: "src/auth/login.ts" }\`
-- 评估影响范围: \`{ mode: "impact", target: "login", direction: "upstream", file_path: "..." }\`
-- 查看代码内容: \`{ mode: "context", target: "login", include_content: true }\`
-
-## 下一步建议
-- 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
-- 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
+    return `## 使用场景指南
+- 探索调用链: \`{ mode: "query", query: "login", goal: "理解登录认证流程" }\`
+- 深入函数上下文: \`{ mode: "context", target: "login", file_path: "src/auth/login.ts" }\`
+- 评估影响范围: \`{ mode: "impact", target: "login", direction: "upstream", file_path: "..." }\`
+- 查看代码内容: \`{ mode: "context", target: "login", include_content: true }\`
+
+## 下一步建议
+- 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
+- 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
 - 需要落盘: 传 \`save_to_docs: true\`，再按 delegated plan 写入 docs/graph-insights`;
 }
 export function resolveCodeInsightQuery(input) {
@@ -307,22 +307,22 @@ export async function codeInsight(args, context) {
             status: item.status,
         })));
         const ambiguityText = formatAmbiguities(result.ambiguities);
-        const message = `# code_insight 图谱分析结果
-
-状态: ${formatStatusLabel(status)}
-模式: ${result.modeRequested} -> ${result.modeResolved}
-来源: ${result.provider}
-启动策略: ${result.launcherStrategy}
-工作区: ${result.workspaceMode}
-源目录: ${result.sourceRoot}
-
-摘要:
-${result.summary}
-
-执行详情:
-${executionSummary}
-
-${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
+        const message = `# code_insight 图谱分析结果
+
+状态: ${formatStatusLabel(status)}
+模式: ${result.modeRequested} -> ${result.modeResolved}
+来源: ${result.provider}
+启动策略: ${result.launcherStrategy}
+工作区: ${result.workspaceMode}
+源目录: ${result.sourceRoot}
+
+摘要:
+${result.summary}
+
+执行详情:
+${executionSummary}
+
+${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
 ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.trim();
         const usageGuide = renderUsageGuide();
         const structured = {
@@ -391,20 +391,20 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
                     `工作区模式: ${result.workspaceMode}`,
                     `来源目录: ${result.sourceRoot}`,
                 ],
-            })}${message}
-
-## delegated plan
-${renderPlanSteps(delegatedPlan.steps)}
-
-${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
-- 如需落盘，写入 ${projectDocs.latestMarkdownFilePath} 与 ${projectDocs.latestJsonFilePath}
-- 如需长期沉淀，可再补充 ${projectDocs.projectContextFilePath} 的图谱入口` : `后续操作:
-- 请先从 candidates 中选定唯一符号
-- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}
-
+            })}${message}
+
+## delegated plan
+${renderPlanSteps(delegatedPlan.steps)}
+
+${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
+- 如需落盘，写入 ${projectDocs.latestMarkdownFilePath} 与 ${projectDocs.latestJsonFilePath}
+- 如需长期沉淀，可再补充 ${projectDocs.projectContextFilePath} 的图谱入口` : `后续操作:
+- 请先从 candidates 中选定唯一符号
+- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}
+
 ${usageGuide}`
-            : `${message}
-
+            : `${message}
+
 ${usageGuide}`, structured);
     }
     catch (error) {

package/build/tools/convert.d.ts

@@ -0,0 +1,13 @@
+export declare function convert(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;