bfi-cli 0.1.98 → 0.1.100

package/dist/_chunks/command.mjs

@@ -0,0 +1,698 @@
+import { isCancel } from "./libs/@clack/core.mjs";
+import { confirm as confirm$1, multiselect, select } from "./libs/@clack/prompts.mjs";
+import { inspectPluginArchive } from "./intent.mjs";
+import { loadGlobalConfig, loadProjectConfig, resolveConfig } from "./config.mjs";
+import { agents, detectInstalledAgents, setAgents } from "./agents.mjs";
+import { SkillHubAPI, getAgentBaseDir } from "../cli.mjs";
+import { builtinCommands, normalizeConfig, variables } from "./model.mjs";
+import { planInstall, readDocument, serversIn, targetFor } from "./manager.mjs";
+import { checkPath, readConfig, writeConfig } from "./files.mjs";
+import { canonical, hash, stableManifest, verifyPlan } from "./digest.mjs";
+import { InstallationClient, credentialForRegistry, registryUrl } from "./client.mjs";
+import { resolveAgents } from "./agents2.mjs";
+import { assertWritable, atomicPrivate, checkpoint, fingerprint, operationRoot, ownershipDigest, pathKey, readReceipt, receipts, safeDirectory, treeFingerprint, withInstallationLock } from "./receipt.mjs";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { access, cp, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+async function inspectBundle(bytes, online) {
+	const tree = await inspectPluginArchive(bytes, "installation.zip", {
+		compressedBytes: 510 * 1024 ** 2,
+		expandedBytes: 512 * 1024 ** 2,
+		fileBytes: 50 * 1024 ** 2,
+		entries: 40010
+	});
+	const manifest = tree.files.find((file) => file.path === "installation-manifest.json");
+	if (!manifest || manifest.content.length > 12 * 1024 ** 2) throw new Error("归档缺少完整安装清单，不支持旧版技能 ZIP。");
+	const stable = JSON.parse(manifest.content.toString("utf8"));
+	if ("id" in stable || "expiresAt" in stable) throw new Error("归档清单不应含在线计划状态。");
+	const plan = verifyPlan({
+		...stable,
+		id: online?.id ?? "offline",
+		expiresAt: online?.expiresAt ?? "9999-01-01T00:00:00.000Z"
+	});
+	if (online && canonical(stableManifest(online)) !== canonical(stableManifest(plan))) throw new Error("归档与固定内容计划不一致。");
+	const metadata = /* @__PURE__ */ new Set([
+		"installation-manifest.json",
+		"README.md",
+		"mcp/servers.json"
+	]);
+	const files = tree.files.filter((file) => !metadata.has(file.path));
+	if (files.length !== plan.files.length) throw new Error("归档文件清单不完整或包含额外文件。");
+	const actual = new Map(files.map((file) => [file.path, file]));
+	for (const expected of plan.files) {
+		const file = actual.get(expected.path);
+		if (!file || file.content.length !== expected.size || hash(file.content) !== expected.sha256 || file.executable !== expected.executable) throw new Error("归档文件内容或权限校验失败。");
+	}
+	const servers = tree.files.find((file) => file.path === "mcp/servers.json");
+	if (!servers || canonical(JSON.parse(servers.content.toString("utf8"))) !== canonical({ mcpServers: Object.fromEntries(plan.mcps.map((mcp) => [mcp.registrationName, mcp.config])) })) throw new Error("MCP 文件与清单不一致。");
+	return {
+		plan,
+		files,
+		offline: !online
+	};
+}
+function parseInstallArguments(args) {
+	const result = { inputEnv: [] };
+	const seen = /* @__PURE__ */ new Set();
+	const values = {
+		"--registry": "registry",
+		"--content-plan": "contentPlan",
+		"--from-archive": "fromArchive",
+		"--operation": "operation"
+	};
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index];
+		if (!argument.startsWith("-")) {
+			if (result.ref || !/^@[\w.-]+\/[\w.-]+$/.test(argument)) throw new Error("请指定唯一的 @空间/名称。");
+			result.ref = argument;
+			continue;
+		}
+		const split = argument.indexOf("=");
+		const raw = split < 0 ? argument : argument.slice(0, split);
+		const flag = {
+			"-g": "--global",
+			"-y": "--yes",
+			"-a": "--agent",
+			"-h": "--help"
+		}[raw] ?? raw;
+		if (seen.has(flag) && !["--agent", "--input-env"].includes(flag)) throw new Error(`重复参数：${flag}`);
+		seen.add(flag);
+		if ([
+			"--agent",
+			"--input-env",
+			"--scope",
+			"--as",
+			...Object.keys(values)
+		].includes(flag)) {
+			const value = split < 0 ? args[++index] : argument.slice(split + 1);
+			if (!value || value.startsWith("-") || /[\x00-\x1f\x7f]/.test(value)) throw new Error(`缺少有效参数：${flag}`);
+			if (flag === "--agent") (result.agents ??= []).push(...value.split(","));
+			else if (flag === "--input-env") result.inputEnv.push(value);
+			else if (flag === "--scope") {
+				if (!["user", "project"].includes(value)) throw new Error("范围仅支持 user 或 project。");
+				result.scope = value;
+			} else if (flag === "--as") {
+				if (value !== "skills") throw new Error("插件必须走原生插件安装入口。");
+			} else Object.assign(result, { [values[flag]]: value });
+		} else {
+			if (split >= 0) throw new Error(`参数不接受值：${flag}`);
+			if (flag === "--global") result.scope = "user";
+			else if (flag === "--yes") result.yes = true;
+			else if (flag === "--replace") result.replace = true;
+			else if (flag === "--environment-ready") result.environmentReady = true;
+			else if (flag === "--help") result.help = true;
+			else if (flag === "--dry-run") result.dryRun = true;
+			else if (flag === "--json") result.json = true;
+			else throw new Error(`未知安装参数：${flag}`);
+		}
+	}
+	if (seen.has("--scope") && seen.has("--global")) throw new Error("不能同时指定 --scope 与 --global。");
+	if ([
+		result.contentPlan,
+		result.fromArchive,
+		result.operation
+	].filter(Boolean).length > 1) throw new Error("计划、离线归档、恢复操作不能混用。");
+	if (result.fromArchive && result.ref) throw new Error("离线归档不能同时指定在线资源。");
+	return result;
+}
+async function resolveDestination(options, prompts, cwd = process.cwd()) {
+	if (!options.agents?.length && !prompts) throw new Error("请指定 --agent；没有交互终端时不能猜测 Agent。");
+	if (!options.scope && !prompts) throw new Error("请指定 --scope user|project；--yes 不会代选安装范围。");
+	const agents = [...new Set(options.agents ?? await prompts.agents())];
+	const scope = options.scope ?? await prompts.scope();
+	if (!agents.length || !["user", "project"].includes(scope)) throw new Error("已取消安装。");
+	return {
+		agents,
+		scope,
+		...scope === "project" ? { projectPath: resolve(cwd) } : {}
+	};
+}
+function parseBindings(values, plan) {
+	const result = {};
+	for (const value of values) {
+		const split = value.indexOf("=");
+		const source = value.slice(0, split);
+		const variable = value.slice(split + 1);
+		const matches = plan.mcps.flatMap((mcp) => variables(normalizeConfig(mcp.config)).filter((key) => `${mcp.registrationName}.${key}` === source).map((key) => ({
+			server: mcp.registrationName,
+			key
+		})));
+		if (split < 0 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable) || matches.length !== 1) throw new Error("变量绑定须为 MCP名称.参数名=环境变量名，且必须来自此计划。");
+		const match = matches[0];
+		const bindings = result[match.server] ??= {};
+		if (bindings[match.key]) throw new Error("重复变量绑定。");
+		bindings[match.key] = variable;
+	}
+	return result;
+}
+async function executable(command, env) {
+	const paths = isAbsolute(command) ? [command] : command.includes("/") || command.includes("\\") ? [] : (env.PATH ?? "").split(delimiter).filter(Boolean).map((directory) => join(directory, command));
+	for (const path of paths) for (const suffix of process.platform === "win32" ? [
+		"",
+		".exe",
+		".cmd",
+		".bat"
+	] : [""]) try {
+		await access(path + suffix, constants.X_OK);
+		return true;
+	} catch {}
+	return false;
+}
+async function checkMcpInputs(plan, bindingsByServer, env, environmentReady = false) {
+	for (const mcp of plan.mcps) {
+		const config = normalizeConfig(mcp.config);
+		if (mcp.runtime?.source === "upload") throw new Error(`MCP ${mcp.registrationName} 的上传运行包尚不能在完整组合中自动安装。`);
+		const keys = variables(config);
+		if (Object.keys(bindingsByServer[mcp.registrationName] ?? {}).some((key) => !keys.includes(key))) throw new Error("变量绑定不属于此 MCP。");
+		for (const key of /* @__PURE__ */ new Set([...keys, ...mcp.inputs.filter((input) => input.required).map((input) => input.key)])) if (!env[bindingsByServer[mcp.registrationName]?.[key] ?? key]) throw new Error(`缺少变量 ${mcp.registrationName}.${key}，请安全设置本机环境并用 --input-env 绑定；不要在命令行填写密钥值。`);
+		if (keys.length && !environmentReady) throw new Error("请确认目标 Agent（包括桌面进程）可读取所绑定的环境变量，再加 --environment-ready；仅 CLI 进程可读不足以证明宿主可用。");
+		if (config.type === "stdio" && !await executable(config.command, env)) throw new Error(`找不到 MCP 启动命令 ${mcp.registrationName}，请先准备其本机依赖。`);
+	}
+	if (Object.keys(bindingsByServer).some((name) => !plan.mcps.some((mcp) => mcp.registrationName === name))) throw new Error("变量绑定包含计划外 MCP。");
+}
+function skillResource(registry, id) {
+	return canonical([registry.replace(/\/$/, ""), id]);
+}
+function skillDirectoryName(registry, id) {
+	return `bfi-skill-${hash(skillResource(registry, id))}`;
+}
+function sameInstallation(record, plan, destination) {
+	return record.plan.registry === plan.registry && record.plan.resourceId === plan.resourceId && record.plan.kind === plan.kind && canonical({
+		...record.destination,
+		agents: [...record.destination.agents].sort()
+	}) === canonical({
+		...destination,
+		agents: [...destination.agents].sort()
+	});
+}
+async function prepareInstall(bundle, destination, options = {}) {
+	const home = options.home ?? homedir();
+	const env = options.env ?? process.env;
+	const plan = verifyPlan(bundle.plan);
+	const supported = [
+		"skill-install-v1",
+		"content-plan-v1",
+		"collection-bundle-v1",
+		"collection-mcp-v1",
+		"scope-selection-v1"
+	];
+	if (plan.requiredCapabilities.some((value) => !supported.includes(value))) throw new Error("内容要求当前 CLI 未支持的能力，请升级。");
+	if (!destination.agents.length || !["user", "project"].includes(destination.scope) || destination.scope === "project" && !destination.projectPath) throw new Error("安装目标不完整。");
+	if (options.previous && !sameInstallation(options.previous, plan, destination)) throw new Error("更新资源稳定身份或目标与原回执不匹配。");
+	const records = await receipts(home);
+	if (records.some((record) => record.state === "INCOMPLETE")) throw new Error("存在未完成安装，请先用 --operation <ID> 恢复，不混入新计划。");
+	await checkMcpInputs(plan, options.bindingsByServer ?? {}, env, options.environmentReady);
+	const receipt = {
+		id: randomUUID(),
+		plan,
+		destination,
+		offline: bundle.offline,
+		state: "INCOMPLETE",
+		actions: [],
+		payloads: /* @__PURE__ */ new Map(),
+		retained: [],
+		bindingsByServer: options.bindingsByServer,
+		ownershipDigest: ownershipDigest(records),
+		...options.previous ? { replaces: options.previous.id } : {}
+	};
+	const add = (action, payload) => {
+		const existing = receipt.actions.find((item) => item.path.toLowerCase().normalize("NFC") === action.path.toLowerCase().normalize("NFC"));
+		if (existing) {
+			if (existing.after !== action.after || existing.before !== action.before || existing.kind !== action.kind || existing.resource !== action.resource) throw new Error("多个目标指向同一路径但内容不兼容。");
+			existing.agents.push(...action.agents);
+			return;
+		}
+		action.source = String(receipt.actions.length);
+		receipt.actions.push(action);
+		receipt.payloads.set(action.source, payload);
+	};
+	for (const agentName of destination.agents) {
+		const agent = agentName;
+		if (!Object.hasOwn(agents, agent)) throw new Error(`未知技能 Agent：${agentName}`);
+		if (destination.scope === "user" && !agents[agent].globalSkillsDir) throw new Error(`Agent ${agentName} 不支持用户级技能。`);
+		let base = getAgentBaseDir(agent, destination.scope === "user", destination.projectPath);
+		if (home !== homedir() && destination.scope === "user") {
+			const suffix = relative(homedir(), base);
+			if (suffix.startsWith("..")) throw new Error("自定义技能路径不在指定 home 下。");
+			base = join(home, suffix);
+		}
+		for (const skill of plan.skills) {
+			if (!/^@[\w.-]+\/[\w.-]+$/.test(skill.ref)) throw new Error("技能引用无效。");
+			const name = skillDirectoryName(plan.registry, skill.id);
+			const path = resolve(base, name);
+			await assertWritable(path, true);
+			const before = await fingerprint(path, "skill");
+			const files = bundle.files.filter((file) => file.path.startsWith(`${skill.root}/`)).map((file) => ({
+				...file,
+				path: file.path.slice(skill.root.length + 1)
+			}));
+			const after = treeFingerprint(files.map((file) => ({
+				path: file.path,
+				sha256: hash(file.content),
+				executable: file.executable
+			})));
+			const resource = skillResource(plan.registry, skill.id);
+			const owners = records.flatMap((record) => record.actions.filter((item) => pathKey(item.path) === pathKey(path) && item.kind === "skill").map((item) => ({
+				record,
+				item
+			})));
+			if (owners.some((owner) => owner.item.resource !== resource)) throw new Error("技能路径被不同来源或稳定身份占用。");
+			if (owners.some((owner) => owner.item.after !== before)) throw new Error("本机技能已修改，不覆盖用户内容。");
+			if (before !== void 0 && before !== after) {
+				if (owners.some((owner) => owner.record.id !== options.previous?.id)) throw new Error("技能被其它安装共用，不能单独升级覆盖。");
+				if (!owners.length && !options.replace) throw new Error("技能路径已存在不同内容；需要明确 --replace。");
+			}
+			add({
+				kind: "skill",
+				path,
+				agents: [agent],
+				before,
+				after,
+				resource,
+				managed: before === void 0 || before !== after || owners.some((owner) => owner.item.managed)
+			}, files);
+		}
+		if (plan.mcps.length) {
+			const target = targetFor(agent === "kimi-code-cli" ? "kimi-code" : agent, destination.scope, {
+				home,
+				cwd: destination.projectPath,
+				env
+			});
+			await assertWritable(target.path);
+			const oldConfig = options.previous?.actions.find((action) => pathKey(action.path) === pathKey(target.path) && action.kind === "mcp");
+			const config = await planInstall(target, plan.mcps.map((mcp) => ({
+				...mcp,
+				config: normalizeConfig(mcp.config),
+				runtime: mcp.runtime ? { source: String(mcp.runtime.source) } : void 0
+			})), {
+				bindingsByServer: options.bindingsByServer,
+				environment: env,
+				replace: options.replace
+			});
+			const currentServers = serversIn(readDocument(config.previous ?? "", target.format), target.key);
+			const nextServers = serversIn(readDocument(config.next ?? "", target.format), target.key);
+			const serverHashes = Object.fromEntries(plan.mcps.map((mcp) => [mcp.registrationName, hash(canonical(nextServers[mcp.registrationName]))]));
+			if (oldConfig) {
+				for (const mcp of plan.mcps.filter((mcp) => options.previous.plan.mcps.some((previous) => previous.registrationName === mcp.registrationName))) if (!oldConfig.servers || hash(canonical(currentServers[mcp.registrationName] ?? null)) !== oldConfig.servers[mcp.registrationName]) throw new Error("受管 MCP 条目已被修改，停止更新；无关服务器不受影响。");
+			}
+			for (const record of records.filter((record) => record.id !== options.previous?.id)) for (const action of record.actions.filter((action) => action.kind === "mcp" && pathKey(action.path) === pathKey(target.path))) for (const [name, digest] of Object.entries(action.servers ?? {})) if (serverHashes[name] && serverHashes[name] !== digest) throw new Error("MCP 被其它安装共用，不能单独覆盖。");
+			add({
+				kind: "mcp",
+				path: target.path,
+				agents: [agent],
+				before: config.previous === void 0 ? void 0 : hash(config.previous),
+				after: config.next === void 0 ? void 0 : hash(config.next),
+				managed: config.previous !== config.next,
+				servers: serverHashes
+			}, Buffer.from(config.next ?? ""));
+		}
+	}
+	if (options.previous) {
+		for (const old of options.previous.actions.filter((action) => action.kind === "skill" && !receipt.actions.some((next) => pathKey(next.path) === pathKey(action.path)))) if (old.managed && !records.some((record) => record.id !== options.previous.id && record.actions.some((action) => pathKey(action.path) === pathKey(old.path))) && await fingerprint(old.path, "skill") === old.after) receipt.actions.push({
+			...old,
+			before: old.after,
+			after: void 0,
+			done: false,
+			remove: true,
+			source: void 0
+		});
+		else receipt.retained.push(old.path);
+		if (options.previous.plan.mcps.some((old) => !plan.mcps.some((next) => next.registrationName === old.registrationName))) receipt.retained.push("已解除关联的 MCP 保留在宿主配置中。");
+	}
+	return receipt;
+}
+async function saveIntent(prepared, home) {
+	const root = operationRoot(prepared.id, home);
+	await safeDirectory(root);
+	await mkdir(root, {
+		recursive: true,
+		mode: 448
+	});
+	for (const [source, payload] of prepared.payloads) {
+		const target = join(root, "payload", source);
+		if (Buffer.isBuffer(payload)) await atomicPrivate(target, payload);
+		else for (const file of payload) {
+			const path = join(target, file.path);
+			await mkdir(dirname(path), {
+				recursive: true,
+				mode: 448
+			});
+			await writeFile(path, file.content, {
+				flag: "wx",
+				mode: file.executable ? 448 : 384
+			});
+		}
+	}
+	const { payloads, ...receipt } = prepared;
+	await checkpoint(receipt, home);
+	return receipt;
+}
+async function execute(receipt, home) {
+	const root = operationRoot(receipt.id, home);
+	try {
+		for (const [index, action] of receipt.actions.entries()) {
+			const actual = await fingerprint(action.path, action.kind);
+			const backup = join(root, "backups", String(index));
+			const moved = action.kind === "skill" && actual === void 0 && action.before !== void 0 && await fingerprint(backup, "skill") === action.before;
+			if (actual !== action.after && actual !== action.before && !moved) throw new Error("本机内容与执行意图不一致，停止恢复。");
+			if (action.done && actual !== action.after) throw new Error("已完成内容被修改，停止恢复。");
+		}
+		for (const [index, action] of receipt.actions.entries()) {
+			let actual = await fingerprint(action.path, action.kind);
+			if (actual !== action.after) {
+				const backup = join(root, "backups", String(index));
+				const moved = action.kind === "skill" && actual === void 0 && action.before !== void 0 && await fingerprint(backup, "skill") === action.before;
+				if (actual !== action.before && !moved) throw new Error("写入前发现并发修改。");
+				if (action.kind === "mcp") {
+					const next = await readConfig(join(root, "payload", action.source));
+					if (next === void 0 || hash(next) !== action.after) throw new Error("恢复配置快照已损坏。");
+					const previous = await readConfig(action.path);
+					if ((previous === void 0 ? void 0 : hash(previous)) !== action.before) throw new Error("配置并发修改。");
+					await writeConfig(action.path, previous, next);
+				} else if (!action.remove) {
+					const source = join(root, "payload", action.source);
+					if (await fingerprint(source, "skill") !== action.after) throw new Error("恢复技能快照已损坏。");
+					const staging = `${action.path}.bfi-${receipt.id}`;
+					await safeDirectory(staging);
+					await rm(staging, {
+						recursive: true,
+						force: true
+					});
+					await mkdir(dirname(staging), {
+						recursive: true,
+						mode: 448
+					});
+					await cp(source, staging, {
+						recursive: true,
+						errorOnExist: true,
+						force: false
+					});
+					actual = await fingerprint(action.path, "skill");
+					if (actual !== action.before && !(actual === void 0 && moved)) throw new Error("技能目录并发修改。");
+					if (actual !== void 0) {
+						await mkdir(dirname(backup), {
+							recursive: true,
+							mode: 448
+						});
+						await rename(action.path, backup);
+					}
+					await rename(staging, action.path);
+				} else if (actual !== void 0) {
+					await mkdir(dirname(backup), {
+						recursive: true,
+						mode: 448
+					});
+					await rename(action.path, backup);
+				}
+			}
+			action.done = true;
+			await checkpoint(receipt, home);
+		}
+		receipt.state = receipt.intent === "uninstall" ? "REMOVED" : "INSTALLED";
+		await checkpoint(receipt, home);
+		return receipt;
+	} catch {
+		receipt.state = "INCOMPLETE";
+		throw new Error(`INCOMPLETE：安装未全部完成，未回滚用户内容。用 --operation ${receipt.id} 恢复；回执和私有备份位于 ${root}。`);
+	}
+}
+async function applyInstall(prepared, options = {}) {
+	return withInstallationLock(async () => {
+		const current = await receipts(options.home);
+		if (current.some((record) => record.state === "INCOMPLETE")) throw new Error("存在未完成执行，请先恢复。");
+		if (prepared.ownershipDigest !== ownershipDigest(current)) throw new Error("安装归属在预览后发生变化，请重新预检确认。");
+		return execute(await saveIntent(prepared, options.home), options.home);
+	}, options.home);
+}
+async function resumeInstall(id, options = {}) {
+	return withInstallationLock(async () => {
+		const receipt = await readReceipt(id, options.home);
+		if (receipt.state === "INCOMPLETE" && receipt.ownershipDigest !== ownershipDigest((await receipts(options.home)).filter((record) => record.id !== id))) throw new Error("安装归属已发生变化，不能自动恢复。");
+		return execute(receipt, options.home);
+	}, options.home);
+}
+function matchingReceipts(records, selector) {
+	return records.filter((record) => registryUrl(record.plan.registry) === registryUrl(selector.registry) && record.plan.ref === selector.ref && record.plan.kind === selector.kind && (!selector.scope || record.destination.scope === selector.scope) && (!selector.projectPath || record.destination.scope !== "project" || record.destination.projectPath === selector.projectPath) && (!selector.agents || selector.agents.every((agent) => record.destination.agents.includes(agent)) && selector.agents.length === record.destination.agents.length));
+}
+function selectReceipt(records, selector) {
+	const matches = matchingReceipts(records, selector);
+	if (matches.length !== 1) throw new Error(matches.length ? "存在多套安装，请明确 Agent、范围及项目目录或交互选择。" : "没有精确安装回执；旧记录无法证明归属，请重新确认目标安装，不按同名技能猜测更新。");
+	if (matches[0].state !== "INSTALLED") throw new Error("请先恢复未完成操作。");
+	return matches[0];
+}
+async function prepareUninstall(previous, home) {
+	const records = await receipts(home);
+	const result = {
+		...previous,
+		id: randomUUID(),
+		intent: "uninstall",
+		state: "INCOMPLETE",
+		replaces: previous.id,
+		payloads: /* @__PURE__ */ new Map(),
+		actions: [],
+		retained: [],
+		ownershipDigest: ownershipDigest(records)
+	};
+	for (const old of previous.actions.filter((action) => action.kind === "skill" && !action.remove)) if (old.managed && !records.some((record) => record.id !== previous.id && record.actions.some((action) => pathKey(action.path) === pathKey(old.path))) && await fingerprint(old.path, "skill") === old.after) result.actions.push({
+		...old,
+		before: old.after,
+		after: void 0,
+		remove: true,
+		done: false,
+		source: void 0
+	});
+	else result.retained.push(old.path);
+	if (previous.plan.mcps.length) result.retained.push("MCP 配置默认保留；如需移除，请使用 bfi mcp remove 单独确认。");
+	return result;
+}
+const help = `完整安装：
+  bfi skills add @空间/技能 [--agent codex] [--scope user|project]
+  bfi skills package install @空间/组合 [--agent codex,claude-code] [--global]
+  bfi skills package install --from-archive ./完整清单.zip
+  bfi skills package update @空间/组合
+  bfi skills package uninstall @空间/组合
+  bfi skills package install --operation <本机操作ID>
+选项：--content-plan <ID> --registry <URL> --input-env MCP.参数=环境变量名
+  --environment-ready 确认 Agent 可读取环境变量（桌面进程也需配置）
+  --dry-run --json --replace -y
+未指定 Agent / 范围时交互选择，-y 不代选。全部关联 MCP 必装，不支持仅技能。
+--replace 仅允许明确替换冲突；不会覆盖已修改或被其它安装共用的受管技能。
+更新继承原回执；移除组合时保留 MCP、共用及本机修改内容。`;
+function accepted(value) {
+	if (isCancel(value)) throw new Error("已取消，未继续安装。");
+	return value;
+}
+async function promptAdapter() {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+	const detected = await detectInstalledAgents();
+	return {
+		agents: async () => accepted(await multiselect({
+			message: "选择目标 Agent（只安装所选目标）",
+			options: Object.entries(agents).map(([value, agent]) => ({
+				value,
+				label: agent.displayName,
+				hint: detected.includes(value) ? "已检测到" : void 0
+			})),
+			required: true
+		})),
+		scope: async () => accepted(await select({
+			message: "选择安装范围",
+			options: [{
+				value: "user",
+				label: "用户级"
+			}, {
+				value: "project",
+				label: `当前项目：${process.cwd()}`
+			}]
+		}))
+	};
+}
+async function confirm(options) {
+	if (options.yes) return;
+	if (options.json || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("非交互安装需要在明确目标和内容后指定 -y。");
+	if (!accepted(await confirm$1({
+		message: "确认安装以上完整内容？",
+		initialValue: false
+	}))) throw new Error("已取消安装。");
+}
+function summary(record) {
+	return {
+		operation: record.id,
+		ref: record.plan.ref,
+		registry: record.plan.registry,
+		digest: record.plan.manifestDigest,
+		destination: record.destination,
+		skills: record.plan.skills.map((skill) => ({
+			ref: skill.ref,
+			version: skill.version
+		})),
+		mcps: record.plan.mcps.map((mcp) => mcp.registrationName),
+		changes: record.actions.map((action) => ({
+			kind: action.kind,
+			path: action.path,
+			agents: action.agents,
+			action: action.remove ? "remove" : action.before === action.after ? "reuse" : action.before ? "update" : "add"
+		})),
+		retained: record.retained,
+		offline: record.offline
+	};
+}
+async function accountPreflight(record) {
+	if (record.intent === "uninstall") return;
+	if (!record.plan.mcps.some((mcp) => builtinCommands.has(String(mcp.config.command)))) return;
+	const login = loadGlobalConfig();
+	const registry = registryUrl(login?.registry ?? "https://bfi.yyuap.com:811");
+	await new InstallationClient(registry, credentialForRegistry(registry, login)).verifyAccount();
+}
+async function runInstallation(command, kind, args) {
+	const options = parseInstallArguments(args);
+	if (options.help) {
+		console.log(help);
+		return;
+	}
+	const registry = registryUrl(resolveConfig({ registry: options.registry }).registry);
+	const globalConfig = loadGlobalConfig();
+	const projectConfig = loadProjectConfig(process.cwd());
+	const token = projectConfig?.token && projectConfig.registry && registryUrl(projectConfig.registry) === registry ? projectConfig.token : credentialForRegistry(registry, globalConfig);
+	const client = new InstallationClient(registry, token);
+	setAgents(await resolveAgents(token ? new SkillHubAPI(registry, token) : void 0));
+	let pendingOutput = {};
+	const output = (value) => {
+		if (!options.json) {
+			console.log(JSON.stringify(value, null, 2));
+			return;
+		}
+		pendingOutput = {
+			...pendingOutput,
+			...value
+		};
+		if (options.dryRun || value.state) console.log(JSON.stringify(pendingOutput, null, 2));
+	};
+	if (options.operation) {
+		if (command !== "install" || options.ref || options.agents || options.scope || options.replace || options.dryRun || options.inputEnv.length) throw new Error("恢复仅使用原回执，请勿混入新目标或新变量绑定。");
+		const record = await readReceipt(options.operation);
+		if (record.plan.kind !== kind) throw new Error("恢复入口与回执资源类型不同。");
+		if (record.intent !== "uninstall") await checkMcpInputs(record.plan, record.bindingsByServer ?? {}, process.env, options.environmentReady);
+		output({
+			...summary(record),
+			notice: "使用本机冻结快照恢复；没有重新验证当前在线授权。"
+		});
+		await confirm(options);
+		await accountPreflight(record);
+		output({
+			state: (await resumeInstall(record.id)).state,
+			operation: record.id
+		});
+		return;
+	}
+	const existing = await receipts();
+	let previous;
+	if (command !== "install") {
+		if (!options.ref || options.contentPlan || options.fromArchive) throw new Error("更新/卸载请指定 @空间/名称，从原回执继承目标。");
+		const selector = {
+			registry,
+			kind,
+			ref: options.ref,
+			scope: options.scope,
+			agents: options.agents,
+			projectPath: resolve(process.cwd())
+		};
+		const matches = matchingReceipts(existing, selector);
+		if (matches.length > 1 && !options.json && process.stdin.isTTY && process.stdout.isTTY) {
+			const id = accepted(await select({
+				message: "选择要处理的安装记录",
+				options: matches.map((record) => ({
+					value: record.id,
+					label: `${record.destination.agents.join(", ")} / ${record.destination.scope} / ${record.destination.projectPath ?? "用户目录"}`
+				}))
+			}));
+			previous = matches.find((record) => record.id === id);
+		} else previous = selectReceipt(existing, selector);
+	}
+	if (command === "uninstall") {
+		const prepared = await prepareUninstall(previous);
+		output(summary(prepared));
+		if (options.dryRun) return;
+		await confirm(options);
+		const result = await applyInstall(prepared);
+		output({
+			state: result.state,
+			operation: result.id,
+			retained: result.retained
+		});
+		return;
+	}
+	if (!options.ref && !options.fromArchive) throw new Error("请指定 @空间/名称或 --from-archive。");
+	const destination = previous?.destination ?? await resolveDestination(options, options.json ? void 0 : await promptAdapter());
+	let bundle;
+	if (options.fromArchive) {
+		await checkPath(resolve(options.fromArchive));
+		if ((await lstat(options.fromArchive)).size > 510 * 1024 ** 2) throw new Error("离线归档超过大小限制。");
+		bundle = await inspectBundle(await readFile(options.fromArchive));
+		if (bundle.plan.kind !== kind) throw new Error("离线归档类型与安装入口不一致。");
+	} else {
+		const plan = options.contentPlan ? await client.get(options.contentPlan, kind, options.ref) : await client.resolve(kind, options.ref);
+		if (previous && !sameInstallation(previous, plan, destination)) throw new Error("资源身份已变化，不能将重建的同名对象当作更新。");
+		const cache = join(homedir(), ".bfi/cache/installation", `${plan.manifestDigest}.zip`);
+		await checkPath(cache);
+		let archive;
+		try {
+			if ((await lstat(cache)).size > 510 * 1024 ** 2) throw new Error("缓存超过上限。");
+			archive = await readFile(cache);
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+			archive = await client.artifact(plan);
+		}
+		bundle = await inspectBundle(archive, plan);
+		await atomicPrivate(cache, archive);
+	}
+	const prior = existing.find((record) => sameInstallation(record, bundle.plan, destination));
+	if (!previous && prior) {
+		if (prior.plan.manifestDigest !== bundle.plan.manifestDigest) throw new Error("已安装内容不同，请使用 update 确认完整变更。");
+		previous = prior;
+	}
+	const prepared = await prepareInstall(bundle, destination, {
+		previous,
+		bindingsByServer: options.inputEnv.length ? parseBindings(options.inputEnv, bundle.plan) : previous?.bindingsByServer,
+		environmentReady: options.environmentReady,
+		replace: options.replace
+	});
+	output({
+		...summary(prepared),
+		...bundle.offline ? { notice: "仅验证离线完整性，不代表当前在线权限或撤回状态。" } : {}
+	});
+	await accountPreflight(prepared);
+	if (options.dryRun) return;
+	await confirm(options);
+	const installed = await applyInstall(prepared);
+	output({
+		state: installed.state,
+		operation: installed.id,
+		notice: "文件和全部关联 MCP 已注册；未调用业务工具，宿主可能需要重新加载/信任。"
+	});
+}
+async function dispatchInstallation(raw) {
+	const args = ["skills", "skill"].includes(raw[0] ?? "") ? raw.slice(1) : raw;
+	const collection = ["package", "pkg"].includes(args[0] ?? "");
+	const tail = collection ? args.slice(2) : args.slice(1);
+	if (collection && tail.includes("plugin") && tail.includes("--as")) return false;
+	const verb = args[collection ? 1 : 0];
+	const command = [
+		"add",
+		"a",
+		"i",
+		"install"
+	].includes(verb ?? "") ? "install" : ["update", "up"].includes(verb ?? "") ? "update" : [
+		"uninstall",
+		"remove",
+		"rm"
+	].includes(verb ?? "") ? "uninstall" : void 0;
+	const qualified = tail.some((value) => /^@[\w.-]+\/[\w.-]+$/.test(value));
+	const requested = tail.some((value) => /^(--content-plan|--scope|--from-archive|--operation)(=|$)/.test(value));
+	if (!command || !collection && !qualified && !requested) return false;
+	await runInstallation(command, collection ? "COLLECTION" : "SKILL", tail);
+	return true;
+}
+export { dispatchInstallation };