create-koishi-ce 1.5.0 → 1.6.0

package/README.md

@@ -27,11 +27,11 @@ npm create koishi-ce my-app
 
 ## 生成的项目
 
-- **package.json**：`type: module`、`packageManager` 钉 Bun、workspaces 含 `plugins/*` 与 `external/*`；dependencies 预装全套 `@koishi-ce` 常用插件（console、config、market、auth、admin、help、sandbox 等），并预置四行 npm alias 钉住上游名——`koishi` / `@koishijs/core` / `@koishijs/loader` 指向 `@koishi-ce/koishi-shim`、`@koishijs/plugin-console` 指向 `@koishi-ce/console-shim`，社区插件由此全部解析到 CE 框架；
-- **koishi.yml**：按 server（端口 5140-5149）/ basic / console（自动打开、市场指向 registry.koishi.chat 镜像）/ storage / adapter / develop（开发模式启用热重载）分组预写；官方 adapter / database 插件以 `~` 停用条目预写，可按需启用；
+- **package.json**：`type: module`、`packageManager` 钉 Bun、workspaces 含 `plugins/*` 与 `external/*`；dependencies 预装全套 `@koishi-ce` 常用插件（console、config、market、auth、admin、help、sandbox、database-sqlite 等），并预置四行 npm alias 钉住上游名——`koishi` / `@koishijs/core` / `@koishijs/loader` 指向 `@koishi-ce/koishi-shim`、`@koishijs/plugin-console` 指向 `@koishi-ce/console-shim`，社区插件由此全部解析到 CE 框架；
+- **koishi.yml**：按 server（端口 5140-5149）/ basic / console（自动打开、市场指向 registry.koishi.chat 镜像）/ storage / adapter / develop（开发模式启用热重载）分组预写；官方 adapter 插件以 `~` 停用条目预写、不预装，装好后在控制台按需启用；数据库开箱即用——`database-sqlite` 默认启用，mongo / mysql / postgres 等其余 database 不预写占位条目，市场安装后自动出现；
 - **开发工具链**：devDependencies 预置 `@koishi-ce/client`、`@koishi-ce/plugin-hmr` 与 `@koishi-ce/scripts`（`koishi-scripts setup` 可在 external/ 下继续创建插件项目）。
 
-不预装任何 adapter 与 database——官方版本可后续从市场安装，peer 已被 alias 钉住不会形成双实例。
+不预装任何 adapter——官方 adapter 可后续从市场安装，peer 已被 alias 钉住不会形成双实例；数据库已由默认启用的 `database-sqlite` 覆盖，其他官方 database 同样可从市场安装。
 
 ## 许可证
 
@@ -66,11 +66,11 @@ Interactive flow: project name; confirm cleaning a non-empty target directory; c
 
 ## Generated project
 
-- **package.json** — `type: module`, `packageManager` pinned to Bun, workspaces covering `plugins/*` and `external/*`; dependencies preinstall the common `@koishi-ce` plugin set (console, config, market, auth, admin, help, sandbox, etc.) plus the four npm-alias lines pinning the upstream names (`koishi` / `@koishijs/core` / `@koishijs/loader` to `@koishi-ce/koishi-shim`, `@koishijs/plugin-console` to `@koishi-ce/console-shim`), so community plugins all resolve to the CE framework.
-- **koishi.yml** — grouped prewrites for server (ports 5140-5149), basic, console (auto-open, market pointed at the registry.koishi.chat mirror), storage, adapter and develop (HMR in development mode); official adapter / database plugins are prewritten as `~`-disabled entries.
+- **package.json** — `type: module`, `packageManager` pinned to Bun, workspaces covering `plugins/*` and `external/*`; dependencies preinstall the common `@koishi-ce` plugin set (console, config, market, auth, admin, help, sandbox, database-sqlite, etc.) plus the four npm-alias lines pinning the upstream names (`koishi` / `@koishijs/core` / `@koishijs/loader` to `@koishi-ce/koishi-shim`, `@koishijs/plugin-console` to `@koishi-ce/console-shim`), so community plugins all resolve to the CE framework.
+- **koishi.yml** — grouped prewrites for server (ports 5140-5149), basic, console (auto-open, market pointed at the registry.koishi.chat mirror), storage, adapter and develop (HMR in development mode); official adapter plugins are prewritten as `~`-disabled entries without being installed — enable them in the console after installing; the database works out of the box (`database-sqlite` enabled by default), while other official databases (mongo / mysql / postgres, ...) leave no placeholder entries and appear automatically once installed from the market.
 - **Toolchain** — devDependencies include `@koishi-ce/client`, `@koishi-ce/plugin-hmr` and `@koishi-ce/scripts` (`koishi-scripts setup` scaffolds further plugin projects under external/).
 
-No adapter or database is preinstalled — official ones can be installed from the market later; their peers are already pinned by the aliases.
+No adapter is preinstalled — official adapters can be installed from the market later, with their peers already pinned by the aliases; the database is covered by the default-enabled `database-sqlite`, and other official databases are equally one market install away.
 
 ## License
 

package/lib/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { t as start } from "./src-t_F40fpK.mjs";
+import { t as start } from "./src-C3GEQDVG.mjs";
 //#region src/bin.ts
 /**
 * create-koishi-ce 的 CLI 可执行入口：shebang 由 rolldown 原样保留到

package/lib/index.d.ts

@@ -21,20 +21,20 @@ interface Manifest {
  * 改写模板的 package.json（纯函数，导出供单测）：替换项目名、标记
  * private、版本归零。
  */
-declare function renderManifest(source: Manifest, project: string, prod: boolean): string;
+export declare function renderManifest(source: Manifest, project: string, prod: boolean): string;
 //#endregion
 //#region src/registry.d.ts
 /**
  * 从单个 .npmrc 文件提取 registry 配置项（非注释、非 scoped 的 registry= 行）。
  * 文件不存在或未配置时返回 undefined，读文件异常一律静默吞掉。
  */
-declare function readNpmrcRegistry(file: string): string | undefined;
+export declare function readNpmrcRegistry(file: string): string | undefined;
 /**
  * 读取本机 npm registry 配置（优先级对齐 npm 自身：环境变量 > 项目
  * .npmrc > 用户 ~/.npmrc）。任何一步都拿不到时返回 undefined，由调用方
  * 回落官方源。
  */
-declare function getLocalRegistry(cwd?: string, userHome?: string): string | undefined;
+export declare function getLocalRegistry(cwd?: string, userHome?: string): string | undefined;
 //#endregion
 //#region src/utils.d.ts
 /**
@@ -42,13 +42,13 @@ declare function getLocalRegistry(cwd?: string, userHome?: string): string | und
  * 生态习惯；其余场景（npm、bun 及探测不到 user-agent）一律走 bun——
  * 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
  */
-declare function detectAgent(): string;
+export declare function detectAgent(): string;
 //#endregion
 //#region src/index.d.ts
 /**
  * CLI 主流程：--help 打印用法后即返回；否则依次执行
  * 项目名询问 → prepare（目录准备）→ scaffold（模板解包）→ initGit → install。
  */
-declare function start(): Promise<void>;
+export declare function start(): Promise<void>;
 //#endregion
-export { type Manifest, detectAgent, getLocalRegistry, readNpmrcRegistry, renderManifest, start };
+export type { Manifest };

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as renderManifest, i as readNpmrcRegistry, n as detectAgent, r as getLocalRegistry, t as start } from "./src-t_F40fpK.mjs";
+import { a as renderManifest, i as readNpmrcRegistry, n as detectAgent, r as getLocalRegistry, t as start } from "./src-C3GEQDVG.mjs";
 export { detectAgent, getLocalRegistry, readNpmrcRegistry, renderManifest, start };

package/lib/{src-t_F40fpK.mjs → src-C3GEQDVG.mjs}

@@ -1,17 +1,15 @@
-import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { homedir } from "node:os";
 import { downloadTemplate } from "giget";
-import { fileURLToPath } from "node:url";
 //#region package.json
 var package_default = {
 	name: "create-koishi-ce",
 	description: "Setup a Koishi application",
-	version: "1.5.0",
+	version: "1.6.0",
 	type: "module",
 	main: "./lib/index.mjs",
 	module: "./lib/index.mjs",
@@ -100,7 +98,7 @@ function readNpmrcRegistry(file) {
 */
 function getLocalRegistry(cwd = process.cwd(), userHome = homedir()) {
 	const candidates = [
-		process.env["npm_config_registry"],
+		Bun.env["npm_config_registry"],
 		readNpmrcRegistry(join(cwd, ".npmrc")),
 		readNpmrcRegistry(join(userHome, ".npmrc"))
 	];
@@ -213,7 +211,7 @@ function writePackageJson(rootDir, project, prod) {
 * 恒存在）。
 */
 function locateTemplateDir() {
-	const base = dirname(fileURLToPath(import.meta.url));
+	const base = import.meta.dir;
 	for (const dir of [join(base, "template"), join(base, "../src/template")]) if (existsSync(dir)) return dir;
 	throw new Error("create-koishi-ce 内置模板目录缺失（src/template）");
 }
@@ -241,7 +239,12 @@ function baseManifest() {
 		scripts: {
 			start: "koishi start",
 			dev: "NODE_ENV=development koishi start",
-			new: "koishi-scripts setup"
+			new: "koishi-scripts setup",
+			clone: "koishi-scripts clone",
+			build: "koishi-scripts build",
+			"release:version": "koishi-scripts version",
+			"release:dryrun": "bun run release:version && bun run build && koishi-scripts publish --dry-run",
+			release: "bun run release:version && bun run build && koishi-scripts publish"
 		},
 		dependencies: {
 			"@koishi-ce/koishi": "^1.0.0",
@@ -305,23 +308,28 @@ function baseManifest() {
 * 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
 */
 function detectAgent() {
-	const ua = process.env["npm_config_user_agent"] ?? "";
+	const ua = Bun.env["npm_config_user_agent"] ?? "";
 	if (ua.startsWith("yarn")) return "yarn";
 	if (ua.startsWith("pnpm")) return "pnpm";
 	return "bun";
 }
 /** 静默执行命令探测其是否可用（如 git --version），失败即视为不可用 */
 function supports(command) {
-	return spawnSync(command[0] ?? "", command.slice(1), { stdio: "ignore" }).status === 0;
+	return Bun.spawnSync({
+		cmd: [...command],
+		stdout: "ignore",
+		stderr: "ignore"
+	}).success;
 }
 /** 读 git 全局配置单项（读不到 → 空串） */
 function gitConfig(key) {
-	const res = spawnSync("git", [
+	const res = Bun.spawnSync([
+		"git",
 		"config",
 		"--get",
 		key
-	], { encoding: "utf8" });
-	return res.status === 0 ? res.stdout?.trim() ?? "" : "";
+	]);
+	return res.success ? res.stdout.toString().trim() : "";
 }
 /** 递归清空目录内容（目录本身保留）。 */
 function emptyDir(root) {
@@ -475,12 +483,15 @@ async function scaffold() {
 async function initGit() {
 	if (!argv.git || !supports(["git", "--version"])) return;
 	const branch = gitConfig("init.defaultBranch") || "main";
-	spawnSync("git", [
-		"init",
-		"-b",
-		branch
-	], {
-		stdio: "ignore",
+	Bun.spawnSync({
+		cmd: [
+			"git",
+			"init",
+			"-b",
+			branch
+		],
+		stdout: "ignore",
+		stderr: "ignore",
 		cwd: rootDir
 	});
 	console.log(pc.green(`  已初始化 git 仓库（分支 ${branch}）。\n`));
@@ -494,15 +505,19 @@ async function install() {
 	const agent = detectAgent();
 	const startArgs = agent === "yarn" ? ["start"] : ["run", "start"];
 	if (await confirm("现在安装依赖并启动吗？")) {
-		if (spawnSync(agent, ["install"], {
-			stdio: "inherit",
+		if (!Bun.spawnSync({
+			cmd: [agent, "install"],
+			stdout: "inherit",
+			stderr: "inherit",
 			cwd: rootDir
-		}).status !== 0) {
+		}).success) {
 			console.log(pc.red("  依赖安装失败，请检查上方日志。"));
 			return;
 		}
-		spawnSync(agent, startArgs, {
-			stdio: "inherit",
+		Bun.spawnSync({
+			cmd: [agent, ...startArgs],
+			stdout: "inherit",
+			stderr: "inherit",
 			cwd: rootDir
 		});
 	} else {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "create-koishi-ce",
     "description": "Setup a Koishi application",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "type": "module",
     "main": "./lib/index.mjs",
     "module": "./lib/index.mjs",

package/src/__tests__/manifest.test.ts

@@ -46,13 +46,13 @@ test("renderManifest prod 模式：删除 workspaces 与 devDependencies", () =>
 
 test("detectAgent：yarn / pnpm 跟随探测，其余一律 bun", () => {
 	const key = "npm_config_user_agent";
-	process.env[key] =
+	Bun.env[key] =
 		"npm/10.9.2 node/v22.14.0 x64 workspaces/false";
 	expect(detectAgent()).toBe("bun");
-	process.env[key] = "yarn/1.22.22 npm/? node/v22.14.0 x64";
+	Bun.env[key] = "yarn/1.22.22 npm/? node/v22.14.0 x64";
 	expect(detectAgent()).toBe("yarn");
-	process.env[key] = "pnpm/10.12.1 npm/? node/v22.14.0 x64";
+	Bun.env[key] = "pnpm/10.12.1 npm/? node/v22.14.0 x64";
 	expect(detectAgent()).toBe("pnpm");
-	delete process.env[key];
+	delete Bun.env[key];
 	expect(detectAgent()).toBe("bun");
 });

package/src/__tests__/registry.test.ts

@@ -45,22 +45,22 @@ test("getLocalRegistry：环境变量优先且校验协议，非法值跳过", (
 	const isolated = mkdtempSync(
 		join(tmpdir(), "ckc-npmrc-"),
 	);
-	process.env[key] = "https://registry.example.com/";
+	Bun.env[key] = "https://registry.example.com/";
 	expect(getLocalRegistry(isolated, isolated)).toBe(
 		"https://registry.example.com/",
 	);
 	// 非 http(s) 的值视为未配置，继续走后续候选
-	process.env[key] = "ftp://not-a-registry/";
+	Bun.env[key] = "ftp://not-a-registry/";
 	expect(
 		getLocalRegistry(isolated, isolated),
 	).toBeUndefined();
-	delete process.env[key];
+	delete Bun.env[key];
 	rmSync(isolated, { recursive: true, force: true });
 });
 
 test("getLocalRegistry：项目 .npmrc 优先于用户级 .npmrc，均无配置时返回 undefined", () => {
 	const key = "npm_config_registry";
-	delete process.env[key];
+	delete Bun.env[key];
 	const dir = mkdtempSync(join(tmpdir(), "ckc-npmrc-"));
 	const emptyHome = mkdtempSync(
 		join(tmpdir(), "ckc-home-"),

package/src/__tests__/run-default.test.ts

@@ -8,8 +8,8 @@ import {
 	expect,
 	it,
 	mock,
+	spyOn,
 } from "bun:test";
-import { spawnSync } from "node:child_process";
 import {
 	existsSync,
 	mkdirSync,
@@ -39,9 +39,9 @@ const previousArgv = process.argv.slice();
 const previousExit = process.exit;
 // 保持无 user-agent 的探测环境（detectAgent 走 bun 分支）
 const userAgentKey = "npm_config_user_agent";
-const hadUserAgent = userAgentKey in process.env;
-const previousUserAgent = process.env[userAgentKey];
-delete process.env[userAgentKey];
+const hadUserAgent = userAgentKey in Bun.env;
+const previousUserAgent = Bun.env[userAgentKey];
+delete Bun.env[userAgentKey];
 
 /** @clack/prompts 的可编程答案队列（按 prompt 类型分发） */
 const nameAnswers: string[] = [];
@@ -62,58 +62,109 @@ const spawnLog: Array<{
 }> = [];
 let installExit = 0;
 
-// 本文件求值时 node:child_process 恒为真实实现（本仓测试中唯一的
-// child_process mock 注册点），持有真实引用供未知命令透传；mock 的
-// 命名空间改写会波及其它测试文件经活绑定发起的调用（如 setup 的
-// git init、release 的子进程测试），透传保证它们拿到真实行为
-const realSpawnSync = spawnSync;
+// 本文件求值时 Bun.spawnSync 恒为真实实现（本仓测试中唯一的子进程 mock
+// 注册点），持有真实引用供未知命令透传；mock 改写会波及其它测试文件经
+// 全局命名空间发起的调用（如 setup 的 git init、release 的子进程测试），
+// 透传保证它们拿到真实行为
+const realSpawnSync = Bun.spawnSync;
 
-mock.module("node:child_process", () => ({
-	spawnSync: (
-		cmd: string,
-		args: readonly string[],
-		options: { cwd?: string },
-	) => {
-		if (cmd === "git" && args[0] === "--version")
-			return { status: 0 };
-		if (
-			cmd === "git" &&
-			args[0] === "config" &&
-			args[1] === "--get"
-		) {
-			const key = args[2];
-			const table: Record<string, string> = {
-				"user.name": "Tester",
-				"user.email": "t@e.st",
-				"init.defaultBranch": "trunk",
-			};
-			const value =
-				key !== undefined ? table[key] : undefined;
-			return value === undefined
-				? { status: 1, stdout: "" }
-				: { status: 0, stdout: `${value}\n` };
-		}
-		// exactOptionalPropertyTypes：cwd 未传时不落键，避免显式写入 undefined
-		spawnLog.push({
-			cmd,
-			args: [...args],
-			...(options.cwd === undefined
-				? {}
-				: { cwd: options.cwd }),
-		});
-		// 依赖安装可编程；agent 启动不真实拉起
-		if (args[0] === "install")
-			return { status: installExit };
-		if (cmd === "bun" && args[0] === "run")
-			return { status: 0 };
-		// 其余命令透传真实执行（副作用均在各自测试的临时目录内）
-		return realSpawnSync(
-			cmd,
-			args,
-			options as Parameters<typeof spawnSync>[2],
+/** 构造 SyncSubprocess 形态的假结果（补全 resourceUsage / pid 等必要字段） */
+function fakeResult(exitCode: number, stdout = "") {
+	return {
+		exitCode,
+		success: exitCode === 0,
+		stdout,
+		stderr: "",
+	} as unknown as ReturnType<typeof Bun.spawnSync>;
+}
+
+/** Bun.spawnSync 调用选项中被本 mock 关心的子集（透传时原样保留） */
+interface SpawnOptionsLike {
+	cmd?: readonly string[];
+	cwd?: string;
+	stdout?: "ignore" | "inherit" | "pipe";
+	stderr?: "ignore" | "inherit" | "pipe";
+}
+
+/**
+ * 把 Bun.spawnSync 的两种调用形态归一为 { cmd, args, cwd, passthrough }。
+ * invoke 为 unknown 数组（重载联合无法静态表达），内部运行时收窄。
+ */
+function normalize(invoke: readonly unknown[]): {
+	cmd: string;
+	args: string[];
+	cwd?: string;
+	passthrough: () => ReturnType<typeof Bun.spawnSync>;
+} {
+	const first = invoke[0];
+	const options = (
+		Array.isArray(first) ? (invoke[1] ?? {}) : first
+	) as SpawnOptionsLike;
+	const argv = (
+		Array.isArray(first) ? first : (options.cmd ?? [])
+	) as readonly string[];
+	const cmd = argv[0] ?? "";
+	const args = [...argv.slice(1)];
+	return {
+		cmd,
+		args,
+		...(options.cwd === undefined
+			? {}
+			: { cwd: options.cwd }),
+		passthrough: () =>
+			realSpawnSync({
+				cmd: [cmd, ...args],
+				...(options.stdout === undefined
+					? {}
+					: { stdout: options.stdout }),
+				...(options.stderr === undefined
+					? {}
+					: { stderr: options.stderr }),
+				...(options.cwd === undefined
+					? {}
+					: { cwd: options.cwd }),
+			}),
+	};
+}
+
+/** 拦截 Bun.spawnSync：git 探测 / 配置读取走桩，其余记录或透传真实执行 */
+spyOn(Bun, "spawnSync").mockImplementation(((
+	...invoke: readonly unknown[]
+) => {
+	const { cmd, args, cwd, passthrough } = normalize(invoke);
+	if (cmd === "git" && args[0] === "--version")
+		return fakeResult(0);
+	if (
+		cmd === "git" &&
+		args[0] === "config" &&
+		args[1] === "--get"
+	) {
+		const key = args[2];
+		const table: Record<string, string> = {
+			"user.name": "Tester",
+			"user.email": "t@e.st",
+			"init.defaultBranch": "trunk",
+		};
+		const value =
+			key !== undefined ? table[key] : undefined;
+		return fakeResult(
+			value === undefined ? 1 : 0,
+			value === undefined ? "" : `${value}\n`,
 		);
-	},
-}));
+	}
+	// exactOptionalPropertyTypes：cwd 未传时不落键，避免显式写入 undefined
+	spawnLog.push({
+		cmd,
+		args,
+		...(cwd === undefined ? {} : { cwd }),
+	});
+	// 依赖安装可编程；agent 启动不真实拉起
+	if (args[0] === "install") return fakeResult(installExit);
+	if (cmd === "bun" && args[0] === "run")
+		return fakeResult(0);
+	// 其余命令透传真实执行（副作用均在各自测试的临时目录内）
+	return passthrough();
+}) as never);
 
 /** process.exit 替换为异常，供断言「直接退出」的分支 */
 // erasableSyntaxOnly 禁用参数属性，改为显式字段声明
@@ -156,9 +207,9 @@ afterAll(() => {
 	process.exit = previousExit;
 	process.argv = previousArgv;
 	if (hadUserAgent) {
-		process.env[userAgentKey] = previousUserAgent;
+		Bun.env[userAgentKey] = previousUserAgent;
 	} else {
-		delete process.env[userAgentKey];
+		delete Bun.env[userAgentKey];
 	}
 	rmSync(workspaceRoot, { recursive: true, force: true });
 });

package/src/__tests__/tar-pack.ts

@@ -11,8 +11,6 @@
  * 端到端链路间接验证。
  */
 
-import { gzipSync } from "node:zlib";
-
 const BLOCK = 512;
 const encoder = new TextEncoder();
 
@@ -207,5 +205,5 @@ export async function tarPack(
 	}
 
 	// gzip 压缩为 .tgz（与 npm registry 的 tarball 同构）
-	return gzipSync(raw);
+	return Bun.gzipSync(raw);
 }

package/src/__tests__/template.test.ts

@@ -48,6 +48,27 @@ test("内置模板 packageManager 钉 Bun，脚本用 Bun Shell 环境变量前
 	);
 });
 
+test("内置模板提供插件开发全链脚本入口（koishi-scripts 子命令形态）", () => {
+	const { scripts } = baseManifest() as unknown as {
+		scripts: Record<string, string>;
+	};
+	// 插件开发链 = devDep @koishi-ce/scripts 的 koishi-scripts CLI 子命令；
+	// new 用主命令名 setup（new/create/init 是 koishi-scripts 的别名）
+	expect(scripts["new"]).toBe("koishi-scripts setup");
+	expect(scripts["clone"]).toBe("koishi-scripts clone");
+	expect(scripts["build"]).toBe("koishi-scripts build");
+	expect(scripts["release:version"]).toBe(
+		"koishi-scripts version",
+	);
+	// release 链 = version → build → publish 三环串联（前环自引用脚本）
+	expect(scripts["release"]).toBe(
+		"bun run release:version && bun run build && koishi-scripts publish",
+	);
+	expect(scripts["release:dryrun"]).toBe(
+		"bun run release:version && bun run build && koishi-scripts publish --dry-run",
+	);
+});
+
 test("内置模板以 npm alias 钉住 koishi 裸名，版本保持 4.18.x 冻结线", () => {
 	const request = baseManifest().dependencies?.["koishi"];
 	expect(typeof request).toBe("string");

package/src/index.ts

@@ -22,7 +22,6 @@
  * - remote.ts     --template 远程模板的下载-解包-改写全流程
  * - template.ts   内置 @koishi-ce 模板（静态文件与 baseManifest）
  */
-import { spawnSync } from "node:child_process";
 import {
 	existsSync,
 	mkdirSync,
@@ -216,8 +215,10 @@ async function scaffold() {
 async function initGit() {
 	if (!argv.git || !supports(["git", "--version"])) return;
 	const branch = gitConfig("init.defaultBranch") || "main";
-	spawnSync("git", ["init", "-b", branch], {
-		stdio: "ignore",
+	Bun.spawnSync({
+		cmd: ["git", "init", "-b", branch],
+		stdout: "ignore",
+		stderr: "ignore",
 		cwd: rootDir,
 	});
 	console.log(
@@ -238,18 +239,22 @@ async function install() {
 		agent === "yarn" ? ["start"] : ["run", "start"];
 	const yes = await confirm("现在安装依赖并启动吗？");
 	if (yes) {
-		const installed = spawnSync(agent, ["install"], {
-			stdio: "inherit",
+		const installed = Bun.spawnSync({
+			cmd: [agent, "install"],
+			stdout: "inherit",
+			stderr: "inherit",
 			cwd: rootDir,
 		});
-		if (installed.status !== 0) {
+		if (!installed.success) {
 			console.log(
 				pc.red("  依赖安装失败，请检查上方日志。"),
 			);
 			return;
 		}
-		spawnSync(agent, startArgs, {
-			stdio: "inherit",
+		Bun.spawnSync({
+			cmd: [agent, ...startArgs],
+			stdout: "inherit",
+			stderr: "inherit",
 			cwd: rootDir,
 		});
 	} else {

package/src/registry.ts

@@ -45,7 +45,7 @@ export function getLocalRegistry(
 	userHome: string = homedir(),
 ): string | undefined {
 	const candidates = [
-		process.env["npm_config_registry"],
+		Bun.env["npm_config_registry"],
 		readNpmrcRegistry(join(cwd, ".npmrc")),
 		readNpmrcRegistry(join(userHome, ".npmrc")),
 	];

package/src/template/README.md

@@ -30,4 +30,18 @@ bun run dev          # 启动（开发模式，启用 HMR 热更新）
 
 ## 自定义插件
 
-在 `plugins/` 目录下创建插件包（可用 `bun run new <名称>` 生成骨架），在 `koishi.yml` 中以相对路径引用（如 `./plugins/my-plugin`）即可启用；Bun 直接加载 TypeScript 源码，无需预编译。
+手动在 `plugins/` 目录下创建插件包，或经脚手架进入 `external/` 工作区：
+
+- `bun run new <名称>` —— 生成插件骨架到 `external/`（`--console` 附带控制台前端扩展）
+- `bun run clone <仓库>` —— 克隆已有插件源码到 `external/` 本地联动调试
+
+两种来源的插件都在 `koishi.yml` 中以相对路径引用（如 `./plugins/my-plugin`、`./external/my-plugin`）即可启用；Bun 直接加载 TypeScript 源码，无需预编译。
+
+## 插件构建与发布
+
+针对 `external/` 工作区的插件项目：
+
+- `bun run build` —— 串行构建 `external/` 下全部可构建项目
+- `bun run release:version` —— 消费 pending changeset 提升版本号
+- `bun run release:dryrun` —— 完整发布链演练（version → build → publish --dry-run）
+- `bun run release` —— 完整发布链（version → build → publish）

package/src/template/koishi.yml

@@ -34,6 +34,7 @@ plugins:
     insight:ozp3by: {}
     notifier:30g7rg: {}
     theme-vanilla:029kuh: {}
+    welcome:q7m2vx: {}
   group:basic:
     $collapsed: true
     $label: 基础库

package/src/template.ts

@@ -39,8 +39,7 @@ import {
 	readdirSync,
 	readFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import type { Manifest } from "./manifest.ts";
 
 /**
@@ -49,7 +48,7 @@ import type { Manifest } from "./manifest.ts";
  * 恒存在）。
  */
 function locateTemplateDir(): string {
-	const base = dirname(fileURLToPath(import.meta.url));
+	const base = import.meta.dir;
 	for (const dir of [
 		join(base, "template"),
 		join(base, "../src/template"),
@@ -98,7 +97,20 @@ export function baseManifest(): Manifest {
 			start: "koishi start",
 			// bun run 走 Bun Shell，`NODE_ENV=...` 前缀天然跨平台，无需 cross-env
 			dev: "NODE_ENV=development koishi start",
+			// 插件开发链（devDep @koishi-ce/scripts 的 koishi-scripts CLI，操作
+			// 本工作区 plugins/ 与 external/；纯运行 bot 的项目用不到这些入口，
+			// prod 模式删 devDependencies 后它们自然失效）：
+			// new 生成插件骨架到 external/，clone 克隆已有插件仓库本地联动，
+			// build / release* 构建并发布 external/ 下的插件（version → build
+			// → publish 三环，dry-run 为演练形态）
 			new: "koishi-scripts setup",
+			clone: "koishi-scripts clone",
+			build: "koishi-scripts build",
+			"release:version": "koishi-scripts version",
+			"release:dryrun":
+				"bun run release:version && bun run build && koishi-scripts publish --dry-run",
+			release:
+				"bun run release:version && bun run build && koishi-scripts publish",
 		},
 		dependencies: {
 			"@koishi-ce/koishi": "^1.0.0",

package/src/utils.ts

@@ -8,7 +8,6 @@
  * prepare 步骤调用，也是除 manifest.ts / registry.ts 之外可脱离交互
  * 直接单测的函数集合。
  */
-import { spawnSync } from "node:child_process";
 import { readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
@@ -18,7 +17,7 @@ import { join } from "node:path";
  * 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
  */
 export function detectAgent(): string {
-	const ua = process.env["npm_config_user_agent"] ?? "";
+	const ua = Bun.env["npm_config_user_agent"] ?? "";
 	if (ua.startsWith("yarn")) return "yarn";
 	if (ua.startsWith("pnpm")) return "pnpm";
 	return "bun";
@@ -26,19 +25,22 @@ export function detectAgent(): string {
 
 /** 静默执行命令探测其是否可用（如 git --version），失败即视为不可用 */
 export function supports(command: readonly string[]) {
-	return (
-		spawnSync(command[0] ?? "", command.slice(1), {
-			stdio: "ignore",
-		}).status === 0
-	);
+	return Bun.spawnSync({
+		cmd: [...command],
+		stdout: "ignore",
+		stderr: "ignore",
+	}).success;
 }
 
 /** 读 git 全局配置单项（读不到 → 空串） */
 export function gitConfig(key: string): string {
-	const res = spawnSync("git", ["config", "--get", key], {
-		encoding: "utf8",
-	});
-	return res.status === 0 ? (res.stdout?.trim() ?? "") : "";
+	const res = Bun.spawnSync([
+		"git",
+		"config",
+		"--get",
+		key,
+	]);
+	return res.success ? res.stdout.toString().trim() : "";
 }
 
 /** 递归清空目录内容（目录本身保留）。 */