cortico 0.1.0

package/src/worlds/qq/normalize.ts

@@ -0,0 +1,323 @@
+/**
+ * QQ群消息归一化:OneBot segment数组 ⇄ agent的纯文本世界。
+ * 全部纯函数,便于单测。
+ *
+ * 入站:segment数组渲染成一行可读文本(谁、几点、@了谁、回复了哪条)。
+ * 出站:agent的纯文本(+可选引用游标)编译回segment数组。
+ * 出站不编译“@某人”为 at 段；agent 写出的 @ 文本按普通文本发送。
+ */
+import { shortTime } from '../../core/util.ts';
+import { QFACE_NAMES } from './qface-map.ts';
+
+
+/** OneBot消息段:{type, data} */
+export interface Segment {
+  type: string;
+  data: Record<string, unknown>;
+}
+
+/** OneBot v11 群消息事件(只列归一化用到的字段) */
+export interface OneBotGroupMessage {
+  post_type: string;
+  message_type?: string;
+  group_id?: number;
+  user_id: number;
+  message_id: number;
+  /** unix秒 */
+  time?: number;
+  sender?: { nickname?: string; card?: string };
+  message: Segment[];
+  raw_message?: string;
+}
+
+
+/** JSON 卡片的通用字段；字段缺失时调用方渲染 `[json]`。 */
+interface JsonCardInfo {
+  /** 腾讯协议提供的卡片回退文本，如 "[分享]标题"。 */
+  prompt?: string;
+  /** 封面图URL,取自meta.<动态key>.preview(key名随卡片类型而变,故只取meta下第一个) */
+  previewUrl?: string;
+}
+
+/**
+ * 解析 JSON 卡片的通用 prompt 与 meta.*.preview 字段。
+ * 解析失败或字段缺失时返回空对象，调用方渲染 `[json]`。
+ */
+export function parseJsonCard(data: Record<string, unknown>): JsonCardInfo {
+  const raw = data.data;
+  if (typeof raw !== 'string' || !raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object') return {};
+  const obj = parsed as Record<string, unknown>;
+  const prompt = typeof obj.prompt === 'string' && obj.prompt ? obj.prompt : undefined;
+
+  let previewUrl: string | undefined;
+  const meta = obj.meta;
+  if (meta && typeof meta === 'object') {
+    for (const v of Object.values(meta as Record<string, unknown>)) {
+      if (v && typeof v === 'object') {
+        const preview = (v as Record<string, unknown>).preview;
+        if (typeof preview === 'string' && preview) {
+          previewUrl = preview.startsWith('//') ? `https:${preview}` : preview;
+          break;
+        }
+      }
+    }
+  }
+  return { prompt, previewUrl };
+}
+
+/** json段的文本渲染策略:输入解析出的卡片信息,输出正文里的占位文本 */
+export type JsonCardRenderPolicy = (info: JsonCardInfo) => string;
+
+
+/** 图片segment的渲染策略函数:输入segment.data,输出占位文本 */
+export type ImageRenderPolicy = (data: Record<string, unknown>) => string;
+
+/**
+ * 生成图片渲染策略:
+ * - 取不到图 → 降级 `[图片]`
+ * - 主模型支持图像或 World 配置了视觉模型 → 带 URL 标记,供后续管线取图
+ * 主模型能力通过 host.modelFacts 查询； World 自带视觉不进入 core 契约。
+ */
+export function makeImagePolicy(canUseImages: boolean): ImageRenderPolicy {
+  if (canUseImages) {
+    return (data) => {
+      const url =
+        typeof data.url === 'string' && data.url
+          ? data.url
+          : typeof data.file === 'string'
+            ? data.file
+            : '';
+      return url ? `[图片 ${url}]` : '[图片]';
+    };
+  }
+  return () => '[图片]';
+}
+
+
+export interface RenderContext {
+  /** bot自己的QQ号 */
+  selfId: number;
+  /** bot 自己在本会话的显示名(群=该群 card;私聊=nickname),渲染 "@<名>(你)" 用 */
+  selfName: string;
+  timezone: string;
+  /**
+   * 会话标签,拼进 `[<label> HH:MM]` 前缀以标明消息来自哪个会话。
+   * 群 = `群「群名」`;私聊 = `私聊`(1:1,发言人由后面的显示名承载)。
+   */
+  convLabel: string;
+  /**
+   * 这条平台 message_id 是否已被记录(QQ 消息身份即平台自身 message_id)。
+   * 查不到时,对应的引用回复走异步取原文。
+   */
+  knowsMessage: (messageId: number | string) => boolean;
+  /** 已知称呼解析(可选):@别人时尝试用称呼替代QQ号 */
+  nameOf?: (qq: string) => string | undefined;
+  /** 图片渲染策略(能力协商产物);缺省=降级`[图片]` */
+  renderImage?: ImageRenderPolicy;
+  /** json卡片渲染策略(封面图接入外挂视觉用);缺省=只显示prompt文本,无封面图占位 */
+  renderJsonCard?: JsonCardRenderPolicy;
+}
+
+interface RenderedIncoming {
+  /** 例: `#842485102 [群「茶话会」 21:32] 阿明(12345): 在吗` */
+  text: string;
+  /** 消息里@了bot自己(→urgent立即投递) */
+  mentionedSelf: boolean;
+}
+
+/** 一个渲染片段:token(记号类,如@xx/[图片])与原样文本在拼接时空格规则不同 */
+interface Part {
+  text: string;
+  isToken: boolean;
+}
+
+/** 拼接片段:token与相邻片段之间保证有一个空格分隔;text-text直接相连 */
+function joinParts(parts: Part[]): string {
+  let out = '';
+  let prevToken = false;
+  for (const p of parts) {
+    if (!p.text) continue;
+    if (
+      out.length > 0 &&
+      (prevToken || p.isToken) &&
+      !out.endsWith(' ') &&
+      !p.text.startsWith(' ')
+    ) {
+      out += ' ';
+    }
+    out += p.text;
+    prevToken = p.isToken;
+  }
+  return out;
+}
+
+/**
+ * 为缺少 RenderContext 的独立消息生成可读正文。
+ * 结果不带发言人或时间，不解析 @ 名称，也不输出图片 URL。
+ */
+export function renderSegmentsPlain(segments: Segment[]): string {
+  const parts: Part[] = [];
+  for (const seg of segments ?? []) {
+    const data = seg.data ?? {};
+    switch (seg.type) {
+      case 'text':
+        parts.push({ text: String(data.text ?? ''), isToken: false });
+        break;
+      case 'at': {
+        const qq = String(data.qq ?? '');
+        parts.push({ text: qq === 'all' ? '@全体成员' : `@${qq}`, isToken: true });
+        break;
+      }
+      case 'image':
+        parts.push({ text: '[图片]', isToken: true });
+        break;
+      case 'face': {
+        const name = QFACE_NAMES[String(data.id ?? '')];
+        parts.push({ text: name ? `[表情:${name}]` : '[QQ表情]', isToken: true });
+        break;
+      }
+      case 'reply':
+        parts.push({ text: '[回复某条消息]', isToken: true });
+        break;
+      case 'forward':
+        parts.push({ text: '[转发消息]', isToken: true });
+        break;
+      case 'node':
+        parts.push({ text: '[嵌套转发消息]', isToken: true });
+        break;
+      case 'json': {
+        const { prompt } = parseJsonCard(data);
+        parts.push({ text: prompt ? `[分享:${prompt}]` : '[json]', isToken: true });
+        break;
+      }
+      default:
+        parts.push({ text: `[${seg.type}]`, isToken: true });
+        break;
+    }
+  }
+  return joinParts(parts);
+}
+
+/**
+ * 群消息 → `[HH:MM] 显示名(QQ号): 正文` + 是否@自己。
+ * 显示名 = sender.card || sender.nickname || QQ号。昵称和群昵称不能作为身份依据,
+ * 消息来源的QQ号(私聊来源/群消息发言人来源同理)始终随行以防身份混淆。
+ */
+export function renderIncoming(
+  msg: OneBotGroupMessage,
+  ctx: RenderContext,
+): RenderedIncoming {
+  const renderImage = ctx.renderImage ?? (() => '[图片]');
+  let mentionedSelf = false;
+  const parts: Part[] = [];
+
+  for (const seg of msg.message ?? []) {
+    const data = seg.data ?? {};
+    switch (seg.type) {
+      case 'text': {
+        parts.push({ text: String(data.text ?? ''), isToken: false });
+        break;
+      }
+      case 'at': {
+        const qq = String(data.qq ?? '');
+        if (qq === String(ctx.selfId)) {
+          mentionedSelf = true;
+          parts.push({ text: `@${ctx.selfName}(你)`, isToken: true });
+        } else if (qq === 'all') {
+          // @全体成员不是对 bot 的定向提及，不触发 urgent。
+          parts.push({ text: '@全体成员', isToken: true });
+        } else {
+          const name = ctx.nameOf?.(qq);
+          parts.push({ text: `@${name ?? qq}`, isToken: true });
+        }
+        break;
+      }
+      case 'reply': {
+        const mid = String(data.id ?? '');
+        parts.push({
+          text: ctx.knowsMessage(mid)
+            ? `[回复#${mid}]`
+            : '[回复某条未被记录的消息,原文正在查询中...]',
+          isToken: true,
+        });
+        break;
+      }
+      case 'image': {
+        parts.push({ text: renderImage(data), isToken: true });
+        break;
+      }
+      case 'face': {
+        const name = QFACE_NAMES[String(data.id ?? '')];
+        parts.push({ text: name ? `[表情:${name}]` : '[QQ表情]', isToken: true });
+        break;
+      }
+      case 'forward': {
+        parts.push({ text: '[转发的聊天记录,正在展开中...]', isToken: true });
+        break;
+      }
+      case 'json': {
+        const info = parseJsonCard(data);
+        const rendered = ctx.renderJsonCard
+          ? ctx.renderJsonCard(info)
+          : info.prompt
+            ? `[分享:${info.prompt}]`
+            : '[json]';
+        parts.push({ text: rendered, isToken: true });
+        break;
+      }
+      default: {
+        // 未知segment类型:保留类型名占位,不丢信息也不崩
+        parts.push({ text: `[${seg.type}]`, isToken: true });
+        break;
+      }
+    }
+  }
+
+  const displayName =
+    msg.sender?.card || msg.sender?.nickname || String(msg.user_id);
+  const when =
+    typeof msg.time === 'number' ? new Date(msg.time * 1000) : new Date();
+  const body = joinParts(parts);
+  // 行首的 `#<message_id>` 是这条消息在 QQ 上的真身份:引用回复哪条,就把这个
+  // 号回传给 draft(reply_to)。它由 World 渲染(平台自己的 ID),不是 core 的存储位置。
+  const idTag = msg.message_id !== undefined ? `#${msg.message_id} ` : '';
+  return {
+    text: `${idTag}[${ctx.convLabel} ${shortTime(ctx.timezone, when)}] ${displayName}(${msg.user_id}): ${body}`,
+    mentionedSelf,
+  };
+}
+
+
+interface OutgoingArgs {
+  text: string;
+  /** 引用回复的平台 message_id(draft(reply_to) 收到的就是这个号) */
+  reply_to_message_id?: number | string;
+  /** 图片base64(不含data:前缀);有则编译成image段(OneBot base64://) */
+  image_base64?: string;
+}
+
+/**
+ * 出站 → segment数组:reply段(如有)在前,然后image段(如有),最后text段
+ * (text非空才加——支持只发图不带字)。
+ * 不做 @ 编译：agent 写出的“@某人”作为纯文本原样发出。
+ */
+export function buildOutgoing(args: OutgoingArgs): Segment[] {
+  const segments: Segment[] = [];
+  if (args.reply_to_message_id !== undefined) {
+    segments.push({ type: 'reply', data: { id: String(args.reply_to_message_id) } });
+  }
+  if (args.image_base64) {
+    segments.push({ type: 'image', data: { file: `base64://${args.image_base64}` } });
+  }
+  if (args.text) {
+    segments.push({ type: 'text', data: { text: args.text } });
+  }
+  return segments;
+}

package/src/worlds/qq/qface-map.ts

@@ -0,0 +1,282 @@
+/**
+ * QQ face segment ID → 中文名称的协议兼容表。
+ * 编号与短名称对应 NapCat `face_config.json` 里的 `QSid`/`QDes`；不含图像或运行代码。
+ * 未覆盖的自定义或新增表情由调用方渲染为通用占位。
+ */
+export const QFACE_NAMES: Record<string, string> = {
+  "0": "惊讶",
+  "1": "撇嘴",
+  "2": "色",
+  "3": "发呆",
+  "4": "得意",
+  "5": "流泪",
+  "6": "害羞",
+  "7": "闭嘴",
+  "8": "睡",
+  "9": "大哭",
+  "10": "尴尬",
+  "11": "发怒",
+  "12": "调皮",
+  "13": "呲牙",
+  "14": "微笑",
+  "15": "难过",
+  "16": "酷",
+  "18": "抓狂",
+  "19": "吐",
+  "20": "偷笑",
+  "21": "可爱",
+  "22": "白眼",
+  "23": "傲慢",
+  "24": "饥饿",
+  "25": "困",
+  "26": "惊恐",
+  "27": "流汗",
+  "28": "憨笑",
+  "29": "悠闲",
+  "30": "奋斗",
+  "31": "咒骂",
+  "32": "疑问",
+  "33": "嘘",
+  "34": "晕",
+  "35": "折磨",
+  "36": "衰",
+  "37": "骷髅",
+  "38": "敲打",
+  "39": "再见",
+  "41": "发抖",
+  "42": "爱情",
+  "43": "跳跳",
+  "46": "猪头",
+  "49": "拥抱",
+  "53": "蛋糕",
+  "54": "闪电",
+  "55": "炸弹",
+  "56": "刀",
+  "57": "足球",
+  "59": "便便",
+  "60": "咖啡",
+  "61": "饭",
+  "63": "玫瑰",
+  "64": "凋谢",
+  "66": "爱心",
+  "67": "心碎",
+  "69": "礼物",
+  "74": "太阳",
+  "75": "月亮",
+  "76": "赞",
+  "77": "踩",
+  "78": "握手",
+  "79": "胜利",
+  "85": "飞吻",
+  "86": "怄火",
+  "89": "西瓜",
+  "96": "冷汗",
+  "97": "擦汗",
+  "98": "抠鼻",
+  "99": "鼓掌",
+  "100": "糗大了",
+  "101": "坏笑",
+  "102": "左哼哼",
+  "103": "右哼哼",
+  "104": "哈欠",
+  "105": "鄙视",
+  "106": "委屈",
+  "107": "快哭了",
+  "108": "阴险",
+  "109": "左亲亲",
+  "110": "吓",
+  "111": "可怜",
+  "112": "菜刀",
+  "113": "啤酒",
+  "114": "篮球",
+  "115": "乒乓",
+  "116": "示爱",
+  "117": "瓢虫",
+  "118": "抱拳",
+  "119": "勾引",
+  "120": "拳头",
+  "121": "差劲",
+  "122": "爱你",
+  "123": "NO",
+  "124": "OK",
+  "125": "转圈",
+  "126": "磕头",
+  "127": "回头",
+  "128": "跳绳",
+  "129": "挥手",
+  "130": "激动",
+  "131": "街舞",
+  "132": "献吻",
+  "133": "左太极",
+  "134": "右太极",
+  "136": "双喜",
+  "137": "鞭炮",
+  "138": "灯笼",
+  "140": "K歌",
+  "144": "喝彩",
+  "145": "祈祷",
+  "146": "爆筋",
+  "147": "棒棒糖",
+  "148": "喝奶",
+  "151": "飞机",
+  "158": "钞票",
+  "168": "药",
+  "169": "手枪",
+  "171": "茶",
+  "172": "眨眼睛",
+  "173": "泪奔",
+  "174": "无奈",
+  "175": "卖萌",
+  "176": "小纠结",
+  "177": "喷血",
+  "178": "斜眼笑",
+  "179": "doge",
+  "180": "惊喜",
+  "181": "骚扰",
+  "182": "笑哭",
+  "183": "我最美",
+  "184": "河蟹",
+  "185": "羊驼",
+  "187": "幽灵",
+  "188": "蛋",
+  "190": "菊花",
+  "192": "红包",
+  "193": "大笑",
+  "194": "不开心",
+  "197": "冷漠",
+  "198": "呃",
+  "199": "好棒",
+  "200": "拜托",
+  "201": "点赞",
+  "202": "无聊",
+  "203": "托脸",
+  "204": "吃",
+  "205": "送花",
+  "206": "害怕",
+  "207": "花痴",
+  "208": "小样儿",
+  "210": "飙泪",
+  "211": "我不看",
+  "212": "托腮",
+  "214": "啵啵",
+  "215": "糊脸",
+  "216": "拍头",
+  "217": "扯一扯",
+  "218": "舔一舔",
+  "219": "蹭一蹭",
+  "220": "拽炸天",
+  "221": "顶呱呱",
+  "222": "抱抱",
+  "223": "暴击",
+  "224": "开枪",
+  "225": "撩一撩",
+  "226": "拍桌",
+  "227": "拍手",
+  "228": "恭喜",
+  "229": "干杯",
+  "230": "嘲讽",
+  "231": "哼",
+  "232": "佛系",
+  "233": "掐一掐",
+  "234": "惊呆",
+  "235": "颤抖",
+  "236": "啃头",
+  "237": "偷看",
+  "238": "扇脸",
+  "239": "原谅",
+  "240": "喷脸",
+  "241": "生日快乐",
+  "242": "头撞击",
+  "243": "甩头",
+  "244": "扔狗",
+  "245": "加油必胜",
+  "246": "加油抱抱",
+  "247": "口罩护体",
+  "260": "搬砖中",
+  "261": "忙到飞起",
+  "262": "脑阔疼",
+  "263": "沧桑",
+  "264": "捂脸",
+  "265": "辣眼睛",
+  "266": "哦哟",
+  "267": "头秃",
+  "268": "问号脸",
+  "269": "暗中观察",
+  "270": "emm",
+  "271": "吃瓜",
+  "272": "呵呵哒",
+  "273": "我酸了",
+  "274": "太南了",
+  "276": "辣椒酱",
+  "277": "汪汪",
+  "278": "汗",
+  "279": "打脸",
+  "280": "击掌",
+  "281": "无眼笑",
+  "282": "敬礼",
+  "283": "狂笑",
+  "284": "面无表情",
+  "285": "摸鱼",
+  "286": "魔鬼笑",
+  "287": "哦",
+  "288": "请",
+  "289": "睁眼",
+  "290": "敲开心",
+  "291": "震惊",
+  "292": "让我康康",
+  "293": "摸锦鲤",
+  "294": "期待",
+  "295": "拿到红包",
+  "296": "真好",
+  "297": "拜谢",
+  "298": "元宝",
+  "299": "牛啊",
+  "300": "胖三斤",
+  "301": "好闪",
+  "302": "左拜年",
+  "303": "右拜年",
+  "304": "红包包",
+  "305": "右亲亲",
+  "306": "牛气冲天",
+  "307": "喵喵",
+  "308": "求红包",
+  "309": "谢红包",
+  "310": "新年烟花",
+  "311": "打call",
+  "312": "变形",
+  "313": "嗑到了",
+  "314": "仔细分析",
+  "315": "加油",
+  "316": "我没事",
+  "317": "菜狗",
+  "318": "崇拜",
+  "319": "比心",
+  "320": "庆祝",
+  "321": "老色痞",
+  "322": "拒绝",
+  "323": "嫌弃",
+  "324": "吃糖",
+  "325": "惊吓",
+  "326": "生气",
+  "327": "加一",
+  "328": "错号",
+  "329": "对号",
+  "330": "完成",
+  "331": "明白",
+  "332": "举牌牌",
+  "333": "烟花",
+  "334": "虎虎生威",
+  "336": "豹富",
+  "337": "花朵脸",
+  "338": "我想开了",
+  "339": "舔屏",
+  "340": "热化了",
+  "341": "打招呼",
+  "342": "酸Q",
+  "343": "我方了",
+  "344": "大怨种",
+  "345": "红包多多",
+  "346": "你真棒棒",
+  "347": "大展宏兔",
+  "348": "福萝卜",
+};

package/src/worlds/qq/vision-prompt.ts

@@ -0,0 +1,27 @@
+/**
+ * 被动识图的默认任务文本。它与配置加载逻辑分开维护，config.json 仍可覆盖。
+ */
+export const VISION_DEFAULT_PROMPT = `准确分析、精简描述图片内容，按以下结构输出：
+
+## 分类
+判断图片属于照片、表情包、屏幕截图或其他类型。
+
+## 视觉事实
+只描述画面中能够直接看见并确认的对象、文字、数量、位置、颜色、环境和动作。
+不要加入原因、用途、身份、品牌背景或其他推断。
+
+## 文字
+提取画面中清晰可辨认的文字。
+看不清的文字不要猜测，用“部分文字模糊无法辨认”说明。
+
+## 视觉确定推测
+仅允许根据清晰视觉线索作出高置信度判断，并明确标注为推测。
+
+## 视觉延伸推测
+描述由画面情境引出的合理但无法直接确认的推测，并明确标注依据。
+
+## 视觉不可辨认项
+只列出“画面中确实存在或疑似存在，但仅因视觉条件而无法看清、分辨或判断”的内容。
+
+## 一句话描述
+只包含确定性事实`;