@koishi-ce/koishi 1.0.0

package/lib/cli/index.d.ts

@@ -0,0 +1 @@
+export {}

package/lib/cli/index.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env bun
+import { cac } from "cac";
+import { hyphenate, isInteger } from "@koishi-ce/utils";
+import kleur from "kleur";
+//#region package.json
+var package_default = {
+	name: "@koishi-ce/koishi",
+	type: "module",
+	description: "Cross-Platform Chatbot Framework Made with Love",
+	version: "1.0.0",
+	main: "lib/index.mjs",
+	module: "lib/index.mjs",
+	types: "lib/index.d.ts",
+	bin: "lib/cli/index.mjs",
+	exports: {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./lib/index.d.ts",
+			"import": "./lib/index.mjs",
+			"default": "./lib/index.mjs"
+		},
+		"./lib/cli": "./lib/cli/index.mjs",
+		"./lib/worker": "./lib/worker/index.mjs",
+		"./src/*": "./src/*",
+		"./package.json": "./package.json"
+	},
+	files: ["lib", "src"],
+	contributors: ["Shigma <shigma10826@gmail.com>", "Oppenheymu <oppenheymu@gmail.com>"],
+	license: "MIT",
+	repository: {
+		"type": "git",
+		"url": "git+https://github.com/Koishi-CE/koishi.git",
+		"directory": "packages/node/cli"
+	},
+	bugs: { "url": "https://github.com/Koishi-CE/koishi/issues" },
+	homepage: "https://koishi.chat",
+	keywords: [
+		"bot",
+		"chatbot",
+		"discord",
+		"telegram",
+		"cordis",
+		"framework"
+	],
+	cordis: {
+		"property": "koishi",
+		"ecosystem": { "pattern": [
+			"@koishi-ce/plugin-*",
+			"@koishijs/plugin-*",
+			"koishi-plugin-*"
+		] },
+		"service": { "implements": ["koishi"] }
+	},
+	dependencies: {
+		"@koishi-ce/core": "workspace:*",
+		"@koishi-ce/loader": "workspace:*",
+		"@koishi-ce/plugin-http": "workspace:*",
+		"@koishi-ce/plugin-proxy-agent": "workspace:*",
+		"@koishi-ce/plugin-server": "workspace:*",
+		"@koishi-ce/utils": "workspace:*",
+		"@satorijs/core": "^4.6.0",
+		"cac": "^7.0.0",
+		"kleur": "^4.1.5"
+	}
+};
+//#endregion
+//#region src/cli/start.ts
+/**
+* `koishi start` 子命令实现：守护进程（daemon）侧的父进程逻辑。
+*
+* 通过 Bun.spawn 以 IPC 通道拉起 worker 子进程，并依据子进程发来的消息
+* （启动配置、共享环境数据、心跳）决定是否重启。子进程以约定的退出码
+* 表达意图：51 表示请求重启，52 表示请求退出，其余交由 autoRestart 判断。
+*/
+let child;
+process.env["KOISHI_SHARED"] = JSON.stringify({ startTime: Date.now() });
+/**
+* 将 cac 解析出的选项键转换为命令行参数形式。
+* 单字母键转为 `-x`，其余转为 `--kebab-case`。
+*/
+function toArg(key) {
+	return key.length === 1 ? `-${key}` : `--${hyphenate(key)}`;
+}
+/**
+* 拉起 worker 子进程并接管其生命周期。
+*
+* @param options 命令行选项，会被还原成 execArgv 传给子进程
+*
+* 子进程退出时依据退出码/信号判断是重启还是跟随退出；
+* 启动后若配置了心跳超时，则心跳超时视为进程假死，直接 SIGKILL。
+*/
+function createWorker(options) {
+	const execArgv = Object.entries(options).flatMap(([key, value]) => {
+		if (key === "--") return [];
+		key = toArg(key);
+		if (value === true) return [key];
+		else if (value === false) return [`--no-${key.slice(2)}`];
+		else if (Array.isArray(value)) return value.flatMap((value) => [key, value]);
+		else return [key, String(value)];
+	});
+	execArgv.push(...options["--"] ?? []);
+	const worker = `${import.meta.dir}/../worker/index.mjs`;
+	let config;
+	let timer;
+	const handleMessage = (message) => {
+		if (message.type === "start") {
+			config = message.body;
+			timer = config.heartbeatTimeout ? setTimeout(() => {
+				console.log(kleur.red("daemon: heartbeat timeout"));
+				child.kill("SIGKILL");
+			}, config.heartbeatTimeout) : void 0;
+		} else if (message.type === "shared") process.env["KOISHI_SHARED"] = message.body;
+		else if (message.type === "heartbeat" && timer && config.heartbeatTimeout) {
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				console.log(kleur.red("daemon: heartbeat timeout"));
+				child.kill("SIGKILL");
+			}, config.heartbeatTimeout);
+		}
+	};
+	child = Bun.spawn([
+		process.execPath,
+		worker,
+		...execArgv
+	], {
+		ipc: handleMessage,
+		stdout: "inherit",
+		stderr: "inherit",
+		onExit: (_, code, signal) => {
+			if (shouldExit(code, signal)) process.exit(code ?? 1);
+			createWorker(options);
+		}
+	});
+	/**
+	* 判断子进程退出后父进程应跟随退出还是重新拉起。
+	*
+	* 退出码约定：0 表示正常退出；51 表示请求重启（如 loader 的整进程重载）；
+	* 52 表示请求退出；收到信号一律视为外部终止，跟随退出。
+	*/
+	function shouldExit(code, signal) {
+		if (!config) return true;
+		if (code === 0) return true;
+		if (signal !== null) return true;
+		if (code === 51) return false;
+		if (code === 52) return true;
+		return !config.autoRestart;
+	}
+}
+/**
+* 将命令行选项写入环境变量。
+* 值为 `true` 时写入空字符串（仅表示开关打开），其余写入字符串值。
+*/
+function setEnvArg(name, value) {
+	if (value === true) process.env[name] = "";
+	else if (value) process.env[name] = value;
+}
+/**
+* 向 cac 实例注册 `koishi start`（别名 `koishi run`）子命令。
+*
+* 解析 --debug / --log-level / --log-time 等选项后，把它们写入对应的环境变量
+* （由 worker 侧的 logger 读取），最后交给 createWorker 拉起守护子进程。
+*/
+function start_default(cli) {
+	cli.command("start [file]", "start a koishi bot").alias("run").allowUnknownOptions().option("--debug [namespace]", "specify debug namespace").option("--log-level [level]", "specify log level (default: 2)").option("--log-time [format]", "show timestamp in logs").action((file, options) => {
+		const { logLevel, debug, logTime, ...rest } = options;
+		if (logLevel !== void 0 && (!isInteger(logLevel) || logLevel < 0)) {
+			console.warn(`${kleur.red("error")} log level should be a positive integer.`);
+			process.exit(1);
+		}
+		setEnvArg("KOISHI_LOG_TIME", logTime);
+		process.env["KOISHI_LOG_LEVEL"] = logLevel || "";
+		process.env["KOISHI_DEBUG"] = debug || "";
+		process.env["KOISHI_CONFIG_FILE"] = file || "";
+		createWorker(rest);
+	});
+}
+//#endregion
+//#region src/cli/index.ts
+/**
+* Koishi 命令行入口。
+*
+* 基于 cac 构建名为 `koishi` 的命令行程序，注册 `start`（别名 `run`）子命令后解析
+* 进程参数。若用户未输入任何子命令（且未请求帮助），则自动打印帮助信息退出。
+*/
+const { version } = package_default;
+const cli = cac("koishi").help().version(version);
+start_default(cli);
+const argv = cli.parse();
+if (!cli.matchedCommand && !argv.options["help"]) cli.outputHelp();
+//#endregion
+export {};

package/lib/index-CGzU40S-.d.ts

@@ -0,0 +1,2 @@
+import Loader$1 from "@koishi-ce/loader";
+export { Loader$1 as t };

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import { t as Loader } from "./index-CGzU40S-.js";
+export * from "@koishi-ce/loader";
+export * from "@koishi-ce/core";
+export { Loader };

package/lib/index.mjs

@@ -0,0 +1,4 @@
+import { t as Loader } from "./src-1HtO5Rx4.mjs";
+export * from "@koishi-ce/loader";
+export * from "@koishi-ce/core";
+export { Loader };

package/lib/rolldown-runtime-BBjsoOtd.mjs

@@ -0,0 +1,27 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+//#endregion
+export { __reExport as n, __exportAll as t };

package/lib/src-1HtO5Rx4.mjs

@@ -0,0 +1,11 @@
+import "./rolldown-runtime-BBjsoOtd.mjs";
+import Loader$1 from "@koishi-ce/loader";
+//#region src/index.ts
+/**
+* `@koishi-ce/koishi` 包入口。
+*
+* 本文件专为不使用 CLI 的用户准备：将 core 与 loader 两包的导出合并再分发，
+* 并默认导出 NodeLoader 实现，使开发者可以直接以编程方式启动 Koishi。
+*/
+//#endregion
+export { Loader$1 as t };

package/lib/worker/index.d.ts

@@ -0,0 +1,59 @@
+import { t as Loader } from "../index-CGzU40S-.js";
+import { Context, Dict, Schema } from "@koishi-ce/core";
+export * from "@koishi-ce/loader";
+export * from "@koishi-ce/core";
+//#region src/worker/daemon.d.ts
+/** 守护设置 */
+interface Config$1 {
+  /** 运行时崩溃后是否自动重启 */
+  autoRestart?: boolean;
+  /** 心跳发送间隔（毫秒），0 表示不发送 */
+  heartbeatInterval?: number;
+  /** 心跳超时时间（毫秒），超时后父进程会强杀子进程，0 表示不检测 */
+  heartbeatTimeout?: number;
+}
+declare const Config$1: Schema<Config$1>;
+//#endregion
+//#region src/worker/logger.d.ts
+/**
+ * 配置文件形态的日志等级表。
+ * 与 @koishi-ce/utils 中的实现略有差异：此处不强制用户提供 base 等级，
+ * 缺省时回退到继承的默认值。
+ */
+interface LogLevelConfig {
+  /** 基础日志等级，未提供时沿用上级默认值 */
+  base?: number;
+  [k: string]: LogLevel;
+}
+/** 日志等级：既可以是单一数值，也可以是按名称分级的嵌套配置表 */
+type LogLevel = number | LogLevelConfig;
+/** 日志设置 */
+interface Config {
+  /** 默认的日志输出等级 */
+  levels?: LogLevel;
+  /** 是否标注相邻两次日志输出的时间差 */
+  showDiff?: boolean;
+  /** 日志时间戳的输出格式，true 表示使用默认格式 */
+  showTime?: string | boolean;
+}
+declare const Config: Schema<Config>;
+//#endregion
+//#region src/worker/index.d.ts
+declare module "@koishi-ce/core" {
+  namespace Context {
+    interface Config {
+      /** 插件配置表，键为插件引用（可带 `group:` 前缀），值为插件配置 */
+      plugins?: Dict;
+      /** 时区偏移量（分钟） */
+      timezoneOffset?: number;
+      /** 报错时的调用堆栈深度上限 */
+      stackTraceLimit?: number;
+      /** 日志设置，见 logger.Config */
+      logger?: Config;
+      /** 守护设置，见 daemon.Config */
+      daemon?: Config$1;
+    }
+  }
+}
+//#endregion
+export { Loader };

package/lib/worker/index.mjs

@@ -0,0 +1,149 @@
+import { t as __exportAll } from "../rolldown-runtime-BBjsoOtd.mjs";
+import { t as Loader } from "../src-1HtO5Rx4.mjs";
+import Loader$1 from "@koishi-ce/loader";
+import { Context, Logger, Schema, Time, defineProperty } from "@koishi-ce/core";
+export * from "@koishi-ce/loader";
+export * from "@koishi-ce/core";
+//#region src/worker/daemon.ts
+/**
+* daemon 插件：worker 子进程侧的守护逻辑。
+*
+* 与父守护进程（src/cli/start.ts）配合：启动后上报自身配置，周期发送心跳，
+* 并在收到 SIGINT / SIGTERM 时广播 exit 事件、清理现场后退出进程。
+*/
+var daemon_exports = /* @__PURE__ */ __exportAll({
+	Config: () => Config$1,
+	apply: () => apply,
+	name: () => name
+});
+const Config$1 = Schema.object({
+	autoRestart: Schema.boolean().description("在运行时崩溃自动重启。").default(true),
+	heartbeatInterval: Schema.number().description("心跳发送间隔。").default(0),
+	heartbeatTimeout: Schema.number().description("心跳超时时间。").default(0)
+}).description("守护设置").hidden();
+Context.Config.list.push(Schema.object({ daemon: Config$1 }));
+const name = "daemon";
+function apply(ctx, config = {}) {
+	/**
+	* 信号处理：先通知父进程"本次是主动退出"（防止被当作崩溃重启），
+	* 再广播 exit 事件等待各插件清理完毕后结束进程。
+	*/
+	function handleSignal(signal) {
+		if (config.autoRestart) process.send?.({ type: "exit" });
+		ctx.logger("app").info(`terminated by ${signal}`);
+		ctx.parallel("exit", signal).finally(() => process.exit());
+	}
+	ctx.on("ready", () => {
+		process.send?.({
+			type: "start",
+			body: config
+		});
+		process.on("SIGINT", handleSignal);
+		process.on("SIGTERM", handleSignal);
+		config.heartbeatInterval && setInterval(() => {
+			process.send?.({ type: "heartbeat" });
+		}, config.heartbeatInterval);
+	});
+}
+//#endregion
+//#region src/worker/logger.ts
+/**
+* 日志配置的解析与应用（worker 侧）。
+*
+* 在应用启动前根据配置文件与 CLI 环境变量（KOISHI_LOG_LEVEL / KOISHI_DEBUG 等）
+* 完成全局 Logger 的等级、时间格式等设定。CLI 传入的环境变量优先级高于配置文件。
+*/
+/**
+* 将配置文件形态的等级表归一化为 Logger 内部的 LevelConfig 结构：
+* 逐层填充 base 并递归处理嵌套对象。
+*/
+function normalizeLevels(config, base) {
+	const result = { base: config.base ?? base };
+	for (const [name, level] of Object.entries(config)) {
+		if (name === "base") continue;
+		result[name] = typeof level === "number" ? level : normalizeLevels(level, result.base);
+	}
+	return result;
+}
+const Config = Schema.object({
+	levels: Schema.any().description("默认的日志输出等级。"),
+	showDiff: Schema.boolean().description("标注相邻两次日志输出的时间差。"),
+	showTime: Schema.union([Boolean, String]).default(true).description("输出日志所使用的时间格式。")
+}).description("日志设置").hidden();
+defineProperty(Context.Config, "logger", Config);
+Context.Config.list.push(Schema.object({ logger: Config }));
+/**
+* 在应用启动前应用日志配置。
+*
+* 处理顺序：配置文件中的等级表 → 时间格式与时间差显示 → CLI 环境变量覆盖 →
+* 补全所有分组的 base 等级 → KOISHI_DEBUG 指定的命名空间设为 DEBUG 级。
+*
+* @param config 来自配置文件 logger 节点的设置
+*/
+function prepare(config = {}) {
+	const { levels } = config;
+	if (typeof levels === "object") Logger.levels = normalizeLevels(levels, 2);
+	else if (typeof levels === "number") Logger.levels.base = levels;
+	let showTime = config.showTime;
+	if (showTime === true) showTime = "yyyy-MM-dd hh:mm:ss";
+	const target = Logger.targets[0];
+	if (target) {
+		if (showTime) target.showTime = showTime;
+		target.showDiff = config.showDiff ?? false;
+	}
+	if (process.env["KOISHI_LOG_LEVEL"]) Logger.levels.base = +process.env["KOISHI_LOG_LEVEL"];
+	/** 递归为所有子命名空间补全 base 等级（未显式设置时继承父级） */
+	function ensureBaseLevel(config, base) {
+		config.base ??= base;
+		Object.values(config).forEach((value) => {
+			if (typeof value !== "object") return;
+			ensureBaseLevel(value, config.base);
+		});
+	}
+	ensureBaseLevel(Logger.levels, 2);
+	if (process.env["KOISHI_DEBUG"]) for (const name of process.env["KOISHI_DEBUG"].split(",")) new Logger(name).level = Logger.DEBUG;
+	if (target) target.timestamp = Date.now();
+}
+//#endregion
+//#region src/worker/index.ts
+/**
+* worker 子进程入口：真正启动 Koishi 应用的地方。
+*
+* 由 CLI 守护进程（src/cli/start.ts）通过 Bun.spawn 拉起。流程为：
+* 初始化 Loader 并读取配置文件 → 应用日志配置 → 应用时区与堆栈深度设置 →
+* 创建应用上下文 → 挂载 daemon 插件 → 启动。未捕获异常将以错误码 1 退出，
+* 由父进程依据退出码决定是否重启。
+*/
+const advancedDict = Context.Config.Advanced.dict;
+if (advancedDict) Object.assign(advancedDict, {
+	timezoneOffset: Schema.number().description("时区偏移量 (分钟)。").default((/* @__PURE__ */ new Date()).getTimezoneOffset()),
+	stackTraceLimit: Schema.natural().description("报错的调用堆栈深度。").default(10),
+	plugins: Schema.any().hidden()
+});
+/**
+* 未捕获异常的兜底处理：记录日志后以退出码 1 结束进程，
+* 交由父守护进程决定是否重启。
+*/
+function handleException(error) {
+	new Logger("app").error(error);
+	process.exit(1);
+}
+process.on("uncaughtException", handleException);
+process.on("unhandledRejection", (error) => {
+	new Logger("app").warn(error);
+});
+/** 应用启动主流程 */
+async function start() {
+	const loader = new Loader$1();
+	await loader.init(process.env["KOISHI_CONFIG_FILE"]);
+	const config = await loader.readConfig(true);
+	prepare(config.logger);
+	if (config.timezoneOffset !== void 0) Time.setTimezoneOffset(config.timezoneOffset);
+	if (config.stackTraceLimit !== void 0) Error.stackTraceLimit = config.stackTraceLimit;
+	const app = await loader.createApp();
+	app.plugin(daemon_exports, config.daemon);
+	await app.start();
+}
+await start().catch(handleException);
+//#endregion
+export { Loader };

package/package.json

@@ -0,0 +1,74 @@
+{
+    "name": "@koishi-ce/koishi",
+    "type": "module",
+    "description": "Cross-Platform Chatbot Framework Made with Love",
+    "version": "1.0.0",
+    "main": "lib/index.mjs",
+    "module": "lib/index.mjs",
+    "types": "lib/index.d.ts",
+    "bin": "lib/cli/index.mjs",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "types": "./lib/index.d.ts",
+            "import": "./lib/index.mjs",
+            "default": "./lib/index.mjs"
+        },
+        "./lib/cli": "./lib/cli/index.mjs",
+        "./lib/worker": "./lib/worker/index.mjs",
+        "./src/*": "./src/*",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "lib",
+        "src"
+    ],
+    "contributors": [
+        "Shigma <shigma10826@gmail.com>",
+        "Oppenheymu <oppenheymu@gmail.com>"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Koishi-CE/koishi.git",
+        "directory": "packages/node/cli"
+    },
+    "bugs": {
+        "url": "https://github.com/Koishi-CE/koishi/issues"
+    },
+    "homepage": "https://koishi.chat",
+    "keywords": [
+        "bot",
+        "chatbot",
+        "discord",
+        "telegram",
+        "cordis",
+        "framework"
+    ],
+    "cordis": {
+        "property": "koishi",
+        "ecosystem": {
+            "pattern": [
+                "@koishi-ce/plugin-*",
+                "@koishijs/plugin-*",
+                "koishi-plugin-*"
+            ]
+        },
+        "service": {
+            "implements": [
+                "koishi"
+            ]
+        }
+    },
+    "dependencies": {
+        "@koishi-ce/core": "^1.0.0",
+        "@koishi-ce/loader": "^1.0.0",
+        "@koishi-ce/plugin-http": "^1.0.0",
+        "@koishi-ce/plugin-proxy-agent": "^1.0.0",
+        "@koishi-ce/plugin-server": "^1.0.0",
+        "@koishi-ce/utils": "^1.0.0",
+        "@satorijs/core": "^4.6.0",
+        "cac": "^7.0.0",
+        "kleur": "^4.1.5"
+    }
+}

package/readme.md

@@ -0,0 +1,26 @@
+<div align="center">
+  <a href="https://koishi.chat/" target="_blank">
+    <img width="160" src="https://koishi.chat/logo.png" alt="logo">
+  </a>
+  <h1 id="koishi"><a href="https://github.com/Koishi-CE/koishi" target="_blank">Koishi CE</a></h1>
+
+[![npm](https://img.shields.io/npm/v/@koishi-ce/koishi?style=flat-square)](https://www.npmjs.com/package/@koishi-ce/koishi)
+[![GitHub](https://img.shields.io/github/license/Koishi-CE/koishi?style=flat-square)](https://github.com/Koishi-CE/koishi/blob/main/LICENSE)
+
+</div>
+
+`@koishi-ce/koishi` 是 [Koishi](https://koishi.chat) 的社区再发行版 (Community Edition) 命令行工具，来自 [Koishi-CE/koishi](https://github.com/Koishi-CE/koishi) —— 将 Koishi 核心与 webui 合并重构的单一 Bun workspace 单仓库。
+
+命令名保持为 `koishi`，与上游用法一致：
+
+```bash
+npm install -g @koishi-ce/koishi
+```
+
+> 本项目与 Koishijs 官方组织无从属关系。感谢原作者 Shigma 及所有上游贡献者，相关声明见仓库根目录的 NOTICE 与 UPSTREAM 文件。
+
+## 许可证
+
+本包基于 [MIT](./LICENSE) 协议开源。
+
+Copyright © 2019-2023, Shigma; Koishi-CE contributors

package/src/cli/index.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+
+/**
+ * Koishi 命令行入口。
+ *
+ * 基于 cac 构建名为 `koishi` 的命令行程序，注册 `start`（别名 `run`）子命令后解析
+ * 进程参数。若用户未输入任何子命令（且未请求帮助），则自动打印帮助信息退出。
+ */
+
+import { cac } from "cac";
+import pkg from "../../package.json" with { type: "json" };
+
+const { version } = pkg;
+
+import registerStartCommand from "./start.ts";
+
+const cli = cac("koishi").help().version(version);
+
+registerStartCommand(cli);
+
+const argv = cli.parse();
+
+// 未匹配到子命令且未请求 --help 时，主动输出帮助信息，避免静默退出
+if (!cli.matchedCommand && !argv.options["help"]) {
+	cli.outputHelp();
+}

package/src/cli/start.ts

@@ -0,0 +1,193 @@
+/**
+ * `koishi start` 子命令实现：守护进程（daemon）侧的父进程逻辑。
+ *
+ * 通过 Bun.spawn 以 IPC 通道拉起 worker 子进程，并依据子进程发来的消息
+ * （启动配置、共享环境数据、心跳）决定是否重启。子进程以约定的退出码
+ * 表达意图：51 表示请求重启，52 表示请求退出，其余交由 autoRestart 判断。
+ */
+
+import { hyphenate, isInteger } from "@koishi-ce/utils";
+import type { CAC } from "cac";
+import kleur from "kleur";
+import type { Config } from "../worker/daemon.ts";
+
+/** 子进程通过 IPC 通道发来的消息类型（并集） */
+type Event = Event.Start | Event.Env | Event.Heartbeat;
+/** 单个命令行选项的取值形态 */
+type WorkerOption = boolean | string | string[] | undefined;
+/** 传递给 worker 的完整选项表；`--` 键对应 cac 收集的透传参数 */
+type WorkerOptions = Record<string, WorkerOption> & { "--"?: string[] };
+
+/** 子进程 IPC 消息的具体结构定义 */
+namespace Event {
+	/** worker 启动完成，附带解析后的守护配置 */
+	export interface Start {
+		type: "start";
+		body: Config;
+	}
+
+	/** loader 触发整进程重载时回传的共享环境数据（KOISHI_SHARED） */
+	export interface Env {
+		type: "shared";
+		body: string;
+	}
+
+	/** 周期性心跳，用于父进程检测子进程是否假死 */
+	export interface Heartbeat {
+		type: "heartbeat";
+	}
+}
+
+let child: Bun.Subprocess;
+
+// 跨重启保留的共享数据：首次启动仅记录启动时间，后续由子进程回传覆盖
+process.env["KOISHI_SHARED"] = JSON.stringify({
+	startTime: Date.now(),
+});
+
+/**
+ * 将 cac 解析出的选项键转换为命令行参数形式。
+ * 单字母键转为 `-x`，其余转为 `--kebab-case`。
+ */
+function toArg(key: string) {
+	return key.length === 1 ? `-${key}` : `--${hyphenate(key)}`;
+}
+
+/**
+ * 拉起 worker 子进程并接管其生命周期。
+ *
+ * @param options 命令行选项，会被还原成 execArgv 传给子进程
+ *
+ * 子进程退出时依据退出码/信号判断是重启还是跟随退出；
+ * 启动后若配置了心跳超时，则心跳超时视为进程假死，直接 SIGKILL。
+ */
+function createWorker(options: WorkerOptions) {
+	// 将选项对象还原为 Node/Bun 可识别的 execArgv 数组
+	const execArgv = Object.entries(options).flatMap<string>(([key, value]) => {
+		if (key === "--") return [];
+		key = toArg(key);
+		if (value === true) {
+			return [key];
+		} else if (value === false) {
+			// 布尔假值转为 --no-xxx 形式
+			return [`--no-${key.slice(2)}`];
+		} else if (Array.isArray(value)) {
+			// 数组值展开为多组 "键 值" 对
+			return value.flatMap((value) => [key, value]);
+		} else {
+			return [key, String(value)];
+		}
+	});
+	execArgv.push(...(options["--"] ?? []));
+
+	// worker 入口为构建产物 index.mjs，而非本 TS 源文件
+	const worker = `${import.meta.dir}/../worker/index.mjs`;
+
+	let config: Config;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	// 处理子进程 IPC 消息：start / shared / heartbeat
+	const handleMessage = (message: Event) => {
+		if (message.type === "start") {
+			config = message.body;
+			timer = config.heartbeatTimeout
+				? setTimeout(() => {
+						// eslint-disable-next-line no-console
+						console.log(kleur.red("daemon: heartbeat timeout"));
+						child.kill("SIGKILL");
+					}, config.heartbeatTimeout)
+				: undefined;
+		} else if (message.type === "shared") {
+			process.env["KOISHI_SHARED"] = message.body;
+		} else if (
+			message.type === "heartbeat" &&
+			timer &&
+			config.heartbeatTimeout
+		) {
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				// eslint-disable-next-line no-console
+				console.log(kleur.red("daemon: heartbeat timeout"));
+				child.kill("SIGKILL");
+			}, config.heartbeatTimeout);
+		}
+	};
+
+	child = Bun.spawn([process.execPath, worker, ...execArgv], {
+		ipc: handleMessage,
+		// Bun.spawn 的 stdio 默认为 ignore，须显式继承输出通道，
+		// 否则 worker 的全部日志都会被丢弃
+		stdout: "inherit",
+		stderr: "inherit",
+		onExit: (_, code, signal) => {
+			if (shouldExit(code, signal)) {
+				process.exit(code ?? 1);
+			}
+			createWorker(options);
+		},
+	});
+
+	/**
+	 * 判断子进程退出后父进程应跟随退出还是重新拉起。
+	 *
+	 * 退出码约定：0 表示正常退出；51 表示请求重启（如 loader 的整进程重载）；
+	 * 52 表示请求退出；收到信号一律视为外部终止，跟随退出。
+	 */
+	function shouldExit(code: number | null, signal: number | null) {
+		// 尚未收到 start 消息即退出，说明启动失败
+		if (!config) return true;
+
+		// 手动退出（正常退出码或被信号终止）
+		if (code === 0) return true;
+		if (signal !== null) return true;
+
+		// 手动重启 / 手动停止
+		if (code === 51) return false;
+		if (code === 52) return true;
+
+		// 其余情况交由 autoRestart 配置决定
+		return !config.autoRestart;
+	}
+}
+
+/**
+ * 将命令行选项写入环境变量。
+ * 值为 `true` 时写入空字符串（仅表示开关打开），其余写入字符串值。
+ */
+function setEnvArg(name: string, value: string | boolean) {
+	if (value === true) {
+		process.env[name] = "";
+	} else if (value) {
+		process.env[name] = value;
+	}
+}
+
+/**
+ * 向 cac 实例注册 `koishi start`（别名 `koishi run`）子命令。
+ *
+ * 解析 --debug / --log-level / --log-time 等选项后，把它们写入对应的环境变量
+ * （由 worker 侧的 logger 读取），最后交给 createWorker 拉起守护子进程。
+ */
+export default function (cli: CAC) {
+	cli
+		.command("start [file]", "start a koishi bot")
+		.alias("run")
+		.allowUnknownOptions()
+		.option("--debug [namespace]", "specify debug namespace")
+		.option("--log-level [level]", "specify log level (default: 2)")
+		.option("--log-time [format]", "show timestamp in logs")
+		.action((file, options) => {
+			const { logLevel, debug, logTime, ...rest } = options;
+			if (logLevel !== undefined && (!isInteger(logLevel) || logLevel < 0)) {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`${kleur.red("error")} log level should be a positive integer.`,
+				);
+				process.exit(1);
+			}
+			setEnvArg("KOISHI_LOG_TIME", logTime);
+			process.env["KOISHI_LOG_LEVEL"] = logLevel || "";
+			process.env["KOISHI_DEBUG"] = debug || "";
+			process.env["KOISHI_CONFIG_FILE"] = file || "";
+			createWorker(rest);
+		});
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@koishi-ce/koishi` 包入口。
+ *
+ * 本文件专为不使用 CLI 的用户准备：将 core 与 loader 两包的导出合并再分发，
+ * 并默认导出 NodeLoader 实现，使开发者可以直接以编程方式启动 Koishi。
+ */
+
+import Loader from "@koishi-ce/loader";
+
+export * from "@koishi-ce/core";
+export * from "@koishi-ce/loader";
+export { Loader };

package/src/worker/daemon.ts

@@ -0,0 +1,64 @@
+/**
+ * daemon 插件：worker 子进程侧的守护逻辑。
+ *
+ * 与父守护进程（src/cli/start.ts）配合：启动后上报自身配置，周期发送心跳，
+ * 并在收到 SIGINT / SIGTERM 时广播 exit 事件、清理现场后退出进程。
+ */
+
+import { Context, Schema } from "@koishi-ce/core";
+
+/** 守护设置 */
+export interface Config {
+	/** 运行时崩溃后是否自动重启 */
+	autoRestart?: boolean;
+	/** 心跳发送间隔（毫秒），0 表示不发送 */
+	heartbeatInterval?: number;
+	/** 心跳超时时间（毫秒），超时后父进程会强杀子进程，0 表示不检测 */
+	heartbeatTimeout?: number;
+}
+
+export const Config: Schema<Config> = Schema.object({
+	autoRestart: Schema.boolean()
+		.description("在运行时崩溃自动重启。")
+		.default(true),
+	heartbeatInterval: Schema.number().description("心跳发送间隔。").default(0),
+	heartbeatTimeout: Schema.number().description("心跳超时时间。").default(0),
+})
+	.description("守护设置")
+	.hidden();
+
+Context.Config.list.push(
+	Schema.object({
+		daemon: Config,
+	}),
+);
+
+export const name = "daemon";
+
+export function apply(ctx: Context, config: Config = {}) {
+	/**
+	 * 信号处理：先通知父进程"本次是主动退出"（防止被当作崩溃重启），
+	 * 再广播 exit 事件等待各插件清理完毕后结束进程。
+	 */
+	function handleSignal(signal: NodeJS.Signals) {
+		// 子进程主动退出时须防止父进程按 autoRestart 策略重启
+		if (config.autoRestart) {
+			process.send?.({ type: "exit" });
+		}
+		ctx.logger("app").info(`terminated by ${signal}`);
+		ctx.parallel("exit", signal).finally(() => process.exit());
+	}
+
+	ctx.on("ready", () => {
+		// 向父进程上报守护配置，供其心跳超时与重启判定使用
+		process.send?.({ type: "start", body: config });
+		process.on("SIGINT", handleSignal);
+		process.on("SIGTERM", handleSignal);
+
+		// 按配置间隔向父进程发送心跳
+		config.heartbeatInterval &&
+			setInterval(() => {
+				process.send?.({ type: "heartbeat" });
+			}, config.heartbeatInterval);
+	});
+}

package/src/worker/index.ts

@@ -0,0 +1,92 @@
+/**
+ * worker 子进程入口：真正启动 Koishi 应用的地方。
+ *
+ * 由 CLI 守护进程（src/cli/start.ts）通过 Bun.spawn 拉起。流程为：
+ * 初始化 Loader 并读取配置文件 → 应用日志配置 → 应用时区与堆栈深度设置 →
+ * 创建应用上下文 → 挂载 daemon 插件 → 启动。未捕获异常将以错误码 1 退出，
+ * 由父进程依据退出码决定是否重启。
+ */
+
+import { Context, type Dict, Logger, Schema, Time } from "@koishi-ce/core";
+import Loader from "@koishi-ce/loader";
+import * as daemon from "./daemon.ts";
+import * as logger from "./logger.ts";
+
+// 以相对导入 re-export 包主入口（上游同款写法）：worker 产物本身属于本包，
+// 若写包名自引用，作为 main entry 直接执行时会触发 Bun 的自引用解析问题
+// （进程静默退出）；相对导入在构建期内联，运行时无自引用。
+export * from "../index.ts";
+
+// 通过模块合并向全局 Context.Config 追加本入口支持的配置项
+declare module "@koishi-ce/core" {
+	namespace Context {
+		interface Config {
+			/** 插件配置表，键为插件引用（可带 `group:` 前缀），值为插件配置 */
+			plugins?: Dict;
+			/** 时区偏移量（分钟） */
+			timezoneOffset?: number;
+			/** 报错时的调用堆栈深度上限 */
+			stackTraceLimit?: number;
+			/** 日志设置，见 logger.Config */
+			logger?: logger.Config;
+			/** 守护设置，见 daemon.Config */
+			daemon?: daemon.Config;
+		}
+	}
+}
+
+// 向控制台"高级设置"分区注册本入口新增的配置项 schema
+const advancedDict = Context.Config.Advanced.dict;
+if (advancedDict) {
+	Object.assign(advancedDict, {
+		timezoneOffset: Schema.number()
+			.description("时区偏移量 (分钟)。")
+			.default(new Date().getTimezoneOffset()),
+		stackTraceLimit: Schema.natural()
+			.description("报错的调用堆栈深度。")
+			.default(10),
+		plugins: Schema.any().hidden(),
+	});
+}
+
+/**
+ * 未捕获异常的兜底处理：记录日志后以退出码 1 结束进程，
+ * 交由父守护进程决定是否重启。
+ */
+function handleException(error: unknown) {
+	new Logger("app").error(error);
+	process.exit(1);
+}
+
+process.on("uncaughtException", handleException);
+
+// Promise 拒绝不致命，仅告警，避免应用因单个异步错误退出
+process.on("unhandledRejection", (error) => {
+	new Logger("app").warn(error);
+});
+
+/** 应用启动主流程 */
+async function start() {
+	const loader = new Loader();
+	await loader.init(process.env["KOISHI_CONFIG_FILE"]);
+	const config = await loader.readConfig(true);
+	logger.prepare(config.logger);
+
+	if (config.timezoneOffset !== undefined) {
+		Time.setTimezoneOffset(config.timezoneOffset);
+	}
+
+	if (config.stackTraceLimit !== undefined) {
+		Error.stackTraceLimit = config.stackTraceLimit;
+	}
+
+	const app = await loader.createApp();
+	// 挂载 daemon 插件以接管信号处理与心跳上报
+	app.plugin(daemon, config.daemon);
+	await app.start();
+}
+
+// 顶层 await 启动：main entry 的模块求值须挂起至启动链推进完成——
+// 若以 start().catch(...) 形式让出，Bun 事件循环在无其他句柄时会随首个
+// await 立即退出（进程静默 exit 0，插件与 daemon 心跳均来不及注册保活）
+await start().catch(handleException);

package/src/worker/logger.ts

@@ -0,0 +1,119 @@
+/**
+ * 日志配置的解析与应用（worker 侧）。
+ *
+ * 在应用启动前根据配置文件与 CLI 环境变量（KOISHI_LOG_LEVEL / KOISHI_DEBUG 等）
+ * 完成全局 Logger 的等级、时间格式等设定。CLI 传入的环境变量优先级高于配置文件。
+ */
+
+import { Context, defineProperty, Logger, Schema } from "@koishi-ce/core";
+
+/**
+ * 配置文件形态的日志等级表。
+ * 与 @koishi-ce/utils 中的实现略有差异：此处不强制用户提供 base 等级，
+ * 缺省时回退到继承的默认值。
+ */
+interface LogLevelConfig {
+	/** 基础日志等级，未提供时沿用上级默认值 */
+	base?: number;
+	[k: string]: LogLevel;
+}
+
+/** 日志等级：既可以是单一数值，也可以是按名称分级的嵌套配置表 */
+type LogLevel = number | LogLevelConfig;
+
+/**
+ * 将配置文件形态的等级表归一化为 Logger 内部的 LevelConfig 结构：
+ * 逐层填充 base 并递归处理嵌套对象。
+ */
+function normalizeLevels(
+	config: LogLevelConfig,
+	base: number,
+): Logger.LevelConfig {
+	const result: Logger.LevelConfig = { base: config.base ?? base };
+	for (const [name, level] of Object.entries(config)) {
+		if (name === "base") continue;
+		result[name] =
+			typeof level === "number" ? level : normalizeLevels(level, result.base);
+	}
+	return result;
+}
+
+/** 日志设置 */
+export interface Config {
+	/** 默认的日志输出等级 */
+	levels?: LogLevel;
+	/** 是否标注相邻两次日志输出的时间差 */
+	showDiff?: boolean;
+	/** 日志时间戳的输出格式，true 表示使用默认格式 */
+	showTime?: string | boolean;
+}
+
+export const Config: Schema<Config> = Schema.object({
+	levels: Schema.any().description("默认的日志输出等级。"),
+	showDiff: Schema.boolean().description("标注相邻两次日志输出的时间差。"),
+	showTime: Schema.union([Boolean, String])
+		.default(true)
+		.description("输出日志所使用的时间格式。"),
+})
+	.description("日志设置")
+	.hidden();
+
+defineProperty(Context.Config, "logger", Config);
+
+Context.Config.list.push(
+	Schema.object({
+		logger: Config,
+	}),
+);
+
+/**
+ * 在应用启动前应用日志配置。
+ *
+ * 处理顺序：配置文件中的等级表 → 时间格式与时间差显示 → CLI 环境变量覆盖 →
+ * 补全所有分组的 base 等级 → KOISHI_DEBUG 指定的命名空间设为 DEBUG 级。
+ *
+ * @param config 来自配置文件 logger 节点的设置
+ */
+export function prepare(config: Config = {}) {
+	const { levels } = config;
+	// 应用配置文件中的日志等级设置
+	if (typeof levels === "object") {
+		Logger.levels = normalizeLevels(levels, 2);
+	} else if (typeof levels === "number") {
+		Logger.levels.base = levels;
+	}
+
+	let showTime = config.showTime;
+	if (showTime === true) showTime = "yyyy-MM-dd hh:mm:ss";
+	const target = Logger.targets[0];
+	if (target) {
+		if (showTime) target.showTime = showTime;
+		target.showDiff = config.showDiff ?? false;
+	}
+
+	// CLI 传入的选项优先级高于配置文件
+	if (process.env["KOISHI_LOG_LEVEL"]) {
+		Logger.levels.base = +process.env["KOISHI_LOG_LEVEL"];
+	}
+
+	/** 递归为所有子命名空间补全 base 等级（未显式设置时继承父级） */
+	function ensureBaseLevel(config: Logger.LevelConfig, base: number) {
+		config.base ??= base;
+		Object.values(config).forEach((value) => {
+			if (typeof value !== "object") return;
+			ensureBaseLevel(value, config.base);
+		});
+	}
+
+	ensureBaseLevel(Logger.levels, 2);
+
+	// KOISHI_DEBUG 指定的各个命名空间一律开启 DEBUG 级输出
+	if (process.env["KOISHI_DEBUG"]) {
+		for (const name of process.env["KOISHI_DEBUG"].split(",")) {
+			new Logger(name).level = Logger.DEBUG;
+		}
+	}
+
+	// 重置时间差计算的基准时间戳，避免把启动前的耗时计入首条日志
+	if (target) target.timestamp = Date.now();
+}