mcp-probe-kit 3.0.18 → 3.0.21

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

@@ -1,4 +1,33 @@
 export declare const memoryToolSchemas: readonly [{
+    readonly name: "search_memory";
+    readonly description: "按语义检索共享记忆库。适合在 start_* 之外主动查找历史 Bug 修复或可复用模式；命中后用 read_memory_asset 读取全文。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "检索 query（现象、报错、关键词、功能描述等）";
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly description: "优先匹配的资产类型，如 bugfix、pattern、component";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "优先匹配的标签";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "返回条数，默认 MEMORY_SEARCH_LIMIT";
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly additionalProperties: true;
+    };
+}, {
     readonly name: "read_memory_asset";
     readonly description: "当编排阶段已检索到记忆摘要，且 AI 需要查看完整沉淀代码或详细规范时使用。根据 asset_id 读取记忆资产详情。";
     readonly inputSchema: {
@@ -14,7 +43,7 @@ export declare const memoryToolSchemas: readonly [{
     };
 }, {
     readonly name: "memorize_asset";
-    readonly description: "当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。";
+    readonly description: "沉淀可检索资产到共享记忆库。Bug 修复后必须 type=bugfix，content 含【现象】【根因】【修复】【验证】。跨仓库共享时勿填 source_project/source_path，路径写入 content 即可。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -24,7 +53,7 @@ export declare const memoryToolSchemas: readonly [{
             };
             readonly type: {
                 readonly type: "string";
-                readonly description: "资产类型，如 code/component/pattern/spec";
+                readonly description: "资产类型：bugfix / pattern / component / code 等";
             };
             readonly description: {
                 readonly type: "string";
@@ -32,11 +61,11 @@ export declare const memoryToolSchemas: readonly [{
             };
             readonly summary: {
                 readonly type: "string";
-                readonly description: "用于检索的凝练摘要";
+                readonly description: "检索用一句话摘要（关键词 + 根因/要点）";
             };
             readonly content: {
                 readonly type: "string";
-                readonly description: "完整内容";
+                readonly description: "完整内容（bugfix 建议结构化四段）";
             };
             readonly code_snippet: {
                 readonly type: "string";
@@ -44,15 +73,15 @@ export declare const memoryToolSchemas: readonly [{
             };
             readonly file_path: {
                 readonly type: "string";
-                readonly description: "来源文件路径";
+                readonly description: "已废弃：勿用于跨仓库沉淀，路径写入 content";
             };
             readonly source_project: {
                 readonly type: "string";
-                readonly description: "来源项目";
+                readonly description: "已废弃：仅同仓库追溯时可选";
             };
             readonly source_path: {
                 readonly type: "string";
-                readonly description: "来源路径";
+                readonly description: "已废弃：仅同仓库追溯时可选";
             };
             readonly usage: {
                 readonly type: "string";
@@ -67,7 +96,7 @@ export declare const memoryToolSchemas: readonly [{
                 readonly items: {
                     readonly type: "string";
                 };
-                readonly description: "标签列表";
+                readonly description: "标签列表，如 bugfix, root-cause";
             };
         };
         readonly required: readonly ["name", "description", "summary"];
@@ -89,7 +118,7 @@ export declare const memoryToolSchemas: readonly [{
             };
             readonly project_name: {
                 readonly type: "string";
-                readonly description: "来源项目名";
+                readonly description: "已废弃，扫描结果不再写入 source_project";
             };
             readonly directory_path: {
                 readonly type: "string";

package/build/schemas/memory-tools.js

@@ -1,4 +1,19 @@
 export const memoryToolSchemas = [
+    {
+        name: 'search_memory',
+        description: '按语义检索共享记忆库。适合在 start_* 之外主动查找历史 Bug 修复或可复用模式；命中后用 read_memory_asset 读取全文。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: '检索 query（现象、报错、关键词、功能描述等）' },
+                type: { type: 'string', description: '优先匹配的资产类型，如 bugfix、pattern、component' },
+                tags: { type: 'array', items: { type: 'string' }, description: '优先匹配的标签' },
+                limit: { type: 'number', description: '返回条数，默认 MEMORY_SEARCH_LIMIT' },
+            },
+            required: ['query'],
+            additionalProperties: true,
+        },
+    },
     {
         name: 'read_memory_asset',
         description: '当编排阶段已检索到记忆摘要，且 AI 需要查看完整沉淀代码或详细规范时使用。根据 asset_id 读取记忆资产详情。',
@@ -16,22 +31,22 @@ export const memoryToolSchemas = [
     },
     {
         name: 'memorize_asset',
-        description: '当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。',
+        description: '沉淀可检索资产到共享记忆库。Bug 修复后必须 type=bugfix，content 含【现象】【根因】【修复】【验证】。跨仓库共享时勿填 source_project/source_path，路径写入 content 即可。',
         inputSchema: {
             type: 'object',
             properties: {
                 name: { type: 'string', description: '资产名称' },
-                type: { type: 'string', description: '资产类型，如 code/component/pattern/spec' },
+                type: { type: 'string', description: '资产类型：bugfix / pattern / component / code 等' },
                 description: { type: 'string', description: '资产描述' },
-                summary: { type: 'string', description: '用于检索的凝练摘要' },
-                content: { type: 'string', description: '完整内容' },
+                summary: { type: 'string', description: '检索用一句话摘要（关键词 + 根因/要点）' },
+                content: { type: 'string', description: '完整内容（bugfix 建议结构化四段）' },
                 code_snippet: { type: 'string', description: '代码片段，content 的别名' },
-                file_path: { type: 'string', description: '来源文件路径' },
-                source_project: { type: 'string', description: '来源项目' },
-                source_path: { type: 'string', description: '来源路径' },
+                file_path: { type: 'string', description: '已废弃：勿用于跨仓库沉淀，路径写入 content' },
+                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: '标签列表' },
+                tags: { type: 'array', items: { type: 'string' }, description: '标签列表，如 bugfix, root-cause' },
             },
             required: ['name', 'description', 'summary'],
             additionalProperties: true,
@@ -45,7 +60,7 @@ export const memoryToolSchemas = [
             properties: {
                 content: { type: 'string', description: '待分析的代码或文本内容。传入该字段时走单段分析模式' },
                 file_path: { type: 'string', description: '来源文件路径。单段分析时作为来源路径使用' },
-                project_name: { type: 'string', description: '来源项目名' },
+                project_name: { type: 'string', description: '已废弃，扫描结果不再写入 source_project' },
                 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' },

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

@@ -3,13 +3,35 @@
  */
 export declare const projectToolSchemas: readonly [{
     readonly name: "init_project_context";
-    readonly description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考";
+    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
             readonly docs_dir: {
                 readonly type: "string";
-                readonly description: "文档目录。可选，默认 docs";
+                readonly description: "附属文档根目录（project-context、graph-insights）。默认 docs";
+            };
+            readonly index_style: {
+                readonly type: "string";
+                readonly enum: readonly ["auto", "agents", "legacy"];
+                readonly description: "索引风格：auto（默认 AGENTS.md）、agents、legacy（docs/project-context.md）";
+            };
+            readonly output: {
+                readonly type: "string";
+                readonly description: "高级：索引文件相对路径，如 AGENTS.md";
+            };
+            readonly output_dir: {
+                readonly type: "string";
+                readonly description: "高级：索引所在目录，如 .claude/rules";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly description: "高级：与 output_dir 合用，默认 project-context.md";
+            };
+            readonly locale: {
+                readonly type: "string";
+                readonly enum: readonly ["en", "zh-CN"];
+                readonly description: "AGENTS.md 语言；默认根据 README 探测";
             };
         };
         readonly required: readonly [];

package/build/schemas/project-tools.js

@@ -4,13 +4,35 @@
 export const projectToolSchemas = [
     {
         name: "init_project_context",
-        description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考",
+        description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。",
         inputSchema: {
             type: "object",
             properties: {
                 docs_dir: {
                     type: "string",
-                    description: "文档目录。可选，默认 docs",
+                    description: "附属文档根目录（project-context、graph-insights）。默认 docs",
+                },
+                index_style: {
+                    type: "string",
+                    enum: ["auto", "agents", "legacy"],
+                    description: "索引风格：auto（默认 AGENTS.md）、agents、legacy（docs/project-context.md）",
+                },
+                output: {
+                    type: "string",
+                    description: "高级：索引文件相对路径，如 AGENTS.md",
+                },
+                output_dir: {
+                    type: "string",
+                    description: "高级：索引所在目录，如 .claude/rules",
+                },
+                filename: {
+                    type: "string",
+                    description: "高级：与 output_dir 合用，默认 project-context.md",
+                },
+                locale: {
+                    type: "string",
+                    enum: ["en", "zh-CN"],
+                    description: "AGENTS.md 语言；默认根据 README 探测",
                 },
             },
             required: [],

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

@@ -144,15 +144,15 @@ describe("code_insight 单元测试", () => {
             expect(text).toMatch(/不要只口头总结而不写文件/);
             expect(text).toMatch(/docs\/graph-insights\/latest\.md/);
             expect(text).toMatch(/使用场景指南/);
-            expect(structured.projectDocs.latestMarkdownFilePath).toContain("/docs/graph-insights/latest.md");
+            expect(structured.projectDocs.latestMarkdownFilePath).toMatch(/docs\/graph-insights\/latest\.md$/);
             expect(structured.projectDocs.archiveMarkdownFilePath).toContain("/docs/graph-insights/");
-            expect(structured.projectDocs.projectContextFilePath).toContain("/docs/project-context.md");
+            expect(structured.projectDocs.projectContextFilePath).toMatch(/\/(AGENTS\.md|docs\/project-context\.md)$/);
             expect(structured.projectDocs.navigationSnippet).toMatch(/代码图谱洞察/);
             expect(structured.plan.mode).toBe("delegated");
             expect(structured.plan.steps).toHaveLength(2);
             expect(structured.plan.steps[0].id).toBe("consume-result");
             expect(structured.plan.steps[1].id).toBe("optional-save");
-            expect(structured.plan.steps[1].outputs[0]).toContain("/docs/graph-insights/latest.md");
+            expect(structured.plan.steps[1].outputs[0]).toMatch(/docs\/graph-insights\/latest\.md$/);
             expect(fs.existsSync(path.join(projectRoot, "docs", "graph-insights", "latest.md"))).toBe(false);
         }
         finally {

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

@@ -4,10 +4,11 @@ import path from 'node:path';
 import { describe, expect, test } from 'vitest';
 import { initProjectContext } from '../init_project_context.js';
 describe('init_project_context 单元测试', () => {
-    test('返回 delegated plan，并预置 code_insight 图谱初始化步骤', async () => {
+    test('返回 delegated plan，含 finalize-agents-md 与 AGENTS.md 模板', async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-init-'));
         const result = await initProjectContext({
             docs_dir: 'docs',
-            project_root: 'E:/workspace/github/mcp-probe-kit',
+            project_root: projectRoot,
         });
         expect(result.isError).toBeFalsy();
         expect('structuredContent' in result).toBe(true);
@@ -15,49 +16,59 @@ describe('init_project_context 单元测试', () => {
             throw new Error('structuredContent 缺失');
         }
         const structured = result.structuredContent;
+        expect(structured.documentation.some((item) => item.path === 'AGENTS.md')).toBe(true);
         expect(structured.documentation.some((item) => item.path === 'docs/graph-insights/latest.md')).toBe(true);
-        expect(structured.documentation.some((item) => item.path === 'docs/graph-insights/latest.json')).toBe(true);
-        expect(structured.metadata?.graphDocs?.latestMarkdownFilePath).toContain('/docs/graph-insights/latest.md');
+        expect(structured.metadata?.layout?.indexPath).toBe('AGENTS.md');
+        expect(structured.metadata?.agentsMdTemplate).toMatch(/mcp-probe:context begin/);
+        expect(structured.metadata?.manifestWritten).toBe('docs/.mcp-probe/layout.json');
+        expect(fs.existsSync(path.join(projectRoot, 'docs', '.mcp-probe', 'layout.json'))).toBe(true);
         const plan = structured.metadata?.plan;
         expect(plan?.mode).toBe('delegated');
         expect(plan.steps.map((step) => step.id)).toEqual([
-            'write-project-context',
+            'write-modular-docs',
             'bootstrap-code-insight',
             'persist-graph-docs',
+            'finalize-agents-md',
         ]);
-        expect(plan.steps[1].action).toMatch(/code_insight/);
+        expect(plan.steps[0].outputs).toContain('docs/project-context.md');
+        expect(plan.steps[3].id).toBe('finalize-agents-md');
     });
-    test('输出文本包含 graph-insights 入口和 delegated plan', async () => {
+    test('输出文本包含 AGENTS.md 与 MCP 触发规则', async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-init-'));
         const result = await initProjectContext({
-            docs_dir: 'docs',
-            project_root: 'E:/workspace/github/mcp-probe-kit',
+            project_root: projectRoot,
         });
         const text = result.content[0].text;
-        expect(text).toMatch(/graph-insights\/latest\.md/);
-        expect(text).toMatch(/delegated plan/);
-        expect(text).toMatch(/code_insight/);
+        expect(text).toMatch(/AGENTS\.md/);
+        expect(text).toMatch(/start_feature/);
+        expect(text).toMatch(/finalize-agents-md/);
     });
-    test('已存在 project-context.md 时不再规划重写上下文文档', async () => {
+    test('已存在 project-context 分类文档时跳过重写 modular', async () => {
         const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-context-'));
-        fs.mkdirSync(path.join(projectRoot, 'docs'), { recursive: true });
+        fs.mkdirSync(path.join(projectRoot, 'docs', 'project-context'), { recursive: true });
         fs.writeFileSync(path.join(projectRoot, 'docs', 'project-context.md'), '# existing context\n', 'utf8');
         const result = await initProjectContext({
             docs_dir: 'docs',
             project_root: projectRoot,
         });
         expect(result.isError).toBeFalsy();
-        expect('structuredContent' in result).toBe(true);
-        if (!('structuredContent' in result)) {
-            throw new Error('structuredContent 缺失');
-        }
         const structured = result.structuredContent;
-        expect(structured.metadata?.projectContextExists).toBe(true);
+        expect(structured.metadata?.legacyProjectContextExists).toBe(true);
         expect(structured.metadata?.plan?.steps.map((step) => step.id)).toEqual([
             'bootstrap-code-insight',
             'persist-graph-docs',
+            'finalize-agents-md',
         ]);
         const text = result.content[0].text;
-        expect(text).toMatch(/已存在（将保留，不覆盖）/);
-        expect(text).toMatch(/不要重写/);
+        expect(text).toMatch(/保留/);
+    });
+    test('已有 AGENTS.md 用户内容时 prepend merge', async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-agents-'));
+        fs.writeFileSync(path.join(projectRoot, 'AGENTS.md'), '# Custom rules\n', 'utf8');
+        const result = await initProjectContext({ project_root: projectRoot });
+        const structured = result.structuredContent;
+        expect(structured.metadata?.agentsMdMergeMode).toBe('prepended');
+        expect(structured.metadata?.agentsMdTemplate).toMatch(/<!-- mcp-probe:context begin/);
+        expect(structured.metadata?.agentsMdTemplate).toContain('# Custom rules');
     });
 });

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

@@ -25,12 +25,13 @@ describe('start_feature 单元测试', () => {
         expect(plan).toBeTruthy();
         expect(plan.mode).toBe('delegated');
         expect(Array.isArray(plan.steps)).toBe(true);
-        expect(plan.steps.length).toBe(3);
+        expect(plan.steps.length).toBeGreaterThanOrEqual(3);
         const tools = plan.steps.map((step) => step.tool);
         expect(tools).toContain('init_project_context');
         expect(tools).toContain('add_feature');
         expect(tools).toContain('estimate');
         const contextStep = plan.steps.find((step) => step.tool === 'init_project_context');
+        expect(contextStep.outputs).toContain('AGENTS.md');
         expect(contextStep.outputs).toContain('docs/graph-insights/latest.md');
         expect(contextStep.outputs).toContain('docs/graph-insights/latest.json');
         expect(contextStep.when).toMatch(/graph-insights\/latest\.md/);

package/build/tools/code_insight.js

@@ -5,7 +5,8 @@ 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";
+import { isLikelyProjectNamedRelativePath, buildProjectRootRetryHint, resolveWorkspaceRoot } from "../lib/workspace-root.js";
+import { layoutAbsPath, parseLayoutArgsFromRecord, resolveProjectContextLayout, } from "../lib/project-context-layout.js";
 const ALLOWED_MODES = new Set(["auto", "query", "context", "impact"]);
 const ALLOWED_DIRECTIONS = new Set(["upstream", "downstream"]);
 const DEFAULT_AUTO_QUERY = "项目整体架构 核心流程 关键模块 依赖关系 入口点";
@@ -25,7 +26,7 @@ function buildProjectDocsOutputs(input) {
     if (!projectRoot) {
         return null;
     }
-    const docsRoot = path.join(path.resolve(projectRoot), input.docsDirName || "docs", "graph-insights");
+    const docsRoot = path.join(path.resolve(projectRoot), input.graphDir || "docs/graph-insights");
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
     const suffix = makeSafeSegment(input.structured.summary || input.mode);
     const baseName = `${timestamp}-${input.mode}-${suffix}`;
@@ -126,13 +127,13 @@ function formatAmbiguities(ambiguities) {
     })
         .join("\n");
 }
-function createProjectDocsPlan(projectRoot, docsDirName, docsSnapshot) {
-    const docsDir = path.dirname(docsSnapshot.markdownFilePath);
+function createProjectDocsPlan(layout, docsSnapshot) {
+    const docsDir = layout.contextRoot;
     return {
         docsDir,
-        projectContextFilePath: toPosixPath(path.join(path.resolve(projectRoot), docsDirName, "project-context.md")),
-        latestMarkdownFilePath: toPosixPath(path.join(docsDir, "latest.md")),
-        latestJsonFilePath: toPosixPath(path.join(docsDir, "latest.json")),
+        projectContextFilePath: toPosixPath(layoutAbsPath(layout, layout.indexPath)),
+        latestMarkdownFilePath: layout.latestMarkdownPath,
+        latestJsonFilePath: layout.latestJsonPath,
         archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
         archiveJsonFilePath: docsSnapshot.jsonFilePath,
         navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
@@ -264,6 +265,7 @@ export async function codeInsight(args, context) {
             };
         }
         const docsDirName = getString(parsedArgs.docs_dir) || "docs";
+        const layout = resolveProjectContextLayout(projectRoot ? resolveWorkspaceRoot(projectRoot) : resolveWorkspaceRoot(), parseLayoutArgsFromRecord({ docs_dir: docsDirName }));
         const goal = getString(parsedArgs.goal);
         const taskContext = getString(parsedArgs.task_context);
         const direction = normalizeDirection(getString(parsedArgs.direction));
@@ -344,12 +346,12 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
         const docsProjectRoot = saveToDocs ? (projectRoot || result.sourceRoot) : "";
         const docsSnapshot = buildProjectDocsOutputs({
             projectRoot: docsProjectRoot,
-            docsDirName,
+            graphDir: layout.graphDir,
             mode,
             structured,
         });
         const projectDocs = docsSnapshot
-            ? createProjectDocsPlan(docsProjectRoot, docsDirName, docsSnapshot)
+            ? createProjectDocsPlan(layout, docsSnapshot)
             : undefined;
         if (projectDocs) {
             structured.projectDocs = projectDocs;

package/build/tools/index.d.ts

@@ -16,6 +16,7 @@ export { interview } from "./interview.js";
 export { askUser } from "./ask_user.js";
 export { uiDesignSystem, uiSearch, syncUiData } from "./ui-ux-tools.js";
 export { startUi } from "./start_ui.js";
+export { searchMemory } from "./search_memory.js";
 export { readMemoryAsset } from "./read_memory_asset.js";
 export { memorizeAsset } from "./memorize_asset.js";
 export { scanAndExtractPatterns } from "./scan_and_extract_patterns.js";

package/build/tools/index.js

@@ -20,6 +20,7 @@ export { askUser } from "./ask_user.js";
 export { uiDesignSystem, uiSearch, syncUiData } from "./ui-ux-tools.js";
 export { startUi } from "./start_ui.js";
 // 记忆工具
+export { searchMemory } from "./search_memory.js";
 export { readMemoryAsset } from "./read_memory_asset.js";
 export { memorizeAsset } from "./memorize_asset.js";
 export { scanAndExtractPatterns } from "./scan_and_extract_patterns.js";