cortico 0.1.0 → 0.1.2

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>;
@@ -833,8 +834,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>;
@@ -930,7 +934,7 @@ export interface Persona {
   /**
    * session 的合成开头:每次请求置于 system 前缀之后、持久历史之前,不写入 session,交接时
    * 不进保留内容。Core 每次出请求前调用一次,丢弃 system 与 developer 项,补齐工具配对,
-   * 计入 hardTokens。内容由 Persona 的当前输入决定。
+   * 计入 hardTokens。内容只应随 Persona 自己的输入变化;每次不同就每次打穿前缀缓存。
    */
   sessionHead?(): Item[];
   /** Memory 实例。Core 不读它的内容;bot 没给 memoryName 时控制台以它的类名作 Memory 页标题。 */
@@ -1120,6 +1124,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

@@ -372,7 +372,8 @@ export function shortId(prefix = ''): string {
 }
 
 /**
- * 按 BOM 读取 UTF-8 或 UTF-16 LE 文本，返回值不含 BOM；无 BOM 时使用 UTF-8。
+ * 读一个手写的文本文件:按 BOM 选编码,UTF-8 与 UTF-16 LE 都读得出来,BOM 不进返回值。
+ * 没有 BOM 就是 UTF-8。Windows 的 shell 重定向写出的是带 BOM 的 UTF-8 或 UTF-16 LE。
  */
 export function readTextFile(file: string): string {
   const bytes = readFileSync(file);
@@ -384,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

@@ -27,7 +27,10 @@ export function listBots(root = deploymentRoot()): string[] {
 /** 部署根下一份部署都没有时自建的那份，以及它引用的 bot 代码包。 */
 export const DEFAULT_DEPLOYMENT = { name: 'mybot', bot: 'cormini' } as const;
 
-/** 部署目录中的开场引导标记。 */
+/**
+ * 开场引导的一次性标记，放在部署目录下。自建部署时写入，控制台见到它才给引导，操作员
+ * 开口或按下那颗按钮后删除。手动建的部署没有这个文件，也就不会看到引导。
+ */
 export const ONBOARDING_FLAG_FILE = '.onboarding';
 
 /** 部署根下另有用途的目录名，不能拿来当部署名。 */

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 与工具名冲突；
+ * 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,24 @@ const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 
 const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 
+/**
+ * 声明过的每个配置路径都要在 `defaults()` 里有对应项,且落在 prefix 指的段内。
+ * 缺默认值时控制台照样渲染旋钮、也照样写回 config.json,而读到的是代码里另一处的兜底值。
+ */
+function configPathProblems(group: ConfigGroup, defaults: Record<string, unknown>, prefix: string): 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) {
+      problems.push(`配置组「${group.id}」声明的「${path}」在 defaults() 里没有对应项:旋钮能改、能写回 config.json,读到的仍是代码里的兜底值。`);
+    }
+  }
+  return problems;
+}
+
 /** 面板 id 的形状:控制台一页内的局部 id。 */
 const PANEL_ID = /^[a-z0-9-]+$/;
 /** 工具名带前缀:`<短名>_` 起头。 */
@@ -190,6 +209,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}.`));
       }
       const keys = new Set<string>();
       for (const doc of decl.promptDocs ?? []) {
@@ -385,6 +405,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: 5,
+};
+
 /** 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;

package/src/extensions.ts

@@ -14,8 +14,14 @@ import type { CoreConfig, Logger } from './core/types.ts';
 import type { BotDefinition } from './bot.ts';
 import type { WorldDefinition, WorldSection } from './world.ts';
 import type { ProviderModule } from './providers/base.ts';
-import type { ExtensionInfo, ExtensionInstallTarget, ExtensionSearchHit } from './web/server.ts';
+import type {
+  ExtensionInfo,
+  ExtensionInstallTarget,
+  ExtensionPackageDetail,
+  ExtensionSearchHit,
+} from './web/server.ts';
 import {
+  EXTENSION_API_VERSIONS,
   EXTENSION_KEYWORDS,
   parseExtensionManifest,
   type ExtensionConsoleAsset,
@@ -368,11 +374,59 @@ interface RegistrySearchResponse {
       description?: string;
       keywords?: string[];
       date?: string;
+      license?: string;
       links?: { npm?: string; homepage?: string; repository?: string };
       publisher?: { username?: string };
     };
+    /** 被依赖的包数。热门包回字符串,新包回数字。 */
+    dependents?: number | string;
     downloads?: { monthly?: number };
   }>;
+  total?: number;
+}
+
+/** registry 的包文档(`GET /<name>`)。只列我们要读的字段。 */
+interface RegistryPackument {
+  'dist-tags'?: Record<string, string>;
+  versions?: Record<string, ExtensionPackageJson & {
+    license?: string;
+    deprecated?: string;
+    engines?: Record<string, string>;
+    maintainers?: Array<{ username?: string; name?: string }>;
+    _npmUser?: { name?: string };
+    dist?: { unpackedSize?: number; fileCount?: number };
+    homepage?: string;
+    bugs?: { url?: string } | string;
+    repository?: { url?: string } | string;
+  }>;
+  /** `created`、`modified` 和每个版本号各一条发布时间 */
+  time?: Record<string, string>;
+}
+
+/** 一页取满 250:registry 的上限(传更大也只回 250)。 */
+const SEARCH_PAGE_SIZE = 250;
+/**
+ * 最多翻四页。`keywords:` 过滤后的全集现在是个位数;真涨到一千条,说明关键字被滥用,
+ * 再往后翻的也不是操作员要找的包。
+ */
+const SEARCH_MAX_HITS = 1000;
+
+/**
+ * registry 给的仓库地址是 npm 规范化过的 `git+https://….git`:浏览器不认这个 scheme。
+ * 收成可点的 https；认不出形状就原样返回，让操作员自己看。
+ */
+export function repositoryWebUrl(raw: string): string {
+  let url = raw.trim().replace(/^git\+/, '').replace(/^git:\/\//, 'https://');
+  const ssh = /^(?:ssh:\/\/)?git@([^:/]+)[:/](.+)$/.exec(url);
+  if (ssh) url = `https://${ssh[1]}/${ssh[2]}`;
+  url = url.replace(/\.git$/, '');
+  return /^https?:\/\//.test(url) ? url : raw;
+}
+
+/** `{ url }` 或裸串两种写法都收。 */
+function urlOf(v: { url?: string } | string | undefined): string | undefined {
+  const raw = typeof v === 'string' ? v : v?.url;
+  return raw && raw.trim() ? raw.trim() : undefined;
 }
 
 export interface ExtensionManagerOptions {
@@ -441,35 +495,105 @@ export class ExtensionManager {
     return { dir: this.dir, extensions: out };
   }
 
-  async search(query: string, kind: ExtensionKind = 'world'): Promise<ExtensionSearchHit[]> {
+  /**
+   * 列出 npm 上带这一类关键字的全部包。**不接文本查询**:registry 的 `text=` 在
+   * `keywords:` 过滤之下只影响排序不缩小结果(实测 `keywords:cortico-world 任意词`
+   * 仍返回同样 8 条),筛选交给控制台在整份结果上做。
+   */
+  async search(kind: ExtensionKind = 'world'): Promise<ExtensionSearchHit[]> {
     const keyword = EXTENSION_KEYWORDS[kind];
-    const text = `keywords:${keyword} ${query.trim()}`.trim();
-    const url = `${this.registry}/-/v1/search?text=${encodeURIComponent(text)}&size=50`;
-    const data = (await this.fetchJson(url)) as RegistrySearchResponse;
     const installed = new Set(readInstalled(this.dir).map((p) => p.name));
     const hits: ExtensionSearchHit[] = [];
-    for (const obj of data.objects ?? []) {
-      const p = obj.package;
-      if (!p?.name || !p.version || !(p.keywords ?? []).includes(keyword)) continue;
-      hits.push({
-        name: p.name,
-        version: p.version,
-        description: p.description ?? '',
-        kind,
-        ...(p.date ? { date: p.date } : {}),
-        ...(p.publisher?.username ? { publisher: p.publisher.username } : {}),
-        downloads: obj.downloads?.monthly ?? 0,
-        links: {
-          ...(p.links?.npm ? { npm: p.links.npm } : {}),
-          ...(p.links?.repository ? { repository: p.links.repository } : {}),
-          ...(p.links?.homepage ? { homepage: p.links.homepage } : {}),
-        },
-        installed: installed.has(p.name),
-      });
+    const seen = new Set<string>();
+    for (let from = 0; from < SEARCH_MAX_HITS; from += SEARCH_PAGE_SIZE) {
+      const text = encodeURIComponent(`keywords:${keyword}`);
+      const url = `${this.registry}/-/v1/search?text=${text}&size=${SEARCH_PAGE_SIZE}&from=${from}`;
+      const data = (await this.fetchJson(url)) as RegistrySearchResponse;
+      const objects = data.objects ?? [];
+      for (const obj of objects) {
+        const p = obj.package;
+        if (!p?.name || !p.version || !(p.keywords ?? []).includes(keyword)) continue;
+        if (seen.has(p.name)) continue;
+        seen.add(p.name);
+        const repository = p.links?.repository;
+        hits.push({
+          name: p.name,
+          version: p.version,
+          description: p.description ?? '',
+          kind,
+          ...(p.date ? { date: p.date } : {}),
+          ...(p.publisher?.username ? { publisher: p.publisher.username } : {}),
+          ...(p.license ? { license: p.license } : {}),
+          ...(p.keywords?.length ? { keywords: p.keywords } : {}),
+          downloads: obj.downloads?.monthly ?? 0,
+          dependents: Number(obj.dependents) || 0,
+          links: {
+            ...(p.links?.npm ? { npm: p.links.npm } : {}),
+            ...(repository ? { repository: repositoryWebUrl(repository) } : {}),
+            ...(p.links?.homepage ? { homepage: p.links.homepage } : {}),
+          },
+          installed: installed.has(p.name),
+        });
+      }
+      if (objects.length < SEARCH_PAGE_SIZE) break;
     }
     return hits;
   }
 
+  /**
+   * 一个包的详情。控制台在操作员点开某张卡片时才调，因此这里取整份包文档
+   * (`GET /<name>`，比搜索结果多出 cortico 声明、许可证、体积与版本史)。
+   * readme 不回传：一份 30KB 以上的 markdown，控制台也不渲染它。
+   */
+  async packageInfo(name: string): Promise<ExtensionPackageDetail> {
+    if (!PACKAGE_NAME.test(name)) throw new Error(`不是合法的 npm 包名: ${name}`);
+    const doc = (await this.fetchJson(`${this.registry}/${name.replace('/', '%2F')}`)) as RegistryPackument;
+    const latest = doc['dist-tags']?.latest;
+    const v = latest ? doc.versions?.[latest] : undefined;
+    if (!latest || !v) throw new Error(`registry 没有给出 ${name} 的 latest 版本`);
+
+    const parsed = parseExtensionManifest(v);
+    const times = Object.entries(doc.time ?? {}).filter(([k]) => k !== 'created' && k !== 'modified');
+    const history = times
+      .sort((a, b) => (a[1] < b[1] ? 1 : -1))
+      .slice(0, 6)
+      .map(([version, date]) => ({ version, date }));
+    const spec = readInstalled(this.dir).find((p) => p.name === name)?.spec;
+    const repository = urlOf(v.repository);
+    const bugs = urlOf(v.bugs);
+
+    return {
+      name,
+      version: latest,
+      ...(v.description ? { description: v.description } : {}),
+      ...(v.license ? { license: v.license } : {}),
+      ...(v.keywords?.length ? { keywords: v.keywords } : {}),
+      ...(doc.time?.[latest] ? { published: doc.time[latest] } : {}),
+      ...(doc.time?.created ? { created: doc.time.created } : {}),
+      versionCount: times.length,
+      history,
+      ...(v.deprecated ? { deprecated: v.deprecated } : {}),
+      ...(parsed.ok
+        ? { manifest: parsed.manifest, frameworkApi: EXTENSION_API_VERSIONS[parsed.manifest.kind] }
+        : { problems: parsed.reasons }),
+      warnings: parsed.warnings,
+      ...(v.engines?.node ? { engines: v.engines.node } : {}),
+      ...(v.dist?.unpackedSize ? { unpackedSize: v.dist.unpackedSize } : {}),
+      ...(v.dist?.fileCount ? { fileCount: v.dist.fileCount } : {}),
+      dependencies: Object.keys(v.dependencies ?? {}),
+      maintainers: (v.maintainers ?? []).map((m) => m.username ?? m.name ?? '').filter(Boolean),
+      ...(v._npmUser?.name ? { publisher: v._npmUser.name } : {}),
+      links: {
+        npm: `https://www.npmjs.com/package/${name}`,
+        ...(repository ? { repository: repositoryWebUrl(repository) } : {}),
+        ...(v.homepage ? { homepage: v.homepage } : {}),
+        ...(bugs ? { bugs } : {}),
+      },
+      installed: spec !== undefined,
+      ...(spec !== undefined ? { installedSpec: spec } : {}),
+    };
+  }
+
   async install(target: ExtensionInstallTarget): Promise<string> {
     const spec = this.installSpec(target);
     if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });

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, consumeBootFlags } from './boot.ts';
+import { announceDataDir, consoleUrlOf, consumeBootFlags, listensOnEveryInterface, startsPaused } 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';
@@ -160,6 +160,22 @@ async function main(): Promise<void> {
     cfg.logging.file = levelArg as LogLevel;
   }
 
+  // 监听地址与端口:--host= / --port= 只覆盖本次运行,不写回 config.json。
+  const hostArg = flagValue('host');
+  if (hostArg !== null) {
+    if (!hostArg.trim()) { console.error('--host 需要一个地址,如 0.0.0.0'); process.exit(1); }
+    cfg.web.host = hostArg.trim();
+  }
+  const portArg = flagValue('port');
+  if (portArg !== null) {
+    const port = Number(portArg);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      console.error(`无效端口: ${portArg}(0–65535 的整数,0 由系统分配)`);
+      process.exit(1);
+    }
+    cfg.web.port = port;
+  }
+
   // 重启标志必须在装配与 session 加载之前处理
   consumeBootFlags(loaded.dataDir);
 
@@ -179,17 +195,15 @@ async function main(): Promise<void> {
   const bot = createBot(loaded, definition, { extensions });
 
   // 必须在启动主循环前暂停，避免首批事件提前投递。
-  const startPaused =
-    process.env.CORTICO_START_PAUSED === '1' ||
-    process.env.CORTICO_START_PAUSED === 'true' ||
-    process.argv.includes('--paused');
-  if (startPaused) bot.core.bus.setPaused(true);
+  const paused = startsPaused();
+  if (paused) bot.core.bus.setPaused(true);
 
   const { port } = await bot.start();
 
   console.log(`\n  Bot:       ${botName}${cfg.displayName && cfg.displayName !== botName ? ` (${cfg.displayName})` : ''}`);
+  const consoleUrl = port === null ? null : consoleUrlOf(bot.webApp?.boundAddress ?? null, port);
   if (port !== null) {
-    console.log(`  控制台:    http://127.0.0.1:${port}/`);
+    console.log(`  控制台:    ${consoleUrl}${listensOnEveryInterface(bot.webApp?.boundAddress ?? null) ? `(监听 ${bot.webApp?.boundAddress},所有网卡)` : ''}`);
     const assetsProblem = webAssetsProblem(fileURLToPath(new URL('../dist/web', import.meta.url)));
     if (assetsProblem) {
       console.log(`  ⚠ 控制台产物不完整(${assetsProblem});停止 bot 后运行 pnpm build:web`);
@@ -214,7 +228,7 @@ async function main(): Promise<void> {
     const where = existsSync(envFile) ? `${envFile} 里也没有` : `${envFile} 不存在`;
     console.log(`  ⚠ 缺少 ${missingSecret}:进程环境里没有,${where}；可在控制台「模型提供商」页修改密钥变量名或补填密钥`);
   }
-  if (startPaused) {
+  if (paused) {
     console.log('  ⏸ 已暂停');
   }
   console.log('');
@@ -223,7 +237,7 @@ async function main(): Promise<void> {
     process.env.CORTICO_OPEN_BROWSER === '1' ||
     process.env.CORTICO_OPEN_BROWSER === 'true' ||
     process.argv.includes('--open');
-  if (openBrowserFlag && port !== null) openBrowser(`http://127.0.0.1:${port}/`);
+  if (openBrowserFlag && consoleUrl !== null) openBrowser(consoleUrl);
 
   // 此时限覆盖整个关机流程；各步骤的时限由 bot.shutdown() 管理。
   const SHUTDOWN_GRACE_MS = 35_000;

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

@@ -1,4 +1,4 @@
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, truncateSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { ContextRecord } from './context.ts';
 
@@ -10,6 +10,20 @@ function freeze<T>(value: T): T {
   return value;
 }
 
+function isRecord(row: unknown): row is ContextRecord {
+  const r = row as ContextRecord | null;
+  return !!r && r.version === 2 && !!r.item && typeof r.item === 'object' && !Array.isArray(r.item)
+    && !!r.context && typeof r.context === 'object' && !Array.isArray(r.context);
+}
+
+/**
+ * The repair `load()` applied to a final line that has no trailing newline. A line that does not
+ * parse is cut off; a complete record only gets its newline.
+ */
+export type ContextLoadRepair =
+  | { kind: 'torn-tail'; bytes: number }
+  | { kind: 'unterminated-tail' };
+
 /** Immutable standard Items with runtime metadata stored in a separate field. */
 export class ContextLog {
   private entries: readonly ContextRecord[] = Object.freeze([]);
@@ -19,18 +33,32 @@ export class ContextLog {
 
   get records(): readonly ContextRecord[] { return this.entries; }
 
-  load(): void {
-    if (!existsSync(this.file)) { this.entries = Object.freeze([]); return; }
-    const rows = readFileSync(this.file, 'utf8').split(/\r?\n/).filter(line => line.trim()).map((line, index) => {
-      let row: ContextRecord;
-      try { row = JSON.parse(line) as ContextRecord; }
+  /** Any other damaged line throws and leaves the file untouched. */
+  load(): ContextLoadRepair | null {
+    if (!existsSync(this.file)) { this.entries = Object.freeze([]); return null; }
+    const raw = readFileSync(this.file, 'utf8');
+    let body = raw;
+    let repair: ContextLoadRepair | null = null;
+    if (raw.length > 0 && !raw.endsWith('\n')) {
+      const cut = raw.lastIndexOf('\n') + 1;
+      const tail = raw.slice(cut);
+      let parsed: unknown = null;
+      try { parsed = JSON.parse(tail); } catch { /* torn */ }
+      if (isRecord(parsed)) repair = { kind: 'unterminated-tail' };
+      else { body = raw.slice(0, cut); repair = { kind: 'torn-tail', bytes: Buffer.byteLength(tail, 'utf8') }; }
+    }
+    const rows = body.split(/\r?\n/).filter(line => line.trim()).map((line, index) => {
+      let row: unknown;
+      try { row = JSON.parse(line); }
       catch { throw new Error(`Invalid session JSON at ${this.file}:${index + 1}`); }
-      if (!row || row.version !== 2 || !row.item || typeof row.item !== 'object' || Array.isArray(row.item)
-        || !row.context || typeof row.context !== 'object' || Array.isArray(row.context))
-        throw new Error(`Invalid context record at ${this.file}:${index + 1}`);
+      if (!isRecord(row)) throw new Error(`Invalid context record at ${this.file}:${index + 1}`);
       return freeze(row);
     });
+    // Written only after every kept line validated.
+    if (repair?.kind === 'torn-tail') truncateSync(this.file, Buffer.byteLength(body, 'utf8'));
+    else if (repair) appendFileSync(this.file, '\n');
     this.entries = Object.freeze(rows);
+    return repair;
   }
 
   append(entry: ContextRecord): ContextRecord {

package/src/providers/README.md

@@ -1,4 +1,4 @@
-<!-- Owner: src/providers/base.ts, src/providers/registry.ts, src/providers/console/settings.ts, src/providers/console/config.ts, src/providers/openai-responses-compat/config.ts -->
+<!-- Owner: src/providers/base.ts, src/providers/console/hub.ts, src/providers/hub-api.ts, src/providers/name.ts, src/providers/registry.ts, src/providers/console/settings.ts, src/providers/console/config.ts, src/providers/openai-responses-compat/config.ts, src/providers/transport/responses-input.ts, src/providers/transport/history.ts, src/providers/llamacpp/native.ts -->
 
 # src/providers
 
@@ -22,15 +22,16 @@
 ## ProviderModule
 
 `id` 必须等于目录名(扩展包里则是包声明的 id)。必填:`title`、`reasoningTiers`(空表 = 开放,
-effort 收任意非空串)、`serviceTiers`、`create(name, entry, host)`。可选:`defaultBaseUrl` 与
+effort 收任意非空串)、`serviceTiers`、`create(name, entry, host)`。可选:`description`、`defaultBaseUrl` 与
 `baseUrlSuggestions`、`effortSuggestions`、`temperatureNote`、`localize()`、`normalize()`、
 `validateEntry()`、`validateModel()`、`accepts()`(多模态判定)、`config()` 与 `console()`
 (附加配置组与面板)、`prices()`、`estimateTokens()`、`contextOverflow()`。
 
-地址、密钥变量名与图像开关由 `console/config.ts` 声明为 ConfigGroup。模块自己的
-配置通过 `config()` 声明。模块可在 `instance` 插槽中渲染这些 schema,
-通过 `ctx.setConfig` 保存;`console().config` 显式为空时省略独立配置页签,
-配置组仍参与服务端校验。运行时启停和模型操作由面板 invoke 提供。
+地址、密钥变量名与图像开关不归模块:框架在 `console/config.ts` 里为每个端点声明这一组,
+扩展来的模块照样有。模块自己的 `options.*` 走 `config()` 的配置组,面板在 `instance` 插槽里
+用控制台的 schema 渲染器画同一份声明、经 `ctx.setConfig` 暂存到连接草稿——内建 llamacpp 的运行时与启动
+两段走的是这条。`console()` 显式给空 `config` 表示这一页不另开配置页签,声明仍参与服务端
+校验。启停与模型操作这类动作走面板 invoke。
 
 `create()` 返回 `ProviderInstance`:`client`(实现 `respond`)、`listModels?`、`control?`、
 `compatibilityKey?`、`start?` / `stop?`、`contextWindow?(model)`。
@@ -69,8 +70,11 @@ Core 侧:`activeProviderEntry()` / `activeSpec()` 每次现读;`contextWindowOf(
 `LLMError`;每次请求尝试记录 `meters` 与 `charges`。
 
 `responses-input.ts` 是原生 Responses 的无状态重放(system / developer 上提为
-`instructions`);`chat.ts` + `native-input.ts` / `history.ts` 转换 Chat Completions 请求(历史
-思维链不回传);`response-assembly.ts` 把两种流归一成 Open Responses 的 Item 流,
+`instructions`;思维链按 `reasoningReplay` 以签名块或 `reasoning_text` 回传,明文形态下没有记录来源
+的调用前补一项合成推理);`chat.ts` + `native-input.ts` / `history.ts` 转换 Chat Completions 请求(历史
+思维链回不回传由模块定:`renderMessagesWithMedia` 的 `keepReasoning` 决定出不出线,`dropPastThinking`
+把合成开头之外的每条抹空);
+`response-assembly.ts` 把两种流归一成 Open Responses 的 Item 流,
 `finish_reason` 的 `length` / `content_filter` 落成 `incomplete_details.reason`;
 `response-meters.ts` 把两种 usage 归一成 `TokenMeters`,缺项保持 null。
 
@@ -84,3 +88,23 @@ Core 侧:`activeProviderEntry()` / `activeSpec()` 每次现读;`contextWindowOf(
 模块默认,快照带 sha256 id 与 `capturedAt`。计量键:`input` / `output` / `total` /
 `cachedInput` / `uncachedInput` / `reasoning` 与 `detail:*`,单价按每百万 token。实际扣费在
 `src/core/generation.ts` 的 `priceUsage()`,缺计量记 `amount: null`。
+
+## 端点配置接口
+
+`console/hub.ts` 的 `ProviderHub` 是控制台改端点的唯一入口,`hub-api.ts` 把它接到
+`/api/providers`(聚合、按名读取、保存、删除、设为当前、测试、模型列表)与
+`/api/provider-modules`(已注册模块)。列表保留 `kind` 没有对应模块的端点,active 与可用性
+分别报告;状态帧的 `modelConnection` 带当前端点的名称、模型、模块与地址。
+
+新名称由 `name.ts` 校验:英文字母、数字、`-` 或 `_`,首字符是字母或数字,不收空格与 Windows
+设备名——名字就是 `<部署根>/providers/` 下的目录名。已在磁盘上的名字不改就继续有效。保存带
+读取时的 revision(端点 `config.json` 与 `.env` 的 sha256),对不上返回 409。共享目录上的写锁
+`.write-lock` 串行化各进程的写入。改名同时改目录和部署根内各 `deployment.json` 的
+`activeProvider`,中途失败回滚已动过的文件和目录;还被引用的端点不能删。
+
+保存一次校验模型、连接与模块配置,再写 `config.json` 和可选密钥;密钥进该端点的 `.env`,读取
+接口不返回密钥值。写完清掉本进程的实例缓存,已绑定的请求与 fork 保持原客户端;其他进程在下次
+重读共享配置时跟上。
+
+`ProviderConsoleHost.editing` 表示这个实例来自还没保存的表单,模块据此拒绝运行时副作用,
+`host.save` 把配置交回浏览器暂存。`ProviderRegistry.preview` 拿到的实例不进运行实例缓存。