cortico 0.1.1 → 0.1.3

package/src/core/loop.ts

@@ -245,12 +245,13 @@ export class MainLoop {
   /** 截断与前缀重载共用的维护串行链，避免两个 session.reset 互相覆盖。 */
   private maintenanceChain: Promise<void> = Promise.resolve();
   private prefixReloadPromise: Promise<void> | null = null;
-  /** 在一轮处理中请求重载时，等自然回合边界再释放。 */
-  private releasePrefixReload: (() => void) | null = null;
+  private clearSessionPromise: Promise<void> | null = null;
+  /** 在一轮处理中请求的前缀重载与清空，等自然回合边界再释放。 */
+  private releaseAtBoundary: Array<() => void> = [];
   /** 当前正在处理一个事件批；手动交接必须等到该批自然结束，不能重置半轮session。 */
   private processingBatch = false;
   private handoffRequested = false;
-  /** onDelivery 同步执行期间，injectInternal 的即时项加入当前批，不经过总线。 */
+  /** onDelivery 执行期间（含其 Promise 完成前），injectInternal 的即时项加入当前批，不经过总线。 */
   private deliveryCollector: EventEnvelope[] | null = null;
   /** 已投递但前面仍有外部缺口的游标；水位只越过连续前缀。 */
   private readonly deliveredCursors = new Set<number>();
@@ -483,7 +484,7 @@ export class MainLoop {
   /**
    * 将一批事件写入主 session。即时事件在前，候选生成内容与延迟渲染内容在后。
    * 候选按 source、origin 和处理函数分组，再按来源项在批次中的顺序生成正文。
-   * 正文归档后调用 onDelivery；同步注入的内部项追加到内部行末尾、外部正文之前。
+   * 正文归档后调用并等待 onDelivery；钩子完成前注入的内部项追加到内部行末尾、外部正文之前。
    * 内部行合成一条 user 消息；外部正文按 eventDelivery 进入合成工具回执或同一条 user 消息。
    */
   private async deliverBatch(batch: WakeItem[], generation: number): Promise<boolean> {
@@ -536,11 +537,13 @@ export class MainLoop {
     }
     if (!this.active(generation)) return false;
     if (delivered.length > 0) {
-      // 仅捕获同步钩子内的即时注入；退出钩子后恢复总线投递。
+      // 捕获钩子完成前的即时注入；钩子完成后恢复总线投递。
       const injected: EventEnvelope[] = [];
       this.deliveryCollector = injected;
       try {
-        persona.onDelivery?.({ events: [...delivered] });
+        // 同步钩子不经过 await，收集范围仍只是钩子本身的执行期。
+        const pending = persona.onDelivery?.({ events: [...delivered] });
+        if (pending) await pending;
       } catch (e) {
         log.warn('onDelivery钩子异常', { err: e });
       } finally {
@@ -722,13 +725,15 @@ export class MainLoop {
     const latest = store.latestCursor();
     for (let c = top + 1; c <= latest; c++) {
       const next = store.get(c);
-      if (!next) break;
-      // 未处理的 archive-only 项必须保留在水位之后，重启才会补投。
-      // 已处理项由 settledArchives 标识。
-      const skippable = next.origin === 'internal'
-        || (next.contextDelivery === 'archive-only' && this.settledArchives.has(c));
-      // 集合记录存储位置；装载期重排保证 next.cursor === c。
-      if (!skippable && !this.deliveredCursors.has(c)) break;
+      // 清空分片或跳过损坏行留下的空位没有可投递内容，不阻止水位推进。
+      if (next) {
+        // 未处理的 archive-only 项必须保留在水位之后，重启才会补投。
+        // 已处理项由 settledArchives 标识。
+        const skippable = next.origin === 'internal'
+          || (next.contextDelivery === 'archive-only' && this.settledArchives.has(c));
+        // 集合记录存储位置；装载期重排保证 next.cursor === c。
+        if (!skippable && !this.deliveredCursors.has(c)) break;
+      }
       this.deliveredCursors.delete(c);
       this.settledArchives.delete(c);
       top = c;
@@ -904,8 +909,8 @@ export class MainLoop {
         } finally {
           this.processingBatch = false;
         }
-        // 异常退出由 stop 释放排队请求；只有正常批次边界执行重载。
-        await this.flushRequestedPrefixReload(generation);
+        // 异常退出由 stop 释放排队请求；只有正常批次边界执行重载与清空。
+        await this.flushBoundaryMaintenance();
       }
     } finally {
       this.stop();
@@ -933,7 +938,11 @@ export class MainLoop {
     for (let round = 1; ; round++) {
       if (!this.active(generation)) return;
       this.roundsLastBatch = round;
-      const spec = this.d.spec();
+      let spec: ModelSpec;
+      try { spec = this.d.spec(); } catch (error) {
+        log.warn('模型配置不可用', { error: String(error) });
+        return;
+      }
       // 后续轮输入超限时结束本批，由批末检查执行交接。
       // 首轮仍处理本批新投递的事件；上一批的容量检查已在批末执行。
       if (round > 1) {
@@ -1425,9 +1434,25 @@ export class MainLoop {
     return rebuildTail(paired, budget, estimate);
   }
 
-  /** 清空主 session，重建 system 前缀并调用 Persona 开场钩子；事件库保留。 */
-  async clearSession(): Promise<void> {
+  /**
+   * 清空主 session，重建 system 前缀并调用 Persona 开场钩子；事件库保留。
+   * 正在处理批次时等到该批自然结束，不重置半轮 session；并发请求复用同一 Promise。
+   */
+  clearSession(): Promise<void> {
     const generation = this.generation;
+    if (!this.active(generation)) return Promise.resolve();
+    if (this.clearSessionPromise) return this.clearSessionPromise;
+    let tracked: Promise<void>;
+    tracked = this.safeBoundary()
+      .then(() => this.enqueueMaintenance(() => this.performClearSession(generation), generation))
+      .finally(() => {
+        if (this.clearSessionPromise === tracked) this.clearSessionPromise = null;
+      });
+    this.clearSessionPromise = tracked;
+    return tracked;
+  }
+
+  private async performClearSession(generation: number): Promise<void> {
     if (!this.active(generation)) return;
     const { session, log } = this.d;
     const sysMsg = await this.buildSystem();
@@ -1447,11 +1472,8 @@ export class MainLoop {
     const generation = this.generation;
     if (!this.active(generation)) return Promise.resolve();
     if (this.prefixReloadPromise) return this.prefixReloadPromise;
-    const safeBoundary = this.processingBatch
-      ? new Promise<void>((resolve) => { this.releasePrefixReload = resolve; })
-      : Promise.resolve();
     let tracked: Promise<void>;
-    tracked = safeBoundary
+    tracked = this.safeBoundary()
       .then(() => this.enqueueMaintenance(() => this.performSystemPrefixReload(generation), generation))
       .finally(() => {
         if (this.prefixReloadPromise === tracked) this.prefixReloadPromise = null;
@@ -1460,12 +1482,22 @@ export class MainLoop {
     return tracked;
   }
 
-  private async flushRequestedPrefixReload(_generation: number): Promise<boolean> {
-    const release = this.releasePrefixReload;
-    if (!release) return false;
-    this.releasePrefixReload = null;
-    release();
-    await this.prefixReloadPromise;
+  /** 空闲时立即；正在处理批次时等 run() 在批末释放，或 stop() 释放。 */
+  private safeBoundary(): Promise<void> {
+    if (!this.processingBatch) return Promise.resolve();
+    return new Promise<void>((resolve) => { this.releaseAtBoundary.push(resolve); });
+  }
+
+  private releaseBoundary(): void {
+    const waiting = this.releaseAtBoundary;
+    this.releaseAtBoundary = [];
+    for (const release of waiting) release();
+  }
+
+  private async flushBoundaryMaintenance(): Promise<boolean> {
+    if (this.releaseAtBoundary.length === 0) return false;
+    this.releaseBoundary();
+    await Promise.all([this.prefixReloadPromise, this.clearSessionPromise]);
     return true;
   }
 
@@ -1633,7 +1665,7 @@ export class MainLoop {
     return this.stallAt.filter((t) => t >= from).length;
   }
 
-  /** 注入 Persona 提供的内部文本。onDelivery 同步执行期间加入当前批，其余时刻进入总线。 */
+  /** 注入 Persona 提供的内部文本。onDelivery 完成前加入当前批，其余时刻进入总线。 */
   injectInternal(text: string, kind = 'notice'): void {
     if (!this.activeNow()) return;
     const item = this.internalItem('persona', kind, text);
@@ -1721,9 +1753,7 @@ export class MainLoop {
     this.backoffWake?.();
     if (!this.shutdown.signal.aborted) this.shutdown.abort(new Error('core 正在关机'));
     this.handoffRequested = false;
-    const releasePrefixReload = this.releasePrefixReload;
-    this.releasePrefixReload = null;
-    releasePrefixReload?.();
+    this.releaseBoundary();
     this.stopFn?.();
     const round = this.currentRound;
     if (round && !round.controller.signal.aborted) {

package/src/core/secrets.ts

@@ -3,16 +3,14 @@ import { existsSync } from 'node:fs';
 import { readTextFile } from './util.ts';
 
 /**
- * 每次优先读取非空进程环境变量；否则使用首次读取后缓存的文件内容，缺失返回空串。
+ * 每次优先读取非空进程环境变量；否则现读文件，缺失返回空串。
  * 文件值读取到首个空白字符，不解析引号。
  */
 export function secretReader(file: string): (name: string) => string {
-  let text: string | null = null;
   return (name: string): string => {
     const fromEnv = process.env[name];
     if (fromEnv) return fromEnv;
-    if (text === null) text = existsSync(file) ? readTextFile(file) : '';
-    const m = new RegExp(`^\\s*${name}\\s*=\\s*(\\S+)`, 'm').exec(text);
+    const m = new RegExp(`^\\s*${name}\\s*=\\s*(\\S+)`, 'm').exec(existsSync(file) ? readTextFile(file) : '');
     return m ? m[1] : '';
   };
 }

package/src/core/session.ts

@@ -1,7 +1,7 @@
 /** Session context is append-only between lifecycle resets. */
 import { join } from 'node:path';
 import type { ContextRecord } from '../protocol/open-responses/context.ts';
-import { ContextLog } from '../protocol/open-responses/context-log.ts';
+import { ContextLog, type ContextLoadRepair } from '../protocol/open-responses/context-log.ts';
 import { estimateMessagesTokens } from './util.ts';
 
 
@@ -38,7 +38,8 @@ export class SessionLog {
     }
   }
 
-  load(): void { this.context.load(); }
+  /** 返回对未写完末行的修复；其他损坏行抛错。 */
+  load(): ContextLoadRepair | null { return this.context.load(); }
 
   /** 整体替换：先写临时文件，再 rename 覆盖目标文件。 */
   reset(messages: readonly ContextRecord[]): void {

package/src/core/timers.ts

@@ -2,7 +2,7 @@
  * 通用持久定时器:到点回调持有方、跨重启恢复。载荷不透明——
  * 闹钟的备注、阻断、关键词这些语义归持有它的Persona。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { Logger, TimerEntry, TimersApi } from './types.ts';
 import { nullLogger, shortId } from './util.ts';
@@ -47,7 +47,8 @@ export class TimerStore implements TimersApi {
     const entry: TimerEntry = { id: shortId('wake_'), atIso, payload };
     this.entries.push(entry);
     this.save();
-    if (this.started) this.arm(entry);
+    // 已到期的也等 set 返回后再回调,持有方先拿到 id。
+    if (this.started) this.arm(entry, 'next-tick');
     return { ok: true, id: entry.id };
   }
 
@@ -76,9 +77,10 @@ export class TimerStore implements TimersApi {
     return n;
   }
 
-  private arm(entry: TimerEntry): void {
+  /** 已到期的条目按 whenDue 立即回调或下一个宏任务回调;start() 用前者。 */
+  private arm(entry: TimerEntry, whenDue: 'now' | 'next-tick' = 'now'): void {
     const delay = Date.parse(entry.atIso) - Date.now();
-    if (delay <= 0) {
+    if (delay <= 0 && whenDue === 'now') {
       this.fire(entry.id);
       return;
     }
@@ -88,7 +90,7 @@ export class TimerStore implements TimersApi {
       // 超长延迟按 MAX_TIMEOUT 分段重新 arm。
       this.timers.set(entry.id, setTimeout(() => this.arm(entry), MAX_TIMEOUT));
     } else {
-      this.timers.set(entry.id, setTimeout(() => this.fire(entry.id), delay));
+      this.timers.set(entry.id, setTimeout(() => this.fire(entry.id), Math.max(0, delay)));
     }
   }
 
@@ -123,7 +125,7 @@ export class TimerStore implements TimersApi {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const tmp = this.file + '.tmp';
     writeFileSync(tmp, JSON.stringify(this.entries, null, 2), 'utf8');
-    if (existsSync(this.file)) rmSync(this.file);
+    // 通过 rename 原子覆盖，不先删除，避免崩溃后定时器全部丢失。
     renameSync(tmp, this.file);
   }
 }

package/src/core/types.ts

@@ -516,6 +516,7 @@ export interface TimerEntry {
 
 /** 跨重启恢复的定时器。 */
 export interface TimersApi {
+  /** 到期回调在 set 返回之后才发生,包括 atIso 已经过去的条目。 */
   set(atIso: string, payload?: Record<string, unknown>): { ok: true; id: string } | { ok: false; error: string };
   cancel(id: string): boolean;
   list(): ReadonlyArray<TimerEntry>;
@@ -550,6 +551,7 @@ export interface DeliveryGateApi {
 /** 运行时查询当前模型的名称、MIME 支持和上下文窗口；配置热改后读取新值。 */
 export interface ModelFacts {
   model(): string;
+  /** 未选端点或端点未选模型时返回 false；activeProvider 指向不存在的端点时抛错。 */
   accepts(mime: string): boolean;
   /** provider 探测值与手动配置取较小者，单位 token；两者均未知时返回 undefined。 */
   contextWindow(): number | undefined;
@@ -833,8 +835,11 @@ export interface World {
    * 语言不缓存，不影响发给模型的文本；未实现时仅显示通用信息。
    */
   console?(language?: Language): WorldConsoleDecl;
-  /** 主 session 的输出流接收器；装配层合并已挂载 World 的接收器，随挂载变化更新。 */
-  outputTap?(): OutputTap;
+  /**
+   * 主 session 的输出流接收器；装配层合并已挂载 World 的接收器，随挂载变化更新。
+   * 这一刻没有接收器（未连接、模式关着）时返回 undefined，合并侧跳过。
+   */
+  outputTap?(): OutputTap | undefined;
   /** 挂载时接收宿主并开始连接平台、推送事件。 */
   start(host: WorldHost): Promise<void>;
   stop(): Promise<void>;
@@ -906,9 +911,11 @@ export interface Persona {
   onOpening?(ctx: { reason: SessionOpeningReason }): void;
   /**
    * 一批事件已渲染并分配游标、尚未进入上下文时调用；events 按投递序包含内部和外部事件。
-   * injectInternal 在此钩子内注入的内容加入当前批，排在已有内部行之后、外部正文之前；钩子阻塞投递。
+   * 返回 Promise 时 Core 等它完成再投递，不设期限：钩子不完成，主循环不前进，钩子自己发起的
+   * 外部调用由 Persona 负责超时。完成前 Persona 的所有 injectInternal 都加入当前批，排在已有
+   * 内部行之后、外部正文之前。钩子抛错或拒绝时 Core 记录 warn，带着已注入的内容照常投递。
    */
-  onDelivery?(ctx: { events: EventEnvelope[] }): void;
+  onDelivery?(ctx: { events: EventEnvelope[] }): void | Promise<void>;
   /**
    * 一批事件处理结束时调用；Persona 可查询 sessionInfo 并决定是否请求交接。
    * Core 在超过 hardTokens 时强制交接。
@@ -1120,6 +1127,18 @@ export interface CoreConfig {
   };
   web: {
     port: number;
+    /** 控制台监听地址；缺省 127.0.0.1。`0.0.0.0` 或 `::` 监听所有网卡。 */
+    host?: string;
+    /**
+     * 回环名与监听地址之外还接受的 Host 名（域名、反向代理对外的名字），同时放行以它为
+     * Origin 的写请求与 WebSocket；缺省为空。
+     */
+    allowedHosts?: string[];
+    /**
+     * 控制台访问密码；缺省或空串时不要求登录。密钥 `CORTICO_WEB_PASSWORD`（进程环境或部署
+     * `.env`）非空时优先于此键。
+     */
+    password?: string;
     /** 控制台配色方案 id；浏览器没有保存过选择时用它，认不出的 id 落到框架默认方案。 */
     theme: string;
   };

package/src/core/util.ts

@@ -385,3 +385,18 @@ export function readTextFile(file: string): string {
   }
   return bytes.toString('utf8');
 }
+
+/** 键名像凭据的值抹成 `***`;数组与嵌套对象逐层走。导出记录与配置副本前过一遍。 */
+const SECRET_KEY = /secret|token|key|password/i;
+
+export function redactSecrets(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redactSecrets);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = SECRET_KEY.test(k) ? '***' : redactSecrets(v);
+    }
+    return out;
+  }
+  return value;
+}

package/src/deploy.ts

@@ -3,11 +3,12 @@
  * 部署文件中的 providers 字段不参与合并。Core、Persona 与 World 的默认值由各自所有者提供。
  * 运行时共享合并后的配置对象，控制台和调参工具原位更新。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+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';
@@ -90,7 +91,7 @@ function globalProviders(providersDir: string): Record<string, LLMProviderEntry>
     const file = resolve(providersDir, name, 'config.json');
     if (!existsSync(file)) continue;
     try {
-      table[name] = JSON.parse(readFileSync(file, 'utf8')) as LLMProviderEntry;
+      table[name] = JSON.parse(readTextFile(file)) as LLMProviderEntry;
     } catch (err) {
       throw new Error(`${file} 解析失败:${err instanceof Error ? err.message : String(err)}`);
     }
@@ -110,7 +111,7 @@ function packageWorldOverrides(pkgDir: string): Record<string, unknown> {
     const file = resolve(ioDir, id, 'config.json');
     if (!existsSync(file)) continue;
     try {
-      worlds[id] = JSON.parse(readFileSync(file, 'utf8'));
+      worlds[id] = JSON.parse(readTextFile(file));
     } catch (err) {
       throw new Error(`${file} 解析失败:${err instanceof Error ? err.message : String(err)}`);
     }
@@ -137,7 +138,7 @@ export function loadDeployment<C extends CoreConfig>(
   const providers = resolve(providersDir);
   const cfgPath = resolve(dir, 'config.json');
   const raw: Partial<C> & Record<string, unknown> = existsSync(cfgPath)
-    ? (JSON.parse(readFileSync(cfgPath, 'utf8')) as Partial<C> & Record<string, unknown>)
+    ? (JSON.parse(readTextFile(cfgPath)) as Partial<C> & Record<string, unknown>)
     : {};
   // 部署文件不能覆盖共享端点表。
   delete raw.providers;

package/src/extensions/README.md

@@ -19,7 +19,7 @@ World 调用 `create()` / `tools()` / `console()`,provider 调用 `create()`,bot
   "keywords": ["cortico-world"],          // npm 搜索按类关键字:cortico-world / cortico-provider / cortico-bot
   "cortico": {
     "kind": "world",                      // world | provider | bot
-    "api": 4,                             // 扩展契约版本,与 EXTENSION_API_VERSION 相等才加载
+    "api": 5,                             // 这一类的契约版本,与 EXTENSION_API_VERSIONS[kind] 相等才加载
     "consoleClient": "dist/console.js",   // 可选:预构建的面板 bundle,包内相对路径
     "consoleStyle": "dist/console.css"    // 可选:随 bundle 注入的样式
   }
@@ -27,9 +27,11 @@ World 调用 `create()` / `tools()` / `console()`,provider 调用 `create()`,bot
 ```
 
 `parseExtensionManifest(pkg)` 只做解析与校验,不碰文件系统;装载器与
-`pnpm check:extension <dir>` 共用它。`api` 与框架不等时不加载,扩展页说明哪一边旧。
-`WorldDefinition`、`ProviderModule`、`BotDefinition`(连同 `BotParts`、`Persona`、`LoadedConfig`)
-或 `ConsolePanelContext` 任一不兼容变更就把 `EXTENSION_API_VERSION` 加一。同一次发布里的多处变更合计加一。
+`pnpm check:extension <dir>` 共用它。`api` 与这一类的契约版本不等时不加载,扩展页说明哪一边旧。
+
+`EXTENSION_API_VERSIONS` 按 kind 各记一个版本:`WorldDefinition` 不兼容变更只加 world,
+`ProviderModule` 只加 provider,`BotDefinition`(连同 `BotParts`、`Persona`、`LoadedConfig`)只加 bot;
+`ConsolePanelContext` 与其余共用接口变更时三类一起加一。同一次发布里的多处变更合计加一。
 
 ## 装载
 

package/src/extensions/dry-mount.ts

@@ -1,16 +1,17 @@
 /**
  * 在临时部署中检查扩展构造与声明接口，不调用 start()。
- * World 使用默认配置、无密钥，检查 create、tools、envPromptVars、console 与工具名冲突；
- * provider 使用测试端点 create，bot 使用测试部署 build。
+ * 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 type { ConfigGroup, 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 { getByPath } from '../core/config-schema.ts';
 import { RESERVED_FRAME_NAMES } from '../core/loop.ts';
 import { nullLogger } from '../core/util.ts';
 import type { Language } from '../core/language.ts';
@@ -38,6 +39,25 @@ const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 
 const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 
+/**
+ * 声明过的每个配置路径都要落在 prefix 指的段内;给了 `defaults` 时还要在里面有对应项。
+ * 缺默认值时控制台照样渲染旋钮、也照样写回 config.json,而读到的是代码里另一处的兜底值。
+ * provider 的旋钮写进端点条目而不是 `defaults()`,所以只核对段。
+ */
+function configPathProblems(group: ConfigGroup, prefix: string, defaults?: Record<string, unknown>): string[] {
+  const problems: string[] = [];
+  for (const path of Object.keys(group.schema.properties ?? {})) {
+    if (!path.startsWith(prefix)) {
+      problems.push(`配置组「${group.id}」声明的「${path}」不在 ${prefix} 段里:写回按路径走,值会落到别人的段上。`);
+      continue;
+    }
+    if (defaults && getByPath(defaults, path.slice(prefix.length)) === undefined) {
+      problems.push(`配置组「${group.id}」声明的「${path}」在 defaults() 里没有对应项:旋钮能改、能写回 config.json,读到的仍是代码里的兜底值。`);
+    }
+  }
+  return problems;
+}
+
 /** 面板 id 的形状:控制台一页内的局部 id。 */
 const PANEL_ID = /^[a-z0-9-]+$/;
 /** 工具名带前缀:`<短名>_` 起头。 */
@@ -190,6 +210,7 @@ export async function dryMountWorld(def: WorldDefinition<WorldSection>, opts: Wo
       }
       for (const group of decl.config ?? []) {
         if (group.owner !== `world:${def.id}`) warnings.push(`配置组「${group.id}」的 owner 是「${group.owner}」,World 的配置组 owner 应为 world:${def.id}。`);
+        failures.push(...configPathProblems(group, `worlds.${def.id}.`, defaults));
       }
       const keys = new Set<string>();
       for (const doc of decl.promptDocs ?? []) {
@@ -213,6 +234,9 @@ export interface ProviderDryMountOptions extends DryMountOptions {
   hasConsoleClient?: boolean;
 }
 
+/** 假端点的名字;模块声明的配置路径按它组成 `providers.<端点名>.options.`。 */
+const PROBE_ENDPOINT = 'check';
+
 export function dryMountProvider(mod: ProviderModule, opts: ProviderDryMountOptions): DryMountReport {
   const report: DryMountReport = { ok: [], warnings: [], failures: [] };
   const { ok, warnings, failures } = report;
@@ -237,7 +261,7 @@ export function dryMountProvider(mod: ProviderModule, opts: ProviderDryMountOpti
     return report;
   }
 
-  const stateDir = join(opts.scratchDir, 'providers', 'check');
+  const stateDir = join(opts.scratchDir, 'providers', PROBE_ENDPOINT);
   mkdirSync(stateDir, { recursive: true });
   const resources = new Map<string, unknown>();
   const host = {
@@ -254,7 +278,7 @@ export function dryMountProvider(mod: ProviderModule, opts: ProviderDryMountOpti
     log: nullLogger(),
   };
   try {
-    const instance = mod.create('check', entry, host);
+    const instance = mod.create(PROBE_ENDPOINT, entry, host);
     if (typeof instance?.client?.respond !== 'function') {
       failures.push('create() 返回的实例没有 client.respond():Core 只经它调模型。');
     } else {
@@ -266,11 +290,14 @@ export function dryMountProvider(mod: ProviderModule, opts: ProviderDryMountOpti
 
   if (mod.config) {
     try {
-      const groups = mod.config('check', entry, language);
+      const groups = mod.config(PROBE_ENDPOINT, 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}。`);
+          // 写回的三道闸都只按 `providers.<端点名>.` 过滤:段外的路径改不动,段内 options 之外的
+          // 路径覆盖框架自己编辑的字段(baseUrl、secret、multimodal、spec)。两类都拦在这里。
+          failures.push(...configPathProblems(group, `providers.${PROBE_ENDPOINT}.options.`));
         }
         ok.push(`config(): ${groups.length} 个配置组。`);
       }
@@ -385,6 +412,7 @@ export function dryMountBot(def: BotDefinition<CoreConfig>, opts: BotDryMountOpt
 
   for (const group of parts.console?.configGroups ?? []) {
     if (group.owner !== 'persona') warnings.push(`配置组「${group.id}」的 owner 是「${group.owner}」,Persona 的配置组 owner 应为 persona。`);
+    failures.push(...configPathProblems(group, '', config));
   }
   return report;
 }

package/src/extensions/manifest.ts

@@ -1,18 +1,25 @@
 /**
  * 解析 package.json 的 cortico 扩展声明，不访问文件系统；装载器与 check:extension 共用。
- * kind 必须为 world、provider 或 bot；api 必须等于 EXTENSION_API_VERSION。
- * WorldDefinition、ProviderModule、BotDefinition 及其可达接口或 ConsolePanelContext
- * 发生不兼容变更时递增版本。
+ * kind 必须为 world、provider 或 bot；api 必须等于这一类的契约版本。
  * consoleClient 和 consoleStyle 是预构建产物的包内相对路径；服务端分配 URL。
  * 包必须使用 type=module，使扩展与框架通过同一 ESM 解析方式共享模块实例。
  */
 
-/** 扩展接口发生不兼容变更时递增。 */
-export const EXTENSION_API_VERSION = 4;
-
 export type ExtensionKind = 'world' | 'provider' | 'bot';
 export const EXTENSION_KINDS: readonly ExtensionKind[] = ['world', 'provider', 'bot'];
 
+/**
+ * 三类扩展各自的契约版本。一类的接口不兼容变更只递增这一类:
+ * world 看 `WorldDefinition`,provider 看 `ProviderModule`,bot 看 `BotDefinition`
+ * (连同 `BotParts`、`Persona`、`LoadedConfig`);`ConsolePanelContext` 与其余共用接口
+ * 变更时三类一起加一。同一次发布里的多处变更合计加一。
+ */
+export const EXTENSION_API_VERSIONS: Readonly<Record<ExtensionKind, number>> = {
+  world: 5,
+  provider: 5,
+  bot: 6,
+};
+
 /** npm 上按类发现用的关键字。 */
 export const EXTENSION_KEYWORDS: Readonly<Record<ExtensionKind, string>> = {
   world: 'cortico-world',
@@ -79,12 +86,15 @@ export function parseExtensionManifest(pkg: ExtensionPackageJson): ExtensionMani
   }
 
   const api = m.api;
+  // kind 认不出时不比版本:每一类的契约版本各走各的,不知道是哪一类就没有可比的数。
+  const expected = kindOk ? EXTENSION_API_VERSIONS[kind as ExtensionKind] : undefined;
   if (typeof api !== 'number' || !Number.isInteger(api) || api < 1) {
-    reasons.push(`cortico.api 必须是正整数(当前框架契约 v${EXTENSION_API_VERSION}),现在是 ${JSON.stringify(api)}。`);
-  } else if (api < EXTENSION_API_VERSION) {
-    reasons.push(`扩展按契约 v${api} 编写,本框架是 v${EXTENSION_API_VERSION}:扩展需要升级。`);
-  } else if (api > EXTENSION_API_VERSION) {
-    reasons.push(`扩展要求契约 v${api},本框架只到 v${EXTENSION_API_VERSION}:框架需要升级。`);
+    const note = expected === undefined ? '' : `(本框架的 ${kind} 契约是 v${expected})`;
+    reasons.push(`cortico.api 必须是正整数${note},现在是 ${JSON.stringify(api)}。`);
+  } else if (expected !== undefined && api < expected) {
+    reasons.push(`扩展按 ${kind} 契约 v${api} 编写,本框架的 ${kind} 契约是 v${expected}:扩展需要升级。`);
+  } else if (expected !== undefined && api > expected) {
+    reasons.push(`扩展要求 ${kind} 契约 v${api},本框架的 ${kind} 契约只到 v${expected}:框架需要升级。`);
   }
 
   const client = m.consoleClient;