cortico 0.1.0

package/src/worlds/bilibili/config.ts

@@ -0,0 +1,185 @@
+import type { ConfigGroup } from '../../core/types.ts';
+import { cloneOverlayConfig } from './overlay/model.ts';
+
+export const BILIBILI_DEFAULTS = {
+  // enabled 由Persona的装配层显式开启。
+  enabled: false,
+  /** 直播间号;短号与真实房间号都行,World 自己换算 */
+  roomId: 0,
+  /** 登录 cookie 的 SESSDATA;空值使用匿名接入。 */
+  sessdata: '',
+  /** 礼物使用 flush 投递的金额门槛,单位元。 */
+  giftFlushYuan: 1,
+  /** 相同弹幕与常规礼物进入总线前的固定归并窗 */
+  coalesceWindowMs: 300,
+  /** 固定窗内累计到此数量时立即冲刷 */
+  coalesceMaxItems: 64,
+  /** 高能榜拥挤代理的开启/退出水位 */
+  audienceOnlineRankOn: 200,
+  audienceOnlineRankOff: 170,
+  /** 人数持续不高于退出线达到此时长后解除拥挤态,单位秒。 */
+  audienceReleaseHoldSec: 120,
+  /** 人数信号新鲜度与已拥挤时的最长陈旧保持 */
+  audienceSignalFreshSec: 90,
+  audienceActiveStaleHoldSec: 300,
+  audienceEventLineBudget: 114,
+  audienceEventTokenBudget: 1061,
+  /** 重要观众常规互动占总批预算的上限比例,同时受剩余额度限制。 */
+  audienceImportantShare: 0.5,
+  overlay: cloneOverlayConfig(),
+};
+
+export const BILIBILI_CONFIG_GROUP: ConfigGroup = {
+  id: 'world:bilibili',
+  owner: 'world:bilibili',
+  schema: {
+    type: 'object',
+    title: 'B 站直播间 · 接入',
+    description: '只读接入:弹幕、礼物、醒目留言、上舰、进场与人流读数。',
+    properties: {
+      'worlds.bilibili.roomId': {
+        type: 'integer',
+        title: '直播间号',
+        minimum: 0,
+        maximum: 4294967295,
+        'x-hot': false,
+        description: '短号或真实房间号皆可。改动需重启后生效。',
+      },
+      'worlds.bilibili.sessdata': {
+        type: 'string',
+        title: '登录凭证 SESSDATA',
+        'x-hot': false,
+        description:
+          '浏览器登录 bilibili 后的 SESSDATA cookie。留空使用匿名接入,观众身份可能被脱敏。修改后需重启。',
+      },
+      'worlds.bilibili.giftFlushYuan': {
+        type: 'number',
+        title: '礼物即时投递门槛',
+        minimum: 0,
+        maximum: 1000,
+        'x-suffix': '元',
+        'x-hot': true,
+        description: '达到此金额的礼物立即投递;其余礼物参与常规合批。',
+      },
+      'worlds.bilibili.coalesceWindowMs': {
+        type: 'integer',
+        title: '相同消息归并窗',
+        minimum: 0,
+        maximum: 2000,
+        multipleOf: 50,
+        'x-scale': 1000,
+        'x-suffix': 's',
+        'x-hot': true,
+        description: '相同弹幕与常规礼物在进入事件总线前合并;0 关闭。窗口固定且不续期,flush 事件不等待。',
+      },
+      'worlds.bilibili.coalesceMaxItems': {
+        type: 'integer',
+        title: '归并池硬上限',
+        minimum: 1,
+        maximum: 1000,
+        'x-suffix': '条',
+        'x-hot': true,
+        description: '固定窗内累计到此数量时立即输出归并结果,交给事件总线调度。',
+      },
+      'worlds.bilibili.audienceOnlineRankOn': {
+        type: 'integer',
+        title: '高能榜拥挤开启线',
+        minimum: 1,
+        maximum: 100000,
+        'x-suffix': '人',
+        'x-hot': true,
+        description: '高能榜人数达到此值时进入拥挤态；只有同批上下文也超预算才会开始筛选。',
+      },
+      'worlds.bilibili.audienceOnlineRankOff': {
+        type: 'integer',
+        title: '高能榜拥挤退出线',
+        minimum: 0,
+        maximum: 100000,
+        'x-suffix': '人',
+        'x-hot': true,
+        description: '人数持续不高于此值,达到退出等待时间后解除拥挤态。',
+      },
+      'worlds.bilibili.audienceReleaseHoldSec': {
+        type: 'integer',
+        title: '拥挤退出等待',
+        minimum: 1,
+        maximum: 1800,
+        'x-suffix': 's',
+        'x-hot': true,
+        description: '高能榜人数需持续不高于退出线的时长。',
+      },
+      'worlds.bilibili.audienceSignalFreshSec': {
+        type: 'integer',
+        title: '高能榜新鲜时间',
+        minimum: 1,
+        maximum: 3600,
+        'x-suffix': 's',
+        'x-hot': true,
+        description: '超过此时间未更新时标记为陈旧，但已拥挤状态可在最长保持期内继续生效。',
+      },
+      'worlds.bilibili.audienceActiveStaleHoldSec': {
+        type: 'integer',
+        title: '拥挤陈旧保持上限',
+        minimum: 1,
+        maximum: 3600,
+        'x-suffix': 's',
+        'x-hot': true,
+        description: '最后一次高能榜读数过去这么久后，旧的拥挤判定不再启用限流。',
+      },
+      'worlds.bilibili.audienceEventLineBudget': {
+        type: 'integer',
+        title: '观众事件行预算',
+        minimum: 1,
+        maximum: 5000,
+        'x-suffix': '行/批',
+        'x-hot': true,
+        description: '拥挤态下同批归并候选超过此行数才启用筛选。',
+      },
+      'worlds.bilibili.audienceEventTokenBudget': {
+        type: 'integer',
+        title: '观众事件 token 预算',
+        minimum: 1,
+        maximum: 100000,
+        'x-suffix': 'token/批',
+        'x-hot': true,
+        description: '拥挤态下同批归并候选超过此估算量才启用筛选。',
+      },
+      'worlds.bilibili.audienceImportantShare': {
+        type: 'number',
+        title: '重要观众常规互动预算比例',
+        minimum: 0.01,
+        maximum: 1,
+        'x-scale': 100,
+        'x-suffix': '%',
+        'x-hot': true,
+        description: '重要观众常规互动占总批预算的上限比例,同时受批次剩余额度限制。',
+      },
+      'worlds.bilibili.overlay.enabled': {
+        type: 'boolean',
+        title: '启用 Overlay',
+        'x-hot': false,
+        description: '在本机启动透明 Overlay 页面。改动需重启后生效。',
+      },
+      'worlds.bilibili.overlay.port': {
+        type: 'integer',
+        title: 'Overlay 端口',
+        minimum: 0,
+        maximum: 65535,
+        'x-hot': false,
+        description: '默认 7795；被占用时会自动顺延。0 表示随机空闲端口。',
+      },
+      'worlds.bilibili.overlay.agentNoticeMaxChars': {
+        type: 'integer',
+        title: 'Agent 公告字数上限',
+        minimum: 1,
+        maximum: 5000,
+        'x-suffix': '字',
+        'x-hot': true,
+        description: 'Agent 公告工具写入纯文本时的 Unicode 字符上限。',
+      },
+    },
+  },
+};
+
+/** config.json 的 `worlds.bilibili` 节。 */
+export type BilibiliConfigSection = typeof BILIBILI_DEFAULTS;

package/src/worlds/bilibili/console/client.ts

@@ -0,0 +1,202 @@
+/**
+ * B 站直播间 World 的浏览器扩展。
+ *
+ * `log` 保留直播间入站诊断。Overlay 编辑器由 World 的回环服务独立承载，
+ * 控制台只暴露入口链接。
+ *
+ * 轮询 state,按 total 差值追加事件。服务端响应类型在浏览器端声明,避免导入 Node 模块。
+ */
+
+import type { ConsoleClientBundle, ConsolePanelContext, ConsolePanel } from '../../../web/shared/client-panel.ts';
+
+export function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// ---------------------------------------------------------------------------
+// 服务端 `BilibiliWorld.console().invoke('log', 'state')` 的返回形状
+// ---------------------------------------------------------------------------
+
+interface BilibiliLiveStatus {
+  /** `stopped` / `connecting` / `connected` / `retrying` */
+  phase: string;
+  /** 配置里填的房间号(可能是短号) */
+  roomId: number;
+  /** 换算出的真实房间号;还没握手完就是 null */
+  realRoomId: number | null;
+  title: string | null;
+  living: boolean;
+  /** 登录凭证对应的自己的 uid;匿名接入时为 0 */
+  selfUid: number;
+  lastError: string | null;
+}
+
+/** 待投递的观众统计;计数项累加,其余字段保留最新值。 */
+interface BilibiliAggregate {
+  enter: number;
+  like: number;
+  freeGift: number;
+  watched: number | null;
+  online: number | null;
+  popularity: number | null;
+  fans: number | null;
+  likeTotal: number | null;
+}
+
+interface BilibiliLogState {
+  status: BilibiliLiveStatus | null;
+  /** 最近一窗弹幕均缺少有效 uid。 */
+  desensitized: boolean;
+  aggregate: BilibiliAggregate;
+  /** 最近事件的文本，按时间倒序排列。 */
+  recent: string[];
+  /** 记过的总条数(含已被上限挤掉的) */
+  total: number;
+  /** cmd → 条数,按条数降序;没进白名单也没进黑名单的 cmd 也在里面 */
+  counts: Array<[string, number]>;
+  audienceAdmission: {
+    trackedViewers: number;
+    qualifiedViewers: number;
+    crowd: { onlineRankCount: number | null; signalFresh: boolean; active: boolean };
+    totals: { input: number; selected: number; dropped: number; limitedBatches: number };
+    lastBatch: { limitingActive: boolean; input: number; selected: number } | null;
+    persistenceError: string | null;
+  };
+}
+
+const DESC = '直播间事件与各 cmd 计数。';
+
+const PHASE_TEXT: Record<string, string> = {
+  stopped: '未接入',
+  connecting: '连接中',
+  connected: '已接入',
+  retrying: '重连中',
+};
+
+const POLL_MS = 2000;
+/** 与服务端 RECENT_CAP 一致。 */
+const KEEP = 200;
+
+const logPanel: ConsolePanel = {
+  mount(ctx: ConsolePanelContext) {
+    const { ui, root } = ctx;
+    const card = ui.sheet({ title: '直播间事件', en: 'bilibili live', desc: DESC });
+    root.appendChild(card.el);
+
+    const err = ui.msgline();
+    const info = ui.h('div');
+    const gauges = ui.statgrid();
+    const view = ui.log({ max: KEEP, maxHeight: '320px', empty: '(等待直播间消息…)' });
+    const counts = ui.table({ head: ['cmd', '条数'] });
+    const btnEnd = ui.button('回到底部', { size: 'sm', onClick: () => view.scrollToEnd() });
+    const bar = ui.rowbar();
+    bar.append(ui.h('span', 'grow'), btnEnd);
+    card.body.append(err, info, gauges, bar, view.el, counts.el);
+
+    let shown = 0;
+
+    const setError = (text: string | null): void => {
+      err.textContent = text ?? '';
+      err.className = text ? 'msgline bad' : 'msgline';
+      err.hidden = !text;
+    };
+    setError(null);
+
+    const drawInfo = (st: BilibiliLogState): void => {
+      const s = st.status;
+      const room = s?.realRoomId
+        ? `${s.realRoomId}${s.roomId && s.roomId !== s.realRoomId ? `(短号 ${s.roomId})` : ''}`
+        : s?.roomId
+          ? `${s.roomId}(还没换算出真实房间号)`
+          : '未配置';
+      info.replaceChildren(ui.kv([
+        { k: '接入', v: PHASE_TEXT[s?.phase ?? 'stopped'] ?? s?.phase ?? '未接入' },
+        { k: '直播间', v: room },
+        { k: '标题', v: s?.title || '—' },
+        { k: '开播', v: ui.pill(s?.living ? '直播中' : '未开播', s?.living ? 'on' : 'off') },
+        {
+          k: '身份',
+          v: st.desensitized
+            ? ui.pill('近期弹幕缺少观众 uid', 'off')
+            : ui.pill(s?.selfUid ? `已登录(uid ${s.selfUid})` : '待观察', s?.selfUid ? 'on' : 'plain'),
+        },
+        ...(s?.lastError ? [{ k: '最近错误', v: s.lastError }] : []),
+      ]));
+    };
+
+    /** 服务端在生成投递正文后清零聚合计数。 */
+    const drawGauges = (agg: BilibiliAggregate, admission: BilibiliLogState['audienceAdmission']): void => {
+      const num = (v: number | null): string => (v === null ? '—' : ui.fmt.count(v));
+      const last = admission.lastBatch;
+      const limiter = admission.crowd.active
+        ? last?.limitingActive
+          ? `拥挤（上批保留 ${last.selected}/${last.input}）`
+          : '拥挤'
+        : last?.limitingActive
+          ? `未限流（上批保留 ${last.selected}/${last.input}）`
+          : '未限流';
+      gauges.replaceChildren(
+        ui.stat({ k: '待投递 · 进场', v: agg.enter, unit: '人' }),
+        ui.stat({ k: '待投递 · 点赞', v: agg.like, unit: '次' }),
+        ui.stat({ k: '待投递 · 免费礼物', v: agg.freeGift, unit: '个' }),
+        ui.stat({ k: '高能榜', v: num(admission.crowd.onlineRankCount ?? agg.online), unit: '人' }),
+        ui.stat({ k: '事件筛选', v: limiter }),
+        ui.stat({ k: '重要观众', v: admission.qualifiedViewers, unit: '人' }),
+        ui.stat({ k: '累计过滤', v: admission.totals.dropped, unit: '条' }),
+        ui.stat({ k: '看过', v: num(agg.watched) }),
+        ui.stat({ k: '人气', v: num(agg.popularity) }),
+        ui.stat({ k: '粉丝', v: num(agg.fans) }),
+      );
+    };
+
+    const drawCounts = (rows: BilibiliLogState['counts']): void => {
+      counts.clear(rows.length ? undefined : '(还没收到任何 cmd)');
+      for (const [cmd, n] of rows) counts.addRow([cmd, n]);
+    };
+
+    const appendNew = (st: BilibiliLogState): void => {
+      const fresh = Math.min(st.total - shown, st.recent.length);
+      if (fresh <= 0) {
+        shown = st.total;
+        return;
+      }
+      const chronological = [...st.recent].reverse();
+      for (const line of chronological.slice(chronological.length - fresh)) view.append(line);
+      shown = st.total;
+    };
+
+    let polling = false;
+    const poll = (): void => {
+      if (polling) return;
+      polling = true;
+      void ctx.invoke<BilibiliLogState>('state').then(
+        (st) => {
+          polling = false;
+          if (ctx.signal.aborted) return;
+          setError(null);
+          drawInfo(st);
+          drawGauges(st.aggregate, st.audienceAdmission);
+          drawCounts(st.counts);
+          appendNew(st);
+        },
+        (e: unknown) => {
+          polling = false;
+          if (ctx.signal.aborted) return;
+          setError(`读取直播间状态失败: ${errText(e)}`);
+        },
+      );
+    };
+
+    ctx.interval(poll, POLL_MS);
+    poll();
+  },
+};
+
+const bundle: ConsoleClientBundle = {
+  // 键是**局部** panel id,与服务端 `console().panels[].id` 一一对应。
+  panels: {
+    log: logPanel,
+  },
+};
+
+export default bundle;

package/src/worlds/bilibili/definition.ts

@@ -0,0 +1,35 @@
+import { join } from 'node:path';
+import type { WorldDefinition } from '../../world.ts';
+import { type BilibiliConfigSection, BILIBILI_DEFAULTS } from './config.ts';
+import { BilibiliWorld } from './world.ts';
+
+export const BILIBILI: WorldDefinition<BilibiliConfigSection> = {
+  id: 'bilibili',
+  label: 'B 站直播间',
+  defaults: () => structuredClone(BILIBILI_DEFAULTS),
+  create: (ctx) => {
+    const { cfg } = ctx;
+    return new BilibiliWorld({
+      roomId: cfg.roomId,
+      sessdata: cfg.sessdata,
+      giftFlushYuan: () => cfg.giftFlushYuan,
+      coalesceWindowMs: () => cfg.coalesceWindowMs,
+      coalesceMaxItems: () => cfg.coalesceMaxItems,
+      audienceOnlineRankOn: () => cfg.audienceOnlineRankOn,
+      audienceOnlineRankOff: () => cfg.audienceOnlineRankOff,
+      audienceReleaseHoldSec: () => cfg.audienceReleaseHoldSec,
+      audienceSignalFreshSec: () => cfg.audienceSignalFreshSec,
+      audienceActiveStaleHoldSec: () => cfg.audienceActiveStaleHoldSec,
+      audienceEventLineBudget: () => cfg.audienceEventLineBudget,
+      audienceEventTokenBudget: () => cfg.audienceEventTokenBudget,
+      audienceImportantShare: () => cfg.audienceImportantShare,
+      audienceLedgerFile: join(ctx.dataDir, 'bilibili-audience', 'ledger.json'),
+      overlay: cfg.overlay,
+      agentNoticeMaxChars: () => cfg.overlay.agentNoticeMaxChars,
+      agentNoticeFile: join(ctx.dataDir, 'bilibili-overlay', 'agent-notice.json'),
+      overlayAssetDir: join(ctx.dataDir, 'bilibili-overlay', 'assets'),
+      onOverlayConfig: (overlay) => ctx.persist({ overlay: { design: overlay.design } }),
+      timezone: ctx.timezone,
+    });
+  },
+};

package/src/worlds/bilibili/gift-frame.ts

@@ -0,0 +1,131 @@
+/**
+ * `SEND_GIFT_V2` 的 protobuf 帧 → V1 的 JSON 字段形状。
+ *
+ * 此层将 protobuf 字段映射到 V1 的 JSON 名称，使 normalize、overlay/project 共用处理路径，并支持 V1/V2 共存及帧回放。
+ *
+ * 字段号依据实采帧推断，未有官方 schema；映射如下：
+ *
+ * ```
+ * 顶层
+ *    1  uid          送礼人
+ *    2  uname
+ *    3  face         头像 URL
+ *    8  medal        粉丝牌:5=等级 6=牌名。**可能是别的房间的牌子**
+ *   10  gift         礼物体,见下
+ *   15  sender       送礼人完整档案(1=uid,2={1=名字,2=头像})
+ * 礼物体(顶层 10)
+ *    1  giftId    2 giftName   3 num   4 giftType(动画礼物=2)
+ *  5/6/7 金瓜子三槽,见 coinTotal
+ *    8  coin_type("gold"=付费,"silver"=免费)
+ *    9  tid(这一笔的交易号,V1 同名字段同形)
+ *   12  combo_id  14 连击累计金瓜子(100/200/400/600 这样递增,**不是单笔**)
+ *   18  动作词("投喂")
+ * ```
+ *
+ * 以下字段不填：
+ *
+ * - `guard_level`:粉丝牌里那个档位(medal.12)是**牌子所属房间**的舰长等级,
+ *   不能作为本房间的舰长等级。
+ * - `is_admin`:尚未确认对应的 protobuf 字段。
+ */
+import { pbFromBase64, pbInt, pbSub, pbText, type PbField } from './protobuf.ts';
+
+/** 由调用方记录解析告警。 */
+type GiftFrameWarn = (message: string, data?: Record<string, unknown>) => void;
+
+/**
+ * V1 data 原样返回;V2 返回补齐 V1 字段名的副本。V2 缺少礼物体或名称时返回原 data。
+ */
+export function giftFrameData(
+  data: Record<string, unknown>,
+  warn?: GiftFrameWarn,
+): Record<string, unknown> {
+  if (text(data.giftName) || text(data.gift_name)) return data;
+  const top = pbFromBase64(data.pb);
+  const gift = pbSub(top, 10);
+  const giftName = pbText(gift, 2);
+  if (!gift || !giftName) {
+    if (data.pb !== undefined) {
+      warn?.('SEND_GIFT_V2 缺少有效礼物体或礼物名', {
+        decoded: top !== null,
+        giftBody: gift !== null,
+      });
+    }
+    return data;
+  }
+  const sender = pbSub(top, 15);
+  const senderBase = pbSub(sender, 2);
+  const uid = pbInt(top, 1) ?? pbInt(sender, 1);
+  const uname = pbText(top, 2) || pbText(senderBase, 1);
+  const face = pbText(top, 3) || pbText(senderBase, 2);
+  const num = pbInt(gift, 3);
+  const coinType = pbText(gift, 8);
+  const totalCoin = coinTotal(gift, num, giftName, warn);
+  const giftId = pbInt(gift, 1);
+  const tid = pbText(gift, 9);
+  return {
+    ...data,
+    ...(uid !== undefined ? { uid } : {}),
+    ...(uname ? { uname } : {}),
+    giftName,
+    ...(giftId !== undefined ? { giftId } : {}),
+    ...(num !== undefined ? { num } : {}),
+    ...(coinType ? { coin_type: coinType } : {}),
+    ...(totalCoin !== undefined ? { total_coin: totalCoin } : {}),
+    ...(tid ? { tid } : {}),
+    sender_uinfo: senderUinfo(top, uid, uname, face),
+  };
+}
+
+function senderUinfo(
+  top: readonly PbField[] | null,
+  uid: number | undefined,
+  uname: string,
+  face: string,
+): Record<string, unknown> {
+  const medal = pbSub(top, 8);
+  const medalLevel = pbInt(medal, 5);
+  const medalName = pbText(medal, 6);
+  const hasMedal = medalLevel !== undefined || medalName !== '';
+  return {
+    ...(uid !== undefined ? { uid } : {}),
+    base: {
+      ...(uname ? { name: uname } : {}),
+      ...(face ? { face } : {}),
+    },
+    ...(hasMedal
+      ? {
+          medal: {
+            ...(medalLevel !== undefined ? { level: medalLevel } : {}),
+            ...(medalName ? { name: medalName } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * 金瓜子字段映射尚未确认,暂取字段 5/6/7 中正数的最大值作为 fallback。
+ * 有效值不相等或已知 num 不为 1 时告警。
+ */
+function coinTotal(
+  gift: readonly PbField[],
+  num: number | undefined,
+  giftName: string,
+  warn?: GiftFrameWarn,
+): number | undefined {
+  const slots = [5, 6, 7]
+    .map((field) => pbInt(gift, field))
+    .filter((value): value is number => value !== undefined && value > 0);
+  if (slots.length === 0) return undefined;
+  const total = Math.max(...slots);
+  const settled = slots.every((value) => value === total) && (num ?? 1) === 1;
+  if (!settled) {
+    warn?.('SEND_GIFT_V2 金瓜子字段映射未确认,暂取最大值', { gift: giftName, slots, num });
+  }
+  return total;
+}
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}