mcp-probe-kit 3.2.0 → 3.3.0

package/build/tools/__tests__/cursor-history.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/__tests__/cursor-history.unit.test.js

@@ -0,0 +1,38 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+const readConversationMock = vi.fn();
+vi.mock('../../lib/cursor-history-client.js', () => ({
+    createCursorHistoryClient: () => ({
+        readConversation: readConversationMock,
+    }),
+}));
+import { cursorReadConversation } from '../cursor_read_conversation.js';
+beforeEach(() => {
+    readConversationMock.mockReset();
+});
+afterEach(() => {
+    vi.clearAllMocks();
+});
+describe('cursor history tools', () => {
+    test('cursor_read_conversation 返回消息时间线', async () => {
+        readConversationMock.mockResolvedValue({
+            composerId: 'c1',
+            messages: [
+                { bubbleId: 'b1', type: 1, text: '我们先聊需求' },
+                { bubbleId: 'b2', type: 2, text: '听懂了' },
+            ],
+        });
+        const result = await cursorReadConversation({ composer_id: 'c1', limit: 50, include_empty: true });
+        expect(result.isError).toBe(false);
+        expect('structuredContent' in result).toBe(true);
+        if (!('structuredContent' in result)) {
+            throw new Error('structuredContent 缺失');
+        }
+        expect(result.content[0].text).toContain('共 2 条消息');
+        expect(result.structuredContent.messageCount).toBe(2);
+        expect(readConversationMock).toHaveBeenCalledWith({
+            composerId: 'c1',
+            limit: 50,
+            includeEmpty: true,
+        });
+    });
+});

package/build/tools/check_spec.js

@@ -55,23 +55,23 @@ export async function checkSpec(args) {
             ? 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}
+
+**需求清单**: ${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）直到通过
+            : `# ❌ 规格校验未通过：${featureName}
+
+${report.summary}
+
+## 待修复（${relDir}）
+${issueLines}
+
+## 处理方式
+1. 按上述每一条补全 \`${relDir}/\` 下的 requirements.md / design.md / tasks.md
+2. **重新运行** \`check_spec\`（同样的 feature_name）直到通过
 3. **校验通过前不要开始写实现代码** —— 这是为了确保需求被完整实现，而不是写到一半才发现规格有缺口`;
         return okStructured(text, report);
     }

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/code_review.js

@@ -2,6 +2,7 @@ import { parseArgs, getString } from "../utils/parseArgs.js";
 import { okText } from "../lib/response.js";
 import { renderGuidanceHeader } from "../lib/guidance.js";
 import { handleToolError } from "../utils/error-handler.js";
+import { renderCodeLimits, renderBannedPatterns, CODE_LIMITS } from "../lib/quality-constraints.js";
 // code_review 工具实现
 export async function codeReview(args) {
     try {
@@ -38,11 +39,13 @@ ${code || "请提供需要审查的代码"}
 
 ### 1️⃣ 代码质量检查
 
+${renderCodeLimits()}
+
 **代码坏味道（Code Smells）**：
 - [ ] 重复代码（Duplicated Code）
-- [ ] 过长函数（Long Function）> 30 行
-- [ ] 过长参数列表（Long Parameter List）> 3 个
-- [ ] 复杂条件判断（Complex Conditional）> 3 层嵌套
+- [ ] 过长函数（Long Function）> ${CODE_LIMITS.maxFunctionLines} 行
+- [ ] 过长参数列表（Long Parameter List）> ${CODE_LIMITS.maxParameters} 个
+- [ ] 复杂条件判断（Complex Conditional）> ${CODE_LIMITS.maxNestingDepth} 层嵌套
 - [ ] 魔法数字（Magic Numbers）
 - [ ] 命名不清晰（Poor Naming）
 
@@ -88,7 +91,11 @@ ${code || "请提供需要审查的代码"}
 - [ ] 大列表未虚拟化
 - [ ] 状态管理不当
 
-### 4️⃣ 最佳实践检查
+### 4️⃣ 完整性检查
+
+${renderBannedPatterns()}
+
+### 5️⃣ 最佳实践检查
 
 **TypeScript/JavaScript**：
 - [ ] 类型定义完整（避免 any）

package/build/tools/cursor_read_conversation.d.ts

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

package/build/tools/cursor_read_conversation.js

@@ -0,0 +1,36 @@
+import { parseArgs, getString, getNumber, getBoolean } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { createCursorHistoryClient } from '../lib/cursor-history-client.js';
+export async function cursorReadConversation(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                composer_id: '',
+                limit: 200,
+                include_empty: false,
+            },
+            fieldAliases: {
+                composer_id: ['conversation_id', 'chat_id'],
+            },
+        });
+        const composerId = getString(parsed.composer_id).trim();
+        if (!composerId) {
+            throw new Error('缺少必填参数: composer_id');
+        }
+        const client = createCursorHistoryClient();
+        const conversation = await client.readConversation({
+            composerId,
+            limit: getNumber(parsed.limit, 200),
+            includeEmpty: getBoolean(parsed.include_empty, false),
+        });
+        return okStructured(`已读取 Cursor 会话 ${composerId}，共 ${conversation.messages.length} 条消息。`, {
+            composerId,
+            messageCount: conversation.messages.length,
+            conversation,
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'cursor_read_conversation');
+    }
+}

package/build/tools/fix_bug.js

@@ -10,167 +10,167 @@ import { parseArgs, getString } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
 import { renderGuidanceHeader } from "../lib/guidance.js";
 import { handleToolError } from "../utils/error-handler.js";
-const PROMPT_TEMPLATE = `# TBP 8 步 Bug 真因分析与修复指南
-
-## 🐛 Bug 信息
-
-**错误信息**:
-\`\`\`
-{error_message}
-\`\`\`
-
-{stack_trace_section}
-
-{reproduce_section}
-
-{behavior_section}
-
-{code_context_section}
-
----
-
-## TBP-1 现象
-
-先把用户可见的问题定义准确，避免“坏了/卡了/有问题”这类泛化描述。
-
-要求：
-1. 用 1-2 句定义现象
-2. 明确是“慢”“停滞”“失败”“回归”还是“未生效”
-3. 如果提供了期望/实际行为，必须纳入现象定义
-
-## TBP-2 时间线
-
-基于现有信息复盘事件顺序，至少回答：
-1. 什么时候开始
-2. 中间发生了什么
-3. 最后停在什么状态
-
-优先记录：
-- 用户输入 / 复现步骤
-- first progress / first error
-- tool call / stack / stop / timeout
-- 关键文件或模块
-
-## TBP-3 不是这个
-
-列出当前应优先排除的错误方向，并说明需要什么证据排除。
-
-常见排除项：
-- 不是单纯网络慢
-- 不是前端展示截断
-- 不是消息没转发
-- 不是纯粹的超时表象
-- 不是用户输入丢失
-
-## TBP-4 共同模式
-
-对比成功/失败样本，找出从哪一步开始分叉。
-
-重点检查：
-- 传输层
-- 会话状态机
-- 完成态判定
-- 工具执行
-- 文件写入
-- 重试策略
-
-## TBP-5 边界
-
-明确指出问题失控落在哪一层：
-- 上游模型 / SDK
-- 网关状态机
-- session 复用
-- tool 执行层
-- 文件系统
-- 环境配置
-- UI 展示层
-
-## TBP-6 真因
-
-真因必须写成因果句：
-\`A + B 在条件 D 下导致了 C\`
-
-不允许只写：
-- 超时了
-- SDK 有 bug
-- 返回慢
-
-## TBP-7 证据链
-
-说明：
-1. 哪些证据支持真因
-2. 哪些现象若出现会推翻它，但现场没有出现
-3. 为什么其他解释更弱
-
-## TBP-8 修复
-
-只有在证据链闭合后，才开始设计修复。
-
-每个修复方案都要说明：
-- 改哪一层
-- 为什么这是修真因，不是补症状
-- 风险是什么
-- 怎么验证
-
----
-
-## 📤 输出格式要求
-
-请严格按以下 JSON 格式输出修复指南：
-
-\`\`\`json
-{
-  "bug_summary": "Bug 简述（一句话）",
-  "analysis_mode": "tbp8",
-  "analysis": {
-    "error_type": "错误类型",
-    "direct_cause": "直接原因",
-    "root_cause": "根本原因",
-    "affected_scope": "影响范围"
-  },
-  "tbp": {
-    "phenomenon": "TBP-1 现象",
-    "timeline": [],
-    "ruled_out": [],
-    "common_pattern": "TBP-4 共同模式",
-    "boundary": "TBP-5 边界",
-    "root_cause_statement": "A + B 在条件 D 下导致 C",
-    "evidence": [],
-    "repair": []
-  },
-  "location": {
-    "file": "问题文件路径",
-    "line": 42,
-    "function": "问题函数名",
-    "code_snippet": "问题代码片段"
-  },
-  "fix_plan": {
-    "chosen_solution": "选择的修复方案",
-    "reason": "选择理由",
-    "steps": [
-      { "step": 1, "action": "修复步骤", "file": "文件", "change": "变更内容" }
-    ],
-    "code_before": "修改前代码",
-    "code_after": "修改后代码"
-  },
-  "verification": {
-    "test_cases": ["测试用例1", "测试用例2"],
-    "manual_checks": ["手动验证项1", "手动验证项2"]
-  }
-}
-\`\`\`
-
-## ⚠️ 护栏
-
-- 不要一看到新现象就补一个新分支，先判断是不是同一类根因在换表现
-- 不要把“超时”直接当真因，要先分清是没进展、慢进展，还是结果已出现但判定过严
-- 不要只看单一样本就下结论，有对比样本时必须做对比
-- 如果证据不足，要明确说明还缺什么证据
-
----
-
-*指南版本: 2.0.0*
-*工具: MCP Probe Kit - fix_bug*
+const PROMPT_TEMPLATE = `# TBP 8 步 Bug 真因分析与修复指南
+
+## 🐛 Bug 信息
+
+**错误信息**:
+\`\`\`
+{error_message}
+\`\`\`
+
+{stack_trace_section}
+
+{reproduce_section}
+
+{behavior_section}
+
+{code_context_section}
+
+---
+
+## TBP-1 现象
+
+先把用户可见的问题定义准确，避免“坏了/卡了/有问题”这类泛化描述。
+
+要求：
+1. 用 1-2 句定义现象
+2. 明确是“慢”“停滞”“失败”“回归”还是“未生效”
+3. 如果提供了期望/实际行为，必须纳入现象定义
+
+## TBP-2 时间线
+
+基于现有信息复盘事件顺序，至少回答：
+1. 什么时候开始
+2. 中间发生了什么
+3. 最后停在什么状态
+
+优先记录：
+- 用户输入 / 复现步骤
+- first progress / first error
+- tool call / stack / stop / timeout
+- 关键文件或模块
+
+## TBP-3 不是这个
+
+列出当前应优先排除的错误方向，并说明需要什么证据排除。
+
+常见排除项：
+- 不是单纯网络慢
+- 不是前端展示截断
+- 不是消息没转发
+- 不是纯粹的超时表象
+- 不是用户输入丢失
+
+## TBP-4 共同模式
+
+对比成功/失败样本，找出从哪一步开始分叉。
+
+重点检查：
+- 传输层
+- 会话状态机
+- 完成态判定
+- 工具执行
+- 文件写入
+- 重试策略
+
+## TBP-5 边界
+
+明确指出问题失控落在哪一层：
+- 上游模型 / SDK
+- 网关状态机
+- session 复用
+- tool 执行层
+- 文件系统
+- 环境配置
+- UI 展示层
+
+## TBP-6 真因
+
+真因必须写成因果句：
+\`A + B 在条件 D 下导致了 C\`
+
+不允许只写：
+- 超时了
+- SDK 有 bug
+- 返回慢
+
+## TBP-7 证据链
+
+说明：
+1. 哪些证据支持真因
+2. 哪些现象若出现会推翻它，但现场没有出现
+3. 为什么其他解释更弱
+
+## TBP-8 修复
+
+只有在证据链闭合后，才开始设计修复。
+
+每个修复方案都要说明：
+- 改哪一层
+- 为什么这是修真因，不是补症状
+- 风险是什么
+- 怎么验证
+
+---
+
+## 📤 输出格式要求
+
+请严格按以下 JSON 格式输出修复指南：
+
+\`\`\`json
+{
+  "bug_summary": "Bug 简述（一句话）",
+  "analysis_mode": "tbp8",
+  "analysis": {
+    "error_type": "错误类型",
+    "direct_cause": "直接原因",
+    "root_cause": "根本原因",
+    "affected_scope": "影响范围"
+  },
+  "tbp": {
+    "phenomenon": "TBP-1 现象",
+    "timeline": [],
+    "ruled_out": [],
+    "common_pattern": "TBP-4 共同模式",
+    "boundary": "TBP-5 边界",
+    "root_cause_statement": "A + B 在条件 D 下导致 C",
+    "evidence": [],
+    "repair": []
+  },
+  "location": {
+    "file": "问题文件路径",
+    "line": 42,
+    "function": "问题函数名",
+    "code_snippet": "问题代码片段"
+  },
+  "fix_plan": {
+    "chosen_solution": "选择的修复方案",
+    "reason": "选择理由",
+    "steps": [
+      { "step": 1, "action": "修复步骤", "file": "文件", "change": "变更内容" }
+    ],
+    "code_before": "修改前代码",
+    "code_after": "修改后代码"
+  },
+  "verification": {
+    "test_cases": ["测试用例1", "测试用例2"],
+    "manual_checks": ["手动验证项1", "手动验证项2"]
+  }
+}
+\`\`\`
+
+## ⚠️ 护栏
+
+- 不要一看到新现象就补一个新分支，先判断是不是同一类根因在换表现
+- 不要把“超时”直接当真因，要先分清是没进展、慢进展，还是结果已出现但判定过严
+- 不要只看单一样本就下结论，有对比样本时必须做对比
+- 如果证据不足，要明确说明还缺什么证据
+
+---
+
+*指南版本: 2.0.0*
+*工具: MCP Probe Kit - fix_bug*
 `;
 function inferBugType(text) {
     if (/timeout|latency|slow|卡|慢|超时/i.test(text))