@fastgpt-plugin/cli 0.2.0-alpha.2 → 0.2.0-alpha.3

package/README.en.md

@@ -46,6 +46,8 @@ fastgpt-plugin dev --no-interactive \
   --connect "fpg_dbg_..."
 ```
 
+After `--connect` starts and connects successfully, it overwrites the persisted connection key in local `config.json`, so later `fastgpt-plugin dev` runs can reuse it. In the TUI, press `c` to enter and save a new connection key. Stop the session with `Ctrl+C`; press `Ctrl+C` again to force exit.
+
 When passing a raw connection key, set `FASTGPT_PLUGIN_DEBUG_CONNECT_URL`, or set `FASTGPT_PLUGIN_SERVER_URL` so the CLI can request `/api/plugin/debug-sessions/connection-key:exchange`. Full connect links remain supported for compatibility. The exchange result returns the gateway WSS endpoint, `debug:tmbId:{tmbId}` source, and scoped connect token. The CLI does not need `CONNECTION_GATEWAY_AUTH_TOKEN` or `JWT_SECRET`.
 
 When no plugin directories are passed, `dev` auto-discovers plugins from the current directory. If the current directory has `index.ts`, it is used as the plugin entry; otherwise, the CLI scans one level of child directories for `index.ts`. You can still pass multiple plugin directories explicitly.

package/README.md

@@ -46,6 +46,8 @@ fastgpt-plugin dev --no-interactive \
   --connect "fpg_dbg_..."
 ```
 
+`--connect` 启动并成功连接后会覆盖本地持久配置 `config.json` 里的 connection key，后续 `fastgpt-plugin dev` 可直接复用该配置。TUI 运行中按 `c` 可以重新输入并保存 connection key；停止会话使用 `Ctrl+C`，再次按 `Ctrl+C` 强制退出。
+
 使用裸 connection key 时，需要设置 `FASTGPT_PLUGIN_DEBUG_CONNECT_URL`，或设置 `FASTGPT_PLUGIN_SERVER_URL` 让 CLI 默认请求 `/api/plugin/debug-sessions/connection-key:exchange`。兼容场景仍可传入完整 connect link。exchange 结果会返回 gateway WSS 地址、`debug:tmbId:{tmbId}` source 和 scoped connect token。CLI 不需要 `CONNECTION_GATEWAY_AUTH_TOKEN` 或 `JWT_SECRET`。
 
 `dev` 未传插件目录时会自动探测当前目录：如果当前目录有 `index.ts`，则把当前目录作为插件；否则扫描当前目录下一层子目录中的 `index.ts`。也可以手动传入多个插件目录。

package/dist/index.js

@@ -526,7 +526,7 @@ var CheckCommand = class extends BaseCommand {
 //#endregion
 //#region package.json
 var name = "@fastgpt-plugin/cli";
-var version = "0.2.0-alpha.2";
+var version = "0.2.0-alpha.3";
 
 //#endregion
 //#region src/constants.ts
@@ -811,6 +811,12 @@ const ConnectionGatewayWsHeartbeatMessageSchema = z.object({
 	type: z.literal("heartbeat"),
 	ts: z.number().int().positive()
 });
+const ConnectionGatewayWsMetadataMessageSchema = z.object({
+	protocol: ConnectionGatewayWsProtocolSchema,
+	type: z.literal("metadata"),
+	requestId: z.string().min(1).optional(),
+	metadata: z.record(z.string(), z.unknown())
+});
 const ConnectionGatewayWsErrorMessageSchema = z.object({
 	protocol: ConnectionGatewayWsProtocolSchema,
 	type: z.literal("error"),
@@ -827,7 +833,8 @@ const ConnectionGatewayWsBoundMessageSchema = z.object({
 const ConnectionGatewayWsClientMessageSchema = z.discriminatedUnion("type", [
 	ConnectionGatewayWsBindMessageSchema,
 	ConnectionGatewayWsEnvelopeMessageSchema,
-	ConnectionGatewayWsHeartbeatMessageSchema
+	ConnectionGatewayWsHeartbeatMessageSchema,
+	ConnectionGatewayWsMetadataMessageSchema
 ]);
 const ConnectionGatewayWsServerMessageSchema = z.discriminatedUnion("type", [
 	ConnectionGatewayWsBoundMessageSchema,
@@ -2238,6 +2245,7 @@ async function assertPathExists(targetPath, message) {
 //#endregion
 //#region src/debug/gateway.ts
 const GATEWAY_DUPLICATE_CONNECTION_CODE = "connection_gateway.session_already_bound";
+const GATEWAY_HEARTBEAT_INTERVAL_MS = 5e3;
 async function connectDebugGateway({ targets, options, onLog }) {
 	if (targets.length === 0) throw new Error("Gateway debug targets cannot be empty");
 	if (options.reconnect) return connectReconnectingDebugGateway({
@@ -2300,6 +2308,9 @@ async function connectReconnectingDebugGateway({ targets, options, onLog }) {
 			latestTargets = targets;
 			current?.updateTargets(targets);
 		},
+		reconnect() {
+			current?.close();
+		},
 		close() {
 			closed = true;
 			current?.close();
@@ -2312,6 +2323,7 @@ async function connectSingleDebugGateway({ targets, options, onLog }) {
 	let targetsByPluginId = createTargetsByPluginId(targets);
 	let closed = false;
 	let session = null;
+	let stopHeartbeat = () => void 0;
 	let boundResolve;
 	let boundReject;
 	const bound = new Promise((resolve, reject) => {
@@ -2321,6 +2333,7 @@ async function connectSingleDebugGateway({ targets, options, onLog }) {
 	const closedPromise = new Promise((resolve) => {
 		socket.addEventListener("close", () => {
 			closed = true;
+			stopHeartbeat();
 			resolve();
 		});
 		socket.addEventListener("error", () => {
@@ -2369,19 +2382,56 @@ async function connectSingleDebugGateway({ targets, options, onLog }) {
 		throw error;
 	});
 	const boundSession = await bound;
+	stopHeartbeat = startGatewayHeartbeat(socket);
 	onLog?.(`已连接 Connection Gateway session: ${boundSession.id}`);
 	return {
 		session: boundSession,
 		updateTargets(targets) {
 			targetsByPluginId = createTargetsByPluginId(targets);
+			updateGatewayMetadata({
+				socket,
+				targets,
+				options,
+				onLog
+			});
 			onLog?.(`已热更新本地调试插件: ${targets.map((target) => target.snapshot.pluginId).join(", ")}`);
 		},
 		close() {
-			if (!closed) socket.close();
+			if (!closed) {
+				stopHeartbeat();
+				socket.close();
+			}
 		},
 		closed: closedPromise
 	};
 }
+async function updateGatewayMetadata({ socket, targets, options, onLog }) {
+	try {
+		await sendMessage(socket, {
+			protocol: "connection-gateway.ws.v1",
+			type: "metadata",
+			requestId: randomUUID(),
+			metadata: makePluginDebugMetadata(targets, options.source)
+		});
+	} catch (error) {
+		onLog?.(`Connection Gateway metadata 更新失败: ${formatErrorMessage(error)}`);
+	}
+}
+function startGatewayHeartbeat(socket) {
+	const timer = setInterval(() => {
+		sendMessage(socket, {
+			protocol: "connection-gateway.ws.v1",
+			type: "heartbeat",
+			ts: Date.now()
+		}).catch(() => {
+			socket.close();
+		});
+	}, GATEWAY_HEARTBEAT_INTERVAL_MS);
+	if (typeof timer === "object" && timer && "unref" in timer) timer.unref();
+	return () => {
+		clearInterval(timer);
+	};
+}
 function createTargetsByPluginId(targets) {
 	return new Map(targets.map((target) => [target.snapshot.pluginId, target]));
 }
@@ -2713,8 +2763,9 @@ var InvokeManager = class {
 //#region src/debug/remote-invoke.ts
 var RemoteDebugInvokeBridge = class {
 	sessions = /* @__PURE__ */ new Map();
+	getFastgptBaseUrl;
 	constructor(fastgptBaseUrl) {
-		this.fastgptBaseUrl = fastgptBaseUrl;
+		this.getFastgptBaseUrl = typeof fastgptBaseUrl === "function" ? fastgptBaseUrl : () => fastgptBaseUrl;
 	}
 	attach(runtime) {
 		runtime.setHostRequestHandler((request) => this.handleHostRequest(request));
@@ -2731,7 +2782,7 @@ var RemoteDebugInvokeBridge = class {
 		if (!session) throw new Error("远程调试反向调用会话不存在或已结束。");
 		const invoke = new InvokeManager({
 			token: session.invokeToken,
-			fastgptBaseUrl: this.fastgptBaseUrl
+			fastgptBaseUrl: this.getFastgptBaseUrl()
 		});
 		switch (method) {
 			case InvokeMethodEnum.uploadFile: return invoke.uploadFile({
@@ -2793,7 +2844,11 @@ async function runRemoteDebugSessionOnce({ entriesInput, options, commandName })
 		commandName,
 		targets
 	});
-	attachRemoteInvokeBridges(targets, gatewayOptions.fastgptBaseUrl);
+	let currentGatewayOptions = gatewayOptions;
+	gatewayOptions.onResolvedReconnectOptions = (nextOptions) => {
+		currentGatewayOptions = nextOptions;
+	};
+	attachRemoteInvokeBridges(targets, () => currentGatewayOptions.fastgptBaseUrl);
 	const reporter = createRemoteDebugReporter({
 		commandName,
 		options,
@@ -2811,6 +2866,20 @@ async function runRemoteDebugSessionOnce({ entriesInput, options, commandName })
 			gateway.close();
 			if (force) process.exit(130);
 		});
+		reporter.attachConfigureConnectionKey(async () => {
+			await configureConnectionKey({
+				options,
+				commandName,
+				targets,
+				reconnect: () => {
+					if (gateway.reconnect) {
+						gateway.reconnect();
+						return;
+					}
+					gateway.close();
+				}
+			});
+		});
 		const source = gateway.session.sessionScope.source ?? gatewayOptions.source ?? "-";
 		reporter.ready(source);
 		await gateway.closed;
@@ -2831,7 +2900,11 @@ async function runWatchRemoteDebugSession({ entriesInput, options, commandName }
 		commandName,
 		targets: initialTargets
 	});
-	attachRemoteInvokeBridges(initialTargets, gatewayOptions.fastgptBaseUrl);
+	let currentGatewayOptions = gatewayOptions;
+	gatewayOptions.onResolvedReconnectOptions = (nextOptions) => {
+		currentGatewayOptions = nextOptions;
+	};
+	attachRemoteInvokeBridges(initialTargets, () => currentGatewayOptions.fastgptBaseUrl);
 	const reporter = createRemoteDebugReporter({
 		commandName,
 		options,
@@ -2842,6 +2915,7 @@ async function runWatchRemoteDebugSession({ entriesInput, options, commandName }
 	let reloadPending = false;
 	let closed = false;
 	let gateway;
+	let activeTargets = initialTargets;
 	const reloadTargets = async () => {
 		if (reloadRunning) {
 			reloadPending = true;
@@ -2853,7 +2927,8 @@ async function runWatchRemoteDebugSession({ entriesInput, options, commandName }
 				reloadPending = false;
 				try {
 					const nextTargets = await loadTargets(entries, options);
-					attachRemoteInvokeBridges(nextTargets, gatewayOptions.fastgptBaseUrl);
+					attachRemoteInvokeBridges(nextTargets, () => currentGatewayOptions.fastgptBaseUrl);
+					activeTargets = nextTargets;
 					gateway?.updateTargets(nextTargets);
 					reporter.log(`检测到插件文件变化，已热更新 ${nextTargets.length} 个本地插件。`);
 				} catch (error) {
@@ -2881,6 +2956,20 @@ async function runWatchRemoteDebugSession({ entriesInput, options, commandName }
 			connectedGateway.close();
 			if (force) process.exit(130);
 		});
+		reporter.attachConfigureConnectionKey(async () => {
+			await configureConnectionKey({
+				options,
+				commandName,
+				targets: activeTargets,
+				reconnect: () => {
+					if (connectedGateway.reconnect) {
+						connectedGateway.reconnect();
+						return;
+					}
+					connectedGateway.close();
+				}
+			});
+		});
 		const source = connectedGateway.session.sessionScope.source ?? gatewayOptions.source ?? "-";
 		reporter.ready(source);
 		await connectedGateway.closed;
@@ -2918,9 +3007,9 @@ async function loadTargets(entries, options) {
 	if (duplicatePluginIds.length > 0) throw new Error(`gateway pluginId 重复: ${duplicatePluginIds.join(", ")}`);
 	return targets;
 }
-function attachRemoteInvokeBridges(targets, fastgptBaseUrl) {
+function attachRemoteInvokeBridges(targets, getFastgptBaseUrl) {
 	targets.forEach((target) => {
-		const invokeBridge = new RemoteDebugInvokeBridge(fastgptBaseUrl);
+		const invokeBridge = new RemoteDebugInvokeBridge(getFastgptBaseUrl);
 		invokeBridge.attach(target.runtime);
 		target.invokeBridge = invokeBridge;
 	});
@@ -2956,7 +3045,10 @@ function createRemoteDebugReporter({ commandName, options, gatewayOptions, targe
 	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;
+	if (options.connect) {
+		options.connectPersistOnSuccess = true;
+		return;
+	}
 	const savedConnect = await readSavedConnectionKey();
 	if (savedConnect) {
 		options.connect = savedConnect;
@@ -3019,6 +3111,16 @@ async function saveConnectionKey(connectionKey) {
 		mode: 384
 	});
 }
+async function configureConnectionKey({ options, commandName, targets, reconnect }) {
+	options.connect = await promptConnectLink({
+		commandName,
+		targets,
+		defaultValue: options.connect
+	});
+	options.connectPersistOnSuccess = true;
+	logger.info("已更新 FastGPT connection key，重连成功后会保存到本地配置。");
+	reconnect();
+}
 async function readCliConfig() {
 	const configPath = getCliConfigPath();
 	let raw;
@@ -3050,10 +3152,20 @@ 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 {
+	closeSession;
+	interruptCount = 0;
+	onSigint = () => {
+		this.requestClose("SIGINT");
+	};
+	onSigterm = () => {
+		this.requestClose("SIGTERM");
+	};
 	constructor(summary) {
 		this.summary = summary;
 	}
 	start() {
+		process.on("SIGINT", this.onSigint);
+		process.on("SIGTERM", this.onSigterm);
 		logger.info([
 			"FastGPT 插件开发会话",
 			`  command: fastgpt-plugin ${this.summary.commandName}`,
@@ -3065,6 +3177,13 @@ var PlainRemoteDebugReporter = class {
 			...this.summary.targets.map(formatTargetLine)
 		].join("\n"));
 	}
+	requestClose(signal) {
+		this.interruptCount += 1;
+		const force = this.interruptCount >= 2;
+		this.log(force ? `再次收到 ${signal}，正在强制退出。` : `收到 ${signal}，正在关闭远程调试会话。再次发送 ${signal} 强制退出。`);
+		this.closeSession?.({ force });
+		if (force && !this.closeSession) process.exit(130);
+	}
 	log(message) {
 		logger.info(message);
 	}
@@ -3074,8 +3193,13 @@ var PlainRemoteDebugReporter = class {
 		});
 		logger.info(`已建立 1 个远程调试通道，挂载 ${this.summary.targets.length} 个插件，按 Ctrl+C 停止。`);
 	}
-	attachClose() {}
+	attachClose(close) {
+		this.closeSession = close;
+	}
+	attachConfigureConnectionKey() {}
 	end() {
+		process.off("SIGINT", this.onSigint);
+		process.off("SIGTERM", this.onSigterm);
 		logger.info("远程调试会话已结束。");
 	}
 };
@@ -3085,36 +3209,34 @@ var TuiRemoteDebugReporter = class {
 	logs = [];
 	instance;
 	closeSession;
+	configureConnectionKey;
 	interruptCount = 0;
+	configuring = false;
 	onSigint = () => {
-		this.requestClose("ctrl-c");
+		this.requestClose("SIGINT");
 	};
-	requestClose = (reason) => {
-		if (reason === "q") {
-			this.log("收到退出指令，正在关闭远程调试会话。");
-			this.closeSession?.({ force: false });
-			return;
-		}
+	requestClose = (signal) => {
 		this.interruptCount += 1;
 		const force = this.interruptCount >= 2;
 		this.status = force ? "closed" : "closing";
-		this.log(force ? "再次收到 Ctrl+C，正在强制退出。" : "收到 Ctrl+C，正在关闭远程调试会话。再次按 Ctrl+C 强制退出。");
+		this.log(force ? `再次收到 ${signal}，正在强制退出。` : `收到 ${signal}，正在关闭远程调试会话。再次按 Ctrl+C 强制退出。`);
 		this.closeSession?.({ force });
 		if (force && !this.closeSession) process.exit(130);
 	};
+	requestConfigureConnectionKey = () => {
+		if (this.configuring) return;
+		if (!this.configureConnectionKey) {
+			this.log("connection key 配置入口尚未就绪。");
+			return;
+		}
+		this.runConfigureConnectionKey();
+	};
 	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
-		});
+		this.mount();
 	}
 	log(message) {
 		this.logs.push({
@@ -3132,39 +3254,78 @@ var TuiRemoteDebugReporter = class {
 	attachClose(close) {
 		this.closeSession = close;
 	}
+	attachConfigureConnectionKey(handler) {
+		this.configureConnectionKey = handler;
+	}
 	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);
-		}
+		await this.unmount();
 		logger.info("远程调试会话已结束。");
 	}
 	rerender() {
 		this.instance?.rerender(this.createApp());
 	}
+	mount() {
+		if (this.instance) return;
+		this.instance = render(this.createApp(), {
+			stdin: process.stdin,
+			stdout: process.stdout,
+			stderr: process.stderr,
+			exitOnCtrlC: false,
+			interactive: true,
+			patchConsole: false
+		});
+	}
+	async unmount() {
+		const instance = this.instance;
+		this.instance = void 0;
+		if (!instance) return;
+		await Promise.race([instance.waitUntilRenderFlush(), setTimeout$1(50)]).catch(() => void 0);
+		instance.unmount();
+		await Promise.race([instance.waitUntilExit(), setTimeout$1(50)]).catch(() => void 0);
+	}
+	async runConfigureConnectionKey() {
+		if (!this.configureConnectionKey) return;
+		const previousStatus = this.status;
+		this.configuring = true;
+		this.status = "configuring";
+		this.rerender();
+		try {
+			await this.unmount();
+			await this.configureConnectionKey();
+			this.status = "connecting";
+			this.log("已更新 connection key，正在重新连接 Connection Gateway。");
+		} catch (error) {
+			this.status = previousStatus;
+			this.log(`connection key 配置失败: ${formatConnectionKeyExchangeError(error)}`);
+		} finally {
+			this.configuring = false;
+			if (this.status !== "closed") {
+				this.mount();
+				this.rerender();
+			}
+		}
+	}
 	createApp() {
 		return React.createElement(RemoteDebugInkApp, {
 			summary: this.summary,
 			status: this.status,
 			source: this.source,
 			logs: this.logs,
-			onQuit: this.requestClose
+			onClose: () => this.requestClose("SIGINT"),
+			onConfigureConnectionKey: this.requestConfigureConnectionKey
 		});
 	}
 };
-function RemoteDebugInkApp({ summary, status, source, logs, onQuit }) {
+function RemoteDebugInkApp({ summary, status, source, logs, onClose, onConfigureConnectionKey }) {
 	useInput((inputValue, key) => {
 		if (key.ctrl && inputValue === "c") {
-			onQuit("ctrl-c");
+			onClose();
 			return;
 		}
-		if (inputValue === "q") onQuit("q");
+		if (inputValue === "c") onConfigureConnectionKey();
 	});
 	const statusMeta = getTuiStatusMeta(status);
 	const sourceLabel = source === "-" ? "waiting for bind" : source;
@@ -3256,7 +3417,7 @@ function RemoteDebugInkApp({ summary, status, source, logs, onQuit }) {
 	}, ...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")));
+	}, React.createElement(Text, { dimColor: true }, "c configure connection key"), React.createElement(Text, { dimColor: true }, "Ctrl+C stop · second Ctrl+C force exit")));
 }
 function getTuiStatusMeta(status) {
 	if (status === "connected") return {
@@ -3273,6 +3434,13 @@ function getTuiStatusMeta(status) {
 		color: "gray",
 		borderColor: "gray"
 	};
+	if (status === "configuring") return {
+		label: "CONFIGURE",
+		marker: "◆",
+		description: "Waiting for a new FastGPT connection key.",
+		color: "cyanBright",
+		borderColor: "cyan"
+	};
 	if (status === "closing") return {
 		label: "CLOSING",
 		marker: "◆",
@@ -3329,7 +3497,7 @@ function formatConnectionKeyExchangeError(error) {
 }
 async function resolveConnectGatewayOptions(options) {
 	const info = await exchangeConnectLink(options.connect);
-	return {
+	const resolvedOptions = {
 		gatewayUrl: normalizeGatewayWsUrl(info.gatewayUrl),
 		connectToken: info.connectToken,
 		userId: info.tmbId,
@@ -3337,9 +3505,20 @@ async function resolveConnectGatewayOptions(options) {
 		fastgptBaseUrl: info.fastgptBaseUrl,
 		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"),
-		resolveReconnectOptions: () => resolveConnectGatewayOptions(options)
+		reconnectIntervalMs: toPositiveInt(options.reconnectIntervalMs ?? process.env.CONNECTION_GATEWAY_RECONNECT_INTERVAL_MS ?? "2000", "reconnect-interval-ms")
+	};
+	resolvedOptions.resolveReconnectOptions = async () => {
+		const nextOptions = await resolveConnectGatewayOptions(options);
+		if (options.connectPersistOnSuccess === true) {
+			await saveConnectionKey(options.connect);
+			logger.info(`已保存 FastGPT connection key 到本地配置: ${getCliConfigPath()}`);
+			options.connectPersistOnSuccess = false;
+		}
+		resolvedOptions.onResolvedReconnectOptions?.(nextOptions);
+		nextOptions.onResolvedReconnectOptions = resolvedOptions.onResolvedReconnectOptions;
+		return nextOptions;
 	};
+	return resolvedOptions;
 }
 function resolveUploadDir({ entryDir, index, total, uploadDir }) {
 	if (!uploadDir) return path.resolve(path.join(entryDir, ".fastgpt-plugin-debug/uploads"));
@@ -3719,9 +3898,6 @@ async function run(argv) {
 
 //#endregion
 //#region src/index.ts
-process.on("SIGINT", () => {
-	process.exit(130);
-});
 const main = async () => {
 	try {
 		await run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastgpt-plugin/cli",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.3",
   "type": "module",
   "private": false,
   "publishConfig": {