cortico 0.1.0 → 0.1.2

package/src/web/server.ts

@@ -1,3 +1,4 @@
+import type { ProviderHubApi as ProviderHub } from '../providers/hub-api.ts';
 import type { ContextRecord } from '../protocol/open-responses/context.ts';
 import type { EnvPromptOrigin } from '../core/prefix.ts';
 /**
@@ -33,6 +34,7 @@ const SERVER_TEXT = {
     paused: '已暂停:事件照常落库排队,不投递唤醒',
     resumed: '已继续:积压事件一次性投递',
     exitSupervised: '进程即将退出,启动器随即重新拉起',
+    exitSupervisedPaused: '进程即将退出,启动器随即重新拉起;回来时事件投递是暂停的,要在运行状态里按继续',
     exitUnsupervised: '进程即将退出;没有检测到启动器循环,需要手动重新启动',
     shutdownSkipped: (n: number, labels: string[]) => `本地关机完成,但有 ${n} 步没走完:${labels.join('、')}`,
     shutdownComplete: (n: number) => `本地关机完成(${n} 步全部走完)`,
@@ -45,6 +47,7 @@ const SERVER_TEXT = {
     paused: 'Paused: events are still stored and queued, no wake is delivered',
     resumed: 'Resumed: the backlog is delivered in one batch',
     exitSupervised: 'The process is about to exit; the launcher will start it again',
+    exitSupervisedPaused: 'The process is about to exit; the launcher will start it again with event delivery paused, so resume it in the run status',
     exitUnsupervised: 'The process is about to exit; no launcher loop was detected, so it must be started again by hand',
     shutdownSkipped: (n: number, labels: string[]) => `Local shutdown finished, but ${n} step(s) did not complete: ${labels.join(', ')}`,
     shutdownComplete: (n: number) => `Local shutdown finished (all ${n} steps completed)`,
@@ -55,12 +58,14 @@ const SERVER_TEXT = {
   },
 };
 import { logPredicate, readRunsIndex, readTailRecordsWhere } from './files.ts';
+import { AUTH_KEY_FILE, ConsoleAuth, SESSION_COOKIE, SESSION_COOKIE_MAX_AGE_SEC, cookieValue } from './auth.ts';
+import { buildDiagnostics, DIAGNOSTICS_TAIL } from './diagnostics.ts';
 import { ConsoleAssets, ConsolePageRegistry, type ConsolePageSource } from './console-pages.ts';
 import { THEME_FILE, readDeploymentTheme, writeDeploymentTheme } from './theme-store.ts';
 import { THEME_SCRIPT_ID, type InjectedTheme, type StoredTheme } from './shared/theme.ts';
 import { EXTENSION_ASSET_PREFIX, extensionAssetSegment, type ExtensionConsoleAsset } from '../extensions/manifest.ts';
 import {
-  CONSOLE_LAMPS_ROUTE, CONSOLE_LANGUAGE_HEADER, CONSOLE_LANGUAGE_QUERY, CONSOLE_PROTOCOL_VERSION,
+  CONSOLE_AUTH_HEADER, CONSOLE_LAMPS_ROUTE, CONSOLE_LANGUAGE_HEADER, CONSOLE_LANGUAGE_QUERY, CONSOLE_PROTOCOL_VERSION,
   PROVIDERS_LAMP_ID,
   isBinaryResult, isFileResult,
   type ConsoleFileResult, type ConsoleLamp, type ConsoleStream,
@@ -192,28 +197,76 @@ export interface ExtensionInfo {
   state: 'loaded' | 'failed' | 'pending-restart' | 'removed' | 'idle';
 }
 
+/**
+ * 搜索结果里的一条。字段全部来自 registry 的搜索端点，够列表排序与筛选;
+ * 契约版本、体积、版本史这些要另取包文档，见 `ExtensionPackageDetail`。
+ */
 export interface ExtensionSearchHit {
   name: string;
   version: string;
   description: string;
+  /** 这个版本的发布时间 */
   date?: string;
   publisher?: string;
+  license?: string;
+  keywords?: string[];
   /** 月下载量 */
   downloads: number;
+  /** npm 上依赖这个包的包数 */
+  dependents: number;
   links: { npm?: string; repository?: string; homepage?: string };
   installed: boolean;
   /** 按哪一类关键字搜到的(`cortico-world` → world,`cortico-provider` → provider,`cortico-bot` → bot) */
   kind?: 'world' | 'provider' | 'bot';
 }
 
+/** 一个 npm 包的详情。操作员点开某条搜索结果时才取。 */
+export interface ExtensionPackageDetail {
+  name: string;
+  /** dist-tag `latest` 指的版本 */
+  version: string;
+  description?: string;
+  license?: string;
+  keywords?: string[];
+  /** latest 版本的发布时间 */
+  published?: string;
+  /** 这个包第一次发布的时间 */
+  created?: string;
+  versionCount: number;
+  /** 最近几个版本,新的在前 */
+  history: Array<{ version: string; date: string }>;
+  /** npm 上标了 deprecated 时是那句话 */
+  deprecated?: string;
+  /** package.json 的 cortico 块解析通过时给出 */
+  manifest?: { kind: 'world' | 'provider' | 'bot'; api: number; consoleClient?: string; consoleStyle?: string };
+  /** 解析不通过的理由,与本机装载时用的是同一套判据 */
+  problems?: string[];
+  warnings: string[];
+  /** 本进程对这个包所属那一类的契约版本;manifest 解析不通过时缺席 */
+  frameworkApi?: number;
+  /** `engines.node` */
+  engines?: string;
+  unpackedSize?: number;
+  fileCount?: number;
+  dependencies: string[];
+  maintainers: string[];
+  publisher?: string;
+  links: { npm: string; repository?: string; homepage?: string; bugs?: string };
+  installed: boolean;
+  /** 已安装时 extensions/package.json 里写的那个版本范围 */
+  installedSpec?: string;
+}
+
 /** 装 npm 上的包(可带版本或 dist-tag),或本机一个含 package.json 的目录。 */
 export type ExtensionInstallTarget = { name: string; version?: string } | { path: string };
 
 /** 扩展面:清单、搜索、装卸。装卸只改磁盘,加载要重启进程。 */
 export interface WebAppExtensionDeps {
   list(): { dir: string; extensions: ExtensionInfo[] };
-  /** 不给 kind = world(`cortico-world`)。 */
-  search(query: string, kind?: 'world' | 'provider' | 'bot'): Promise<ExtensionSearchHit[]>;
+  /** 该类关键字下 npm 上的全部包;不给 kind = world(`cortico-world`)。 */
+  search(kind?: 'world' | 'provider' | 'bot'): Promise<ExtensionSearchHit[]>;
+  /** 单个包的详情(另取一次包文档)。 */
+  packageInfo(name: string): Promise<ExtensionPackageDetail>;
   /**
    * 已加载扩展的浏览器端产物。服务端据此把页 id 映到 `/assets/extensions/<包>/<版本>/<文件>`
    * 并只发这几个文件;缺席 = 没有扩展带面板。
@@ -415,6 +468,12 @@ export interface ConsoleSurface {
    * 要放到反向代理后面或有意让别的机器访问,才显式换成 `0.0.0.0`。
    */
   host?: string;
+  /** 回环名与监听地址之外还接受的 Host 名；以它为 Origin 的写请求与 WebSocket 同样放行。 */
+  allowedHosts?: readonly string[];
+  /** 访问密码;缺省或空串时不要求登录。 */
+  password?: string;
+  /** 登录失败的回应延迟(毫秒);缺省见 FAILED_LOGIN_DELAY_MS,测试里调到 0。 */
+  failedLoginDelayMs?: number;
   /** 主循环状态快照(token/截断/梦状态…有什么给什么) */
   getStatus(): Record<string, unknown>;
   /** 调试通道(可选;不挂载时 /ws/debug 拒绝连接) */
@@ -447,7 +506,10 @@ export interface ConsoleSurface {
     dismiss(): void;
   };
 
-  /** 运行控制缺席时 /api/run/* 返回 503；暂停期间事件仍落库排队。关机顺序与进程退出由装配层决定。 */
+  /**
+   * 可选的运行控制，未挂载时 /api/run/* 返回 503；暂停期间事件仍落库排队。
+   * shutdown 按装配层顺序停止投递、IO、托管 LLM server 并落盘，各步有时间预算并返回结果；未提供时不显示关机键，进程退出由装配层决定。
+   */
   run?: {
     pause(): void;
     resume(): void;
@@ -460,6 +522,8 @@ export interface ConsoleSurface {
      */
     restart?(language: Language): Promise<WebAppShutdownReport>;
     supervised?: boolean;
+    /** 重启后是否以暂停态回来;重启回执据此说清楚。 */
+    startsPaused?: boolean;
   };
   /** 扩展装卸(可选;不挂载时 /api/extensions* 503)。 */
   extensions?: WebAppExtensionDeps;
@@ -469,7 +533,10 @@ export interface ConsoleSurface {
    * 不挂载时 /api/console/manifest 返回一份只有 framework 能力的空 manifest。
    */
   consolePageSources?: () => ConsolePageSource[];
-  /** 所有 provider 模块的本地可用性汇总；缺席时省略该状态。 */
+  /**
+   * 有没有一个可用的端点。缺省不挂:「模型提供商」那一行不点灯。
+   */
+  providers?: ProviderHub;
   providersLamp?: (language: Language) => ConsoleLamp;
   /**
    * 浏览器端构建产物目录(含 asset-manifest.json)。缺省取仓库的 `dist/web`。
@@ -538,7 +605,7 @@ const hasPort = (h: string): boolean => /:\d+$/.test(h);
 const barePort = (h: string): string => h.replace(/:\d+$/, '');
 
 /** 按 Host 校验 Origin；缺失 Origin 时放行，null、非法或主机不匹配时拒绝。 */
-function isForeignOrigin(origin: unknown, hostHeader: unknown): boolean {
+function isForeignOrigin(origin: unknown, hostHeader: unknown, allowedHosts: readonly string[] = []): boolean {
   if (typeof origin !== 'string' || origin === '') return false;
   if (origin === 'null') return true; // 沙箱 iframe / file:// 一类,不是本控制台
   let originHost: string;
@@ -547,6 +614,8 @@ function isForeignOrigin(origin: unknown, hostHeader: unknown): boolean {
   } catch {
     return true;
   }
+  // 反向代理改写 Host 时 Origin 与 Host 不同名；操作员点名的对外名字照样算本站。
+  if (namesHost(allowedHosts, originHost)) return false;
   const host = typeof hostHeader === 'string' ? hostHeader : '';
   if (!originHost || !host) return true;
   if (originHost === host) return false;
@@ -555,17 +624,35 @@ function isForeignOrigin(origin: unknown, hostHeader: unknown): boolean {
   return true;
 }
 
+/** 表里的名字可带端口也可不带；不带端口的匹配任意端口。比较不分大小写。 */
+function namesHost(names: readonly string[], host: string): boolean {
+  const full = host.toLowerCase();
+  const bare = barePort(full);
+  return names.some((name) => {
+    const n = name.trim().toLowerCase();
+    return n !== '' && (n === full || n === bare);
+  });
+}
+
+/** 对端地址是不是本机回环(含 IPv4 映射的 IPv6 写法)。 */
+function isLoopbackPeer(address: string | undefined): boolean {
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]']);
 
 /**
- * Host 头必须是回环名或显式绑定的地址；绑定通配地址时不校验 Host。
+ * Host 头必须是回环名或显式绑定的地址。DNS rebinding 让外站页面的 Origin 与 Host 同名,
+ * 同源闸门因此失效;这一关把请求钉在浏览器真正访问的名字上。绑到通配地址即操作员
+ * 已选择对外露面,不校验。
  */
-function isAllowedHost(hostHeader: unknown, listenHost: string): boolean {
+function isAllowedHost(hostHeader: unknown, listenHost: string, allowedHosts: readonly string[] = []): boolean {
   if (WILDCARD_HOSTS.has(listenHost)) return true;
   if (typeof hostHeader !== 'string' || hostHeader === '') return false;
   const name = barePort(hostHeader).toLowerCase();
-  return LOOPBACK_HOSTS.has(name) || name === listenHost.toLowerCase() || name === `[${listenHost.toLowerCase()}]`;
+  return LOOPBACK_HOSTS.has(name) || name === listenHost.toLowerCase() || name === `[${listenHost.toLowerCase()}]`
+    || namesHost(allowedHosts, hostHeader);
 }
 
 /**
@@ -708,6 +795,8 @@ export class WebApp {
   private readonly deps: WebAppDeps;
   private readonly app: express.Express;
   private readonly listenHost: string;
+  private readonly allowedHosts: readonly string[];
+  private readonly auth: ConsoleAuth;
   /** 控制台页聚合。没挂 consolePageSources 时它也在,只是永远收到空清单。 */
   private readonly consolePages: ConsolePageRegistry;
   private readonly assets: ConsoleAssets;
@@ -726,6 +815,8 @@ export class WebApp {
   constructor(deps: WebAppDeps) {
     this.deps = deps;
     this.listenHost = deps.host ?? '127.0.0.1';
+    this.allowedHosts = deps.allowedHosts ?? [];
+    this.auth = new ConsoleAuth(deps.password ?? '', join(deps.dataDir, AUTH_KEY_FILE), deps.failedLoginDelayMs);
     this.language = deps.language ?? systemLanguage();
     this.webDistDir = deps.webDistDir ?? fileURLToPath(new URL('../../dist/web', import.meta.url));
     this.extensionAssets = deps.extensions?.consoleAssets?.() ?? [];
@@ -809,6 +900,7 @@ export class WebApp {
       supervised: this.deps.run?.supervised === true,
       extensions: !!this.deps.extensions,
       avatar: !!this.deps.botDir,
+      auth: this.auth.enabled,
     };
   }
 
@@ -932,6 +1024,29 @@ export class WebApp {
     }
   }
 
+  private authorized(req: { headers: Record<string, unknown> }): boolean {
+    return !this.auth.enabled || this.auth.verify(cookieValue(req.headers.cookie, SESSION_COOKIE));
+  }
+
+  /** 直连 HTTPS,或反向代理报告 X-Forwarded-Proto: https。 */
+  private overHttps(req: Request): boolean {
+    return req.secure || req.headers['x-forwarded-proto'] === 'https';
+  }
+
+  /** HTTPS 下加 Secure;HttpOnly 使页面脚本读不到令牌。 */
+  private sessionCookie(value: string, maxAgeSec: number, req: Request): string {
+    const secure = this.overHttps(req);
+    return `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAgeSec}${secure ? '; Secure' : ''}`;
+  }
+
+  private serveLogin(res: Response): void {
+    const file = fileURLToPath(new URL('./public/login.html', import.meta.url));
+    let html = readFileSync(file, 'utf8');
+    if (this.language === 'en') html = html.replace('<html lang="zh-CN">', '<html lang="en">');
+    res.setHeader('Cache-Control', 'no-store');
+    res.type('html').send(html);
+  }
+
   private safeSessionList(): SessionStats[] {
     try {
       return this.deps.sessions?.list() ?? [];
@@ -1086,7 +1201,7 @@ export class WebApp {
           socket.destroy();
           return;
         }
-        if (!isAllowedHost(req.headers.host, this.listenHost)) {
+        if (!isAllowedHost(req.headers.host, this.listenHost, this.allowedHosts)) {
           this.deps.log.warn('拒绝 Host 不在白名单的 WebSocket 连接', {
             path: pathname, host: String(req.headers.host),
           });
@@ -1094,13 +1209,18 @@ export class WebApp {
           return;
         }
         // 跨站页面开的 WS 不受同源策略限制,只能在 upgrade 这一关自己拦(见 isForeignOrigin)
-        if (isForeignOrigin(req.headers.origin, req.headers.host)) {
+        if (isForeignOrigin(req.headers.origin, req.headers.host, this.allowedHosts)) {
           this.deps.log.warn('拒绝跨站WebSocket连接', {
             path: pathname, origin: String(req.headers.origin),
           });
           socket.destroy();
           return;
         }
+        if (!this.authorized(req)) {
+          this.deps.log.warn('拒绝未登录的 WebSocket 连接', { path: pathname });
+          socket.destroy();
+          return;
+        }
         wss.handleUpgrade(req, socket, head, (ws) => {
           if (stream) {
             this.handleConsolePageStream(ws, stream.pageId, stream.panelId, this.languageOf(req));
@@ -1136,7 +1256,8 @@ export class WebApp {
     // 固定端口被占时顺延;0 交给 OS 分配且只尝试一次。
     //
     // 固定端口最多尝试 5 个候选端口。
-    const maxAttempts = port === 0 ? 1 : 5;
+    // 候选不越过 65535:listen(65536) 抛的是非法端口,会盖住真正的监听错误。
+    const maxAttempts = port === 0 ? 1 : Math.min(5, 65536 - port);
     let server: Server | null = null;
     let lastErr: unknown;
     for (let i = 0; i < maxAttempts; i++) {
@@ -1146,14 +1267,15 @@ export class WebApp {
         if (i > 0) {
           // 端口顺延记录 warn，便于发现预期端口被其他实例占用。
           this.deps.log.warn(
-            `端口 ${port} 被占用，改用 ${candidate}。`,
+            `端口 ${port} 被占用或不可监听，改用 ${candidate}。`,
           );
         }
         break;
       } catch (err) {
         lastErr = err;
         const code = (err as NodeJS.ErrnoException)?.code;
-        if (code !== 'EADDRINUSE' || port === 0) throw err;
+        // EACCES 与 EADDRINUSE 一样只说明这个候选端口此刻不能监听,成因不论(Windows 的排除端口段、权限、安全策略);试下一个,候选用尽时抛最后一个错误。
+        if ((code !== 'EADDRINUSE' && code !== 'EACCES') || port === 0) throw err;
       }
     }
     if (!server) {
@@ -1166,6 +1288,9 @@ export class WebApp {
     this.wss = wss;
     const actual = (server.address() as AddressInfo).port;
     this.deps.log.info(`web面板已启动 http://${this.listenHost}:${actual}/`);
+    if (!LOOPBACK_HOSTS.has(this.listenHost) && this.listenHost !== '::1' && !this.auth.enabled) {
+      this.deps.log.warn('控制台监听在非回环地址且没有设访问密码,能连到这个端口的人都能操作 bot', { host: this.listenHost });
+    }
     return actual;
   }
 
@@ -1202,7 +1327,7 @@ export class WebApp {
     app.disable('x-powered-by');
 
     app.use((req, res, next) => {
-      if (isAllowedHost(req.headers.host, this.listenHost)) {
+      if (isAllowedHost(req.headers.host, this.listenHost, this.allowedHosts)) {
         next();
         return;
       }
@@ -1218,7 +1343,7 @@ export class WebApp {
         next();
         return;
       }
-      if (!isForeignOrigin(req.headers.origin, req.headers.host)) {
+      if (!isForeignOrigin(req.headers.origin, req.headers.host, this.allowedHosts)) {
         next();
         return;
       }
@@ -1234,6 +1359,59 @@ export class WebApp {
         if (!res.headersSent) res.status(500).json({ error: String(err) });
       }
     };
+    // 登录、登出与状态三条路由在闸前;其余路由连同各自的 body 解析都在闸后。
+    app.get('/api/auth/status', wrap((req, res) => {
+      res.json({ required: this.auth.enabled, authenticated: this.authorized(req) });
+    }));
+    app.post('/api/auth/login', express.json(), (req: Request, res: Response) => {
+      void (async () => {
+        if (!this.auth.enabled) { res.json({ ok: true }); return; }
+        if (!this.overHttps(req) && !isLoopbackPeer(req.socket.remoteAddress)) {
+          this.deps.log.warn('登录请求从非回环对端经明文连接送来,密码与登录态 Cookie 可被途中截获;公网使用请放在终结 HTTPS 的反向代理后面', { from: req.socket.remoteAddress });
+        }
+        const candidate = (req.body as { password?: unknown } | undefined)?.password;
+        if (typeof candidate !== 'string' || !(await this.auth.login(candidate))) {
+          this.deps.log.warn('控制台登录失败', { from: req.socket.remoteAddress });
+          res.status(401).json({ error: '密码不对' });
+          return;
+        }
+        res.setHeader('Set-Cookie', this.sessionCookie(this.auth.issue(), SESSION_COOKIE_MAX_AGE_SEC, req));
+        this.deps.log.info('控制台登录', { from: req.socket.remoteAddress });
+        res.json({ ok: true });
+      })().catch((err: unknown) => {
+        if (!res.headersSent) res.status(500).json({ error: String(err) });
+      });
+    });
+    app.post('/api/auth/logout', wrap((req, res) => {
+      res.setHeader('Set-Cookie', this.sessionCookie('', 0, req));
+      res.json({ ok: true });
+    }));
+    app.use((req, res, next) => {
+      if (this.authorized(req)) { next(); return; }
+      if (req.method === 'GET' && (req.path === '/' || req.path === '/index.html')) { this.serveLogin(res); return; }
+      res.setHeader(CONSOLE_AUTH_HEADER, 'required');
+      res.status(401).json({ error: '需要登录' });
+    });
+
+    const providerRoute = (handler: (hub: ProviderHub, req: Request) => unknown) => wrap(async (req, res) => {
+      if (!this.deps.providers) { res.status(503).json({ error: 'Provider configuration unavailable.' }); return; }
+      try { res.json((await handler(this.deps.providers, req)) ?? { ok: true });
+        if (req.method === 'POST' && /^\/api\/providers(?:$|\/[^/]+\/(save|delete|activate)$)/.test(req.path)) this.debugBroadcast({ t: 'status', status: this.safeStatus() });
+      }
+      catch (error) { res.status(error instanceof Error && 'status' in error && typeof error.status === 'number' ? error.status : 400).json({ error: error instanceof Error ? error.message : String(error) }); }
+    });
+    app.get('/api/providers', providerRoute((hub, req) => hub.list(this.languageOf(req))));
+    app.get('/api/provider-modules', providerRoute((hub, req) => hub.moduleList(this.languageOf(req))));
+    app.post('/api/provider-modules/config', express.json(), providerRoute((hub, req) => hub.groups(req.body.name || 'draft', req.body.entry, this.languageOf(req))));
+    app.post('/api/provider-modules/preview', express.json(), providerRoute((hub, req) => hub.preview(req.body.name, req.body.entry, req.body.panel, req.body.method, req.body.args ?? [], this.languageOf(req))));
+    app.get('/api/providers/:name', providerRoute((hub, req) => hub.detail(String(req.params.name), this.languageOf(req))));
+    app.post('/api/providers', express.json(), providerRoute((hub, req) => hub.save(null, req.body, this.languageOf(req))));
+    app.post('/api/providers/:name/save', express.json(), providerRoute((hub, req) => hub.save(String(req.params.name), req.body, this.languageOf(req))));
+    app.post('/api/providers/:name/delete', express.json(), providerRoute((hub, req) => hub.delete(String(req.params.name), req.body.expectedRevision)));
+    app.post('/api/providers/:name/activate', providerRoute((hub, req) => hub.activate(String(req.params.name), this.languageOf(req))));
+    app.post('/api/providers/:name/test', providerRoute((hub, req) => hub.action(String(req.params.name), 'test', this.languageOf(req))));
+    app.post('/api/providers/:name/models', providerRoute((hub, req) => hub.action(String(req.params.name), 'models', this.languageOf(req))));
+
     app.get('/api/status', wrap((_req, res) => {
       res.json({ ...this.safeStatus(), uptimeSec: Math.round(process.uptime()) });
     }));
@@ -1319,6 +1497,24 @@ export class WebApp {
       res.json(readTailRecordsWhere(join(this.deps.dataDir, 'runs', runId, 'log.jsonl'), limit, pred));
     }));
 
+    // 诊断包:一次导出把排查一场跑要看的记录收进一个 JSON。缺席的接缝那一段为空。
+    app.get('/api/diagnostics', wrap(async (req, res) => {
+      const dbg = this.deps.debug;
+      res.json(buildDiagnostics({
+        dataDir: this.deps.dataDir,
+        runId: dbg?.runId?.() ?? null,
+        exportedAt: new Date(),
+        status: this.deps.getStatus(),
+        session: dbg ? { messages: dbg.sessionMessages(), head: dbg.sessionHead?.() ?? [] } : null,
+        sessions: this.deps.sessions?.list() ?? [],
+        toolSchemas: dbg?.toolSchemas() ?? [],
+        events: this.deps.store.range({ limit: DIAGNOSTICS_TAIL }),
+        latestCursor: this.deps.store.latestCursor(),
+        worlds: (await this.deps.worlds?.(this.languageOf(req))) ?? [],
+        usage: this.deps.usage?.aggregate({ bucket: 'day' }) ?? null,
+      }));
+    }));
+
     app.get('/api/runs', wrap((_req, res) => {
       res.json({ current: this.deps.debug?.runId?.() ?? null, runs: readRunsIndex(join(this.deps.dataDir, 'runs', 'index.jsonl')) });
     }));
@@ -1387,6 +1583,7 @@ export class WebApp {
       })();
     });
 
+    // 开场引导只出现一次:控制台在操作员开口或按下那颗按钮时销掉标记。
     app.post('/api/onboarding/dismiss', wrap((_req, res) => {
       const src = this.deps.onboarding;
       if (!src) { res.status(503).json({ error: '开场引导标记不可用' }); return; }
@@ -1418,13 +1615,16 @@ export class WebApp {
       );
     });
 
-    // 重启 = 落下重启标志 + 规范关机。有没有启动器循环把它拉起来,回执里说明。
+    // 重启 = 落下重启标志 + 规范关机。有没有启动器循环把它拉起来、回来时投递是不是暂停的,回执里说明。
     app.post('/api/run/restart', (req: Request, res: Response) => {
       const supervised = this.deps.run?.supervised === true;
       const language = this.languageOf(req);
+      const text = pick(language, SERVER_TEXT);
       void this.respondPowerAction(
         res, language, this.deps.run?.restart, '重启控制不可用', '收到重启请求(人工操作)',
-        supervised ? pick(language, SERVER_TEXT).exitSupervised : pick(language, SERVER_TEXT).exitUnsupervised,
+        !supervised ? text.exitUnsupervised
+          : this.deps.run?.startsPaused ? text.exitSupervisedPaused
+          : text.exitSupervised,
       );
     });
 
@@ -1508,12 +1708,26 @@ export class WebApp {
         return;
       }
       try {
-        res.json({ hits: await src.search(strParam(req.query.q) ?? '', kind) });
+        res.json({ hits: await src.search(kind) });
       } catch (err) {
         res.status(502).json({ error: `npm 搜索失败: ${String(err)}` });
       }
     }));
 
+    app.get('/api/extensions/package', wrap(async (req, res) => {
+      const src = this.deps.extensions;
+      if (!src) { res.status(503).json({ error: '扩展管理不可用' }); return; }
+      const name = strParam(req.query.name)?.trim();
+      if (!name) { res.status(400).json({ error: '缺少包名' }); return; }
+      try {
+        res.json(await src.packageInfo(name));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // 包名不合法是请求的问题,其余当成 registry 那一头的问题
+        res.status(msg.includes('包名') ? 400 : 502).json({ error: msg });
+      }
+    }));
+
     app.post('/api/extensions/install', express.json(), wrap(async (req, res) => {
       const src = this.deps.extensions;
       if (!src) { res.status(503).json({ error: '扩展管理不可用' }); return; }

package/src/web/shared/client-panel.ts

@@ -423,10 +423,13 @@ export interface ConsolePromptImagesOptions {
 export interface ConsolePromptInputOptions {
   label?: string;
   placeholder?: string;
+  /** 底栏左侧的灰字。不给就不占字。 */
   hint?: string;
   disabled?: boolean;
   /** 发送键左侧的紧凑工具入口。节点所有权随 prompt input 一起结束。 */
   tools?: HTMLElement;
+  /** 底栏最左的入口，排在 `hint` 之前。节点所有权随 prompt input 一起结束。 */
+  leading?: HTMLElement;
   /** 图片通道。不给 = 不收图,`onSubmit` 的第二参恒为空数组。 */
   images?: ConsolePromptImagesOptions;
   /**
@@ -440,7 +443,7 @@ export interface ConsolePromptInput {
   el: HTMLDivElement;
   focus(): void;
   setDisabled(disabled: boolean): void;
-  /** 设置输入框占位文本；`null` 恢复初值。 */
+  /** 盖住输入框里的灰字。`null` 回到构造时给的那一句。 */
   setPlaceholder(text: string | null): void;
 }
 

package/src/web/shared/console-protocol.ts

@@ -14,6 +14,8 @@ export const CONSOLE_PROTOCOL_VERSION = 1;
  * WebSocket 构造器带不了头)。值是 `zh` / `en`;缺席或不认识时服务端用部署默认语言。
  */
 export const CONSOLE_LANGUAGE_HEADER = 'x-cortico-language';
+/** 设了访问密码而请求未登录时,401 响应带这个头;浏览器端据此回到入口页。 */
+export const CONSOLE_AUTH_HEADER = 'x-cortico-auth';
 export const CONSOLE_LANGUAGE_QUERY = 'language';
 
 /** world：World 控制面；llm：LLM 供应模块；persona：bot/Persona 控制面；memory：Persona 的 Memory 页。framework 为保留类别，不经贡献协议提供页面。 */
@@ -401,7 +403,8 @@ export interface ConsoleLampsResponse {
 }
 
 /**
- * 框架的 provider 状态灯键，与贡献页 id 使用不同的 kind。
+ * 「模型提供商」那一行的灯在灯表里的键。贡献方的 page id 是 `<kind>:<id>`,
+ * kind 取 world / llm / persona,因此这个键与谁都不撞。
  */
 export const PROVIDERS_LAMP_ID = 'framework:providers';
 

package/src/worlds/bilibili/README.md

@@ -113,7 +113,7 @@ B 站直播间协议只读接入。观众的弹幕、礼物、醒目留言、上
 
 World 在 `127.0.0.1` 启动独立页面：`GET /overlay` 是 OBS browser source，`GET /editor`
 是编辑器，`GET /stream` 是同源 SSE 数据面，`GET /assets/<id>` 提供上传素材。端口默认 7795，
-被占用时顺延,含配置端口最多尝试 5 个端口,并记录 warn。
+被占用或不可监听(`listen` 回 `EADDRINUSE` 或 `EACCES`)时顺延,含配置端口最多尝试 5 个端口,并记录 warn。
 编辑接口只接受浏览器携带的同源 `Origin` 与 JSON 请求，并限制请求体大小；
 服务不发送 wildcard CORS。设计和公告分别使用修订号做冲突检测，素材、设计与公告写入共用串行队列，
 避免保存过程中删除素材或后完成的旧请求覆盖新状态。

package/src/worlds/bilibili/overlay/server.ts

@@ -98,14 +98,16 @@ export class BilibiliOverlayServer {
         this.boundPort = (server.address() as AddressInfo).port;
         if (index > 0) {
           log.warn(
-            `B站 Overlay 端口 ${preferred} 被占用,改用 ${this.boundPort}`,
+            `B站 Overlay 端口 ${preferred} 被占用或不可监听,改用 ${this.boundPort}`,
           );
         }
         break;
       } catch (error) {
         lastError = error;
         server.close();
-        if ((error as NodeJS.ErrnoException)?.code !== 'EADDRINUSE' || preferred === 0) throw error;
+        const code = (error as NodeJS.ErrnoException)?.code;
+        // EACCES 与 EADDRINUSE 一样只说明这个候选端口此刻不能监听,成因不论(Windows 的排除端口段、权限、安全策略);试下一个,候选用尽时抛最后一个错误。
+        if ((code !== 'EADDRINUSE' && code !== 'EACCES') || preferred === 0) throw error;
       }
     }
     if (!this.http) throw lastError instanceof Error ? lastError : new Error('B站 Overlay 没有可用端口');

package/src/worlds/minecraft/ADAPT.md

@@ -0,0 +1,66 @@
+<!-- Owner: src/worlds/minecraft/mineflayer-fixes.ts -->
+
+# 版本适配
+
+Minecraft 服务端换一个版本,客户端这边要跟着改的事实记在这里:版本边界、认得出它的
+判据、改在哪、当时怎么量出来的。
+
+**接到「她走不动 / 动作被打回 / 某个动作忽然失效」这类报告,先读这一页。** 这类症状里
+客户端看得见的只有"位置包被打回",光读代码分不出是判据变了还是别的;下面每条都带着
+当时的实测数字,对得上就直接按那条走。
+
+## 1.21.11:包围盒贴着方块侧面的位置被拒,静默传送回
+
+**版本边界** Paper 1.21.8、1.21.9、1.21.10 收下贴面位置,1.21.11 拒。不带任何插件的
+原版 Paper 即可复现,与服务端分支(Leaves)、反作弊插件无关。
+
+**服务端的判据** 把玩家包围盒摆在离方块侧面缝隙 `g` 处发过去:
+
+| `g` | 服务端 |
+|---|---|
+| > 0(1e-7 也算) | 收下 |
+| = 0 或 < 0 | 回一个 `position` 包把人传回上一个好位置,**不打 `moved wrongly`** |
+
+竖直方向的判据不同:贴着地面顶面、贴着天花板底面都照收,只有真的插进去才被拒。
+
+**客户端为什么总是踩中** `prismarine-physics` 的 `AABB.computeOffsetX/Z` 把移动量削到
+"恰好贴上"。于是走到墙根、沿墙走、上一格台阶时贴着立面起跳,发出去的位置包缝隙恰好
+为零,每个物理刻都被打回,人钉在原地。
+
+**认得出它的样子**
+
+- 服务端日志干净:同时段别的玩家有 `moved wrongly`,bot 一条都没有
+- 每秒 1 到 9 个服务端 `position` 包,落点比当前位置略微靠后
+- 单次被放行的净位移 0.02 到 0.03 格
+- `goto-stall-probe` 里 `onGround=false`、三轴速度为零、y 停在起跳弧线中途的值
+  (贴墙起跳第一刻被收、第二刻被打回第一刻的位置),`controlKeys` 显示前进键一直按着
+
+**改法** `mineflayer-fixes.ts` 的 `installWallGap()`:替换 `prismarine-physics` AABB 原型上的
+`computeOffsetX` 与 `computeOffsetZ`,朝方块走的那一步停在离面 `WALL_GAP`(1e-5)处,已经
+贴着再往里走时退开同样距离;`computeOffsetY` 不动。bot 的物理与寻路器的判据模拟共用
+这一个类,改原型两处同时生效。原型上打 `Symbol.for` 标记,装几次都只改一次。
+
+**试过没用的**
+
+- 补上原版客户端 1.21.2+ 每刻发的 `tick_end`、按键变化时的 `player_input`、位置包里真实的
+  `hasHorizontalCollision`:三样一起上,打回次数不变
+- 压掉 mineflayer 收到传送后回的那个位置包、补发 `player_loaded`:与这条无关
+
+**验证** 不带插件的 Paper 1.21.11,八种一格台阶几何(斜角单块、正对与斜对高台、贴脸
+起步、头顶树冠):改前每场被打回 160 到 334 次、两场钉死;改后 16 场全部到达、打回
+零次,耗时与 1.20.6 同一量级。
+
+## 怎么量一条新的版本差异
+
+服务端改了移动判据时,别读反编译猜,直接问服务端:
+
+1. 取各版本的原版服务端 jar(Paper 的 `fill.papermc.io/v3/projects/paper/versions/<版本>/builds`),
+   一个版本一个进程,端口与存档都隔离。
+2. 关掉客户端物理(`bot.physicsEnabled = false`),手工写 `bot.entity.position` 把人摆到要
+   测的位置,数 400 毫秒内收到几个服务端 `position` 包。零个 = 服务端认,一个及以上 = 被拒。
+3. 缝隙按 0.05、1e-3、1e-5、1e-7、0、负值扫一遍;地面与空中各扫一次;水平与竖直分开扫
+   ——两个方向的判据可以不一样,1.21.11 就不一样。
+4. 同一套摆法在相邻版本上各跑一次,边界就出来了。
+
+台架在 `scratch/mc-bench/`(不入库):`rig.ts` 起真服务端配真执行器,`BENCH_JAR` 选服务端
+jar、`BENCH_VERSION` 选协议版本。