create-koishi-ce 1.0.1 → 1.1.0

package/lib/bin.mjs

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

package/lib/index.d.ts

@@ -8,7 +8,8 @@ interface Manifest {
   private?: boolean;
   version?: string;
   workspaces?: unknown;
-  devDependencies?: unknown;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
   [key: string]: unknown;
 }
 /**

package/lib/index.mjs

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

package/lib/{src-B_s70NbL.mjs → src-CUSQBq1d.mjs}

@@ -7,23 +7,11 @@ import kleur from "kleur";
 import prompts from "prompts";
 import { extract } from "tar";
 import parse from "yargs-parser";
-//#endregion
-//#region src/index.ts
-/**
-* create-koishi-ce 脚手架（npm 包名 create-koishi-ce，目录名为
-* apps/koishi-create，二者不一致是历史遗留，以目录名为准）。
-*
-* 通过 `bunx create-koishi-ce [name]`（npx 亦可）交互式创建 Koishi 机器人
-* 应用项目：确定项目名 → 准备目标目录 → 从 npm registry 下载模板包（默认
-* @koishijs/boilerplate，刻意沿用上游官方模板以保持与上游插件生态一致）
-* 并解包 → 改写 package.json → 按需初始化 git → 询问是否立即安装依赖并
-* 启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段指向
-* 它）；本文件只承载主流程与可单测的纯函数（范式对齐 @koishi-ce/scripts）。
-*/
-const { version } = {
+//#region package.json
+var package_default = {
 	name: "create-koishi-ce",
 	description: "Setup a Koishi application",
-	version: "1.0.1",
+	version: "1.1.0",
 	type: "module",
 	main: "./lib/index.mjs",
 	module: "./lib/index.mjs",
@@ -72,6 +60,163 @@ const { version } = {
 		"./package.json": "./package.json"
 	}
 };
+//#endregion
+//#region src/template.ts
+/** 模板静态文件（相对项目根的路径 → 文件内容），package.json 另行渲染 */
+const templateFiles = {
+	".env": [
+		"GITHUB_MIRROR = https://ghproxy.com/https://github.com",
+		"GITHUB_CONTENT_MIRROR = https://ghproxy.com/https://raw.githubusercontent.com",
+		"GRAVATAR_MIRROR = https://cravatar.cn"
+	].join("\n"),
+	".gitignore": ["node_modules/", "data/"].join("\n"),
+	"koishi.yml": [
+		"plugins:",
+		"  group:server:",
+		"    server:",
+		"      port: 5140",
+		"      maxPort: 5149",
+		"  group:basic:",
+		"    ~admin: {}",
+		"    ~bind: {}",
+		"    commands: {}",
+		"    help: {}",
+		"    http: {}",
+		"    ~inspect: {}",
+		"    locales: {}",
+		"    proxy-agent: {}",
+		"  group:console:",
+		"    actions: {}",
+		"    ~analytics: {}",
+		"    ~auth: {}",
+		"    config: {}",
+		"    console:",
+		"      open: true",
+		"    explorer: {}",
+		"    insight: {}",
+		"    logger: {}",
+		"    market:",
+		"      search:",
+		"        endpoint: https://registry.koishi.chat/index.json",
+		"    notifier: {}",
+		"    oobe: {}",
+		"    sandbox: {}",
+		"    status: {}",
+		"  group:develop:",
+		"    $if: env.NODE_ENV === 'development'",
+		"    hmr:",
+		"      root: ."
+	].join("\n"),
+	"tsconfig.json": [
+		"{",
+		"  \"compilerOptions\": {",
+		"    \"target\": \"ESNext\",",
+		"    \"module\": \"ESNext\",",
+		"    \"moduleResolution\": \"bundler\",",
+		"    \"lib\": [\"ESNext\"],",
+		"    \"types\": [\"bun-types\"],",
+		"    \"strict\": true,",
+		"    \"skipLibCheck\": true,",
+		"    \"noEmit\": true,",
+		"    \"allowImportingTsExtensions\": true,",
+		"    \"verbatimModuleSyntax\": true,",
+		"    \"erasableSyntaxOnly\": true",
+		"  },",
+		"  \"include\": [\"plugins/*/src\", \"external/*/src\"]",
+		"}"
+	].join("\n"),
+	"README.md": `# Koishi 机器人项目
+
+由 \`bun create koishi-ce\` 生成，运行于 [@koishi-ce 社区再分发版](https://github.com/Koishi-CE/koishi) 生态。
+
+## 环境要求
+
+- [Bun](https://bun.sh) ≥ 1.2（运行时：koishi CLI 与插件加载链以 Bun 为准）
+
+## 快速开始
+
+\`\`\`bash
+bun install
+bun run start        # 启动（生产模式）
+bun run dev          # 启动（开发模式，启用 HMR 热更新）
+\`\`\`
+
+启动后访问控制台：<http://127.0.0.1:5140>
+
+## 安装插件
+
+推荐在控制台「插件市场」页安装（已预配 registry.koishi.chat 镜像源）；也可以手动 \`bun add <包名>\` 后在 \`koishi.yml\` 中启用。
+
+上游官方 adapter（如 adapter-discord / adapter-telegram）、数据库插件（如 database-sqlite）与社区 koishi-plugin-* 插件均可直接安装：根依赖中的 \`"koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"\` 已把上游生态对 \`koishi\` 的依赖钉回 @koishi-ce 框架（**请勿删除或改写该行**），不会形成第二份框架副本。analytics 等依赖数据库的插件请先安装数据库插件，再去掉配置中对应的 \`~\` 前缀启用。
+
+## 自定义插件
+
+在 \`plugins/\` 目录下创建插件包（可用 \`bun run new <名称>\` 生成骨架），在 \`koishi.yml\` 中以相对路径引用（如 \`./plugins/my-plugin\`）即可启用；Bun 直接加载 TypeScript 源码，无需预编译。
+`
+};
+/**
+* 内置模板的 package.json 基础内容（name/version 会被 renderManifest 覆写，
+* prod 模式下 workspaces 与 devDependencies 会被移除）。
+*/
+function baseManifest() {
+	return {
+		type: "module",
+		workspaces: ["plugins/*", "external/*"],
+		scripts: {
+			start: "koishi start",
+			dev: "cross-env NODE_ENV=development koishi start",
+			new: "koishi-scripts setup"
+		},
+		dependencies: {
+			"@koishi-ce/koishi": "^1.0.0",
+			"@koishi-ce/plugin-actions": "^1.0.0",
+			"@koishi-ce/plugin-admin": "^1.0.0",
+			"@koishi-ce/plugin-analytics": "^1.0.0",
+			"@koishi-ce/plugin-auth": "^1.0.0",
+			"@koishi-ce/plugin-bind": "^1.0.0",
+			"@koishi-ce/plugin-commands": "^1.0.0",
+			"@koishi-ce/plugin-config": "^1.0.0",
+			"@koishi-ce/plugin-console": "^1.0.0",
+			"@koishi-ce/plugin-explorer": "^1.0.0",
+			"@koishi-ce/plugin-help": "^1.0.0",
+			"@koishi-ce/plugin-http": "^1.0.0",
+			"@koishi-ce/plugin-insight": "^1.0.0",
+			"@koishi-ce/plugin-inspect": "^1.0.0",
+			"@koishi-ce/plugin-locales": "^1.0.0",
+			"@koishi-ce/plugin-logger": "^1.0.0",
+			"@koishi-ce/plugin-market": "^1.0.0",
+			"@koishi-ce/plugin-notifier": "^1.0.0",
+			"@koishi-ce/plugin-oobe": "^1.0.0",
+			"@koishi-ce/plugin-proxy-agent": "^1.0.0",
+			"@koishi-ce/plugin-sandbox": "^1.0.0",
+			"@koishi-ce/plugin-server": "^1.0.0",
+			"@koishi-ce/plugin-status": "^1.0.0",
+			koishi: "npm:@koishi-ce/koishi-shim@^4.18.11"
+		},
+		devDependencies: {
+			"@koishi-ce/client": "^1.0.0",
+			"@koishi-ce/plugin-hmr": "^1.0.0",
+			"@koishi-ce/scripts": "^1.0.0",
+			"bun-types": "^1.4.0",
+			"cross-env": "^7.0.3"
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* create-koishi-ce 脚手架（npm 包名 create-koishi-ce，目录名为
+* apps/koishi-create，二者不一致是历史遗留，以目录名为准）。
+*
+* 通过 `bunx create-koishi-ce [name]`（npx 亦可）交互式创建 Koishi 机器人
+* 应用项目：确定项目名 → 准备目标目录 → 写入内置 @koishi-ce 模板（默认，
+* 见 src/template.ts；--template <包名> 可改用 npm registry 远程模板，如
+* 上游官方 @koishijs/boilerplate）→ 按需初始化 git → 询问是否立即安装
+* 依赖并启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段
+* 指向它）；本文件只承载主流程与可单测的纯函数（范式对齐
+* @koishi-ce/scripts）。
+*/
+const { version } = package_default;
 /** fetch 请求非 2xx 时抛出的错误，携带 HTTP 状态码与状态文本 */
 var HttpError = class extends Error {
 	status;
@@ -217,18 +362,22 @@ function writePackageJson() {
 	writeFileSync(filename, renderManifest(meta, project, argv.prod === true));
 }
 /**
-* 模板下载与解包的主流程：
-* 1. 确定 npm registry（--registry 参数 > 本机 npm 配置 > 官方源）；
-* 2. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
-* 3. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
+* 写入内置模板（默认路径）：静态文件（src/template.ts 的 templateFiles）
+* 加上由 baseManifest() 渲染出的 package.json。纯本地写入，无网络请求。
+*/
+function scaffoldBuiltin() {
+	for (const [file, content] of Object.entries(templateFiles)) writeFileSync(join(rootDir, file), content);
+	writeFileSync(join(rootDir, "package.json"), renderManifest(baseManifest(), project, argv.prod === true));
+}
+/**
+* 远程模板下载与解包（--template 指定时）：
+* 1. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
+* 2. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
 *    网络错误统一以 HttpError 提示后退出；
-* 4. 最后改写 package.json。
+* 3. 最后改写 package.json。
 */
-async function scaffold() {
-	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
-	const registry = (argv.registry || getLocalRegistry() || "https://registry.npmjs.org").replace(/\/$/, "");
-	console.log(kleur.dim(`  使用 registry：${registry}\n`));
-	const template = argv.template || "@koishijs/boilerplate";
+async function scaffoldRemote(registry) {
+	const template = argv.template;
 	const ref = argv.ref || "latest";
 	try {
 		const metaRes = await fetch(`${registry}/${template}`);
@@ -253,6 +402,19 @@ async function scaffold() {
 		process.exit(1);
 	}
 	writePackageJson();
+}
+/**
+* 生成项目的主入口：默认写内置 @koishi-ce 模板（scaffoldBuiltin）；
+* --template <包名> 时改为从 npm registry 下载远程模板（scaffoldRemote），
+* registry 取值 --registry 参数 > 本机 npm 配置 > 官方源。
+*/
+async function scaffold() {
+	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
+	if (argv.template) {
+		const registry = (argv.registry || getLocalRegistry() || "https://registry.npmjs.org").replace(/\/$/, "");
+		console.log(kleur.dim(`  使用 registry：${registry}\n`));
+		await scaffoldRemote(registry);
+	} else scaffoldBuiltin();
 	console.log(kleur.green("  完成。\n"));
 }
 /**
@@ -313,8 +475,8 @@ async function start() {
   用法：create-koishi-ce [名称] [选项]
 
   选项：
-    -t, --template <名称>   模板包名（默认 @koishijs/boilerplate）
-    -r, --ref <引用>        模板版本引用（默认 latest）
+    -t, --template <名称>   从 npm registry 下载指定模板包（默认使用内置 @koishi-ce 模板）
+    -r, --ref <引用>        远程模板版本引用（默认 latest）
     -f, --forced            强制清空目标目录
     -g, --git               初始化 git 仓库
         --registry <地址>   指定 npm registry（如 https://registry.npmmirror.com）

package/package.json

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

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

@@ -0,0 +1,275 @@
+import { afterAll, beforeAll, describe, expect, it, mock } from "bun:test";
+import { spawnSync } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+/**
+ * start() 默认（内置模板）主流程的端到端测试。
+ *
+ * 手段：把 process.argv 指为无位置参数 + --git，chdir 到临时目录后动态
+ * 导入被测模块（其内部 cwd / argv 在模块顶层固化）；prompts 与
+ * node:child_process 均 mock，分别提供可编程的问询答案与子进程记录，
+ * process.exit 替换为可捕获的异常，从而覆盖全部交互分支。
+ */
+
+const workspaceRoot = mkdtempSync(join(tmpdir(), "ckc-run-default-"));
+const previousCwd = process.cwd();
+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];
+
+/** prompts 的可编程答案队列（按 type 分发） */
+const nameAnswers: string[] = [];
+const confirmAnswers: boolean[] = [];
+
+mock.module("prompts", () => ({
+	default: async (question: { type?: string }) => {
+		if (question.type === "confirm") {
+			return { yes: confirmAnswers.shift() ?? false };
+		}
+		return { name: nameAnswers.shift() ?? "" };
+	},
+}));
+
+/** spawnSync 的调用记录与可编程行为 */
+const spawnLog: Array<{ cmd: string; args: string[]; cwd?: string }> = [];
+let installExit = 0;
+
+// 本文件求值时 node:child_process 恒为真实实现（本仓测试中唯一的
+// child_process mock 注册点），持有真实引用供未知命令透传；mock 的
+// 命名空间改写会波及其它测试文件经活绑定发起的调用（如 setup 的
+// git init、release 的子进程测试），透传保证它们拿到真实行为
+const realSpawnSync = 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]);
+	},
+}));
+
+/** process.exit 替换为异常，供断言「直接退出」的分支 */
+// erasableSyntaxOnly 禁用参数属性，改为显式字段声明
+class ExitError extends Error {
+	code: number;
+	constructor(code: number) {
+		super(`process.exit(${code})`);
+		this.code = code;
+	}
+}
+
+process.exit = ((code?: number) => {
+	throw new ExitError(code ?? 0);
+}) as typeof process.exit;
+
+process.argv = [process.argv[0] ?? "bun", "create-koishi-ce", "--git"];
+process.chdir(workspaceRoot);
+// query 强制独立实例（说明与写法见 run-help.test.ts）
+const specifier = "../index.ts?default-run";
+const { start, getLocalRegistry, readNpmrcRegistry } = (await import(
+	specifier
+)) as typeof import("../index.ts");
+// cwd 已在被测模块内固化，立即切回，缩小对进程全局的影响窗口
+process.chdir(previousCwd);
+
+const logs: string[] = [];
+const originalLog = console.log;
+
+beforeAll(() => {
+	console.log = (...args: unknown[]) => {
+		logs.push(args.map((arg) => `${arg}`).join(" "));
+	};
+});
+
+afterAll(() => {
+	console.log = originalLog;
+	process.exit = previousExit;
+	process.argv = previousArgv;
+	if (hadUserAgent) {
+		process.env[userAgentKey] = previousUserAgent;
+	} else {
+		delete process.env[userAgentKey];
+	}
+	rmSync(workspaceRoot, { recursive: true, force: true });
+});
+
+/** 断言内置模板的静态文件齐备 */
+function expectTemplateFiles(dir: string): void {
+	for (const file of [
+		"package.json",
+		"koishi.yml",
+		"tsconfig.json",
+		".env",
+		".gitignore",
+		"README.md",
+	]) {
+		expect(existsSync(join(dir, file)), file).toBe(true);
+	}
+	const manifest = JSON.parse(
+		readFileSync(join(dir, "package.json"), "utf8"),
+	) as Record<string, unknown>;
+	expect(manifest["private"]).toBe(true);
+	expect(manifest["version"]).toBe("0.0.0");
+	expect(manifest["workspaces"]).toEqual(["plugins/*", "external/*"]);
+}
+
+describe("create-koishi-ce 默认模板主流程", () => {
+	// 补齐本实例下纯函数分支的行覆盖（registry 既有测试走的是共享实例）
+	it("registry 探测纯函数在本实例同样可用", () => {
+		const npmrc = join(workspaceRoot, ".npmrc");
+		writeFileSync(npmrc, "registry=https://registry.example.com/\n");
+		expect(readNpmrcRegistry(npmrc)).toBe("https://registry.example.com/");
+		expect(readNpmrcRegistry(join(workspaceRoot, "absent"))).toBeUndefined();
+		expect(getLocalRegistry(workspaceRoot, workspaceRoot)).toBe(
+			"https://registry.example.com/",
+		);
+		expect(getLocalRegistry(workspaceRoot, workspaceRoot)).toBeDefined();
+		rmSync(npmrc, { force: true });
+	});
+
+	it("项目名指向当前目录（rootDir === cwd）：直接在原地生成，不打印 cd 提示", async () => {
+		// workspaceRoot 此刻为空目录：prepare 直接通过，无需清空确认
+		nameAnswers.push(".");
+		confirmAnswers.push(false);
+		await start();
+		expectTemplateFiles(workspaceRoot);
+		expect(
+			(
+				JSON.parse(
+					readFileSync(join(workspaceRoot, "package.json"), "utf8"),
+				) as Record<string, unknown>
+			)["name"],
+		).toBe(basename(workspaceRoot));
+		// rootDir 与 cwd 相同 → 稍后启动提示里没有 cd 行
+		expect(logs.join("\n")).not.toContain("cd ");
+		logs.length = 0;
+	});
+
+	it("常规新目录：内置模板 + git init（分支名取 init.defaultBranch）+ 安装并启动", async () => {
+		nameAnswers.push("app-a");
+		confirmAnswers.push(true);
+		installExit = 0;
+		await start();
+		expectTemplateFiles(join(workspaceRoot, "app-a"));
+		expect(
+			(
+				JSON.parse(
+					readFileSync(join(workspaceRoot, "app-a", "package.json"), "utf8"),
+				) as Record<string, unknown>
+			)["name"],
+		).toBe("app-a");
+		// git init 使用 git config 探测到的分支名
+		expect(spawnLog).toContainEqual({
+			cmd: "git",
+			args: ["init", "-b", "trunk"],
+			cwd: join(workspaceRoot, "app-a"),
+		});
+		// install 确认后：agent install → agent run start（bun-first 探测）
+		expect(spawnLog).toContainEqual({
+			cmd: "bun",
+			args: ["install"],
+			cwd: join(workspaceRoot, "app-a"),
+		});
+		expect(spawnLog).toContainEqual({
+			cmd: "bun",
+			args: ["run", "start"],
+			cwd: join(workspaceRoot, "app-a"),
+		});
+		logs.length = 0;
+	});
+
+	it("目标目录非空且用户拒绝清空：直接退出且不改动现有文件", async () => {
+		const dir = join(workspaceRoot, "app-b");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "occupier.txt"), "保留我");
+		nameAnswers.push("app-b");
+		confirmAnswers.push(false);
+		await expect(start()).rejects.toThrow("process.exit(0)");
+		expect(readFileSync(join(dir, "occupier.txt"), "utf8")).toBe("保留我");
+	});
+
+	it("用户确认清空：emptyDir 后重建模板", async () => {
+		const dir = join(workspaceRoot, "app-b");
+		nameAnswers.push("app-b");
+		confirmAnswers.push(true);
+		await start();
+		expect(existsSync(join(dir, "occupier.txt"))).toBe(false);
+		expectTemplateFiles(dir);
+		logs.length = 0;
+	});
+
+	it("项目名问询被取消（空白输入）：直接退出", async () => {
+		nameAnswers.push("   ");
+		await expect(start()).rejects.toThrow("process.exit(0)");
+	});
+
+	it("依赖安装失败：提示后不再尝试启动", async () => {
+		nameAnswers.push("app-f");
+		confirmAnswers.push(true);
+		installExit = 1;
+		spawnLog.length = 0;
+		await start();
+		const commands = spawnLog.map(
+			(call) => `${call.cmd} ${call.args.join(" ")}`,
+		);
+		expect(commands).toContain("bun install");
+		expect(commands).not.toContain("bun run start");
+		expect(logs.join("\n")).toContain("依赖安装失败");
+		logs.length = 0;
+	});
+
+	it("拒绝立即安装：打印后续手动命令（含相对路径 cd 提示）", async () => {
+		nameAnswers.push("sub/app-c");
+		confirmAnswers.push(false);
+		await start();
+		const output = logs.join("\n");
+		expect(output).toContain("cd");
+		expect(output).toContain("bun install");
+		expect(output).toContain("bun run start");
+		expect(existsSync(join(workspaceRoot, "sub", "app-c", "koishi.yml"))).toBe(
+			true,
+		);
+		expect(
+			readdirSync(join(workspaceRoot, "sub", "app-c")).length,
+		).toBeGreaterThan(0);
+	});
+});

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

@@ -0,0 +1,41 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+
+/**
+ * start() 的 --help 分支：打印用法后直接返回（不产生任何写盘）。
+ * argv 在模块顶层解析，故在动态导入前改写 process.argv。
+ */
+
+const logs: string[] = [];
+const originalLog = console.log;
+
+process.argv = [process.argv[0] ?? "bun", "create-koishi-ce", "--help"];
+
+// 以 query 强制独立实例：index.ts 顶层固化 argv / cwd，而 bun test 的
+// 模块注册表跨测试文件共享（不带 query 会拿到既有测试文件已加载的
+// 实例，其 argv / cwd 均为测试进程默认值）。query 须以相对说明符的
+// 形式交给运行时（file URL 形式的 query 不参与缓存键；TS 亦不解析
+// 带 query 的说明符），故经变量动态构造，类型以 typeof import() 收紧
+const specifier = "../index.ts?help";
+const { start } = (await import(specifier)) as typeof import("../index.ts");
+
+beforeAll(() => {
+	console.log = (...args: unknown[]) => {
+		logs.push(args.map((arg) => `${arg}`).join(" "));
+	};
+});
+
+afterAll(() => {
+	console.log = originalLog;
+});
+
+describe("create-koishi-ce --help", () => {
+	it("打印用法说明后即返回", async () => {
+		await start();
+		const output = logs.join("\n");
+		expect(output).toContain("用法：create-koishi-ce [名称] [选项]");
+		expect(output).toContain("--template");
+		expect(output).toContain("--prod");
+		// 帮助分支不应询问项目名（无 "项目名：" 提示输出）
+		expect(output).not.toContain("项目名：");
+	});
+});

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

@@ -0,0 +1,242 @@
+import { afterAll, beforeAll, describe, expect, it, mock } from "bun:test";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { c as tarCreate } from "tar";
+
+/**
+ * start() 远程模板分支（--template）的端到端测试。
+ *
+ * 以 Bun.serve 起本地伪 registry（127.0.0.1 随机端口），按用例切换
+ * 场景（正常 / 元数据 404 / dist-tag 缺失 / tarball 404 / tarball 损坏）；
+ * tarball 由 tar 包真实打包，scaffoldRemote 的下载-解包-改写全链路真实执行。
+ *
+ * 覆盖率口径说明：bun 的覆盖率对同一路径的多个 query 实例只统计最后
+ * 求值的那份，本文件是 koishi-create 全部测试中最后加载的实例，因此
+ * 在此补齐 registry 探测纯函数、emptyDir 与 initGit（--git）等只在其它
+ * 实例出现过的分支，保证 src/index.ts 的行覆盖完整。
+ */
+
+const workspaceRoot = mkdtempSync(join(tmpdir(), "ckc-run-remote-"));
+const previousCwd = process.cwd();
+const previousArgv = process.argv.slice();
+const previousExit = process.exit;
+
+/** 伪 registry 的场景开关 */
+let scenario: "ok" | "meta-404" | "missing-ref" | "tarball-404" | "corrupt" =
+	"ok";
+
+/** 预先打包好的模板 tarball（package/ 前缀目录，strip:1 解包） */
+let tarball: Buffer;
+
+// fetch 回调内引用 registry.port，显式标注返回类型以切断 initializer 的循环推断
+const registry = Bun.serve({
+	port: 0,
+	hostname: "127.0.0.1",
+	// serve 的 fetch 允许同步或异步返回，显式标注以切断 registry 的循环推断
+	fetch: (request): Response | Promise<Response> => {
+		const url = new URL(request.url);
+		if (url.pathname === "/fake-tpl") {
+			if (scenario === "meta-404") {
+				return new Response(null, { status: 404, statusText: "Not Found" });
+			}
+			if (scenario === "missing-ref") {
+				return Response.json({
+					"dist-tags": { latest: "1.0.0" },
+					versions: { "1.0.0": {} },
+				});
+			}
+			return Response.json({
+				"dist-tags": { latest: "1.0.0", beta: "2.0.0" },
+				versions: {
+					"2.0.0": {
+						dist: {
+							tarball: `http://127.0.0.1:${registry.port}/fake-tpl/-/fake-tpl-2.0.0.tgz`,
+						},
+					},
+				},
+			});
+		}
+		if (url.pathname === "/fake-tpl/-/fake-tpl-2.0.0.tgz") {
+			if (scenario === "tarball-404") {
+				return new Response(null, { status: 404, statusText: "Not Found" });
+			}
+			if (scenario === "corrupt") {
+				return new Response("definitely not a tarball", { status: 200 });
+			}
+			return new Response(tarball);
+		}
+		return new Response(null, { status: 404 });
+	},
+});
+
+/** prompts mock：install 的 confirm 默认拒绝，可按用例入队覆盖 */
+const confirmAnswers: boolean[] = [];
+
+mock.module("prompts", () => ({
+	default: async (question: { type?: string }) => {
+		if (question.type === "confirm") {
+			return { yes: confirmAnswers.shift() ?? false };
+		}
+		return { name: "" };
+	},
+}));
+
+// erasableSyntaxOnly 禁用参数属性，改为显式字段声明
+class ExitError extends Error {
+	code: number;
+	constructor(code: number) {
+		super(`process.exit(${code})`);
+		this.code = code;
+	}
+}
+
+process.exit = ((code?: number) => {
+	throw new ExitError(code ?? 0);
+}) as typeof process.exit;
+
+process.argv = [
+	process.argv[0] ?? "bun",
+	"create-koishi-ce",
+	"myapp",
+	"--template",
+	"fake-tpl",
+	"--registry",
+	`http://127.0.0.1:${registry.port}`,
+	"--ref",
+	"beta",
+	// 附带 --git 使 initGit 的 supports / gitConfig 分支也得到执行
+	// （spawnSync 由 run-default 注册的 mock 拦截，无真实子进程）
+	"--git",
+];
+process.chdir(workspaceRoot);
+// query 强制独立实例（说明见 run-help.test.ts）
+const specifier = "../index.ts?remote-run";
+const { start, getLocalRegistry, readNpmrcRegistry } = (await import(
+	specifier
+)) as typeof import("../index.ts");
+process.chdir(previousCwd);
+
+const logs: string[] = [];
+const originalLog = console.log;
+
+beforeAll(async () => {
+	console.log = (...args: unknown[]) => {
+		logs.push(args.map((arg) => `${arg}`).join(" "));
+	};
+	// 造模板载荷并打包：package/package.json + package/index.js
+	const payload = join(workspaceRoot, "payload", "package");
+	mkdirSync(payload, { recursive: true });
+	writeFileSync(
+		join(payload, "package.json"),
+		JSON.stringify({
+			name: "fake-tpl",
+			version: "2.0.0",
+			private: false,
+			workspaces: ["src/*"],
+			scripts: { start: "node index.js" },
+		}),
+	);
+	writeFileSync(join(payload, "index.js"), "console.log('tpl');\n");
+	const tarballPath = join(workspaceRoot, "fake-tpl.tgz");
+	await tarCreate(
+		{ file: tarballPath, cwd: join(workspaceRoot, "payload"), portable: true },
+		["package"],
+	);
+	tarball = readFileSync(tarballPath);
+});
+
+afterAll(() => {
+	console.log = originalLog;
+	process.exit = previousExit;
+	process.argv = previousArgv;
+	void registry.stop(true);
+	rmSync(workspaceRoot, { recursive: true, force: true });
+});
+
+/** 每个场景前移除上一场景的产物，prepare 走「新建目录」分支 */
+function reset(sc: typeof scenario): void {
+	scenario = sc;
+	logs.length = 0;
+	rmSync(join(workspaceRoot, "myapp"), { recursive: true, force: true });
+}
+
+describe("create-koishi-ce 远程模板", () => {
+	it("正常链路：元数据 → tarball → 解包 → package.json 改写", async () => {
+		reset("ok");
+		await start();
+		const dir = join(workspaceRoot, "myapp");
+		expect(existsSync(join(dir, "index.js"))).toBe(true);
+		const manifest = JSON.parse(
+			readFileSync(join(dir, "package.json"), "utf8"),
+		) as Record<string, unknown>;
+		// writePackageJson：替换项目名、标记 private、版本归零；模板其余字段保留
+		expect(manifest["name"]).toBe("myapp");
+		expect(manifest["private"]).toBe(true);
+		expect(manifest["version"]).toBe("0.0.0");
+		expect(manifest["workspaces"]).toEqual(["src/*"]);
+		expect(logs.join("\n")).toContain("使用 registry");
+	});
+
+	it("模板包元数据 404：HttpError 提示后以码 1 退出", async () => {
+		reset("meta-404");
+		await expect(start()).rejects.toThrow("process.exit(1)");
+		expect(logs.join("\n")).toContain("请求失败：HTTP 404");
+	});
+
+	it("dist-tag 引用不存在：以码 1 退出", async () => {
+		reset("missing-ref");
+		await expect(start()).rejects.toThrow("process.exit(1)");
+		expect(logs.join("\n")).toContain("模板 fake-tpl@beta 不存在");
+	});
+
+	it("tarball 下载 404：以码 1 退出", async () => {
+		reset("tarball-404");
+		await expect(start()).rejects.toThrow("process.exit(1)");
+		expect(logs.join("\n")).toContain("请求失败：HTTP 404");
+	});
+
+	it("tarball 内容损坏：解包错误原样抛出（非 HttpError 不吞）", async () => {
+		reset("corrupt");
+		await expect(start()).rejects.toThrow();
+		// 非 HttpError 路径不打印友好提示、不调用 process.exit
+		expect(logs.join("\n")).not.toContain("请求失败");
+	});
+
+	it("非空目录确认清空：emptyDir 后重新解包（覆盖 prepare 清空分支）", async () => {
+		scenario = "ok";
+		logs.length = 0;
+		const dir = join(workspaceRoot, "myapp");
+		rmSync(dir, { recursive: true, force: true });
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "occupier.txt"), "占位");
+		confirmAnswers.push(true);
+		await start();
+		expect(existsSync(join(dir, "occupier.txt"))).toBe(false);
+		expect(existsSync(join(dir, "index.js"))).toBe(true);
+	});
+
+	it("registry 探测纯函数（补本实例的行覆盖）", () => {
+		const npmrc = join(workspaceRoot, ".npmrc");
+		writeFileSync(npmrc, "registry=https://registry.example.com/\n");
+		expect(readNpmrcRegistry(npmrc)).toBe("https://registry.example.com/");
+		expect(
+			readNpmrcRegistry(join(workspaceRoot, "absent.npmrc")),
+		).toBeUndefined();
+		expect(getLocalRegistry(workspaceRoot, workspaceRoot)).toBe(
+			"https://registry.example.com/",
+		);
+		rmSync(npmrc, { force: true });
+		expect(getLocalRegistry(workspaceRoot, workspaceRoot)).toBeUndefined();
+		// 临时目录内容核对后由 afterAll 统一清理
+		expect(readdirSync(workspaceRoot).length).toBeGreaterThan(0);
+	});
+});

package/src/__tests__/template.test.ts

@@ -0,0 +1,57 @@
+import { expect, test } from "bun:test";
+import { renderManifest } from "../index.ts";
+import { baseManifest, templateFiles } from "../template.ts";
+
+test("内置模板依赖纯度：不含任何 @koishijs / koishi-plugin 官方生态包", () => {
+	const { dependencies, devDependencies } = baseManifest();
+	for (const key of Object.keys(dependencies ?? {})) {
+		// koishi 裸名是刻意的 npm alias 占位，其余必须是 @koishi-ce 作用域
+		expect(key === "koishi" || key.startsWith("@koishi-ce/")).toBe(true);
+	}
+	const toolchain = new Set(["bun-types", "cross-env"]);
+	for (const key of Object.keys(devDependencies ?? {})) {
+		expect(key.startsWith("@koishi-ce/") || toolchain.has(key)).toBe(true);
+	}
+});
+
+test("内置模板以 npm alias 钉住 koishi 裸名，版本保持 4.18.x 冻结线", () => {
+	const request = baseManifest().dependencies?.["koishi"];
+	expect(typeof request).toBe("string");
+	// alias 形态 npm:@koishi-ce/koishi-shim@^4.18.x——版本若漂出 ^4 区间，
+	// 上游插件的 peer `koishi ^4` 判定为不满足，market UI 会试图改写它
+	expect(request ?? "").toMatch(/^npm:@koishi-ce\/koishi-shim@\^4\./);
+});
+
+test("内置模板静态文件齐备，koishi.yml 预配 market 镜像源", () => {
+	for (const file of [
+		".env",
+		".gitignore",
+		"koishi.yml",
+		"tsconfig.json",
+		"README.md",
+	]) {
+		expect(templateFiles[file]?.length ?? 0).toBeGreaterThan(0);
+	}
+	expect(templateFiles["koishi.yml"]).toContain(
+		"endpoint: https://registry.koishi.chat/index.json",
+	);
+	// 模板不预装数据库，依赖数据库的插件保持 ~ 禁用
+	expect(templateFiles["koishi.yml"]).toContain("~analytics");
+});
+
+test("renderManifest 渲染内置模板：常规改写生效，prod 模式保留 koishi alias", () => {
+	const output = JSON.parse(renderManifest(baseManifest(), "my-app", false));
+	expect(output.name).toBe("my-app");
+	expect(output.private).toBe(true);
+	expect(output.version).toBe("0.0.0");
+	expect(output.scripts.start).toBe("koishi start");
+	expect(output.dependencies.koishi).toBe(
+		"npm:@koishi-ce/koishi-shim@^4.18.11",
+	);
+
+	const prod = JSON.parse(renderManifest(baseManifest(), "my-app", true));
+	expect("workspaces" in prod).toBe(false);
+	expect("devDependencies" in prod).toBe(false);
+	// koishi alias 是运行时依赖，prod 模式下必须原样保留
+	expect(prod.dependencies.koishi).toBe("npm:@koishi-ce/koishi-shim@^4.18.11");
+});

package/src/index.ts

@@ -3,11 +3,12 @@
  * apps/koishi-create，二者不一致是历史遗留，以目录名为准）。
  *
  * 通过 `bunx create-koishi-ce [name]`（npx 亦可）交互式创建 Koishi 机器人
- * 应用项目：确定项目名 → 准备目标目录 → 从 npm registry 下载模板包（默认
- * @koishijs/boilerplate，刻意沿用上游官方模板以保持与上游插件生态一致）
- * 并解包 → 改写 package.json → 按需初始化 git → 询问是否立即安装依赖并
- * 启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段指向
- * 它）；本文件只承载主流程与可单测的纯函数（范式对齐 @koishi-ce/scripts）。
+ * 应用项目：确定项目名 → 准备目标目录 → 写入内置 @koishi-ce 模板（默认，
+ * 见 src/template.ts；--template <包名> 可改用 npm registry 远程模板，如
+ * 上游官方 @koishijs/boilerplate）→ 按需初始化 git → 询问是否立即安装
+ * 依赖并启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段
+ * 指向它）；本文件只承载主流程与可单测的纯函数（范式对齐
+ * @koishi-ce/scripts）。
  */
 import { spawnSync } from "node:child_process";
 import {
@@ -27,6 +28,7 @@ import prompts from "prompts";
 import { extract } from "tar";
 import parse from "yargs-parser";
 import pkg from "../package.json" with { type: "json" };
+import { baseManifest, templateFiles } from "./template.ts";
 
 const { version } = pkg;
 
@@ -52,7 +54,8 @@ export interface Manifest {
 	private?: boolean;
 	version?: string;
 	workspaces?: unknown;
-	devDependencies?: unknown;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
 	[key: string]: unknown;
 }
 
@@ -250,23 +253,28 @@ function writePackageJson() {
 }
 
 /**
- * 模板下载与解包的主流程：
- * 1. 确定 npm registry（--registry 参数 > 本机 npm 配置 > 官方源）；
- * 2. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
- * 3. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
- *    网络错误统一以 HttpError 提示后退出；
- * 4. 最后改写 package.json。
+ * 写入内置模板（默认路径）：静态文件（src/template.ts 的 templateFiles）
+ * 加上由 baseManifest() 渲染出的 package.json。纯本地写入，无网络请求。
  */
-async function scaffold() {
-	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
+function scaffoldBuiltin() {
+	for (const [file, content] of Object.entries(templateFiles)) {
+		writeFileSync(join(rootDir, file), content);
+	}
+	writeFileSync(
+		join(rootDir, "package.json"),
+		renderManifest(baseManifest(), project, argv.prod === true),
+	);
+}
 
-	const registry = (
-		argv.registry ||
-		getLocalRegistry() ||
-		"https://registry.npmjs.org"
-	).replace(/\/$/, "");
-	console.log(kleur.dim(`  使用 registry：${registry}\n`));
-	const template = argv.template || "@koishijs/boilerplate";
+/**
+ * 远程模板下载与解包（--template 指定时）：
+ * 1. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
+ * 2. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
+ *    网络错误统一以 HttpError 提示后退出；
+ * 3. 最后改写 package.json。
+ */
+async function scaffoldRemote(registry: string) {
+	const template = argv.template as string;
 	const ref = argv.ref || "latest";
 
 	try {
@@ -302,6 +310,27 @@ async function scaffold() {
 	}
 
 	writePackageJson();
+}
+
+/**
+ * 生成项目的主入口：默认写内置 @koishi-ce 模板（scaffoldBuiltin）；
+ * --template <包名> 时改为从 npm registry 下载远程模板（scaffoldRemote），
+ * registry 取值 --registry 参数 > 本机 npm 配置 > 官方源。
+ */
+async function scaffold() {
+	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
+
+	if (argv.template) {
+		const registry = (
+			argv.registry ||
+			getLocalRegistry() ||
+			"https://registry.npmjs.org"
+		).replace(/\/$/, "");
+		console.log(kleur.dim(`  使用 registry：${registry}\n`));
+		await scaffoldRemote(registry);
+	} else {
+		scaffoldBuiltin();
+	}
 
 	console.log(kleur.green("  完成。\n"));
 }
@@ -364,8 +393,8 @@ export async function start() {
   用法：create-koishi-ce [名称] [选项]
 
   选项：
-    -t, --template <名称>   模板包名（默认 @koishijs/boilerplate）
-    -r, --ref <引用>        模板版本引用（默认 latest）
+    -t, --template <名称>   从 npm registry 下载指定模板包（默认使用内置 @koishi-ce 模板）
+    -r, --ref <引用>        远程模板版本引用（默认 latest）
     -f, --forced            强制清空目标目录
     -g, --git               初始化 git 仓库
         --registry <地址>   指定 npm registry（如 https://registry.npmmirror.com）

package/src/template.ts

@@ -0,0 +1,167 @@
+/**
+ * 内置项目模板（create-koishi-ce 的默认模板）。
+ *
+ * 历史包袱修正：本脚手架最初直接下载上游官方 @koishijs/boilerplate 解包
+ * 生成项目，产物依赖全是 npm 官方包（koishi / @koishijs/*），完全绕开了
+ * 本仓的 @koishi-ce 再分发生态（官方 market 还带 Bun 下必炸的 get-registry）。
+ * 默认模板改为内置的纯 @koishi-ce 依赖集；确需上游官方模板时用
+ * --template <包名> 走 npm 远程下载（见 index.ts 的 scaffoldRemote）。
+ *
+ * 模板要点：
+ * - 运行时 Bun：koishi CLI（@koishi-ce/koishi 的 bin）与 loader 插件加载链
+ *   均以 Bun 为准（ESM-only 产物，Bun 原生加载 TS / yml）；
+ * - "koishi" 裸名用 npm alias 钉到 @koishi-ce/koishi-shim（4.18.x 冻结线，
+ *   见 packages/node/koishi-shim）：上游官方 adapter / database 插件与社区
+ *   koishi-plugin-* 的 peer `koishi ^4.x` 由此满足，不会拉入 npm 官方
+ *   koishi 形成第二份框架副本；市场安装亦不改写该声明（installer 的
+ *   isGuardedRequest 护栏将 npm:@koishi-ce alias 与 workspace: 同等保护）；
+ * - 本仓没有 adapter / database 插件的再分发，模板不预装这两类；依赖数据库
+ *   的插件（如 analytics）在 koishi.yml 中保持 ~ 禁用，待用户从市场安装
+ *   数据库插件后再启用；
+ * - 依赖版本统一 ^1.0.0 区间（安装时取最新 1.x），shim 版本例外（冻结线）。
+ */
+import type { Manifest } from "./index.ts";
+
+/** 模板静态文件（相对项目根的路径 → 文件内容），package.json 另行渲染 */
+export const templateFiles: Record<string, string> = {
+	".env": [
+		"GITHUB_MIRROR = https://ghproxy.com/https://github.com",
+		"GITHUB_CONTENT_MIRROR = https://ghproxy.com/https://raw.githubusercontent.com",
+		"GRAVATAR_MIRROR = https://cravatar.cn",
+	].join("\n"),
+	".gitignore": ["node_modules/", "data/"].join("\n"),
+	"koishi.yml": [
+		"plugins:",
+		"  group:server:",
+		"    server:",
+		"      port: 5140",
+		"      maxPort: 5149",
+		"  group:basic:",
+		"    ~admin: {}",
+		"    ~bind: {}",
+		"    commands: {}",
+		"    help: {}",
+		"    http: {}",
+		"    ~inspect: {}",
+		"    locales: {}",
+		"    proxy-agent: {}",
+		"  group:console:",
+		"    actions: {}",
+		"    ~analytics: {}",
+		"    ~auth: {}",
+		"    config: {}",
+		"    console:",
+		"      open: true",
+		"    explorer: {}",
+		"    insight: {}",
+		"    logger: {}",
+		"    market:",
+		"      search:",
+		"        endpoint: https://registry.koishi.chat/index.json",
+		"    notifier: {}",
+		"    oobe: {}",
+		"    sandbox: {}",
+		"    status: {}",
+		"  group:develop:",
+		"    $if: env.NODE_ENV === 'development'",
+		"    hmr:",
+		"      root: .",
+	].join("\n"),
+	"tsconfig.json": [
+		"{",
+		'  "compilerOptions": {',
+		'    "target": "ESNext",',
+		'    "module": "ESNext",',
+		'    "moduleResolution": "bundler",',
+		'    "lib": ["ESNext"],',
+		'    "types": ["bun-types"],',
+		'    "strict": true,',
+		'    "skipLibCheck": true,',
+		'    "noEmit": true,',
+		'    "allowImportingTsExtensions": true,',
+		'    "verbatimModuleSyntax": true,',
+		'    "erasableSyntaxOnly": true',
+		"  },",
+		'  "include": ["plugins/*/src", "external/*/src"]',
+		"}",
+	].join("\n"),
+	"README.md": `# Koishi 机器人项目
+
+由 \`bun create koishi-ce\` 生成，运行于 [@koishi-ce 社区再分发版](https://github.com/Koishi-CE/koishi) 生态。
+
+## 环境要求
+
+- [Bun](https://bun.sh) ≥ 1.2（运行时：koishi CLI 与插件加载链以 Bun 为准）
+
+## 快速开始
+
+\`\`\`bash
+bun install
+bun run start        # 启动（生产模式）
+bun run dev          # 启动（开发模式，启用 HMR 热更新）
+\`\`\`
+
+启动后访问控制台：<http://127.0.0.1:5140>
+
+## 安装插件
+
+推荐在控制台「插件市场」页安装（已预配 registry.koishi.chat 镜像源）；也可以手动 \`bun add <包名>\` 后在 \`koishi.yml\` 中启用。
+
+上游官方 adapter（如 adapter-discord / adapter-telegram）、数据库插件（如 database-sqlite）与社区 koishi-plugin-* 插件均可直接安装：根依赖中的 \`"koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"\` 已把上游生态对 \`koishi\` 的依赖钉回 @koishi-ce 框架（**请勿删除或改写该行**），不会形成第二份框架副本。analytics 等依赖数据库的插件请先安装数据库插件，再去掉配置中对应的 \`~\` 前缀启用。
+
+## 自定义插件
+
+在 \`plugins/\` 目录下创建插件包（可用 \`bun run new <名称>\` 生成骨架），在 \`koishi.yml\` 中以相对路径引用（如 \`./plugins/my-plugin\`）即可启用；Bun 直接加载 TypeScript 源码，无需预编译。
+`,
+};
+
+/**
+ * 内置模板的 package.json 基础内容（name/version 会被 renderManifest 覆写，
+ * prod 模式下 workspaces 与 devDependencies 会被移除）。
+ */
+export function baseManifest(): Manifest {
+	return {
+		type: "module",
+		workspaces: ["plugins/*", "external/*"],
+		scripts: {
+			start: "koishi start",
+			dev: "cross-env NODE_ENV=development koishi start",
+			new: "koishi-scripts setup",
+		},
+		dependencies: {
+			"@koishi-ce/koishi": "^1.0.0",
+			"@koishi-ce/plugin-actions": "^1.0.0",
+			"@koishi-ce/plugin-admin": "^1.0.0",
+			"@koishi-ce/plugin-analytics": "^1.0.0",
+			"@koishi-ce/plugin-auth": "^1.0.0",
+			"@koishi-ce/plugin-bind": "^1.0.0",
+			"@koishi-ce/plugin-commands": "^1.0.0",
+			"@koishi-ce/plugin-config": "^1.0.0",
+			"@koishi-ce/plugin-console": "^1.0.0",
+			"@koishi-ce/plugin-explorer": "^1.0.0",
+			"@koishi-ce/plugin-help": "^1.0.0",
+			"@koishi-ce/plugin-http": "^1.0.0",
+			"@koishi-ce/plugin-insight": "^1.0.0",
+			"@koishi-ce/plugin-inspect": "^1.0.0",
+			"@koishi-ce/plugin-locales": "^1.0.0",
+			"@koishi-ce/plugin-logger": "^1.0.0",
+			"@koishi-ce/plugin-market": "^1.0.0",
+			"@koishi-ce/plugin-notifier": "^1.0.0",
+			"@koishi-ce/plugin-oobe": "^1.0.0",
+			"@koishi-ce/plugin-proxy-agent": "^1.0.0",
+			"@koishi-ce/plugin-sandbox": "^1.0.0",
+			"@koishi-ce/plugin-server": "^1.0.0",
+			"@koishi-ce/plugin-status": "^1.0.0",
+			// 上游裸名占位：npm alias 钉到 @koishi-ce 的 koishi shim（勿删，
+			// 语义见文件头注释）；版本必须保持 4.18.x 冻结线以满足 ^4 peer
+			koishi: "npm:@koishi-ce/koishi-shim@^4.18.11",
+		},
+		devDependencies: {
+			"@koishi-ce/client": "^1.0.0",
+			"@koishi-ce/plugin-hmr": "^1.0.0",
+			"@koishi-ce/scripts": "^1.0.0",
+			"bun-types": "^1.4.0",
+			"cross-env": "^7.0.3",
+		},
+	};
+}