create-koishi-ce 1.7.0 → 1.9.0

package/README.md

@@ -29,7 +29,7 @@ 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、database-sqlite 等），并预置六行 npm alias 钉住上游名——`koishi` / `@koishijs/core` / `@koishijs/loader` 指向 `@koishi-ce/koishi-shim`、`@koishijs/plugin-console` 指向 `@koishi-ce/console-shim`、`@koishijs/client` / `@koishijs/components` 分别指向 `@koishi-ce/client-shim` / `@koishi-ce/components-shim`，社区插件（含把上游前端库写进 dependencies 的 webui 插件）由此全部解析到 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/ 下继续创建插件项目）。
+- **开发工具链**：devDependencies 预置 `@koishi-ce/client`、`@koishi-ce/console-app`（宿主 SPA 源码，devMode 的 vite root）、`@koishi-ce/console-builder`（控制台 devMode 的 Vite 开发服务器）、`@koishi-ce/plugin-hmr` 与 `@koishi-ce/scripts`（`koishi-scripts setup` 可在 external/ 下继续创建插件项目）。
 
 不预装任何 adapter——官方 adapter 可后续从市场安装，peer 已被 alias 钉住不会形成双实例；数据库已由默认启用的 `database-sqlite` 覆盖，其他官方 database 同样可从市场安装。
 
@@ -68,7 +68,7 @@ Interactive flow: project name; confirm cleaning a non-empty target directory; c
 
 - **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/).
+- **Toolchain** — devDependencies include `@koishi-ce/client`, `@koishi-ce/console-app` (the host SPA source serving as the devMode vite root), `@koishi-ce/console-builder` (the Vite dev server behind the console devMode), `@koishi-ce/plugin-hmr` and `@koishi-ce/scripts` (`koishi-scripts setup` scaffolds further plugin projects under external/).
 
 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.
 

package/lib/bin.mjs

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

package/lib/index.d.ts

@@ -16,6 +16,7 @@ interface Manifest {
   workspaces?: unknown;
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
+  overrides?: Record<string, string>;
   [key: string]: unknown;
 }
 /**

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-Cj4uFpkr.mjs";
+import { a as renderManifest, i as readNpmrcRegistry, n as detectAgent, r as getLocalRegistry, t as start } from "./src-rD4foyof.mjs";
 export { detectAgent, getLocalRegistry, readNpmrcRegistry, renderManifest, start };

package/lib/{src-Cj4uFpkr.mjs → src-rD4foyof.mjs}

@@ -1,15 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { getLocalRegistry, readNpmrcRegistry } from "@koishi-ce/utils";
-import { downloadTemplate } from "giget";
+import { tmpdir } from "node:os";
 //#region package.json
 var package_default = {
 	name: "create-koishi-ce",
 	description: "Setup a Koishi application",
-	version: "1.7.0",
+	version: "1.9.0",
 	type: "module",
 	main: "./lib/index.mjs",
 	module: "./lib/index.mjs",
@@ -41,8 +41,7 @@ var package_default = {
 	dependencies: {
 		"@clack/prompts": "^1.7.0",
 		"@koishi-ce/utils": "workspace:*",
-		"picocolors": "^1.1.1",
-		"giget": "^3.3.1"
+		"picocolors": "^1.1.1"
 	},
 	exports: {
 		".": {
@@ -75,7 +74,7 @@ function renderManifest(source, project, prod) {
 //#region src/remote.ts
 /**
 * 远程模板分支（--template <包名>）的下载-解包-改写全流程：拉取 npm
-* registry 包元数据解析目标版本，经 giget 下载 tarball 并解包到目标
+* registry 包元数据解析目标版本，经 Bun.Archive 下载 tarball 并解包到目标
 * 目录，最后改写 package.json。HttpError 与 RegistryMeta 只在本流程
 * 消费，就近定义不另立文件；本机 registry 配置探测见 registry.ts。
 *
@@ -97,9 +96,8 @@ var HttpError = class extends Error {
 /**
 * 远程模板下载与解包：
 * 1. 拉取模板包元数据，按 dist-tags 解析目标版本（ref，默认 latest）；
-* 2. 下载 tarball 并解包到目标目录（解包走 giget，其按 npm tarball 惯例
-*    剥离顶层 package/ 目录，等价于 strip: 1），网络错误统一以 HttpError
-*    提示后退出；
+* 2. 下载 tarball 并解包到目标目录（Bun.Archive 负责 tar/gzip 解包，按 npm
+*    tarball 惯例剥离顶层 package/ 目录），网络错误统一以 HttpError 提示后退出；
 * 3. 最后改写 package.json。
 */
 async function scaffoldRemote({ registry, template, ref, prod, project, rootDir }) {
@@ -111,19 +109,21 @@ async function scaffoldRemote({ registry, template, ref, prod, project, rootDir
 		if (version === void 0) throw new HttpError(404, `模板 ${template}@${ref} 不存在`);
 		const url = remote.versions[version]?.dist?.tarball;
 		if (url === void 0) throw new HttpError(404, `模板 ${template}@${ref} 不存在`);
-		await downloadTemplate(template, {
-			provider: "npm",
-			providers: { npm: async () => ({
-				name: template,
-				version,
-				tar: async () => {
-					const tarballRes = await fetch(url);
-					if (!tarballRes.ok || !tarballRes.body) throw new HttpError(tarballRes.status, tarballRes.statusText);
-					return tarballRes.body;
-				}
-			}) },
-			dir: rootDir
-		});
+		const tarballRes = await fetch(url);
+		if (!tarballRes.ok || !tarballRes.body) throw new HttpError(tarballRes.status, tarballRes.statusText);
+		const archive = new Bun.Archive(await tarballRes.blob());
+		const tempDir = mkdtempSync(join(tmpdir(), "create-koishi-ce-"));
+		try {
+			await archive.extract(tempDir);
+			const packageDir = join(tempDir, "package");
+			if (!existsSync(packageDir)) throw new Error("远程模板归档缺少 package/ 目录");
+			for (const entry of readdirSync(packageDir)) renameSync(join(packageDir, entry), join(rootDir, entry));
+		} finally {
+			rmSync(tempDir, {
+				recursive: true,
+				force: true
+			});
+		}
 	} catch (err) {
 		if (!(err instanceof HttpError)) throw err;
 		console.log(`${pc.red("error")} 请求失败：HTTP ${err.status} ${err.statusText}`);
@@ -197,6 +197,74 @@ const dotFiles = {
 /** 模板静态文件（相对项目根的路径 → 文件内容），package.json 另行渲染 */
 const templateFiles = Object.fromEntries(readdirSync(templateDir).filter((file) => !file.startsWith(".")).map((file) => [dotFiles[file] ?? file, readFileSync(join(templateDir, file), "utf8")]));
 /**
+* 上游名 → CE 对应包的 overrides 兜底映射（值统一 npm:<目标>@^1.0.0，
+* 经 buildUpstreamOverrides 包装）。
+*
+* 六行钉名依赖「落盘版本满足声明范围」：第三方插件的声明超出冻结线
+* （如未来上游升线后的 ^6）或引用清单外的上游名（如 dependencies 直接
+* 依赖 @koishijs/plugin-admin / @koishijs/utils）时，官方包仍会落盘。
+* overrides 是包管理器级的强制重写——不看版本满足性，把整棵依赖树中对
+* 这些上游名的解析一律改指 CE 对应包，与钉名构成双层防线（napuketto
+* 事件 2026-09-19 后补）。
+*
+* 清单 = CE 已再分发且官方同名的包，2026-09-19 逐一 npm view 核实：
+* - plugin-cron 不在列（上游是裸名社区包 koishi-plugin-cron，非 @koishijs
+*   作用域）；
+* - plugin-welcome / plugin-theme-vanilla 不在列（CE 原创，上游无此名）；
+* - plugin-assets 的 CE 对应物是 @koishi-ce/assets（无 plugin 前缀）。
+* 新增 CE 再分发包时须同步本表与 sandbox 生成器的同款清单
+* （tooling/sandbox/manifest.ts，对账测试防漂移）。
+*/
+const UPSTREAM_OVERRIDES = {
+	koishi: "@koishi-ce/koishi",
+	"@koishijs/core": "@koishi-ce/koishi",
+	"@koishijs/loader": "@koishi-ce/koishi",
+	"@koishijs/utils": "@koishi-ce/utils",
+	"@koishijs/i18n-utils": "@koishi-ce/i18n-utils",
+	"@koishijs/client": "@koishi-ce/client",
+	"@koishijs/components": "@koishi-ce/components",
+	"@koishijs/console": "@koishi-ce/console",
+	"@koishijs/registry": "@koishi-ce/registry",
+	"@koishijs/plugin-console": "@koishi-ce/plugin-console",
+	"@koishijs/plugin-assets": "@koishi-ce/assets"
+};
+for (const name of [
+	"actions",
+	"admin",
+	"analytics",
+	"assets-local",
+	"auth",
+	"bind",
+	"broadcast",
+	"callme",
+	"commands",
+	"config",
+	"database-sqlite",
+	"dataview",
+	"echo",
+	"explorer",
+	"help",
+	"hmr",
+	"insight",
+	"inspect",
+	"locales",
+	"logger",
+	"market",
+	"mock",
+	"notifier",
+	"oobe",
+	"proxy-agent",
+	"rate-limit",
+	"sandbox",
+	"server",
+	"server-temp",
+	"status"
+]) UPSTREAM_OVERRIDES[`@koishijs/plugin-${name}`] = `@koishi-ce/plugin-${name}`;
+/** 生成模板 overrides 块：键为上游名，值统一 npm:<CE 包>@^1.0.0。 */
+function buildUpstreamOverrides() {
+	return Object.fromEntries(Object.entries(UPSTREAM_OVERRIDES).map(([name, target]) => [name, `npm:${target}@^1.0.0`]));
+}
+/**
 * 内置模板的 package.json 基础内容（name/version 会被 renderManifest 覆写，
 * prod 模式下 workspaces 与 devDependencies 会被移除）。
 */
@@ -261,12 +329,15 @@ function baseManifest() {
 			"@koishijs/client": "npm:@koishi-ce/client-shim@^5.30.11",
 			"@koishijs/components": "npm:@koishi-ce/components-shim@^1.5.22"
 		},
+		overrides: buildUpstreamOverrides(),
 		devDependencies: {
 			"@koishi-ce/client": "^1.0.0",
+			"@koishi-ce/console-app": "^1.0.0",
+			"@koishi-ce/console-builder": "^1.0.0",
 			"@koishi-ce/plugin-hmr": "^1.0.0",
 			"@koishi-ce/plugin-mock": "^1.0.0",
 			"@koishi-ce/scripts": "^1.0.0",
-			"bun-types": "^1.4.0"
+			"@types/bun": "^1.4.0"
 		}
 	};
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "create-koishi-ce",
     "description": "Setup a Koishi application",
-    "version": "1.7.0",
+    "version": "1.9.0",
     "type": "module",
     "main": "./lib/index.mjs",
     "module": "./lib/index.mjs",
@@ -45,8 +45,7 @@
     "dependencies": {
         "@clack/prompts": "^1.7.0",
         "@koishi-ce/utils": "^1.1.0",
-        "picocolors": "^1.1.1",
-        "giget": "^3.3.1"
+        "picocolors": "^1.1.1"
     },
     "exports": {
         ".": {

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

@@ -18,7 +18,7 @@ import {
 	rmSync,
 	writeFileSync,
 } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { tarPack } from "./tar-pack.ts";
 
@@ -29,7 +29,7 @@ import { tarPack } from "./tar-pack.ts";
  * 场景（正常 / 元数据 404 / dist-tag 缺失 / tarball 404 / tarball 损坏）；
  * tarball 由 __tests__/tar-pack.ts 的 tarPack 打包（ustar + gzip，与真实
  * npm tarball 同构），scaffoldRemote 的下载-解包-改写全链路真实执行
- * （解包走 giget，含超长名 pax 条目的端到端验证）。
+ * （解包走 Bun.Archive，含超长名 pax 条目的端到端验证）。
  *
  * 覆盖率口径说明：bun 的覆盖率对同一路径的多个 query 实例只统计最后
  * 求值的那份，本文件是 koishi-create 全部测试中最后加载的实例，因此
@@ -180,7 +180,7 @@ beforeAll(async () => {
 		},
 		{
 			// 124 字符 > ustar 的 100 字节 name 上限：tarPack 前置 pax
-			// 扩展头，giget（tar 库）经 pax 还原后同样能正确落盘
+			// 扩展头，Bun.Archive 经 pax 还原后同样能正确落盘
 			path: `package/${longName}.txt`,
 			data: encoder.encode("pax"),
 		},
@@ -203,19 +203,6 @@ function reset(sc: typeof scenario): void {
 		recursive: true,
 		force: true,
 	});
-	// giget 缓存位置随平台而异（win32 为 tmpdir()/giget，POSIX 跟随
-	// XDG_CACHE_HOME——默认 ~/.cache）；逐用例清理，避免上一场景的缓存
-	// （tarball-404 的缺失或 corrupt 的损坏归档）被 giget 的
-	// 「下载失败回退缓存」吞掉
-	const cacheRoot =
-		process.env["XDG_CACHE_HOME"] ??
-		join(homedir(), ".cache");
-	for (const dir of [
-		join(tmpdir(), "giget"),
-		join(cacheRoot, "giget"),
-	]) {
-		rmSync(dir, { recursive: true, force: true });
-	}
 }
 
 describe("create-koishi-ce 远程模板", () => {
@@ -224,7 +211,7 @@ describe("create-koishi-ce 远程模板", () => {
 		await start();
 		const dir = join(workspaceRoot, "myapp");
 		expect(existsSync(join(dir, "index.js"))).toBe(true);
-		// 超长名文件经 pax 扩展头正常落盘（tarPack 打包 → giget 解包全链路）
+		// 超长名文件经 pax 扩展头正常落盘（tarPack 打包 → Bun.Archive 解包全链路）
 		expect(
 			readFileSync(join(dir, `${longName}.txt`), "utf8"),
 		).toBe("pax");

package/src/__tests__/tar-pack.ts

@@ -4,10 +4,10 @@
 /**
  * 测试专用 .tgz fixture 构造器（ustar + 超长名 pax 兜底 + gzip）。
  *
- * 生产代码的远程模板解包已改走 giget（见 src/index.ts scaffoldRemote），
+ * 生产代码的远程模板解包已改走 Bun.Archive（见 src/index.ts scaffoldRemote），
  * 这里只保留「打包」一侧供测试构造伪 registry 的 tarball 响应。tar
  * 归档格式稳定，此工具不随业务演进，故不再单独维护解析逻辑与单测
- * ——其正确性由 __tests__/run-remote.test.ts 的「打包 → giget 解包」
+ * ——其正确性由 __tests__/run-remote.test.ts 的「打包 → Bun.Archive 解包」
  * 端到端链路间接验证。
  */
 

package/src/__tests__/template.test.ts

@@ -5,6 +5,7 @@ import { expect, test } from "bun:test";
 import { renderManifest } from "../index.ts";
 import {
 	baseManifest,
+	buildUpstreamOverrides,
 	templateFiles,
 } from "../template.ts";
 
@@ -28,7 +29,7 @@ test("内置模板依赖纯度：不含任何 @koishijs / koishi-plugin 官方
 	}
 	for (const key of Object.keys(devDependencies ?? {})) {
 		expect(
-			key === "bun-types" || key.startsWith("@koishi-ce/"),
+			key === "@types/bun" || key.startsWith("@koishi-ce/"),
 		).toBe(true);
 	}
 });
@@ -178,13 +179,14 @@ test("koishi.yml 预写策略：sqlite 默认启用开箱数据库，非必需
 		expect(yml).toContain(name);
 	}
 	expect(yml).not.toContain("database-mongo");
-	// 模板依赖里不得出现官方 adapter / database 包名（只预写不预装）
-	expect(JSON.stringify(baseManifest())).not.toContain(
-		"adapter-",
-	);
-	expect(JSON.stringify(baseManifest())).not.toContain(
-		"@koishijs/plugin-database-",
-	);
+	// 模板依赖里不得出现官方 adapter / database 包名（只预写不预装）。
+	// 断言只扫 dependencies——overrides 的键含官方名是重写所需，属预期
+	expect(
+		JSON.stringify(baseManifest().dependencies),
+	).not.toContain("adapter-");
+	expect(
+		JSON.stringify(baseManifest().dependencies),
+	).not.toContain("@koishijs/plugin-database-");
 });
 
 test("koishi.yml 预写条目与模板依赖对账：CE 插件必须在册，官方 adapter 只预写不预装", () => {
@@ -264,3 +266,65 @@ test("renderManifest 渲染内置模板：常规改写生效，prod 模式保留
 		"npm:@koishi-ce/koishi-shim@^4.18.11",
 	);
 });
+
+test("内置模板 overrides 兜底层：41 个上游名强制重定向 CE 包", () => {
+	const table = baseManifest().overrides ?? {};
+	expect(Object.keys(table)).toHaveLength(41);
+	const keys = Object.keys(table);
+	// 核心九名（钉名六行之外由 overrides 补齐覆盖面）
+	expect(table["koishi"]).toBe(
+		"npm:@koishi-ce/koishi@^1.0.0",
+	);
+	expect(table["@koishijs/core"]).toBe(
+		"npm:@koishi-ce/koishi@^1.0.0",
+	);
+	expect(table["@koishijs/loader"]).toBe(
+		"npm:@koishi-ce/koishi@^1.0.0",
+	);
+	expect(table["@koishijs/utils"]).toBe(
+		"npm:@koishi-ce/utils@^1.0.0",
+	);
+	expect(table["@koishijs/i18n-utils"]).toBe(
+		"npm:@koishi-ce/i18n-utils@^1.0.0",
+	);
+	expect(table["@koishijs/client"]).toBe(
+		"npm:@koishi-ce/client@^1.0.0",
+	);
+	expect(table["@koishijs/components"]).toBe(
+		"npm:@koishi-ce/components@^1.0.0",
+	);
+	expect(table["@koishijs/console"]).toBe(
+		"npm:@koishi-ce/console@^1.0.0",
+	);
+	expect(table["@koishijs/registry"]).toBe(
+		"npm:@koishi-ce/registry@^1.0.0",
+	);
+	// CE 原创与上游裸名社区对应物不进清单（不拦官方生态的真实依赖）
+	expect(keys.includes("@koishijs/plugin-welcome")).toBe(
+		false,
+	);
+	expect(
+		keys.includes("@koishijs/plugin-theme-vanilla"),
+	).toBe(false);
+	expect(keys.includes("@koishijs/plugin-cron")).toBe(
+		false,
+	);
+	// plugin-assets 的 CE 对应物无 plugin 前缀
+	expect(table["@koishijs/plugin-assets"]).toBe(
+		"npm:@koishi-ce/assets@^1.0.0",
+	);
+	// 全部值为 npm:@koishi-ce/ 前缀，键全为 @koishijs/ 上游名或 koishi 裸名
+	for (const key of keys) {
+		expect(
+			key === "koishi" || key.startsWith("@koishijs/"),
+		).toBe(true);
+		expect(table[key]).toMatch(/^npm:@koishi-ce\//);
+	}
+	// buildUpstreamOverrides 与 baseManifest().overrides 同源
+	expect(buildUpstreamOverrides()).toEqual(table);
+	// renderManifest 全程透传 overrides（prod 模式也不删）
+	const prod = JSON.parse(
+		renderManifest(baseManifest(), "my-app", true),
+	);
+	expect(prod.overrides).toEqual(table);
+});

package/src/manifest.ts

@@ -18,6 +18,7 @@ export interface Manifest {
 	workspaces?: unknown;
 	dependencies?: Record<string, string>;
 	devDependencies?: Record<string, string>;
+	overrides?: Record<string, string>;
 	[key: string]: unknown;
 }
 

package/src/remote.ts

@@ -3,7 +3,7 @@
 
 /**
  * 远程模板分支（--template <包名>）的下载-解包-改写全流程：拉取 npm
- * registry 包元数据解析目标版本，经 giget 下载 tarball 并解包到目标
+ * registry 包元数据解析目标版本，经 Bun.Archive 下载 tarball 并解包到目标
  * 目录，最后改写 package.json。HttpError 与 RegistryMeta 只在本流程
  * 消费，就近定义不另立文件；本机 registry 配置探测见 registry.ts。
  *
@@ -12,9 +12,17 @@
  * 经 RemoteOptions 显式传入，由 index.ts 的 scaffold 组装，避免子模块
  * 与顶层状态的隐式耦合。
  */
-import { readFileSync, writeFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { downloadTemplate } from "giget";
 import pc from "picocolors";
 import {
 	type Manifest,
@@ -57,9 +65,8 @@ interface RemoteOptions {
 /**
  * 远程模板下载与解包：
  * 1. 拉取模板包元数据，按 dist-tags 解析目标版本（ref，默认 latest）；
- * 2. 下载 tarball 并解包到目标目录（解包走 giget，其按 npm tarball 惯例
- *    剥离顶层 package/ 目录，等价于 strip: 1），网络错误统一以 HttpError
- *    提示后退出；
+ * 2. 下载 tarball 并解包到目标目录（Bun.Archive 负责 tar/gzip 解包，按 npm
+ *    tarball 惯例剥离顶层 package/ 目录），网络错误统一以 HttpError 提示后退出；
  * 3. 最后改写 package.json。
  */
 export async function scaffoldRemote({
@@ -93,30 +100,34 @@ export async function scaffoldRemote({
 			);
 		}
 
-		// 解包交给 giget：provider 的 tar 字段是函数，giget 需要时才发起
-		// 下载（HttpError 在下载阶段抛出，不经 giget 包装可直接识别）；
-		// giget 先把 tarball 落入本地缓存再解压到 rootDir，解压失败
-		// （gzip 损坏 / 归档截断）走下方非 HttpError 分支原样上抛。
-		await downloadTemplate(template, {
-			provider: "npm",
-			providers: {
-				npm: async () => ({
-					name: template,
-					version,
-					tar: async () => {
-						const tarballRes = await fetch(url);
-						if (!tarballRes.ok || !tarballRes.body) {
-							throw new HttpError(
-								tarballRes.status,
-								tarballRes.statusText,
-							);
-						}
-						return tarballRes.body;
-					},
-				}),
-			},
-			dir: rootDir,
-		});
+		const tarballRes = await fetch(url);
+		if (!tarballRes.ok || !tarballRes.body) {
+			throw new HttpError(
+				tarballRes.status,
+				tarballRes.statusText,
+			);
+		}
+		const archive = new Bun.Archive(
+			await tarballRes.blob(),
+		);
+		const tempDir = mkdtempSync(
+			join(tmpdir(), "create-koishi-ce-"),
+		);
+		try {
+			await archive.extract(tempDir);
+			const packageDir = join(tempDir, "package");
+			if (!existsSync(packageDir)) {
+				throw new Error("远程模板归档缺少 package/ 目录");
+			}
+			for (const entry of readdirSync(packageDir)) {
+				renameSync(
+					join(packageDir, entry),
+					join(rootDir, entry),
+				);
+			}
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
 	} catch (err) {
 		if (!(err instanceof HttpError)) throw err;
 		console.log(

package/src/template/tsconfig.json

@@ -1,16 +1,23 @@
 {
-  "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"]
-}
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": [
+            "ESNext"
+        ],
+        "types": [
+            "bun"
+        ],
+        "strict": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "erasableSyntaxOnly": true
+    },
+    "include": [
+        "plugins/*/src",
+        "external/*/src"
+    ]
+}

package/src/template.ts

@@ -85,6 +85,88 @@ export const templateFiles: Record<string, string> =
 			]),
 	);
 
+/**
+ * 上游名 → CE 对应包的 overrides 兜底映射（值统一 npm:<目标>@^1.0.0，
+ * 经 buildUpstreamOverrides 包装）。
+ *
+ * 六行钉名依赖「落盘版本满足声明范围」：第三方插件的声明超出冻结线
+ * （如未来上游升线后的 ^6）或引用清单外的上游名（如 dependencies 直接
+ * 依赖 @koishijs/plugin-admin / @koishijs/utils）时，官方包仍会落盘。
+ * overrides 是包管理器级的强制重写——不看版本满足性，把整棵依赖树中对
+ * 这些上游名的解析一律改指 CE 对应包，与钉名构成双层防线（napuketto
+ * 事件 2026-09-19 后补）。
+ *
+ * 清单 = CE 已再分发且官方同名的包，2026-09-19 逐一 npm view 核实：
+ * - plugin-cron 不在列（上游是裸名社区包 koishi-plugin-cron，非 @koishijs
+ *   作用域）；
+ * - plugin-welcome / plugin-theme-vanilla 不在列（CE 原创，上游无此名）；
+ * - plugin-assets 的 CE 对应物是 @koishi-ce/assets（无 plugin 前缀）。
+ * 新增 CE 再分发包时须同步本表与 sandbox 生成器的同款清单
+ * （tooling/sandbox/manifest.ts，对账测试防漂移）。
+ */
+const UPSTREAM_OVERRIDES: Record<string, string> = {
+	koishi: "@koishi-ce/koishi",
+	"@koishijs/core": "@koishi-ce/koishi",
+	"@koishijs/loader": "@koishi-ce/koishi",
+	"@koishijs/utils": "@koishi-ce/utils",
+	"@koishijs/i18n-utils": "@koishi-ce/i18n-utils",
+	"@koishijs/client": "@koishi-ce/client",
+	"@koishijs/components": "@koishi-ce/components",
+	"@koishijs/console": "@koishi-ce/console",
+	"@koishijs/registry": "@koishi-ce/registry",
+	"@koishijs/plugin-console": "@koishi-ce/plugin-console",
+	"@koishijs/plugin-assets": "@koishi-ce/assets",
+};
+
+// CE 与上游同名再分发的 plugin-*：机械一一对应
+for (const name of [
+	"actions",
+	"admin",
+	"analytics",
+	"assets-local",
+	"auth",
+	"bind",
+	"broadcast",
+	"callme",
+	"commands",
+	"config",
+	"database-sqlite",
+	"dataview",
+	"echo",
+	"explorer",
+	"help",
+	"hmr",
+	"insight",
+	"inspect",
+	"locales",
+	"logger",
+	"market",
+	"mock",
+	"notifier",
+	"oobe",
+	"proxy-agent",
+	"rate-limit",
+	"sandbox",
+	"server",
+	"server-temp",
+	"status",
+]) {
+	UPSTREAM_OVERRIDES[`@koishijs/plugin-${name}`] =
+		`@koishi-ce/plugin-${name}`;
+}
+
+/** 生成模板 overrides 块：键为上游名，值统一 npm:<CE 包>@^1.0.0。 */
+export function buildUpstreamOverrides(): Record<
+	string,
+	string
+> {
+	return Object.fromEntries(
+		Object.entries(UPSTREAM_OVERRIDES).map(
+			([name, target]) => [name, `npm:${target}@^1.0.0`],
+		),
+	);
+}
+
 /**
  * 内置模板的 package.json 基础内容（name/version 会被 renderManifest 覆写，
  * prod 模式下 workspaces 与 devDependencies 会被移除）。
@@ -187,12 +269,17 @@ export function baseManifest(): Manifest {
 			"@koishijs/components":
 				"npm:@koishi-ce/components-shim@^1.5.22",
 		},
+		// overrides 兜底层（语义见 UPSTREAM_OVERRIDES 注释）：不看版本
+		// 满足性强制重写整棵依赖树，拦住钉名覆盖面之外的上游声明
+		overrides: buildUpstreamOverrides(),
 		devDependencies: {
 			"@koishi-ce/client": "^1.0.0",
+			"@koishi-ce/console-app": "^1.0.0",
+			"@koishi-ce/console-builder": "^1.0.0",
 			"@koishi-ce/plugin-hmr": "^1.0.0",
 			"@koishi-ce/plugin-mock": "^1.0.0",
 			"@koishi-ce/scripts": "^1.0.0",
-			"bun-types": "^1.4.0",
+			"@types/bun": "^1.4.0",
 		},
 	};
 }