bfi-cli 0.1.98 → 0.1.100

package/dist/_chunks/mcp.mjs

@@ -0,0 +1,559 @@
+import { builtinCommands, entriesFromJson, normalizeConfig, object, resolveVariables, validName, variables } from "./model.mjs";
+import { agentIds, applyPlan, decodeServer, loadTarget, planInstall, planRemove, readDocument, targetFor } from "./manager.mjs";
+import { readConfig } from "./files.mjs";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+async function readCatalog(registry, query = "", fetcher = fetch) {
+	let base;
+	try {
+		base = new URL(registry);
+	} catch {
+		throw new Error("SkillHub 地址无效。");
+	}
+	if (!["https:", "http:"].includes(base.protocol) || base.username || base.password || base.search || base.hash) throw new Error("SkillHub 地址必须为无凭据的 HTTP(S) 地址。");
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (let page = 0; page < 100; page++) {
+		const url = new URL(`${base.toString().replace(/\/$/, "")}/api/web/mcps`);
+		url.search = new URLSearchParams({
+			query,
+			page: String(page),
+			size: "100"
+		}).toString();
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 15e3);
+		try {
+			const response = await fetcher(url, {
+				signal: controller.signal,
+				redirect: "error",
+				headers: { Accept: "application/json" }
+			});
+			if (!response.ok) throw new Error();
+			const reader = response.body?.getReader();
+			if (!reader) throw new Error();
+			const chunks = [];
+			let size = 0;
+			try {
+				while (true) {
+					const chunk = await reader.read();
+					if (chunk.done) break;
+					size += chunk.value.byteLength;
+					if (size > 2097152) throw new Error();
+					chunks.push(chunk.value);
+				}
+			} finally {
+				await reader.cancel().catch(() => {});
+			}
+			const envelope = object(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+			if (envelope.code !== 0) throw new Error();
+			const data = object(envelope.data);
+			if (!Array.isArray(data.items) || typeof data.total !== "number" || data.total < 0) throw new Error();
+			for (const item of data.items) {
+				const row = object(item);
+				if (typeof row.registrationName !== "string") throw new Error();
+				const name = validName(row.registrationName);
+				if (seen.has(name)) throw new Error();
+				seen.add(name);
+				entries.push({
+					registrationName: name,
+					id: typeof row.id === "string" ? row.id : void 0,
+					title: typeof row.title === "string" ? row.title : void 0,
+					description: typeof row.description === "string" ? row.description : void 0,
+					revision: typeof row.revision === "number" ? row.revision : void 0,
+					config: normalizeConfig(row.config),
+					runtime: row.runtime ? { source: String(object(row.runtime).source) } : null
+				});
+			}
+			if (entries.length >= data.total) return entries;
+			if (!data.items.length) throw new Error();
+		} catch {
+			throw new Error("读取 MCP 市场失败：请核对 SkillHub 地址、网络及服务版本；未修改本地配置。");
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	throw new Error("MCP 市场分页超过安全上限，请缩小查询范围。");
+}
+async function catalogEntries(registry, names) {
+	const entries = [];
+	for (const name of names) {
+		validName(name);
+		const matches = (await readCatalog(registry, name)).filter((entry) => entry.registrationName === name);
+		if (matches.length !== 1) throw new Error(`市场中未找到唯一 MCP：${name}。请用 bfi mcp search 查询准确名称。`);
+		entries.push(matches[0]);
+	}
+	return entries;
+}
+async function probe(config, options = {}) {
+	const environment = options.environment ?? process.env;
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 100 || timeoutMs > 3e5) throw new Error("测试超时必须为 0.1–300 秒。");
+	let resolved;
+	try {
+		resolved = resolveVariables(config, {}, environment);
+	} catch {
+		return {
+			ok: false,
+			phase: "configuration",
+			code: "INVALID_INPUT",
+			message: "所需环境变量缺失或值无效，请核对安装计划列出的变量；不会保存或回显凭据。"
+		};
+	}
+	const client = new Client({
+		name: "bfi-mcp-check",
+		version: "1.0.0"
+	}, { capabilities: {} });
+	const controller = new AbortController();
+	let phase = "connect";
+	let transport;
+	const abort = () => controller.abort();
+	options.signal?.addEventListener("abort", abort, { once: true });
+	if (options.signal?.aborted) controller.abort();
+	const timeout = setTimeout(abort, timeoutMs);
+	if (resolved.type === "stdio") {
+		const child = new StdioClientTransport({
+			command: resolved.command,
+			args: resolved.args,
+			cwd: resolved.cwd,
+			env: {
+				...Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== void 0)),
+				...resolved.env
+			},
+			stderr: "pipe"
+		});
+		child.stderr?.on("data", () => {});
+		transport = child;
+	} else {
+		const destination = new URL(resolved.url);
+		const boundedFetch = async (input, init) => {
+			if (new URL(input instanceof Request ? input.url : String(input)).origin !== destination.origin) throw new Error("CROSS_ORIGIN");
+			const headers = new Headers(init?.headers);
+			for (const [name, value] of Object.entries(resolved.headers ?? {})) if (!headers.has(name)) headers.set(name, value);
+			return fetch(input, {
+				...init,
+				signal: controller.signal,
+				redirect: "error",
+				headers
+			});
+		};
+		const transportOptions = {
+			requestInit: {
+				headers: resolved.headers,
+				redirect: "error"
+			},
+			fetch: boundedFetch
+		};
+		transport = resolved.type === "sse" ? new SSEClientTransport(destination, transportOptions) : new StreamableHTTPClientTransport(destination, transportOptions);
+	}
+	let abortListener;
+	try {
+		const work = async () => {
+			try {
+				await client.connect(transport);
+			} catch (error) {
+				const code = error.code;
+				if (!options.autoSse || resolved.type !== "http" || ![404, 405].includes(code ?? 0)) throw error;
+				await transport.close();
+				return probe({
+					...config,
+					type: "sse"
+				}, {
+					...options,
+					autoSse: false,
+					signal: controller.signal
+				});
+			}
+			phase = "tools/list";
+			if (!client.getServerCapabilities()?.tools) return {
+				ok: true,
+				phase,
+				tools: []
+			};
+			const names = /* @__PURE__ */ new Set();
+			const cursors = /* @__PURE__ */ new Set();
+			let cursor;
+			for (let page = 0; page < 100; page++) {
+				const result = await client.listTools(cursor ? { cursor } : void 0, {
+					signal: controller.signal,
+					timeout: timeoutMs
+				});
+				for (const tool of result.tools) {
+					if (names.has(tool.name)) throw new Error("DUPLICATE_TOOL");
+					names.add(tool.name);
+				}
+				if (names.size > 5e3) throw new Error("TOO_MANY_TOOLS");
+				cursor = result.nextCursor;
+				if (!cursor) return {
+					ok: true,
+					phase,
+					tools: [...names]
+				};
+				if (cursors.has(cursor)) throw new Error("REPEATED_CURSOR");
+				cursors.add(cursor);
+			}
+			throw new Error("TOO_MANY_PAGES");
+		};
+		return await Promise.race([work(), new Promise((_resolve, reject) => {
+			abortListener = () => reject(/* @__PURE__ */ new Error("ABORTED"));
+			controller.signal.addEventListener("abort", abortListener, { once: true });
+			if (controller.signal.aborted) abortListener();
+		})]);
+	} catch (error) {
+		const code = error.code;
+		const message = error instanceof Error ? error.message : "";
+		const timedOut = controller.signal.aborted;
+		const auth = code === 401 || code === 403 || /unauthorized|forbidden|\b401\b|\b403\b/i.test(message);
+		const missing = code === "ENOENT";
+		return {
+			ok: false,
+			phase,
+			code: timedOut ? "ABORTED" : auth ? "AUTH_REQUIRED" : missing ? "COMMAND_NOT_FOUND" : "PROTOCOL_OR_CONNECTION_ERROR",
+			message: timedOut ? "测试超时或已取消。" : auth ? "认证失败，请核对环境变量、账号权限，或在目标 Agent 中完成 OAuth 登录。" : missing ? "启动命令不存在，请先安装相应的 Node.js/Python 运行环境及 MCP 程序。" : "连接或协议响应失败，请核对服务、登录态及配置；原始输出已隐藏，避免泄露凭据。"
+		};
+	} finally {
+		clearTimeout(timeout);
+		options.signal?.removeEventListener("abort", abort);
+		if (abortListener) controller.signal.removeEventListener("abort", abortListener);
+		controller.abort();
+		await client.close().catch(() => {});
+		await transport.close().catch(() => {});
+	}
+}
+const help = `bfi mcp — 安装、管理与验证独立 MCP（不影响技能或插件）
+
+  search [query]                    搜索 SkillHub MCP 市场
+  info <name>                       查看元信息、传输和所需变量（不显示凭据）
+  agents                            查看支持的 Agent 与配置路径
+  install <name...> --agent <agent>  安装选中的 MCP，默认用户级
+  install --file <json> --agent <agent>  离线导入 mcpServers JSON
+  list --agent <agent>              列出所选文件中的 MCP
+  remove <name...> --agent <agent>   仅移除配置，不卸载程序
+  test <name...> --agent <agent>     显式启动/连接并查询 tools/list，不调用业务工具
+
+  --scope user|project              用户级（默认）或项目级
+  --config <path>                   明确目标配置文件（格式由 Agent 决定）
+  --dry-run                        仅预览脱敏计划，不写文件/执行程序
+  --replace                        同名冲突时替换连接配置，保留宿主其它设置
+  --input-env key=ENV_NAME          将配置变量绑定到环境变量（可重复）
+  --materialize-inputs              显式将值写入用户私有配置；禁止项目级使用
+  --yes, -y                        确认写入或执行测试（不会隐式启用 --replace）
+  --timeout <seconds>              测试总超时，默认 30，最大 300
+  --registry <url>                  市场地址；查询公开目录，不发送账号 Token
+  --json                           输出脱敏 JSON
+
+示例：bfi mcp install bfi-db --agent codex --dry-run
+      bfi mcp install bfi-pm --agent codex --input-env pm_ak=PM_AK --input-env pm_sk=PM_SK --yes
+      bfi mcp test bfi-db --agent codex --yes
+
+注册不安装依赖、不授予项目信任、不自动打开 OAuth。GUI Agent 必须能继承引用的环境变量。
+stdio 测试会执行本机程序并使用本机登录态；远程测试会发送配置的认证头。`;
+function parseMcpArguments(args) {
+	const result = {
+		command: args[0] ?? "help",
+		names: [],
+		scope: "user",
+		bindings: {},
+		dryRun: false,
+		replace: false,
+		materialize: false,
+		yes: false,
+		json: false,
+		timeoutMs: 3e4
+	};
+	if (["--help", "-h"].includes(result.command)) result.command = "help";
+	const seen = /* @__PURE__ */ new Set();
+	for (let index = 1; index < args.length; index++) {
+		const flag = args[index];
+		if (flag === "--help" || flag === "-h") {
+			result.command = "help";
+			continue;
+		}
+		if (!flag.startsWith("-")) {
+			result.names.push(flag);
+			continue;
+		}
+		const normalized = flag === "-a" ? "--agent" : flag === "-y" ? "--yes" : flag === "--plan" ? "--dry-run" : flag;
+		if (seen.has(normalized) && normalized !== "--input-env") throw new Error("选项重复，请检查参数。");
+		seen.add(normalized);
+		if (normalized === "--yes") result.yes = true;
+		else if (normalized === "--dry-run") result.dryRun = true;
+		else if (normalized === "--replace") result.replace = true;
+		else if (normalized === "--json") result.json = true;
+		else if (normalized === "--materialize-inputs") result.materialize = true;
+		else {
+			if (![
+				"--agent",
+				"--scope",
+				"--config",
+				"--file",
+				"--registry",
+				"--input-env",
+				"--timeout"
+			].includes(normalized)) throw new Error("未知 MCP 选项；请运行 bfi mcp --help。");
+			const value = args[++index];
+			if (!value || value.startsWith("-")) throw new Error("选项缺少值；请运行 bfi mcp --help。");
+			if (normalized === "--scope") {
+				if (!["user", "project"].includes(value)) throw new Error("--scope 只接受 user 或 project。");
+				result.scope = value;
+			} else if (normalized === "--input-env") {
+				const match = /^([A-Za-z_][A-Za-z0-9_]*)=([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+				if (!match || Object.hasOwn(result.bindings, match[1])) throw new Error("--input-env 需要唯一的 key=ENV_NAME，不接受密钥值。");
+				if ([
+					"__proto__",
+					"constructor",
+					"prototype"
+				].includes(match[1])) throw new Error("不安全的变量名。");
+				result.bindings[match[1]] = match[2];
+			} else if (normalized === "--timeout") {
+				const timeout = Number(value);
+				if (!Number.isFinite(timeout) || timeout < .1 || timeout > 300) throw new Error("--timeout 范围为 0.1–300 秒。");
+				result.timeoutMs = timeout * 1e3;
+			} else result[normalized.slice(2)] = value;
+		}
+	}
+	if (![
+		"help",
+		"search",
+		"info",
+		"agents",
+		"install",
+		"list",
+		"remove",
+		"test"
+	].includes(result.command)) throw new Error("未知 MCP 命令；请运行 bfi mcp --help。");
+	if (result.command === "help") return result;
+	if ([
+		"install",
+		"list",
+		"remove",
+		"test"
+	].includes(result.command) && !result.agent) throw new Error("请用 --agent 明确目标；bfi mcp agents 可查看支持列表。");
+	if (result.command !== "install" && (result.file || result.replace || result.materialize || Object.keys(result.bindings).length)) throw new Error("安装专用选项仅适用于 install。");
+	if (result.dryRun && !["install", "remove"].includes(result.command)) throw new Error("--dry-run 仅适用于 install/remove，不会执行测试。");
+	if ([
+		"info",
+		"remove",
+		"test"
+	].includes(result.command) && !result.names.length) throw new Error("请明确指定 MCP 名称。");
+	if (result.command === "info" && result.names.length !== 1) throw new Error("info 每次只接受一个 MCP 名称。");
+	if (["agents", "list"].includes(result.command) && result.names.length) throw new Error("此命令不接受 MCP 名称。");
+	if (result.command === "install" && !result.file && !result.names.length) throw new Error("请指定 MCP 名称或 --file。");
+	if (result.command !== "search") result.names.forEach(validName);
+	if (new Set(result.names).size !== result.names.length && result.command !== "search") throw new Error("MCP 名称重复。");
+	return result;
+}
+function terminalText(value) {
+	return value.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, " ");
+}
+async function registryAddress(override) {
+	if (override) return override;
+	for (const path of [join(process.cwd(), ".bfirc"), join(homedir(), ".bfi/config.json")]) try {
+		const config = readDocument(await readFile(path, "utf8"), "jsonc");
+		if (typeof config.registry === "string" && config.registry) return config.registry;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw new Error("BFI 配置无法读取；请检查配置或用 --registry 指定地址。");
+	}
+	return "https://bfi.yyuap.com:811";
+}
+async function confirm(yes, message) {
+	if (yes) return true;
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("非交互环境需要 --yes；安装可先使用 --dry-run。");
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		return /^(y|yes)$/i.test((await prompt.question(`${message} [y/N] `)).trim());
+	} finally {
+		prompt.close();
+	}
+}
+function entryInfo(entry) {
+	return {
+		name: entry.registrationName,
+		title: entry.title,
+		description: entry.description,
+		transport: entry.config.type,
+		variables: variables(entry.config),
+		revision: entry.revision
+	};
+}
+async function runMcp(args) {
+	const options = parseMcpArguments(args);
+	const print = (value) => console.log(options.json ? JSON.stringify(value, null, 2) : terminalText(typeof value === "string" ? value : JSON.stringify(value)));
+	if (options.command === "help") {
+		console.log(help);
+		return;
+	}
+	if (options.command === "agents") {
+		const targets = agentIds.map((agent) => {
+			try {
+				const target = targetFor(agent, options.scope);
+				return {
+					agent,
+					path: target.path,
+					format: target.format
+				};
+			} catch {
+				return {
+					agent,
+					path: "需用 --config 明确文件；见帮助及 README"
+				};
+			}
+		});
+		if (options.json) print(targets);
+		else targets.forEach((target) => print(`${target.agent.padEnd(14)} ${target.path}`));
+		return;
+	}
+	if (options.command === "search" || options.command === "info") {
+		const registry = await registryAddress(options.registry);
+		const entries = options.command === "search" ? await readCatalog(registry, options.names.join(" ")) : await catalogEntries(registry, options.names);
+		if (options.json) print(entries.map(entryInfo));
+		else entries.forEach((entry) => print(`${entry.registrationName} [${entry.config.type}] ${entry.description ?? ""}${variables(entry.config).length ? ` · 变量：${variables(entry.config).join(", ")}` : ""}`));
+		if (!entries.length && !options.json) print("未找到 MCP。");
+		return;
+	}
+	const target = targetFor(options.agent, options.scope, { config: options.config });
+	if (options.command === "list") {
+		const { servers } = await loadTarget(target);
+		const rows = Object.entries(servers).map(([name, value]) => {
+			try {
+				return {
+					name,
+					transport: decodeServer(value, target).type
+				};
+			} catch {
+				return {
+					name,
+					transport: "原生扩展/停用配置，请在 Agent 中查看"
+				};
+			}
+		});
+		if (options.json) print({
+			path: target.path,
+			servers: rows
+		});
+		else {
+			print(target.path);
+			rows.forEach((row) => print(`${row.name} [${row.transport}]`));
+		}
+		return;
+	}
+	if (options.command === "test") {
+		const { servers } = await loadTarget(target);
+		const configs = options.names.map((name) => {
+			if (!Object.hasOwn(servers, name)) throw new Error(`配置中没有 MCP：${name}。`);
+			return {
+				name,
+				config: decodeServer(servers[name], target)
+			};
+		});
+		if (!await confirm(options.yes, "测试会执行所选本机程序/连接远程服务，使用本机环境与登录态；只查询工具清单。继续？")) return;
+		const controller = new AbortController();
+		const abort = () => controller.abort();
+		process.once("SIGINT", abort);
+		process.once("SIGTERM", abort);
+		const results = [];
+		try {
+			for (const item of configs) {
+				if (controller.signal.aborted) break;
+				const result = await probe(item.config, {
+					timeoutMs: options.timeoutMs,
+					signal: controller.signal,
+					autoSse: ["cursor", "opencode"].includes(target.agent)
+				});
+				results.push({
+					name: item.name,
+					...result
+				});
+				if (!result.ok) process.exitCode = 1;
+				if (!options.json) print(result.ok ? `${item.name}：连接成功，发现 ${result.tools.length} 个工具（未调用业务工具）。` : `${item.name}：${result.message} [${result.phase} / ${result.code}]`);
+			}
+			if (controller.signal.aborted) process.exitCode = 130;
+			if (options.json) print({
+				path: target.path,
+				results,
+				cancelled: controller.signal.aborted
+			});
+		} finally {
+			process.removeListener("SIGINT", abort);
+			process.removeListener("SIGTERM", abort);
+		}
+		return;
+	}
+	let entries = [];
+	if (options.command === "install") {
+		if (options.file) {
+			const data = await readConfig(options.file);
+			if (data === void 0) throw new Error("导入配置文件不存在。");
+			entries = entriesFromJson(readDocument(data, "jsonc"));
+			if (options.names.length) entries = options.names.map((name) => {
+				const match = entries.find((entry) => entry.registrationName === name);
+				if (!match) throw new Error(`导入文件中没有 MCP：${name}。`);
+				return match;
+			});
+		} else entries = await catalogEntries(await registryAddress(options.registry), options.names);
+	}
+	const plan = options.command === "remove" ? await planRemove(target, options.names) : await planInstall(target, entries, {
+		replace: options.replace,
+		bindings: options.bindings,
+		materialize: options.materialize
+	});
+	const warnings = [];
+	if (entries.some((entry) => builtinCommands.has(entry.config.command ?? ""))) warnings.push("BFI 命令复用 bfi auth login 登录态；本命令不安装/升级 bfi-cli，也不额外写入 BFI_TOKEN。");
+	if (entries.some((entry) => variables(entry.config).length) && !options.materialize) warnings.push("只保存变量引用。请安全设置环境变量，并确保实际启动 Agent 的进程可读取（GUI 不一定继承终端环境）。");
+	if (options.materialize) warnings.push("将把真实值写入用户私有配置及其后续备份；请勿分享这些文件。");
+	if (target.scope === "project") warnings.push("项目配置不自动获得宿主信任；请在 Agent 中审核启用。");
+	const summary = {
+		agent: target.agent,
+		path: target.path,
+		scope: target.scope,
+		changes: plan.changes,
+		warnings
+	};
+	if (!options.json) {
+		print(`目标：${target.agent} · ${target.scope} · ${target.path}`);
+		plan.changes.forEach((change) => print(`${change.action.padEnd(10)} ${change.name}${change.variables?.length ? ` · 环境变量 ${change.variables.join(", ")}` : ""}`));
+		warnings.forEach(print);
+	}
+	if (options.dryRun) {
+		if (options.json) print({
+			...summary,
+			dryRun: true
+		});
+		else print("仅预览，未写入配置。");
+		return;
+	}
+	if (plan.next === plan.previous) {
+		if (options.json) print({
+			...summary,
+			changed: false
+		});
+		else print("无需修改。");
+		return;
+	}
+	if (!await confirm(options.yes, "按以上计划修改配置？")) {
+		if (options.json) print({
+			...summary,
+			cancelled: true
+		});
+		return;
+	}
+	const result = await applyPlan(plan);
+	if (options.json) print({
+		...summary,
+		...result
+	});
+	else {
+		print(`已更新配置：${target.path}`);
+		if (result.backup) print(`原配置备份：${result.backup}`);
+		print("重新加载/重启目标 Agent 后生效。");
+	}
+}
+export { runMcp };

package/dist/_chunks/model.mjs

@@ -0,0 +1,124 @@
+const variablePattern = /\$\{(?:user_config\.)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+const builtinCommands = /* @__PURE__ */ new Set([
+	"bfi-db-mcp",
+	"bfi-codesearch-mcp",
+	"bfi-weknora-mcp"
+]);
+function object(value, label = "配置") {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}必须为对象。`);
+	return value;
+}
+function validName(name) {
+	if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name) || [
+		"__proto__",
+		"prototype",
+		"constructor"
+	].includes(name)) throw new Error("MCP 名称只能包含字母、数字、下划线、点或连字符（最长 128 字符）。");
+	return name;
+}
+function stringMap(value, label) {
+	if (value === void 0) return;
+	const mapping = object(value, label);
+	for (const [key, item] of Object.entries(mapping)) {
+		if (!key || [
+			"__proto__",
+			"prototype",
+			"constructor"
+		].includes(key) || typeof item !== "string" || /[\0\r\n]/.test(key)) throw new Error(`${label}必须是字符串键值映射。`);
+		if (item.includes("\0")) throw new Error("配置值不允许 NUL 字符。");
+		if (label === "headers" && /[\r\n]/.test(item)) throw new Error("HTTP header 不允许换行。");
+		if (label === "env" && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error("环境变量名无效。");
+		if (label === "headers" && !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(key)) throw new Error("HTTP header 名称无效。");
+	}
+	return Object.keys(mapping).length ? mapping : void 0;
+}
+function normalizeConfig(value, resolved = false) {
+	const source = object(value);
+	const allowed = [
+		"type",
+		"transport",
+		"command",
+		"args",
+		"env",
+		"cwd",
+		"url",
+		"headers"
+	];
+	if (Object.keys(source).some((key) => !allowed.includes(key))) throw new Error("配置含未支持的扩展字段；为避免丢失其语义，本次不安装。请使用客户端原生配置。");
+	if (source.type && source.transport && source.type !== source.transport) throw new Error("type 与 transport 冲突。");
+	const rawType = source.type ?? source.transport ?? (source.command ? "stdio" : "http");
+	const type = rawType === "streamable-http" ? "http" : rawType;
+	if (![
+		"stdio",
+		"http",
+		"sse"
+	].includes(String(type))) throw new Error("不支持的 MCP 传输方式。");
+	const result = { type };
+	if (type === "stdio") {
+		if (typeof source.command !== "string" || !source.command.trim() || /[\0\r\n]/.test(source.command)) throw new Error("stdio 需要有效的 command。");
+		if (source.url !== void 0 || source.headers !== void 0) throw new Error("stdio 不接受 url/headers。");
+		result.command = source.command;
+		if (source.args !== void 0) {
+			if (!Array.isArray(source.args) || !source.args.every((item) => typeof item === "string" && !item.includes("\0"))) throw new Error("args 必须为字符串数组。");
+			if (source.args.length) result.args = source.args;
+		}
+		const env = stringMap(source.env, "env");
+		if (env) result.env = env;
+		if (source.cwd !== void 0) {
+			if (typeof source.cwd !== "string" || !source.cwd || source.cwd.includes("\0")) throw new Error("cwd 必须为路径字符串。");
+			result.cwd = source.cwd;
+		}
+	} else {
+		if ([
+			"command",
+			"args",
+			"env",
+			"cwd"
+		].some((key) => source[key] !== void 0)) throw new Error("远程 MCP 不接受 stdio 启动字段。");
+		if (typeof source.url !== "string") throw new Error("远程 MCP 需要 url。");
+		let url;
+		try {
+			url = new URL(source.url.replace(variablePattern, "placeholder"));
+		} catch {
+			throw new Error("MCP URL 无效。");
+		}
+		if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash) throw new Error("MCP URL 必须是无内嵌凭据的 HTTP(S) 地址。");
+		result.url = source.url;
+		const headers = stringMap(source.headers, "headers");
+		if (headers) result.headers = headers;
+	}
+	for (const value of resolved ? [] : strings(result)) if (value.replace(variablePattern, "").includes("${")) throw new Error("不支持的变量语法；请使用 ${NAME} 或 ${user_config.NAME}。");
+	return result;
+}
+function strings(value) {
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value)) return value.flatMap(strings);
+	if (value && typeof value === "object") return Object.values(value).flatMap(strings);
+	return [];
+}
+function mapStrings(value, mapper) {
+	if (typeof value === "string") return mapper(value);
+	if (Array.isArray(value)) return value.map((item) => mapStrings(item, mapper));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapStrings(item, mapper)]));
+	return value;
+}
+function variables(config) {
+	return [...new Set(strings(config).flatMap((value) => [...value.matchAll(variablePattern)].map((match) => match[1])))];
+}
+function resolveVariables(config, bindings, environment) {
+	return normalizeConfig(mapStrings(config, (text) => text.replace(variablePattern, (_whole, name, fallback) => {
+		const key = bindings[name] ?? name;
+		const value = environment[key] || fallback;
+		if (value === void 0 || value === "") throw new Error(`缺少环境变量 ${key}，请在本机安全设置后重试。`);
+		return value;
+	})), true);
+}
+function entriesFromJson(value) {
+	const mapping = object(object(value).mcpServers, "mcpServers");
+	if (!Object.keys(mapping).length || Object.keys(mapping).length > 100) throw new Error("mcpServers 需要 1–100 项。");
+	return Object.entries(mapping).map(([name, config]) => ({
+		registrationName: validName(name),
+		config: normalizeConfig(config)
+	}));
+}
+export { builtinCommands, entriesFromJson, mapStrings, normalizeConfig, object, resolveVariables, validName, variablePattern, variables };

package/dist/_chunks/ownership.mjs

@@ -0,0 +1,7 @@
+import { pathKey, receipts } from "./receipt.mjs";
+import { sep } from "node:path";
+async function assertLegacyUnmanaged(paths, home) {
+	const owned = (await receipts(home)).flatMap((record) => record.actions.filter((action) => action.kind === "skill" && !action.remove).map((action) => pathKey(action.path)));
+	if (paths.some((path) => owned.some((root) => root === pathKey(path) || root.startsWith(pathKey(path) + sep) || pathKey(path).startsWith(root + sep)))) throw new Error("此技能属于完整安装回执；请使用 bfi skills/package update 或 package uninstall @空间/名称，不可通过旧批量路径覆盖或删除。");
+}
+export { assertLegacyUnmanaged };