@fastgpt-plugin/cli 0.1.0-beta.8 → 0.2.0-alpha.1

package/dist/index.js

@@ -8,8 +8,12 @@ import { build } from "tsdown";
 import z from "zod";
 import { input, select } from "@inquirer/prompts";
 import { kebabCase } from "es-toolkit";
-import { createHash, randomUUID } from "node:crypto";
 import fs$1, { createWriteStream } from "node:fs";
+import os from "node:os";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { Box, Text, render, useInput } from "ink";
+import React from "react";
+import { createHash, randomUUID } from "node:crypto";
 import { Readable } from "stream";
 import { Readable as Readable$1 } from "node:stream";
 import { ZipFile } from "yazl";
@@ -48,27 +52,6 @@ const PluginPermissionEnumSchema = z.enum([
 ]);
 const PluginPermissionEnum = PluginPermissionEnumSchema.enum;
 
-//#endregion
-//#region ../../packages/domain/src/value-objects/plugin.vo.ts
-const PluginUniqueIdSchema = z.object({
-	pluginId: z.string(),
-	version: z.string(),
-	etag: z.string()
-});
-const PluginSourceSchema = z.literal("system").or(z.string());
-const PluginTagListItemSchema = z.object({
-	id: z.string(),
-	name: I18nStringStrictSchema
-});
-const PluginTagListSchema = z.array(PluginTagListItemSchema);
-const PluginRuntimeModeSchema = z.enum(["localPool", "serverless"]);
-const PluginRuntimeModeEnum = PluginRuntimeModeSchema.enum;
-const UserPluginIdSchema = z.object({
-	pluginId: z.string(),
-	version: z.string().optional(),
-	source: PluginSourceSchema.optional()
-});
-
 //#endregion
 //#region ../../packages/domain/src/entities/plugin-base.entity.ts
 const PluginTagSchema = z.enum([
@@ -543,7 +526,7 @@ var CheckCommand = class extends BaseCommand {
 //#endregion
 //#region package.json
 var name = "@fastgpt-plugin/cli";
-var version = "0.1.0-beta.8";
+var version = "0.2.0-alpha.1";
 
 //#endregion
 //#region src/constants.ts
@@ -703,6 +686,301 @@ var CreateCommand = class extends BaseCommand {
 	}
 };
 
+//#endregion
+//#region src/debug/discover.ts
+const IGNORED_DIRS = new Set([
+	".build",
+	".fastgpt-plugin-debug",
+	".git",
+	".turbo",
+	".vite",
+	"coverage",
+	"dist",
+	"node_modules",
+	"__pack_output__"
+]);
+async function discoverDebugEntries(cwd = process.cwd()) {
+	const root = path.resolve(cwd);
+	if (await hasIndexFile(root)) return [root];
+	const children = await fs.readdir(root, { withFileTypes: true });
+	const entries = [];
+	for (const child of children) {
+		if (!child.isDirectory() || IGNORED_DIRS.has(child.name)) continue;
+		const candidate = path.join(root, child.name);
+		if (await hasIndexFile(candidate)) entries.push(candidate);
+	}
+	entries.sort();
+	if (entries.length === 0) throw new Error(`当前目录未发现可调试插件，请传入插件目录或在当前目录下放置 index.ts。`);
+	return entries;
+}
+async function hasIndexFile(dir) {
+	try {
+		return (await fs.stat(path.join(dir, "index.ts"))).isFile();
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/connection-gateway.vo.ts
+const ConnectionGatewayConsumerTypeSchema = z.string().min(1).max(64);
+const ConnectionGatewayTransportSchema = z.literal("websocket");
+const ConnectionGatewayCapabilitySchema = z.string().min(1).max(64);
+const ConnectionGatewaySessionScopeSchema = z.object({
+	userId: z.string().min(1),
+	teamId: z.string().min(1).optional(),
+	source: z.string().min(1).optional(),
+	sources: z.array(z.string().min(1)).optional()
+});
+const ConnectionGatewayTokenClaimsSchema = z.object({
+	consumerType: ConnectionGatewayConsumerTypeSchema,
+	subject: z.string().min(1),
+	sessionScope: ConnectionGatewaySessionScopeSchema,
+	transport: ConnectionGatewayTransportSchema,
+	capabilities: z.array(ConnectionGatewayCapabilitySchema).default([]),
+	expiresAt: z.number().int().positive(),
+	issuedAt: z.number().int().positive().optional(),
+	nonce: z.string().min(1).optional()
+});
+const ConnectionGatewayEnvelopeSchema = z.object({
+	protocol: z.literal("connection-gateway.v1"),
+	sessionId: z.string().min(1),
+	generation: z.number().int().nonnegative(),
+	requestId: z.string().min(1).optional(),
+	type: z.enum([
+		"request",
+		"response",
+		"event",
+		"stream"
+	]),
+	consumerType: ConnectionGatewayConsumerTypeSchema,
+	capability: ConnectionGatewayCapabilitySchema.optional(),
+	traceId: z.string().optional(),
+	payload: z.unknown().optional(),
+	createdAt: z.number().int().positive()
+});
+const ConnectionGatewayWsProtocolSchema = z.literal("connection-gateway.ws.v1");
+const ConnectionGatewayWsBindMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("bind"),
+	requestId: z.string().min(1),
+	token: z.string().min(1),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+const ConnectionGatewayWsEnvelopeMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("envelope"),
+	envelope: ConnectionGatewayEnvelopeSchema
+});
+const ConnectionGatewayWsHeartbeatMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("heartbeat"),
+	ts: z.number().int().positive()
+});
+const ConnectionGatewayWsErrorMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("error"),
+	requestId: z.string().min(1).optional(),
+	code: z.string().min(1),
+	message: z.string().min(1)
+});
+const ConnectionGatewayWsBoundMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("bound"),
+	requestId: z.string().min(1),
+	session: z.lazy(() => ConnectionGatewaySessionSchema)
+});
+const ConnectionGatewayWsClientMessageSchema = z.discriminatedUnion("type", [
+	ConnectionGatewayWsBindMessageSchema,
+	ConnectionGatewayWsEnvelopeMessageSchema,
+	ConnectionGatewayWsHeartbeatMessageSchema
+]);
+const ConnectionGatewayWsServerMessageSchema = z.discriminatedUnion("type", [
+	ConnectionGatewayWsBoundMessageSchema,
+	ConnectionGatewayWsEnvelopeMessageSchema,
+	ConnectionGatewayWsHeartbeatMessageSchema,
+	ConnectionGatewayWsErrorMessageSchema
+]);
+const ConnectionGatewaySessionStatusSchema = z.enum([
+	"connecting",
+	"connected",
+	"draining",
+	"closed"
+]);
+const ConnectionGatewaySessionSchema = z.object({
+	id: z.string().min(1),
+	consumerType: ConnectionGatewayConsumerTypeSchema,
+	subject: z.string().min(1),
+	sessionScope: ConnectionGatewaySessionScopeSchema,
+	transport: ConnectionGatewayTransportSchema,
+	capabilities: z.array(ConnectionGatewayCapabilitySchema),
+	generation: z.number().int().nonnegative(),
+	ownerNodeId: z.string().min(1),
+	status: ConnectionGatewaySessionStatusSchema,
+	connectedAt: z.number().int().positive(),
+	lastSeenAt: z.number().int().positive(),
+	expiresAt: z.number().int().positive(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+const ConnectionGatewaySessionStatusViewSchema = z.object({
+	session: ConnectionGatewaySessionSchema.nullable(),
+	ownerAlive: z.boolean(),
+	mailboxLag: z.number().int().nonnegative(),
+	logs: z.array(z.object({
+		ts: z.number().int().positive(),
+		level: z.enum([
+			"debug",
+			"info",
+			"warn",
+			"error"
+		]),
+		message: z.string(),
+		data: z.record(z.string(), z.unknown()).optional()
+	}))
+});
+const ConnectionGatewayMetricsSchema = z.object({
+	nodeId: z.string(),
+	activeConnections: z.number().int().nonnegative(),
+	activeSessions: z.number().int().nonnegative(),
+	inFlightRequests: z.number().int().nonnegative(),
+	streamBufferBytes: z.number().int().nonnegative(),
+	slowConsumers: z.number().int().nonnegative(),
+	ownerLeaseExpiries: z.number().int().nonnegative(),
+	mailbox: z.object({
+		lag: z.number().int().nonnegative(),
+		redisRoundTripMs: z.number().nonnegative()
+	}),
+	limits: z.object({
+		maxConnections: z.number().int().positive(),
+		maxSessionsPerSubject: z.number().int().positive(),
+		maxInFlightPerSession: z.number().int().positive(),
+		maxEnvelopeBytes: z.number().int().positive()
+	})
+});
+const ConnectionGatewayResourceLimitsSchema = z.object({
+	maxConnections: z.number().int().positive(),
+	maxSessionsPerSubject: z.number().int().positive(),
+	maxInFlightPerSession: z.number().int().positive(),
+	maxEnvelopeBytes: z.number().int().positive(),
+	slowConsumerBufferBytes: z.number().int().positive()
+});
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/system-var.vo.ts
+const SystemVarSchema = z.object({
+	app: z.object({
+		id: z.string(),
+		name: z.string()
+	}),
+	chat: z.object({
+		chatId: z.string(),
+		uid: z.string().optional()
+	}),
+	invokeToken: z.string(),
+	time: z.string()
+});
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/plugin.vo.ts
+const PluginUniqueIdSchema = z.object({
+	pluginId: z.string(),
+	version: z.string(),
+	etag: z.string()
+});
+const PluginSourceSchema = z.literal("system").or(z.string());
+const PluginTagListItemSchema = z.object({
+	id: z.string(),
+	name: I18nStringStrictSchema
+});
+const PluginTagListSchema = z.array(PluginTagListItemSchema);
+const PluginRuntimeModeSchema = z.enum(["localPool", "serverless"]);
+const PluginRuntimeModeEnum = PluginRuntimeModeSchema.enum;
+const UserPluginIdSchema = z.object({
+	pluginId: z.string(),
+	version: z.string().optional(),
+	source: PluginSourceSchema.optional()
+});
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/tool.vo.ts
+const ToolHandlerReturnSchema = z.record(z.string(), z.unknown());
+const StreamMessageTypeSchema = z.enum([
+	"response",
+	"error",
+	"stream"
+]);
+const StreamMessageTypeEnum = StreamMessageTypeSchema.enum;
+const StreamDataAnswerTypeSchema = z.enum(["answer", "fastAnswer"]);
+const StreamDataAnswerTypeEnum = StreamDataAnswerTypeSchema.enum;
+const ToolAnswerSchema = z.object({
+	type: StreamDataAnswerTypeSchema,
+	content: z.string()
+});
+const ToolStreamMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal(StreamMessageTypeEnum.response),
+		data: ToolHandlerReturnSchema
+	}),
+	z.object({
+		type: z.literal(StreamMessageTypeEnum.stream),
+		data: ToolAnswerSchema
+	}),
+	z.object({
+		type: z.literal(StreamMessageTypeEnum.error),
+		data: z.string()
+	})
+]);
+const ToolRunInputSchema = z.object({
+	pluginId: z.string(),
+	version: z.preprocess((value) => {
+		if (value === "") return void 0;
+		return value;
+	}, z.string().optional()),
+	source: PluginSourceSchema.optional(),
+	childId: z.string().optional(),
+	input: z.record(z.string(), z.unknown()),
+	secrets: z.record(z.string(), z.unknown()).optional(),
+	systemVar: SystemVarSchema
+});
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/connection-gateway-debug.vo.ts
+const CONNECTION_GATEWAY_PLUGIN_DEBUG_INVOKE_CAPABILITY = "invoke";
+const ConnectionGatewayPluginDebugRequestPayloadSchema = z.object({
+	kind: z.literal("plugin-debug.run"),
+	eventName: z.literal("run"),
+	payload: z.object({
+		pluginId: z.string().min(1).optional(),
+		input: z.record(z.string(), z.unknown()),
+		secrets: z.record(z.string(), z.unknown()).optional(),
+		systemVar: SystemVarSchema,
+		source: z.string().optional(),
+		childId: z.string().optional()
+	})
+});
+const ConnectionGatewayPluginDebugResponsePayloadSchema = z.discriminatedUnion("kind", [z.object({ kind: z.literal("plugin-debug.accepted") }), z.object({
+	kind: z.literal("plugin-debug.error"),
+	message: z.string(),
+	code: z.string().optional(),
+	data: z.unknown().optional()
+})]);
+const ConnectionGatewayPluginDebugStreamPayloadSchema = z.discriminatedUnion("event", [
+	z.object({
+		kind: z.literal("plugin-debug.stream"),
+		event: z.literal("chunk"),
+		data: ToolStreamMessageSchema
+	}),
+	z.object({
+		kind: z.literal("plugin-debug.stream"),
+		event: z.literal("end")
+	}),
+	z.object({
+		kind: z.literal("plugin-debug.stream"),
+		event: z.literal("error"),
+		message: z.string()
+	})
+]);
+
 //#endregion
 //#region src/debug/import-hooks.ts
 const SOURCE_EXTENSIONS = [
@@ -892,7 +1170,10 @@ const InvokeUploadFileInputSchema = z.object({ ...FileCreateSchema.omit({
 	overwrite: true,
 	path: true
 }).shape });
-const InvokeUploadFileOutputSchema = z.object({ accessURL: z.string() });
+const InvokeUploadFileOutputSchema = z.object({
+	...FileMetaSchema.omit({ fileKey: true }).partial().shape,
+	accessURL: z.string()
+});
 const InvokeUserInfoOutputSchema = z.object({
 	username: z.string(),
 	contact: z.string().nullish(),
@@ -903,9 +1184,17 @@ const InvokeUserInfoOutputSchema = z.object({
 	})),
 	groups: z.array(z.object({ name: z.string() }))
 });
-const InvokeMethodEnumSchema = z.enum(["uploadFile", "userInfo"]);
+const InvokeMethodEnumSchema = z.enum([
+	"uploadFile",
+	"userInfo",
+	"wecomCorpToken"
+]);
 const InvokeMethodEnum = InvokeMethodEnumSchema.enum;
 
+//#endregion
+//#region ../../packages/domain/src/value-objects/result.vo.ts
+const successResult = (data) => [data, null];
+
 //#endregion
 //#region ../../packages/domain/src/value-objects/stream.vo.ts
 var StreamData = class StreamData {
@@ -966,63 +1255,6 @@ var StreamData = class StreamData {
 	}
 };
 
-//#endregion
-//#region ../../packages/domain/src/value-objects/system-var.vo.ts
-const SystemVarSchema = z.object({
-	app: z.object({
-		id: z.string(),
-		name: z.string()
-	}),
-	chat: z.object({
-		chatId: z.string(),
-		uid: z.string().optional()
-	}),
-	invokeToken: z.string(),
-	time: z.string()
-});
-
-//#endregion
-//#region ../../packages/domain/src/value-objects/tool.vo.ts
-const ToolHandlerReturnSchema = z.record(z.string(), z.unknown());
-const StreamMessageTypeSchema = z.enum([
-	"response",
-	"error",
-	"stream"
-]);
-const StreamMessageTypeEnum = StreamMessageTypeSchema.enum;
-const StreamDataAnswerTypeSchema = z.enum(["answer", "fastAnswer"]);
-const StreamDataAnswerTypeEnum = StreamDataAnswerTypeSchema.enum;
-const ToolAnswerSchema = z.object({
-	type: StreamDataAnswerTypeSchema,
-	content: z.string()
-});
-const ToolStreamMessageSchema = z.discriminatedUnion("type", [
-	z.object({
-		type: z.literal(StreamMessageTypeEnum.response),
-		data: ToolHandlerReturnSchema
-	}),
-	z.object({
-		type: z.literal(StreamMessageTypeEnum.stream),
-		data: ToolAnswerSchema
-	}),
-	z.object({
-		type: z.literal(StreamMessageTypeEnum.error),
-		data: z.string()
-	})
-]);
-const ToolRunInputSchema = z.object({
-	pluginId: z.string(),
-	version: z.preprocess((value) => {
-		if (value === "") return void 0;
-		return value;
-	}, z.string().optional()),
-	source: PluginSourceSchema.optional(),
-	childId: z.string().optional(),
-	input: z.record(z.string(), z.unknown()),
-	secrets: z.record(z.string(), z.unknown()).optional(),
-	systemVar: SystemVarSchema
-});
-
 //#endregion
 //#region ../../packages/infrastructure/src/plugin/plugin-runtime/ports/channel/event/client.ts
 /**
@@ -1160,7 +1392,9 @@ const PluginChannelMessageIdSchema = z.union([z.string(), z.number()]);
 const PluginChannelErrorSchema = z.object({
 	code: z.string(),
 	message: z.string(),
-	data: z.unknown().optional()
+	reason: I18nStringSchema.optional(),
+	data: z.unknown().optional(),
+	cause: z.lazy(() => PluginChannelErrorSchema).optional()
 });
 /**
 * request message：需要对端返回 success/error。
@@ -1456,7 +1690,7 @@ function createIncomingStream({ source, streamName, streamId, traceId, meta }) {
 	};
 }
 function toStreamData(source) {
-	if (source instanceof StreamData) return source;
+	if (isStreamDataLike$1(source)) return source;
 	const output = StreamData.create();
 	(async () => {
 		try {
@@ -1468,6 +1702,9 @@ function toStreamData(source) {
 	})();
 	return output;
 }
+function isStreamDataLike$1(source) {
+	return source instanceof StreamData || typeof source === "object" && source !== null && typeof source.values === "function" && typeof source.consume === "function";
+}
 
 //#endregion
 //#region src/debug/session.ts
@@ -1616,14 +1853,14 @@ function createVirtualHostHandler(uploadDir) {
 				const outputPath = path.join(saveDir, `${Date.now()}-${randomUUID().slice(0, 8)}-${fileName}`);
 				await fs.mkdir(saveDir, { recursive: true });
 				await fs.writeFile(outputPath, buffer);
-				return {
+				return successResult({
 					fileName,
 					contentType,
 					size: buffer.length,
 					etag: createHash("md5").update(buffer).digest("hex"),
 					createTime: /* @__PURE__ */ new Date(),
 					accessURL: pathToFileURL(outputPath).href
-				};
+				});
 			}
 			default: throw new Error(`本地虚拟环境暂不支持反向调用: ${String(method)}`);
 		}
@@ -1632,10 +1869,13 @@ function createVirtualHostHandler(uploadDir) {
 async function readSourceToBuffer(source) {
 	if (!source) return Buffer.alloc(0);
 	const chunks = [];
-	const iterable = source instanceof StreamData ? source.values() : source;
+	const iterable = isStreamDataLike(source) ? source.values() : source;
 	for await (const chunk of iterable) chunks.push(toBuffer(chunk));
 	return Buffer.concat(chunks);
 }
+function isStreamDataLike(source) {
+	return source instanceof StreamData || typeof source === "object" && source !== null && typeof source.values === "function" && typeof source.consume === "function";
+}
 function toBuffer(value) {
 	if (Buffer.isBuffer(value)) return value;
 	if (value instanceof Uint8Array) return Buffer.from(value);
@@ -1703,22 +1943,960 @@ async function assertPathExists(targetPath, message) {
 	}
 }
 
+//#endregion
+//#region src/debug/gateway.ts
+async function connectDebugGateway({ targets, options, onLog }) {
+	if (targets.length === 0) throw new Error("Gateway debug targets cannot be empty");
+	if (options.reconnect) return connectReconnectingDebugGateway({
+		targets,
+		options,
+		onLog
+	});
+	return connectSingleDebugGateway({
+		targets,
+		options,
+		onLog
+	});
+}
+async function connectReconnectingDebugGateway({ targets, options, onLog }) {
+	let closed = false;
+	let current = null;
+	let currentSession = null;
+	let latestTargets = targets;
+	const intervalMs = Math.max(100, options.reconnectIntervalMs ?? 2e3);
+	const closedPromise = (async () => {
+		while (!closed) {
+			try {
+				current = await connectSingleDebugGateway({
+					targets: latestTargets,
+					options,
+					onLog
+				});
+				currentSession = current.session;
+				await current.closed;
+			} catch (error) {
+				if (closed) return;
+				onLog?.(`Connection Gateway 调试通道断开: ${formatErrorMessage(error)}`);
+			} finally {
+				current = null;
+			}
+			if (!closed) {
+				onLog?.(`将在 ${intervalMs}ms 后重连 Connection Gateway。`);
+				await delay(intervalMs);
+			}
+		}
+	})();
+	while (!currentSession && !closed) await delay(10);
+	if (!currentSession) throw new Error("Connection Gateway debug session was closed before connecting");
+	return {
+		session: currentSession,
+		updateTargets(targets) {
+			latestTargets = targets;
+			current?.updateTargets(targets);
+		},
+		close() {
+			closed = true;
+			current?.close();
+		},
+		closed: closedPromise
+	};
+}
+async function connectSingleDebugGateway({ targets, options, onLog }) {
+	const socket = await openWebSocket(options.gatewayUrl);
+	let targetsByPluginId = createTargetsByPluginId(targets);
+	let closed = false;
+	let session = null;
+	let boundResolve;
+	let boundReject;
+	const bound = new Promise((resolve, reject) => {
+		boundResolve = resolve;
+		boundReject = reject;
+	});
+	const closedPromise = new Promise((resolve) => {
+		socket.addEventListener("close", () => {
+			closed = true;
+			resolve();
+		});
+		socket.addEventListener("error", () => {
+			onLog?.("Connection Gateway WebSocket 错误");
+		});
+	});
+	socket.addEventListener("message", (event) => {
+		const message = parseWsServerMessage(event.data);
+		if (message.type === "bound") {
+			session = message.session;
+			boundResolve(message.session);
+			return;
+		}
+		if (message.type === "heartbeat") return;
+		if (message.type === "error") {
+			const error = new Error(message.message);
+			if (!session) boundReject(error);
+			onLog?.(`Connection Gateway 错误: ${message.code} ${message.message}`);
+			return;
+		}
+		if (message.type === "envelope") {
+			const envelope = message.envelope;
+			if (!session) {
+				boundReject(/* @__PURE__ */ new Error("Gateway envelope received before session bound"));
+				return;
+			}
+			handleGatewayEnvelope({
+				socket,
+				session,
+				targetsByPluginId,
+				envelope,
+				onLog
+			}).catch(async (error) => {
+				if (session) await sendEnvelope(socket, makeErrorEnvelope(session, envelope, error));
+			});
+		}
+	});
+	await sendMessage(socket, {
+		protocol: "connection-gateway.ws.v1",
+		type: "bind",
+		requestId: randomUUID(),
+		token: options.connectToken,
+		metadata: makePluginDebugMetadata(targets, options.source)
+	}).catch(async (error) => {
+		socket.close();
+		throw error;
+	});
+	const boundSession = await bound;
+	onLog?.(`已连接 Connection Gateway session: ${boundSession.id}`);
+	return {
+		session: boundSession,
+		updateTargets(targets) {
+			targetsByPluginId = createTargetsByPluginId(targets);
+			onLog?.(`已热更新本地调试插件: ${targets.map((target) => target.snapshot.pluginId).join(", ")}`);
+		},
+		close() {
+			if (!closed) socket.close();
+		},
+		closed: closedPromise
+	};
+}
+function createTargetsByPluginId(targets) {
+	return new Map(targets.map((target) => [target.snapshot.pluginId, target]));
+}
+async function handleGatewayEnvelope({ socket, session, targetsByPluginId, envelope, onLog }) {
+	if (envelope.type !== "request") return;
+	const request = ConnectionGatewayPluginDebugRequestPayloadSchema.parse(envelope.payload);
+	const source = request.payload.source ?? session.sessionScope.source;
+	if (!source) throw new Error("Gateway debug request missing source");
+	const pluginId = request.payload.pluginId;
+	if (!pluginId) throw new Error("Gateway debug request missing pluginId");
+	const target = targetsByPluginId.get(pluginId);
+	if (!target) throw new Error(`Gateway debug target not found: ${source} ${pluginId}`);
+	onLog?.(`收到远程调试请求: ${source} ${pluginId} ${envelope.requestId ?? "-"}`);
+	await sendEnvelope(socket, {
+		protocol: "connection-gateway.v1",
+		sessionId: session.id,
+		generation: session.generation,
+		requestId: requiredRequestId(envelope),
+		type: "response",
+		consumerType: session.consumerType,
+		capability: CONNECTION_GATEWAY_PLUGIN_DEBUG_INVOKE_CAPABILITY,
+		traceId: envelope.traceId,
+		createdAt: Date.now(),
+		payload: { kind: "plugin-debug.accepted" }
+	});
+	const result = await runDebugTool({
+		runtime: target.runtime,
+		snapshot: target.snapshot,
+		toolId: request.payload.childId,
+		input: request.payload.input,
+		secrets: request.payload.secrets,
+		systemVar: request.payload.systemVar
+	});
+	for (const message of result.streamMessages) await sendStreamChunk(socket, session, envelope, message);
+	await sendEnvelope(socket, {
+		protocol: "connection-gateway.v1",
+		sessionId: session.id,
+		generation: session.generation,
+		requestId: requiredRequestId(envelope),
+		type: "stream",
+		consumerType: session.consumerType,
+		capability: CONNECTION_GATEWAY_PLUGIN_DEBUG_INVOKE_CAPABILITY,
+		traceId: envelope.traceId,
+		createdAt: Date.now(),
+		payload: {
+			kind: "plugin-debug.stream",
+			event: "end"
+		}
+	});
+}
+async function sendStreamChunk(socket, session, request, message) {
+	await sendEnvelope(socket, {
+		protocol: "connection-gateway.v1",
+		sessionId: session.id,
+		generation: session.generation,
+		requestId: requiredRequestId(request),
+		type: "stream",
+		consumerType: session.consumerType,
+		capability: CONNECTION_GATEWAY_PLUGIN_DEBUG_INVOKE_CAPABILITY,
+		traceId: request.traceId,
+		createdAt: Date.now(),
+		payload: {
+			kind: "plugin-debug.stream",
+			event: "chunk",
+			data: ToolStreamMessageSchema.parse(message)
+		}
+	});
+}
+function makeErrorEnvelope(session, request, error) {
+	return {
+		protocol: "connection-gateway.v1",
+		sessionId: session.id,
+		generation: session.generation,
+		requestId: request.requestId,
+		type: "stream",
+		consumerType: session.consumerType,
+		capability: CONNECTION_GATEWAY_PLUGIN_DEBUG_INVOKE_CAPABILITY,
+		traceId: request.traceId,
+		createdAt: Date.now(),
+		payload: {
+			kind: "plugin-debug.stream",
+			event: "error",
+			message: error instanceof Error ? error.message : String(error)
+		}
+	};
+}
+function makePluginDebugMetadata(targets, source) {
+	return { pluginDebug: { targets: targets.map((target) => ({
+		source,
+		pluginId: target.snapshot.pluginId,
+		version: target.snapshot.version,
+		name: target.snapshot.name,
+		description: target.snapshot.description,
+		toolDescription: target.snapshot.toolDescription,
+		author: target.snapshot.author,
+		tags: target.snapshot.tags,
+		permissions: target.snapshot.permissions,
+		secretSchema: target.snapshot.secretSchema,
+		isToolSet: target.snapshot.isToolSet,
+		tools: target.snapshot.tools
+	})) } };
+}
+async function openWebSocket(url) {
+	return new Promise((resolve, reject) => {
+		const socket = new WebSocket(url);
+		socket.addEventListener("open", () => {
+			resolve(socket);
+		}, { once: true });
+		socket.addEventListener("error", () => {
+			reject(/* @__PURE__ */ new Error(`Connection Gateway WebSocket connect failed: ${url}`));
+		}, { once: true });
+	});
+}
+async function sendEnvelope(socket, envelope) {
+	await sendMessage(socket, {
+		protocol: "connection-gateway.ws.v1",
+		type: "envelope",
+		envelope
+	});
+}
+async function sendMessage(socket, message) {
+	if (socket.readyState !== WebSocket.OPEN) throw new Error("Connection Gateway WebSocket is not open");
+	socket.send(JSON.stringify(message));
+}
+function requiredRequestId(envelope) {
+	if (!envelope.requestId) throw new Error("Gateway request envelope missing requestId");
+	return envelope.requestId;
+}
+function delay(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+function formatErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function parseWsServerMessage(data) {
+	const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? Buffer.from(data).toString("utf8") : ArrayBuffer.isView(data) ? Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8") : String(data);
+	return ConnectionGatewayWsServerMessageSchema.parse(JSON.parse(text));
+}
+
+//#endregion
+//#region src/debug/remote-session.ts
+async function runRemoteDebugSession({ entriesInput, options, commandName, migrationHint }) {
+	if (migrationHint) logger.warn(migrationHint);
+	if (options.watch) {
+		await runWatchRemoteDebugSession({
+			entriesInput,
+			options,
+			commandName
+		});
+		return;
+	}
+	await runRemoteDebugSessionOnce({
+		entriesInput,
+		options,
+		commandName
+	});
+}
+async function runRemoteDebugSessionOnce({ entriesInput, options, commandName }) {
+	const targets = await loadTargets(await resolveDebugEntries(entriesInput), options);
+	await ensureConnectLink({
+		options,
+		commandName,
+		targets
+	});
+	const gatewayOptions = await resolveGatewayOptions({
+		options,
+		commandName,
+		targets
+	});
+	const reporter = createRemoteDebugReporter({
+		commandName,
+		options,
+		gatewayOptions,
+		targets
+	});
+	reporter.start();
+	try {
+		const gateway = await connectDebugGateway({
+			targets,
+			options: gatewayOptions,
+			onLog: (message) => reporter.log(`[gateway] ${message}`)
+		});
+		reporter.attachClose(({ force }) => {
+			gateway.close();
+			if (force) process.exit(130);
+		});
+		const source = gateway.session.sessionScope.source ?? gatewayOptions.source ?? "-";
+		reporter.ready(source);
+		await gateway.closed;
+	} finally {
+		await reporter.end();
+	}
+}
+async function runWatchRemoteDebugSession({ entriesInput, options, commandName }) {
+	const entries = await resolveDebugEntries(entriesInput);
+	const initialTargets = await loadTargets(entries, options);
+	await ensureConnectLink({
+		options,
+		commandName,
+		targets: initialTargets
+	});
+	const gatewayOptions = await resolveGatewayOptions({
+		options,
+		commandName,
+		targets: initialTargets
+	});
+	const reporter = createRemoteDebugReporter({
+		commandName,
+		options,
+		gatewayOptions,
+		targets: initialTargets
+	});
+	let reloadRunning = false;
+	let reloadPending = false;
+	let closed = false;
+	let gateway;
+	const reloadTargets = async () => {
+		if (reloadRunning) {
+			reloadPending = true;
+			return;
+		}
+		reloadRunning = true;
+		try {
+			do {
+				reloadPending = false;
+				try {
+					const nextTargets = await loadTargets(entries, options);
+					gateway?.updateTargets(nextTargets);
+					reporter.log(`检测到插件文件变化，已热更新 ${nextTargets.length} 个本地插件。`);
+				} catch (error) {
+					reporter.log(`插件热更新失败: ${formatConnectionKeyExchangeError(error)}`);
+				}
+			} while (reloadPending && !closed);
+		} finally {
+			reloadRunning = false;
+		}
+	};
+	const watcher = watchDebugEntries(entries, () => {
+		reloadTargets();
+	});
+	reporter.start();
+	try {
+		const connectedGateway = await connectDebugGateway({
+			targets: initialTargets,
+			options: gatewayOptions,
+			onLog: (message) => reporter.log(`[gateway] ${message}`)
+		});
+		gateway = connectedGateway;
+		reporter.attachClose(({ force }) => {
+			closed = true;
+			watcher.close();
+			connectedGateway.close();
+			if (force) process.exit(130);
+		});
+		const source = connectedGateway.session.sessionScope.source ?? gatewayOptions.source ?? "-";
+		reporter.ready(source);
+		await connectedGateway.closed;
+	} finally {
+		closed = true;
+		watcher.close();
+		await reporter.end();
+	}
+}
+async function resolveDebugEntries(entriesInput) {
+	const entries = (Array.isArray(entriesInput) ? entriesInput : [entriesInput]).filter((entry) => entry.trim().length > 0);
+	if (entries.length > 0) return entries.map((entry) => path.resolve(entry));
+	const discovered = await discoverDebugEntries();
+	logger.info([`自动发现 ${discovered.length} 个可调试插件:`, ...discovered.map((entry) => `  - ${entry}`)].join("\n"));
+	return discovered;
+}
+async function loadTargets(entries, options) {
+	const targets = [];
+	for (const [index, entryDir] of entries.entries()) {
+		const session = await loadDebugSession({
+			entryDir,
+			uploadDir: resolveUploadDir({
+				entryDir,
+				index,
+				total: entries.length,
+				uploadDir: options.uploadDir
+			})
+		});
+		targets.push({
+			runtime: session.runtime,
+			snapshot: session.snapshot
+		});
+	}
+	const duplicatePluginIds = findDuplicateValues$1(targets.map((target) => target.snapshot.pluginId));
+	if (duplicatePluginIds.length > 0) throw new Error(`gateway pluginId 重复: ${duplicatePluginIds.join(", ")}`);
+	return targets;
+}
+function watchDebugEntries(entries, onChange) {
+	const watchers = entries.map((entry) => fsWatch(entry, {
+		recursive: true,
+		onChange
+	}));
+	return { close() {
+		watchers.forEach((watcher) => watcher.close());
+	} };
+}
+function fsWatch(dir, { recursive, onChange }) {
+	let timer;
+	const watcher = fs$1.watch(dir, { recursive }, () => {
+		clearTimeout(timer);
+		timer = setTimeout(onChange, 150);
+	});
+	return { close() {
+		clearTimeout(timer);
+		watcher.close();
+	} };
+}
+function createRemoteDebugReporter({ commandName, options, gatewayOptions, targets }) {
+	const summary = {
+		commandName,
+		mode: "FastGPT connection key",
+		gateway: gatewayOptions.gatewayUrl,
+		reconnect: gatewayOptions.reconnect === false ? "off" : "on",
+		targets: targets.map((target) => target.snapshot)
+	};
+	return options.interactive !== false && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY) ? new TuiRemoteDebugReporter(summary) : new PlainRemoteDebugReporter(summary);
+}
+async function ensureConnectLink({ options, commandName, targets }) {
+	if (options.connect) return;
+	const savedConnect = await readSavedConnectionKey();
+	if (savedConnect) {
+		options.connect = savedConnect;
+		options.connectPersistOnSuccess = true;
+		logger.info(`已读取本地 FastGPT connection key 配置: ${getCliConfigPath()}`);
+		return;
+	}
+	if (options.interactive === false || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("dev 需要 --connect，或在交互式终端中输入 FastGPT connection key。");
+	options.connect = await promptConnectLink({
+		commandName,
+		targets
+	});
+	options.connectPersistOnSuccess = true;
+}
+async function promptConnectLink({ commandName, targets, defaultValue, errorMessage }) {
+	process.stdout.write([
+		"\x1B[?25h\x1B[2J\x1B[HFastGPT Plugin Dev",
+		"",
+		`Command   fastgpt-plugin ${commandName}`,
+		"Mode      waiting for FastGPT connection key",
+		"Status    pending",
+		"",
+		"Plugins",
+		...targets.map((target) => `  ${target.snapshot.pluginId}@${target.snapshot.version}`),
+		"",
+		...errorMessage ? [`Last error ${errorMessage}`, ""] : [],
+		"Paste the FastGPT connection key or connect link to start the WSS debug session.",
+		""
+	].join("\n"));
+	return (await input({
+		message: "FastGPT connection key",
+		default: defaultValue,
+		prefill: defaultValue ? "editable" : void 0,
+		validate(value) {
+			return value.trim().length > 0 || "请输入 FastGPT connection key";
+		}
+	})).trim();
+}
+async function readSavedConnectionKey() {
+	return (await readCliConfig()).debug?.connectionKey?.trim() || void 0;
+}
+async function saveConnectionKey(connectionKey) {
+	const trimmed = connectionKey.trim();
+	if (!trimmed) return;
+	const configPath = getCliConfigPath();
+	const config = await readCliConfig();
+	const nextConfig = {
+		...config,
+		debug: {
+			...config.debug,
+			connectionKey: trimmed
+		}
+	};
+	await fs.mkdir(path.dirname(configPath), {
+		recursive: true,
+		mode: 448
+	});
+	await fs.writeFile(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, {
+		encoding: "utf-8",
+		mode: 384
+	});
+}
+async function readCliConfig() {
+	const configPath = getCliConfigPath();
+	let raw;
+	try {
+		raw = await fs.readFile(configPath, "utf-8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return {};
+		throw error;
+	}
+	if (!raw.trim()) return {};
+	return CliConfigSchema.parse(JSON.parse(raw));
+}
+function getCliConfigPath() {
+	return path.join(getCliConfigDir(), CLI_CONFIG_FILE_NAME);
+}
+function getCliConfigDir() {
+	const xdgConfigHome = process.env.XDG_CONFIG_HOME?.trim();
+	if (xdgConfigHome) return path.join(xdgConfigHome, CLI_CONFIG_DIR_NAME);
+	return path.join(os.homedir(), ".config", CLI_CONFIG_DIR_NAME);
+}
+function isNodeError(error) {
+	return error instanceof Error && "code" in error;
+}
+function formatTargetLine(snapshot) {
+	const tools = snapshot.tools.map((tool) => tool.id).join(", ") || "-";
+	return `    - ${snapshot.pluginId}@${snapshot.version} tools=[${tools}] entry=${snapshot.entryDir}`;
+}
+const CLI_CONFIG_FILE_NAME = "config.json";
+const CLI_CONFIG_DIR_NAME = "fastgpt-plugin";
+const CliConfigSchema = z.object({ debug: z.object({ connectionKey: z.string().min(1).optional() }).optional() }).passthrough();
+var PlainRemoteDebugReporter = class {
+	constructor(summary) {
+		this.summary = summary;
+	}
+	start() {
+		logger.info([
+			"FastGPT 插件开发会话",
+			`  command: fastgpt-plugin ${this.summary.commandName}`,
+			`  mode: ${this.summary.mode}`,
+			"  ui: plain",
+			`  gateway: ${this.summary.gateway}`,
+			`  reconnect: ${this.summary.reconnect}`,
+			"  plugins:",
+			...this.summary.targets.map(formatTargetLine)
+		].join("\n"));
+	}
+	log(message) {
+		logger.info(message);
+	}
+	ready(source) {
+		this.summary.targets.forEach((target) => {
+			logger.success(`远程调试已就绪: ${source} ${target.pluginId}`);
+		});
+		logger.info(`已建立 1 个远程调试通道，挂载 ${this.summary.targets.length} 个插件，按 Ctrl+C 停止。`);
+	}
+	attachClose() {}
+	end() {
+		logger.info("远程调试会话已结束。");
+	}
+};
+var TuiRemoteDebugReporter = class {
+	status = "connecting";
+	source = "-";
+	logs = [];
+	instance;
+	closeSession;
+	interruptCount = 0;
+	onSigint = () => {
+		this.requestClose("ctrl-c");
+	};
+	requestClose = (reason) => {
+		if (reason === "q") {
+			this.log("收到退出指令，正在关闭远程调试会话。");
+			this.closeSession?.({ force: false });
+			return;
+		}
+		this.interruptCount += 1;
+		const force = this.interruptCount >= 2;
+		this.status = force ? "closed" : "closing";
+		this.log(force ? "再次收到 Ctrl+C，正在强制退出。" : "收到 Ctrl+C，正在关闭远程调试会话。再次按 Ctrl+C 强制退出。");
+		this.closeSession?.({ force });
+		if (force && !this.closeSession) process.exit(130);
+	};
+	constructor(summary) {
+		this.summary = summary;
+	}
+	start() {
+		process.on("SIGINT", this.onSigint);
+		this.instance = render(this.createApp(), {
+			stdin: process.stdin,
+			stdout: process.stdout,
+			stderr: process.stderr,
+			exitOnCtrlC: false,
+			interactive: true,
+			patchConsole: false
+		});
+	}
+	log(message) {
+		this.logs.push({
+			at: /* @__PURE__ */ new Date(),
+			message
+		});
+		this.logs = this.logs.slice(-6);
+		this.rerender();
+	}
+	ready(source) {
+		this.status = "connected";
+		this.source = source;
+		this.log(`远程调试已就绪，挂载 ${this.summary.targets.length} 个插件。`);
+	}
+	attachClose(close) {
+		this.closeSession = close;
+	}
+	async end() {
+		process.off("SIGINT", this.onSigint);
+		this.status = "closed";
+		this.rerender();
+		const instance = this.instance;
+		this.instance = void 0;
+		if (instance) {
+			await Promise.race([instance.waitUntilRenderFlush(), setTimeout$1(50)]).catch(() => void 0);
+			instance.unmount();
+			await Promise.race([instance.waitUntilExit(), setTimeout$1(50)]).catch(() => void 0);
+		}
+		logger.info("远程调试会话已结束。");
+	}
+	rerender() {
+		this.instance?.rerender(this.createApp());
+	}
+	createApp() {
+		return React.createElement(RemoteDebugInkApp, {
+			summary: this.summary,
+			status: this.status,
+			source: this.source,
+			logs: this.logs,
+			onQuit: this.requestClose
+		});
+	}
+};
+function RemoteDebugInkApp({ summary, status, source, logs, onQuit }) {
+	useInput((inputValue, key) => {
+		if (key.ctrl && inputValue === "c") {
+			onQuit("ctrl-c");
+			return;
+		}
+		if (inputValue === "q") onQuit("q");
+	});
+	const statusMeta = getTuiStatusMeta(status);
+	const sourceLabel = source === "-" ? "waiting for bind" : source;
+	const rows = [
+		["command", `fastgpt-plugin ${summary.commandName}`],
+		["gateway", summary.gateway],
+		["source", sourceLabel],
+		["reconnect", summary.reconnect === "on" ? "enabled" : "disabled"]
+	];
+	const plugins = summary.targets.map((target) => {
+		const toolCount = target.tools.length;
+		return {
+			id: `${target.pluginId}:${target.version}`,
+			name: `${target.pluginId}@${target.version}`,
+			tools: toolCount === 1 ? "1 tool" : `${toolCount} tools`,
+			entry: target.entryDir
+		};
+	});
+	const activityItems = logs.length > 0 ? logs.map((entry, index) => React.createElement(Box, {
+		key: `${entry.at.getTime()}:${index}`,
+		flexDirection: "row"
+	}, React.createElement(Text, { color: "gray" }, formatTuiTime(entry.at)), React.createElement(Text, { dimColor: true }, "  │  "), React.createElement(Text, { wrap: "truncate-end" }, entry.message))) : [React.createElement(Text, {
+		key: "empty-log",
+		dimColor: true
+	}, "waiting for gateway events")];
+	return React.createElement(Box, {
+		flexDirection: "column",
+		paddingX: 1,
+		paddingY: 1
+	}, React.createElement(Box, {
+		borderStyle: "round",
+		borderColor: statusMeta.borderColor,
+		paddingX: 2,
+		paddingY: 1,
+		flexDirection: "column"
+	}, React.createElement(Box, { justifyContent: "space-between" }, React.createElement(Box, null, React.createElement(Text, {
+		bold: true,
+		color: "cyanBright"
+	}, "FastGPT Plugin Dev"), React.createElement(Text, { dimColor: true }, "  remote debug")), React.createElement(Box, null, React.createElement(Text, {
+		color: statusMeta.color,
+		bold: true
+	}, statusMeta.label), React.createElement(Text, { dimColor: true }, `  ${plugins.length} plugins`))), React.createElement(Box, { marginTop: 1 }, React.createElement(Text, { color: statusMeta.color }, statusMeta.marker), React.createElement(Text, { dimColor: true }, "  "), React.createElement(Text, { wrap: "truncate-end" }, statusMeta.description))), React.createElement(Box, {
+		marginTop: 1,
+		columnGap: 1
+	}, React.createElement(Box, {
+		borderStyle: "round",
+		borderColor: "gray",
+		paddingX: 1,
+		paddingY: 1,
+		flexDirection: "column",
+		width: "50%"
+	}, React.createElement(Text, { bold: true }, "Session"), React.createElement(Box, {
+		flexDirection: "column",
+		marginTop: 1
+	}, ...rows.map(([label, value]) => React.createElement(SessionRow, {
+		key: label,
+		label,
+		value
+	})))), React.createElement(Box, {
+		borderStyle: "round",
+		borderColor: "gray",
+		paddingX: 1,
+		paddingY: 1,
+		flexDirection: "column",
+		width: "50%"
+	}, React.createElement(Box, { justifyContent: "space-between" }, React.createElement(Text, { bold: true }, "Plugins"), React.createElement(Text, { dimColor: true }, `${plugins.length} mounted`)), React.createElement(Box, {
+		flexDirection: "column",
+		marginTop: 1
+	}, ...plugins.map((plugin, index) => React.createElement(Box, {
+		key: plugin.id,
+		flexDirection: "column",
+		marginTop: index === 0 ? 0 : 1
+	}, React.createElement(Box, null, React.createElement(Text, { color: "greenBright" }, "● "), React.createElement(Text, {
+		bold: true,
+		wrap: "truncate-end"
+	}, plugin.name), React.createElement(Text, { dimColor: true }, `  ${plugin.tools}`)), React.createElement(Text, {
+		dimColor: true,
+		wrap: "truncate-end"
+	}, `  ${plugin.entry}`)))))), React.createElement(Box, {
+		borderStyle: "round",
+		borderColor: "gray",
+		paddingX: 1,
+		paddingY: 1,
+		flexDirection: "column",
+		marginTop: 1
+	}, React.createElement(Box, { justifyContent: "space-between" }, React.createElement(Text, { bold: true }, "Activity"), React.createElement(Text, { dimColor: true }, "latest 6 events")), React.createElement(Box, {
+		flexDirection: "column",
+		marginTop: 1
+	}, ...activityItems)), React.createElement(Box, {
+		marginTop: 1,
+		justifyContent: "space-between"
+	}, React.createElement(Text, { dimColor: true }, "q stop"), React.createElement(Text, { dimColor: true }, "Ctrl+C stop · second Ctrl+C force exit")));
+}
+function getTuiStatusMeta(status) {
+	if (status === "connected") return {
+		label: "CONNECTED",
+		marker: "●",
+		description: "Gateway channel is live and ready to receive FastGPT invocations.",
+		color: "greenBright",
+		borderColor: "green"
+	};
+	if (status === "closed") return {
+		label: "CLOSED",
+		marker: "■",
+		description: "Remote debug session has been closed.",
+		color: "gray",
+		borderColor: "gray"
+	};
+	if (status === "closing") return {
+		label: "CLOSING",
+		marker: "◆",
+		description: "Closing gateway channel. Press Ctrl+C again to force exit.",
+		color: "yellowBright",
+		borderColor: "yellow"
+	};
+	return {
+		label: "CONNECTING",
+		marker: "◆",
+		description: "Binding local plugins to the FastGPT connection gateway.",
+		color: "yellowBright",
+		borderColor: "yellow"
+	};
+}
+function SessionRow({ label, value }) {
+	return React.createElement(Box, null, React.createElement(Text, { color: "gray" }, label.padEnd(10)), React.createElement(Text, { wrap: "truncate-end" }, value));
+}
+function formatTuiTime(value) {
+	return [
+		value.getHours().toString().padStart(2, "0"),
+		value.getMinutes().toString().padStart(2, "0"),
+		value.getSeconds().toString().padStart(2, "0")
+	].join(":");
+}
+async function resolveGatewayOptions({ options, commandName, targets }) {
+	if (!options.connect) throw new Error("dev 需要 --connect 来建立远程调试通道。");
+	while (true) try {
+		const gatewayOptions = await resolveConnectGatewayOptions(options);
+		if (options.connectPersistOnSuccess === true) {
+			await saveConnectionKey(options.connect);
+			logger.info(`已保存 FastGPT connection key 到本地配置: ${getCliConfigPath()}`);
+			options.connectPersistOnSuccess = false;
+		}
+		return gatewayOptions;
+	} catch (error) {
+		const errorMessage = formatConnectionKeyExchangeError(error);
+		if (!canPromptForConnectInput(options)) throw error;
+		logger.error(errorMessage);
+		options.connect = await promptConnectLink({
+			commandName,
+			targets,
+			defaultValue: options.connect,
+			errorMessage
+		});
+		options.connectPersistOnSuccess = true;
+	}
+}
+function canPromptForConnectInput(options) {
+	return options.interactive !== false && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+function formatConnectionKeyExchangeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function resolveConnectGatewayOptions(options) {
+	const info = await exchangeConnectLink(options.connect);
+	return {
+		gatewayUrl: normalizeGatewayWsUrl(info.gatewayUrl),
+		connectToken: info.connectToken,
+		userId: info.tmbId,
+		source: info.source,
+		tokenTtlMs: Math.max(1, info.expiresAt - Date.now()),
+		reconnect: options.noReconnect ? false : options.reconnect ?? true,
+		reconnectIntervalMs: toPositiveInt(options.reconnectIntervalMs ?? process.env.CONNECTION_GATEWAY_RECONNECT_INTERVAL_MS ?? "2000", "reconnect-interval-ms")
+	};
+}
+function resolveUploadDir({ entryDir, index, total, uploadDir }) {
+	if (!uploadDir) return path.resolve(path.join(entryDir, ".fastgpt-plugin-debug/uploads"));
+	if (total === 1) return path.resolve(uploadDir);
+	return path.resolve(uploadDir, `${index + 1}-${sanitizePathSegment$1(path.basename(entryDir))}`);
+}
+const ConnectInfoSchema = z.object({
+	gatewayUrl: z.string().min(1),
+	transport: z.literal("websocket"),
+	source: z.string().min(1),
+	connectToken: z.string().min(1),
+	expiresAt: z.number().int().positive()
+});
+async function exchangeConnectLink(connectInput) {
+	const response = isHttpUrl(connectInput) ? await fetch(connectInput) : await fetch(resolveConnectionKeyExchangeUrl(), {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ connectionKey: connectInput })
+	});
+	const text = await response.text();
+	if (!response.ok) throw new Error(`connection key 请求失败: ${response.status} ${text}`);
+	const payload = text ? JSON.parse(text) : {};
+	const info = ConnectInfoSchema.parse(payload.data ?? payload);
+	return {
+		...info,
+		tmbId: parseTmbIdFromDebugSource(info.source)
+	};
+}
+function isHttpUrl(value) {
+	try {
+		const parsed = new URL(value);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+function resolveConnectionKeyExchangeUrl() {
+	const explicit = process.env.FASTGPT_PLUGIN_DEBUG_CONNECT_URL;
+	if (explicit) return explicit;
+	const baseUrl = process.env.FASTGPT_PLUGIN_SERVER_URL ?? process.env.PLUGIN_SERVER_URL;
+	if (!baseUrl) throw new Error("使用裸 connection key 时需要设置 FASTGPT_PLUGIN_DEBUG_CONNECT_URL 或 FASTGPT_PLUGIN_SERVER_URL。");
+	return new URL("/api/plugin/debug-sessions/connection-key:exchange", baseUrl).toString();
+}
+function parseTmbIdFromDebugSource(source) {
+	const parts = source.split(":");
+	const index = parts.indexOf("tmbId");
+	const tmbId = index >= 0 ? parts[index + 1] : void 0;
+	if (!tmbId) throw new Error(`debug source 缺少 tmbId: ${source}`);
+	return tmbId;
+}
+function normalizeGatewayWsUrl(gatewayUrl) {
+	const parsed = new URL(gatewayUrl);
+	if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") throw new Error("gatewayUrl 必须使用 ws:// 或 wss:// 协议。");
+	if (!parsed.hostname) throw new Error("gatewayUrl 必须包含 host。");
+	return parsed.toString();
+}
+function toPositiveInt(value, label) {
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`${label} 必须是正整数。`);
+	return parsed;
+}
+function findDuplicateValues$1(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	values.forEach((value) => {
+		if (seen.has(value)) {
+			duplicates.add(value);
+			return;
+		}
+		seen.add(value);
+	});
+	return [...duplicates];
+}
+function sanitizePathSegment$1(value) {
+	return value.replace(/[^a-zA-Z0-9._-]/g, "_") || "plugin";
+}
+
 //#endregion
 //#region src/commands/debug.ts
 var DebugCommand = class extends BaseCommand {
 	register(parent) {
-		parent.command("debug <entry>").description("直接加载本地插件目录并调试工具").option("-t, --tool <childId>", "工具集子工具 ID").option("--run", "立即执行一次工具调试", false).option("-i, --input <json>", "工具输入 JSON 字符串").option("--input-file <path>", "工具输入 JSON 文件路径").option("--secrets <json>", "secrets JSON 字符串").option("--secrets-file <path>", "secrets JSON 文件路径").option("--system-var <json>", "systemVar JSON 字符串").option("--system-var-file <path>", "systemVar JSON 文件路径").option("--upload-dir <path>", "虚拟 uploadFile 的输出目录").action(async (entry, opts) => {
-			await this.run(entry, opts);
+		parent.command("debug <entries...>").description("直接加载本地插件目录并调试工具").option("-t, --tool <childId>", "工具集子工具 ID").option("--run", "立即执行一次工具调试", false).option("-i, --input <json>", "工具输入 JSON 字符串").option("--input-file <path>", "工具输入 JSON 文件路径").option("--secrets <json>", "secrets JSON 字符串").option("--secrets-file <path>", "secrets JSON 文件路径").option("--system-var <json>", "systemVar JSON 字符串").option("--system-var-file <path>", "systemVar JSON 文件路径").option("--upload-dir <path>", "虚拟 uploadFile 的输出目录").option("--connect <keyOrUrl>", "兼容入口：FastGPT debug connection key 或 connect link，建议改用 dev 命令").option("--reconnect", "兼容入口：断线后自动重连", true).option("--no-reconnect", "兼容入口：关闭自动重连").option("--reconnect-interval-ms <ms>", "兼容入口：重连间隔").action(async (entries, opts) => {
+			await this.run(entries, opts);
 		});
 	}
-	async run(entry, options) {
-		const entryDir = path.resolve(entry);
-		const uploadDir = path.resolve(options.uploadDir ?? path.join(entryDir, ".fastgpt-plugin-debug/uploads"));
-		const session = await loadDebugSession({
+	async run(entriesInput, options) {
+		const entries = (Array.isArray(entriesInput) ? entriesInput : [entriesInput]).map((entry) => path.resolve(entry));
+		const isMultiEntry = entries.length > 1;
+		if (options.connect) {
+			await runRemoteDebugSession({
+				entriesInput,
+				options,
+				commandName: "dev",
+				migrationHint: "debug --connect 是兼容入口，远程集成调试建议改用 fastgpt-plugin dev。"
+			});
+			return;
+		}
+		if (isMultiEntry && !options.connect) throw new Error("debug 是轻量本地调试入口，一次只支持一个插件；多插件远程调试请使用 dev。");
+		if (isMultiEntry && options.run) throw new Error("--run 只支持单个插件入口。");
+		const sessions = [];
+		for (const [index, entryDir] of entries.entries()) sessions.push(await loadDebugSession({
 			entryDir,
-			uploadDir
+			uploadDir: this.resolveUploadDir({
+				entryDir,
+				index,
+				total: entries.length,
+				uploadDir: options.uploadDir
+			})
+		}));
+		sessions.forEach((session) => {
+			this.printSnapshot(session.snapshot, session.uploadDir);
 		});
-		this.printSnapshot(session.snapshot, uploadDir);
+		const duplicatePluginIds = findDuplicateValues(sessions.map((session) => session.snapshot.pluginId));
+		if (duplicatePluginIds.length > 0) throw new Error(`gateway pluginId 重复: ${duplicatePluginIds.join(", ")}`);
+		const [session] = sessions;
 		if (!options.run) return;
 		const input = await this.readJsonOption(options.input, options.inputFile, "input");
 		const secrets = await this.readJsonOption(options.secrets, options.secretsFile, "secrets");
@@ -1799,6 +2977,11 @@ var DebugCommand = class extends BaseCommand {
 			JSON.stringify(this.createInputExample(tool.inputSchema))
 		].map(quoteShellArg).join(" ");
 	}
+	resolveUploadDir({ entryDir, index, total, uploadDir }) {
+		if (!uploadDir) return path.resolve(path.join(entryDir, ".fastgpt-plugin-debug/uploads"));
+		if (total === 1) return path.resolve(uploadDir);
+		return path.resolve(uploadDir, `${index + 1}-${sanitizePathSegment(path.basename(entryDir))}`);
+	}
 	createInputExample(schema) {
 		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
 		if ("const" in schema) return schema.const;
@@ -1842,6 +3025,38 @@ function quoteShellArg(value) {
 	if (/^[a-zA-Z0-9_./:@-]+$/.test(value)) return value;
 	return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
+function findDuplicateValues(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	values.forEach((value) => {
+		if (seen.has(value)) {
+			duplicates.add(value);
+			return;
+		}
+		seen.add(value);
+	});
+	return [...duplicates];
+}
+function sanitizePathSegment(value) {
+	return value.replace(/[^a-zA-Z0-9._-]/g, "_") || "plugin";
+}
+
+//#endregion
+//#region src/commands/dev.ts
+var DevCommand = class extends BaseCommand {
+	register(parent) {
+		parent.command("dev [entries...]").description("启动 FastGPT 插件集成开发会话").option("--connect <keyOrUrl>", "可选：FastGPT debug connection key 或 connect link，适合脚本和 Agent").option("--reconnect", "断线后自动重连", true).option("--no-reconnect", "关闭自动重连").option("--reconnect-interval-ms <ms>", "重连间隔").option("--upload-dir <path>", "虚拟 uploadFile 的输出目录").option("--watch", "监听插件文件变化并自动重载远程调试会话", false).option("--no-interactive", "使用纯文本状态输出，适合脚本和 Agent").action(async (entries, opts) => {
+			await this.run(entries, opts);
+		});
+	}
+	async run(entriesInput, options) {
+		await runRemoteDebugSession({
+			entriesInput,
+			options,
+			commandName: "dev"
+		});
+	}
+};
 
 //#endregion
 //#region src/commands/pack.ts
@@ -1931,6 +3146,7 @@ function createProgram() {
 	new CheckCommand().register(program);
 	new CreateCommand().register(program);
 	new DebugCommand().register(program);
+	new DevCommand().register(program);
 	new PackCommand().register(program);
 	return program;
 }