cortico 0.1.0

package/src/worlds/qq/ENV_PROMPT.md

@@ -0,0 +1,5 @@
+你在QQ上。
+
+下面是你正在参与的会话:
+{{qq.conversations | (还没有配置任何监听的群或私聊。)}}
+{{qq.identity | (与QQ的连接尚未建立,群名和你的账号信息暂时未知。)}}

package/src/worlds/qq/config.ts

@@ -0,0 +1,108 @@
+import type { ConfigGroup } from '../../core/types.ts';
+import type { VisionConfig } from './vision.ts';
+
+/** 关闭的 roster 条目仍持久化并显示,仅从监听集合中排除。 */
+export interface QQRosterEntry {
+  id: number;
+  enabled: boolean;
+}
+
+export const QQ_DEFAULTS = {
+  enabled: false,
+  /** NapCat 正向 WS 地址 */
+  wsUrl: 'ws://127.0.0.1:3001',
+  groups: [] as QQRosterEntry[],
+  privates: [] as QQRosterEntry[],
+  token: '',
+} as const;
+
+/**
+ * 本 World 需要的密钥的**环境变量名**。辅助视觉用的是 OpenRouter——
+ * core 不认识这个名字,装配层照 World 声明的名字取值。
+ */
+export const QQ_SECRETS = { vision: 'OPENROUTER_API_KEY' } as const;
+
+/**
+ * 本 World 声明的可调项。只声明**World 自己**的参数:连接与监听名单有
+ * 专用面板(要卡片式增删、要重启),这里放的是自带视觉的行为旋钮。
+ */
+export const QQ_CONFIG_GROUP: ConfigGroup = {
+  id: 'world:qq',
+  owner: 'world:qq',
+  schema: {
+    type: 'object',
+    title: 'QQ · 辅助视觉',
+    description: '图片描述写入事件库。',
+    properties: {
+      'worlds.qq.vision.enabled': {
+        type: 'boolean',
+        title: '开启辅助视觉',
+        'x-hot': false,
+        description: '关掉后图片只留可读占位。需要重启生效(装配时才创建视觉服务),且需要配好 OPENROUTER_API_KEY。',
+      },
+      'worlds.qq.vision.model': {
+        type: 'string',
+        title: 'VLM 模型',
+        'x-hot': false,
+        description: 'OpenRouter 上的模型名。重启生效。',
+      },
+      'worlds.qq.vision.concurrency': {
+        type: 'integer',
+        title: '被动识图并发',
+        minimum: 1,
+        maximum: 16,
+        multipleOf: 1,
+        'x-suffix': '路',
+        'x-hot': true,
+        description: '同时最多跑几张图的识别。',
+      },
+      'worlds.qq.vision.dedupPrecheckMs': {
+        type: 'integer',
+        title: '去重预判等待上限',
+        minimum: 0,
+        maximum: 30_000,
+        multipleOf: 100,
+        'x-suffix': 'ms',
+        'x-hot': true,
+        description: '消息渲染前检查图片是否重复的最长等待时间。命中时引用已有图片，下载失败时标记失败；'
+          + '新图片或超时先显示占位，识图结果另行投递。',
+      },
+      'worlds.qq.vision.maxImageBytes': {
+        type: 'integer',
+        title: '图片下载上限',
+        minimum: 65_536,
+        maximum: 104_857_600,
+        multipleOf: 65_536,
+        'x-scale': 1_048_576,
+        'x-suffix': 'MB',
+        'x-hot': true,
+        description: '超过这个大小的图不下载、不识别。',
+      },
+      'worlds.qq.vision.timeoutMs': {
+        type: 'integer',
+        title: 'VLM 请求超时',
+        minimum: 1000,
+        maximum: 300_000,
+        multipleOf: 1000,
+        'x-scale': 1000,
+        'x-suffix': 's',
+        'x-hot': false,
+        description: '单次识别请求的超时。重启生效(客户端构造时固定)。',
+      },
+    },
+  },
+};
+
+/** config.json 的 `worlds.qq` 节。 */
+export interface QQConfigSection {
+  enabled: boolean;
+  /** NapCat 正向 WS 地址 */
+  wsUrl: string;
+  /** 群 roster,逐项热更新;关闭的条目仍持久化并显示,但不参与监听。 */
+  groups: QQRosterEntry[];
+  /** 监听的私聊 QQ 号 roster,语义同 groups */
+  privates: QQRosterEntry[];
+  /** OneBot access token,可空 */
+  token: string;
+  vision: VisionConfig;
+}

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

@@ -0,0 +1,126 @@
+/**
+ * QQ World 的浏览器扩展 —— 接入门 / 监听名单 / 事件三个面板。
+ *
+ * 这个文件只做两件事:**装配**(把三个面板接到局部 id 上)与**共享 helper**
+ * (三个面板都要的取数—渲染骨架、类型、错误措辞)。面板本体各在自己的文件里。
+ *
+ * 与外界的依赖只有一条:`client-panel.ts` 里的**类型**。没有 import 控制台内部
+ * 模块,没有 `fetch`,没有 `document.body`,没有 `window.__*`——数据面一律走
+ * `ctx.invoke`,DOM 一律用 `ctx.ui` 的原语,定时器一律走 `ctx.interval`。
+ *
+ * `style.css` 是本 provider 自己的样式:只放 `ctx.ui` 没有对应原语的那几块布局
+ * (名单卡片的网格、字段标签),用 `qq-` 前缀避开控制台的通用 class,
+ * 变量取自控制台的主题变量,所以浅深色两套皮都跟着走。
+ */
+
+import type {
+  ConsoleClientBundle,
+  ConsolePanelContext,
+} from '../../../web/shared/client-panel.ts';
+import './style.css';
+import { gatePanel } from './gate.ts';
+import { rosterPanel } from './roster.ts';
+import { eventsPanel } from './events.ts';
+
+// ---------------------------------------------------------------------------
+// 共享类型:服务端 `QQWorld.invokePanel` 各方法的返回形状
+// ---------------------------------------------------------------------------
+
+/** `gate.state` */
+export interface QQGateState {
+  enabled: boolean;
+  wsUrl: string;
+  tokenSet: boolean;
+  connected: boolean;
+  selfId: number | null;
+  nickname: string;
+  groups: QQGroupName[];
+  privates: QQPrivateName[];
+}
+
+interface QQGroupName {
+  id: number;
+  name: string;
+  card: string;
+}
+
+interface QQPrivateName {
+  id: number;
+  name: string;
+}
+
+/** `roster.names` / `events.names`:号码 → 人看得懂的名字 */
+export interface QQConvNames {
+  groups: QQGroupName[];
+  privates: QQPrivateName[];
+}
+
+/** `roster.get` 的一条。关掉的条目仍留在名单里,只是不进监听集合。 */
+export interface QQRosterEntry {
+  id: number;
+  enabled: boolean;
+}
+
+export interface QQRoster {
+  groups: QQRosterEntry[];
+  privates: QQRosterEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// 共享 helper
+// ---------------------------------------------------------------------------
+
+/** 错误 → 一句人话。`ConsoleInvokeError` 带的就是服务端的中文措辞。 */
+export function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export interface AutoloadOptions<T> {
+  /** 取数期间铺的空态措辞 */
+  loading: string;
+  /** 取数失败时空态的前半句,后面接错误原文 */
+  failed: string;
+  load(): Promise<T>;
+  /**
+   * 画出来。`reload` 重跑一遍取数与渲染——面板改完自己的状态之后调它,
+   * 而不是去重挂面板(那会连同定时器与滚动位置一起重来)。
+   */
+  render(data: T, reload: () => void): Node[];
+}
+
+/**
+ * 三个面板共用的取数—渲染骨架：空态 → 取数 → 渲染或错误空态。
+ * 请求代号防止晚到的旧响应覆盖新响应；unmount 后到达的异步拒绝不再写 DOM。
+ */
+export function autoload<T>(ctx: ConsolePanelContext, opts: AutoloadOptions<T>): void {
+  const { ui, root } = ctx;
+  let generation = 0;
+  const run = (): void => {
+    const gen = ++generation;
+    root.replaceChildren(ui.placeholder(opts.loading));
+    void opts.load().then(
+      (data) => {
+        if (gen !== generation || ctx.signal.aborted) return;
+        root.replaceChildren(...opts.render(data, run));
+      },
+      (err: unknown) => {
+        if (gen !== generation || ctx.signal.aborted) return;
+        root.replaceChildren(ui.placeholder(`${opts.failed}: ${errText(err)}`));
+      },
+    );
+  };
+  run();
+}
+
+// ---------------------------------------------------------------------------
+
+const bundle: ConsoleClientBundle = {
+  // 键是**局部** panel id,与服务端 `console().panels[].id` 一一对应。
+  panels: {
+    gate: gatePanel,
+    roster: rosterPanel,
+    events: eventsPanel,
+  },
+};
+
+export default bundle;

package/src/worlds/qq/console/events.ts

@@ -0,0 +1,155 @@
+/**
+ * 面板 `events` —— 事件库里 `source=qq` 的历史,按会话翻。
+ *
+ * 只读面板:选会话、翻记录、改条数上限、刷新。离线(NapCat 没连上)也能看,
+ * 因为它读的是事件库而不是协议端。
+ *
+ * 选中的会话与条数上限记在 `ctx.memo` 里(按 `provider:panel` 命名空间隔离),
+ * 所以离开面板再回来还在原处。
+ */
+
+import type {
+  ConsolePanelContext,
+  ConsolePanel,
+} from '../../../web/shared/client-panel.ts';
+import { autoload, type QQConvNames } from './client.ts';
+
+/** 事件 type → 列表里那颗药丸上的字。不认识的 type 原样显示。 */
+const TYPE_LABEL: Record<string, string> = {
+  'qq.message': '消息',
+  'qq.self': '我',
+  'qq.recall': '撤回',
+  'qq.member': '成员',
+  'qq.emoji': '表情',
+  'qq.poke': '戳一戳',
+  'qq.vision': '识图',
+  'qq.watch': '监听',
+  'qq.forward': '转发',
+  'qq.reply.uncaptured': '引用',
+};
+
+/** 服务端把它夹在 1..2000 之间,这里只给几个常用挡位。 */
+const LIMITS = ['100', '300', '1000', '2000'] as const;
+const DEFAULT_LIMIT = '300';
+
+interface QQConvSummary {
+  kind: 'group' | 'private';
+  id: number;
+  count: number;
+  lastTs: string;
+}
+
+interface QQLeanEvent {
+  cursor: number;
+  type: string;
+  ts: string;
+  text: string;
+  senderKey: string;
+  senderName: string;
+  conv: { kind?: string; id?: number } | null;
+}
+
+interface QQEventList {
+  conversations: QQConvSummary[];
+  events: QQLeanEvent[];
+  total: number;
+}
+
+interface EventsView {
+  list: QQEventList;
+  names: QQConvNames;
+}
+
+const NO_NAMES: QQConvNames = { groups: [], privates: [] };
+
+export const eventsPanel: ConsolePanel = {
+  mount(ctx: ConsolePanelContext) {
+    // `''` = 全部会话
+    let conv = ctx.memo.get<string>('conv', '');
+    let limit = ctx.memo.get<string>('limit', DEFAULT_LIMIT);
+
+    autoload<EventsView>(ctx, {
+      loading: '加载 QQ 事件…',
+      failed: 'QQ 事件不可用',
+      load: async () => ({
+        list: await ctx.invoke<QQEventList>('list', [{ conv, limit: Number(limit) }]),
+        names: await ctx.invoke<QQConvNames>('names').catch(() => NO_NAMES),
+      }),
+      render: (view, reload) => [
+        sheet(ctx, view, {
+          conv,
+          limit,
+          pick: (next) => { conv = next; ctx.memo.set('conv', next); reload(); },
+          setLimit: (next) => { limit = next; ctx.memo.set('limit', next); reload(); },
+          reload,
+        }),
+      ],
+    });
+  },
+};
+
+interface Controls {
+  conv: string;
+  limit: string;
+  pick(conv: string): void;
+  setLimit(limit: string): void;
+  reload(): void;
+}
+
+function sheet(ctx: ConsolePanelContext, view: EventsView, ctl: Controls): HTMLElement {
+  const { ui } = ctx;
+  const card = ui.sheet({
+    title: 'QQ 事件',
+    en: '分群 / 私聊',
+    desc: `事件库里 source=qq 的历史,按会话查看(离线也能翻)。共 ${view.list.total} 条。`,
+  });
+
+  // 会话切换:与控制台画面板页签同一套做法(一行按钮,选中的那颗上主色)
+  const tabs = ui.rowbar();
+  const tab = (label: string, value: string): HTMLButtonElement =>
+    ui.button(label, {
+      size: 'sm',
+      variant: ctl.conv === value ? 'primary' : 'plain',
+      onClick: () => { if (ctl.conv !== value) ctl.pick(value); },
+    });
+  tabs.appendChild(tab('全部', ''));
+  for (const c of view.list.conversations) {
+    tabs.appendChild(tab(`${convName(view.names, c)} (${c.count})`, `${c.kind}:${c.id}`));
+  }
+  card.body.appendChild(tabs);
+
+  const bar = ui.rowbar();
+  bar.append(
+    ui.h('span', 'grow'),
+    ui.chip(`本页 ${view.list.events.length}`),
+    ui.select({
+      value: ctl.limit,
+      options: LIMITS.map((n) => ({ value: n, label: `最近 ${n} 条` })),
+      onInput: (v) => ctl.setLimit(v),
+    }),
+    ui.button('↻ 刷新', { size: 'sm', onClick: () => ctl.reload() }),
+  );
+  card.body.appendChild(bar);
+
+  const table = ui.table({ head: ['#', '类型', '正文'], maxHeight: 'calc(100vh - 360px)' });
+  if (!view.list.events.length) table.clear('(无事件)');
+  for (const e of view.list.events) {
+    table.addRow([
+      { text: `#${e.cursor}`, cls: 'mono' },
+      { el: ui.pill(TYPE_LABEL[e.type] ?? e.type, 'plain') },
+      { text: e.text || '', cls: 'txt' },
+    ]);
+  }
+  card.body.appendChild(table.el);
+  return card.el;
+}
+
+/** 会话在页签上的名字:能查到就用群名/称呼,否则退回号码。 */
+function convName(names: QQConvNames, c: QQConvSummary): string {
+  if (c.kind === 'group') {
+    const g = names.groups.find((x) => x.id === c.id);
+    return `群 ${g?.name || c.id}`;
+  }
+  const p = names.privates.find((x) => x.id === c.id);
+  return `私聊 ${p?.name || c.id}`;
+}

package/src/worlds/qq/console/gate.ts

@@ -0,0 +1,232 @@
+/**
+ * 面板 `gate` —— 接入门:接入开关 + 连接状态 + NapCat 连接。
+ *
+ * 三张卡靠同一份 `gate.state`,一次取数。改开关或改连接都会**真重启进程**,
+ * 所以这里还带着重启期间的等待与回来后的自动刷新(`restartWatch`)。
+ */
+
+import type {
+  ConsolePanelContext,
+  ConsolePanel,
+} from '../../../web/shared/client-panel.ts';
+import { autoload, errText, type QQGateState } from './client.ts';
+
+/** WS 地址的形状。与服务端 `invokeGate` 那条校验同一个判据,先在本地拦一次。 */
+const WS_URL_RE = /^wss?:\/\/.+/i;
+
+export const gatePanel: ConsolePanel = {
+  mount(ctx: ConsolePanelContext) {
+    autoload<QQGateState>(ctx, {
+      loading: '加载 QQ 接入状态…',
+      failed: 'QQ 接入状态不可用',
+      load: () => ctx.invoke<QQGateState>('state'),
+      render: (st) => [enableSheet(ctx, st), connSheet(ctx, st), napcatSheet(ctx, st)],
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 接入开关
+// ---------------------------------------------------------------------------
+
+function enableSheet(ctx: ConsolePanelContext, st: QQGateState): HTMLElement {
+  const { ui } = ctx;
+  const card = ui.sheet({
+    title: '接入开关',
+    en: 'enabled',
+    desc: '开启或关闭 QQ 接入会重启进程。',
+  });
+
+  const status = ui.rowbar();
+  const btn = ui.button(st.enabled ? '关闭 QQ 接入' : '开启 QQ 接入', {
+    variant: st.enabled ? 'danger' : 'primary',
+    onClick: () => { void toggleEnabled(ctx, st, btn); },
+  });
+  status.append(
+    st.enabled
+      ? ui.pill(st.connected ? '已启用 · 已连接' : '已启用 · 未连接', st.connected ? 'on' : 'off')
+      : ui.pill('未启用', 'plain'),
+    ui.h('span', 'grow'),
+  );
+  card.body.appendChild(status);
+  if (st.enabled && !st.connected) {
+    card.body.appendChild(ui.msgline('NapCat 未连接。', true));
+  }
+  const actions = ui.actions();
+  actions.append(ui.h('span', 'grow'), btn);
+  card.body.appendChild(actions);
+  return card.el;
+}
+
+async function toggleEnabled(
+  ctx: ConsolePanelContext,
+  st: QQGateState,
+  btn: HTMLButtonElement,
+): Promise<void> {
+  const next = !st.enabled;
+  const verb = next ? '开启' : '关闭';
+  const ok = await ctx.ui.confirm({
+    title: `${verb} QQ 接入?`,
+    body: '此操作会重启进程。',
+    danger: true,
+  });
+  if (!ok) return;
+  btn.disabled = true;
+  try {
+    await ctx.invoke('setEnabled', [next]);
+    restartWatch(ctx, verb);
+  } catch (err) {
+    ctx.ui.toast(`操作失败: ${errText(err)}`, 'bad');
+    btn.disabled = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 连接状态
+// ---------------------------------------------------------------------------
+
+function connSheet(ctx: ConsolePanelContext, st: QQGateState): HTMLElement {
+  const { ui } = ctx;
+  const card = ui.sheet({ title: '连接状态', en: 'NapCat ⇄ core' });
+
+  const conn = !st.enabled
+    ? '未启用'
+    : st.connected
+      ? '已连接'
+      : '未连接';
+  const self = st.selfId != null
+    ? `${st.selfId}${st.nickname ? ` · ${st.nickname}` : ''}`
+    : '—';
+  const groups = st.groups.length
+    ? st.groups
+      .map((g) => `${g.name}(${g.id})${g.card ? ` · 我的群昵称「${g.card}」` : ''}`)
+      .join('\n')
+    : '(未配置)';
+  const privates = st.privates.length
+    ? st.privates.map((p) => (p.name ? `${p.name}(${p.id})` : String(p.id))).join('、')
+    : '(未配置)';
+
+  const table = ui.table();
+  table.addRow(['连接', { el: ui.pill(conn, !st.enabled ? 'plain' : st.connected ? 'on' : 'off') }]);
+  table.addRow(['自身 QQ', { text: self, cls: 'txt' }]);
+  table.addRow(['监听群', { text: groups, cls: 'txt' }]);
+  table.addRow(['监听私聊', { text: privates, cls: 'txt' }]);
+  card.body.appendChild(table.el);
+  card.body.appendChild(ui.msgline('监听名单在「监听名单」面板里热改(无需重启)。'));
+  return card.el;
+}
+
+// ---------------------------------------------------------------------------
+// NapCat 连接
+// ---------------------------------------------------------------------------
+
+function napcatSheet(ctx: ConsolePanelContext, st: QQGateState): HTMLElement {
+  const { ui } = ctx;
+  const card = ui.sheet({
+    title: 'NapCat 连接',
+    en: '正向 WS + token',
+    desc: 'NapCat 需保持运行并登录 QQ，通过正向 WebSocket 连接。保存连接配置后重启进程。',
+  });
+
+  const ws = ui.input({ value: st.wsUrl || '', placeholder: 'ws://127.0.0.1:3001' });
+  const token = ui.input({
+    type: 'password',
+    placeholder: st.tokenSet ? '已配置(留空＝不改动)' : '(未配置)',
+  });
+  const msg = ui.msgline('');
+  const save = ui.button('保存并重启', {
+    variant: 'primary',
+    onClick: () => { void saveConnection(ctx, ws, token, msg, save); },
+  });
+
+  const bar = ui.actions();
+  bar.append(msg, ui.h('span', 'grow'), save);
+  card.body.append(
+    ui.field('WS 地址', ws),
+    ui.field('Access Token(可空)', token),
+    bar,
+  );
+  return card.el;
+}
+
+async function saveConnection(
+  ctx: ConsolePanelContext,
+  ws: HTMLInputElement,
+  token: HTMLInputElement,
+  msg: HTMLDivElement,
+  save: HTMLButtonElement,
+): Promise<void> {
+  const fail = (text: string): void => {
+    msg.textContent = text;
+    msg.classList.add('bad');
+  };
+  const wsUrl = ws.value.trim();
+  if (!WS_URL_RE.test(wsUrl)) {
+    fail('WS 地址必须以 ws:// 或 wss:// 开头');
+    return;
+  }
+  msg.textContent = '';
+  msg.classList.remove('bad');
+  const ok = await ctx.ui.confirm({
+    title: '保存 NapCat 连接并重启?',
+    body: '保存连接配置后重启进程。',
+  });
+  if (!ok) return;
+  save.disabled = true;
+  try {
+    await ctx.invoke('setConnection', [wsUrl, token.value]);
+    restartWatch(ctx, '保存连接');
+  } catch (err) {
+    fail(`保存失败: ${errText(err)}`);
+    save.disabled = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 重启等待
+// ---------------------------------------------------------------------------
+
+/** 探活前先让旧进程走完退出窗口(约 350ms),这几拍不问。 */
+const SETTLE_TICKS = 3;
+/** 探活总拍数。超了就换一句"要不要手动看看"的措辞,不再空转。 */
+const MAX_TICKS = 90;
+const TICK_MS = 1000;
+
+/**
+ * 重启期间显示等待状态，以 ctx.interval 轮询 ctx.invoke("state")，确认本面板服务恢复后整页重载。轮询和请求均随 ctx.signal 取消，离开面板后停止。
+ */
+function restartWatch(ctx: ConsolePanelContext, verb: string): void {
+  const { ui } = ctx;
+  const view = ctx.root.ownerDocument?.defaultView ?? null;
+  let notice = ui.drawer(
+    `${verb}中`,
+    '正在重启，完成后自动刷新页面。',
+  );
+
+  let ticks = 0;
+  let probing = false;
+  const timer = ctx.interval(() => {
+    ticks++;
+    if (ticks <= SETTLE_TICKS) return;
+    if (ticks > MAX_TICKS) {
+      timer.dispose();
+      notice.dispose();
+      notice = ui.drawer(
+        '重启耗时偏长',
+        '请手动刷新页面,或检查启动器是否还在运行'
+        + '(没用启动器起的进程,退出后不会有人把它拉起来)。',
+      );
+      return;
+    }
+    if (probing) return; // 上一拍的探活还没回来,不叠着发
+    probing = true;
+    void ctx.invoke('state').then(
+      () => {
+        timer.dispose();
+        notice.dispose();
+        view?.location.reload();
+      },
+      () => { probing = false; }, // 还没回来,下一拍再问
+    );
+  }, TICK_MS);
+}