cortico 0.1.0

package/src/deploy.ts

@@ -0,0 +1,162 @@
+/**
+ * 部署配置按顺序深合并：BotDefinition.defaults()、包内 World 覆盖、共享端点表、部署 config.json。
+ * 部署文件中的 providers 字段不参与合并。Core、Persona 与 World 的默认值由各自所有者提供。
+ * 运行时共享合并后的配置对象，控制台和调参工具原位更新。
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import type { CoreConfig, LLMProviderEntry } from './core/types.ts';
+import { deepMerge, type LoadedConfig } from './core/config.ts';
+import { secretReader } from './core/secrets.ts';
+import { readTextFile } from './core/util.ts';
+import { deploymentRoot, repoRoot as codeRepoRoot } from './paths.ts';
+
+export type { LoadedConfig } from './core/config.ts';
+
+/** 部署根下每个含 deployment.json 的目录就是一份可启动的部署。 */
+export function listBots(root = deploymentRoot()): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((name) => {
+      const dir = resolve(root, name);
+      return statSync(dir).isDirectory() && existsSync(resolve(dir, 'deployment.json'));
+    })
+    .sort();
+}
+
+/** 部署根下一份部署都没有时自建的那份，以及它引用的 bot 代码包。 */
+export const DEFAULT_DEPLOYMENT = { name: 'mybot', bot: 'cormini' } as const;
+
+/** 部署目录中的开场引导标记。 */
+export const ONBOARDING_FLAG_FILE = '.onboarding';
+
+/** 部署根下另有用途的目录名，不能拿来当部署名。 */
+const RESERVED_DEPLOYMENT_NAMES: readonly string[] = ['providers', 'runtimes', 'models'];
+
+/** 部署目录名不合用的原因；合用时为 null。这个名字就是目录名，也出现在命令行上。 */
+export function deploymentNameProblem(name: string, taken: readonly string[]): string | null {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    return '只能用字母、数字、- . _，且以字母或数字开头。';
+  }
+  if (RESERVED_DEPLOYMENT_NAMES.includes(name)) return `${name} 是部署根下的固定目录。`;
+  if (taken.includes(name)) return `${name} 已经有了。`;
+  return null;
+}
+
+/**
+ * 建一份空白部署：`deployment.json` 指向代码包，加上开场引导的标记；给了展示名就写一份
+ * 只有 `displayName` 的 `config.json`。端点与其余设置在控制台里配。
+ */
+export function createDeployment(
+  options: { name: string; bot: string; displayName?: string; root?: string },
+): string {
+  const root = options.root ?? deploymentRoot();
+  const problem = deploymentNameProblem(options.name, listBots(root));
+  if (problem) throw new Error(problem);
+  const dir = resolve(root, options.name);
+  mkdirSync(dir, { recursive: true });
+  writeJson(resolve(dir, 'deployment.json'), { bot: options.bot });
+  if (options.displayName) writeJson(resolve(dir, 'config.json'), { displayName: options.displayName });
+  writeFileSync(resolve(dir, ONBOARDING_FLAG_FILE), '', 'utf8');
+  return options.name;
+}
+
+function writeJson(file: string, value: unknown): void {
+  writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+/** 返回一个可启动的部署名；部署根下一份都没有时先建 DEFAULT_DEPLOYMENT。 */
+export function ensureDeployment(root = deploymentRoot()): string {
+  const existing = listBots(root);
+  if (existing.length > 0) return existing[0];
+  return createDeployment({ ...DEFAULT_DEPLOYMENT, root });
+}
+
+export interface DeploymentSource<C extends CoreConfig> {
+  /** 每次返回独立的合并默认值。 */
+  defaults(): C;
+}
+
+/**
+ * 读取 <部署根>/providers/<端点名>/config.json，供同一部署根下的部署共享。
+ * 同名条目覆盖 Core 默认端点；目录内的密钥与其他状态由 provider 管理。
+ */
+function globalProviders(providersDir: string): Record<string, LLMProviderEntry> {
+  if (!existsSync(providersDir)) return {};
+  const table: Record<string, LLMProviderEntry> = {};
+  for (const name of readdirSync(providersDir)) {
+    const file = resolve(providersDir, name, 'config.json');
+    if (!existsSync(file)) continue;
+    try {
+      table[name] = JSON.parse(readTextFile(file)) as LLMProviderEntry;
+    } catch (err) {
+      throw new Error(`${file} 解析失败:${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return table;
+}
+
+/**
+ * 代码包在 worlds/<id>/config.json 提供 World 配置覆盖；部署 config.json 可继续覆盖。
+ * 路径、设备与端口等本机配置由部署提供。
+ */
+function packageWorldOverrides(pkgDir: string): Record<string, unknown> {
+  const ioDir = resolve(pkgDir, 'worlds');
+  if (!existsSync(ioDir)) return {};
+  const worlds: Record<string, unknown> = {};
+  for (const id of readdirSync(ioDir)) {
+    const file = resolve(ioDir, id, 'config.json');
+    if (!existsSync(file)) continue;
+    try {
+      worlds[id] = JSON.parse(readTextFile(file));
+    } catch (err) {
+      throw new Error(`${file} 解析失败:${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return Object.keys(worlds).length ? { worlds } : {};
+}
+
+/**
+ * 加载部署并解析目录：
+ * botDir 是部署目录，config.json、.env 及相对 memory/data 路径以它为基准。
+ * repoRoot 是代码检出目录，用于扩展与代码信息。
+ * pkgDir 是代码包目录，供模板和包内资产使用；缺省为 botDir。
+ * providersDir 是共享端点目录；缺省为 <botDir>/providers。
+ */
+export function loadDeployment<C extends CoreConfig>(
+  source: DeploymentSource<C>,
+  botDir: string,
+  repoRoot: string = codeRepoRoot(),
+  pkgDir: string = botDir,
+  providersDir: string = resolve(botDir, 'providers'),
+): LoadedConfig<C> {
+  const dir = resolve(botDir);
+  const root = resolve(repoRoot);
+  const providers = resolve(providersDir);
+  const cfgPath = resolve(dir, 'config.json');
+  const raw: Partial<C> & Record<string, unknown> = existsSync(cfgPath)
+    ? (JSON.parse(readTextFile(cfgPath)) as Partial<C> & Record<string, unknown>)
+    : {};
+  // 部署文件不能覆盖共享端点表。
+  delete raw.providers;
+  // source.defaults() 已包含各所有者默认值，后续层依次覆盖。
+  const config = deepMerge(
+    deepMerge(
+      deepMerge(source.defaults(), packageWorldOverrides(resolve(pkgDir)) as Partial<C>),
+      { providers: globalProviders(providers) } as Partial<C>,
+    ),
+    raw,
+  );
+
+  const abs = (p: string): string => (isAbsolute(p) ? p : resolve(dir, p));
+  return {
+    config,
+    secret: secretReader(resolve(dir, '.env')),
+    rootDir: dir,
+    packageDir: resolve(pkgDir),
+    providersDir: providers,
+    repoRoot: root,
+    memoryDir: abs(config.paths.memory),
+    dataDir: abs(config.paths.data),
+  };
+}

package/src/extensions/README.md

@@ -0,0 +1,72 @@
+<!-- Owner: src/extensions/manifest.ts, src/extensions/runtime.ts, src/extensions/dry-mount.ts, src/extensions.ts -->
+
+# src/extensions
+
+扩展是装在 `extensions/` 下的 npm 包,给框架补一个 World、一个 provider 或一个 bot。
+三类使用相同的 manifest 和加载流程,按 `kind` 校验默认导出结构、id 命名空间与控制台页前缀。
+`pnpm check:extension` 使用 `dry-mount.ts` 在假部署中验证构造与声明接口:
+World 调用 `create()` / `tools()` / `console()`,provider 调用 `create()`,bot 调用 `build()`;
+不调用 `start()`。
+
+## manifest
+
+包的 `package.json` 里一块 `cortico`:
+
+```jsonc
+{
+  "name": "cortico-world-vtuber",
+  "type": "module",                       // 必填;CommonJS 有加载重复模块实例的风险
+  "keywords": ["cortico-world"],          // npm 搜索按类关键字:cortico-world / cortico-provider / cortico-bot
+  "cortico": {
+    "kind": "world",                      // world | provider | bot
+    "api": 4,                             // 扩展契约版本,与 EXTENSION_API_VERSION 相等才加载
+    "consoleClient": "dist/console.js",   // 可选:预构建的面板 bundle,包内相对路径
+    "consoleStyle": "dist/console.css"    // 可选:随 bundle 注入的样式
+  }
+}
+```
+
+`parseExtensionManifest(pkg)` 只做解析与校验,不碰文件系统;装载器与
+`pnpm check:extension <dir>` 共用它。`api` 与框架不等时不加载,扩展页说明哪一边旧。
+`WorldDefinition`、`ProviderModule`、`BotDefinition`(连同 `BotParts`、`Persona`、`LoadedConfig`)
+或 `ConsolePanelContext` 任一不兼容变更就把 `EXTENSION_API_VERSION` 加一。同一次发布里的多处变更合计加一。
+
+## 装载
+
+`loadExtensions(repoRoot)` 读 `extensions/package.json` 的 dependencies,逐个从
+`extensions/node_modules/<包>/` import 入口(`exports` → `module` → `main` → `index.js`),
+按 `kind` 校验默认导出:
+
+| kind | 默认导出 | 命名空间 | 控制台页 |
+|---|---|---|---|
+| `world` | `WorldDefinition`(`id` / `label` / `defaults()` / `create()`) | 与内建 World 共用 | `world:<id>` |
+| `provider` | `ProviderModule`(`id` / `title` / `reasoningTiers` / `serviceTiers` / `create()`) | 与内建 provider 共用 | `llm:<id>` |
+| `bot` | `BotDefinition`(`id` / `defaults()` / `build()`) | 不得与仓内 `bots/` 目录同名 | `persona:<id>` |
+
+与内建 id 冲突的扩展不能加载;两个扩展 id 相同时只加载第一个。单个扩展失败不影响其他扩展,
+原因写入 `ExtensionRecord.reason`。
+
+bot 包不在这条循环里 import:`deployment.json` 的 `bot` 字段指向哪个包,启动器就先经
+`locateBotPackage()`(优先仓内 `bots/<名>/`,其次为 `extensions/` 下同名且 `kind: "bot"` 的包)与
+`importBotDefinition()` 导入该包,再作为 `activeBot` 交给 `loadExtensions()` 标记加载状态:
+同名记录记 loaded,其余 bot 包记 `idle`。`ExtensionSet.bot` 说明这份部署的 bot 来自扩展包,
+`createBot` 据此把已安装扩展包内的提示词模板设为只读,pnpm 安装的文件可能硬链接到 store。结果 `ExtensionSet` 里 `worlds` 由启动器接在仓内目录(`src/worlds/index.ts`)之后,整张表经
+`withWorlds()` 交给 bot 定义；它仅补充缺失的 World 配置段，已有段保持原值，新增段的 `enabled` 取决于 bot 是否声明该 World。`providers` 交给 `registerProviderModules()`，`consoleAssets` 交给控制台。
+
+新装或卸掉的包要重启进程:ESM 模块缓存不支持运行中换代码。
+
+## 扩展怎么 import 框架
+
+扩展写 `import { nowIso } from 'cortico/core/util.ts'`:`cortico/<路径>` 就是 `src/<路径>`。
+`runtime.ts` 用 `module.registerHooks` 把这个前缀映到框架源码,再交给链上下一个解析器,
+所以扩展与框架拿到同一份模块实例。fork 出去的子进程用 `childExecArgv()` 带上同一个钩子。
+
+浏览器侧(面板 bundle)对 `cortico/*` 只允许 `import type`;bundle 里要用的运行时值由包自带。
+
+## 控制台接口
+
+`ExtensionManager` 提供扩展页接口:`list()` 比较启动时的加载结果与当前安装状态
+(`loaded` / `failed` / `pending-restart` / `removed`),`search()` 按关键字查 npm registry,
+`install()` / `uninstall()` 经 `corepack pnpm add|remove --ignore-workspace` 改 `extensions/`。
+装卸串行。面板 bundle 的 URL 由服务端分配:`/assets/extensions/<包>/<版本>/<文件>`,只发
+manifest 里声明的那两个文件。

package/src/extensions/dry-mount.ts

@@ -0,0 +1,390 @@
+/**
+ * 在临时部署中检查扩展构造与声明接口，不调用 start()。
+ * World 使用默认配置、无密钥，检查 create、tools、envPromptVars、console 与工具名冲突；
+ * provider 使用测试端点 create，bot 使用测试部署 build。
+ * World 构造失败为错误；provider 仅在绑定端点时构造，测试条目不完整导致的失败记为警告。
+ * 临时文件位于 scratchDir，调用方负责创建与清理。
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CoreConfig, World } from '../core/types.ts';
+import { MODULE_LAMP_MAX } from '../core/types.ts';
+import type { LoadedConfig } from '../core/config.ts';
+import { CORE_DEFAULTS } from '../core/config.ts';
+import { RESERVED_FRAME_NAMES } from '../core/loop.ts';
+import { nullLogger } from '../core/util.ts';
+import type { Language } from '../core/language.ts';
+import type { BotDefinition } from '../bot.ts';
+import type { WorldContext, WorldDefinition, WorldSection } from '../world.ts';
+import type { ProviderModule } from '../providers/base.ts';
+
+export interface DryMountReport {
+  ok: string[];
+  warnings: string[];
+  failures: string[];
+}
+
+export interface DryMountOptions {
+  /** 假部署与假端点目录的根。 */
+  scratchDir: string;
+  /** 扩展包目录;bot 的 `packageDir` 与 World 的 `packageDir` 都指它。缺省用假部署目录。 */
+  packageDir?: string;
+  repoRoot?: string;
+  language?: Language;
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/** 面板 id 的形状:控制台一页内的局部 id。 */
+const PANEL_ID = /^[a-z0-9-]+$/;
+/** 工具名带前缀:`<短名>_` 起头。 */
+const TOOL_PREFIX = /^[a-z0-9]+_/;
+
+function deploymentDirs(opts: DryMountOptions): { botDir: string; dataDir: string; memoryDir: string } {
+  const botDir = join(opts.scratchDir, 'deployment');
+  const dataDir = join(botDir, 'data');
+  const memoryDir = join(botDir, 'memory');
+  mkdirSync(dataDir, { recursive: true });
+  mkdirSync(memoryDir, { recursive: true });
+  return { botDir, dataDir, memoryDir };
+}
+
+/** 装配层给 `create()` 的上下文的假件:默认配置、没有密钥、写回都是空操作。 */
+export function fakeWorldContext<S extends WorldSection>(def: WorldDefinition<S>, opts: DryMountOptions): WorldContext<S> {
+  const cfg = def.defaults();
+  const { botDir, dataDir } = deploymentDirs(opts);
+  return {
+    id: def.id,
+    cfg,
+    timezone: CORE_DEFAULTS.timezone,
+    botName: CORE_DEFAULTS.displayName,
+    botDir,
+    packageDir: opts.packageDir ?? botDir,
+    dataDir,
+    repoRoot: opts.repoRoot ?? botDir,
+    secret: () => '',
+    storeSecret: () => {},
+    persist: (patch) => { Object.assign(cfg as object, patch); },
+    restart: async () => {},
+  };
+}
+
+/**
+ * 收集工具名称及所属定义，用于冲突检查；无法构造的定义列入 skipped，
+ * 调用方应说明冲突检查未覆盖这些定义。
+ */
+export function collectToolNames(
+  defs: readonly WorldDefinition<WorldSection>[],
+  opts: DryMountOptions,
+): { taken: Map<string, string>; skipped: string[] } {
+  const taken = new Map<string, string>();
+  const skipped: string[] = [];
+  for (const def of defs) {
+    try {
+      for (const tool of def.create(fakeWorldContext(def, opts)).tools()) taken.set(tool.name, def.label);
+    } catch (error) {
+      skipped.push(`${def.label}: ${message(error)}`);
+    }
+  }
+  return { taken, skipped };
+}
+
+export interface WorldDryMountOptions extends DryMountOptions {
+  /** manifest 声明了浏览器端产物;声明了面板却没有产物只是警告。 */
+  hasConsoleClient?: boolean;
+  /** 已被别的 World 占用的工具名 → 占用者。 */
+  takenToolNames?: ReadonlyMap<string, string>;
+}
+
+export async function dryMountWorld(def: WorldDefinition<WorldSection>, opts: WorldDryMountOptions): Promise<DryMountReport> {
+  const report: DryMountReport = { ok: [], warnings: [], failures: [] };
+  const { ok, warnings, failures } = report;
+
+  let defaults: unknown;
+  try {
+    defaults = def.defaults();
+  } catch (error) {
+    failures.push(`defaults() 抛错: ${message(error)}`);
+    return report;
+  }
+  if (!isPlainObject(defaults)) {
+    failures.push('defaults() 没有返回对象:它是 worlds.<id> 段的默认值。');
+    return report;
+  }
+  if (defaults.enabled !== false) {
+    warnings.push('defaults().enabled 不是 false:启用与否由 bot 的 declares 与部署决定,定义里恒为 false。');
+  }
+  ok.push('defaults() 返回配置段。');
+
+  let world: World;
+  try {
+    world = def.create(fakeWorldContext(def, opts));
+  } catch (error) {
+    failures.push(`create() 在默认配置、无密钥下抛错: ${message(error)}。装配层会构造所有可用定义，默认配置下也必须能完成构造。`);
+    return report;
+  }
+  if (world.id !== def.id) {
+    failures.push(`实例的 id「${world.id}」与定义的 id「${def.id}」不同:装配层按定义找槽位,Core 按实例归属工具与事件,两边会对不上。`);
+  } else {
+    ok.push(`create() 返回 World 实例,id = ${world.id}。`);
+  }
+
+  let tools: ReturnType<World['tools']>;
+  try {
+    tools = world.tools();
+  } catch (error) {
+    failures.push(`tools() 抛错: ${message(error)}`);
+    return report;
+  }
+  if (!Array.isArray(tools)) {
+    failures.push('tools() 没有返回数组。');
+    return report;
+  }
+  const seen = new Set<string>();
+  for (const tool of tools) {
+    const name = tool?.name;
+    if (typeof name !== 'string' || name === '') {
+      failures.push('有一个工具没有 name。');
+      continue;
+    }
+    if (seen.has(name)) failures.push(`工具名重复: ${name}。`);
+    seen.add(name);
+    if (RESERVED_FRAME_NAMES.has(name)) failures.push(`工具名「${name}」是 Core 的保留帧名,装配层拒绝挂载。`);
+    const owner = opts.takenToolNames?.get(name);
+    if (owner) failures.push(`工具名「${name}」与 ${owner} 撞名,装配层拒绝挂载。`);
+    if (!isPlainObject(tool.parameters)) failures.push(`工具「${name}」的 parameters 不是对象:它是发给模型的 JSON Schema。`);
+    if (typeof tool.handler !== 'function') failures.push(`工具「${name}」没有 handler。`);
+    if (!Array.isArray(tool.tags)) failures.push(`工具「${name}」没有 tags 数组:空数组表示明确不分类,缺席不行。`);
+    else if (tool.tags.length === 0) warnings.push(`工具「${name}」的 tags 为空，按标签选择工具时不会匹配；挂载时记录警告。`);
+    if (!TOOL_PREFIX.test(name)) warnings.push(`工具名「${name}」没有前缀:惯例是 <短名>_<动词短语>,工具名在整个 bot 里唯一。`);
+  }
+  if (!failures.length) ok.push(tools.length ? `tools(): ${tools.map((t) => t.name).join(', ')}` : 'tools(): 没有工具。');
+
+  try {
+    const vars = await world.envPromptVars();
+    if (vars === null) ok.push('envPromptVars() 返回 null:这个 World 的段不进前缀。');
+    else if (isPlainObject(vars)) ok.push(`envPromptVars(): ${Object.keys(vars).length} 个占位符值。`);
+    else failures.push('envPromptVars() 要返回对象或 null。');
+  } catch (error) {
+    failures.push(`envPromptVars() 抛错: ${message(error)}`);
+  }
+
+  if (typeof world.console === 'function') {
+    try {
+      const decl = world.console(opts.language ?? 'zh');
+      const panels = decl.panels ?? [];
+      const panelIds = new Set<string>();
+      for (const panel of panels) {
+        if (!PANEL_ID.test(panel.id)) failures.push(`面板 id「${panel.id}」不合形状:控制台一页内的局部 id,只用 [a-z0-9-]。`);
+        if (panelIds.has(panel.id)) failures.push(`面板 id 重复: ${panel.id}。`);
+        panelIds.add(panel.id);
+      }
+      if (panels.length && !opts.hasConsoleClient) {
+        warnings.push(`console() 声明了 ${panels.length} 个面板，未声明 cortico.consoleClient；使用自定义面板时需提供浏览器产物。`);
+      }
+      if ((decl.lamps?.length ?? 0) > MODULE_LAMP_MAX) {
+        warnings.push(`console().lamps 有 ${decl.lamps?.length} 颗,控制台最多画 ${MODULE_LAMP_MAX} 颗。`);
+      }
+      for (const group of decl.config ?? []) {
+        if (group.owner !== `world:${def.id}`) warnings.push(`配置组「${group.id}」的 owner 是「${group.owner}」,World 的配置组 owner 应为 world:${def.id}。`);
+      }
+      const keys = new Set<string>();
+      for (const doc of decl.promptDocs ?? []) {
+        if (keys.has(doc.key)) failures.push(`promptDocs key 重复: ${doc.key}。`);
+        keys.add(doc.key);
+        if (doc.role === 'envPrompt' && !existsSync(doc.path)) {
+          warnings.push(`环境提示词模板 ${doc.path} 不在:这个 World 的段会是空的。`);
+        }
+      }
+      ok.push(`console(): ${panels.length} 个面板,${decl.config?.length ?? 0} 个配置组,${decl.promptDocs?.length ?? 0} 份提示词文档。`);
+    } catch (error) {
+      failures.push(`console() 抛错: ${message(error)}`);
+    }
+  } else {
+    ok.push('没有 console():控制台按通用信息显示。');
+  }
+  return report;
+}
+
+export interface ProviderDryMountOptions extends DryMountOptions {
+  hasConsoleClient?: boolean;
+}
+
+export function dryMountProvider(mod: ProviderModule, opts: ProviderDryMountOptions): DryMountReport {
+  const report: DryMountReport = { ok: [], warnings: [], failures: [] };
+  const { ok, warnings, failures } = report;
+  const language = opts.language ?? 'zh';
+
+  for (const [field, tiers] of [['reasoningTiers', mod.reasoningTiers], ['serviceTiers', mod.serviceTiers]] as const) {
+    for (const tier of tiers) {
+      if (typeof tier?.id !== 'string' || typeof tier.label !== 'string') {
+        failures.push(`${field} 里有一项缺 id 或 label。`);
+        break;
+      }
+    }
+  }
+  if (!failures.length) ok.push(`档位表: ${mod.reasoningTiers.length} 档推理(空表 = 开放),${mod.serviceTiers.length} 档服务。`);
+
+  const raw = { kind: mod.id, baseUrl: mod.defaultBaseUrl ?? mod.baseUrlSuggestions?.[0] ?? 'http://127.0.0.1:0' };
+  let entry = raw;
+  try {
+    entry = mod.normalize?.(structuredClone(raw)) ?? raw;
+  } catch (error) {
+    failures.push(`normalize() 抛错: ${message(error)}`);
+    return report;
+  }
+
+  const stateDir = join(opts.scratchDir, 'providers', 'check');
+  mkdirSync(stateDir, { recursive: true });
+  const resources = new Map<string, unknown>();
+  const host = {
+    stateDir,
+    repoRoot: opts.repoRoot ?? opts.scratchDir,
+    resource: <T>(key: string, create: () => T): T => {
+      if (!resources.has(key)) resources.set(key, create());
+      return resources.get(key) as T;
+    },
+    currentEntry: () => entry,
+    secret: () => '',
+    readBlob: () => null,
+    keepThinking: () => false,
+    log: nullLogger(),
+  };
+  try {
+    const instance = mod.create('check', entry, host);
+    if (typeof instance?.client?.respond !== 'function') {
+      failures.push('create() 返回的实例没有 client.respond():Core 只经它调模型。');
+    } else {
+      ok.push('create() 返回实例,client.respond() 在。');
+    }
+  } catch (error) {
+    warnings.push(`create() 在假端点条目(只有 kind 与 baseUrl)下抛错: ${message(error)}。真实端点条目可能不同,这一项不算失败。`);
+  }
+
+  if (mod.config) {
+    try {
+      const groups = mod.config('check', entry, language);
+      if (!Array.isArray(groups)) failures.push('config() 没有返回数组。');
+      else {
+        for (const group of groups) {
+          if (group.owner !== `provider:${mod.id}`) warnings.push(`配置组「${group.id}」的 owner 是「${group.owner}」,provider 的配置组 owner 应为 provider:${mod.id}。`);
+        }
+        ok.push(`config(): ${groups.length} 个配置组。`);
+      }
+    } catch (error) {
+      failures.push(`config() 抛错: ${message(error)}`);
+    }
+  }
+
+  if (mod.localize) {
+    try {
+      mod.localize(language);
+      ok.push("localize() 调用成功。");
+    } catch (error) {
+      failures.push(`localize() 抛错: ${message(error)}`);
+    }
+  }
+
+  if (mod.console) {
+    try {
+      const contribution = mod.console({
+        language,
+        entries: () => [],
+        instance: () => { throw new Error("构造检查不提供实际端点实例"); },
+        save: () => {},
+      });
+      const panels = contribution.panels ?? [];
+      for (const panel of panels) {
+        if (!PANEL_ID.test(panel.id)) failures.push(`面板 id「${panel.id}」不合形状:只用 [a-z0-9-]。`);
+      }
+      if (panels.length && !opts.hasConsoleClient) {
+        warnings.push(`console() 声明了 ${panels.length} 个面板，未声明 cortico.consoleClient；使用自定义面板时需提供浏览器产物。`);
+      }
+      ok.push(`console(): ${panels.length} 个面板。`);
+    } catch (error) {
+      failures.push(`console() 抛错: ${message(error)}`);
+    }
+  }
+  return report;
+}
+
+export interface BotDryMountOptions extends DryMountOptions {
+  packageDir: string;
+}
+
+export function dryMountBot(def: BotDefinition<CoreConfig>, opts: BotDryMountOptions): DryMountReport {
+  const report: DryMountReport = { ok: [], warnings: [], failures: [] };
+  const { ok, warnings, failures } = report;
+
+  let config: unknown;
+  try {
+    config = def.defaults();
+  } catch (error) {
+    failures.push(`defaults() 抛错: ${message(error)}`);
+    return report;
+  }
+  if (!isPlainObject(config)) {
+    failures.push("defaults() 必须返回配置对象。");
+    return report;
+  }
+  (config as { worlds?: unknown }).worlds ??= {};
+  ok.push('defaults() 返回对象。');
+
+  for (const decl of def.declares ?? []) {
+    const shaped = typeof decl === 'string' ? decl !== '' : isPlainObject(decl) && typeof decl.id === 'string' && typeof decl.label === 'string';
+    if (!shaped) failures.push(`declares 里有一项不合形状: ${JSON.stringify(decl)}(World id 字符串,或 { id, label, reason? })。`);
+  }
+  if (def.declares?.length) ok.push(`declares: ${def.declares.map((d) => (typeof d === 'string' ? d : d.id)).join(', ')}`);
+
+  const { botDir, dataDir, memoryDir } = deploymentDirs(opts);
+  const loaded: LoadedConfig<CoreConfig> = {
+    config: config as unknown as CoreConfig,
+    secret: () => '',
+    rootDir: botDir,
+    memoryDir,
+    dataDir,
+    packageDir: opts.packageDir,
+    providersDir: join(botDir, 'providers'),
+    repoRoot: opts.repoRoot ?? botDir,
+  };
+  let parts: ReturnType<typeof def.build>;
+  try {
+    parts = def.build(loaded, []);
+  } catch (error) {
+    failures.push(`build() 在假部署(默认配置、空 Memory、无密钥)下抛错: ${message(error)}。build() 必须能在该配置下完成构造。`);
+    return report;
+  }
+  const persona = parts?.persona as unknown;
+  if (!isPlainObject(persona)) {
+    failures.push('build() 没有返回 persona。');
+    return report;
+  }
+  for (const method of ['systemSegments', 'attach', 'declareSessions'] as const) {
+    if (typeof persona[method] !== 'function') failures.push(`persona 缺 ${method}():Persona 契约的必填项。`);
+  }
+  if (typeof persona.memoryDir !== 'string') failures.push('persona.memoryDir 不是字符串:Memory 目录的绝对路径。');
+  const blobs = persona.blobs as Record<string, unknown> | undefined;
+  if (!isPlainObject(blobs) || ['put', 'get', 'list'].some((m) => typeof blobs[m] !== 'function')) {
+    failures.push('persona.blobs 不是 BlobStore(put / get / list):mem: 句柄没有后端。');
+  }
+  if (!failures.length) ok.push('build() 返回 Persona,契约必填项都在。');
+  if (typeof def.memoryName !== 'string' || def.memoryName === '') {
+    warnings.push('BotDefinition 没有 memoryName:Memory 页标题回落到 persona.memory 的类名,再缺省是「Memory」。');
+  }
+
+  const prebuilt = parts.worlds ?? [];
+  const ids = new Set<string>();
+  for (const world of prebuilt) {
+    if (ids.has(world.id)) failures.push(`预建 World id 重复: ${world.id}。`);
+    ids.add(world.id);
+  }
+  if (prebuilt.length) ok.push(`预建 World: ${[...ids].join(', ')}（预建实例重启时复用原对象）。`);
+
+  for (const group of parts.console?.configGroups ?? []) {
+    if (group.owner !== 'persona') warnings.push(`配置组「${group.id}」的 owner 是「${group.owner}」,Persona 的配置组 owner 应为 persona。`);
+  }
+  return report;
+}