cortico 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "A TypeScript framework for event-driven, long-running persona bots",
   "license": "MIT",

package/src/boot.ts

@@ -4,6 +4,7 @@
  */
 import { existsSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import type { CoreConfig, LLMProviderEntry } from './core/types.ts';
 
 export const RESTART_FLAG_FILE = '.restart-request';
 
@@ -62,3 +63,13 @@ export function consoleUrlOf(bound: string | null, port: number): string {
   const host = bound === null || listensOnEveryInterface(bound) ? '127.0.0.1' : bound.includes(':') ? `[${bound}]` : bound;
   return `http://${host}:${port}/`;
 }
+
+/** 空选择允许进入控制台完成配置；非空名称必须引用已有连接。 */
+export function providerAtBoot(config: Pick<CoreConfig, 'activeProvider' | 'providers'>): LLMProviderEntry | undefined {
+  if (!config.activeProvider) return undefined;
+  const entry = config.providers[config.activeProvider];
+  if (!entry) {
+    throw new Error(`activeProvider="${config.activeProvider}" 在 providers 段里不存在(现有: ${Object.keys(config.providers).join(' / ') || '无'})`);
+  }
+  return entry;
+}

package/src/core/README.md

@@ -34,6 +34,9 @@ Core 管理 session、事件流与模型调用的生命周期，包括事件投
 `sessionDecls`;`spawnFork`、`resolveBlob` / `internBlobs`、`setWorldVisible`、`activeSpec` /
 `activeProviderEntry`、`mountWorld` / `unmountWorld`、`start` / `stop`。
 
+`WorldHost.modelFacts` 每次调用按当前端点读取。`activeProvider` 为空或端点没有模型时 `accepts`
+返回 false,`activeProvider` 指向不存在的端点时抛错。
+
 Persona 通过 `CoreApi` 访问：`injectInternal` / `injectDeferred` / `injectExternal`、
 `requestContextHandoff`、`spawnFork`、`sessionInfo`、`llm`、`timers`、`deliveryGate`、
 `personaState` / `savePersonaState`、`toolsTagged`、`blob`、`log`。
@@ -62,6 +65,9 @@ piggyback 只入队，随后续唤醒一起投递。
 退回总线，进入下一批。控制台的前缀重载与清空 session 在批次边界执行：正在处理批次时等该批
 结束，空闲时立即；并发请求复用同一事务。
 
+一批正文归档后，Core 调用 `Persona.onDelivery` 并等待它返回的 Promise,不设期限。完成前
+`injectInternal` 的内容排在这批的内部行末尾、外部正文之前;完成后的注入进入总线。
+
 状态 0、429 或 5xx 的模型调用失败，可保留已记录的输出和工具回执，按 `ResubmitPolicy` 重试。
 默认允许连续重试 2 次、每批最多 4 次，退避为 2 秒、10 秒；上下文超限、抢占、关机或轮数
 达到硬上限时不重试。
@@ -88,3 +94,5 @@ handler 异常转为失败回执。流式生成时 `EagerDispatch` 可提前执
 warn；`onHandoff` 异常记录 error 并使用默认交接策略。其他钩子的异常由调用方处理。
 读取 `console()` 失败时省略该 World 的环境段，继续构建前缀。主循环异常退出时记录 error
 并停止定时器。启动器处理未捕获的进程异常并执行关机流程。
+
+`instanceIsRunning(dataDir)` 只读检查实例锁对应进程是否存活，沿用锁接管时的陈旧记录判定，不获取或更改锁。

package/src/core/core.ts

@@ -468,8 +468,10 @@ export class Core<C extends CoreConfig = CoreConfig> {
     return {
       model: () => spec().model,
       accepts: (mime) => {
+        if (!this.loaded.config.activeProvider) return false;
         const {entry} = this.activeProviderEntry();
-        return providerModule(entry.kind).accepts?.(entry,spec(),mime) ?? (entry.multimodal === true && mime.startsWith('image/'));
+        if (!entry.spec) return false;
+        return providerModule(entry.kind).accepts?.(entry,entry.spec,mime) ?? (entry.multimodal === true && mime.startsWith('image/'));
       },
       contextWindow: () => this.contextWindowOf(spec()),
     };

package/src/core/generation.ts

@@ -16,13 +16,26 @@ export interface TokenMeters {
 }
 export type Meter = Exclude<keyof TokenMeters, 'native' | 'details'> | `detail:${string}`;
 export interface PriceRule { meter: Meter; perMillion: number; unit?: string; }
-export interface PriceSnapshot {
+export interface PriceSchedule { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }>; }
+export interface PriceTable extends PriceSchedule { serviceTiers?: Record<string, PriceSchedule>; }
+/**
+ * `from` and `to` are `HH:MM` on the clock of `timezone`, half-open; `to` at or before `from` spans midnight.
+ * A span belongs to the local date it starts on. `weekdays` (ISO, 1 = Monday to 7 = Sunday) limits the dates
+ * that open it; `exceptDates` (`YYYY-MM-DD`) removes single dates.
+ */
+export interface PriceWindow extends PriceTable {
+  from: string;
+  to: string;
+  timezone: string;
+  weekdays?: number[];
+  exceptDates?: string[];
+}
+export interface PriceSnapshot extends PriceTable {
   id: string;
   currency: string;
   basis: 'marginal' | 'equivalent';
-  rules: PriceRule[];
-  inputBands?: Array<{ from: number; rules: PriceRule[] }>;
-  serviceTiers?: Record<string, { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }> }>;
+  /** The first window holding `capturedAt` replaces the table above it; outside every window that table applies. */
+  timeWindows?: PriceWindow[];
   source: string;
   capturedAt: string;
 }
@@ -30,7 +43,7 @@ export interface Charge {
   quote: PriceSnapshot;
   amount: number | null;
   knownAmount: number;
-  missing: Array<Meter | 'serviceTier'>;
+  missing: Array<Meter | 'serviceTier' | 'timeWindow'>;
   lines: Array<{ meter: Meter; unit: string; quantity: number | null; perMillion: number; amount: number | null }>;
 }
 export interface ProviderAttempt {
@@ -89,13 +102,57 @@ export function standardUsage(meters: TokenMeters): Usage | null {
   return { input_tokens: input, output_tokens: output, total_tokens: total,
     input_tokens_details: { cached_tokens: cachedInput }, output_tokens_details: { reasoning_tokens: reasoning } };
 }
+/** Minutes since midnight for an `HH:MM` bound, 24:00 included; null when the text is not one. */
+function clockMinutes(value: string): number | null {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value);
+  if (!match) return null;
+  const minutes = Number(match[1]) * 60 + Number(match[2]);
+  return Number(match[2]) > 59 || minutes > 24 * 60 ? null : minutes;
+}
+/** Whether the text is a real calendar date written `YYYY-MM-DD`. */
+function isCalendarDate(value: string): boolean {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+/** Whether the instant falls in the window on the window's own clock and date; null when a field is unreadable. */
+function holdsTime(window: PriceWindow, at: string): boolean | null {
+  const instant = new Date(at);
+  const [from, to] = [clockMinutes(window.from), clockMinutes(window.to)];
+  if (from === null || to === null || Number.isNaN(instant.getTime())) return null;
+  if (window.weekdays?.some(day => !Number.isInteger(day) || day < 1 || day > 7)) return null;
+  if (window.exceptDates?.some(date => !isCalendarDate(date))) return null;
+  let year: number, month: number, day: number, local: number;
+  try {
+    // Intl throws on a zone name it does not know.
+    const parts = new Intl.DateTimeFormat('en-GB', { timeZone: window.timezone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(instant);
+    const read = (type: string): number => Number(parts.find(part => part.type === type)!.value);
+    [year, month, day] = [read('year'), read('month'), read('day')];
+    local = read('hour') * 60 + read('minute');
+  } catch { return null; }
+  const spansMidnight = to <= from;
+  if (spansMidnight ? local < from && local >= to : local < from || local >= to) return false;
+  // After midnight the span still belongs to the previous date, the one it started on.
+  const start = new Date(Date.UTC(year, month - 1, spansMidnight && local < to ? day - 1 : day));
+  if (window.weekdays && !window.weekdays.includes(start.getUTCDay() || 7)) return false;
+  return !window.exceptDates?.includes(start.toISOString().slice(0, 10));
+}
 export function priceUsage(meters: TokenMeters, quotes: readonly PriceSnapshot[], serviceTier: string | null = null): Charge[] {
   return quotes.map(quote => {
     const missing: Charge['missing'] = [];
-    let schedule: Pick<PriceSnapshot, 'rules' | 'inputBands'> = quote;
-    if (quote.serviceTiers) {
-      if (serviceTier === null || !quote.serviceTiers[serviceTier]) missing.push('serviceTier');
-      else schedule = quote.serviceTiers[serviceTier];
+    let table: PriceTable = quote;
+    for (const window of quote.timeWindows ?? []) {
+      const holds = holdsTime(window, quote.capturedAt);
+      // An unreadable window may be the one holding the request; a later table cannot stand in for it.
+      if (holds === null) { missing.push('timeWindow'); break; }
+      if (holds) { table = window; break; }
+    }
+    let schedule: PriceSchedule = table;
+    if (table.serviceTiers) {
+      if (serviceTier === null || !table.serviceTiers[serviceTier]) missing.push('serviceTier');
+      else schedule = table.serviceTiers[serviceTier];
     }
     let rules = schedule.rules;
     if (schedule.inputBands?.length) {

package/src/core/instance-lock.ts

@@ -72,6 +72,12 @@ function readPayload(file: string): LockPayload | null {
   }
 }
 
+/** 只读检查数据目录的锁是否仍对应存活进程。 */
+export function instanceIsRunning(dataDir: string): boolean {
+  const payload = readPayload(join(dataDir, INSTANCE_LOCK_FILE));
+  return payload !== null && ownerStillRunning(payload);
+}
+
 /** 排他创建；仅 EEXIST 返回 false，其他错误抛出。 */
 function createExclusive(file: string, payload: LockPayload): boolean {
   let fd: number;

package/src/core/loop.ts

@@ -251,7 +251,7 @@ export class MainLoop {
   /** 当前正在处理一个事件批；手动交接必须等到该批自然结束，不能重置半轮session。 */
   private processingBatch = false;
   private handoffRequested = false;
-  /** onDelivery 同步执行期间，injectInternal 的即时项加入当前批，不经过总线。 */
+  /** onDelivery 执行期间（含其 Promise 完成前），injectInternal 的即时项加入当前批，不经过总线。 */
   private deliveryCollector: EventEnvelope[] | null = null;
   /** 已投递但前面仍有外部缺口的游标；水位只越过连续前缀。 */
   private readonly deliveredCursors = new Set<number>();
@@ -484,7 +484,7 @@ export class MainLoop {
   /**
    * 将一批事件写入主 session。即时事件在前，候选生成内容与延迟渲染内容在后。
    * 候选按 source、origin 和处理函数分组，再按来源项在批次中的顺序生成正文。
-   * 正文归档后调用 onDelivery；同步注入的内部项追加到内部行末尾、外部正文之前。
+   * 正文归档后调用并等待 onDelivery；钩子完成前注入的内部项追加到内部行末尾、外部正文之前。
    * 内部行合成一条 user 消息；外部正文按 eventDelivery 进入合成工具回执或同一条 user 消息。
    */
   private async deliverBatch(batch: WakeItem[], generation: number): Promise<boolean> {
@@ -537,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 {
@@ -1663,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);

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/types.ts

@@ -551,6 +551,7 @@ export interface DeliveryGateApi {
 /** 运行时查询当前模型的名称、MIME 支持和上下文窗口；配置热改后读取新值。 */
 export interface ModelFacts {
   model(): string;
+  /** 未选端点或端点未选模型时返回 false；activeProvider 指向不存在的端点时抛错。 */
   accepts(mime: string): boolean;
   /** provider 探测值与手动配置取较小者，单位 token；两者均未知时返回 undefined。 */
   contextWindow(): number | undefined;
@@ -910,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 时强制交接。

package/src/extensions/dry-mount.ts

@@ -1,7 +1,7 @@
 /**
  * 在临时部署中检查扩展构造与声明接口，不调用 start()。
  * World 使用默认配置、无密钥，检查 create、tools、envPromptVars、console、工具名冲突与配置路径；
- * provider 使用测试端点 create，bot 使用测试部署 build。
+ * provider 使用测试端点 create 并检查配置路径，bot 使用测试部署 build。
  * World 构造失败为错误；provider 仅在绑定端点时构造，测试条目不完整导致的失败记为警告。
  * 临时文件位于 scratchDir，调用方负责创建与清理。
  */
@@ -40,17 +40,18 @@ const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 
 /**
- * 声明过的每个配置路径都要在 `defaults()` 里有对应项,且落在 prefix 指的段内。
+ * 声明过的每个配置路径都要落在 prefix 指的段内;给了 `defaults` 时还要在里面有对应项。
  * 缺默认值时控制台照样渲染旋钮、也照样写回 config.json,而读到的是代码里另一处的兜底值。
+ * provider 的旋钮写进端点条目而不是 `defaults()`,所以只核对段。
  */
-function configPathProblems(group: ConfigGroup, defaults: Record<string, unknown>, prefix: string): string[] {
+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 (getByPath(defaults, path.slice(prefix.length)) === undefined) {
+    if (defaults && getByPath(defaults, path.slice(prefix.length)) === undefined) {
       problems.push(`配置组「${group.id}」声明的「${path}」在 defaults() 里没有对应项:旋钮能改、能写回 config.json,读到的仍是代码里的兜底值。`);
     }
   }
@@ -209,7 +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, defaults, `worlds.${def.id}.`));
+        failures.push(...configPathProblems(group, `worlds.${def.id}.`, defaults));
       }
       const keys = new Set<string>();
       for (const doc of decl.promptDocs ?? []) {
@@ -233,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;
@@ -257,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 = {
@@ -274,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 {
@@ -286,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} 个配置组。`);
       }
@@ -405,7 +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, ''));
+    failures.push(...configPathProblems(group, '', config));
   }
   return report;
 }

package/src/extensions/manifest.ts

@@ -17,7 +17,7 @@ export const EXTENSION_KINDS: readonly ExtensionKind[] = ['world', 'provider', '
 export const EXTENSION_API_VERSIONS: Readonly<Record<ExtensionKind, number>> = {
   world: 5,
   provider: 5,
-  bot: 5,
+  bot: 6,
 };
 
 /** npm 上按类发现用的关键字。 */

package/src/launcher.ts

@@ -13,7 +13,7 @@ import { createBot } from './bot.ts';
 import { createDeployment, ensureDeployment, listBots, loadDeployment } from './deploy.ts';
 import { buildListing, type BotDefaults } from './deploy-listing.ts';
 import { secretReader } from './core/secrets.ts';
-import { announceDataDir, consoleUrlOf, consumeBootFlags, listensOnEveryInterface, startsPaused } from './boot.ts';
+import { announceDataDir, consoleUrlOf, consumeBootFlags, listensOnEveryInterface, startsPaused, providerAtBoot } from './boot.ts';
 import { extensionsDir, importBotDefinition, loadExtensions, locateBotPackage, readInstalled, type ActiveBotPackage } from './extensions.ts';
 import { withWorlds } from './world.ts';
 import { BUILTIN_WORLDS } from './worlds/index.ts';
@@ -179,16 +179,10 @@ async function main(): Promise<void> {
   // 重启标志必须在装配与 session 加载之前处理
   consumeBootFlags(loaded.dataDir);
 
-  const activeProvider = cfg.providers?.[cfg.activeProvider];
-  if (!activeProvider) {
-    console.error(
-      `activeProvider="${cfg.activeProvider}" 在 providers 段里不存在(现有: ${Object.keys(cfg.providers ?? {}).join(' / ') || '无'})`,
-    );
-    process.exit(1);
-  }
-  const endpointDir = providerDir(cfg.activeProvider);
+  const activeProvider = providerAtBoot(cfg);
+  const endpointDir = activeProvider ? providerDir(cfg.activeProvider) : null;
   const missingSecret =
-    activeProvider.secret && !secretReader(resolve(endpointDir, '.env'))(activeProvider.secret)
+    activeProvider?.secret && endpointDir && !secretReader(resolve(endpointDir, '.env'))(activeProvider.secret)
       ? activeProvider.secret
       : null;
 
@@ -204,9 +198,9 @@ async function main(): Promise<void> {
   const consoleUrl = port === null ? null : consoleUrlOf(bot.webApp?.boundAddress ?? null, port);
   if (port !== null) {
     console.log(`  控制台:    ${consoleUrl}${listensOnEveryInterface(bot.webApp?.boundAddress ?? null) ? `(监听 ${bot.webApp?.boundAddress},所有网卡)` : ''}`);
-    const assetsProblem = webAssetsProblem(fileURLToPath(new URL('../dist/web', import.meta.url)));
+    const assetsProblem = webAssetsProblem(fileURLToPath(new URL('..', import.meta.url)));
     if (assetsProblem) {
-      console.log(`  ⚠ 控制台产物不完整(${assetsProblem});停止 bot 后运行 pnpm build:web`);
+      console.log(`  ⚠ 控制台产物需要重建(${assetsProblem});停止 bot 后运行 pnpm build:web`);
     }
   }
   for (const slot of bot.assembly.slots) {
@@ -222,8 +216,8 @@ async function main(): Promise<void> {
         ? `  扩展:      ${ext.name}@${ext.version} · bot 包,本部署未引用`
         : `  扩展:      ${ext.name} 未加载: ${ext.reason}`);
   }
-  console.log(`  主模型:    ${bot.core.mainSessionSpec().model}`);
-  if (missingSecret) {
+  console.log(`  主模型:    ${activeProvider?.spec?.model || '未配置；请在控制台「模型供应商」页选择连接与模型'}`);
+  if (missingSecret && endpointDir) {
     const envFile = resolve(endpointDir, '.env');
     const where = existsSync(envFile) ? `${envFile} 里也没有` : `${envFile} 不存在`;
     console.log(`  ⚠ 缺少 ${missingSecret}:进程环境里没有,${where}；可在控制台「模型提供商」页修改密钥变量名或补填密钥`);

package/src/protocol/open-responses/context-helpers.ts

@@ -12,7 +12,9 @@ export function withoutPastReasoning(entries: readonly ContextRecord[]): Context
 }
 export function responseRequest(spec: ModelSpec, context: readonly ContextRecord[], tools: readonly ToolSchema[] = []): Request {
   return {
-    model: spec.model, input: context.map(inputItem), tools: tools.map(tool => ({ ...tool, type: 'function' })),
+    model: spec.model, input: context.map(inputItem),
+    // 只有协议声明的成员进线;运行时传进来的对象还带着分类标签,它归控制台与工具装配。
+    tools: tools.map(({ name, description, parameters }) => ({ type: 'function' as const, name, description, parameters })),
     // effort 词表归端点(见 ModelSpec.reasoningEffort);协议枚举只覆盖 OpenAI 自己的取值。
     reasoning: spec.thinking ? { ...(spec.reasoningEffort ? { effort: spec.reasoningEffort as Schemas['ReasoningEffortEnum'] } : {}) } : { effort: 'none' },
     ...(spec.temperature !== undefined ? { temperature: spec.temperature } : {}),

package/src/providers/README.md

@@ -28,16 +28,17 @@ effort 收任意非空串)、`serviceTiers`、`create(name, entry, host)`。可
 (附加配置组与面板)、`prices()`、`estimateTokens()`、`contextOverflow()`。
 
 地址、密钥变量名与图像开关不归模块:框架在 `console/config.ts` 里为每个端点声明这一组,
-扩展来的模块照样有。模块自己的 `options.*` 走 `config()` 的配置组,面板在 `instance` 插槽里
+扩展来的模块照样有。模块自己的 `options.*` 走 `config()` 的配置组,模块的面板作为端点编辑页的段落
 用控制台的 schema 渲染器画同一份声明、经 `ctx.setConfig` 暂存到连接草稿——内建 llamacpp 的运行时与启动
-两段走的是这条。`console()` 显式给空 `config` 表示这一页不另开配置页签,声明仍参与服务端
-校验。启停与模型操作这类动作走面板 invoke。
+两段走的是这条。段落顺序由 `console()` 的 `panels` 定:编辑页自带的四块(`console/config.ts` 的
+`connectionBlocks`)与模块自己的面板排成一列。`console()` 显式给空 `config` 表示这一页不另开配置页签,
+声明仍参与服务端校验。启停与模型操作这类动作走面板 invoke。
 
 `create()` 返回 `ProviderInstance`:`client`(实现 `respond`)、`listModels?`、`control?`、
 `compatibilityKey?`、`start?` / `stop?`、`contextWindow?(model)`。
 
 `ProviderHost` 给实例:`stateDir`(`<部署根>/providers/<端点名>/`,归实例独占)、`repoRoot`、
-`resource()`、`currentEntry()`、`secret(name)`(进程环境优先,否则读 `stateDir/.env` 一次)、
+`resource()`、`currentEntry()`、`secret(name)`(进程环境优先,否则现读 `stateDir/.env`)、
 `readBlob()`、`keepThinking()`、`log`。
 
 ## 注册与解析
@@ -46,10 +47,11 @@ effort 收任意非空串)、`serviceTiers`、`create(name, entry, host)`。可
 之前通过 `registerProviderModules()` 注册,id 重复时抛错。
 
 `ProviderRegistry.resolve(name)`:按 `entry.kind` 找模块,`normalize`,以去掉 `pricing` 与
-`spec` 的条目 JSON 为缓存键(改模型或价格不重建实例),填 `stateDir` 与 `secret`。
+`spec` 的条目 JSON 加端点 `.env` 的内容指纹为缓存键(改模型或价格不重建实例,密钥文件变更后
+下一次解析重建),填 `stateDir` 与 `secret`。
 `bind(name)` 在实例外包一层:注入 `quote`(报价快照)与 `origin`(实例、模块、模型、
 `compatibilityDomain` = sha256(kind + baseUrl + `compatibilityKey()`))。Responses 历史推理仅在实例、
-模块、兼容域与模型均匹配时回传。`invalidate()` 清除缓存;写入 `.env` 后必须调用,每个实例仅缓存一次文件内容。
+模块、兼容域与模型均匹配时回传。`invalidate()` 清除缓存,控制台保存端点后调用;`.env` 变更经缓存键在下一次解析生效。
 
 ## 配置形状
 
@@ -64,8 +66,9 @@ Core 侧:`activeProviderEntry()` / `activeSpec()` 每次现读;`contextWindowOf(
 ## transport
 
 `response-http.ts` 处理 HTTP/SSE:一次生成可包含多次请求尝试,重试间隔为 `[1s, 4s, 10s]`;超时
-四档(流式首包 300s、非流式 120s、帧空闲 120s、内容空闲 300s);只对状态 0 / 429 / 5xx 重试,
-401 / 403 先 `transport.refresh()` 一次;已提交不可逆增量后不再重试;输出字符超过
+四档(流式首包 300s、非流式 120s、帧空闲 120s、内容空闲 300s);只对状态 0 / 408 / 429 / 5xx
+重试,响应带 `Retry-After` 时按它退避,401 / 403 先 `transport.refresh()`
+一次;已提交不可逆增量后不再重试;输出字符超过
 `max_output_tokens × 12` 时终止请求并报告超限;终态只接受 `completed` / `incomplete`,`failed` 抛
 `LLMError`;每次请求尝试记录 `meters` 与 `charges`。
 
@@ -107,4 +110,8 @@ Core 侧:`activeProviderEntry()` / `activeSpec()` 每次现读;`contextWindowOf(
 重读共享配置时跟上。
 
 `ProviderConsoleHost.editing` 表示这个实例来自还没保存的表单,模块据此拒绝运行时副作用,
-`host.save` 把配置交回浏览器暂存。`ProviderRegistry.preview` 拿到的实例不进运行实例缓存。
+`host.save` 把配置交回浏览器暂存。`ProviderRegistry.previewRegistry` 按一份条目造注册表,实例不进
+运行实例缓存,浏览器刚输入的密钥作为覆盖值排在进程环境与端点 `.env` 之前;测试与模型列表带
+`{ entry, secretValue }` 时走它。
+
+连接列表的 usage 包含其他部署的选用记录及运行锁状态，排除当前部署。运行状态按部署配置的 paths.data（缺省使用 Core 默认值）检查实例锁，不代表供应商正在处理请求，也不建立供应商独占锁。

package/src/providers/console/config.ts

@@ -1,8 +1,23 @@
 import type { ConfigGroup } from '../../core/config-schema.ts';
 import type { LLMProviderEntry } from '../../core/types.ts';
 import type { Language } from '../../core/language.ts';
+import type { ConsolePanelDecl } from '../../web/shared/console-protocol.ts';
 import { text } from './strings.ts';
 
+/**
+ * The editor's own sections with their default wording. A module lists them among its panels,
+ * in the order its workflow wants, and may override title and description.
+ */
+export function connectionBlocks(language: Language): Record<'endpoint' | 'model' | 'pricing' | 'protocol', ConsolePanelDecl> {
+  const S = text(language);
+  return {
+    endpoint: { id: 'endpoint', title: S.endpointBlock, description: S.endpointBlockDescription, builtin: 'connection-endpoint' },
+    model: { id: 'model', title: S.modelBlock, description: S.modelBlockDescription, builtin: 'connection-model' },
+    pricing: { id: 'pricing', title: S.pricingBlock, builtin: 'connection-pricing' },
+    protocol: { id: 'protocol', title: S.protocolBlock, description: S.protocolBlockDescription, builtin: 'connection-protocol' },
+  };
+}
+
 export function connectionGroup(name: string, entry: LLMProviderEntry, language: Language): ConfigGroup {
   const S = text(language);
   const prefix = `providers.${name}.`;

package/src/providers/console/hub.ts

@@ -2,18 +2,20 @@ import { coerceGroupValues, getByPath, setByPath } from '../../core/config-schem
 /** Connection configuration transactions serialize writers across deployments and roll back all touched files on failure. */
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import type { CoreConfig, LLMProviderEntry } from '../../core/types.ts';
 import type { Language } from '../../core/language.ts';
 import { readJsonObject, updateJsonObject } from '../../config-file.ts';
 import { readTextFile } from '../../core/util.ts';
 import type { ProviderModule } from '../base.ts';
 import { validateEntry } from '../configuration.ts';
-import { validateProviderName } from '../name.ts';
+import { validateProviderName, defaultSecretName } from '../name.ts';
 import { providerModules, type ProviderRegistry } from '../registry.ts';
 import type { ProviderSettings } from './settings.ts';
 import { quotePrices } from '../pricebook.ts';
 import { connectionGroup } from './config.ts';
+import { instanceIsRunning } from '../../core/instance-lock.ts';
+import { CORE_DEFAULTS } from '../../core/config.ts';
 
 export class ProviderHubError extends Error {
   constructor(message: string, readonly status = 400) { super(message); }
@@ -63,8 +65,15 @@ export class ProviderHub {
       reasoningTiers: module.localize?.(language)?.reasoningTiers ?? module.reasoningTiers,
       effortSuggestions: module.effortSuggestions ?? [], serviceTiers: module.localize?.(language)?.serviceTiers ?? module.serviceTiers,
       temperatureNote: module.localize?.(language)?.temperatureNote ?? module.temperatureNote,
+      sections: this.sections(module.id, language),
     }));
   }
+  /** The editor's sections for one module, in order: the page's panels minus the endpoint table. */
+  private sections(kind: string, language: Language) {
+    const source = this.settings.sources().find(source => source.id === `llm:${kind}`);
+    return (source?.contribute(language).panels ?? []).filter(panel => panel.id !== 'settings')
+      .map(({ id, title, description, builtin }) => ({ id, title, ...(description ? { description } : {}), ...(builtin ? { builtin } : {}) }));
+  }
   private readiness(name: string, entry: LLMProviderEntry, language: Language) {
     const module = this.modules.find(m => m.id === entry.kind);
     if (!module) return { state: 'module-missing', reason: language === 'zh' ? '供应商模块不可用。' : 'Provider module is unavailable.' };
@@ -89,6 +98,11 @@ export class ProviderHub {
       id: name, name, module: entry.kind, moduleTitle: this.modules.find(m => m.id === entry.kind)?.title ?? entry.kind,
       model: entry.spec?.model ?? null, baseUrl: entry.baseUrl, active: name === this.config.activeProvider,
       readiness: this.readiness(name, entry, language), revision: this.revision(name),
+      usage: this.references(name).filter(file => resolve(file) !== resolve(this.file)).map(file => {
+        const config = readJsonObject(file);
+        const paths = config.paths as { data?: string } | undefined;
+        return { name: basename(dirname(file)), running: instanceIsRunning(resolve(dirname(file), paths?.data ?? CORE_DEFAULTS.paths.data)) };
+      }),
     })) };
   }
   detail(name: string, language: Language) {
@@ -171,11 +185,8 @@ export class ProviderHub {
       if (prior && prior.kind !== input.entry.kind) throw new ProviderHubError('Provider module cannot be changed.');
       const module = this.modules.find(m => m.id === input.entry.kind);
       if (!module) throw new ProviderHubError('Provider module is unavailable.');
-      const requested = structuredClone(input.entry);
+      const requested = withTypedSecret(name, structuredClone(input.entry), input.secretValue);
       if (!requested.spec?.model) throw new ProviderHubError('Model is required.');
-      if (input.secretValue !== undefined && (typeof input.secretValue !== 'string' || !input.secretValue || /\s/.test(input.secretValue)))
-        throw new ProviderHubError('API Key must be nonempty and contain no whitespace.');
-      if (input.secretValue && !requested.secret) requested.secret = 'CORTICO_PROVIDER_API_KEY';
       const entry = validateEntry(module, requested, language);
       const prefix = `providers.${name}.`;
       for (const group of this.groups(name, entry, language)) {
@@ -259,12 +270,38 @@ export class ProviderHub {
       rmSync(tomb, { recursive: true, force: true });
     });
   }
-  async action(name: string, action: string, language: Language) {
+  /**
+   * Probe (`test`) or list models (`models`). With `draft`, the request goes through an instance
+   * built from the browser's entry and typed key; nothing is written, and `name` may not exist yet.
+   */
+  async action(name: string, action: 'test' | 'models', language: Language, draft?: { entry: LLMProviderEntry; secretValue?: string }) {
     this.refresh();
-    const entry = this.config.providers[name];
-    if (!entry) throw new ProviderHubError('Provider does not exist.', 404);
-    const source = this.settings.sources().find(source => source.id === `llm:${entry.kind}`);
-    if (!source) throw new ProviderHubError('Provider module is unavailable.');
-    return source.contribute(language).invoke!('settings', action === 'test' ? 'probe' : 'models', [{ name }]);
+    if (!draft) {
+      const entry = this.config.providers[name];
+      if (!entry) throw new ProviderHubError('Provider does not exist.', 404);
+      const source = this.settings.sources().find(source => source.id === `llm:${entry.kind}`);
+      if (!source) throw new ProviderHubError('Provider module is unavailable.');
+      return source.contribute(language).invoke!('settings', action === 'test' ? 'probe' : 'models', [{ name }]);
+    }
+    this.path(name);
+    if (!draft.entry || typeof draft.entry !== 'object') throw new ProviderHubError('Provider configuration is required.');
+    const module = this.modules.find(m => m.id === draft.entry.kind);
+    if (!module) throw new ProviderHubError('Provider module is unavailable.');
+    const entry = validateEntry(module, withTypedSecret(name, draft.entry, draft.secretValue), language);
+    const registry = this.registry.previewRegistry(name, entry, entry.secret && draft.secretValue ? { [entry.secret]: draft.secretValue } : {});
+    if (action === 'models') {
+      const instance = registry.resolve(name);
+      if (!instance.listModels) throw new ProviderHubError('This module does not list models.');
+      return { models: await instance.listModels() };
+    }
+    if (!entry.spec) throw new ProviderHubError('Model is required.');
+    return this.settings.probeClient(registry.bind(name), entry.spec, language);
   }
 }
+
+/** A typed key with no variable name declared is stored under the name derived from the endpoint name. */
+function withTypedSecret(name: string, entry: LLMProviderEntry, secretValue: string | undefined): LLMProviderEntry {
+  if (secretValue !== undefined && (typeof secretValue !== 'string' || !secretValue || /\s/.test(secretValue)))
+    throw new ProviderHubError('API Key must be nonempty and contain no whitespace.');
+  return secretValue && !entry.secret ? { ...entry, secret: defaultSecretName(name) } : entry;
+}