mcp-probe-kit 3.0.15 → 3.0.17

package/build/lib/memory-client.js

@@ -0,0 +1,293 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { getMemoryConfig, isMemoryEnabled, isMemoryReadEnabled } from './memory-config.js';
+function truncate(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+function ensureArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+}
+function numberOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function buildEmbeddingInput(input) {
+    return [
+        `name: ${input.name}`,
+        `type: ${input.type}`,
+        `description: ${input.description}`,
+        `summary: ${input.summary}`,
+        input.tags.length > 0 ? `tags: ${input.tags.join(', ')}` : '',
+        input.usage ? `usage: ${input.usage}` : '',
+        `content:\n${input.content}`,
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
+export function normalizeContentForHash(content) {
+    return content
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/g, ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function buildMemoryContentHashes(content) {
+    return {
+        contentHash: sha256Hex(content),
+        normalizedContentHash: sha256Hex(normalizeContentForHash(content)),
+    };
+}
+export class MemoryClient {
+    config;
+    constructor(config = getMemoryConfig()) {
+        this.config = config;
+    }
+    isEnabled() {
+        return isMemoryEnabled(this.config);
+    }
+    isReadEnabled() {
+        return isMemoryReadEnabled(this.config);
+    }
+    buildHeaders(includeJson = true) {
+        const headers = {};
+        if (includeJson) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (this.config.qdrantApiKey) {
+            headers['api-key'] = this.config.qdrantApiKey;
+        }
+        return headers;
+    }
+    buildEmbeddingHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.config.embeddingApiKey) {
+            headers.Authorization = `Bearer ${this.config.embeddingApiKey}`;
+        }
+        return headers;
+    }
+    async requestJson(url, init) {
+        const response = await fetch(url, init);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+        }
+        return response.json();
+    }
+    async ensureCollection(vectorSize) {
+        const url = `${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}`;
+        const exists = await fetch(url, { headers: this.buildHeaders(false) });
+        if (exists.ok) {
+            return;
+        }
+        if (exists.status !== 404) {
+            throw new Error(`Qdrant collection check failed: HTTP ${exists.status}`);
+        }
+        await this.requestJson(url, {
+            method: 'PUT',
+            headers: this.buildHeaders(),
+            body: JSON.stringify({
+                vectors: {
+                    size: vectorSize,
+                    distance: 'Cosine',
+                },
+            }),
+        });
+    }
+    async embed(text) {
+        if (!this.config.embeddingUrl) {
+            throw new Error('MEMORY_EMBEDDING_URL 未配置');
+        }
+        if (this.config.embeddingProvider === 'openai-compatible') {
+            const data = await this.requestJson(this.config.embeddingUrl, {
+                method: 'POST',
+                headers: this.buildEmbeddingHeaders(),
+                body: JSON.stringify({
+                    model: this.config.embeddingModel,
+                    input: text,
+                }),
+            });
+            const vector = data.data?.[0]?.embedding;
+            if (!vector || !Array.isArray(vector) || vector.length === 0) {
+                throw new Error('Embedding 服务未返回有效向量');
+            }
+            return vector;
+        }
+        const data = await this.requestJson(this.config.embeddingUrl, {
+            method: 'POST',
+            headers: this.buildEmbeddingHeaders(),
+            body: JSON.stringify({
+                model: this.config.embeddingModel,
+                prompt: text,
+            }),
+        });
+        if (!data.embedding || !Array.isArray(data.embedding) || data.embedding.length === 0) {
+            throw new Error('Embedding 服务未返回有效向量');
+        }
+        return data.embedding;
+    }
+    async findExistingAssetByNormalizedContentHash(normalizedContentHash) {
+        const data = await this.requestJson(`${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}/points/scroll`, {
+            method: 'POST',
+            headers: this.buildHeaders(),
+            body: JSON.stringify({
+                limit: 1,
+                with_payload: true,
+                with_vectors: false,
+                filter: {
+                    must: [
+                        {
+                            key: 'normalizedContentHash',
+                            match: {
+                                value: normalizedContentHash,
+                            },
+                        },
+                    ],
+                },
+            }),
+        });
+        const payload = data.result?.points?.[0]?.payload;
+        if (!payload) {
+            return null;
+        }
+        return {
+            id: String(payload.id || ''),
+            name: String(payload.name || ''),
+            type: String(payload.type || ''),
+            description: String(payload.description || ''),
+            summary: String(payload.summary || ''),
+            content: String(payload.content || ''),
+            tags: ensureArray(payload.tags),
+            confidence: numberOr(payload.confidence, 0.5),
+            sourceProject: typeof payload.sourceProject === 'string' ? payload.sourceProject : undefined,
+            sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
+            usage: typeof payload.usage === 'string' ? payload.usage : undefined,
+            contentHash: typeof payload.contentHash === 'string' ? payload.contentHash : undefined,
+            normalizedContentHash: typeof payload.normalizedContentHash === 'string' ? payload.normalizedContentHash : undefined,
+            createdAt: String(payload.createdAt || ''),
+            updatedAt: String(payload.updatedAt || ''),
+        };
+    }
+    async upsertAsset(input) {
+        if (!this.isEnabled()) {
+            throw new Error('记忆系统未启用');
+        }
+        const now = new Date().toISOString();
+        const hashes = buildMemoryContentHashes(input.content);
+        const asset = {
+            id: randomUUID(),
+            name: input.name,
+            type: input.type,
+            description: input.description,
+            summary: input.summary,
+            content: input.content,
+            tags: ensureArray(input.tags),
+            confidence: numberOr(input.confidence, 0.5),
+            sourceProject: input.sourceProject,
+            sourcePath: input.sourcePath,
+            usage: input.usage,
+            contentHash: hashes.contentHash,
+            normalizedContentHash: hashes.normalizedContentHash,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const vector = await this.embed(buildEmbeddingInput({
+            name: asset.name,
+            type: asset.type,
+            description: asset.description,
+            summary: asset.summary,
+            tags: asset.tags,
+            usage: asset.usage,
+            content: asset.content,
+        }));
+        await this.ensureCollection(vector.length);
+        const existing = await this.findExistingAssetByNormalizedContentHash(asset.normalizedContentHash || '');
+        if (existing) {
+            return existing;
+        }
+        await this.requestJson(`${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}/points?wait=true`, {
+            method: 'PUT',
+            headers: this.buildHeaders(),
+            body: JSON.stringify({
+                points: [
+                    {
+                        id: asset.id,
+                        vector,
+                        payload: asset,
+                    },
+                ],
+            }),
+        });
+        return asset;
+    }
+    async search(query, limit = this.config.searchLimit) {
+        if (!this.isEnabled()) {
+            return [];
+        }
+        const vector = await this.embed(query);
+        const data = await this.requestJson(`${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}/points/search`, {
+            method: 'POST',
+            headers: this.buildHeaders(),
+            body: JSON.stringify({
+                vector,
+                limit,
+                with_payload: true,
+            }),
+        });
+        return (data.result || []).map((point) => {
+            const payload = point.payload || {};
+            return {
+                id: String(point.id),
+                score: numberOr(point.score, 0),
+                name: String(payload.name || ''),
+                type: String(payload.type || ''),
+                description: String(payload.description || ''),
+                summary: truncate(String(payload.summary || ''), this.config.summaryMaxChars),
+                tags: ensureArray(payload.tags),
+                sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
+            };
+        });
+    }
+    async getAsset(assetId) {
+        if (!this.isReadEnabled()) {
+            return null;
+        }
+        const data = await this.requestJson(`${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}/points/${encodeURIComponent(assetId)}`, {
+            method: 'GET',
+            headers: this.buildHeaders(false),
+        });
+        const payload = data.result?.payload;
+        if (!payload) {
+            return null;
+        }
+        return {
+            id: String(payload.id || assetId),
+            name: String(payload.name || ''),
+            type: String(payload.type || ''),
+            description: String(payload.description || ''),
+            summary: String(payload.summary || ''),
+            content: String(payload.content || ''),
+            tags: ensureArray(payload.tags),
+            confidence: numberOr(payload.confidence, 0.5),
+            sourceProject: typeof payload.sourceProject === 'string' ? payload.sourceProject : undefined,
+            sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
+            usage: typeof payload.usage === 'string' ? payload.usage : undefined,
+            contentHash: typeof payload.contentHash === 'string' ? payload.contentHash : undefined,
+            normalizedContentHash: typeof payload.normalizedContentHash === 'string' ? payload.normalizedContentHash : undefined,
+            createdAt: String(payload.createdAt || ''),
+            updatedAt: String(payload.updatedAt || ''),
+        };
+    }
+}
+export function createMemoryClient() {
+    return new MemoryClient();
+}

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

@@ -0,0 +1,14 @@
+export interface MemoryConfig {
+    qdrantUrl: string;
+    qdrantApiKey: string;
+    qdrantCollection: string;
+    embeddingUrl: string;
+    embeddingApiKey: string;
+    embeddingModel: string;
+    embeddingProvider: 'ollama' | 'openai-compatible';
+    searchLimit: number;
+    summaryMaxChars: number;
+}
+export declare function getMemoryConfig(): MemoryConfig;
+export declare function isMemoryEnabled(config?: MemoryConfig): boolean;
+export declare function isMemoryReadEnabled(config?: MemoryConfig): boolean;

package/build/lib/memory-config.js

@@ -0,0 +1,31 @@
+function normalizeBaseUrl(value) {
+    return (value || '').trim().replace(/\/+$/, '');
+}
+function getNumberEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function getMemoryConfig() {
+    const provider = (process.env.MEMORY_EMBEDDING_PROVIDER || 'ollama').trim().toLowerCase();
+    return {
+        qdrantUrl: normalizeBaseUrl(process.env.MEMORY_QDRANT_URL),
+        qdrantApiKey: (process.env.MEMORY_QDRANT_API_KEY || '').trim(),
+        qdrantCollection: (process.env.MEMORY_QDRANT_COLLECTION || 'mcp_probe_memory').trim(),
+        embeddingUrl: normalizeBaseUrl(process.env.MEMORY_EMBEDDING_URL),
+        embeddingApiKey: (process.env.MEMORY_EMBEDDING_API_KEY || '').trim(),
+        embeddingModel: (process.env.MEMORY_EMBEDDING_MODEL || 'nomic-embed-text').trim(),
+        embeddingProvider: provider === 'openai-compatible' ? 'openai-compatible' : 'ollama',
+        searchLimit: getNumberEnv('MEMORY_SEARCH_LIMIT', 3),
+        summaryMaxChars: getNumberEnv('MEMORY_SUMMARY_MAX_CHARS', 280),
+    };
+}
+export function isMemoryEnabled(config = getMemoryConfig()) {
+    return Boolean(config.qdrantUrl && config.embeddingUrl && config.embeddingModel);
+}
+export function isMemoryReadEnabled(config = getMemoryConfig()) {
+    return Boolean(config.qdrantUrl);
+}

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

@@ -0,0 +1,26 @@
+import type { MemorySearchResult } from './memory-client.js';
+export interface MemoryInjectionContext {
+    enabled: boolean;
+    available: boolean;
+    degraded: boolean;
+    query: string;
+    results: MemorySearchResult[];
+    error?: string;
+}
+export declare function loadMemoryInjectionContext(query: string): Promise<MemoryInjectionContext>;
+export declare function renderMemoryGuideSection(context: MemoryInjectionContext): string;
+export declare function buildMemoryPlanStep(): {
+    id: string;
+    tool: string;
+    when: string;
+    args: {
+        name: string;
+        type: string;
+        description: string;
+        summary: string;
+        content: string;
+        usage: string;
+        confidence: number;
+    };
+    outputs: never[];
+};

package/build/lib/memory-orchestration.js

@@ -0,0 +1,65 @@
+import { createMemoryClient } from './memory-client.js';
+export async function loadMemoryInjectionContext(query) {
+    const client = createMemoryClient();
+    if (!client.isEnabled()) {
+        return {
+            enabled: false,
+            available: false,
+            degraded: false,
+            query,
+            results: [],
+        };
+    }
+    try {
+        const results = await client.search(query);
+        return {
+            enabled: true,
+            available: true,
+            degraded: false,
+            query,
+            results,
+        };
+    }
+    catch (error) {
+        return {
+            enabled: true,
+            available: false,
+            degraded: true,
+            query,
+            results: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function renderMemoryGuideSection(context) {
+    if (!context.enabled) {
+        return '';
+    }
+    if (!context.available) {
+        return `\n\n## 🧠 记忆系统\n- 状态: 已配置但本次检索降级\n- 原因: ${context.error || '未知错误'}\n- 处理: 忽略记忆注入，继续主流程\n`;
+    }
+    if (context.results.length === 0) {
+        return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 检索结果: 未找到高相关历史资产\n- 处理: 继续主流程；若本次产出存在高价值通用资产，结束后调用 \`memorize_asset\` 沉淀\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}` : ''}`)
+        .join('\n');
+    return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 指令: 优先复用以下历史成功经验；如果某条相关，再用 \`read_memory_asset\` 拉取完整内容，不要直接重写\n- 检索结果:\n${items}\n`;
+}
+export function buildMemoryPlanStep() {
+    return {
+        id: 'memorize',
+        tool: 'memorize_asset',
+        when: '本次实现完成且确认存在可复用资产',
+        args: {
+            name: '[资产名称]',
+            type: 'code',
+            description: '[该资产解决了什么问题]',
+            summary: '[用于后续检索的简洁摘要]',
+            content: '[可复用代码或规范内容]',
+            usage: '[适用场景与限制]',
+            confidence: 0.7,
+        },
+        outputs: [],
+    };
+}

package/build/lib/project-detector.js

@@ -8,6 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { resolveWorkspaceRoot } from './workspace-root.js';
 // 检测规则配置
 const detectionRules = {
     javascript: {
@@ -116,7 +117,8 @@ const detectionRules = {
 /**
  * 检测项目类型
  */
-export function detectProjectType(projectRoot = process.cwd()) {
+export function detectProjectType(projectRoot) {
+    const resolvedProjectRoot = resolveWorkspaceRoot(projectRoot);
     const indicators = [];
     let detectedLanguage = 'unknown';
     let detectedFramework;
@@ -126,7 +128,7 @@ export function detectProjectType(projectRoot = process.cwd()) {
     for (const [language, rule] of Object.entries(detectionRules)) {
         // 检查语言特征文件是否存在
         const languageIndicator = rule.indicators.find(indicator => {
-            const filePath = path.join(projectRoot, indicator);
+            const filePath = path.join(resolvedProjectRoot, indicator);
             return fs.existsSync(filePath);
         });
         if (languageIndicator) {
@@ -134,7 +136,7 @@ export function detectProjectType(projectRoot = process.cwd()) {
             indicators.push(languageIndicator);
             confidence = 50; // 基础置信度
             // 检测框架
-            const frameworkResult = detectFramework(projectRoot, language, rule);
+            const frameworkResult = detectFramework(resolvedProjectRoot, language, rule);
             if (frameworkResult) {
                 detectedFramework = frameworkResult.framework;
                 detectedCategory = frameworkResult.category;
@@ -146,7 +148,7 @@ export function detectProjectType(projectRoot = process.cwd()) {
     }
     // 如果没有检测到语言，尝试通过文件扩展名判断
     if (detectedLanguage === 'unknown') {
-        const languageByExtension = detectLanguageByExtension(projectRoot);
+        const languageByExtension = detectLanguageByExtension(resolvedProjectRoot);
         if (languageByExtension) {
             detectedLanguage = languageByExtension.language;
             confidence = languageByExtension.confidence;

package/build/lib/skill-bridge.d.ts

@@ -0,0 +1,31 @@
+export type SkillBridgeWorkflow = "start_ui" | "start_product";
+export interface SkillBridgeItem {
+    name: string;
+    role: string;
+    installed: boolean;
+    skillPath?: string;
+    expectedPaths: string[];
+}
+export interface SkillBridgeStatus {
+    workflow: SkillBridgeWorkflow;
+    generatedAt: string;
+    installedCount: number;
+    missingCount: number;
+    ready: boolean;
+    skills: SkillBridgeItem[];
+}
+export declare function detectSkillBridge(workflow: SkillBridgeWorkflow): SkillBridgeStatus;
+export declare function buildSkillHeaderNote(status: SkillBridgeStatus): string;
+export declare function buildSkillBridgePlanStep(status: SkillBridgeStatus): {
+    id: string;
+    tool: string;
+    action: string;
+    when: string;
+    args: {
+        order: string[];
+        available: string[];
+        missing: string[];
+    };
+    outputs: never[];
+};
+export declare function renderSkillBridgeSection(status: SkillBridgeStatus): string;

package/build/lib/skill-bridge.js

@@ -0,0 +1,100 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const SKILL_DEFINITIONS = [
+    {
+        name: "ui-ux-pro-max",
+        role: "设计系统与风格策略推荐",
+        appliesTo: ["start_ui", "start_product"],
+    },
+    {
+        name: "interaction-design",
+        role: "交互状态与流程约束",
+        appliesTo: ["start_ui", "start_product"],
+    },
+    {
+        name: "frontend-design",
+        role: "前端视觉与代码实现增强",
+        appliesTo: ["start_ui", "start_product"],
+    },
+];
+function buildSkillRoots() {
+    const fromEnv = (process.env.MCP_SKILLS_ROOTS || "")
+        .split(path.delimiter)
+        .map((item) => item.trim())
+        .filter(Boolean);
+    const home = os.homedir();
+    const defaults = [
+        path.join(home, ".agents", "skills"),
+        path.join(home, ".codex", "skills"),
+        path.join(home, ".codex", "skills", ".system"),
+    ];
+    return Array.from(new Set([...fromEnv, ...defaults]));
+}
+function resolveSkill(name, roots) {
+    const expectedPaths = roots.map((root) => path.join(root, name, "SKILL.md"));
+    const installedPath = expectedPaths.find((candidate) => fs.existsSync(candidate));
+    return {
+        name,
+        role: SKILL_DEFINITIONS.find((item) => item.name === name)?.role || "",
+        installed: Boolean(installedPath),
+        skillPath: installedPath,
+        expectedPaths,
+    };
+}
+export function detectSkillBridge(workflow) {
+    const roots = buildSkillRoots();
+    const selected = SKILL_DEFINITIONS.filter((item) => item.appliesTo.includes(workflow));
+    const skills = selected.map((item) => resolveSkill(item.name, roots));
+    const installedCount = skills.filter((item) => item.installed).length;
+    const missingCount = skills.length - installedCount;
+    return {
+        workflow,
+        generatedAt: new Date().toISOString(),
+        installedCount,
+        missingCount,
+        ready: missingCount === 0,
+        skills,
+    };
+}
+export function buildSkillHeaderNote(status) {
+    return `Skill Bridge: ${status.installedCount}/${status.skills.length} 可用`;
+}
+export function buildSkillBridgePlanStep(status) {
+    return {
+        id: "skill-bridge",
+        tool: "manual",
+        action: "invoke_skills",
+        when: "在宿主支持 skill 调用时优先执行",
+        args: {
+            order: status.skills.map((item) => item.name),
+            available: status.skills.filter((item) => item.installed).map((item) => item.name),
+            missing: status.skills.filter((item) => !item.installed).map((item) => item.name),
+        },
+        outputs: [],
+    };
+}
+export function renderSkillBridgeSection(status) {
+    const orderLines = status.skills
+        .map((item, index) => `${index + 1}. \`${item.name}\` - ${item.role}`)
+        .join("\n");
+    const stateLines = status.skills
+        .map((item) => `- ${item.name}: ${item.installed ? `已安装（${item.skillPath}）` : "未安装"}`)
+        .join("\n");
+    const conclusion = status.ready
+        ? "全部 skill 可用，建议按顺序调用后再执行 MCP 工具步骤。"
+        : "部分 skill 缺失：继续执行 MCP 主流程，不阻塞；安装缺失 skill 后下次运行可获得更高质量输出。";
+    return `## 🧩 Skill Bridge（UI/PRD 增强）
+
+按顺序调用（宿主支持时）：
+${orderLines}
+
+当前状态：
+${stateLines}
+
+${conclusion}
+
+---
+
+`;
+}

package/build/lib/workspace-root.d.ts

@@ -0,0 +1,12 @@
+export declare function isLikelyProjectNamedRelativePath(inputPath?: string): boolean;
+export declare function buildProjectRootRetryHint(inputPath?: string): {
+    preferred: {
+        project_root: string;
+        path: string;
+    };
+    fallback: {
+        project_root: string;
+    };
+};
+export declare function resolveWorkspaceRoot(explicitProjectRoot?: string): string;
+export declare function toWorkspacePath(explicitProjectRoot?: string): string;