cortico 0.1.0

package/src/world.ts

@@ -0,0 +1,449 @@
+/**
+ * 按 WorldDefinition 构造实例，依据 worlds.<id>.enabled 挂载，并提供运行时激活、停用和重启。
+ * 挂载状态与启动状态分开，实际启动由 Core 管理。定义实例在停用和重启时重新构造；
+ * 预建实例重启时复用原对象。名称、标签与缺失原因来自定义或 bot 声明。
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CoreConfig, World, WorldLifecycleEvent } from './core/types.ts';
+import type { LoadedConfig } from './core/config.ts';
+import type { BotDefinition } from './bot.ts';
+import { updateJsonObject } from './config-file.ts';
+import { pick, type Language } from './core/language.ts';
+
+/** 装配层给控制台的回执与拒绝理由,按发起请求的界面语言取。 */
+const ASSEMBLY_TEXT = {
+  zh: {
+    constructFailed: (detail: string) => `构造失败: ${detail}`,
+    notImplemented: '本地没有找到这个 World 的实现。',
+    unknownWorld: (id: string) => `未知 World: ${id}`,
+    alreadyRunning: (label: string) => `${label} 已启用`,
+    prebuilt: (label: string) => `${label} 是预建实例,不经装配层激活`,
+    activated: (label: string, id: string) => `${label}（${id}）已启用`,
+    deactivated: (label: string, id: string) => `${label}（${id}）已停用`,
+    notActive: (label: string) => `${label} 未激活,没有可重启的实例`,
+    restarted: (label: string) => `${label} 已重启`,
+    toolClash: (other: string, names: string[]) => `工具名与 ${other} 撞名,拒绝挂载: ${names.join(', ')}`,
+    toolReserved: (names: string[]) => `工具名已被 Core 或 Persona 占用,拒绝挂载: ${names.join(', ')}`,
+    unbound: '装配层尚未绑定 core',
+  },
+  en: {
+    constructFailed: (detail: string) => `Construction failed: ${detail}`,
+    notImplemented: 'No implementation of this World was found locally.',
+    unknownWorld: (id: string) => `Unknown World: ${id}`,
+    alreadyRunning: (label: string) => `${label} is already enabled`,
+    prebuilt: (label: string) => `${label} is a prebuilt instance and is not activated through assembly`,
+    activated: (label: string, id: string) => `${label} (${id}) enabled`,
+    deactivated: (label: string, id: string) => `${label} (${id}) disabled`,
+    notActive: (label: string) => `${label} is not active, so there is no instance to restart`,
+    restarted: (label: string) => `${label} restarted`,
+    toolClash: (other: string, names: string[]) => `Tool names clash with ${other}, refusing to mount: ${names.join(', ')}`,
+    toolReserved: (names: string[]) => `Tool names are taken by Core or the Persona, refusing to mount: ${names.join(', ')}`,
+    unbound: 'The assembly layer is not bound to a core yet',
+  },
+};
+const text = (language: Language) => pick(language, ASSEMBLY_TEXT);
+
+/** 每个 World 配置段的最小形状。 */
+export interface WorldSection {
+  enabled: boolean;
+}
+
+export type DeepPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
+/** 装配层提供给 World 构造函数的上下文。 */
+export interface WorldContext<S extends WorldSection = WorldSection> {
+  readonly id: string;
+  /** worlds.<id> 的共享引用；每次读取的配置立即生效，构造时保存的值需重启实例。 */
+  readonly cfg: S;
+  readonly timezone: string;
+  readonly botName: string;
+  /** 部署目录，保存本机配置、密钥和部署资产覆盖。 */
+  readonly botDir: string;
+  /** bot 代码包目录，供包内模板与资产使用，可由多个部署共享。 */
+  readonly packageDir: string;
+  readonly dataDir: string;
+  readonly repoRoot: string;
+  secret(name: string): string;
+  /** 将密钥写入部署 .env，并更新进程环境供 secret() 立即读取。 */
+  storeSecret(name: string, value: string): void;
+  /** 深合并进 `worlds.<id>` 段:活对象与 config.json 同步。数组整体替换。 */
+  persist(patch: DeepPartial<S>): void;
+  /** 按 cfg.enabled 同步状态：启用时激活或重启，禁用时停止。 */
+  restart(): Promise<void>;
+}
+
+export interface WorldDefinition<S extends WorldSection = WorldSection> {
+  id: string;
+  label: string;
+  /** World 配置默认值，每次返回新对象；enabled=false，由 bot 声明或部署配置启用。 */
+  defaults(): S;
+  /** 激活前置检查。抛错 = 不能激活,错误信息原样给操作者。 */
+  preflight?(ctx: WorldContext<S>): void;
+  /**
+   * 返回 x-options 的完整选项表，包含按请求语言生成的固定项。
+   * 未知 kind 返回空数组，框架继续查询其他 World；当前值不在表中时由控制台补入。
+   * Persona 的选项由 Bot ConsoleContribution 提供。
+   */
+  configOptions?(kind: string, language: Language): Array<{ value: string; label: string }>;
+  create(ctx: WorldContext<S>): World;
+}
+
+/**
+ * bot 默认使用的 World 声明。字符串是 World id；对象还可提供标签与缺失原因。
+ * 两种声明均允许本地缺少实现。
+ */
+export type WorldDeclaration = string | { id: string; label: string; reason?: string };
+
+/** 各 World 的默认配置段；已声明的 id 默认启用。 */
+export function worldDefaults(
+  definitions: readonly WorldDefinition<WorldSection>[],
+  declares: readonly WorldDeclaration[],
+  overrides: Record<string, Record<string, unknown>> = {},
+): Record<string, WorldSection> {
+  const declared = new Set(declares.map((d) => (typeof d === 'string' ? d : d.id)));
+  const worlds: Record<string, WorldSection> = {};
+  for (const def of definitions) {
+    worlds[def.id] = { ...def.defaults(), enabled: declared.has(def.id), ...(overrides[def.id] ?? {}) };
+  }
+  return worlds;
+}
+
+/**
+ * 将可用 World 定义加入 bot。对 defaults() 中缺失的 World 段补充默认值，
+ * 已声明的 id 默认启用，其余默认关闭；已有配置段保持原样。
+ */
+export function withWorlds<C extends CoreConfig>(
+  definition: BotDefinition<C>,
+  definitions: readonly WorldDefinition<WorldSection>[],
+): BotDefinition<C> {
+  const declared = new Set((definition.declares ?? []).map((d) => (typeof d === 'string' ? d : d.id)));
+  return {
+    ...definition,
+    worlds: definitions,
+    defaults: () => {
+      const config = definition.defaults();
+      const worlds = ((config as unknown as { worlds?: Record<string, WorldSection> }).worlds ??= {});
+      for (const def of definitions) worlds[def.id] ??= { ...def.defaults(), enabled: declared.has(def.id) };
+      return config;
+    },
+  };
+}
+
+export interface WorldSlot {
+  readonly id: string;
+  readonly label: string;
+  /** bot 声明过的渠道;false = 部署侧选配。 */
+  readonly declared: boolean;
+  /** null = 预建实例(不能重建,只能停/起)。 */
+  readonly definition: WorldDefinition<WorldSection> | null;
+  instance: World;
+  mounted: boolean;
+}
+
+export interface MissingWorld {
+  readonly id: string;
+  readonly label: string;
+  /** 缺失的原因,按界面语言给;bot 声明里自带的理由不翻译。 */
+  readonly reason: (language: Language) => string;
+  /** Persona声明过的渠道。缺省 true:声明了却没实现的那类。 */
+  readonly declared?: boolean;
+}
+
+export interface PrebuiltOptions {
+  /** 控制台显示名;缺省用 id。 */
+  labels?: Record<string, string>;
+  /** 按 bot 声明的渠道算(缺省)还是按部署侧选配算。 */
+  declared?: boolean;
+}
+
+/** Core 构造后绑定挂载与卸载方法。 */
+export interface WorldMountHost {
+  mount(mod: World): Promise<void>;
+  unmount(id: string): Promise<void>;
+  /** 装配层改了一个槽位的挂载状态(激活 / 停用 / 重启)。启动期的初始挂载不报。 */
+  lifecycle?(event: WorldLifecycleEvent): void;
+  /**
+   * Core 保留帧与 Persona 自有工具的名称。绑定时检查已挂载实例，
+   * 冲突实例移入 missing；后续激活、重启和添加预建实例同样检查。
+   */
+  reservedToolNames?(): readonly string[];
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** 就地深合并:叶子替换,沿途对象身份保持,数组整体替换。 */
+function assignDeep(target: Record<string, unknown>, patch: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue;
+    const current = target[key];
+    if (isPlainObject(value) && isPlainObject(current)) assignDeep(current, value);
+    else target[key] = isPlainObject(value) ? structuredClone(value) : value;
+  }
+}
+
+function writeEnvLine(envPath: string, name: string, value: string): void {
+  const prev = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+  const line = `${name}=${value}`;
+  const pattern = new RegExp(`^[ \\t]*${name}\\s*=.*$`, 'm');
+  const next = pattern.test(prev)
+    ? prev.replace(pattern, line)
+    : (prev.trimEnd() ? `${prev.trimEnd()}\n${line}\n` : `${line}\n`);
+  writeFileSync(envPath, next, 'utf8');
+}
+
+export class WorldAssembly {
+  /** 挂载表。与 core 共用同一个数组,激活/停用就地增删。 */
+  readonly mounted: World[] = [];
+  readonly slots: WorldSlot[] = [];
+  readonly missing: MissingWorld[] = [];
+  private host: WorldMountHost | null = null;
+  private readonly cfgPath: string;
+
+  constructor(
+    private readonly loaded: LoadedConfig<CoreConfig>,
+    worlds: readonly WorldDefinition<WorldSection>[],
+    declares: readonly WorldDeclaration[],
+  ) {
+    this.cfgPath = join(loaded.rootDir, 'config.json');
+    const declared = new Set<string>();
+    for (const decl of declares) declared.add(typeof decl === 'string' ? decl : decl.id);
+    const defined = new Set(worlds.map((m) => m.id));
+    for (const def of worlds) {
+      const section = this.section(def);
+      let instance: World;
+      try {
+        instance = def.create(this.context(def));
+      } catch (error) {
+        // 单个定义构造失败记入 missing，继续构造其他 World。
+        const detail = error instanceof Error ? error.message : String(error);
+        this.missing.push({
+          id: def.id,
+          label: def.label,
+          declared: declared.has(def.id),
+          reason: (language) => text(language).constructFailed(detail),
+        });
+        continue;
+      }
+      const clash = section.enabled ? this.toolClash(instance, this.mounted) : null;
+      if (clash) {
+        this.missing.push({ id: def.id, label: def.label, declared: declared.has(def.id), reason: clash });
+        continue;
+      }
+      const slot: WorldSlot = {
+        id: def.id,
+        label: def.label,
+        declared: declared.has(def.id),
+        definition: def,
+        instance,
+        mounted: false,
+      };
+      this.slots.push(slot);
+      if (section.enabled) {
+        slot.mounted = true;
+        this.mounted.push(slot.instance);
+      }
+    }
+    for (const decl of declares) {
+      if (typeof decl === 'string') {
+        if (!defined.has(decl)) this.missing.push({ id: decl, label: decl, reason: (language) => text(language).notImplemented });
+        continue;
+      }
+      if (defined.has(decl.id)) continue;
+      const given = decl.reason;
+      this.missing.push({ id: decl.id, label: decl.label, reason: given ? () => given : (language) => text(language).notImplemented });
+    }
+  }
+
+  /** 只有预建实例的槽位表(测试与开发态用):不读配置,不写 config.json。 */
+  static ofInstances(instances: readonly World[], opts: PrebuiltOptions = {}): WorldAssembly {
+    const loaded = {
+      config: { worlds: {} } as unknown as CoreConfig,
+      secret: () => '',
+      rootDir: '',
+      memoryDir: '',
+      dataDir: '',
+    } satisfies LoadedConfig<CoreConfig>;
+    const assembly = new WorldAssembly(loaded, [], []);
+    assembly.addPrebuilt(instances, opts);
+    return assembly;
+  }
+
+  /** 预建实例初始挂载，重启复用原对象；同 id 时替换原定义实例。 */
+  addPrebuilt(instances: readonly World[], opts: PrebuiltOptions = {}): void {
+    for (const mod of instances) {
+      const existing = this.slots.findIndex((s) => s.id === mod.id);
+      if (existing >= 0) {
+        const old = this.slots[existing];
+        if (old.mounted) this.mounted.splice(this.mounted.indexOf(old.instance), 1);
+        this.slots.splice(existing, 1);
+      }
+      const clash = this.toolClash(mod, this.mounted);
+      if (clash) throw new Error(clash('zh'));
+      this.slots.push({
+        id: mod.id,
+        label: opts.labels?.[mod.id] ?? mod.id,
+        declared: opts.declared ?? true,
+        definition: null,
+        instance: mod,
+        mounted: true,
+      });
+      this.mounted.push(mod);
+    }
+  }
+
+  /** 绑定 Core 后检查保留名称，冲突的已挂载实例移入 missing。 */
+  bind(host: WorldMountHost): void {
+    this.host = host;
+    for (const slot of [...this.slots]) {
+      if (!slot.mounted) continue;
+      const clash = this.toolClash(slot.instance, []);
+      if (!clash) continue;
+      this.mounted.splice(this.mounted.indexOf(slot.instance), 1);
+      this.slots.splice(this.slots.indexOf(slot), 1);
+      this.missing.push({ id: slot.id, label: slot.label, declared: slot.declared, reason: clash });
+    }
+  }
+
+  slot(id: string, language: Language = 'zh'): WorldSlot {
+    const slot = this.slots.find((s) => s.id === id);
+    if (!slot) throw new Error(text(language).unknownWorld(id));
+    return slot;
+  }
+
+  /** 所有槽位的实例(含未挂载的),给控制台拼面板、提示词文档与配置组用。 */
+  instances(): World[] {
+    return this.slots.map((s) => s.instance);
+  }
+
+  labelOf(id: string): string | undefined {
+    return this.slots.find((s) => s.id === id)?.label;
+  }
+
+  /** 三个动作的回执与拒绝理由按 `language` 给;省略 = 中文。 */
+  async activate(id: string, language: Language = 'zh'): Promise<string> {
+    const t = text(language);
+    const slot = this.slot(id, language);
+    if (slot.mounted) return t.alreadyRunning(slot.label);
+    const def = slot.definition;
+    if (!def) throw new Error(t.prebuilt(slot.label));
+    const ctx = this.context(def);
+    def.preflight?.(ctx);
+    const clash = this.toolClash(slot.instance, this.mounted);
+    if (clash) throw new Error(clash(language));
+    this.persist(id, { enabled: true });
+    try {
+      await this.mountHost().mount(slot.instance);
+    } catch (error) {
+      this.persist(id, { enabled: false });
+      slot.instance = def.create(ctx);
+      throw error;
+    }
+    slot.mounted = true;
+    this.host?.lifecycle?.({ kind: 'mounted', id, label: slot.label });
+    return t.activated(slot.label, id);
+  }
+
+  async deactivate(id: string, language: Language = 'zh'): Promise<string> {
+    const slot = this.slot(id, language);
+    const wasMounted = slot.mounted;
+    if (wasMounted) await this.stopSlot(slot);
+    this.persist(id, { enabled: false });
+    if (wasMounted) this.host?.lifecycle?.({ kind: 'unmounted', id, label: slot.label });
+    return text(language).deactivated(slot.label, id);
+  }
+
+  async restart(id: string, language: Language = 'zh'): Promise<string> {
+    const slot = this.slot(id, language);
+    if (!slot.mounted) throw new Error(text(language).notActive(slot.label));
+    await this.stopSlot(slot);
+    const clash = this.toolClash(slot.instance, this.mounted);
+    if (clash) throw new Error(clash(language));
+    await this.mountHost().mount(slot.instance);
+    slot.mounted = true;
+    this.host?.lifecycle?.({ kind: 'restarted', id, label: slot.label });
+    return text(language).restarted(slot.label);
+  }
+
+  /** 按 worlds.<id>.enabled 同步状态，供 WorldContext.restart 调用。 */
+  async sync(id: string): Promise<void> {
+    const slot = this.slot(id);
+    const enabled = (slot.definition ? this.section(slot.definition) : { enabled: true }).enabled;
+    if (enabled) {
+      if (slot.mounted) await this.restart(id);
+      else await this.activate(id);
+    } else if (slot.mounted) {
+      await this.stopSlot(slot);
+      this.host?.lifecycle?.({ kind: 'unmounted', id, label: slot.label });
+    }
+  }
+
+  private async stopSlot(slot: WorldSlot): Promise<void> {
+    await this.mountHost().unmount(slot.id);
+    slot.mounted = false;
+    if (slot.definition) slot.instance = slot.definition.create(this.context(slot.definition));
+  }
+
+  /** 工具名在 bot 内唯一。与保留名称或已挂载 World 工具冲突时拒绝挂载。 */
+  private toolClash(mod: World, mounted: readonly World[]): ((language: Language) => string) | null {
+    const names = new Set(mod.tools().map((t) => t.name));
+    const reserved = (this.host?.reservedToolNames?.() ?? []).filter((n) => names.has(n));
+    if (reserved.length) return (language) => text(language).toolReserved(reserved);
+    for (const other of mounted) {
+      const shared = other.tools().map((t) => t.name).filter((n) => names.has(n));
+      if (shared.length) {
+        const label = this.labelOf(other.id) ?? other.id;
+        return (language) => text(language).toolClash(label, shared);
+      }
+    }
+    return null;
+  }
+
+  private mountHost(): WorldMountHost {
+    if (!this.host) throw new Error(text('zh').unbound);
+    return this.host;
+  }
+
+  /** `worlds.<id>` 活引用;缺段时按定义默认值补一段。 */
+  private section(def: WorldDefinition<WorldSection>): WorldSection {
+    const worlds = ((this.loaded.config as unknown as { worlds?: Record<string, WorldSection> }).worlds ??= {});
+    return (worlds[def.id] ??= def.defaults());
+  }
+
+  private persist(id: string, patch: Record<string, unknown>): void {
+    const worlds = (this.loaded.config as unknown as { worlds: Record<string, Record<string, unknown>> }).worlds;
+    assignDeep(worlds[id], patch);
+    updateJsonObject(this.cfgPath, (raw) => {
+      const rawIo = (raw.worlds ??= {}) as Record<string, Record<string, unknown>>;
+      const section = (rawIo[id] ??= {});
+      assignDeep(section, patch);
+    });
+  }
+
+  private context<S extends WorldSection>(def: WorldDefinition<S>): WorldContext<S> {
+    const { loaded } = this;
+    const cfg = loaded.config;
+    return {
+      id: def.id,
+      cfg: this.section(def as unknown as WorldDefinition<WorldSection>) as S,
+      timezone: cfg.timezone,
+      botName: cfg.displayName,
+      botDir: loaded.rootDir,
+      packageDir: loaded.packageDir ?? loaded.rootDir,
+      dataDir: loaded.dataDir,
+      repoRoot: loaded.repoRoot ?? loaded.rootDir,
+      secret: (name) => loaded.secret(name),
+      storeSecret: (name, value) => {
+        writeEnvLine(join(loaded.rootDir, '.env'), name, value);
+        process.env[name] = value;
+      },
+      persist: (patch) => this.persist(def.id, patch as Record<string, unknown>),
+      restart: () => this.sync(def.id),
+    };
+  }
+}

package/src/worlds/bilibili/ENV_PROMPT.md

@@ -0,0 +1,5 @@
+你接入了一个 B 站直播间
+观众看到的画面比现场晚 5 到 8 秒，注意下延迟
+你可以用 `bilibili_set_announcement` 更新直播画面上的写字板，最多 {{bilibili.agentAnnouncementLimit}} 字
+当前写字板内容：{{bilibili.agentAnnouncement | （暂无内容）}}
+可以把你当前的目标/直播内容，或者别的你想写的更新在写字板。更新之前要通知外界。

package/src/worlds/bilibili/README.md

@@ -0,0 +1,176 @@
+<!-- Owner: src/worlds/bilibili/definition.ts -->
+
+# worlds/bilibili
+
+B 站直播间协议只读接入。观众的弹幕、礼物、醒目留言、上舰、进场与人流读数从这里进事件流；
+同一 World 提供本机透明 Overlay。唯一工具 `bilibili_set_announcement` 只写本机 Agent 公告栏，
+不会向 B 站账号发送弹幕或执行平台操作。
+
+“重要观众”指符合 UID 资格、在限流时优先分配上下文预算的观众。资格、拥挤状态、事件分组与人物档案召回由 [`audience-admission.ts`](audience-admission.ts) 管理；阈值和预算在 [`config.ts`](config.ts)。资格变化不删除 Memory 中的人物档案。具体条件见「重要观众与实时限流」。
+
+## 分层
+
+| 文件 | 职责 |
+|---|---|
+| [`wire.ts`](wire.ts) | 16 字节帧头的编解码;`op=5` 且 protover 2/3 时包体是压缩过的另一串完整包,解析是递归的 |
+| [`client.ts`](client.ts) | 握手四步 + wss 长连 + 30s 心跳 + 退避重连 |
+| [`normalize.ts`](normalize.ts) | 原始 cmd → 归一化产物(事件 / 计数 / 读数 / 不推)。纯函数 |
+| [`protobuf.ts`](protobuf.ts) | 按字段号与 wire type 读取 protobuf；无法解析时返回 null |
+| [`gift-frame.ts`](gift-frame.ts) | `SEND_GIFT_V2` 的 pb blob → V1 字段形状。两种帧共用下游 |
+| [`coalescing-buffer.ts`](coalescing-buffer.ts) | 相同弹幕与常规礼物进入事件总线前的固定窗归并 |
+| [`audience-admission.ts`](audience-admission.ts) | 按 UID 记录优先资格，以高能榜和批次预算决定是否筛选，并分配三类事件的上下文额度 |
+| [`world.ts`](world.ts) | 投递分档、人流聚合、公告工具、控制台数据面与 Overlay 接线 |
+| [`overlay/`](overlay/) | 设计模型、用户组匹配、原始事件显示、素材、公告持久化、loopback HTTP/SSE、运行页与独立编辑器 |
+| [`console/`](console/) | 直播间入站诊断 `log`；Overlay 编辑入口由 World 链接提供 |
+
+帧压缩使用 `node:zlib`，WBI 签名使用 `node:crypto` 的 md5，WebSocket 使用 `ws`。protobuf 读取器按已核对的字段编号解析；本项目没有官方 `.proto` schema。
+
+## 接入协议
+
+本 World 使用 B 站 web 直播协议，按返回的 uid 识别观众。该接口非官方开放平台接口，字段可能变化，接入也可能受风控限制。
+
+## 送礼帧:V1 与 V2 并存
+
+`SEND_GIFT` 使用 V1 JSON 字段；`SEND_GIFT_V2` 的 `data.pb` 是 base64 编码的 protobuf，`data` 还可含 `dmscore`。[`gift-frame.ts`](gift-frame.ts) 将 V2 解码为 V1 字段结构，包括 `giftName`、`num`、`coin_type`、`total_coin`、`uname` 与 `sender_uinfo`。帧中已有 V1 字段时沿用 V1 路径。
+
+字段编号没有官方 schema，映射来自 `bilibili-raw-samples.jsonl` 的实际接收帧。回归夹具位于 [`tests/worlds/bilibili/gift-v2-frames.ts`](../../../tests/worlds/bilibili/gift-v2-frames.ts)，保留原始布局并替换身份字段。V1 接收帧和同结构夹具也用于回放与测试。
+
+**读取失败不能降级为计数。** 只有明确读出 `coin_type` 且不是 gold 时才计为免费礼物；读取失败仍生成事件，正文省略金额并告警。
+
+握手四步(全在 `client.ts`):
+
+1. `x/frontend/finger/spi` 取非空 `buvid3`
+2. `x/web-interface/nav` 取 WBI 密钥与登录 uid
+3. `Room/get_info` 将短房间号转换为认证包使用的真实房间号
+4. `getDanmuInfo`(WBI 签名)拿弹幕服务器列表与 token
+
+## 登录凭证与观众身份
+
+`worlds.bilibili.sessdata` 保存浏览器登录后的 SESSDATA cookie，位于部署的 `config.json`，不进入版本控制。匿名连接仍可接收弹幕；已观测到匿名响应将观众 uid 置为 0，并对昵称脱敏。`uid=0` 时不生成 `senderKey`，昵称不作为稳定身份键。
+
+已有弹幕且最近至多 20 条均缺少有效 uid 时,控制台显示「近期弹幕缺少观众 uid」。
+
+登录态以服务端返回的 `LiveStatus.selfUid` 为准，0 表示匿名。已配置 `sessdata` 但仍为匿名时，每次接入至多记录一次 error。
+
+## 接入日志
+
+- **归并统计**：`info 直播间归并折叠` 按分钟汇总 `folds`、`sourceItems` 和 `windowMs`，停机时记录剩余不足一分钟的统计。
+- **筛选统计**：`warn 直播间准入筛除` 逐批记录筛除量、候选量、限流状态与本场累计量。
+- **存储失败**：`warn B站观众准入账本落盘失败` 由 `onPersistError` 报告。
+
+## 投递分档
+
+事件按 `trigger` 决定是否唤醒以及是否参与合批。人流读数在投递时生成正文。
+
+| 事件 | 唤醒 | 说明 |
+|---|---|---|
+| `bilibili.superchat` | flush | 醒目留言 |
+| `bilibili.guard` | flush | 上舰 |
+| `bilibili.gift` | flush / debounce | 金额 ≥ `worlds.bilibili.giftFlushYuan` 走 flush,低于它先过短窗归并再排常规合批 |
+| `bilibili.guard-renew` | debounce | 续费 |
+| `bilibili.danmaku` | debounce | 弹幕 |
+| `bilibili.enter-guard` | debounce | 舰长进场(普通进场只计数) |
+| `bilibili.block` | debounce | 观众被禁言 |
+| `bilibili.room` | flush / debounce | 开播、下播、全员禁言走 flush;标题变更 debounce |
+| `bilibili.feed` | flush / debounce | 弹幕接入中断超过 60 秒成文一次(flush),恢复时补一条带中断时长(debounce);60 秒内的抖动不推 |
+| `bilibili.warning` | flush | 超管警告与切断；World 仅投递事件 |
+| `bilibili.superchat-del` | piggyback | |
+| `bilibili.audience` | piggyback + **投递成文** | 人流读数 |
+
+进场、点赞和免费礼物累计次数；看过、在线、人气与粉丝数记录接收时的读数。它们在 World 内累积，经 `pushDeferred` 随下一批事件投递，并在渲染正文后清零。待投递期间不重复登记；超过 5 分钟未渲染时允许重新登记。
+
+`normalize.ts` 的 `IGNORED` 列出不投递的 cmd，包括运营挂件、连麦玩法、全站广播及自身语音转写。未识别的 cmd 仍按原名称计数，并显示在控制台。
+
+## 相同消息归并
+
+弹幕与低于插队门槛的付费礼物在写事件库和总线前经过固定窗。窗口默认 300ms，从池内首件
+起算且不因后续消息续期；累计到 64 条立即冲刷。任何不能归并的事件与 `flush` 都是顺序屏障：
+先按各组首件的到达顺序冲刷旧池，再立即写入该事件。停机同样先冲刷并取消定时器。
+
+弹幕以「稳定 UID + 去掉首尾空白后的正文」逐字匹配，大小写、内部空白和 Unicode 形式均不改写；**不同观众发同一句话不合并**。礼物只合并礼物流中连续出现的同一稳定 UID、同一礼物名和单价，累计笔数、件数与金额；另一位送礼人或另一种礼物结束该连续段，普通弹幕不打断礼物段。无稳定 UID 的礼物逐笔投递，不凭昵称猜身份。匿名接入时弹幕没有稳定身份键，按正文合并。
+单件仍使用原正文、昵称和 `senderKey`；两件以上写成 `[弹幕×N|昵称] 正文`；礼物写成 `[礼物×N笔 ¥合计|昵称] 礼物×总件数`，保留送礼人姓名与组级 `senderKey`。昵称必须进入归并正文，因为私有 `meta` 不渲染给 agent。
+参与者的稳定 `senderKey`、昵称与原始条数保留在组级私有 `meta`，供人物档案逐人召回。Overlay 与控制台日志在原始消息到达时逐条更新，不等待归并窗。
+
+控制台 `log.state.coalescing` 报告输入量、输出量、已合并量、冲刷次数、容量冲刷次数与当前池内条数。`worlds.bilibili.coalesceWindowMs` 和 `worlds.bilibili.coalesceMaxItems` 支持热改；窗口设为 0 时关闭等待，逐条输出。
+
+## 重要观众与实时限流
+
+优先资格只使用稳定 UID，满足任一条件即可获得：舰队身份的正向记录保留 35 天；单条 SC 不低于 ¥30，或 30 天内累计不低于 ¥50；30 天内至少一场直播有 25 个去重活跃分钟。互动所需分钟数与场次数可配置。SC 与互动资格自命中起保留 30 天。
+
+账本位于 `data/bilibili-audience/ledger.json`，记录 UID、时间、金额、活跃分钟和用于跨批分配的等待计数（`fairDebt`）；不存昵称或消息正文。记录在归并和筛选前更新。脏账本每 30 秒至多保存一次，停机强制保存；运行期保存失败时报警，保留未保存状态并在后续更新时重试。
+
+高能榜用于判断拥挤状态，不等同于在线人数。默认达到 200 时进入拥挤态，连续 120 秒不高于 170 时退出；信号超过 300 秒未更新后不再维持拥挤态，下播或切换直播代次时清零。只有拥挤态且同批候选超过 114 行或 1,061 个估算 token 时才筛选，否则全部进入上下文。
+
+筛选时分为三组：
+
+- `critical`：平台警告、开关播、SC、上舰/续费与达到即时投递金额门槛的礼物全部保留，可超过批次预算。
+- `important`：任一参与者具有优先资格的合并组整体归入此组。按跨批等待计数分配，最多使用所配置行数和 token 预算的 50%，同时受全批剩余额度限制。
+- `ordinary`：其余事件按持久保存的私有盐确定性抽样，使用剩余额度。
+
+原始事件均以 `archive-only` 保存，供历史查询；筛选结果进入 Agent 上下文。控制台报告高能榜、拥挤与限流状态、重要观众数和累计筛除量。
+
+## Overlay
+
+World 在 `127.0.0.1` 启动独立页面：`GET /overlay` 是 OBS browser source，`GET /editor`
+是编辑器，`GET /stream` 是同源 SSE 数据面，`GET /assets/<id>` 提供上传素材。端口默认 7795，
+被占用时顺延,含配置端口最多尝试 5 个端口,并记录 warn。
+编辑接口只接受浏览器携带的同源 `Origin` 与 JSON 请求，并限制请求体大小；
+服务不发送 wildcard CORS。设计和公告分别使用修订号做冲突检测，素材、设计与公告写入共用串行队列，
+避免保存过程中删除素材或后完成的旧请求覆盖新状态。
+
+组件类型：
+
+- 横向或纵向弹幕机，准入可选弹幕、礼物、弹幕+礼物；用户名与内容可分别限制显示字数，礼物包含免费礼物、付费礼物、SC 与舰队事件。
+- 横向或纵向滚动公告、固定公告、Agent 公告；多行滚动公告可设置每行停留时间和行间切换时长，滚动内容在运动方向的两端渐隐。
+- HTTPS/HTTP 外部图片或上传图片，支持 contain/cover/fill。
+
+组件可带独立标题。标题占据上、右、下或左侧边带，支持起点、居中、终点对齐，并拥有独立的
+字体、字号、字重、RGBA 颜色与描边。Agent 公告更新时按 Unicode 字符逐字显示并保留输入光标；
+弹幕机 Mock 会持续混合注入弹幕和礼物，组件工作区的 Mock 测试只写入预览运行器，不改设计、
+真实公告或直播事件流。
+
+内置样式为天蓝色、海军蓝、白色与极简，全部默认尖角。自定义样式可分别配置用户名和正文的
+字体、字号、字重、RGBA 颜色与描边。Nine-slice 将源图四条切线与输出边框宽度分开保存；
+编辑器可在源图上拖动切线，并用可缩放的实际组件预览验证拉伸、平铺和中心填充。
+
+用户组规则是递归 `all`/`any` 组合。可匹配 uid、舰队等级、粉丝牌、房管、VIP/SVIP、
+用户等级以及实测弹幕结构中的排名和颜色字段；最高优先级的匹配组覆写用户名与正文样式。
+头像优先使用消息携带的 `sender_uinfo`/富用户信息，经典弹幕没有头像时显示昵称首字占位。
+
+设计保存在部署配置 `worlds.bilibili.overlay.design`，由装配层的 `onOverlayConfig` 原子写回。
+上传素材位于 `data/bilibili-overlay/assets/`，文件名是内容哈希；只接受经魔数确认的 PNG、JPEG、
+WebP 与 GIF，单文件上限 8 MiB。Agent 公告单独原子保存到
+`data/bilibili-overlay/agent-notice.json`，工具写入后以独立 SSE 事件更新公告节点，不会清空
+正在滚动的弹幕。公告内容在下一次主会话前缀重建时通过 `ENV_PROMPT.md` 占位符同步； World 不会
+为了每次公告写入强制重建前缀。
+
+## 控制台
+
+控制台提供直播间事件诊断和独立 Overlay 编辑器入口。样式、组件与布局编辑共享草稿、撤销历史和保存操作。草稿预览复用 OBS 渲染器，支持拖动、八向缩放、网格、画布与组件吸附、层级、可见性和锁定；编辑控件与选择框不进入 `/overlay` 输出。
+
+从主 Web 页面打开编辑器时，语义调色板通过 URL fragment 传递。编辑器内置浅色和深色默认调色板，主 Web 停止后仍可通过独立 URL 打开。画布背景的浅深设置只保存在本机，不写入设计数据。
+
+配置项包括直播间号、登录凭证、礼物即时投递门槛、相同消息归并窗与容量上限，以及 Overlay
+启用、端口和 Agent 公告字数上限。
+
+日志面板每 2 秒轮询 `log.state`。`total` 是累计记录数，包括已超出 `RECENT_CAP` 而从缓冲移除的记录；客户端按差值追加新行，保留滚动位置。
+
+目录名 `worlds/bilibili` 的末段必须与 World id `bilibili` 对得上:浏览器产物的 asset key 由目录名推导
+(`src/worlds/<x>/console/client.ts` → `world:<x>`),而控制台按 provider id `world:bilibili` 去取它。
+两边对不上时页面上出现的是"声明了面板,但没有构建出浏览器扩展"。
+
+## 字段待校
+
+以下 cmd 尚未用实际接收帧验证，字段形状来自社区文档：
+`ROOM_BLOCK_MSG`(禁言)、`ROOM_SILENT_ON/OFF`、`WARNING`、`CUT_OFF`。
+
+已用接收帧核对的 cmd 包括 `DANMU_MSG`、`USER_TOAST_MSG_V2`、`INTERACT_WORD_V2`、`LIKE_INFO_V3_*`、`WATCHED_CHANGE`、
+`ONLINE_RANK_COUNT`、`ROOM_REAL_TIME_MESSAGE_UPDATE`、`STOP_LIVE_ROOM_LIST`。
+
+`INTERACT_WORD_V2` 使用 protobuf；当前解析未区分进场、关注和分享，均计为进场。
+
+## 接入限制
+
+- 握手失败后按指数退避重连，等待从 2 秒起加倍，最多 60 秒。状态轮询遇到 HTTP 412 时将下一次轮询延后 10 分钟。412 / -352 作为风控错误报告。
+- 连接看门狗在平台开播时检查 `connecting`，以及没有重试定时器的 `retrying` 状态；持续 60 秒无结果后重新连接。它不检查 `connected` 状态下长期收不到业务消息的情况。
+- Web 协议字段可能变化；`IGNORED` 之外的新 cmd 会显示在控制台计数中。