mcp-probe-kit 3.0.15 → 3.0.17

package/build/schemas/memory-tools.d.ts

@@ -0,0 +1,191 @@
+export declare const memoryToolSchemas: readonly [{
+    readonly name: "read_memory_asset";
+    readonly description: "当编排阶段已检索到记忆摘要，且 AI 需要查看完整沉淀代码或详细规范时使用。根据 asset_id 读取记忆资产详情。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset_id: {
+                readonly type: "string";
+                readonly description: "记忆资产 ID";
+            };
+        };
+        readonly required: readonly ["asset_id"];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "memorize_asset";
+    readonly description: "当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "资产名称";
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly description: "资产类型，如 code/component/pattern/spec";
+            };
+            readonly description: {
+                readonly type: "string";
+                readonly description: "资产描述";
+            };
+            readonly summary: {
+                readonly type: "string";
+                readonly description: "用于检索的凝练摘要";
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly description: "完整内容";
+            };
+            readonly code_snippet: {
+                readonly type: "string";
+                readonly description: "代码片段，content 的别名";
+            };
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "来源文件路径";
+            };
+            readonly source_project: {
+                readonly type: "string";
+                readonly description: "来源项目";
+            };
+            readonly source_path: {
+                readonly type: "string";
+                readonly description: "来源路径";
+            };
+            readonly usage: {
+                readonly type: "string";
+                readonly description: "适用场景/使用方式";
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly description: "置信度，0-1";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "标签列表";
+            };
+        };
+        readonly required: readonly ["name", "description", "summary"];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "scan_and_extract_patterns";
+    readonly description: "当需要从单段代码、单文件或整个目录中抽取可复用模式，再决定是否沉淀到记忆系统时使用。目录扫描时，优先传 `project_root` 为项目根目录绝对路径，并让 `directory_path` 传相对项目根的路径，例如 `app/utils`；只有无法确定项目根时，才把 `directory_path` 直接设为绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "待分析的代码或文本内容。传入该字段时走单段分析模式";
+            };
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "来源文件路径。单段分析时作为来源路径使用";
+            };
+            readonly project_name: {
+                readonly type: "string";
+                readonly description: "来源项目名";
+            };
+            readonly directory_path: {
+                readonly type: "string";
+                readonly description: "要扫描的目录路径。最佳实践是传相对 `project_root` 的路径，例如 `app/utils`；如果拿不到 `project_root`，才传目录绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。";
+            };
+            readonly project_root: {
+                readonly type: "string";
+                readonly description: "项目根目录绝对路径。目录扫描时建议始终传入；传入后，`directory_path` 应写成相对项目根的路径。";
+            };
+            readonly max_files: {
+                readonly type: "number";
+                readonly description: "最多扫描多少个文件，默认 30，最大 200";
+            };
+            readonly max_patterns: {
+                readonly type: "number";
+                readonly description: "最多返回多少个候选模式，默认 20，最大 100";
+            };
+            readonly include_extensions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "允许扫描的文件扩展名列表，例如 [\".ts\", \".tsx\", \".py\"]";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "cursor_list_conversations";
+    readonly description: "读取 Cursor 本地历史会话摘要。适合按标题、工作区列出最近会话，用于续接旧上下文。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title_query: {
+                readonly type: "string";
+                readonly description: "按会话标题过滤，支持部分匹配";
+            };
+            readonly workspace_query: {
+                readonly type: "string";
+                readonly description: "按工作区路径过滤，支持部分匹配";
+            };
+            readonly include_archived: {
+                readonly type: "boolean";
+                readonly description: "是否包含已归档会话，默认 false";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "最多返回多少条，默认 20，最大 200";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "cursor_search_conversations";
+    readonly description: "在 Cursor 本地历史消息里按关键词、request id 搜索命中内容，可选限定某个会话。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "搜索关键词，可传标题片段、正文片段或 request id";
+            };
+            readonly composer_id: {
+                readonly type: "string";
+                readonly description: "可选，限定某个 Cursor 会话 ID";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "最多返回多少条，默认 20，最大 200";
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "cursor_read_conversation";
+    readonly description: "按 composer_id 读取一条 Cursor 本地会话的消息时间线。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly composer_id: {
+                readonly type: "string";
+                readonly description: "Cursor 会话 ID";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "最多返回多少条消息，默认 200，最大 2000";
+            };
+            readonly include_empty: {
+                readonly type: "boolean";
+                readonly description: "是否包含空文本消息，默认 false";
+            };
+        };
+        readonly required: readonly ["composer_id"];
+        readonly additionalProperties: true;
+    };
+}];

package/build/schemas/memory-tools.js

@@ -0,0 +1,106 @@
+export const memoryToolSchemas = [
+    {
+        name: 'read_memory_asset',
+        description: '当编排阶段已检索到记忆摘要，且 AI 需要查看完整沉淀代码或详细规范时使用。根据 asset_id 读取记忆资产详情。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                asset_id: {
+                    type: 'string',
+                    description: '记忆资产 ID',
+                },
+            },
+            required: ['asset_id'],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'memorize_asset',
+        description: '当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: '资产名称' },
+                type: { type: 'string', description: '资产类型，如 code/component/pattern/spec' },
+                description: { type: 'string', description: '资产描述' },
+                summary: { type: 'string', description: '用于检索的凝练摘要' },
+                content: { type: 'string', description: '完整内容' },
+                code_snippet: { type: 'string', description: '代码片段，content 的别名' },
+                file_path: { type: 'string', description: '来源文件路径' },
+                source_project: { type: 'string', description: '来源项目' },
+                source_path: { type: 'string', description: '来源路径' },
+                usage: { type: 'string', description: '适用场景/使用方式' },
+                confidence: { type: 'number', description: '置信度，0-1' },
+                tags: { type: 'array', items: { type: 'string' }, description: '标签列表' },
+            },
+            required: ['name', 'description', 'summary'],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'scan_and_extract_patterns',
+        description: '当需要从单段代码、单文件或整个目录中抽取可复用模式，再决定是否沉淀到记忆系统时使用。目录扫描时，优先传 `project_root` 为项目根目录绝对路径，并让 `directory_path` 传相对项目根的路径，例如 `app/utils`；只有无法确定项目根时，才把 `directory_path` 直接设为绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: { type: 'string', description: '待分析的代码或文本内容。传入该字段时走单段分析模式' },
+                file_path: { type: 'string', description: '来源文件路径。单段分析时作为来源路径使用' },
+                project_name: { type: 'string', description: '来源项目名' },
+                directory_path: { type: 'string', description: '要扫描的目录路径。最佳实践是传相对 `project_root` 的路径，例如 `app/utils`；如果拿不到 `project_root`，才传目录绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。' },
+                project_root: { type: 'string', description: '项目根目录绝对路径。目录扫描时建议始终传入；传入后，`directory_path` 应写成相对项目根的路径。' },
+                max_files: { type: 'number', description: '最多扫描多少个文件，默认 30，最大 200' },
+                max_patterns: { type: 'number', description: '最多返回多少个候选模式，默认 20，最大 100' },
+                include_extensions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '允许扫描的文件扩展名列表，例如 [".ts", ".tsx", ".py"]'
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'cursor_list_conversations',
+        description: '读取 Cursor 本地历史会话摘要。适合按标题、工作区列出最近会话，用于续接旧上下文。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title_query: { type: 'string', description: '按会话标题过滤，支持部分匹配' },
+                workspace_query: { type: 'string', description: '按工作区路径过滤，支持部分匹配' },
+                include_archived: { type: 'boolean', description: '是否包含已归档会话，默认 false' },
+                limit: { type: 'number', description: '最多返回多少条，默认 20，最大 200' },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'cursor_search_conversations',
+        description: '在 Cursor 本地历史消息里按关键词、request id 搜索命中内容，可选限定某个会话。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: '搜索关键词，可传标题片段、正文片段或 request id' },
+                composer_id: { type: 'string', description: '可选，限定某个 Cursor 会话 ID' },
+                limit: { type: 'number', description: '最多返回多少条，默认 20，最大 200' },
+            },
+            required: ['query'],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'cursor_read_conversation',
+        description: '按 composer_id 读取一条 Cursor 本地会话的消息时间线。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                composer_id: { type: 'string', description: 'Cursor 会话 ID' },
+                limit: { type: 'number', description: '最多返回多少条消息，默认 200，最大 2000' },
+                include_empty: { type: 'boolean', description: '是否包含空文本消息，默认 false' },
+            },
+            required: ['composer_id'],
+            additionalProperties: true,
+        },
+    },
+];

package/build/schemas/orchestration-tools.d.ts

@@ -21,7 +21,7 @@ export declare const orchestrationToolSchemas: readonly [{
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录。当前客户端未把工作区作为进程 cwd 传进来时，建议显式指定";
+                readonly description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。";
             };
             readonly template_profile: {
                 readonly type: "string";
@@ -67,7 +67,7 @@ export declare const orchestrationToolSchemas: readonly [{
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录。当前客户端未把工作区作为进程 cwd 传进来时，建议显式指定";
+                readonly description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。";
             };
             readonly analysis_mode: {
                 readonly type: "string";
@@ -105,7 +105,7 @@ export declare const orchestrationToolSchemas: readonly [{
         readonly properties: {
             readonly project_path: {
                 readonly type: "string";
-                readonly description: "项目路径。可选，默认当前目录";
+                readonly description: "项目根目录绝对路径。建议显式传入；如果还传 docs_dir 等相对路径，应统一相对该项目根目录解析。";
             };
             readonly docs_dir: {
                 readonly type: "string";

package/build/schemas/orchestration-tools.js

@@ -22,7 +22,7 @@ export const orchestrationToolSchemas = [
                 },
                 project_root: {
                     type: "string",
-                    description: "项目根目录。当前客户端未把工作区作为进程 cwd 传进来时，建议显式指定",
+                    description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。",
                 },
                 template_profile: {
                     type: "string",
@@ -69,7 +69,7 @@ export const orchestrationToolSchemas = [
                 },
                 project_root: {
                     type: "string",
-                    description: "项目根目录。当前客户端未把工作区作为进程 cwd 传进来时，建议显式指定",
+                    description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。",
                 },
                 analysis_mode: {
                     type: "string",
@@ -108,7 +108,7 @@ export const orchestrationToolSchemas = [
             properties: {
                 project_path: {
                     type: "string",
-                    description: "项目路径。可选，默认当前目录",
+                    description: "项目根目录绝对路径。建议显式传入；如果还传 docs_dir 等相对路径，应统一相对该项目根目录解析。",
                 },
                 docs_dir: {
                     type: "string",

package/build/schemas/ui-ux-schemas.d.ts

@@ -105,6 +105,10 @@ export declare const startUiSchema: {
                 type: string;
                 description: string;
             };
+            project_root: {
+                type: string;
+                description: string;
+            };
             template_profile: {
                 type: string;
                 description: string;
@@ -236,6 +240,10 @@ export declare const uiUxSchemas: ({
                 type: string;
                 description: string;
             };
+            project_root: {
+                type: string;
+                description: string;
+            };
             template_profile: {
                 type: string;
                 description: string;

package/build/schemas/ui-ux-schemas.js

@@ -69,7 +69,7 @@ export const uiSearchSchema = {
 };
 export const syncUiDataSchema = {
     name: "sync_ui_data",
-    description: "同步 UI/UX 数据到本地缓存。从 npm 包 uipro-cli 下载最新数据，支持自动检查更新和强制同步。数据存储在 ~/.mcp-probe-kit/ui-ux-data/。",
+    description: "同步 UI/UX 数据到本地缓存。从 npm 包 uipro-cli 下载最新数据，支持自动检查更新和强制同步。数据存储在 ~/.mcp-probe-kit/ui-ux-data/，默认在下次启动时生效以保证当前会话一致性。",
     inputSchema: {
         type: "object",
         properties: {
@@ -105,6 +105,10 @@ export const startUiSchema = {
                 type: "string",
                 description: "模板名称（可选，不提供则自动生成）",
             },
+            project_root: {
+                type: "string",
+                description: "项目根目录绝对路径。建议显式传入；如果存在 docs 或模板等相对路径解析，应统一相对该项目根目录处理，避免依赖客户端 cwd。",
+            },
             template_profile: {
                 type: "string",
                 description: "模板档位：auto（默认，自动选择 guided/strict）、guided（普通模型友好）或 strict（结构更紧凑）",

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,87 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+const listConversationsMock = vi.fn();
+const searchHistoryMock = vi.fn();
+const readConversationMock = vi.fn();
+vi.mock('../../lib/cursor-history-client.js', () => ({
+    createCursorHistoryClient: () => ({
+        listConversations: listConversationsMock,
+        searchHistory: searchHistoryMock,
+        readConversation: readConversationMock,
+    }),
+}));
+import { cursorListConversations } from '../cursor_list_conversations.js';
+import { cursorSearchConversations } from '../cursor_search_conversations.js';
+import { cursorReadConversation } from '../cursor_read_conversation.js';
+beforeEach(() => {
+    listConversationsMock.mockReset();
+    searchHistoryMock.mockReset();
+    readConversationMock.mockReset();
+});
+afterEach(() => {
+    vi.clearAllMocks();
+});
+describe('cursor history tools', () => {
+    test('cursor_list_conversations 返回摘要列表', async () => {
+        listConversationsMock.mockResolvedValue([
+            { composerId: 'c1', name: '新需求', source: 'composerHeaders' },
+        ]);
+        const result = await cursorListConversations({ title_query: '新需求', limit: 10 });
+        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('已获取 1 条 Cursor 会话摘要');
+        expect(result.structuredContent.count).toBe(1);
+        expect(listConversationsMock).toHaveBeenCalledWith({
+            titleQuery: '新需求',
+            workspaceQuery: '',
+            includeArchived: false,
+            limit: 10,
+        });
+    });
+    test('cursor_search_conversations 缺少 query 时返回错误', async () => {
+        const result = await cursorSearchConversations({});
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('缺少必填参数: query');
+    });
+    test('cursor_search_conversations 返回命中结果', async () => {
+        searchHistoryMock.mockResolvedValue([
+            { composerId: 'c1', conversationName: '新需求', bubbleId: 'b1', type: 1, text: '我们先聊需求' },
+        ]);
+        const result = await cursorSearchConversations({ query: '需求', composer_id: 'c1', limit: 5 });
+        expect(result.isError).toBe(false);
+        expect('structuredContent' in result).toBe(true);
+        if (!('structuredContent' in result)) {
+            throw new Error('structuredContent 缺失');
+        }
+        expect(result.structuredContent.count).toBe(1);
+        expect(searchHistoryMock).toHaveBeenCalledWith({
+            query: '需求',
+            composerId: 'c1',
+            limit: 5,
+        });
+    });
+    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/__tests__/memorize_asset.unit.test.d.ts

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

package/build/tools/__tests__/memorize_asset.unit.test.js

@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+const upsertAssetMock = vi.fn();
+const isEnabledMock = vi.fn();
+vi.mock('../../lib/memory-client.js', () => ({
+    createMemoryClient: () => ({
+        isEnabled: isEnabledMock,
+        upsertAsset: upsertAssetMock,
+    }),
+}));
+import { memorizeAsset } from '../memorize_asset.js';
+beforeEach(() => {
+    isEnabledMock.mockReset();
+    upsertAssetMock.mockReset();
+});
+afterEach(() => {
+    vi.clearAllMocks();
+});
+describe('memorize_asset 单元测试', () => {
+    const validArgs = {
+        name: 'AppError',
+        description: '统一错误封装',
+        summary: '用于标准化应用错误处理',
+        content: 'export class AppError extends Error {}',
+    };
+    test('记忆服务未开启时返回跳过结果而不是报错', async () => {
+        isEnabledMock.mockReturnValue(false);
+        const result = await memorizeAsset(validArgs);
+        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('记忆服务未开启');
+        expect(result.structuredContent).toEqual({ enabled: false, stored: false });
+        expect(upsertAssetMock).not.toHaveBeenCalled();
+    });
+    test('记忆服务开启时写入资产', async () => {
+        isEnabledMock.mockReturnValue(true);
+        upsertAssetMock.mockResolvedValue({
+            id: 'asset-1',
+            name: 'AppError',
+            type: 'code',
+            description: '统一错误封装',
+            summary: '用于标准化应用错误处理',
+            content: 'export class AppError extends Error {}',
+            tags: [],
+            confidence: 0.7,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+        });
+        const result = await memorizeAsset(validArgs);
+        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('已沉淀记忆资产: AppError');
+        expect(result.structuredContent.enabled).toBe(true);
+        expect(result.structuredContent.stored).toBe(true);
+        expect(upsertAssetMock).toHaveBeenCalledTimes(1);
+        expect(upsertAssetMock).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'AppError',
+            description: '统一错误封装',
+            summary: '用于标准化应用错误处理',
+            content: 'export class AppError extends Error {}',
+        }));
+    });
+});

package/build/tools/code_insight.d.ts

@@ -44,5 +44,25 @@ export declare function codeInsight(args: any, context?: ToolExecutionContext):
         text: string;
     }[];
     isError: boolean;
+    structuredContent: {
+        error_code: string;
+        rejected_project_root: string;
+        retry_hint: {
+            preferred: {
+                project_root: string;
+                path: string;
+            };
+            fallback: {
+                project_root: string;
+            };
+        };
+    };
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+    structuredContent?: undefined;
 }>;
 export {};

package/build/tools/code_insight.js

@@ -5,6 +5,7 @@ import { okStructured } from "../lib/response.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { runCodeInsightBridge, } from "../lib/gitnexus-bridge.js";
 import { throwIfAborted, } from "../lib/tool-execution-context.js";
+import { isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
 const ALLOWED_MODES = new Set(["auto", "query", "context", "impact"]);
 const ALLOWED_DIRECTIONS = new Set(["upstream", "downstream"]);
 const DEFAULT_AUTO_QUERY = "项目整体架构 核心流程 关键模块 依赖关系 入口点";
@@ -248,6 +249,20 @@ export async function codeInsight(args, context) {
         const filePath = getString(parsedArgs.file_path);
         const repo = getString(parsedArgs.repo);
         const projectRoot = getString(parsedArgs.project_root);
+        if (isLikelyProjectNamedRelativePath(projectRoot)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `拒绝执行 code_insight：project_root 不能传带项目名的半相对路径，例如 ${projectRoot}。请改为传项目根目录绝对路径。`,
+                    }],
+                isError: true,
+                structuredContent: {
+                    error_code: "INVALID_PROJECT_ROOT",
+                    rejected_project_root: projectRoot,
+                    retry_hint: buildProjectRootRetryHint(projectRoot),
+                },
+            };
+        }
         const docsDirName = getString(parsedArgs.docs_dir) || "docs";
         const goal = getString(parsedArgs.goal);
         const taskContext = getString(parsedArgs.task_context);

package/build/tools/cursor_list_conversations.d.ts

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

package/build/tools/cursor_list_conversations.js

@@ -0,0 +1,35 @@
+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 cursorListConversations(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                title_query: '',
+                workspace_query: '',
+                include_archived: false,
+                limit: 20,
+            },
+            fieldAliases: {
+                title_query: ['title', 'name_query', 'query'],
+                workspace_query: ['workspace', 'workspace_path'],
+                include_archived: ['archived'],
+            },
+        });
+        const client = createCursorHistoryClient();
+        const conversations = await client.listConversations({
+            titleQuery: getString(parsed.title_query),
+            workspaceQuery: getString(parsed.workspace_query),
+            includeArchived: getBoolean(parsed.include_archived, false),
+            limit: getNumber(parsed.limit, 20),
+        });
+        return okStructured(`已获取 ${conversations.length} 条 Cursor 会话摘要。`, {
+            count: conversations.length,
+            conversations,
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'cursor_list_conversations');
+    }
+}