mcp-probe-kit 3.6.1 → 3.6.3

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.js

@@ -11,9 +11,9 @@ function buildWorkspaceWarning(projectRoot) {
     const packageRoot = path.resolve(getMcpPackageInstallRoot());
     if (normalizedRoot === packageRoot) {
         return [
-            "未能解析用户项目根目录，Skill/AGENTS.md 可能写入了 mcp-probe-kit 安装目录。",
-            "请在 MCP 配置 env 中设置 MCP_PROJECT_ROOT 为 ${workspaceFolder}，",
-            "或调用工具时传 project_root 绝对路径。",
+            "未能自动识别用户项目根目录，Skill/AGENTS.md 可能写入了 mcp-probe-kit 安装目录。",
+            "请从目标项目目录打开 MCP 客户端（Cursor / OpenCode 等会自动传入工作区），",
+            "或在工具参数中传 project_root 绝对路径。",
         ].join("");
     }
     return undefined;

package/build/lib/workflow-skill-template.js

@@ -37,7 +37,7 @@ export function generateWorkflowSkillBody(skillVersion = VERSION) {
     return `# MCP 调用时机 — mcp-probe-kit
 
 > 本 Skill 只回答一件事：**什么情况 → 调哪个 MCP**。不是开发流程剧本。
-> 由 mcp-probe-kit 自动安装；Cursor 从 \`.agents/skills/\` 加载。
+> 由 mcp-probe-kit 自动安装；支持 MCP 的 Agent 客户端可从 \`.agents/skills/\` 加载。
 
 ## 总规则
 

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

@@ -1,6 +1,8 @@
+/** Schema / 文档：project_root 参数说明（自动探测，无需用户配置 MCP_PROJECT_ROOT） */
+export declare const PROJECT_ROOT_SCHEMA_DESCRIPTION = "\u53EF\u9009\u3002\u9879\u76EE\u6839\u76EE\u5F55\u7EDD\u5BF9\u8DEF\u5F84\uFF1B\u672A\u4F20\u65F6\u81EA\u52A8\u4ECE MCP \u5BA2\u6237\u7AEF\u5DE5\u4F5C\u533A\u89E3\u6790\uFF08\u5982 Cursor \u6CE8\u5165 WORKSPACE_FOLDER_PATHS\u3001OpenCode/\u5BA2\u6237\u7AEF\u914D\u7F6E\u7684 cwd \u7B49\uFF09\u3002\u4EC5\u8FB9\u7F18\u573A\u666F\u9700\u624B\u52A8\u4F20\u5165\u3002";
 /** MCP 包自身安装目录（bootstrap 误写此处说明工作区未解析成功） */
 export declare function getMcpPackageInstallRoot(): string;
-/** 解析 Cursor 等客户端注入的 WORKSPACE_FOLDER_PATHS */
+/** 解析 MCP 客户端注入的 WORKSPACE_FOLDER_PATHS（如 Cursor） */
 export declare function resolveFromWorkspaceFolderPathsEnv(): string | null;
 export declare function isLikelyProjectNamedRelativePath(inputPath?: string): boolean;
 export declare function buildProjectRootRetryHint(inputPath?: string): {
@@ -12,5 +14,20 @@ export declare function buildProjectRootRetryHint(inputPath?: string): {
         project_root: string;
     };
 };
+export type WorkspaceRootSource = "explicit" | "explicit-not-yet-created" | "workspace-env" | "layout" | "env" | "cwd" | "package-fallback";
+export interface WorkspaceRootResolution {
+    root: string;
+    source: WorkspaceRootSource;
+    /** 用户传入的 project_root 原始值 */
+    explicitRequested?: string;
+    /** 是否采用了用户显式路径（未回退到 MCP 安装目录等） */
+    explicitHonored: boolean;
+    warning?: string;
+}
+/**
+ * 解析项目根目录。
+ * 若调用方显式传入 project_root（非空），优先信任该路径，不再向上游走 layout 到父目录。
+ */
+export declare function resolveWorkspaceRootWithMeta(explicitProjectRoot?: string): WorkspaceRootResolution;
 export declare function resolveWorkspaceRoot(explicitProjectRoot?: string): string;
 export declare function toWorkspacePath(explicitProjectRoot?: string): string;