cortico 0.1.1 → 0.1.2

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 与工具名冲突；
+ * 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 -->
+<!-- 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,14 +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()`。
 
-地址、密钥变量名与图像开关由控制台的端点面板编辑,模块不为它们声明配置组。模块自己的
-`options.*` 要么走 `config()` 的配置组,要么由 `console()` 声明一块挂进 `instance` 插槽的面板——
-内建 llamacpp 的运行时与模型两段走的是后者。
+地址、密钥变量名与图像开关不归模块:框架在 `console/config.ts` 里为每个端点声明这一组,
+扩展来的模块照样有。模块自己的 `options.*` 走 `config()` 的配置组,面板在 `instance` 插槽里
+用控制台的 schema 渲染器画同一份声明、经 `ctx.setConfig` 暂存到连接草稿——内建 llamacpp 的运行时与启动
+两段走的是这条。`console()` 显式给空 `config` 表示这一页不另开配置页签,声明仍参与服务端
+校验。启停与模型操作这类动作走面板 invoke。
 
 `create()` 返回 `ProviderInstance`:`client`(实现 `respond`)、`listModels?`、`control?`、
 `compatibilityKey?`、`start?` / `stop?`、`contextWindow?(model)`。
@@ -68,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。
 
@@ -83,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` 拿到的实例不进运行实例缓存。

package/src/providers/base.ts

@@ -70,6 +70,7 @@ export interface ProviderAvailability {
 export interface ProviderModule {
   id: string;
   title: string;
+  description?: string;
   defaultBaseUrl?: string;
   /** Candidate endpoint URLs offered on the URL field. Candidates only: any URL is accepted. */
   baseUrlSuggestions?: readonly string[];
@@ -83,6 +84,7 @@ export interface ProviderModule {
    * Absent (or a field left out) = the tables above are shown as written.
    */
   localize?(language: Language): {
+    description?: string;
     reasoningTiers?: readonly ReasoningTier[];
     serviceTiers?: readonly ServiceTier[];
     temperatureNote?: string;

package/src/providers/console/config.ts

@@ -0,0 +1,21 @@
+import type { ConfigGroup } from '../../core/config-schema.ts';
+import type { LLMProviderEntry } from '../../core/types.ts';
+import type { Language } from '../../core/language.ts';
+import { text } from './strings.ts';
+
+export function connectionGroup(name: string, entry: LLMProviderEntry, language: Language): ConfigGroup {
+  const S = text(language);
+  const prefix = `providers.${name}.`;
+  return {
+    id: `llm.${entry.kind}.${name}.connection`,
+    owner: `provider:${entry.kind}`,
+    schema: {
+      type: 'object', title: name, description: S.connectionDescription,
+      properties: {
+        [`${prefix}baseUrl`]: { type: 'string', title: S.baseUrl, 'x-hot': true },
+        [`${prefix}secret`]: { type: 'string', title: S.secret, description: S.secretDescription, 'x-hot': true },
+        [`${prefix}multimodal`]: { type: 'boolean', title: S.multimodal, 'x-hot': true },
+      },
+    },
+  };
+}