bfi-cli 0.1.99 → 0.1.101

package/dist/_chunks/package-plugin.mjs

@@ -1,30 +1,14 @@
-import { PluginInstallRecords, PluginRegistryClient, inspectPluginArchive, materializePluginTree, normalizeRegistry, pluginArchiveLimits, pluginInstallKey, pluginSlotKey, selectPluginRoot, sha256, treeDigest } from "./registry-client.mjs";
-import { resolveConfig } from "./config.mjs";
-import { isPluginArchive, isPluginVersion, parsePluginArguments } from "../cli.mjs";
+import { isCancel } from "./libs/@clack/core.mjs";
+import { confirm, select } from "./libs/@clack/prompts.mjs";
+import { PluginInstallRecords, PluginRegistryClient, inspectPluginArchive, isPluginArchive, isPluginVersion, materializePluginTree, normalizeRegistry, parsePluginArguments, pluginArchiveLimits, pluginInstallKey, pluginSlotKey, pluginTargets, selectPluginRoot, sha256, treeDigest } from "./intent.mjs";
+import { loadGlobalConfig, loadProjectConfig, resolveConfig } from "./config.mjs";
+import { credentialForRegistry } from "./client.mjs";
 import { randomUUID } from "node:crypto";
-import { isAbsolute, join, resolve } from "node:path";
-import { lstat, mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { lstat, mkdir, open, readFile, readdir, realpath, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { execFile } from "node:child_process";
-const adapters = Object.freeze({});
-const reasons = {
-	"claude-code": ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
-	codex: ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
-	zcode: ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"],
-	codebuddy: ["OFFICIAL_FIXTURE_UNVERIFIED", "HOST_BINARY_UNAVAILABLE"],
-	"qwen-code": ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"]
-};
-function nativeAdapterFor(target) {
-	return adapters[target] ?? null;
-}
-function nativeSupportFor(target) {
-	return {
-		targetAgent: target,
-		status: "EXPORT_ONLY",
-		reasons: [...reasons[target]]
-	};
-}
 const nativeManifestFormats = {
 	"claude-code": ["CLAUDE"],
 	codex: [
@@ -75,7 +59,8 @@ function nativeRequirements(tree, target) {
 	const files = new Map(tree.files.map((file) => [file.path, file]));
 	for (const file of tree.files) {
 		const root = file.path.split("/")[0];
-		if (defaultComponents.has(root)) requirements.add(`component:${root}`);
+		if (target === "codex" && file.path === "agents/openai.yaml") requirements.add("component:agent-metadata");
+		else if (defaultComponents.has(root)) requirements.add(`component:${root}`);
 		if (file.executable) requirements.add("executable-assets");
 	}
 	const configuration = (value, kind) => {
@@ -154,6 +139,367 @@ function nativeRequirements(tree, target) {
 	}
 	return [...requirements].sort();
 }
+const nativeNamePattern = /^[a-z][a-z0-9-]{0,63}$/u;
+const cwdFor = (identity) => identity.projectPath ?? homedir();
+const marketName = (identity, digest, directory) => `bfi-${pluginInstallKey(identity).slice(0, 20)}-${digest.slice(0, 12)}-${sha256(Buffer.from(directory)).slice(0, 12)}`;
+async function nativeDirectoryDigest(directory) {
+	const files = [];
+	let bytes = 0, entries = 0;
+	const walk = async (relative) => {
+		if (++entries > pluginArchiveLimits.entries) throw new Error("NATIVE_TREE_LIMIT");
+		const path = join(directory, relative), info = await lstat(path);
+		if (info.isSymbolicLink()) throw new Error("NATIVE_TREE_LINK");
+		if (info.isDirectory()) for (const name of await readdir(path)) await walk(relative ? `${relative}/${name}` : name);
+		else {
+			if (!info.isFile() || info.size > pluginArchiveLimits.fileBytes || (bytes += info.size) > pluginArchiveLimits.expandedBytes) throw new Error("NATIVE_TREE_LIMIT");
+			files.push({
+				path: relative,
+				content: await readFile(path),
+				executable: (info.mode & 73) !== 0
+			});
+		}
+	};
+	await walk("");
+	return treeDigest(files);
+}
+async function nativeList(runner, cwd, markets = false) {
+	const { stdout } = await runner({
+		command: "claude",
+		args: [
+			"plugin",
+			...markets ? ["marketplace"] : [],
+			"list",
+			"--json"
+		]
+	}, { cwd });
+	const result = JSON.parse(stdout);
+	if (!Array.isArray(result) || result.some((item) => !item || typeof item !== "object" || Array.isArray(item))) throw new Error("NATIVE_LIST_INVALID");
+	return result;
+}
+function contextValues(context) {
+	if (!context.nativeName || !nativeNamePattern.test(context.nativeName) || !/^[a-f0-9]{64}$/u.test(context.treeDigest ?? "") || basename(context.artifactDirectory) !== "plugin") throw new Error("NATIVE_CONTEXT_INVALID");
+	const market = marketName(context.identity, context.treeDigest, context.artifactDirectory);
+	return {
+		market,
+		selector: `${context.nativeName}@${market}`,
+		directory: dirname(context.artifactDirectory),
+		manifest: {
+			name: market,
+			owner: { name: "bfi" },
+			plugins: [{
+				name: context.nativeName,
+				version: context.identity.version,
+				source: "./plugin"
+			}]
+		}
+	};
+}
+async function recordValues(record) {
+	if (await nativeDirectoryDigest(record.artifactDirectory) !== record.treeDigest) throw new Error("NATIVE_CONTENT_CHANGED");
+	const manifest = JSON.parse(await readFile(join(record.artifactDirectory, ".claude-plugin/plugin.json"), "utf8"));
+	return contextValues({
+		...record,
+		nativeName: manifest.name
+	});
+}
+const claudeAdapter = {
+	targetAgent: "claude-code",
+	version: "claude-public-v1",
+	hostVersions: ["2.1.251"],
+	scopes: ["user", "project"],
+	capabilities: [
+		"native-plugin",
+		"manifest:CLAUDE",
+		"component:skills",
+		"component:commands",
+		"component:agents",
+		"component:hooks",
+		"executable-assets",
+		"manifest-field:hooks",
+		"hook-handler:command",
+		"hook-event:PreToolUse",
+		"hook-event:PostToolUse",
+		"hook-event:Stop",
+		"hook-event:UserPromptSubmit"
+	],
+	async detect(runner, cwd) {
+		try {
+			return /^(\d+\.\d+\.\d+) \(Claude Code\)\s*$/u.exec((await runner({
+				command: "claude",
+				args: ["--version"]
+			}, { cwd })).stdout)?.[1] ?? null;
+		} catch {
+			return null;
+		}
+	},
+	plan(context) {
+		const values = contextValues(context);
+		return [{
+			command: "claude",
+			args: [
+				"plugin",
+				"marketplace",
+				"add",
+				values.directory,
+				"--scope",
+				context.identity.scope
+			]
+		}, {
+			command: "claude",
+			args: [
+				"plugin",
+				"install",
+				values.selector,
+				"--scope",
+				context.identity.scope
+			]
+		}];
+	},
+	async preflight(plan, runner) {
+		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
+		const values = contextValues({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		});
+		const cwd = cwdFor(plan.identity);
+		if ((await nativeList(runner, cwd)).some((item) => typeof item.id !== "string" || item.id.split("@")[0] === plan.nativeName)) throw new Error("NATIVE_NAME_CONFLICT");
+		if ((await nativeList(runner, cwd, true)).some((item) => item.name === values.market)) throw new Error("NATIVE_MARKET_CONFLICT");
+	},
+	async install(plan, runner) {
+		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
+		const values = contextValues({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		});
+		const cwd = cwdFor(plan.identity);
+		await this.preflight(plan, runner);
+		if (await nativeDirectoryDigest(plan.artifactDirectory) !== plan.treeDigest) throw new Error("NATIVE_CONTENT_CHANGED");
+		const nativeManifest = JSON.parse(await readFile(join(plan.artifactDirectory, ".claude-plugin/plugin.json"), "utf8"));
+		if (nativeManifest.name !== plan.nativeName || nativeManifest.version && nativeManifest.version !== plan.identity.version) throw new Error("NATIVE_IDENTITY_CHANGED");
+		await mkdir(join(values.directory, ".claude-plugin"), { mode: 448 });
+		await writeFile(join(values.directory, ".claude-plugin/marketplace.json"), JSON.stringify(values.manifest, null, 2) + "\n", {
+			flag: "wx",
+			mode: 384
+		});
+		for (const invocation of this.plan({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		})) await runner(invocation, { cwd });
+	},
+	async verify(record, runner) {
+		try {
+			const values = await recordValues(record), cwd = cwdFor(record.identity);
+			const index = JSON.parse(await readFile(join(values.directory, ".claude-plugin/marketplace.json"), "utf8"));
+			if (JSON.stringify(index) !== JSON.stringify(values.manifest)) throw new Error("NATIVE_INDEX_CHANGED");
+			const market = (await nativeList(runner, cwd, true)).filter((item) => item.name === values.market);
+			if (market.length !== 1 || market[0].source !== "directory" || typeof market[0].path !== "string" || await realpath(market[0].path) !== await realpath(values.directory)) throw new Error("NATIVE_MARKET_CHANGED");
+			const entries = (await nativeList(runner, cwd)).filter((item) => item.id === values.selector && item.scope === record.identity.scope && (record.identity.scope === "user" || item.projectPath === record.identity.projectPath));
+			const entry = entries[0];
+			return {
+				verified: entries.length === 1 && entry?.enabled === true && entry.version === record.identity.version && typeof entry.installPath === "string" && await nativeDirectoryDigest(entry.installPath) === record.treeDigest,
+				installationId: values.selector,
+				treeDigest: record.treeDigest
+			};
+		} catch {
+			return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+		}
+	},
+	async uninstall(record, runner) {
+		const values = await recordValues(record), cwd = cwdFor(record.identity);
+		await runner({
+			command: "claude",
+			args: [
+				"plugin",
+				"uninstall",
+				values.selector,
+				"--scope",
+				record.identity.scope,
+				"--keep-data"
+			]
+		}, { cwd });
+	},
+	async verifyAbsent(record, runner) {
+		const values = await recordValues(record);
+		return !(await nativeList(runner, cwdFor(record.identity))).some((item) => item.id === values.selector && item.scope === record.identity.scope && (record.identity.scope === "user" || item.projectPath === record.identity.projectPath));
+	}
+};
+const codexRequirements = [
+	"native-plugin",
+	"manifest:CODEX",
+	"manifest-field:skills",
+	"component:skills",
+	"component:agent-metadata",
+	"executable-assets"
+];
+async function prepareNativeHandoff(input) {
+	const { tree, target, scope, hostVersion, version } = input;
+	if (target !== "claude-code" && target !== "codex") throw new Error("NATIVE_HOST_UNVERIFIED");
+	if (hostVersion !== (target === "claude-code" ? "2.1.251" : "0.136.0")) throw new Error("HOST_VERSION_UNVERIFIED");
+	if (target === "codex" && scope !== "user") throw new Error("SCOPE_UNSUPPORTED");
+	const supported = target === "claude-code" ? claudeAdapter.capabilities : codexRequirements;
+	const missing = nativeRequirements(tree, target).filter((requirement) => !supported.includes(requirement));
+	if (missing.length) throw new Error(`NATIVE_COMPONENTS_UNSUPPORTED: ${missing.join(", ")}; original files retained; no skills fallback`);
+	const manifest = tree.manifests.find((item) => item.root === "" && item.format === (target === "claude-code" ? "CLAUDE" : "CODEX"));
+	if (!manifest?.name || !/^[a-z][a-z0-9-]{0,63}$/u.test(manifest.name) || !isPluginVersion(version) || manifest.version && manifest.version !== version) throw new Error("NATIVE_MANIFEST_UNSUPPORTED");
+	const destination = resolve(input.directory);
+	const directory = join(await realpath(dirname(destination)), destination.slice(dirname(destination).length + 1));
+	const market = `bfi-${target}-${tree.treeDigest.slice(0, 24)}`;
+	const selector = `${manifest.name}@${market}`;
+	const commands = target === "claude-code" ? [{
+		command: "claude",
+		args: [
+			"plugin",
+			"marketplace",
+			"add",
+			directory,
+			"--scope",
+			scope
+		]
+	}, {
+		command: "claude",
+		args: [
+			"plugin",
+			"install",
+			selector,
+			"--scope",
+			scope
+		]
+	}] : [{
+		command: "codex",
+		args: [
+			"plugin",
+			"marketplace",
+			"add",
+			directory
+		]
+	}, {
+		command: "codex",
+		args: [
+			"plugin",
+			"add",
+			selector
+		]
+	}];
+	await mkdir(directory, { mode: 448 });
+	await materializePluginTree(tree, join(directory, "plugin"));
+	const indexDirectory = join(directory, target === "claude-code" ? ".claude-plugin" : ".agents/plugins");
+	await mkdir(indexDirectory, {
+		recursive: true,
+		mode: 448
+	});
+	const index = target === "claude-code" ? {
+		name: market,
+		owner: { name: "bfi" },
+		plugins: [{
+			name: manifest.name,
+			version,
+			source: "./plugin"
+		}]
+	} : {
+		name: market,
+		plugins: [{
+			name: manifest.name,
+			source: {
+				source: "local",
+				path: "./plugin"
+			}
+		}]
+	};
+	await writeFile(join(indexDirectory, "marketplace.json"), JSON.stringify(index, null, 2) + "\n", {
+		flag: "wx",
+		mode: 384
+	});
+	return {
+		state: "PREPARED_FOR_REVIEW",
+		directory,
+		treeDigest: tree.treeDigest,
+		registered: false,
+		loaded: false,
+		commands,
+		instructions: "Review all plugin code and native-name conflicts first. Execute from the intended project only after user confirmation. Do not bypass trust. Keep this directory while installed. List/registration success is not runtime LOAD; restart the host and check all components. Use the native host for updates/removal; this handoff does not create bfi installation ownership."
+	};
+}
+var targets = [
+	{
+		"id": "claude-code",
+		"name": "Claude Code",
+		"status": "NATIVE_GATED",
+		"versions": ["2.1.251"],
+		"scopes": ["user", "project"],
+		"manifest": ".claude-plugin/plugin.json",
+		"docs": "https://code.claude.com/docs/en/plugins/cli-reference",
+		"reason": "仅开放已验证的技能、命令、Agents 和四类 command Hooks；每个发布版本仍需匹配加载证据与服务端授权。MCP、userConfig 及其他扩展尚未通过完整运行验证。",
+		"manual": "先用 --prepare-native 生成完整插件目录及独立市场索引，再审阅其输出的 claude plugin marketplace add / install 命令。需要信任审批时由用户操作，重启后检查 /plugin 与组件是否加载。"
+	},
+	{
+		"id": "codex",
+		"name": "Codex",
+		"status": "EXPORT_ONLY",
+		"versions": ["0.136.0"],
+		"scopes": ["user"],
+		"manifest": ".codex-plugin/plugin.json",
+		"docs": "https://learn.chatgpt.com/docs/plugins",
+		"reason": "已验证公开市场注册、安装和卸载接口；尚未满足自动安装的完整加载及归属验证门禁。项目级原生插件安装未验证。",
+		"manual": "仅原生 Codex 技能型插件可用 --prepare-native 生成完整目录和独立市场索引，再按输出执行 codex plugin marketplace add / plugin add。在 /plugins 检查实际启用；有 MCP、Hooks、Apps 或转换需求时停止，不把不支持的组件丢弃。"
+	},
+	{
+		"id": "zcode",
+		"name": "ZCode",
+		"status": "EXPORT_ONLY",
+		"versions": [],
+		"scopes": [],
+		"manifest": ".zcode-plugin/plugin.json",
+		"docs": "https://zcode.z.ai/cn/docs/plugin",
+		"reason": "本机无 ZCode，原生安装、加载和作用域未实测。",
+		"manual": "官方入口为打开工作区后进入 设置 → 插件 → 个人 → 创建，添加插件市场。此处尚未验证 SkillHub 归档的完整导入链路，只导出，不生成或执行猜测的安装命令。"
+	},
+	{
+		"id": "codebuddy",
+		"name": "CodeBuddy",
+		"status": "EXPORT_ONLY",
+		"versions": [],
+		"scopes": [],
+		"manifest": ".codebuddy-plugin/plugin.json",
+		"docs": "https://www.codebuddy.ai/docs/cli/plugins-reference",
+		"reason": "本机无 CodeBuddy，官方样例及完整加载未实测。",
+		"manual": "官方提供 codebuddy plugin marketplace / install 入口；未完成当前格式和宿主版本验证，只导出并提示待适配，不借用 Claude 的测试结论。"
+	},
+	{
+		"id": "qwen-code",
+		"name": "Qwen Code",
+		"status": "EXPORT_ONLY",
+		"versions": [],
+		"scopes": [],
+		"manifest": "qwen-extension.json",
+		"docs": "https://qwenlm.github.io/qwen-code-docs/en/users/extension/introduction/",
+		"reason": "本机无 Qwen Code；Claude 插件导入会进行格式转换，不等于保真兼容。",
+		"manual": "原生入口为 qwen extensions install；此处未验证隔离安装及组件保真，只导出。禁止自动把 Claude 插件转换成扩展或拆成技能。"
+	}
+];
+const adapters = Object.freeze({ "claude-code": claudeAdapter });
+const reasons = {
+	"claude-code": ["EXACT_RELEASE_LOAD_EVIDENCE_REQUIRED", "SERVER_NATIVE_CAPABILITY_REQUIRED"],
+	codex: ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
+	zcode: ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"],
+	codebuddy: ["OFFICIAL_FIXTURE_UNVERIFIED", "HOST_BINARY_UNAVAILABLE"],
+	"qwen-code": ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"]
+};
+function nativeAdapterFor(target) {
+	return adapters[target] ?? null;
+}
+function nativeSupportFor(target) {
+	return {
+		...targets.find((item) => item.id === target),
+		targetAgent: target,
+		status: adapters[target] ? "NATIVE_GATED" : "EXPORT_ONLY",
+		reasons: [...reasons[target]],
+		adapterVersion: adapters[target]?.version
+	};
+}
 function meetsMinimum(version, minimum) {
 	const expression = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/u;
 	const current = expression.exec(version), required = expression.exec(minimum);
@@ -172,6 +518,8 @@ function createPluginInstallPlan(input) {
 	const { identity, release, adapter, host } = input;
 	const plan = {
 		identity: structuredClone(identity),
+		artifactDirectory: input.artifactDirectory,
+		nativeName: input.nativeName,
 		treeDigest: release.treeDigest,
 		artifactSha256: release.artifactSha256,
 		adapterVersion: adapter?.version ?? "",
@@ -218,7 +566,9 @@ function createPluginInstallPlan(input) {
 	};
 	const invocations = adapter.plan({
 		identity: structuredClone(identity),
-		artifactDirectory: input.artifactDirectory
+		artifactDirectory: input.artifactDirectory,
+		nativeName: input.nativeName,
+		treeDigest: release.treeDigest
 	});
 	if (!invocations.length || invocations.some((invocation) => !invocation.command || [invocation.command, ...invocation.args].some((value) => typeof value !== "string" || value.includes("\0")))) return {
 		...plan,
@@ -262,24 +612,30 @@ async function installNativePlugin(request) {
 		if (active.adapterVersion !== adapter.version) throw new Error("Existing plugin requires its original adapter for safe update");
 		const verification = await adapter.verify(active, runner);
 		if (!verification.verified || verification.treeDigest !== active.treeDigest || verification.installationId !== active.installationId) throw new Error("Existing plugin ownership changed; refusing destructive update");
+		if (pluginInstallKey(active.identity) === pluginInstallKey(plan.identity) && active.artifactSha256 === plan.artifactSha256 && active.treeDigest === plan.treeDigest) return activeId;
+		throw new Error("NATIVE_UPDATE_REQUIRES_USER: existing verified version retained; export the new version and review the native update procedure");
 	}
 	const identifier = records.prepare(plan.identity, plan.artifactSha256, adapter.version, {
 		treeDigest: plan.treeDigest,
 		artifactDirectory: input.artifactDirectory
 	});
-	let invoked = false;
+	let invoked = false, staged = false;
 	try {
 		await materializePluginTree(tree, input.artifactDirectory);
+		staged = true;
+		await adapter.preflight?.(plan, runner);
 		invoked = true;
 		await adapter.install(plan, runner);
 		const verification = await adapter.verify(records.read().operations[identifier], runner);
 		if (!verification.verified || verification.treeDigest !== plan.treeDigest || !verification.installationId) throw new Error("Native verification failed");
 		records.complete(identifier, verification);
 		return identifier;
-	} catch {
+	} catch (error) {
 		if (!invoked) {
-			records.fail(identifier, "STAGING_FAILED");
-			throw new Error(`PLUGIN_STAGING_FAILED: ${identifier}`);
+			const code = staged ? "NATIVE_PREFLIGHT_FAILED" : "PLUGIN_STAGING_FAILED";
+			records.fail(identifier, code);
+			const reason = error instanceof Error && /^[A-Z_]+$/u.test(error.message) ? `: ${error.message}` : "";
+			throw new Error(`${code}: ${identifier}${reason}; no native mutation occurred`);
 		}
 		throw new Error(`NATIVE_OUTCOME_UNKNOWN: ${identifier}; PREPARED retained, inspect the native host before recovery`);
 	}
@@ -414,9 +770,40 @@ function matchingOperations(records, options, root, registry) {
 }
 async function runPluginPackage(args, globalOpts) {
 	const options = parsePluginArguments(args), cwd = await realpath(String(globalOpts.workdir ?? process.cwd()));
+	const chooseAgent = !options.agent && options.command !== "list";
+	if (chooseAgent) {
+		if (options.json || options.confirmed || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("AGENT_REQUIRED: specify --agent; interactive installation will ask you to choose");
+		const agent = await select({
+			message: "选择插件目标 Agent",
+			options: pluginTargets.map((value) => ({
+				value,
+				label: value
+			}))
+		});
+		if (isCancel(agent) || !pluginTargets.includes(agent)) throw new Error("NATIVE_CANCELLED");
+		options.agent = agent;
+	}
+	if (!options.scopeExplicit && options.command !== "list" && (chooseAgent || !options.planOnly && !options.exportPath)) {
+		if (options.json || options.confirmed || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("SCOPE_REQUIRED: specify --scope user or --scope project; --yes does not choose a scope");
+		const scope = await select({
+			message: "选择插件安装范围",
+			options: [{
+				value: "user",
+				label: "用户级"
+			}, {
+				value: "project",
+				label: `当前项目：${cwd}`
+			}]
+		});
+		if (isCancel(scope) || scope !== "user" && scope !== "project") throw new Error("NATIVE_CANCELLED");
+		options.scope = scope;
+	}
 	const storeRoot = options.scope === "user" ? await realpath(homedir()) : cwd;
 	const records = new PluginInstallRecords(storeRoot), config = resolveConfig(globalOpts);
-	const registry = new PluginRegistryClient(config.registry, config.token);
+	const projectConfig = loadProjectConfig(cwd);
+	const projectToken = projectConfig?.registry && normalizeRegistry(projectConfig.registry) === normalizeRegistry(config.registry) ? projectConfig.token : void 0;
+	const token = typeof globalOpts.token === "string" ? globalOpts.token : projectToken ?? credentialForRegistry(config.registry, loadGlobalConfig());
+	const registry = new PluginRegistryClient(config.registry, token ?? null);
 	if (options.command === "list") {
 		const lock = records.read();
 		console.log(JSON.stringify({
@@ -527,17 +914,29 @@ async function runPluginPackage(args, globalOpts) {
 		checkFiles(detail, tree);
 	}
 	if (options.command === "update" && !records.read().active[pluginSlotKey(identity)]) throw new Error("This exact source/agent/scope is not installed; local changed-content archives are separate identities");
-	const artifactDirectory = join(storeRoot, ".bfi", "plugin-artifacts", `${pluginInstallKey(identity)}-${randomUUID()}`);
+	const artifactContainer = join(storeRoot, ".bfi", "plugin-artifacts", `${pluginInstallKey(identity)}-${randomUUID()}`);
+	const artifactDirectory = join(artifactContainer, "plugin");
+	const manifest = nativeManifestFormats[agent].map((format) => tree.manifests.find((item) => item.root === "" && item.format === format)).find(Boolean);
+	let hostVersion = adapter ? await adapter.detect(runNative, cwd) : null;
+	if (options.preparePath && agent === "codex") try {
+		hostVersion = /^codex-cli (\d+\.\d+\.\d+)\s*$/u.exec((await runNative({
+			command: "codex",
+			args: ["--version"]
+		}, { cwd })).stdout)?.[1] ?? null;
+	} catch {
+		hostVersion = null;
+	}
 	const input = {
 		identity,
 		release: detail.release,
 		actualTreeDigest: tree.treeDigest,
 		actualArtifactSha256: sha256(archive),
 		requiredCapabilities: nativeRequirements(tree, agent),
+		nativeName: manifest?.name,
 		evidence: detail.evidence,
 		host: {
 			agent,
-			version: adapter ? await adapter.detect(runNative, cwd) : null
+			version: hostVersion
 		},
 		cliVersion: String(globalOpts.version ?? ""),
 		serverCapability,
@@ -550,7 +949,10 @@ async function runPluginPackage(args, globalOpts) {
 			...plan,
 			archiveRoot: root,
 			requiredCapabilities: input.requiredCapabilities,
-			nativeSupport: nativeSupportFor(agent)
+			nativeSupport: nativeSupportFor(agent),
+			diagnostics: input.requiredCapabilities.includes("manifest:missing-or-invalid") ? ["没有目标 Agent 可识别的原生插件清单；旧版 provides/pi 格式只允许原样导出，不生成替代清单。"] : [],
+			registered: false,
+			loaded: false
 		}, null, 2));
 		return;
 	}
@@ -562,22 +964,54 @@ async function runPluginPackage(args, globalOpts) {
 			mode: 384
 		});
 		console.log(JSON.stringify({
+			state: "EXPORTED",
 			exported: target,
 			archiveSha256: sha256(archive),
 			treeDigest: tree.treeDigest,
 			archiveRoot: root,
 			originalArchive: true,
-			installed: false
+			installed: false,
+			registered: false,
+			loaded: false
 		}, null, 2));
 		return;
 	}
+	if (options.preparePath) {
+		if (detail.evidence.some((item) => item.targetAgent === agent && item.treeDigest === tree.treeDigest && (!item.hostVersion || item.hostVersion === hostVersion) && (item.result === "FAIL" || item.result === "UNSUPPORTED"))) throw new Error("COMPATIBILITY_CHECK_FAILED: native handoff blocked by recorded compatibility failure; complete export remains available");
+		if (plan.reasons.includes("CLI_UPGRADE_REQUIRED")) throw new Error("CLI_UPGRADE_REQUIRED");
+		console.log(JSON.stringify(await prepareNativeHandoff({
+			tree,
+			target: agent,
+			scope: options.scope,
+			version: identity.version,
+			hostVersion,
+			directory: resolve(cwd, options.preparePath)
+		}), null, 2));
+		return;
+	}
 	if (plan.status !== "READY" || !adapter) throw new Error(`${plan.status}: ${plan.reasons.join(", ")}; use --plan or --export <archive>, no skills-only fallback occurred`);
+	if (!options.confirmed) {
+		if (options.json || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("NATIVE_CONFIRMATION_REQUIRED: review --plan first, then explicitly confirm with --yes");
+		const answer = await confirm({ message: `原生注册 ${identity.version} 到 ${agent} (${identity.scope})。插件代码、Hooks 可在宿主加载时执行；是否已审阅完整内容并继续？` });
+		if (isCancel(answer) || !answer) throw new Error("NATIVE_CANCELLED");
+	}
 	if (identity.source.kind === "registry") {
 		const [namespace, slug] = identity.source.packageRef.slice(1).split("/");
 		const current = checkedDetail(await registry.release(namespace, slug, identity.version));
-		if (await registry.packageId(namespace, slug) !== identity.source.packageId || current.release.id !== detail.release.id || current.release.treeDigest !== tree.treeDigest || current.release.state !== "PUBLISHED" || current.release.quarantined) throw new Error("Plugin distribution identity or authority changed before installation");
+		const summary = await registry.summary(namespace, slug);
+		const capability = summary?.installCapabilities?.version === "1" ? summary.installCapabilities.targets.find((item) => item.targetAgent === agent && item.path === "native") : void 0;
+		const fresh = createPluginInstallPlan({
+			...input,
+			release: current.release,
+			evidence: current.evidence,
+			serverCapability: capability
+		});
+		if (!summary?.enabled || await registry.packageId(namespace, slug) !== identity.source.packageId || current.release.id !== detail.release.id || current.release.snapshotId !== detail.release.snapshotId || current.release.artifactSize !== archive.length || current.release.lifecycleRevision !== detail.release.lifecycleRevision || fresh.status !== "READY") throw new Error("Plugin distribution identity or authority changed before installation");
+		checkFiles(current, tree);
 	}
+	if (await adapter.detect(runNative, cwd) !== hostVersion) throw new Error("HOST_VERSION_CHANGED");
 	await artifactParent(storeRoot);
+	await mkdir(artifactContainer, { mode: 448 });
 	const operationId = await installNativePlugin({
 		input,
 		archive,
@@ -589,7 +1023,10 @@ async function runPluginPackage(args, globalOpts) {
 	console.log(JSON.stringify({
 		operationId,
 		identity,
-		verified: true
+		state: "REGISTERED",
+		registrationVerified: true,
+		loadStatus: "PENDING_HOST_RESTART",
+		message: "原生注册和文件归属已核对；请重启宿主确认组件加载，不代表业务功能测试通过。"
 	}, null, 2));
 }
 export { runPluginPackage };