create-koishi-ce 1.6.4 → 1.8.0

package/README.md

@@ -27,7 +27,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`，社区插件由此全部解析到 CE 框架；
+- **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/ 下继续创建插件项目）。
 

package/lib/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { t as start } from "./src-D2Fw0uXq.mjs";
+import { t as start } from "./src-D36TrO6G.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-D2Fw0uXq.mjs";
+import { a as renderManifest, i as readNpmrcRegistry, n as detectAgent, r as getLocalRegistry, t as start } from "./src-D36TrO6G.mjs";
 export { detectAgent, getLocalRegistry, readNpmrcRegistry, renderManifest, start };

package/lib/{src-D2Fw0uXq.mjs → src-D36TrO6G.mjs}

@@ -9,7 +9,7 @@ import { downloadTemplate } from "giget";
 var package_default = {
 	name: "create-koishi-ce",
 	description: "Setup a Koishi application",
-	version: "1.6.4",
+	version: "1.8.0",
 	type: "module",
 	main: "./lib/index.mjs",
 	module: "./lib/index.mjs",
@@ -157,10 +157,12 @@ function writePackageJson(rootDir, project, prod) {
 *   均以 Bun 为准（ESM-only 产物，Bun 原生加载 TS / yml）；脚本里的环境
 *   变量注入直接写 `NODE_ENV=... ` 前缀——bun run 走 Bun Shell，跨平台
 *   原生支持，无需 cross-env 一类的依赖；
-* - "koishi" 裸名与 @koishijs/core / @koishijs/loader / @koishijs/plugin-console
-*   上游名用 npm alias 钉到 @koishi-ce shim（版本冻结线，见 packages/shim）：
-*   上游官方 adapter / database 插件与社区 koishi-plugin-* 的 peer 由此满足，
-*   不会拉入 npm 官方全家桶形成第二份框架副本；市场安装亦不改写该声明
+* - "koishi" 裸名与 @koishijs/core / @koishijs/loader / @koishijs/plugin-console /
+*   @koishijs/client / @koishijs/components 上游名用 npm alias 钉到 @koishi-ce
+*   shim（版本冻结线，见 packages/shim）：上游官方 adapter / database 插件与
+*   社区 koishi-plugin-* 的 peer 由此满足，webui 插件写进 dependencies 的
+*   client / components 亦被钉住（满足性判定看落盘版本），不会拉入 npm
+*   官方全家桶形成第二份框架副本；市场安装亦不改写该声明
 *   （installer 的 isGuardedRequest 护栏将 npm:@koishi-ce alias 与
 *   workspace: 同等保护）；
 * - koishi.yml 采用配置页导出形态：插件键带 uid 实例后缀，分组带中文
@@ -195,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 会被移除）。
 */
@@ -255,8 +325,11 @@ function baseManifest() {
 			koishi: "npm:@koishi-ce/koishi-shim@^4.18.11",
 			"@koishijs/plugin-console": "npm:@koishi-ce/console-shim@^5.30.11",
 			"@koishijs/core": "npm:@koishi-ce/koishi-shim@4.18.11",
-			"@koishijs/loader": "npm:@koishi-ce/koishi-shim@^4.18.11"
+			"@koishijs/loader": "npm:@koishi-ce/koishi-shim@^4.18.11",
+			"@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/plugin-hmr": "^1.0.0",
@@ -390,7 +463,7 @@ async function getName() {
 		initialValue: "koishi-app",
 		validate: (value) => value?.trim() ? void 0 : "项目名不能为空"
 	});
-	if (p.isCancel(answer)) process.exit(0);
+	if (p.isCancel(answer) || typeof answer !== "string") process.exit(0);
 	const trimmed = answer.trim();
 	if (!trimmed) process.exit(0);
 	return trimmed;

package/package.json

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

package/src/__tests__/template.test.ts

@@ -5,18 +5,22 @@ import { expect, test } from "bun:test";
 import { renderManifest } from "../index.ts";
 import {
 	baseManifest,
+	buildUpstreamOverrides,
 	templateFiles,
 } from "../template.ts";
 
 test("内置模板依赖纯度：不含任何 @koishijs / koishi-plugin 官方生态包", () => {
 	const { dependencies, devDependencies } = baseManifest();
-	// 四个上游名是刻意的 npm alias 占位（koishi 裸名 / @koishijs/plugin-console /
-	// @koishijs/core / @koishijs/loader），其余必须是 @koishi-ce 作用域
+	// 六个上游名是刻意的 npm alias 占位（koishi 裸名 / @koishijs/plugin-console /
+	// @koishijs/core / @koishijs/loader / @koishijs/client / @koishijs/components），
+	// 其余必须是 @koishi-ce 作用域
 	const guarded = new Set([
 		"koishi",
 		"@koishijs/plugin-console",
 		"@koishijs/core",
 		"@koishijs/loader",
+		"@koishijs/client",
+		"@koishijs/components",
 	]);
 	for (const key of Object.keys(dependencies ?? {})) {
 		expect(
@@ -96,6 +100,15 @@ test("内置模板钉住 console / core / loader 上游 peer 名，防 Bun 自
 	expect(dependencies?.["@koishijs/loader"]).toBe(
 		"npm:@koishi-ce/koishi-shim@^4.18.11",
 	);
+	// webui 插件把 client 写进 dependencies 的形态（napuketto 实证）：
+	// 版本冻结 5.30.x 线满足 ^5.x，官方 client（连带 components）不再落盘
+	expect(dependencies?.["@koishijs/client"]).toBe(
+		"npm:@koishi-ce/client-shim@^5.30.11",
+	);
+	// 官方 client 的硬依赖、插件生态常直接依赖；冻结 1.5.x 线满足 ^1.5
+	expect(dependencies?.["@koishijs/components"]).toBe(
+		"npm:@koishi-ce/components-shim@^1.5.22",
+	);
 });
 
 test("内置模板静态文件齐备，koishi.yml 预配 market 镜像源", () => {
@@ -166,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 只预写不预装", () => {
@@ -252,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/index.ts

@@ -115,7 +115,10 @@ async function getName(): Promise<string> {
 		validate: (value) =>
 			value?.trim() ? undefined : "项目名不能为空",
 	});
-	if (p.isCancel(answer)) process.exit(0);
+	// @clack/core 1.5 的 isCancel 只收窄 unique symbol，而 text() 返回泛型
+	// symbol，需叠加 typeof 才能把类型收窄到 string
+	if (p.isCancel(answer) || typeof answer !== "string")
+		process.exit(0);
 	const trimmed = answer.trim();
 	if (!trimmed) process.exit(0);
 	return trimmed;

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/template/README.md

@@ -26,7 +26,7 @@ bun run dev          # 启动（开发模式，启用 HMR 热更新）
 
 推荐在控制台「插件市场」页安装（已预配 registry.koishi.chat 镜像源）；也可以手动 `bun add <包名>` 后在 `koishi.yml` 中启用。
 
-根依赖中的四行 npm alias——`"koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"`、`"@koishijs/plugin-console": "npm:@koishi-ce/console-shim@^5.30.11"`、`"@koishijs/core": "npm:@koishi-ce/koishi-shim@4.18.11"`、`"@koishijs/loader": "npm:@koishi-ce/koishi-shim@^4.18.11"`——已把上游生态的 peer 依赖全部钉回 @koishi-ce 框架（前两行与后两行分别只涉及 koishi-shim / console-shim 两个包；**请勿删除或改写这四行**），不会形成第二份框架 / console / loader 副本。
+根依赖中的六行 npm alias——`"koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"`、`"@koishijs/plugin-console": "npm:@koishi-ce/console-shim@^5.30.11"`、`"@koishijs/core": "npm:@koishi-ce/koishi-shim@4.18.11"`、`"@koishijs/loader": "npm:@koishi-ce/koishi-shim@^4.18.11"`、`"@koishijs/client": "npm:@koishi-ce/client-shim@^5.30.11"`、`"@koishijs/components": "npm:@koishi-ce/components-shim@^1.5.22"`——已把上游生态的 peer 与 dependencies 声明全部钉回 @koishi-ce 对应包（涉及 koishi-shim / console-shim / client-shim / components-shim 四个包；**请勿删除或改写这六行**），不会形成第二份框架 / console / 前端库副本。
 
 ## 更新依赖
 

package/src/template.ts

@@ -19,10 +19,12 @@
  *   均以 Bun 为准（ESM-only 产物，Bun 原生加载 TS / yml）；脚本里的环境
  *   变量注入直接写 `NODE_ENV=... ` 前缀——bun run 走 Bun Shell，跨平台
  *   原生支持，无需 cross-env 一类的依赖；
- * - "koishi" 裸名与 @koishijs/core / @koishijs/loader / @koishijs/plugin-console
- *   上游名用 npm alias 钉到 @koishi-ce shim（版本冻结线，见 packages/shim）：
- *   上游官方 adapter / database 插件与社区 koishi-plugin-* 的 peer 由此满足，
- *   不会拉入 npm 官方全家桶形成第二份框架副本；市场安装亦不改写该声明
+ * - "koishi" 裸名与 @koishijs/core / @koishijs/loader / @koishijs/plugin-console /
+ *   @koishijs/client / @koishijs/components 上游名用 npm alias 钉到 @koishi-ce
+ *   shim（版本冻结线，见 packages/shim）：上游官方 adapter / database 插件与
+ *   社区 koishi-plugin-* 的 peer 由此满足，webui 插件写进 dependencies 的
+ *   client / components 亦被钉住（满足性判定看落盘版本），不会拉入 npm
+ *   官方全家桶形成第二份框架副本；市场安装亦不改写该声明
  *   （installer 的 isGuardedRequest 护栏将 npm:@koishi-ce alias 与
  *   workspace: 同等保护）；
  * - koishi.yml 采用配置页导出形态：插件键带 uid 实例后缀，分组带中文
@@ -83,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 会被移除）。
@@ -175,7 +259,19 @@ export function baseManifest(): Manifest {
 			// koishi-shim（4.18.11 满足 ^4.6.11），勿指回已废弃的 loader-shim
 			"@koishijs/loader":
 				"npm:@koishi-ce/koishi-shim@^4.18.11",
+			// 上游 client 名占位：第三方 webui 插件常把 @koishijs/client 写进
+			// dependencies（非 peer，napuketto 实证），无归属时 Bun 装下官方
+			// client 并连带官方 components 全家桶；版本冻结 5.30.x 线满足 ^5.x
+			"@koishijs/client":
+				"npm:@koishi-ce/client-shim@^5.30.11",
+			// 上游 components 名占位：官方 client 的硬依赖，插件生态亦常直接
+			// 依赖（element-plus 系共享组件库）；版本冻结 1.5.x 线满足 ^1.5
+			"@koishijs/components":
+				"npm:@koishi-ce/components-shim@^1.5.22",
 		},
+		// overrides 兜底层（语义见 UPSTREAM_OVERRIDES 注释）：不看版本
+		// 满足性强制重写整棵依赖树，拦住钉名覆盖面之外的上游声明
+		overrides: buildUpstreamOverrides(),
 		devDependencies: {
 			"@koishi-ce/client": "^1.0.0",
 			"@koishi-ce/plugin-hmr": "^1.0.0",