mcp-probe-kit 3.0.17 → 3.0.19

package/README.md

@@ -1,3 +1,5 @@
+# mcp-probe-kit — Know the Context, Feed the Moment
+
 <div align="center">
   <img src="docs/assets/logo.png" alt="知时MCP Logo" width="160"/>
   <h1>知时MCP | mcp-probe-kit</h1>
@@ -39,6 +41,7 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
 **👉 [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)**
 
 - [Quick Start](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html) - Setup in 5 minutes
+- [Local Memory Stack (Qdrant + Nomic Embed)](docs/memory-local-setup.md) - Docker Compose, ports `50008` / `50012`, MCP env
 - [All Tools](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - Complete list of 28 tools
 - [Best Practices](https://mcp-probe-kit.bytezonex.com/pages/examples.html) - Full development workflow guide
 - [v3.0 Migration Guide](https://mcp-probe-kit.bytezonex.com/pages/migration.html) - Upgrade from v2.x to v3.0
@@ -103,10 +106,10 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
 
 **Memory backend and embedding configuration:**
 - Vector database: **Qdrant**
-- Recommended local setup: `Qdrant + Ollama`
+- **Recommended local setup:** `Qdrant (port 50008) + Infinity / nomic-embed (port 50012)` — lighter than Ollama; see **[Local Memory Stack guide](docs/memory-local-setup.md)** (中文: [memory-local-setup.zh-CN.md](docs/memory-local-setup.zh-CN.md))
 - Supported embedding providers:
   - `ollama`
-  - `openai-compatible`
+  - `openai-compatible` (Infinity, OpenAI, etc.)
 - Required environment variables for memory write/search:
   - `MEMORY_QDRANT_URL`
   - `MEMORY_EMBEDDING_URL`
@@ -123,11 +126,9 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
   - Memory write is enabled only when `MEMORY_QDRANT_URL`, `MEMORY_EMBEDDING_URL`, and `MEMORY_EMBEDDING_MODEL` are all configured
   - The Qdrant collection is auto-created on first write, and vector dimension is inferred from the first embedding response
 
-**Recommended local memory setup (Qdrant + Ollama):**
-```bash
-docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
-ollama pull nomic-embed-text
-```
+**Recommended local memory setup (Qdrant + Nomic Embed / Infinity):**
+
+Full Docker Compose, ports, and troubleshooting: **[docs/memory-local-setup.md](docs/memory-local-setup.md)**
 
 ```json
 {
@@ -136,11 +137,13 @@ ollama pull nomic-embed-text
       "command": "npx",
       "args": ["-y", "mcp-probe-kit@latest"],
       "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
         "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_EMBEDDING_PROVIDER": "ollama",
-        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
-        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
         "MEMORY_SEARCH_LIMIT": "3",
         "MEMORY_SUMMARY_MAX_CHARS": "280"
       }
@@ -149,7 +152,21 @@ ollama pull nomic-embed-text
 }
 ```
 
-**OpenAI-compatible embedding setup:**
+**Alternative: Qdrant + Ollama** (if you already run Ollama):
+
+```bash
+docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text
+```
+
+```json
+"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+"MEMORY_EMBEDDING_PROVIDER": "ollama",
+"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"
+```
+
+**OpenAI-compatible embedding (hosted API):**
 ```json
 {
   "mcpServers": {
@@ -414,6 +431,27 @@ No installation needed, use the latest version directly.
 }
 ```
 
+#### OpenCode Configuration
+
+**Config file location:**
+- Project-level: `opencode.json` (in project root)
+- Global: `~/.config/opencode/opencode.json`
+
+**Config content:**
+```json
+{
+  "mcp": {
+    "mcp-probe-kit": {
+      "type": "local",
+      "command": ["npx", "-y", "mcp-probe-kit@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> **Note:** OpenCode uses `opencode.json` with a different schema from Cursor/Claude Desktop. The key `mcp` replaces `mcpServers`, `command` is an array, `type: "local"` is required, and environment variables use `environment` instead of `env`. See [OpenCode MCP docs](https://opencode.ai/docs/mcp) for details.
+
 ### Method 2: Global Installation
 
 ```bash
@@ -438,21 +476,14 @@ If you want to use `memorize_asset`, `read_memory_asset`, and `scan_and_extract_
 1. A **Qdrant** vector database
 2. An **embedding service** in either `ollama` or `openai-compatible` mode
 
-#### Option A: Qdrant + Ollama
+**Full guide (Docker Compose for Qdrant + Infinity, ports `50008` / `50012`, MCP env, smoke tests):**
 
-Start Qdrant with Docker:
+- English: [docs/memory-local-setup.md](docs/memory-local-setup.md)
+- 中文: [docs/memory-local-setup.zh-CN.md](docs/memory-local-setup.zh-CN.md)
 
-```bash
-docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
-```
-
-Start Ollama and pull the default embedding model:
-
-```bash
-ollama pull nomic-embed-text
-```
+#### Option A: Qdrant + Nomic Embed / Infinity (recommended)
 
-Recommended MCP config env:
+Lightweight local stack; no Ollama. Deploy Qdrant and `nomic-embed` via Docker Compose (see guide), then:
 
 ```json
 {
@@ -461,11 +492,13 @@ Recommended MCP config env:
       "command": "npx",
       "args": ["-y", "mcp-probe-kit@latest"],
       "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
         "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_EMBEDDING_PROVIDER": "ollama",
-        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
-        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
         "MEMORY_SEARCH_LIMIT": "3",
         "MEMORY_SUMMARY_MAX_CHARS": "280"
       }
@@ -474,36 +507,30 @@ Recommended MCP config env:
 }
 ```
 
-#### Option B: Qdrant + OpenAI-Compatible Embedding API
+> Embedding URL must be `/embeddings` (not `/v1/embeddings`). Qdrant requires `api-key` when `QDRANT__SERVICE__API_KEY` is set.
 
-Start Qdrant with Docker:
+#### Option B: Qdrant + Ollama
 
 ```bash
 docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text
+```
+
+```json
+"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+"MEMORY_EMBEDDING_PROVIDER": "ollama",
+"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"
 ```
 
-Then point the embedding config to an OpenAI-compatible `/embeddings` endpoint:
+#### Option C: Qdrant + hosted OpenAI-compatible API
 
 ```json
-{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "npx",
-      "args": ["-y", "mcp-probe-kit@latest"],
-      "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
-        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_QDRANT_API_KEY": "",
-        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
-        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
-        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
-        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small",
-        "MEMORY_SEARCH_LIMIT": "3",
-        "MEMORY_SUMMARY_MAX_CHARS": "280"
-      }
-    }
-  }
-}
+"MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+"MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+"MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
+"MEMORY_EMBEDDING_API_KEY": "your-api-key",
+"MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"
 ```
 
 #### Memory Environment Variables

package/build/lib/__tests__/agents-md-template.unit.test.d.ts

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

package/build/lib/__tests__/agents-md-template.unit.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { generateAgentsMdInner } from '../agents-md-template.js';
+import { resolveProjectContextLayout } from '../project-context-layout.js';
+const layout = resolveProjectContextLayout(process.cwd());
+const baseInput = {
+    layout,
+    locale: 'zh-CN',
+    projectName: 'demo',
+    projectVersion: '1.0.0',
+    description: 'test',
+    language: 'TypeScript',
+    category: 'library',
+    docs: [],
+    projectRootPosix: '/repo',
+    graphReady: false,
+};
+describe('generateAgentsMdInner', () => {
+    it('includes memory workflow in zh-CN template', () => {
+        const md = generateAgentsMdInner({ ...baseInput });
+        expect(md).toContain('记忆');
+        expect(md).toContain('start_bugfix');
+        expect(md).toContain('memorize_asset');
+        expect(md).toContain('bugfix');
+    });
+});

package/build/lib/__tests__/project-context-layout.unit.test.d.ts

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

package/build/lib/__tests__/project-context-layout.unit.test.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { detectDocumentLocale, discoverProjectRootFromLayout, layoutAbsPath, readLayoutManifest, relativeLink, resolveProjectContextLayout, writeLayoutManifest, } from "../project-context-layout.js";
+import { mergeAgentsMdBlock } from "../merge-agents-md.js";
+describe("project-context-layout", () => {
+    test("relativeLink from AGENTS.md to docs paths", () => {
+        const link = relativeLink("AGENTS.md", "docs/project-context/tech-stack.md");
+        expect(link === "docs/project-context/tech-stack.md" || link === "./docs/project-context/tech-stack.md").toBe(true);
+    });
+    test("default layout uses AGENTS.md and docs/", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-"));
+        const layout = resolveProjectContextLayout(root, {});
+        expect(layout.indexPath).toBe("AGENTS.md");
+        expect(layout.contextRoot).toBe("docs");
+        expect(layout.modularDir).toBe("docs/project-context");
+        expect(layout.latestMarkdownPath).toBe("docs/graph-insights/latest.md");
+    });
+    test("writeLayoutManifest is portable (no absolute projectRoot)", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-manifest-"));
+        const layout = resolveProjectContextLayout(root, {});
+        const rel = writeLayoutManifest(root, layout);
+        expect(rel).toBe("docs/.mcp-probe/layout.json");
+        const manifest = readLayoutManifest(root);
+        expect(manifest?.indexPath).toBe("AGENTS.md");
+        expect(manifest?.projectRoot).toBeUndefined();
+        expect(manifest?.projectRootEnv).toBe("MCP_PROJECT_ROOT");
+        expect(discoverProjectRootFromLayout(root)).toBe(path.resolve(root));
+    });
+    test("ignores stale absolute projectRoot in manifest", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-stale-root-"));
+        const layout = resolveProjectContextLayout(root, {});
+        writeLayoutManifest(root, layout);
+        const manifestPath = path.join(root, "docs", ".mcp-probe", "layout.json");
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        manifest.projectRoot = "Z:/nonexistent/wrong-root";
+        fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        expect(discoverProjectRootFromLayout(path.join(root, "src"))).toBe(path.resolve(root));
+    });
+    test("infers root for custom contextRoot manifest path", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-custom-docs-"));
+        const layout = resolveProjectContextLayout(root, { docs_dir: "documentation" });
+        writeLayoutManifest(root, layout);
+        expect(fs.existsSync(path.join(root, "documentation", ".mcp-probe", "layout.json"))).toBe(true);
+        const fromSub = resolveProjectContextLayout(path.join(root, "src"), {});
+        expect(fromSub.projectRoot).toBe(path.resolve(root));
+        expect(fromSub.contextRoot).toBe("documentation");
+    });
+    test("discovers projectRoot from layout.json when cwd is subdirectory", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-discover-"));
+        const layout = resolveProjectContextLayout(root, {});
+        writeLayoutManifest(root, layout);
+        const subDir = path.join(root, "src", "tools");
+        fs.mkdirSync(subDir, { recursive: true });
+        expect(discoverProjectRootFromLayout(subDir)).toBe(path.resolve(root));
+        const fromSub = resolveProjectContextLayout(subDir, {});
+        expect(fromSub.projectRoot).toBe(path.resolve(root));
+        expect(layoutAbsPath(fromSub, "docs/project-context.md")).toBe(path.join(root, "docs", "project-context.md"));
+    });
+    test("detectDocumentLocale zh from README", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-zh-"));
+        fs.writeFileSync(path.join(root, "README.md"), "# 测试项目\n\n这是一个中文项目说明，用于单元测试。\n".repeat(5), "utf8");
+        expect(detectDocumentLocale(root)).toBe("zh-CN");
+    });
+});
+describe("mergeAgentsMdBlock", () => {
+    test("prepends block when no marker exists", () => {
+        const { content, mergeMode } = mergeAgentsMdBlock("# User rules\n", "## MCP block");
+        expect(mergeMode).toBe("prepended");
+        expect(content.startsWith("<!-- mcp-probe:context begin")).toBe(true);
+        expect(content).toContain("# User rules");
+    });
+    test("replaces and moves block to top", () => {
+        const existing = "# Footer\n\n<!-- mcp-probe:context begin -->\nold\n<!-- mcp-probe:context end -->\n";
+        const { content, mergeMode } = mergeAgentsMdBlock(existing, "new inner");
+        expect(mergeMode).toBe("replaced-and-moved-to-top");
+        expect(content.indexOf("new inner")).toBeLessThan(content.indexOf("# Footer"));
+    });
+});

package/build/lib/agents-md-template.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentLocale, ProjectContextLayout } from "./project-context-layout.js";
+export interface AgentsMdTemplateInput {
+    layout: ProjectContextLayout;
+    locale: DocumentLocale;
+    projectName: string;
+    projectVersion: string;
+    description: string;
+    language: string;
+    framework?: string;
+    category: string;
+    docs: Array<{
+        file: string;
+        title: string;
+        purpose: string;
+    }>;
+    projectRootPosix: string;
+    graphReady: boolean;
+    /** @deprecated kept for callers; memory rules are always included in AGENTS.md */
+    memoryEnabled?: boolean;
+}
+/**
+ * Ultra-compact AGENTS.md body (inside mcp-probe block).
+ */
+export declare function generateAgentsMdInner(input: AgentsMdTemplateInput): string;
+export declare function generateAgentsMdTemplate(input: AgentsMdTemplateInput): string;

package/build/lib/agents-md-template.js

@@ -0,0 +1,55 @@
+import { relativeLink } from "./project-context-layout.js";
+function link(layout, targetRel) {
+    return relativeLink(layout.indexPath, targetRel);
+}
+function memorySection(locale) {
+    if (locale === "zh-CN") {
+        return `
+记忆（需 MEMORY_QDRANT_URL 等已配置）：
+- 检索：\`start_feature\` / \`start_bugfix\` / \`start_ui\` 会自动搜记忆；命中后用 \`read_memory_asset\` 读全文再动手
+- Bug 修完验证通过后 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（现象+根因+改法）
+- 功能/UI 有可复用产出 → \`memorize_asset\` type=\`pattern\`/\`component\``;
+    }
+    return `
+Memory (requires MEMORY_* env):
+- Search: \`start_feature\` / \`start_bugfix\` / \`start_ui\` auto-search; use \`read_memory_asset\` on hits before coding
+- After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\` (symptom + root cause + fix)
+- Reusable feature/UI → \`memorize_asset\` type=\`pattern\`/\`component\``;
+}
+/**
+ * Ultra-compact AGENTS.md body (inside mcp-probe block).
+ */
+export function generateAgentsMdInner(input) {
+    const { layout, locale } = input;
+    const graph = link(layout, layout.latestMarkdownPath);
+    const ctxIndex = link(layout, layout.legacyIndexPath);
+    if (locale === "zh-CN") {
+        return `## MCP（必须先调）
+需已配置 mcp-probe-kit。\`start_*\` 若返回 delegated plan，逐步执行完再结束。
+
+- 新功能 → \`start_feature\`（会先搜记忆）
+- Bug → \`start_bugfix\`（会先搜记忆）
+- UI → \`start_ui\`（会先搜记忆）
+- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
+- 缺上下文 → \`init_project_context\`
+- 提交 → \`gencommit\`
+
+上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
+图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+    }
+    return `## MCP (call first)
+Requires mcp-probe-kit. Complete every \`start_*\` delegated plan step before done.
+
+- Feature → \`start_feature\` (searches memory first)
+- Bug → \`start_bugfix\` (searches memory first)
+- UI → \`start_ui\` (searches memory first)
+- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
+- Missing context → \`init_project_context\`
+- Commit → \`gencommit\`
+
+Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
+Graph: read [latest](${graph}) before large changes; refresh \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+}
+export function generateAgentsMdTemplate(input) {
+    return generateAgentsMdInner(input);
+}

package/build/lib/memory-orchestration.d.ts

@@ -1,4 +1,5 @@
 import type { MemorySearchResult } from './memory-client.js';
+export type MemoryPlanKind = 'feature' | 'bugfix' | 'ui' | 'default';
 export interface MemoryInjectionContext {
     enabled: boolean;
     available: boolean;
@@ -9,7 +10,7 @@ export interface MemoryInjectionContext {
 }
 export declare function loadMemoryInjectionContext(query: string): Promise<MemoryInjectionContext>;
 export declare function renderMemoryGuideSection(context: MemoryInjectionContext): string;
-export declare function buildMemoryPlanStep(): {
+export declare function buildMemoryPlanStep(kind?: MemoryPlanKind): {
     id: string;
     tool: string;
     when: string;
@@ -20,6 +21,7 @@ export declare function buildMemoryPlanStep(): {
         summary: string;
         content: string;
         usage: string;
+        tags: string[];
         confidence: number;
     };
     outputs: never[];

package/build/lib/memory-orchestration.js

@@ -31,6 +31,14 @@ export async function loadMemoryInjectionContext(query) {
         };
     }
 }
+function formatMemoryResultLabel(item) {
+    const kind = item.type === 'bugfix' || item.tags.includes('bugfix')
+        ? '历史 Bug 修复'
+        : item.type === 'pattern' || item.type === 'component'
+            ? '可复用模式'
+            : '历史资产';
+    return `${item.name} [${item.type}] (${kind})`;
+}
 export function renderMemoryGuideSection(context) {
     if (!context.enabled) {
         return '';
@@ -39,25 +47,83 @@ export function renderMemoryGuideSection(context) {
         return `\n\n## 🧠 记忆系统\n- 状态: 已配置但本次检索降级\n- 原因: ${context.error || '未知错误'}\n- 处理: 忽略记忆注入，继续主流程\n`;
     }
     if (context.results.length === 0) {
-        return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 检索结果: 未找到高相关历史资产\n- 处理: 继续主流程；若本次产出存在高价值通用资产，结束后调用 \`memorize_asset\` 沉淀\n`;
+        return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 检索结果: 未找到高相关记录（含历史 Bug 修复与可复用模式）\n- 处理: 继续主流程；Bug 修复验证通过后必须 \`memorize_asset\` 沉淀；功能/UI 有可复用产出再沉淀\n`;
     }
     const items = context.results
-        .map((item, index) => `${index + 1}. ${item.name} [${item.type}] score=${item.score.toFixed(3)}\n   - 摘要: ${item.summary}\n   - 读取: read_memory_asset {\"asset_id\": \"${item.id}\"}${item.sourcePath ? `\n   - 来源: ${item.sourcePath}` : ''}`)
+        .map((item, index) => {
+        const label = formatMemoryResultLabel(item);
+        return `${index + 1}. ${label} score=${item.score.toFixed(3)}\n   - 摘要: ${item.summary}\n   - 读取: read_memory_asset {\"asset_id\": \"${item.id}\"}${item.sourcePath ? `\n   - 来源: ${item.sourcePath}` : ''}`;
+    })
         .join('\n');
-    return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 指令: 优先复用以下历史成功经验；如果某条相关，再用 \`read_memory_asset\` 拉取完整内容，不要直接重写\n- 检索结果:\n${items}\n`;
+    return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 指令: 开干前先复用下列记录（含历史 Bug 现象/根因/改法）；相关条目用 \`read_memory_asset\` 读全文，避免重复踩坑\n- 检索结果:\n${items}\n`;
 }
-export function buildMemoryPlanStep() {
+export function buildMemoryPlanStep(kind = 'default') {
+    if (kind === 'bugfix') {
+        return {
+            id: 'memorize-bugfix',
+            tool: 'memorize_asset',
+            when: 'Bug 已修复且验证通过后（必须沉淀，便于下次同类问题检索）',
+            args: {
+                name: '[问题简述，如 登录超时-Redis连接池]',
+                type: 'bugfix',
+                description: '[现象、报错信息、复现条件]',
+                summary: '[检索用：关键词 + 根因 + 修复要点，一句话]',
+                content: '【现象】...\n【根因】...\n【修复】具体改动文件与关键代码/配置\n【验证】如何确认已修好',
+                usage: '[再次遇到何种症状时可参考]',
+                tags: ['bugfix', 'root-cause'],
+                confidence: 0.85,
+            },
+            outputs: [],
+        };
+    }
+    if (kind === 'ui') {
+        return {
+            id: 'memorize-ui',
+            tool: 'memorize_asset',
+            when: 'UI 实现完成且存在可复用组件/布局/交互模式',
+            args: {
+                name: '[UI 资产名称]',
+                type: 'component',
+                description: '[该 UI 模式解决什么问题]',
+                summary: '[检索用摘要]',
+                content: '[组件结构、样式约定或可复用片段]',
+                usage: '[适用页面/场景]',
+                tags: ['ui', 'pattern'],
+                confidence: 0.75,
+            },
+            outputs: [],
+        };
+    }
+    if (kind === 'feature') {
+        return {
+            id: 'memorize-feature',
+            tool: 'memorize_asset',
+            when: '功能完成且存在可复用实现/规范',
+            args: {
+                name: '[功能/模式名称]',
+                type: 'pattern',
+                description: '[该资产解决什么问题]',
+                summary: '[检索用摘要]',
+                content: '[可复用代码或流程]',
+                usage: '[适用场景与限制]',
+                tags: ['feature', 'pattern'],
+                confidence: 0.75,
+            },
+            outputs: [],
+        };
+    }
     return {
         id: 'memorize',
         tool: 'memorize_asset',
         when: '本次实现完成且确认存在可复用资产',
         args: {
             name: '[资产名称]',
-            type: 'code',
+            type: 'pattern',
             description: '[该资产解决了什么问题]',
             summary: '[用于后续检索的简洁摘要]',
             content: '[可复用代码或规范内容]',
             usage: '[适用场景与限制]',
+            tags: ['pattern'],
             confidence: 0.7,
         },
         outputs: [],

package/build/lib/merge-agents-md.d.ts

@@ -0,0 +1,6 @@
+export type AgentsMdMergeMode = "created" | "prepended" | "replaced-and-moved-to-top" | "skipped-empty";
+export declare function wrapMcpProbeBlock(innerMarkdown: string): string;
+export declare function mergeAgentsMdBlock(existingContent: string | null | undefined, generatedInner: string): {
+    content: string;
+    mergeMode: AgentsMdMergeMode;
+};

package/build/lib/merge-agents-md.js

@@ -0,0 +1,51 @@
+const BLOCK_BEGIN = "<!-- mcp-probe:context begin — auto-generated; re-run init_project_context updates this block only -->";
+const BLOCK_END = "<!-- mcp-probe:context end -->";
+export function wrapMcpProbeBlock(innerMarkdown) {
+    return `${BLOCK_BEGIN}\n${innerMarkdown.trim()}\n${BLOCK_END}`;
+}
+function stripExistingBlock(content) {
+    const beginIdx = content.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        const legacyBegin = content.indexOf("<!-- mcp-probe:context begin");
+        if (legacyBegin === -1) {
+            return content.trim();
+        }
+        const legacyEnd = content.indexOf(BLOCK_END);
+        if (legacyEnd === -1) {
+            return content.trim();
+        }
+        const legacyLineEnd = content.indexOf("-->", legacyBegin);
+        const blockStart = legacyLineEnd === -1 ? legacyBegin : legacyLineEnd + 3;
+        const before = content.slice(0, legacyBegin).trimEnd();
+        const after = content.slice(legacyEnd + BLOCK_END.length).trimStart();
+        return [before, after].filter(Boolean).join("\n\n").trim();
+    }
+    const endIdx = content.indexOf(BLOCK_END);
+    if (endIdx === -1) {
+        return content.trim();
+    }
+    const before = content.slice(0, beginIdx).trimEnd();
+    const after = content.slice(endIdx + BLOCK_END.length).trimStart();
+    return [before, after].filter(Boolean).join("\n\n").trim();
+}
+export function mergeAgentsMdBlock(existingContent, generatedInner) {
+    const block = wrapMcpProbeBlock(generatedInner);
+    if (!existingContent?.trim()) {
+        return { content: `${block}\n`, mergeMode: "created" };
+    }
+    const userBody = stripExistingBlock(existingContent);
+    const hadBlock = existingContent.includes(BLOCK_BEGIN) || existingContent.includes("<!-- mcp-probe:context begin");
+    if (!userBody) {
+        return { content: `${block}\n`, mergeMode: hadBlock ? "replaced-and-moved-to-top" : "created" };
+    }
+    if (!hadBlock) {
+        return {
+            content: `${block}\n\n${userBody}\n`,
+            mergeMode: "prepended",
+        };
+    }
+    return {
+        content: `${block}\n\n${userBody}\n`,
+        mergeMode: "replaced-and-moved-to-top",
+    };
+}