mcp-probe-kit 3.6.0 → 3.6.2

package/build/lib/__tests__/project-mcp-resources.unit.test.js

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { PROJECT_BOOTSTRAP_URI, ensureAndDiscoverProjectResources, readProjectResourceContent, } from "../project-mcp-resources.js";
+import { MCP_PROBE_SKILL_REL_PATH } from "../workflow-skill-template.js";
+function withTempProject(run) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-proj-res-"));
+    try {
+        run(root);
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
+describe("project-mcp-resources", () => {
+    const prevEnv = { ...process.env };
+    afterEach(() => {
+        process.env = { ...prevEnv };
+    });
+    test("ensureAndDiscoverProjectResources auto-creates skill and agents", () => {
+        withTempProject((root) => {
+            const snapshot = ensureAndDiscoverProjectResources(root);
+            expect(snapshot.bootstrap.skill.created).toBe(true);
+            expect(snapshot.bootstrap.agentsMd.created).toBe(true);
+            expect(fs.existsSync(path.join(root, MCP_PROBE_SKILL_REL_PATH))).toBe(true);
+            expect(fs.existsSync(path.join(root, "AGENTS.md"))).toBe(true);
+            const skill = snapshot.resources.find((item) => item.id === "skill");
+            expect(skill?.exists).toBe(true);
+        });
+    });
+    test("readProjectResourceContent returns bootstrap catalog", () => {
+        withTempProject((root) => {
+            const content = readProjectResourceContent(PROJECT_BOOTSTRAP_URI, root);
+            expect(content?.mimeType).toBe("application/json");
+            const payload = JSON.parse(content?.text ?? "{}");
+            expect(payload.autoBootstrap.skill.path).toBe(MCP_PROBE_SKILL_REL_PATH);
+            expect(Array.isArray(payload.resources)).toBe(true);
+        });
+    });
+    test("readProjectResourceContent reads skill markdown", () => {
+        withTempProject((root) => {
+            ensureAndDiscoverProjectResources(root);
+            const content = readProjectResourceContent("probe://project/skill", root);
+            expect(content?.mimeType).toBe("text/markdown");
+            expect(content?.text).toContain("mcp-probe-kit-skill-version");
+        });
+    });
+});

package/build/lib/__tests__/workspace-root.unit.test.d.ts

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

package/build/lib/__tests__/workspace-root.unit.test.js

@@ -0,0 +1,63 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { resolveFromWorkspaceFolderPathsEnv, resolveWorkspaceRoot, resolveWorkspaceRootWithMeta, } from "../workspace-root.js";
+const original = process.env.WORKSPACE_FOLDER_PATHS;
+const tempDirs = [];
+afterEach(() => {
+    if (original === undefined) {
+        delete process.env.WORKSPACE_FOLDER_PATHS;
+    }
+    else {
+        process.env.WORKSPACE_FOLDER_PATHS = original;
+    }
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("workspace-root WORKSPACE_FOLDER_PATHS", () => {
+    test("解析 JSON 数组形式", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "ws-"));
+        tempDirs.push(root);
+        fs.writeFileSync(path.join(root, "package.json"), "{}", "utf8");
+        process.env.WORKSPACE_FOLDER_PATHS = JSON.stringify([root]);
+        expect(resolveFromWorkspaceFolderPathsEnv()).toBe(path.resolve(root));
+        expect(resolveWorkspaceRoot("")).toBe(path.resolve(root));
+    });
+    test("客户端工作区路径不向父级 layout 上爬", () => {
+        const parent = fs.mkdtempSync(path.join(os.tmpdir(), "ws-parent-"));
+        const child = path.join(parent, "my-app");
+        tempDirs.push(parent);
+        fs.mkdirSync(child, { recursive: true });
+        fs.writeFileSync(path.join(child, "package.json"), "{}", "utf8");
+        fs.mkdirSync(path.join(parent, "docs", ".mcp-probe"), { recursive: true });
+        fs.writeFileSync(path.join(parent, "docs", ".mcp-probe", "layout.json"), JSON.stringify({ version: 1, indexPath: "AGENTS.md", contextRoot: "docs" }), "utf8");
+        process.env.WORKSPACE_FOLDER_PATHS = JSON.stringify([child]);
+        const resolution = resolveWorkspaceRootWithMeta("");
+        expect(resolution.root).toBe(path.resolve(child));
+        expect(resolution.source).toBe("workspace-env");
+    });
+});
+describe("workspace-root explicit project_root", () => {
+    test("显式绝对路径优先，不走上级 layout", () => {
+        const parent = fs.mkdtempSync(path.join(os.tmpdir(), "ws-parent-"));
+        const child = path.join(parent, "my-app");
+        tempDirs.push(parent);
+        fs.mkdirSync(child, { recursive: true });
+        fs.mkdirSync(path.join(parent, "docs", ".mcp-probe"), { recursive: true });
+        fs.writeFileSync(path.join(parent, "docs", ".mcp-probe", "layout.json"), JSON.stringify({ version: 1, indexPath: "AGENTS.md", contextRoot: "docs" }), "utf8");
+        const resolution = resolveWorkspaceRootWithMeta(child);
+        expect(resolution.root).toBe(path.resolve(child));
+        expect(resolution.explicitHonored).toBe(true);
+        expect(resolution.source).toBe("explicit");
+    });
+    test("显式路径无效时返回 warning", () => {
+        const resolution = resolveWorkspaceRootWithMeta("not/a/valid/root");
+        expect(resolution.explicitHonored).toBe(false);
+        expect(resolution.warning).toMatch(/未能采用传入的 project_root/);
+    });
+});

package/build/lib/custom-mcp-resources.d.ts

@@ -0,0 +1,39 @@
+export declare const CUSTOM_RESOURCES_MANIFEST_REL = ".mcp-probe-kit/resources.json";
+export declare const CUSTOM_RESOURCE_URI_PREFIX = "project://";
+export interface CustomResourceManifestEntry {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+    /** 相对项目根的文件路径 */
+    file?: string;
+    /** 内联文本（与 file 二选一） */
+    text?: string;
+    /** 是否在 resources/list 中展示，默认 true */
+    list?: boolean;
+}
+export interface CustomResourcesManifestV1 {
+    version: 1;
+    resources: CustomResourceManifestEntry[];
+}
+export interface CustomResourceDescriptor {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export interface CustomResourceContent {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export declare function resolveCustomResourcesManifestPath(projectRoot?: string): string;
+export declare function parseCustomResourcesManifest(raw: string): CustomResourceManifestEntry[];
+export declare function loadCustomResourcesManifest(projectRoot?: string): {
+    manifestPath: string | null;
+    entries: CustomResourceManifestEntry[];
+    error: string | null;
+};
+export declare function listCustomResourceDescriptors(projectRoot?: string): CustomResourceDescriptor[];
+export declare function readCustomResourceContent(uri: string, projectRoot?: string): CustomResourceContent | null;
+export declare function buildCustomResourcesManifestExample(): CustomResourcesManifestV1;

package/build/lib/custom-mcp-resources.js

@@ -0,0 +1,222 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveWorkspaceRoot } from "./workspace-root.js";
+export const CUSTOM_RESOURCES_MANIFEST_REL = ".mcp-probe-kit/resources.json";
+export const CUSTOM_RESOURCE_URI_PREFIX = "project://";
+const DEFAULT_MAX_RESOURCES = 50;
+const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
+function getMaxResources() {
+    const raw = process.env.MCP_CUSTOM_RESOURCES_MAX?.trim();
+    if (!raw) {
+        return DEFAULT_MAX_RESOURCES;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_RESOURCES;
+}
+function getMaxFileBytes() {
+    const raw = process.env.MCP_CUSTOM_RESOURCE_MAX_BYTES?.trim();
+    if (!raw) {
+        return DEFAULT_MAX_FILE_BYTES;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_FILE_BYTES;
+}
+export function resolveCustomResourcesManifestPath(projectRoot) {
+    const root = path.resolve(projectRoot ?? resolveWorkspaceRoot(""));
+    const envPath = process.env.MCP_CUSTOM_RESOURCES_PATH?.trim();
+    if (envPath) {
+        return path.isAbsolute(envPath) ? envPath : path.join(root, envPath);
+    }
+    return path.join(root, CUSTOM_RESOURCES_MANIFEST_REL);
+}
+function normalizeRelativeFilePath(raw) {
+    const cleaned = raw.replace(/\\/g, "/").trim().replace(/^\/+/, "");
+    if (!cleaned || cleaned === ".") {
+        throw new Error("file 不能为空");
+    }
+    if (cleaned.split("/").includes("..")) {
+        throw new Error(`file 不允许包含 '..': ${raw}`);
+    }
+    return cleaned;
+}
+function assertValidCustomUri(uri) {
+    if (!uri.startsWith(CUSTOM_RESOURCE_URI_PREFIX)) {
+        throw new Error(`uri 必须以 ${CUSTOM_RESOURCE_URI_PREFIX} 开头: ${uri}`);
+    }
+    const tail = uri.slice(CUSTOM_RESOURCE_URI_PREFIX.length);
+    if (!tail || !/^[a-zA-Z0-9._\-/]+$/.test(tail)) {
+        throw new Error(`uri 格式无效: ${uri}`);
+    }
+    if (uri.startsWith("probe://")) {
+        throw new Error(`uri 不可使用 probe:// 命名空间: ${uri}`);
+    }
+}
+function resolveFileInsideProject(projectRoot, fileRel) {
+    const normalized = normalizeRelativeFilePath(fileRel);
+    const abs = path.resolve(projectRoot, normalized);
+    const relative = path.relative(projectRoot, abs);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`file 必须位于项目根内: ${fileRel}`);
+    }
+    return abs;
+}
+function validateManifestEntry(entry, index, seenUris) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new Error(`resources[${index}] 必须是对象`);
+    }
+    const record = entry;
+    const uri = typeof record.uri === "string" ? record.uri.trim() : "";
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const mimeType = typeof record.mimeType === "string" ? record.mimeType.trim() : "";
+    const file = typeof record.file === "string" ? record.file.trim() : undefined;
+    const text = typeof record.text === "string" ? record.text : undefined;
+    const description = typeof record.description === "string" ? record.description.trim() : undefined;
+    const list = record.list === undefined ? true : Boolean(record.list);
+    if (!uri) {
+        throw new Error(`resources[${index}].uri 必填`);
+    }
+    if (!name) {
+        throw new Error(`resources[${index}].name 必填`);
+    }
+    if (!mimeType) {
+        throw new Error(`resources[${index}].mimeType 必填`);
+    }
+    assertValidCustomUri(uri);
+    if (seenUris.has(uri)) {
+        throw new Error(`resources[${index}] uri 重复: ${uri}`);
+    }
+    seenUris.add(uri);
+    const hasFile = Boolean(file);
+    const hasText = text !== undefined;
+    if (hasFile === hasText) {
+        throw new Error(`resources[${index}] 必须指定 file 或 text 之一（不可同时或皆无）`);
+    }
+    return {
+        uri,
+        name,
+        description,
+        mimeType,
+        ...(file ? { file } : {}),
+        ...(text !== undefined ? { text } : {}),
+        list,
+    };
+}
+export function parseCustomResourcesManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`resources.json 不是合法 JSON: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("resources.json 根节点必须是对象");
+    }
+    const record = parsed;
+    const version = record.version;
+    if (version !== 1) {
+        throw new Error(`resources.json version 必须为 1，当前: ${String(version)}`);
+    }
+    if (!Array.isArray(record.resources)) {
+        throw new Error("resources.json 缺少 resources 数组");
+    }
+    const max = getMaxResources();
+    if (record.resources.length > max) {
+        throw new Error(`resources 数量超过上限 ${max}`);
+    }
+    const seenUris = new Set();
+    return record.resources.map((entry, index) => validateManifestEntry(entry, index, seenUris));
+}
+export function loadCustomResourcesManifest(projectRoot) {
+    const manifestPath = resolveCustomResourcesManifestPath(projectRoot);
+    if (!fs.existsSync(manifestPath)) {
+        return { manifestPath: null, entries: [], error: null };
+    }
+    try {
+        const raw = fs.readFileSync(manifestPath, "utf-8");
+        const entries = parseCustomResourcesManifest(raw);
+        return { manifestPath, entries, error: null };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[MCP Probe Kit] 自定义 resources 清单加载失败: ${message}`);
+        return { manifestPath, entries: [], error: message };
+    }
+}
+export function listCustomResourceDescriptors(projectRoot) {
+    const { entries } = loadCustomResourcesManifest(projectRoot);
+    return entries
+        .filter((entry) => entry.list !== false)
+        .map((entry) => ({
+        uri: entry.uri,
+        name: entry.name,
+        description: entry.description ?? `项目自建资源 (${entry.uri})`,
+        mimeType: entry.mimeType,
+    }));
+}
+export function readCustomResourceContent(uri, projectRoot) {
+    if (!uri.startsWith(CUSTOM_RESOURCE_URI_PREFIX)) {
+        return null;
+    }
+    const root = path.resolve(projectRoot ?? resolveWorkspaceRoot(""));
+    const { entries, error } = loadCustomResourcesManifest(root);
+    const entry = entries.find((item) => item.uri === uri);
+    if (!entry) {
+        if (error) {
+            throw new Error(`自定义 resources 清单无效，无法读取 ${uri}: ${error}`);
+        }
+        throw new Error(`未找到自定义 resource: ${uri}`);
+    }
+    if (entry.text !== undefined) {
+        return {
+            uri: entry.uri,
+            mimeType: entry.mimeType,
+            text: entry.text,
+        };
+    }
+    if (!entry.file) {
+        throw new Error(`resource 配置无效（缺少 file/text）: ${uri}`);
+    }
+    const absPath = resolveFileInsideProject(root, entry.file);
+    if (!fs.existsSync(absPath)) {
+        throw new Error(`resource 文件不存在: ${entry.file}`);
+    }
+    const stat = fs.statSync(absPath);
+    if (!stat.isFile()) {
+        throw new Error(`resource 路径不是文件: ${entry.file}`);
+    }
+    const maxBytes = getMaxFileBytes();
+    if (stat.size > maxBytes) {
+        throw new Error(`resource 文件过大 (${stat.size} > ${maxBytes} bytes): ${entry.file}`);
+    }
+    const text = fs.readFileSync(absPath, "utf-8");
+    return {
+        uri: entry.uri,
+        mimeType: entry.mimeType,
+        text,
+    };
+}
+export function buildCustomResourcesManifestExample() {
+    return {
+        version: 1,
+        resources: [
+            {
+                uri: "project://docs/architecture",
+                name: "架构说明",
+                description: "项目架构文档（docs/architecture.md）",
+                mimeType: "text/markdown",
+                file: "docs/architecture.md",
+                list: true,
+            },
+            {
+                uri: "project://team/oncall",
+                name: "值班信息",
+                description: "内联文本示例",
+                mimeType: "text/plain",
+                text: "Oncall: team@example.com",
+                list: false,
+            },
+        ],
+    };
+}

package/build/lib/output-schema-registry.d.ts

@@ -3,9 +3,17 @@
  */
 type JsonSchema = Record<string, unknown>;
 export declare function getOutputSchemaForTool(toolName: string): JsonSchema | undefined;
+/** Cursor 等对 tools/list 体积敏感时，默认不在列表里附带 outputSchema（调用仍返回 structuredContent） */
+export declare function shouldIncludeOutputSchemaInToolsList(): boolean;
 export declare function withOutputSchema<T extends {
     name: string;
 }>(tool: T): T & {
     outputSchema?: JsonSchema;
 };
+/** tools/list 返回前的最终形态（默认省略 outputSchema 以兼容 Cursor lease） */
+export declare function prepareToolForToolsList<T extends {
+    name: string;
+}>(tool: T): T & {
+    annotations?: import("./tool-annotations.js").ToolAnnotations;
+};
 export {};

package/build/lib/output-schema-registry.js

@@ -8,6 +8,7 @@ import { InterviewReportSchema } from '../schemas/output/product-design-tools.js
 import { CommitGuidanceSchema, FeatureReportSchema, BugFixReportSchema, UIReportSchema, OnboardingReportSchema, RalphLoopReportSchema, WorkflowReportSchema, } from '../schemas/structured-output.js';
 import { MemorySearchSchema, MemoryAssetDetailSchema, MemorizeResultSchema, DeleteMemoryResultSchema, UpdateMemoryResultSchema, PatternExtractionSchema, } from '../schemas/output/memory-tools.js';
 import { CodeInsightSchema } from '../schemas/output/code-insight-tools.js';
+import { withToolAnnotations } from './tool-annotations.js';
 const SpecValidationReportSchema = {
     type: 'object',
     properties: {
@@ -74,7 +75,20 @@ const OUTPUT_SCHEMA_BY_TOOL = {
 export function getOutputSchemaForTool(toolName) {
     return OUTPUT_SCHEMA_BY_TOOL[toolName];
 }
+/** Cursor 等对 tools/list 体积敏感时，默认不在列表里附带 outputSchema（调用仍返回 structuredContent） */
+export function shouldIncludeOutputSchemaInToolsList() {
+    const raw = process.env.MCP_INCLUDE_OUTPUT_SCHEMA;
+    if (raw === undefined) {
+        return false;
+    }
+    return /^(1|true|yes|on)$/i.test(raw.trim());
+}
 export function withOutputSchema(tool) {
     const outputSchema = getOutputSchemaForTool(tool.name);
     return outputSchema ? { ...tool, outputSchema } : tool;
 }
+/** tools/list 返回前的最终形态（默认省略 outputSchema 以兼容 Cursor lease） */
+export function prepareToolForToolsList(tool) {
+    const annotated = withToolAnnotations(tool);
+    return shouldIncludeOutputSchemaInToolsList() ? withOutputSchema(annotated) : annotated;
+}

package/build/lib/project-mcp-resources.d.ts

@@ -0,0 +1,61 @@
+import { type McpProbeKitBootstrapResult } from "./workflow-skill-installer.js";
+export declare const PROJECT_BOOTSTRAP_URI = "probe://project/bootstrap";
+export declare const PROJECT_RESOURCE_PREFIX = "probe://project/";
+export type ProjectResourceId = "skill" | "agents" | "context" | "graph";
+export interface ProjectResourceEntry {
+    id: ProjectResourceId;
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    fileRel: string;
+    exists: boolean;
+}
+export interface ProjectResourcesSnapshot {
+    projectRoot: string;
+    bootstrap: McpProbeKitBootstrapResult;
+    resources: ProjectResourceEntry[];
+}
+/**
+ * 只读发现项目资源（不写盘）。用于 resources/list、probe://status 等热路径。
+ */
+export declare function discoverProjectResources(projectRoot?: string): Omit<ProjectResourcesSnapshot, "bootstrap"> & {
+    bootstrap?: never;
+};
+/**
+ * 自检并补齐 Skill + AGENTS.md，再按约定路径发现可读 Resource（按需调用，勿在 resources/list 中调用）。
+ */
+export declare function ensureAndDiscoverProjectResources(projectRoot?: string): ProjectResourcesSnapshot;
+export declare function buildProjectBootstrapPayload(snapshot: ProjectResourcesSnapshot): {
+    projectRoot: string;
+    autoBootstrap: {
+        skill: {
+            path: string;
+            created: boolean;
+            updated: boolean;
+            version: string;
+        };
+        agentsMd: {
+            path: string;
+            created: boolean;
+            updated: boolean;
+        };
+        workspaceWarning: string | null;
+    };
+    resources: {
+        id: ProjectResourceId;
+        uri: string;
+        name: string;
+        description: string;
+        mimeType: string;
+        file: string;
+        exists: boolean;
+    }[];
+    readHint: string;
+};
+export declare function resolveProjectResourceId(uri: string): ProjectResourceId | null;
+export declare function readProjectResourceContent(uri: string, projectRoot?: string): {
+    uri: string;
+    mimeType: string;
+    text: string;
+} | null;

package/build/lib/project-mcp-resources.js

@@ -0,0 +1,173 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensureMcpProbeKitBootstrap, } from "./workflow-skill-installer.js";
+import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
+import { resolveProjectContextLayout, toPosixPath } from "./project-context-layout.js";
+import { resolveWorkspaceRoot } from "./workspace-root.js";
+export const PROJECT_BOOTSTRAP_URI = "probe://project/bootstrap";
+export const PROJECT_RESOURCE_PREFIX = "probe://project/";
+const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
+function getMaxFileBytes() {
+    const raw = process.env.MCP_PROJECT_RESOURCE_MAX_BYTES?.trim();
+    if (!raw) {
+        return DEFAULT_MAX_FILE_BYTES;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_FILE_BYTES;
+}
+function fileExists(projectRoot, rel) {
+    try {
+        return fs.existsSync(path.join(projectRoot, rel)) && fs.statSync(path.join(projectRoot, rel)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function buildResourceEntries(projectRoot, layout) {
+    const skillRel = MCP_PROBE_SKILL_REL_PATH;
+    const agentsRel = toPosixPath(layout.indexPath);
+    const contextRel = layout.indexStyle === "legacy"
+        ? toPosixPath(layout.legacyIndexPath)
+        : agentsRel;
+    const graphRel = toPosixPath(layout.latestMarkdownPath);
+    const defs = [
+        {
+            id: "skill",
+            uri: `${PROJECT_RESOURCE_PREFIX}skill`,
+            name: "MCP 调用时机 Skill",
+            description: "自动维护的 .agents/skills/mcp-probe-kit/SKILL.md",
+            mimeType: "text/markdown",
+            fileRel: skillRel,
+        },
+        {
+            id: "agents",
+            uri: `${PROJECT_RESOURCE_PREFIX}agents`,
+            name: "AGENTS.md",
+            description: "项目 Agent 规则与 mcp-probe 上下文块",
+            mimeType: "text/markdown",
+            fileRel: agentsRel,
+        },
+        {
+            id: "context",
+            uri: `${PROJECT_RESOURCE_PREFIX}context`,
+            name: "项目上下文索引",
+            description: "AGENTS.md 或 docs/project-context.md 入口",
+            mimeType: "text/markdown",
+            fileRel: contextRel,
+        },
+        {
+            id: "graph",
+            uri: `${PROJECT_RESOURCE_PREFIX}graph`,
+            name: "图谱洞察（最新）",
+            description: "docs/graph-insights/latest.md（存在时）",
+            mimeType: "text/markdown",
+            fileRel: graphRel,
+        },
+    ];
+    return defs.map((item) => ({
+        ...item,
+        exists: fileExists(projectRoot, item.fileRel),
+    }));
+}
+/**
+ * 只读发现项目资源（不写盘）。用于 resources/list、probe://status 等热路径。
+ */
+export function discoverProjectResources(projectRoot) {
+    const root = path.resolve(projectRoot ?? resolveWorkspaceRoot(""));
+    const layout = resolveProjectContextLayout(root);
+    const resources = buildResourceEntries(root, layout);
+    return {
+        projectRoot: root,
+        resources,
+    };
+}
+/**
+ * 自检并补齐 Skill + AGENTS.md，再按约定路径发现可读 Resource（按需调用，勿在 resources/list 中调用）。
+ */
+export function ensureAndDiscoverProjectResources(projectRoot) {
+    const root = path.resolve(projectRoot ?? resolveWorkspaceRoot(""));
+    const bootstrap = ensureMcpProbeKitBootstrap(root);
+    const layout = resolveProjectContextLayout(root);
+    const resources = buildResourceEntries(root, layout);
+    return {
+        projectRoot: root,
+        bootstrap,
+        resources,
+    };
+}
+export function buildProjectBootstrapPayload(snapshot) {
+    const { bootstrap, resources } = snapshot;
+    return {
+        projectRoot: toPosixPath(snapshot.projectRoot),
+        autoBootstrap: {
+            skill: {
+                path: bootstrap.skill.skillRelPath,
+                created: bootstrap.skill.created,
+                updated: bootstrap.skill.updated,
+                version: bootstrap.skill.version,
+            },
+            agentsMd: {
+                path: toPosixPath(bootstrap.agentsMd.path),
+                created: bootstrap.agentsMd.created,
+                updated: bootstrap.agentsMd.updated,
+            },
+            workspaceWarning: bootstrap.workspaceWarning ?? null,
+        },
+        resources: resources.map((item) => ({
+            id: item.id,
+            uri: item.uri,
+            name: item.name,
+            description: item.description,
+            mimeType: item.mimeType,
+            file: item.fileRel,
+            exists: item.exists,
+        })),
+        readHint: "无需配置文件。resources/read 按需读取 probe://project/skill、agents、context、graph；缺失项会在 tools/list 或工具调用时自动补齐。",
+    };
+}
+export function resolveProjectResourceId(uri) {
+    if (!uri.startsWith(PROJECT_RESOURCE_PREFIX)) {
+        return null;
+    }
+    const tail = uri.slice(PROJECT_RESOURCE_PREFIX.length);
+    if (tail === "bootstrap") {
+        return null;
+    }
+    if (tail === "skill" || tail === "agents" || tail === "context" || tail === "graph") {
+        return tail;
+    }
+    return null;
+}
+export function readProjectResourceContent(uri, projectRoot) {
+    if (uri === PROJECT_BOOTSTRAP_URI) {
+        const snapshot = ensureAndDiscoverProjectResources(projectRoot);
+        return {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(buildProjectBootstrapPayload(snapshot), null, 2),
+        };
+    }
+    const id = resolveProjectResourceId(uri);
+    if (!id) {
+        return null;
+    }
+    const snapshot = ensureAndDiscoverProjectResources(projectRoot);
+    const entry = snapshot.resources.find((item) => item.id === id);
+    if (!entry) {
+        throw new Error(`未知项目 resource: ${uri}`);
+    }
+    if (!entry.exists) {
+        throw new Error(`项目 resource 文件尚不存在: ${entry.fileRel}（可先调用 init_project_context 或任意 MCP 工具触发自动补齐）`);
+    }
+    const absPath = path.join(snapshot.projectRoot, entry.fileRel);
+    const stat = fs.statSync(absPath);
+    const maxBytes = getMaxFileBytes();
+    if (stat.size > maxBytes) {
+        throw new Error(`文件过大 (${stat.size} > ${maxBytes} bytes): ${entry.fileRel}`);
+    }
+    return {
+        uri: entry.uri,
+        mimeType: entry.mimeType,
+        text: fs.readFileSync(absPath, "utf-8"),
+    };
+}

package/build/lib/workflow-skill-installer.d.ts

@@ -17,6 +17,8 @@ export interface McpProbeKitBootstrapResult {
     projectRoot: string;
     skill: SkillEnsureResult;
     agentsMd: AgentsMdEnsureResult;
+    /** 工作区可能解析失败（写到了 mcp-probe-kit 安装目录） */
+    workspaceWarning?: string;
 }
 export declare function resolveProjectRootFromToolArgs(args: unknown): string;
 /**