@fastgpt-plugin/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/index.js

@@ -1,262 +1,203 @@
 #!/usr/bin/env node
-import { consola } from "consola/basic";
-import { Command } from "commander";
-import path from "node:path";
+import { registerHooks, stripTypeScriptTypes } from "node:module";
 import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { consola } from "consola/basic";
 import { build } from "tsdown";
-import { Visitor, parseSync } from "oxc-parser";
-import { createHash } from "node:crypto";
+import z from "zod";
 import { input, select } from "@inquirer/prompts";
 import { kebabCase } from "es-toolkit";
-import { createWriteStream } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import fs$1, { createWriteStream } from "node:fs";
+import { Readable } from "stream";
+import { Readable as Readable$1 } from "node:stream";
 import { ZipFile } from "yazl";
+import { Command } from "commander";
 
 //#region src/helpers.ts
 const logger = consola;
 
 //#endregion
-//#region package.json
-var name = "@fastgpt-plugin/cli";
-var version = "0.1.0-beta.3";
+//#region ../../packages/domain/src/value-objects/i18n-string.vo.ts
+const I18nLangSchema = z.enum([
+	"en",
+	"zh-CN",
+	"zh-Hant"
+]);
+const I18nLangEnum = I18nLangSchema.enum;
+const I18nStringSchema = z.object({
+	[I18nLangEnum.en]: z.string(),
+	[I18nLangEnum["zh-CN"]]: z.string().optional(),
+	[I18nLangEnum["zh-Hant"]]: z.string().optional()
+});
+const I18nStringStrictSchema = z.object({
+	[I18nLangEnum.en]: z.string(),
+	[I18nLangEnum["zh-CN"]]: z.string(),
+	[I18nLangEnum["zh-Hant"]]: z.string()
+});
 
 //#endregion
-//#region src/constants.ts
-const CLI_NAME = name;
-const CLI_VERSION = version;
-const DEFAULT_PLUGIN_NAME = "./packages/my-tool";
-const DEFAULT_PLUGIN_DESCRIPTION = "This is a FastGPT plugin";
-const TOOL_TEMPLATES_DIR = path.join(import.meta.dirname, "../templates");
+//#region ../../packages/domain/src/value-objects/permission.vo.ts
+const PluginPermissionEnumSchema = z.enum([
+	"userInfo:read",
+	"teamInfo:read",
+	"model:read",
+	"dataset:read",
+	"file-upload:allow"
+]);
+const PluginPermissionEnum = PluginPermissionEnumSchema.enum;
 
 //#endregion
-//#region src/commands/base.ts
-/**
-* 所有子命令的基类：
-* - 统一命令接口类型
-* - 强制实现 register 方法，用于向 Commander 注册自身
-*/
-var BaseCommand = class {};
+//#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 PluginTagListSchema = z.array(z.record(z.string(), I18nStringStrictSchema));
+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 src/build/etag.ts
-/**
-* 计算单工具的 etag。
-*
-* 规则：
-* - 仅计算 src/ 目录下的源码文件
-* - 排除测试相关文件：
-*   - 文件名包含 .test. 或 .spec.
-*   - 位于 __tests__ 目录中的文件
-* - 参与计算的每一行格式为：
-*   <relative-path>:<file-content-md5>\n
-*   其中 relative-path 相对于 rootDir，统一使用 / 作为分隔符。
-* - 对拼接后的所有行再次计算 md5，得到最终 etag。
-*/
-async function computeSingleToolEtag(options) {
-	const srcDir = path.join(options.rootDir, "src");
-	if (!await pathExists$1(srcDir)) return md5("");
-	const files = [];
-	const walk = async (dir) => {
-		const entries = await fs.readdir(dir, { withFileTypes: true });
-		for (const entry of entries) {
-			const full = path.join(dir, entry.name);
-			if (entry.isDirectory()) {
-				if (entry.name === "__tests__") continue;
-				await walk(full);
-				continue;
-			}
-			if (!entry.isFile()) continue;
-			const filename = entry.name;
-			if (filename.includes(".test.") || filename.includes(".spec.")) continue;
-			const relFromRoot = path.relative(options.rootDir, full).split(path.sep).join("/");
-			if (!relFromRoot.startsWith("src/")) continue;
-			files.push({
-				rel: relFromRoot,
-				abs: full
-			});
-		}
-	};
-	await walk(srcDir);
-	files.sort((a, b) => a.rel.localeCompare(b.rel));
-	let aggregate = "";
-	for (const file of files) {
-		const fileHash = md5(await fs.readFile(file.abs));
-		aggregate += `${file.rel}:${fileHash}\n`;
-	}
-	return md5(aggregate);
-}
-/**
-* 计算工具集的 etag。
-*
-* 规则：
-* - 首先为每个子工具单独计算 etag（同单工具规则）
-* - 然后按子工具名称排序，拼接行：
-*   <tool-suite-id>/<child-name>:<child-etag>\n
-* - 对拼接后的所有行再次计算 md5，得到工具集的 etag。
-*/
-async function computeToolSuiteEtag(options) {
-	const { rootDir, toolId } = options;
-	const children = [...options.children].sort();
-	const lines = [];
-	for (const child of children) {
-		const childEtag = await computeSingleToolEtag({ rootDir: path.join(rootDir, "children", child) });
-		lines.push(`${toolId}/${child}:${childEtag}`);
-	}
-	return md5(lines.length > 0 ? `${lines.join("\n")}\n` : "");
-}
-async function pathExists$1(p) {
-	try {
-		await fs.access(p);
-		return true;
-	} catch {
-		return false;
-	}
-}
-function md5(input) {
-	const hash = createHash("md5");
-	hash.update(input);
-	return hash.digest("hex");
-}
+//#region ../../packages/domain/src/entities/plugin-base.entity.ts
+const PluginTagSchema = z.enum([
+	"tools",
+	"search",
+	"multimodal",
+	"communication",
+	"finance",
+	"design",
+	"productivity",
+	"news",
+	"entertainment",
+	"social",
+	"scientific",
+	"other"
+]);
+const PluginTagEnum = PluginTagSchema.enum;
+const PluginTypeSchema = z.enum(["tool"]);
+const PluginTypeEnum = PluginTypeSchema.enum;
+const PluginStatusEnumSchema = z.enum([
+	"active",
+	"pending",
+	"disabled"
+]);
+const PluginStatusEnum = PluginStatusEnumSchema.enum;
+const PluginBaseSchema = z.object({
+	pluginId: z.string(),
+	version: z.string(),
+	etag: z.string(),
+	type: PluginTypeSchema,
+	author: z.string().optional(),
+	repoUrl: z.string().optional(),
+	name: I18nStringSchema,
+	icon: z.string(),
+	tutorialUrl: z.url().optional(),
+	readmeUrl: z.url().optional(),
+	description: I18nStringSchema,
+	tags: z.array(PluginTagSchema).optional(),
+	versionDescription: I18nStringSchema.optional(),
+	permission: z.array(PluginPermissionEnumSchema).optional()
+});
 
 //#endregion
-//#region src/build/ast-transform.ts
-function extractToolId(filePath) {
-	const stack = filePath.split("/");
-	if (stack.at(-3) === "children") return `${stack.at(-4)}/${stack.at(-2)}`;
-	return stack.at(-2) || "unknown";
-}
-async function getChildrenList(configDir) {
-	const childrenDir = path.join(configDir, "children");
-	try {
-		await fs.access(childrenDir);
-	} catch {
-		return [];
-	}
-	try {
-		return await fs.readdir(childrenDir);
-	} catch {
-		return [];
-	}
-}
-function hasProperty(properties, keyName) {
-	return properties.some((prop) => prop.type === "Property" && prop.key?.type === "Identifier" && prop.key?.name === keyName);
-}
-function applyModifications(sourceCode, modifications) {
-	const sorted = modifications.sort((a, b) => b.start - a.start);
-	let result = sourceCode;
-	for (const mod of sorted) result = result.slice(0, mod.start) + mod.content + result.slice(mod.end);
-	return result;
-}
-async function transformToolConfig({ sourceCode, filePath }) {
-	if (sourceCode.includes("toolId:")) return {
-		code: sourceCode,
-		hasToolId: true
-	};
-	const toolId = extractToolId(filePath);
-	const configDir = path.dirname(filePath);
-	const childrenList = await getChildrenList(configDir);
-	const singleToolEtag = await computeSingleToolEtag({ rootDir: configDir });
-	const toolSuiteEtag = childrenList.length > 0 ? await computeToolSuiteEtag({
-		rootDir: configDir,
-		toolId,
-		children: childrenList
-	}) : null;
-	const result = parseSync(path.basename(filePath), sourceCode, { sourceType: "module" });
-	if (result.errors.length > 0) throw new Error(`Parse errors: ${result.errors.map((e) => e.message).join(", ")}`);
-	const modifications = [];
-	const targetCallExpressions = [];
-	new Visitor({ CallExpression(node) {
-		if (node.callee?.type === "Identifier" && (node.callee.name === "defineTool" || node.callee.name === "defineToolSet") && node.arguments?.[0]?.type === "ObjectExpression") targetCallExpressions.push(node);
-	} }).visit(result.program);
-	for (const node of targetCallExpressions) {
-		const firstArg = node.arguments[0];
-		if (firstArg?.type !== "ObjectExpression") continue;
-		const objExpr = firstArg;
-		const properties = objExpr.properties || [];
-		const isToolSet = node.callee?.type === "Identifier" && node.callee.name === "defineToolSet";
-		const needsToolId = !hasProperty(properties, "toolId");
-		const needsEtag = !hasProperty(properties, "etag");
-		const needsChildren = isToolSet && !hasProperty(properties, "children") && childrenList.length > 0;
-		if (!needsToolId && !needsEtag && !needsChildren) continue;
-		const lastProperty = properties[properties.length - 1];
-		const insertPos = lastProperty ? lastProperty.end : (objExpr.start ?? 0) + 1;
-		const newProperties = [];
-		if (needsToolId) newProperties.push(`toolId: '${toolId}'`);
-		if (needsEtag) {
-			const etagValue = isToolSet && toolSuiteEtag ? toolSuiteEtag : singleToolEtag;
-			newProperties.push(`etag: '${etagValue}'`);
-		}
-		if (needsChildren) {
-			const childrenArray = childrenList.map((child) => child).join(", ");
-			newProperties.push(`children: [${childrenArray}]`);
-			const importStatements = childrenList.map((child) => `import ${child} from './children/${child}';`).join("\n");
-			modifications.push({
-				start: 0,
-				end: 0,
-				content: importStatements + "\n"
-			});
-		}
-		if (newProperties.length > 0) {
-			const content = (lastProperty ? ",\n  " : "\n  ") + newProperties.join(",\n  ");
-			modifications.push({
-				start: insertPos,
-				end: insertPos,
-				content
-			});
-		}
-	}
-	if (modifications.length === 0) return {
-		code: sourceCode,
-		hasToolId: false
-	};
-	return {
-		code: applyModifications(sourceCode, modifications),
-		hasToolId: true
-	};
-}
+//#region ../../packages/domain/src/entities/tool.entity.ts
+const ToolSetChildItemSchema = z.object({
+	id: z.string(),
+	name: I18nStringSchema,
+	description: I18nStringSchema.optional(),
+	icon: z.string(),
+	toolDescription: z.string(),
+	inputSchema: z.any(),
+	outputSchema: z.any()
+});
+const ToolSchema = z.object({
+	...PluginBaseSchema.shape,
+	type: z.literal(PluginTypeEnum.tool),
+	toolDescription: z.string(),
+	inputSchema: z.any().optional(),
+	outputSchema: z.any().optional(),
+	secretSchema: z.any().optional(),
+	children: z.array(ToolSetChildItemSchema).optional()
+});
+const ToolSetSchema = z.object({
+	...PluginBaseSchema.shape,
+	type: z.literal(PluginTypeEnum.tool),
+	meta: z.object({
+		secretSchema: z.any().optional(),
+		toolDescription: z.string()
+	})
+});
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/plugin/plugin-manifest.vo.ts
+const PluginManifestBaseSchema = z.object({ ...PluginBaseSchema.omit({
+	etag: true,
+	readmeUrl: true
+}).shape });
+const ToolManifestSchema = z.object({
+	...PluginManifestBaseSchema.shape,
+	type: z.literal(PluginTypeEnum.tool),
+	toolDescription: z.string(),
+	inputSchema: z.any().optional(),
+	outputSchema: z.any().optional(),
+	secretSchema: z.any(),
+	children: z.array(z.object({
+		id: z.string(),
+		description: I18nStringSchema,
+		name: I18nStringSchema,
+		toolDescription: z.string(),
+		icon: z.string(),
+		inputSchema: z.any(),
+		outputSchema: z.any()
+	})).min(1).optional()
+});
 
 //#endregion
 //#region src/build/index.ts
 /**
 * 核心构建逻辑：给定入口目录和输出目录，完成一次工具构建。
-* - 使用 logger 记录关键阶段和耗时
-* - 不调用 process.exit
-* - 失败时抛出 Error
+*
+* 输出：
+*   dist/index.js
+*   dist/manifest.json
+*   dist/logo.* / dist/<childId>.logo.*
+*   dist/README.md（可选）
+*   dist/assets/**（可选）
 */
 async function buildToolPackage(options) {
 	const entryDir = path.resolve(options.entry);
-	await assertPathExists$1(entryDir, `入口目录不存在: ${entryDir}`);
-	const configPath = path.join(entryDir, "config.ts");
-	await assertPathExists$1(configPath, `找不到 config.ts 文件: ${configPath}`);
+	const outputDir = path.resolve(options.output);
 	const indexPath = path.join(entryDir, "index.ts");
-	await assertPathExists$1(indexPath, `找不到 index.ts 文件: ${indexPath}`);
 	const tempDir = path.join(entryDir, ".build-temp");
-	await ensureDir$1(tempDir);
+	await assertPathExists$1(entryDir, `入口目录不存在: ${entryDir}`);
+	await assertPathExists$1(indexPath, `找不到 index.ts 文件: ${indexPath}`);
 	const tStart = Date.now();
-	let tConfig = 0;
 	let tCopy = 0;
 	let tBuild = 0;
+	let tAssemble = 0;
 	try {
-		const tConfigStart = Date.now();
-		const transformed = await transformToolConfig({
-			sourceCode: await fs.readFile(configPath, "utf-8"),
-			filePath: configPath
-		});
-		await fs.writeFile(path.join(tempDir, "config.ts"), transformed.code, "utf-8");
-		tConfig = Date.now() - tConfigStart;
+		await resetDir(tempDir);
 		const tCopyStart = Date.now();
-		await copySourceFiles(entryDir, tempDir, entryDir);
+		await copySourceFiles(entryDir, tempDir);
 		tCopy = Date.now() - tCopyStart;
-		const outputDir = path.resolve(options.output);
-		await ensureDir$1(outputDir);
+		await resetDir(outputDir);
 		const tempIndexPath = path.join(tempDir, "index.ts");
 		const tBuildStart = Date.now();
 		await build({
-			entry: [tempIndexPath],
+			entry: { index: tempIndexPath },
 			outDir: outputDir,
 			format: [options.format],
 			clean: true,
 			minify: options.minify,
-			inlineOnly: false,
+			inlineOnly: ["*"],
 			nodeProtocol: true,
 			platform: "node",
 			target: "node22",
@@ -269,19 +210,25 @@ async function buildToolPackage(options) {
 			})
 		});
 		tBuild = Date.now() - tBuildStart;
-		const files = await fs.readdir(outputDir);
+		const tAssembleStart = Date.now();
+		const plan = await createBuildPlan(entryDir, await loadPackableTool(path.join(outputDir, "index.js")));
+		await fs.writeFile(path.join(outputDir, "manifest.json"), JSON.stringify(plan.manifest, null, 2), "utf-8");
+		await copyLogoFiles(outputDir, plan.logoFiles);
+		await copyOptionalStaticFiles(entryDir, outputDir);
+		tAssemble = Date.now() - tAssembleStart;
+		const files = await collectRelativeFiles(outputDir);
 		const tTotal = Date.now() - tStart;
 		logger.info([
 			"构建阶段耗时统计：",
-			`• config 转换: ${formatDuration(tConfig)}`,
-			`• 源码复制:    ${formatDuration(tCopy)}`,
-			`• tsdown 构建: ${formatDuration(tBuild)}`,
-			`• 总耗时:      ${formatDuration(tTotal)}`
+			`• 源码复制:      ${formatDuration(tCopy)}`,
+			`• tsdown 构建:   ${formatDuration(tBuild)}`,
+			`• 产物组装:      ${formatDuration(tAssemble)}`,
+			`• 总耗时:        ${formatDuration(tTotal)}`
 		].join("\n"));
 		return {
 			entryDir,
 			outputDir,
-			files: files.map((f) => f)
+			files
 		};
 	} finally {
 		try {
@@ -292,12 +239,69 @@ async function buildToolPackage(options) {
 		} catch {}
 	}
 }
-/**
-* 从入口目录复制源码到临时目录：
-* - 根目录的 config.ts 已被转换，不再复制
-* - 子目录中的 config.ts 需要保留（子工具自身的配置）
-*/
-async function copySourceFiles(sourceDir, targetDir, rootDir) {
+async function loadPackableTool(indexJsPath) {
+	await assertPathExists$1(indexJsPath, `找不到编译产物 index.js：${indexJsPath}`);
+	const tool = (await import(`${pathToFileURL(indexJsPath).href}?t=${Date.now()}`)).default;
+	if (!isPackableToolExport$1(tool)) throw new Error("index.ts 的 default export 必须是 defineTool()/defineToolSet() 返回的 factory-sdk 实例");
+	return tool;
+}
+async function createBuildPlan(entryDir, tool) {
+	const rootLogoPath = await findRootLogoFile(entryDir);
+	if (!rootLogoPath) throw new Error(`找不到主 logo 文件，请在 ${entryDir} 下提供 logo.*`);
+	const rootLogoName = path.basename(rootLogoPath);
+	const logoFiles = new Map([[rootLogoName, rootLogoPath]]);
+	const userManifest = tool.getUserToolManifest();
+	const secretSchema = z.toJSONSchema(tool.getSecretSchema());
+	const toolDescription = pickToolDescription$1(getOptionalString$1(userManifest.toolDescription), userManifest.description);
+	const childManifests = tool.getChildManifests();
+	const manifestCandidate = {
+		...userManifest,
+		type: "tool",
+		icon: rootLogoName,
+		toolDescription,
+		secretSchema
+	};
+	if (childManifests.length === 0) {
+		const handler = tool.getToolHandler();
+		if (!handler) throw new Error("default export 未注册任何工具 handler");
+		manifestCandidate.inputSchema = z.toJSONSchema(handler.inputSchema);
+		manifestCandidate.outputSchema = z.toJSONSchema(handler.outputSchema);
+	} else manifestCandidate.children = await Promise.all(childManifests.map(async (child) => {
+		const handler = tool.getToolHandler(child.id);
+		if (!handler) throw new Error(`找不到子工具 handler: ${child.id}`);
+		const childLogoPath = await findChildLogoFile(entryDir, child.id) ?? rootLogoPath;
+		const childLogoName = path.basename(childLogoPath);
+		logoFiles.set(childLogoName, childLogoPath);
+		return {
+			id: child.id,
+			description: child.description,
+			name: child.name,
+			icon: childLogoName,
+			toolDescription: pickToolDescription$1(child.toolDescription, child.description),
+			inputSchema: z.toJSONSchema(handler.inputSchema),
+			outputSchema: z.toJSONSchema(handler.outputSchema)
+		};
+	}));
+	return {
+		manifest: ToolManifestSchema.parse(manifestCandidate),
+		logoFiles: [...logoFiles.entries()].map(([fileName, sourcePath]) => ({
+			fileName,
+			sourcePath
+		}))
+	};
+}
+async function copyLogoFiles(outputDir, logoFiles) {
+	await Promise.all(logoFiles.map(async ({ fileName, sourcePath }) => {
+		await fs.copyFile(sourcePath, path.join(outputDir, fileName));
+	}));
+}
+async function copyOptionalStaticFiles(entryDir, outputDir) {
+	const readmePath = path.join(entryDir, "README.md");
+	if (await pathExists$1(readmePath)) await fs.copyFile(readmePath, path.join(outputDir, "README.md"));
+	const assetsDir = path.join(entryDir, "assets");
+	if (await pathExists$1(assetsDir)) await copyDirectory(assetsDir, path.join(outputDir, "assets"));
+}
+async function copySourceFiles(sourceDir, targetDir) {
 	const files = await fs.readdir(sourceDir, { withFileTypes: true });
 	for (const file of files) {
 		if (file.name === "node_modules" || file.name === "dist" || file.name.startsWith(".build-")) continue;
@@ -305,21 +309,88 @@ async function copySourceFiles(sourceDir, targetDir, rootDir) {
 		const targetPath = path.join(targetDir, file.name);
 		if (file.isDirectory()) {
 			await ensureDir$1(targetPath);
-			await copySourceFiles(sourcePath, targetPath, rootDir);
-		} else if (file.isFile()) {
-			if (!(file.name === "config.ts" && sourceDir === rootDir)) if (file.name === "config.ts") {
-				const transformed = await transformToolConfig({
-					sourceCode: await fs.readFile(sourcePath, "utf-8"),
-					filePath: sourcePath
-				});
-				await fs.writeFile(targetPath, transformed.code, "utf-8");
-			} else await fs.copyFile(sourcePath, targetPath);
+			await copySourceFiles(sourcePath, targetPath);
+		} else if (file.isFile()) await fs.copyFile(sourcePath, targetPath);
+	}
+}
+async function collectRelativeFiles(dir, baseDir = dir) {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await collectRelativeFiles(fullPath, baseDir));
+			continue;
 		}
+		if (entry.isFile()) files.push(path.relative(baseDir, fullPath));
+	}
+	return files.sort();
+}
+async function findRootLogoFile(entryDir) {
+	return findMatchingFile(entryDir, /^logo\./i);
+}
+async function findChildLogoFile(entryDir, childId) {
+	const escapedChildId = escapeRegExp(childId);
+	return findMatchingFile(entryDir, new RegExp(`^${escapedChildId}\\.logo\\.`, "i"));
+}
+async function findMatchingFile(dir, pattern) {
+	try {
+		const matched = (await fs.readdir(dir, { withFileTypes: true })).find((entry) => entry.isFile() && pattern.test(entry.name));
+		return matched ? path.join(dir, matched.name) : null;
+	} catch {
+		return null;
+	}
+}
+async function copyDirectory(sourceDir, targetDir) {
+	await ensureDir$1(targetDir);
+	const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const sourcePath = path.join(sourceDir, entry.name);
+		const targetPath = path.join(targetDir, entry.name);
+		if (entry.isDirectory()) await copyDirectory(sourcePath, targetPath);
+		else if (entry.isFile()) await fs.copyFile(sourcePath, targetPath);
+	}
+}
+function isPackableToolExport$1(value) {
+	return Boolean(value && typeof value === "object" && "getUserToolManifest" in value && typeof value.getUserToolManifest === "function" && "getSecretSchema" in value && typeof value.getSecretSchema === "function" && "getToolHandler" in value && typeof value.getToolHandler === "function" && "getChildManifests" in value && typeof value.getChildManifests === "function");
+}
+function pickToolDescription$1(explicitDescription, fallbackSource) {
+	if (explicitDescription && explicitDescription.trim().length > 0) return explicitDescription;
+	if (fallbackSource && typeof fallbackSource === "object") {
+		const localized = fallbackSource;
+		const preferred = [
+			localized["zh-CN"],
+			localized.en,
+			...Object.values(localized)
+		].find((value) => typeof value === "string" && value.trim().length > 0);
+		if (typeof preferred === "string") return preferred;
+	}
+	return "";
+}
+function getOptionalString$1(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function pathExists$1(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
 	}
 }
 async function ensureDir$1(dir) {
 	await fs.mkdir(dir, { recursive: true });
 }
+async function resetDir(dir) {
+	await fs.rm(dir, {
+		recursive: true,
+		force: true
+	});
+	await ensureDir$1(dir);
+}
 async function assertPathExists$1(p, message) {
 	try {
 		await fs.access(p);
@@ -332,6 +403,15 @@ function formatDuration(ms) {
 	return `${(ms / 1e3).toFixed(2)}s`;
 }
 
+//#endregion
+//#region src/commands/base.ts
+/**
+* 所有子命令的基类：
+* - 统一命令接口类型
+* - 强制实现 register 方法，用于向 Commander 注册自身
+*/
+var BaseCommand = class {};
+
 //#endregion
 //#region src/commands/build.ts
 var BuildCommand = class extends BaseCommand {
@@ -367,6 +447,100 @@ var BuildCommand = class extends BaseCommand {
 	}
 };
 
+//#endregion
+//#region src/check/index.ts
+/**
+* 检查构建产物的正确性：
+*  - dist/index.js 存在
+*  - dist/manifest.json 存在且通过 Schema 校验
+*  - manifest.json 引用的 logo 文件存在
+*/
+async function checkBuildOutput(options) {
+	const outputDir = path.resolve(options.output);
+	const errors = [];
+	const warnings = [];
+	const indexJsPath = path.join(outputDir, "index.js");
+	if (!await pathExists(indexJsPath)) errors.push(`缺少构建产物 dist/index.js：${indexJsPath}`);
+	const manifestPath = path.join(outputDir, "manifest.json");
+	const manifestContent = await readFileSafe(manifestPath);
+	if (manifestContent === null) errors.push(`缺少 dist/manifest.json：${manifestPath}`);
+	else {
+		let rawManifest;
+		try {
+			rawManifest = JSON.parse(manifestContent);
+		} catch (e) {
+			errors.push(`manifest.json 解析失败（JSON 语法错误）：${e.message}`);
+		}
+		if (rawManifest !== void 0) {
+			const result = ToolManifestSchema.safeParse(rawManifest);
+			if (!result.success) for (const issue of result.error.issues) errors.push(`manifest.json 校验失败 [${issue.path.join(".")}]: ${issue.message}`);
+			else await validateManifestAssets(result.data, outputDir, errors, warnings);
+		}
+	}
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+async function validateManifestAssets(manifest, outputDir, errors, warnings) {
+	if (!await pathExists(path.join(outputDir, manifest.icon))) errors.push(`manifest.json 引用的主 logo 不存在：${manifest.icon}`);
+	if (manifest.children && manifest.children.length > 0) {
+		for (const child of manifest.children) if (!await pathExists(path.join(outputDir, child.icon))) errors.push(`manifest.json 中子工具 "${child.id}" 的 logo 不存在：${child.icon}`);
+	}
+	if (!await pathExists(path.join(outputDir, "README.md"))) warnings.push("dist/README.md 不存在");
+}
+async function readFileSafe(filePath) {
+	try {
+		return await fs.readFile(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+async function pathExists(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/commands/check.ts
+var CheckCommand = class extends BaseCommand {
+	register(parent) {
+		parent.command("check").description("检查构建产物的正确性（manifest.json、config.json、index.js）").option("-e, --entry <path>", "工具源码目录", process.cwd()).option("-o, --output <path>", "构建输出目录", "./dist").action(async (opts) => {
+			await this.run(opts);
+		});
+	}
+	async run(options) {
+		logger.info(`检查目录: ${options.entry}`);
+		logger.info(`产物目录: ${options.output}`);
+		const result = await checkBuildOutput(options);
+		if (result.warnings.length > 0) for (const w of result.warnings) logger.warn(w);
+		if (result.errors.length > 0) {
+			logger.error(`检查失败，共 ${result.errors.length} 个错误：`);
+			for (const e of result.errors) logger.error(`  ✗ ${e}`);
+			process.exit(1);
+		}
+		logger.success("检查通过，构建产物格式正确");
+	}
+};
+
+//#endregion
+//#region package.json
+var name = "@fastgpt-plugin/cli";
+var version = "0.1.0-beta.5";
+
+//#endregion
+//#region src/constants.ts
+const CLI_NAME = name;
+const CLI_VERSION = version;
+const DEFAULT_PLUGIN_NAME = "./packages/my-tool";
+const DEFAULT_PLUGIN_DESCRIPTION = "This is a FastGPT plugin";
+const TOOL_TEMPLATES_DIR = path.join(import.meta.dirname, "../templates");
+
 //#endregion
 //#region src/prompts/create/deps.ts
 const defaultDeps = {
@@ -464,7 +638,7 @@ var CreateCommand = class extends BaseCommand {
 	}
 	async run(options) {
 		const targetDir = path.resolve(options.cwd, options.name);
-		const templateDir = path.join(TOOL_TEMPLATES_DIR, options.type === "tool-suite" ? "tool-suite" : "tool");
+		const templateDir = path.join(TOOL_TEMPLATES_DIR, "tool");
 		const files = await this.collectTemplateFiles(templateDir);
 		const description = options.description ?? DEFAULT_PLUGIN_DESCRIPTION;
 		await this.ensureDir(targetDir);
@@ -476,6 +650,7 @@ var CreateCommand = class extends BaseCommand {
 			const content = this.applyPlaceholders(raw, options.name, description);
 			await fs.writeFile(filePath, content, "utf-8");
 		}
+		await this.finalizeIndexTemplate(targetDir, options.type);
 		logger.success(`创建插件项目: ${options.name} (${options.type})`, { cwd: options.cwd });
 	}
 	applyPlaceholders(text, name, description) {
@@ -499,58 +674,920 @@ var CreateCommand = class extends BaseCommand {
 		await walk(root);
 		return result.sort();
 	}
+	async finalizeIndexTemplate(targetDir, type) {
+		const toolIndexPath = path.join(targetDir, "index.tool.ts");
+		const toolSetIndexPath = path.join(targetDir, "index.toolset.ts");
+		const finalIndexPath = path.join(targetDir, "index.ts");
+		const sourcePath = type === "tool-suite" ? toolSetIndexPath : toolIndexPath;
+		const cleanupTargets = [toolIndexPath, toolSetIndexPath];
+		await fs.rename(sourcePath, finalIndexPath);
+		await Promise.all(cleanupTargets.map(async (filePath) => {
+			if (filePath === sourcePath) return;
+			await fs.rm(filePath, { force: true });
+		}));
+	}
 	async ensureDir(dir) {
 		await fs.mkdir(dir, { recursive: true });
 	}
 };
 
+//#endregion
+//#region src/debug/import-hooks.ts
+const SOURCE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts"
+];
+const RESOLVE_EXTENSIONS = [
+	"",
+	...SOURCE_EXTENSIONS,
+	".js",
+	".mjs",
+	".cjs",
+	".json"
+];
+let hooksRegistered = false;
+function ensureDebugImportHooks() {
+	if (hooksRegistered) return;
+	hooksRegistered = true;
+	const workspaceRoot = findWorkspaceRoot(path.dirname(fileURLToPath(import.meta.url)));
+	registerHooks({
+		resolve(specifier, context, nextResolve) {
+			const resolved = resolveSpecifier({
+				specifier,
+				parentURL: context.parentURL,
+				workspaceRoot
+			});
+			if (resolved) return {
+				url: resolved,
+				shortCircuit: true
+			};
+			return nextResolve(specifier, context);
+		},
+		load(url, context, nextLoad) {
+			const parsed = new URL(url);
+			const ext = path.extname(parsed.pathname);
+			if (SOURCE_EXTENSIONS.includes(ext)) return {
+				format: "module",
+				shortCircuit: true,
+				source: stripTypeScriptTypes(fs$1.readFileSync(fileURLToPath(parsed), "utf-8"), {
+					mode: "transform",
+					sourceMap: false
+				})
+			};
+			return nextLoad(url, context);
+		}
+	});
+}
+function resolveSpecifier({ specifier, parentURL, workspaceRoot }) {
+	if (specifier.startsWith("node:")) return null;
+	if (specifier.startsWith("file:")) return toFileURL(resolveExistingPath(fileURLToPath(new URL(specifier))));
+	if (specifier.startsWith("./") || specifier.startsWith("../")) {
+		if (!parentURL?.startsWith("file:")) return null;
+		const parentPath = fileURLToPath(new URL(parentURL));
+		return toFileURL(resolveExistingPath(path.resolve(path.dirname(parentPath), specifier)));
+	}
+	if (path.isAbsolute(specifier)) return toFileURL(resolveExistingPath(specifier));
+	if (!workspaceRoot) return null;
+	return toFileURL(resolveWorkspaceAlias(specifier, workspaceRoot));
+}
+function resolveWorkspaceAlias(specifier, workspaceRoot) {
+	const exactAliasMap = new Map([
+		["@fastgpt-plugin/sdk-factory", path.join(workspaceRoot, "sdk/factory/src/index.ts")],
+		["@fastgpt-plugin/sdk-client", path.join(workspaceRoot, "sdk/client/src/index.ts")],
+		["sdk/factory/src", path.join(workspaceRoot, "sdk/factory/src/index.ts")],
+		["sdk/factory/dist", path.join(workspaceRoot, "sdk/factory/src/index.ts")],
+		["sdk/client/src", path.join(workspaceRoot, "sdk/client/src/index.ts")],
+		["sdk/client/dist", path.join(workspaceRoot, "sdk/client/src/index.ts")]
+	]);
+	const prefixAliasMap = [
+		["@fastgpt-plugin/sdk-factory/", path.join(workspaceRoot, "sdk/factory/src")],
+		["@fastgpt-plugin/sdk-client/", path.join(workspaceRoot, "sdk/client/src")],
+		["@domain/", path.join(workspaceRoot, "packages/domain/src")],
+		["@usecase/", path.join(workspaceRoot, "packages/usecase/src")],
+		["@shared/", path.join(workspaceRoot, "packages/shared/src")],
+		["@interface-adapter/", path.join(workspaceRoot, "packages/interface-adapter/src")],
+		["@infrastructure/", path.join(workspaceRoot, "packages/infrastructure/src")],
+		["@fastgpt-plugin/cli/", path.join(workspaceRoot, "apps/cli/src")],
+		["sdk/factory/src/", path.join(workspaceRoot, "sdk/factory/src")],
+		["sdk/factory/dist/", path.join(workspaceRoot, "sdk/factory/src")],
+		["sdk/client/src/", path.join(workspaceRoot, "sdk/client/src")],
+		["sdk/client/dist/", path.join(workspaceRoot, "sdk/client/src")]
+	];
+	const exact = exactAliasMap.get(specifier);
+	if (exact) return resolveExistingPath(exact);
+	for (const [prefix, targetDir] of prefixAliasMap) {
+		if (!specifier.startsWith(prefix)) continue;
+		const subPath = specifier.slice(prefix.length);
+		return resolveExistingPath(path.join(targetDir, subPath));
+	}
+	return null;
+}
+function resolveExistingPath(targetPath) {
+	const normalizedTarget = path.normalize(targetPath);
+	if (fs$1.existsSync(normalizedTarget) && fs$1.statSync(normalizedTarget).isFile()) return normalizedTarget;
+	for (const ext of RESOLVE_EXTENSIONS) {
+		const candidate = ext ? `${normalizedTarget}${ext}` : normalizedTarget;
+		if (fs$1.existsSync(candidate) && fs$1.statSync(candidate).isFile()) return candidate;
+	}
+	if (fs$1.existsSync(normalizedTarget) && fs$1.statSync(normalizedTarget).isDirectory()) for (const ext of RESOLVE_EXTENSIONS.filter(Boolean)) {
+		const candidate = path.join(normalizedTarget, `index${ext}`);
+		if (fs$1.existsSync(candidate) && fs$1.statSync(candidate).isFile()) return candidate;
+	}
+	return null;
+}
+function toFileURL(targetPath) {
+	if (!targetPath) return null;
+	return pathToFileURL(targetPath).href;
+}
+function findWorkspaceRoot(startDir) {
+	let currentDir = startDir;
+	while (true) {
+		const sdkFactoryIndex = path.join(currentDir, "sdk/factory/src/index.ts");
+		const domainDir = path.join(currentDir, "packages/domain/src");
+		if (fs$1.existsSync(sdkFactoryIndex) && fs$1.existsSync(domainDir)) return currentDir;
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return;
+		currentDir = parentDir;
+	}
+}
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/file/MIME.vo.ts
+const CommonMIMETypes = [
+	"application/javascript",
+	"application/json",
+	"application/yaml",
+	"application/zip",
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp",
+	"image/svg+xml",
+	"application/pdf",
+	"text/plain",
+	"text/csv",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation",
+	"application/msword",
+	"application/vnd.ms-excel",
+	"application/vnd.ms-powerpoint",
+	"text/markdown",
+	"audio/mpeg",
+	"video/mp4",
+	"audio/wav",
+	"text/html",
+	"application/xml",
+	"application/gzip",
+	"application/octet-stream",
+	"multipart/form-data",
+	"text/event-stream"
+];
+const MIMESchema = z.enum(CommonMIMETypes).and(z.string().regex(/^[^/]+\/[^/]+$/));
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/file/file.vo.ts
+const FileMetaSchema = z.object({
+	fileKey: z.string(),
+	fileName: z.string(),
+	contentType: MIMESchema,
+	size: z.number(),
+	etag: z.string(),
+	createTime: z.date()
+});
+const FileCreateSchema = z.object({
+	fileKey: z.string().optional(),
+	path: z.string().optional(),
+	fileName: z.string().optional(),
+	contentType: MIMESchema.optional(),
+	overwrite: z.boolean().optional(),
+	file: z.union([z.instanceof(Readable, { error: "Stream cannot be empty" }), z.union([z.instanceof(Buffer, { error: "Buffer is required" }), z.instanceof(Uint8Array, { error: "Uint8Array is required" })]).transform((data) => {
+		if (data instanceof Uint8Array && !(data instanceof Buffer)) return Buffer.from(data);
+		return data;
+	})])
+});
+
+//#endregion
+//#region ../../packages/domain/src/ports/invoke.port.ts
+const InvokeUploadFileInputSchema = z.object({ ...FileCreateSchema.omit({
+	fileKey: true,
+	overwrite: true,
+	path: true
+}).shape });
+const InvokeUploadFileOutputSchema = z.object({
+	...FileMetaSchema.omit({ fileKey: true }).shape,
+	accessURL: z.string()
+});
+const InvokeMethodEnumSchema = z.enum(["uploadFile"]);
+const InvokeMethodEnum = InvokeMethodEnumSchema.enum;
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/stream.vo.ts
+var StreamData = class StreamData {
+	stream;
+	closed = false;
+	constructor(initializer) {
+		this.stream = new Readable$1({
+			objectMode: true,
+			read() {}
+		});
+		initializer?.(this);
+	}
+	static create(initializer) {
+		return new StreamData(initializer);
+	}
+	write(data) {
+		this.ensureWritable();
+		this.stream.push(data);
+	}
+	send(data) {
+		this.write(data);
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.stream.push(null);
+	}
+	end() {
+		this.close();
+	}
+	fail(error) {
+		this.closed = true;
+		this.stream.destroy(error);
+	}
+	toReadable() {
+		return this.stream;
+	}
+	onData(listener) {
+		this.stream.on("data", listener);
+		return this;
+	}
+	onEnd(listener) {
+		this.stream.on("end", listener);
+		return this;
+	}
+	onError(listener) {
+		this.stream.on("error", listener);
+		return this;
+	}
+	async consume(consumer) {
+		for await (const chunk of this.values()) await consumer(chunk);
+	}
+	async *values() {
+		for await (const chunk of this.stream) yield chunk;
+	}
+	ensureWritable() {
+		if (this.closed || this.stream.destroyed) throw new Error("StreamData is already closed");
+	}
+};
+
+//#endregion
+//#region ../../packages/domain/src/value-objects/system-var.vo.ts
+const SystemVarSchema = z.object({
+	user: z.object({
+		id: z.string(),
+		username: z.string(),
+		contact: z.string(),
+		membername: z.string(),
+		teamName: z.string(),
+		teamId: z.string(),
+		name: z.string()
+	}),
+	app: z.object({
+		id: z.string(),
+		name: z.string()
+	}),
+	tool: z.object({
+		id: z.string(),
+		version: z.string(),
+		prefix: z.string().optional()
+	}).passthrough(),
+	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 ToolRunContextSchema = z.object({ systemVar: z.record(z.string(), z.unknown()) });
+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/drivers/local-pool/ipc-channel.ts
+const HOST_INVOKE_METHOD = "__host_invoke__";
+
+//#endregion
+//#region src/debug/runtime.ts
+const LOCAL_DEBUG_RUNTIME_GLOBAL_KEY = "__FASTGPT_PLUGIN_LOCAL_DEBUG_RUNTIME__";
+const LOCAL_DEBUG_DUPLEX_REPLY_MARK = "__localDebugDuplexReply__";
+var LocalDebugChannel = class {
+	constructor(runtime) {
+		this.runtime = runtime;
+	}
+	setRequestHandler(handler) {
+		this.runtime.setPluginRequestHandler(handler);
+	}
+	async requestDuplex(method, params, options) {
+		return this.runtime.invokeHost(method, params, {
+			...options,
+			streamName: method
+		});
+	}
+	replyDuplex(_message, result, options) {
+		return {
+			[LOCAL_DEBUG_DUPLEX_REPLY_MARK]: true,
+			...result !== void 0 ? { result } : {},
+			...options?.output !== void 0 ? { output: options.output } : {},
+			...options ? { options: {
+				traceId: options.traceId,
+				outputMeta: options.outputMeta,
+				outputStreamId: options.outputStreamId
+			} } : {}
+		};
+	}
+	sendReady() {
+		this.runtime.markReady();
+	}
+};
+var LocalDebugRuntime = class {
+	pluginRequestHandler = null;
+	hostRequestHandler = null;
+	ready = false;
+	readyPromise;
+	resolveReady;
+	pluginChannel;
+	constructor() {
+		this.pluginChannel = new LocalDebugChannel(this);
+		this.readyPromise = new Promise((resolve) => {
+			this.resolveReady = resolve;
+		});
+	}
+	setPluginRequestHandler(handler) {
+		this.pluginRequestHandler = handler;
+	}
+	setHostRequestHandler(handler) {
+		this.hostRequestHandler = handler;
+	}
+	markReady() {
+		if (this.ready) return;
+		this.ready = true;
+		this.resolveReady();
+	}
+	async waitUntilReady() {
+		await this.readyPromise;
+	}
+	async invokePlugin(method, params, options) {
+		if (!this.pluginRequestHandler) throw new Error("Plugin request handler is not initialized.");
+		return this.dispatch(this.pluginRequestHandler, method, params, {
+			...options,
+			streamName: method
+		});
+	}
+	async invokeHost(method, params, options) {
+		if (!this.hostRequestHandler) throw new Error(`Local debug host handler is not configured: ${method}`);
+		const message = createMessage(method, params, options);
+		return toDuplexResponse(message, await this.hostRequestHandler({
+			message,
+			method,
+			args: params,
+			traceId: options.traceId,
+			input: options.input,
+			replyDuplex: (result, replyOptions) => this.pluginChannel.replyDuplex(message, result, replyOptions)
+		}), options);
+	}
+	async dispatch(handler, method, params, options) {
+		const message = createMessage(method, params, options);
+		return toDuplexResponse(message, await handler(message), options);
+	}
+};
+const createLocalDebugRuntime = () => new LocalDebugRuntime();
+const setCurrentLocalDebugRuntime = (runtime) => {
+	const store = globalThis;
+	if (!runtime) {
+		delete store[LOCAL_DEBUG_RUNTIME_GLOBAL_KEY];
+		return;
+	}
+	store[LOCAL_DEBUG_RUNTIME_GLOBAL_KEY] = runtime;
+};
+function createMessage(method, params, options) {
+	return {
+		id: options?.requestId ?? randomUUID(),
+		messageType: "request",
+		method,
+		params,
+		traceId: options?.traceId,
+		timestamp: Date.now()
+	};
+}
+function isLocalDebugReplyDescriptor(value) {
+	return Boolean(value && typeof value === "object" && LOCAL_DEBUG_DUPLEX_REPLY_MARK in value && value[LOCAL_DEBUG_DUPLEX_REPLY_MARK] === true);
+}
+function toDuplexResponse(message, response, options) {
+	const inputDone = options?.input !== void 0 ? Promise.resolve() : void 0;
+	if (!isLocalDebugReplyDescriptor(response)) return {
+		requestId: message.id,
+		result: response,
+		...inputDone ? { inputDone } : {}
+	};
+	const output = response.output !== void 0 ? createIncomingStream({
+		source: response.output,
+		streamName: response.options?.outputStreamId ?? options?.streamName ?? message.method ?? "stream",
+		streamId: response.options?.outputStreamId ?? randomUUID(),
+		traceId: response.options?.traceId ?? message.traceId,
+		meta: response.options?.outputMeta
+	}) : void 0;
+	return {
+		requestId: message.id,
+		result: response.result,
+		...output ? { output } : {},
+		...inputDone ? { inputDone } : {}
+	};
+}
+function createIncomingStream({ source, streamName, streamId, traceId, meta }) {
+	return {
+		streamId,
+		streamName,
+		stream: toStreamData(source),
+		...traceId ? { traceId } : {},
+		...meta !== void 0 ? { meta } : {}
+	};
+}
+function toStreamData(source) {
+	if (source instanceof StreamData) return source;
+	const output = StreamData.create();
+	(async () => {
+		try {
+			for await (const chunk of source) output.send(chunk);
+			output.end();
+		} catch (error) {
+			output.fail(error instanceof Error ? error : new Error(String(error)));
+		}
+	})();
+	return output;
+}
+
+//#endregion
+//#region src/debug/session.ts
+async function loadDebugSession({ entryDir, uploadDir }) {
+	const resolvedEntryDir = path.resolve(entryDir);
+	const indexPath = path.join(resolvedEntryDir, "index.ts");
+	await assertPathExists(resolvedEntryDir, `调试目录不存在: ${resolvedEntryDir}`);
+	await assertPathExists(indexPath, `找不到 index.ts: ${indexPath}`);
+	ensureDebugImportHooks();
+	const runtime = createLocalDebugRuntime();
+	runtime.setHostRequestHandler(createVirtualHostHandler(uploadDir));
+	const previousRuntimeMode = process.env.RUNTIME_MODE;
+	process.env.RUNTIME_MODE = "dev";
+	setCurrentLocalDebugRuntime(runtime);
+	try {
+		const tool = (await import(`${pathToFileURL(indexPath).href}#fastgpt-plugin-debug-${Date.now()}-${Math.random().toString(16).slice(2)}`)).default;
+		if (!isPackableToolExport(tool)) throw new Error("index.ts 的 default export 必须是 defineTool()/defineToolSet() 返回的 factory-sdk 实例");
+		await runtime.waitUntilReady();
+		return {
+			runtime,
+			uploadDir: path.resolve(uploadDir),
+			snapshot: createDebugSnapshot(tool, {
+				entryDir: resolvedEntryDir,
+				indexPath
+			})
+		};
+	} finally {
+		setCurrentLocalDebugRuntime(void 0);
+		if (previousRuntimeMode === void 0) delete process.env.RUNTIME_MODE;
+		else process.env.RUNTIME_MODE = previousRuntimeMode;
+	}
+}
+async function runDebugTool({ runtime, snapshot, toolId, input, secrets, systemVar }) {
+	const targetTool = pickTargetTool(snapshot, toolId);
+	const mergedSystemVar = createDebugSystemVar(snapshot, targetTool.id, systemVar);
+	const response = await runtime.invokePlugin("run", {
+		input,
+		systemVar: mergedSystemVar,
+		...snapshot.isToolSet ? { childId: targetTool.id } : {},
+		...secrets ? { secrets } : {}
+	}, { traceId: randomUUID() });
+	if (!response.output) throw new Error("调试运行未返回输出流。");
+	const streamMessages = [];
+	let finalResponse;
+	let finalError;
+	await response.output.stream.consume(async (chunk) => {
+		const parsed = ToolStreamMessageSchema.parse(chunk);
+		streamMessages.push(parsed);
+		if (parsed.type === "response") finalResponse = parsed.data;
+		if (parsed.type === "error") finalError = parsed.data;
+	});
+	return {
+		systemVar: mergedSystemVar,
+		response: finalResponse,
+		error: finalError,
+		streamMessages
+	};
+}
+function createDebugSystemVar(snapshot, toolId, overrides) {
+	const base = {
+		user: {
+			id: "debug-user",
+			username: "debug-user",
+			contact: "debug@example.com",
+			membername: "debug-member",
+			teamName: "debug-team",
+			teamId: "debug-team-id",
+			name: "Local Debug User"
+		},
+		app: {
+			id: "debug-app",
+			name: "FastGPT Local Debug"
+		},
+		tool: {
+			id: snapshot.pluginId,
+			version: snapshot.version,
+			prefix: snapshot.isToolSet ? toolId : snapshot.pluginId,
+			token: "debug-token",
+			accessToken: "debug-access-token"
+		},
+		time: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	return SystemVarSchema.parse({
+		...base,
+		...overrides,
+		user: {
+			...base.user,
+			...overrides?.user ?? {}
+		},
+		app: {
+			...base.app,
+			...overrides?.app ?? {}
+		},
+		tool: {
+			...base.tool,
+			...overrides?.tool ?? {}
+		}
+	});
+}
+function createDebugSnapshot(tool, location) {
+	const userManifest = tool.getUserToolManifest();
+	const children = tool.getChildManifests();
+	const secretSchema = z.toJSONSchema(tool.getSecretSchema());
+	const tools = children.length === 0 ? [createSingleToolSnapshot(tool, userManifest)] : children.map((child) => createChildToolSnapshot(tool, child));
+	return {
+		entryDir: location.entryDir,
+		indexPath: location.indexPath,
+		pluginId: getRequiredString(userManifest.pluginId, "缺少 pluginId"),
+		version: getRequiredString(userManifest.version, "缺少 version"),
+		name: pickLocalizedText(userManifest.name),
+		description: pickLocalizedText(userManifest.description),
+		toolDescription: pickToolDescription(getOptionalString(userManifest.toolDescription), userManifest.description),
+		author: getOptionalString(userManifest.author),
+		tags: toStringArray(userManifest.tags),
+		permissions: toStringArray(userManifest.permission),
+		secretSchema: ensurePlainObject(secretSchema),
+		isToolSet: children.length > 0,
+		tools
+	};
+}
+function createSingleToolSnapshot(tool, userManifest) {
+	const handler = tool.getToolHandler();
+	if (!handler) throw new Error("default export 未注册任何工具 handler");
+	return {
+		id: "tool",
+		name: pickLocalizedText(userManifest.name),
+		description: pickLocalizedText(userManifest.description),
+		toolDescription: pickToolDescription(getOptionalString(userManifest.toolDescription), userManifest.description),
+		inputSchema: ensurePlainObject(z.toJSONSchema(handler.inputSchema)),
+		outputSchema: ensurePlainObject(z.toJSONSchema(handler.outputSchema))
+	};
+}
+function createChildToolSnapshot(tool, child) {
+	const handler = tool.getToolHandler(child.id);
+	if (!handler) throw new Error(`找不到子工具 handler: ${child.id}`);
+	return {
+		id: child.id,
+		name: pickLocalizedText(child.name),
+		description: pickLocalizedText(child.description),
+		toolDescription: pickToolDescription(child.toolDescription, child.description),
+		inputSchema: ensurePlainObject(z.toJSONSchema(handler.inputSchema)),
+		outputSchema: ensurePlainObject(z.toJSONSchema(handler.outputSchema))
+	};
+}
+function pickTargetTool(snapshot, toolId) {
+	if (!snapshot.isToolSet) return snapshot.tools[0];
+	if (!toolId) throw new Error("当前插件是工具集，请通过 --tool <childId> 指定要调试的子工具。");
+	const tool = snapshot.tools.find((item) => item.id === toolId);
+	if (!tool) throw new Error(`找不到子工具: ${toolId}`);
+	return tool;
+}
+function createVirtualHostHandler(uploadDir) {
+	return async ({ method, args, input }) => {
+		if (method !== HOST_INVOKE_METHOD) throw new Error(`本地虚拟环境暂不支持反向调用: ${method}`);
+		const payload = ensurePlainObject(args);
+		const invokeMethod = payload.method;
+		const invokeArgs = ensurePlainObject(payload.args);
+		switch (invokeMethod) {
+			case InvokeMethodEnum.uploadFile: {
+				const buffer = await readSourceToBuffer(input);
+				const fileName = sanitizeFileName(typeof invokeArgs.fileName === "string" && invokeArgs.fileName.trim().length > 0 ? invokeArgs.fileName : "debug-upload.bin");
+				const contentType = typeof invokeArgs.contentType === "string" && invokeArgs.contentType.trim().length > 0 ? invokeArgs.contentType : "application/octet-stream";
+				const saveDir = path.resolve(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 {
+					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(invokeMethod)}`);
+		}
+	};
+}
+async function readSourceToBuffer(source) {
+	if (!source) return Buffer.alloc(0);
+	const chunks = [];
+	const iterable = source instanceof StreamData ? source.values() : source;
+	for await (const chunk of iterable) chunks.push(toBuffer(chunk));
+	return Buffer.concat(chunks);
+}
+function toBuffer(value) {
+	if (Buffer.isBuffer(value)) return value;
+	if (value instanceof Uint8Array) return Buffer.from(value);
+	if (typeof value === "string") return Buffer.from(value);
+	return Buffer.from(JSON.stringify(value));
+}
+function isPackableToolExport(value) {
+	return Boolean(value && typeof value === "object" && "getUserToolManifest" in value && typeof value.getUserToolManifest === "function" && "getSecretSchema" in value && typeof value.getSecretSchema === "function" && "getToolHandler" in value && typeof value.getToolHandler === "function" && "getChildManifests" in value && typeof value.getChildManifests === "function");
+}
+function pickLocalizedText(value) {
+	if (typeof value === "string") return value;
+	if (value && typeof value === "object") {
+		const localized = value;
+		const preferred = [
+			localized["zh-CN"],
+			localized.en,
+			...Object.values(localized)
+		].find((item) => typeof item === "string" && item.trim().length > 0);
+		if (typeof preferred === "string") return preferred;
+	}
+	return "";
+}
+function pickToolDescription(explicitDescription, fallbackSource) {
+	if (explicitDescription && explicitDescription.trim().length > 0) return explicitDescription;
+	return pickLocalizedText(fallbackSource);
+}
+function getRequiredString(value, message) {
+	if (typeof value === "string" && value.trim().length > 0) return value;
+	throw new Error(message);
+}
+function getOptionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function toStringArray(value) {
+	if (!Array.isArray(value)) return;
+	const items = value.filter((item) => typeof item === "string");
+	return items.length > 0 ? items : void 0;
+}
+function ensurePlainObject(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function sanitizeFileName(fileName) {
+	return Array.from(fileName, (char) => {
+		const code = char.charCodeAt(0);
+		if (INVALID_FILE_NAME_CHARS.has(char) || code <= 31) return "_";
+		return char;
+	}).join("");
+}
+const INVALID_FILE_NAME_CHARS = new Set([
+	"<",
+	">",
+	":",
+	"\"",
+	"/",
+	"\\",
+	"|",
+	"?",
+	"*"
+]);
+async function assertPathExists(targetPath, message) {
+	try {
+		await fs.access(targetPath);
+	} catch {
+		throw new Error(message);
+	}
+}
+
+//#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);
+		});
+	}
+	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({
+			entryDir,
+			uploadDir
+		});
+		this.printSnapshot(session.snapshot, uploadDir);
+		if (!options.run) return;
+		const input = await this.readJsonOption(options.input, options.inputFile, "input");
+		const secrets = await this.readJsonOption(options.secrets, options.secretsFile, "secrets");
+		const systemVar = await this.readJsonOption(options.systemVar, options.systemVarFile, "systemVar");
+		const result = await runDebugTool({
+			runtime: session.runtime,
+			snapshot: session.snapshot,
+			toolId: options.tool,
+			input: input ?? {},
+			secrets,
+			systemVar
+		});
+		logger.success(`本地调试执行完成: ${session.snapshot.isToolSet ? options.tool ?? "" : session.snapshot.pluginId}`.trim());
+		logger.info(`虚拟时间: ${result.systemVar.time}`);
+		this.printStreamMessages(result.streamMessages);
+		if (result.response) logger.info(`返回结果:\n${JSON.stringify(result.response, null, 2)}`);
+		if (result.error) {
+			logger.error(result.error);
+			process.exit(1);
+		}
+	}
+	printSnapshot(snapshot, uploadDir) {
+		const lines = [
+			"插件信息",
+			`  entry: ${snapshot.entryDir}`,
+			`  index: ${snapshot.indexPath}`,
+			`  pluginId: ${snapshot.pluginId}`,
+			`  version: ${snapshot.version}`,
+			`  name: ${snapshot.name || "-"}`,
+			`  description: ${snapshot.description || "-"}`,
+			`  toolDescription: ${snapshot.toolDescription || "-"}`,
+			`  author: ${snapshot.author ?? "-"}`,
+			`  tags: ${snapshot.tags?.join(", ") ?? "-"}`,
+			`  permissions: ${snapshot.permissions?.join(", ") ?? "-"}`,
+			`  uploadDir: ${uploadDir}`,
+			`  secretKeys: ${this.formatSchemaKeys(snapshot.secretSchema)}`
+		];
+		logger.info(lines.join("\n"));
+		const toolLines = ["可调试工具"];
+		snapshot.tools.forEach((tool) => {
+			toolLines.push(`  - id: ${tool.id}`);
+			toolLines.push(`    name: ${tool.name || "-"}`);
+			toolLines.push(`    description: ${tool.description || "-"}`);
+			toolLines.push(`    inputKeys: ${this.formatSchemaKeys(tool.inputSchema)}`);
+			toolLines.push(`    command: ${this.buildCommand(snapshot, tool)}`);
+		});
+		logger.info(toolLines.join("\n"));
+	}
+	printStreamMessages(messages) {
+		if (messages.length === 0) {
+			logger.info("流式输出: 无");
+			return;
+		}
+		const lines = ["流式输出"];
+		messages.forEach((message) => {
+			switch (message.type) {
+				case "stream":
+					lines.push(`  [${message.data.type}] ${message.data.content}`);
+					break;
+				case "response":
+					lines.push("  [response] 已收到最终返回结果");
+					break;
+				case "error":
+					lines.push(`  [error] ${message.data}`);
+					break;
+			}
+		});
+		logger.info(lines.join("\n"));
+	}
+	buildCommand(snapshot, tool) {
+		return [
+			"fastgpt-plugin",
+			"debug",
+			snapshot.entryDir,
+			"--run",
+			...snapshot.isToolSet ? ["--tool", tool.id] : [],
+			"--input",
+			JSON.stringify(this.createInputExample(tool.inputSchema))
+		].map(quoteShellArg).join(" ");
+	}
+	createInputExample(schema) {
+		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
+		if ("const" in schema) return schema.const;
+		if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) return this.createInputExample(asObject(schema.anyOf[0]));
+		if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return this.createInputExample(asObject(schema.oneOf[0]));
+		switch (schema.type) {
+			case "object": {
+				const properties = asObject(schema.properties);
+				return Object.fromEntries(Object.entries(properties).map(([key, value]) => [key, this.createInputExample(asObject(value))]));
+			}
+			case "array": return [];
+			case "integer":
+			case "number": return 0;
+			case "boolean": return true;
+			case "string": return "";
+			default: return {};
+		}
+	}
+	formatSchemaKeys(schema) {
+		const properties = asObject(schema.properties);
+		const keys = Object.keys(properties);
+		return keys.length > 0 ? keys.join(", ") : "-";
+	}
+	async readJsonOption(inlineValue, filePath, label) {
+		if (!inlineValue && !filePath) return;
+		if (inlineValue && filePath) throw new Error(`${label} 只能传入一种来源：JSON 字符串或 JSON 文件。`);
+		const raw = inlineValue ?? await fs.readFile(path.resolve(filePath), "utf-8");
+		try {
+			const parsed = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+			return parsed;
+		} catch {
+			throw new Error(`${label} 解析失败，请提供合法的 JSON object。`);
+		}
+	}
+};
+function asObject(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function quoteShellArg(value) {
+	if (/^[a-zA-Z0-9_./:@-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
 //#endregion
 //#region src/commands/pack.ts
+/**
+* `.pkg` 文件结构：
+*   index.js
+*   manifest.json
+*   *.logo.*
+*   README.md（可选）
+*   assets/**（可选）
+*/
 var PackCommand = class extends BaseCommand {
 	register(parent) {
-		parent.command("pack").description("将 FastGPT 工具或工具集打包为 .pkg 文件").option("-e, --entry <path>", "工具入口目录", process.cwd()).option("-o, --output <path>", "输出目录（默认使用入口目录）").option("-n, --name <name>", "包名称（默认使用入口目录名）").action(async (opts) => {
+		parent.command("pack").description("基于 build 产物打包 FastGPT 工具或工具集").option("-e, --entry <path>", "工具源码根目录", process.cwd()).option("-d, --dist <path>", "构建产物目录", "./dist").option("-o, --output <path>", "pkg 输出目录（默认使用入口目录）").option("-n, --name <name>", "包名称（默认使用入口目录名）").action(async (opts) => {
 			await this.run(opts);
 		});
 	}
 	async run(options) {
 		const start = Date.now();
 		const entryDir = path.resolve(options.entry);
+		const distDir = path.resolve(entryDir, options.dist);
 		const outputDir = path.resolve(options.output || entryDir);
-		const toolName = options.name || path.basename(entryDir);
-		const pkgPath = path.join(outputDir, `${toolName}.pkg`);
+		const packageName = options.name || path.basename(entryDir);
+		const pkgPath = path.join(outputDir, `${packageName}.pkg`);
 		try {
-			await assertPathExists(entryDir, `入口目录不存在: ${entryDir}`);
-			const distIndexPath = path.join(entryDir, "dist", "index.js");
-			const logoPath = path.join(entryDir, "logo.svg");
-			const readmePath = path.join(entryDir, "README.md");
-			const assetsDir = path.join(entryDir, "assets");
-			const childrenDir = path.join(entryDir, "children");
-			await assertPathExists(distIndexPath, `找不到 dist/index.js 文件: ${distIndexPath}`);
-			await ensureDir(outputDir);
-			const zipFile = new ZipFile();
-			const outStream = createWriteStream(pkgPath);
-			const zipPromise = new Promise((resolve, reject) => {
-				zipFile.outputStream.pipe(outStream).on("close", () => resolve());
-				zipFile.outputStream.on("error", (err) => reject(err));
-				outStream.on("error", (err) => reject(err));
+			await buildToolPackage({
+				entry: entryDir,
+				output: distDir,
+				minify: false,
+				format: "esm"
 			});
-			zipFile.addFile(distIndexPath, "index.js");
-			if (await pathExists(logoPath)) zipFile.addFile(logoPath, "logo.svg");
-			if (await pathExists(readmePath)) zipFile.addFile(readmePath, "README.md");
-			if (await pathExists(assetsDir)) await addDirectoryToZip(zipFile, assetsDir, "assets");
-			if (await pathExists(childrenDir)) {
-				const children = await fs.readdir(childrenDir, { withFileTypes: true });
-				for (const child of children) {
-					if (!child.isDirectory()) continue;
-					const childName = child.name;
-					const childDir = path.join(childrenDir, childName);
-					const childLogoPath = path.join(childDir, "logo.svg");
-					zipFile.addEmptyDirectory(`${childName}/`);
-					if (await pathExists(childLogoPath)) zipFile.addFile(childLogoPath, `${childName}/logo.svg`);
-				}
-			}
-			zipFile.end();
-			await zipPromise;
+			await ensureDir(outputDir);
+			await zipDirectory(distDir, pkgPath);
 			const duration = ((Date.now() - start) / 1e3).toFixed(2);
 			logger.success(`打包完成，用时 ${duration}s`);
 			logger.info(`输出文件: ${pkgPath}`);
@@ -561,34 +1598,41 @@ var PackCommand = class extends BaseCommand {
 		}
 	}
 };
-async function pathExists(p) {
-	try {
-		await fs.access(p);
-		return true;
-	} catch {
-		return false;
-	}
-}
-async function ensureDir(dir) {
-	await fs.mkdir(dir, { recursive: true });
-}
-async function assertPathExists(p, message) {
-	try {
-		await fs.access(p);
-	} catch {
-		throw new Error(message);
+async function zipDirectory(sourceDir, pkgPath) {
+	const zipFile = new ZipFile();
+	const outStream = createWriteStream(pkgPath);
+	const zipPromise = new Promise((resolve, reject) => {
+		zipFile.outputStream.pipe(outStream).on("close", () => resolve());
+		zipFile.outputStream.on("error", (err) => reject(err));
+		outStream.on("error", (err) => reject(err));
+	});
+	const files = await collectFiles(sourceDir);
+	const normalizedPkgPath = path.resolve(pkgPath);
+	for (const file of files) {
+		if (path.resolve(file.absolutePath) === normalizedPkgPath) continue;
+		zipFile.addFile(file.absolutePath, file.relativePath);
 	}
+	zipFile.end();
+	await zipPromise;
 }
-async function addDirectoryToZip(zipFile, dir, rootInZip) {
+async function collectFiles(dir, baseDir = dir) {
 	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const files = [];
 	for (const entry of entries) {
-		const fullPath = path.join(dir, entry.name);
-		const relPath = path.join(rootInZip, entry.name).split(path.sep).join("/");
+		const absolutePath = path.join(dir, entry.name);
 		if (entry.isDirectory()) {
-			zipFile.addEmptyDirectory(`${relPath}/`);
-			await addDirectoryToZip(zipFile, fullPath, relPath);
-		} else if (entry.isFile()) zipFile.addFile(fullPath, relPath);
+			files.push(...await collectFiles(absolutePath, baseDir));
+			continue;
+		}
+		if (entry.isFile()) files.push({
+			absolutePath,
+			relativePath: path.relative(baseDir, absolutePath)
+		});
 	}
+	return files;
+}
+async function ensureDir(dir) {
+	await fs.mkdir(dir, { recursive: true });
 }
 
 //#endregion
@@ -597,7 +1641,9 @@ function createProgram() {
 	const program = new Command();
 	program.name(CLI_NAME).version(CLI_VERSION).description("FastGPT 插件开发 CLI");
 	new BuildCommand().register(program);
+	new CheckCommand().register(program);
 	new CreateCommand().register(program);
+	new DebugCommand().register(program);
 	new PackCommand().register(program);
 	return program;
 }