mcp-probe-kit 1.3.0 → 1.6.0

package/build/tools/estimate.js

@@ -0,0 +1,225 @@
+/**
+ * estimate 工具
+ *
+ * 功能：评估开发任务的工作量
+ * 模式：指令生成器模式 - 返回估算指南，由 AI 执行实际分析
+ */
+const PROMPT_TEMPLATE = `# 工作量估算指南
+
+## 🎯 估算目标
+
+**任务描述**: 
+{task_description}
+
+**上下文信息**:
+- 团队规模: {team_size} 人
+- 经验水平: {experience_level}
+
+{code_context_section}
+
+---
+
+## 📋 估算步骤
+
+### 步骤 1: 任务分解
+
+将任务分解为以下标准活动：
+
+| 活动 | 说明 | 占比参考 |
+|------|------|----------|
+| 需求理解 | 理解需求、澄清疑问 | 5-10% |
+| 设计 | 技术方案设计 | 10-15% |
+| 编码 | 核心代码实现 | 40-50% |
+| 单元测试 | 编写测试用例 | 15-20% |
+| 代码审查 | CR 和修改 | 5-10% |
+| 集成测试 | 联调和修复 | 10-15% |
+| 文档 | 更新文档 | 5% |
+
+### 步骤 2: 复杂度评估
+
+对每个维度打分（1-5）：
+
+#### 代码量评估
+| 等级 | 行数 | 说明 |
+|------|------|------|
+| 1 | < 50 行 | 微小改动 |
+| 2 | 50-200 行 | 小改动 |
+| 3 | 200-500 行 | 中等改动 |
+| 4 | 500-1000 行 | 较大改动 |
+| 5 | > 1000 行 | 大型改动 |
+
+#### 技术难度评估
+| 等级 | 说明 |
+|------|------|
+| 1 | 简单 CRUD、配置修改 |
+| 2 | 常规业务逻辑 |
+| 3 | 复杂算法、第三方集成 |
+| 4 | 新技术栈、架构变更 |
+| 5 | 核心系统重构 |
+
+#### 依赖复杂度评估
+| 等级 | 说明 |
+|------|------|
+| 1 | 无外部依赖，独立模块 |
+| 2 | 依赖 1-2 个内部模块 |
+| 3 | 依赖 3-5 个模块 |
+| 4 | 跨团队协作 |
+| 5 | 外部系统集成 |
+
+#### 测试复杂度评估
+| 等级 | 说明 |
+|------|------|
+| 1 | 简单单测即可 |
+| 2 | 常规单测 + 少量集成测试 |
+| 3 | 需要 Mock、集成测试 |
+| 4 | 需要 E2E 测试 |
+| 5 | 需要性能/安全测试 |
+
+### 步骤 3: 时间估算
+
+使用三点估算法（PERT）：
+
+| 场景 | 时间 | 说明 |
+|------|------|------|
+| 乐观 (O) | ?h | 一切顺利，无阻塞 |
+| 正常 (M) | ?h | 预期情况，少量问题 |
+| 悲观 (P) | ?h | 遇到较多问题 |
+
+**期望时间** = (O + 4×M + P) ÷ 6 = ?h
+
+### 步骤 4: 故事点映射
+
+| 故事点 | 时间范围 | 适用场景 |
+|--------|----------|----------|
+| 1 | 1-2 小时 | 微小改动、配置修改 |
+| 2 | 2-4 小时 | 小功能、Bug 修复 |
+| 3 | 4-8 小时 | 中等功能 |
+| 5 | 1-2 天 | 较大功能 |
+| 8 | 2-3 天 | 大功能 |
+| 13 | 3-5 天 | 需要拆分的大任务 |
+
+### 步骤 5: 风险识别
+
+识别可能影响估算的风险因素：
+
+| 风险类型 | 检查项 |
+|----------|--------|
+| 技术风险 | 新技术？复杂算法？不熟悉的领域？ |
+| 依赖风险 | 外部依赖？团队协作？接口不稳定？ |
+| 需求风险 | 需求明确？可能变更？边界清晰？ |
+| 资源风险 | 人员可用？环境就绪？ |
+
+---
+
+## 📊 输出模板
+
+### 估算结果
+
+| 项目 | 结果 |
+|------|------|
+| **故事点** | X 点 |
+| **预估时间** | X-X 小时/天 |
+| **置信度** | 高 / 中 / 低 |
+
+### 复杂度分析
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 代码量 | X/5 | [说明] |
+| 技术难度 | X/5 | [说明] |
+| 依赖复杂度 | X/5 | [说明] |
+| 测试复杂度 | X/5 | [说明] |
+| **综合** | X/5 | |
+
+### 时间分解
+
+| 活动 | 时间 | 说明 |
+|------|------|------|
+| 需求理解 | Xh | |
+| 设计 | Xh | |
+| 编码 | Xh | |
+| 单元测试 | Xh | |
+| 代码审查 | Xh | |
+| 集成测试 | Xh | |
+| 文档 | Xh | |
+| **合计** | Xh | |
+
+### 风险因素
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| [风险描述] | 高/中/低 | [措施] |
+
+### 任务拆分建议
+
+> 如果估算超过 8 小时（5 故事点），建议拆分：
+
+| 子任务 | 估算 | 说明 |
+|--------|------|------|
+| [子任务1] | Xh | |
+| [子任务2] | Xh | |
+
+### 置信度说明
+
+**置信度**: [高/中/低]
+
+**影响因素**:
+- [因素1]
+- [因素2]
+
+**建议**: [如果置信度低，建议补充什么信息]
+
+---
+
+## ✅ 估算检查清单
+
+- [ ] 任务已分解为标准活动
+- [ ] 复杂度已评估
+- [ ] 三点估算已完成
+- [ ] 故事点已确定
+- [ ] 风险已识别
+- [ ] 置信度已评估
+- [ ] 大任务已建议拆分
+
+---
+
+*指南版本: 1.0.0*
+*工具: MCP Probe Kit - estimate*
+`;
+/**
+ * estimate 工具实现
+ */
+export async function estimate(args) {
+    try {
+        const taskDescription = args?.task_description;
+        if (!taskDescription) {
+            throw new Error("缺少必填参数: task_description（任务描述）");
+        }
+        const codeContext = args?.code_context || "";
+        const teamSize = args?.team_size || 1;
+        const experienceLevel = args?.experience_level || "mid";
+        const expLevelMap = {
+            junior: "初级（1-2年经验）",
+            mid: "中级（3-5年经验）",
+            senior: "高级（5年以上经验）",
+        };
+        const codeContextSection = codeContext
+            ? `**相关代码/文件**:\n\`\`\`\n${codeContext}\n\`\`\``
+            : "";
+        const guide = PROMPT_TEMPLATE
+            .replace(/{task_description}/g, taskDescription)
+            .replace(/{team_size}/g, String(teamSize))
+            .replace(/{experience_level}/g, expLevelMap[experienceLevel] || experienceLevel)
+            .replace(/{code_context_section}/g, codeContextSection);
+        return {
+            content: [{ type: "text", text: guide }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `❌ 工作量估算失败: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+}

package/build/tools/fix_bug.d.ts

@@ -0,0 +1,24 @@
+/**
+ * fix_bug 工具
+ *
+ * 功能：指导完整的 Bug 修复流程
+ * 模式：指令生成器模式 - 返回详细的修复指南，由 AI 执行实际操作
+ *
+ * 流程：问题定位 → 原因分析 → 修复方案 → 验证测试
+ */
+/**
+ * fix_bug 工具实现
+ */
+export declare function fixBug(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/build/tools/fix_bug.js

@@ -0,0 +1,298 @@
+/**
+ * fix_bug 工具
+ *
+ * 功能：指导完整的 Bug 修复流程
+ * 模式：指令生成器模式 - 返回详细的修复指南，由 AI 执行实际操作
+ *
+ * 流程：问题定位 → 原因分析 → 修复方案 → 验证测试
+ */
+const PROMPT_TEMPLATE = `# Bug 修复指南
+
+## 🐛 Bug 信息
+
+**错误信息**: 
+\`\`\`
+{error_message}
+\`\`\`
+
+{stack_trace_section}
+
+{reproduce_section}
+
+{behavior_section}
+
+---
+
+## 📍 阶段 1: 问题定位
+
+### 步骤 1.1: 分析错误信息
+
+1. **识别错误类型**:
+   - 语法错误（SyntaxError）
+   - 运行时错误（TypeError, ReferenceError, RangeError）
+   - 逻辑错误（结果不符合预期）
+   - 异步错误（Promise rejection, 回调异常）
+
+2. **提取关键信息**:
+   - 错误名称: [从错误信息中提取]
+   - 错误消息: [具体描述]
+   - 发生位置: [文件:行号]
+
+### 步骤 1.2: 分析堆栈跟踪
+
+**操作**:
+1. 找到堆栈中第一个项目文件（排除 node_modules）
+2. 追踪调用链，理解执行流程
+3. 记录所有相关的项目文件
+
+**相关文件列表**:
+| 文件 | 行号 | 函数/方法 |
+|------|------|-----------|
+| [文件路径] | [行号] | [函数名] |
+
+### 步骤 1.3: 读取相关代码
+
+**操作**: 读取以下文件并分析：
+- 错误发生的文件
+- 调用链上的文件
+- 相关的配置文件
+- 相关的测试文件（如有）
+
+### 📋 定位结论
+
+| 项目 | 内容 |
+|------|------|
+| 问题文件 | [文件路径] |
+| 问题位置 | 第 X 行 |
+| 问题代码 | \`[代码片段]\` |
+| 触发条件 | [什么情况下触发] |
+
+---
+
+## 🔍 阶段 2: 原因分析
+
+### 步骤 2.1: 5 Whys 分析
+
+使用 5 Whys 方法深入分析根本原因：
+
+1. **Why 1**: 为什么会出现这个错误？
+   - [答案]
+
+2. **Why 2**: 为什么会 [Why 1 的答案]？
+   - [答案]
+
+3. **Why 3**: 为什么会 [Why 2 的答案]？
+   - [答案]
+
+4. **Why 4**: 为什么会 [Why 3 的答案]？
+   - [答案]
+
+5. **Why 5**: 为什么会 [Why 4 的答案]？
+   - [答案]
+
+### 步骤 2.2: 代码逻辑分析
+
+1. **数据流分析**: 追踪数据从输入到出错位置的流动
+2. **状态分析**: 检查相关变量/状态在出错时的值
+3. **边界条件**: 检查是否处理了所有边界情况
+4. **异常处理**: 检查是否有适当的错误处理
+
+### 📋 分析结论
+
+| 项目 | 内容 |
+|------|------|
+| 直接原因 | [直接导致错误的原因] |
+| 根本原因 | [深层次的原因] |
+| 触发条件 | [什么情况下会触发] |
+| 影响范围 | [受影响的功能/模块] |
+
+---
+
+## 🔧 阶段 3: 修复方案
+
+### 步骤 3.1: 设计修复方案
+
+**方案 A**: [方案描述]
+- 修改内容: [具体修改]
+- 优点: [优点]
+- 缺点: [缺点]
+- 风险: [潜在风险]
+
+**方案 B**: [备选方案描述]
+- 修改内容: [具体修改]
+- 优点: [优点]
+- 缺点: [缺点]
+- 风险: [潜在风险]
+
+**选择方案**: [选择的方案]
+**选择理由**: [为什么选择这个方案]
+
+### 步骤 3.2: 影响范围评估
+
+| 影响项 | 说明 |
+|--------|------|
+| 修改文件 | [文件列表] |
+| 影响功能 | [功能列表] |
+| 需要测试 | [测试范围] |
+| 是否需要回归 | [是/否] |
+
+### 步骤 3.3: 实施修复
+
+**修改文件**: \`[文件路径]\`
+
+**修改前**:
+\`\`\`
+[原代码]
+\`\`\`
+
+**修改后**:
+\`\`\`
+[新代码]
+\`\`\`
+
+**修改说明**: [解释修改的原因和逻辑]
+
+---
+
+## ✅ 阶段 4: 验证测试
+
+### 步骤 4.1: 单元测试
+
+为修复编写针对性的单元测试：
+
+\`\`\`typescript
+describe('[功能描述]', () => {
+  // 测试正常情况
+  it('should [正常行为描述]', () => {
+    // 测试代码
+  });
+  
+  // 测试修复的 Bug 场景
+  it('should handle [Bug 场景]', () => {
+    // 测试代码 - 确保 Bug 已修复
+  });
+  
+  // 测试边界情况
+  it('should handle [边界情况]', () => {
+    // 边界测试
+  });
+});
+\`\`\`
+
+### 步骤 4.2: 手动验证
+
+1. [ ] 按原复现步骤验证问题已修复
+2. [ ] 验证正常流程不受影响
+3. [ ] 验证边界情况处理正确
+4. [ ] 验证错误处理正确
+
+### 步骤 4.3: 回归测试
+
+1. [ ] 运行相关模块的测试
+2. [ ] 运行全量测试（如有 CI）
+3. [ ] 检查是否引入新问题
+
+---
+
+## 📋 修复检查清单
+
+### 定位阶段
+- [ ] 错误类型已识别
+- [ ] 问题代码已定位
+- [ ] 相关文件已读取
+
+### 分析阶段
+- [ ] 5 Whys 分析已完成
+- [ ] 根本原因已确定
+- [ ] 影响范围已评估
+
+### 修复阶段
+- [ ] 修复方案已设计
+- [ ] 代码修改已完成
+- [ ] 修改已解释清楚
+
+### 验证阶段
+- [ ] 单元测试已添加
+- [ ] 手动验证已通过
+- [ ] 回归测试已通过
+
+### 提交阶段
+- [ ] 代码已提交
+- [ ] Commit message 清晰描述了修复内容
+
+---
+
+## 📝 修复总结
+
+完成修复后，填写以下总结：
+
+| 项目 | 内容 |
+|------|------|
+| Bug 描述 | [简述] |
+| 根本原因 | [原因] |
+| 修复方案 | [方案] |
+| 修改文件 | [文件列表] |
+| 测试覆盖 | [测试情况] |
+| 修复时间 | [耗时] |
+
+---
+
+## 💡 经验教训
+
+记录本次 Bug 的经验教训，避免类似问题：
+
+1. **代码层面**: [如何避免写出类似 Bug]
+2. **测试层面**: [应该增加什么测试]
+3. **流程层面**: [流程上如何改进]
+
+---
+
+*指南版本: 1.0.0*
+*工具: MCP Probe Kit - fix_bug*
+`;
+/**
+ * fix_bug 工具实现
+ */
+export async function fixBug(args) {
+    try {
+        const errorMessage = args?.error_message;
+        if (!errorMessage) {
+            throw new Error("缺少必填参数: error_message（错误信息）");
+        }
+        const stackTrace = args?.stack_trace || "";
+        const stepsToReproduce = args?.steps_to_reproduce || "";
+        const expectedBehavior = args?.expected_behavior || "";
+        const actualBehavior = args?.actual_behavior || "";
+        // 构建可选部分
+        const stackTraceSection = stackTrace
+            ? `**堆栈跟踪**:\n\`\`\`\n${stackTrace}\n\`\`\``
+            : "**堆栈跟踪**: 未提供（建议提供以便更准确定位）";
+        const reproduceSection = stepsToReproduce
+            ? `**复现步骤**:\n${stepsToReproduce}`
+            : "";
+        let behaviorSection = "";
+        if (expectedBehavior || actualBehavior) {
+            behaviorSection = [
+                expectedBehavior ? `**期望行为**: ${expectedBehavior}` : "",
+                actualBehavior ? `**实际行为**: ${actualBehavior}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+        }
+        const guide = PROMPT_TEMPLATE
+            .replace(/{error_message}/g, errorMessage)
+            .replace(/{stack_trace_section}/g, stackTraceSection)
+            .replace(/{reproduce_section}/g, reproduceSection)
+            .replace(/{behavior_section}/g, behaviorSection);
+        return {
+            content: [{ type: "text", text: guide }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `❌ 生成修复指南失败: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+}

package/build/tools/gen_mock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * gen_mock 工具
+ *
+ * 功能：根据数据结构生成 Mock 数据
+ * 模式：指令生成器模式 - 返回生成指南，由 AI 执行实际生成
+ */
+/**
+ * gen_mock 工具实现
+ */
+export declare function genMock(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;