cortico 0.1.1 → 0.1.3

package/src/worlds/minecraft/README.md

@@ -5,6 +5,13 @@
 实时游戏 World：以 mineflayer 玩家客户端连原版服务器，把"游戏状态 → 文字观察"
 与"高层意图 → 游戏操作"接通。
 
+**症状跟服务端版本有关就先读 [ADAPT.md](ADAPT.md)。** 那里按版本记着已知的服务端判据
+差异、在日志里认出它的特征、以及客户端这边的改法。
+
+新量到一条就补进 ADAPT.md,并在情况允许时向操作员申请提一个 PR。通用的适配问题连代码
+一起提;改动牵涉上游(mineflayer、prismarine-*、服务端行为)时,代码不一定要提,那条经验
+仍然值得提。
+
 ## 结构
 
 ```
@@ -523,6 +530,7 @@ surface 是尽力而为：先浮上水面换气（这步永远做得到），再
 2. **合成前清空合成格。** 光标物品无法放回时返回错误；徒手 2×2 合成使用不会关闭的窗口 0，失败后由补丁取回格内材料。
 3. **放置后回读目标格。** 每次等待 400ms，最多尝试三次；最终错误保留 Mineflayer 的文本契约，供寻路器处理。
 4. **丢弃 `windowId=-2` 的 `set_slot`。** 其他窗口的 `set_slot` 和 `window_items` 继续传递；已收到当前窗口的 `stateId` 时，用该值替换其他窗口包中的 `stateId`。
+5. **水平碰撞停在离方块面 `WALL_GAP` 处。** 服务端拒绝包围盒恰好贴着方块侧面的位置(静默传送回上一个好位置,不打 `moved wrongly`),prismarine-physics 原本停在贴面处;竖直方向贴面服务端照收,不改。改的是 `prismarine-physics` 的 AABB 原型,bot 物理与寻路器模拟同时生效。
 
 合成与放置期间的包流记为 World 日志 `craft` 类别（`click-out`、`slot-in`、
 `items-in`、`stateid-guard`、`result-slot`、`grid-clear`);窗口外的高频 `set_slot`

package/src/worlds/minecraft/client-launch.ts

@@ -65,6 +65,8 @@ interface ClientLaunch {
   nativeJars: string[];
   /** 实际用到的版本 id 链,child → root */
   versionChain: string[];
+  /** 版本 JSON 点名、但 libraries 目录里没有的条目,相对 libraries 目录。类路径里少了它们。 */
+  missingLibraries: string[];
 }
 
 const OS_NAMES: Partial<Record<NodeJS.Platform, string>> = {
@@ -202,6 +204,7 @@ export function buildClientLaunch(input: ClientLaunchInput): ClientLaunch | { er
   const librariesDir = join(gameDir, 'libraries');
   const classpath: string[] = [];
   const nativeJars: string[] = [];
+  const missingLibraries: string[] = [];
   const seenPaths = new Set<string>();
   for (const version of chain) {
     for (const lib of version.libraries ?? []) {
@@ -211,7 +214,10 @@ export function buildClientLaunch(input: ClientLaunchInput): ClientLaunch | { er
       const abs = join(librariesDir, rel);
       if (seenPaths.has(abs)) continue;
       seenPaths.add(abs);
-      if (!existsSync(abs)) continue;
+      if (!existsSync(abs)) {
+        missingLibraries.push(rel);
+        continue;
+      }
       if (/natives/i.test(rel)) nativeJars.push(abs);
       classpath.push(abs);
     }
@@ -222,7 +228,9 @@ export function buildClientLaunch(input: ClientLaunchInput): ClientLaunch | { er
   const separator = os === 'windows' ? ';' : ':';
   const vars: Record<string, string> = {
     auth_player_name: input.username,
-    version_name: versionId,
+    // 加载器版本靠 `-DignoreList=...,${version_name}.jar` 把主 jar 挡在模块路径外,所以这个名字
+    // 必须是实际加载的那个 jar;继承链上的版本没有自己的 jar,用的是 jarId 那个。
+    version_name: jarId,
     game_directory: gameDir,
     assets_root: join(gameDir, 'assets'),
     game_assets: join(gameDir, 'assets'),
@@ -268,5 +276,6 @@ export function buildClientLaunch(input: ClientLaunchInput): ClientLaunch | { er
     mainClass,
     nativeJars,
     versionChain: chain.map((v, i) => v.id ?? (i === 0 ? versionId : '?')),
+    missingLibraries,
   };
 }

package/src/worlds/minecraft/client.ts

@@ -215,6 +215,10 @@ export class GameClient {
       return this.state();
     }
     this.activeGameDir = gameDir;
+    if ('missingLibraries' in launch && launch.missingLibraries.length > 0) {
+      this.opts.log.warn(`${this.opts.label}版本 JSON 点名的 ${launch.missingLibraries.length} 个库`
+        + `不在 libraries 目录,类路径里没有它们:${launch.missingLibraries.join(' ')}`);
+    }
     if ('nativeJars' in launch) prepareNatives(launch.nativeJars, launch.nativesDir, this.opts.log);
     if (!this.opts.commandOverride) {
       if (this.opts.noPauseOnLostFocus()) {

package/src/worlds/minecraft/mineflayer-fixes.ts

@@ -8,7 +8,10 @@
  * 一律本地换位，原版服务端不换。一次换位两边状态就此分家，之后所有合成都在错的格子上做。
  *
  * 光照段随包到来时必须按 nibble 原序落位,prismarine-chunk 把它当长整型数组读了。
+ *
+ * 水平碰撞停在离方块面 `WALL_GAP` 处:服务端拒绝包围盒恰好贴着方块侧面的位置(见 `installWallGap`)。
  */
+import { createRequire } from 'node:module';
 import type { Bot } from 'mineflayer';
 import type { Logger } from '../../core/types.ts';
 import type { MinecraftLog } from './log.ts';
@@ -36,6 +39,11 @@ const DIG_CONFIRM_FACTOR = 3;
 const DIG_GROUND_WAIT_MS = 600;
 /** 服务端认账比本地定时器晚这么多就记一条:整片挖掘不刷屏,慢的那些留痕 */
 const DIG_SLOW_ACK_MS = 200;
+/**
+ * 水平碰撞停在离方块面这么远的地方。服务端只要缝隙大于零就收(实测 1e-7 也收),
+ * 取 1e-5 让坐标到三千万格时的浮点误差也吃不掉它。
+ */
+export const WALL_GAP = 1e-5;
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
@@ -136,7 +144,53 @@ export function installMineflayerFixes(
   installConfirmedCraft(bot, diag, trace, (n) => { tracing += n; }, showTempo);
   installLightRelay(bot, log, diag);
   installDismountFix(bot, diag);
-  log.info(`mineflayer 修补已装上:合成取服务端产物、放置短超时重发、附魔按组件格式计入挖掘、挖掘等服务端改掉那一格、stateId 认当前窗口、光照段重新落位${diag ? '' : '(没给 World 日志,包流不留痕)'}`);
+  installWallGap();
+  log.info(`mineflayer 修补已装上:合成取服务端产物、放置短超时重发、附魔按组件格式计入挖掘、挖掘等服务端改掉那一格、stateId 认当前窗口、光照段重新落位、水平碰撞留缝${diag ? '' : '(没给 World 日志,包流不留痕)'}`);
+}
+
+/** 原型上的标记:同一进程里多个连接、多份模块实例只改一次 */
+const WALL_GAP_MARK = Symbol.for('cortico.minecraft.wallGap');
+
+interface PhysicsBox {
+  minX: number; minY: number; minZ: number; maxX: number; maxY: number; maxZ: number;
+  computeOffsetX(other: PhysicsBox, offset: number): number;
+  computeOffsetZ(other: PhysicsBox, offset: number): number;
+}
+
+/**
+ * 1.21.11 的服务端把「包围盒恰好贴着方块侧面」的位置当成撞进方块:不打 moved wrongly,
+ * 静默把人传送回上一个好位置(1.21.10 及更早照收)。prismarine-physics 的碰撞解算恰好停在
+ * 贴面处,于是贴墙、上台阶、贴墙起跳每一拍都被打回,人钉在原地。竖直方向贴面照收,这里只改 X/Z:
+ * 朝方块走的那一步停在离面 `WALL_GAP` 处;已经贴着(服务端传送来的位置就是贴面的)
+ * 再往里走时退开同样的距离。bot 的物理与寻路器的模拟共用这一个类,一处改两处生效。
+ */
+export function installWallGap(): void {
+  const mfRequire = createRequire(createRequire(import.meta.url).resolve('mineflayer/package.json'));
+  const AABB = mfRequire('prismarine-physics/lib/aabb.js') as { prototype: PhysicsBox & { [WALL_GAP_MARK]?: true } };
+  const proto = AABB.prototype;
+  if (proto[WALL_GAP_MARK]) return;
+  // this 是方块的盒子,other 是正在挪的实体的盒子(prismarine-physics 这么调)
+  proto.computeOffsetX = function (this: PhysicsBox, other: PhysicsBox, offsetX: number): number {
+    if (other.maxY > this.minY && other.minY < this.maxY && other.maxZ > this.minZ && other.minZ < this.maxZ) {
+      if (offsetX > 0 && other.maxX <= this.minX + WALL_GAP) {
+        offsetX = Math.min(this.minX - other.maxX - WALL_GAP, offsetX);
+      } else if (offsetX < 0 && other.minX >= this.maxX - WALL_GAP) {
+        offsetX = Math.max(this.maxX - other.minX + WALL_GAP, offsetX);
+      }
+    }
+    return offsetX;
+  };
+  proto.computeOffsetZ = function (this: PhysicsBox, other: PhysicsBox, offsetZ: number): number {
+    if (other.maxX > this.minX && other.minX < this.maxX && other.maxY > this.minY && other.minY < this.maxY) {
+      if (offsetZ > 0 && other.maxZ <= this.minZ + WALL_GAP) {
+        offsetZ = Math.min(this.minZ - other.maxZ - WALL_GAP, offsetZ);
+      } else if (offsetZ < 0 && other.minZ >= this.maxZ - WALL_GAP) {
+        offsetZ = Math.max(this.maxZ - other.minZ + WALL_GAP, offsetZ);
+      }
+    }
+    return offsetZ;
+  };
+  proto[WALL_GAP_MARK] = true;
 }
 
 /**

package/src/worlds/qq/normalize.ts

@@ -178,6 +178,9 @@ export function renderSegmentsPlain(segments: Segment[]): string {
       case 'image':
         parts.push({ text: '[图片]', isToken: true });
         break;
+      case 'record':
+        parts.push({ text: '[语音]', isToken: true });
+        break;
       case 'face': {
         const name = QFACE_NAMES[String(data.id ?? '')];
         parts.push({ text: name ? `[表情:${name}]` : '[QQ表情]', isToken: true });
@@ -253,6 +256,11 @@ export function renderIncoming(
         parts.push({ text: renderImage(data), isToken: true });
         break;
       }
+      // 语音条的音频不随消息到达,取回它要另一次动作调用;这里只说这是一条语音。
+      case 'record': {
+        parts.push({ text: '[语音]', isToken: true });
+        break;
+      }
       case 'face': {
         const name = QFACE_NAMES[String(data.id ?? '')];
         parts.push({ text: name ? `[表情:${name}]` : '[QQ表情]', isToken: true });
@@ -301,14 +309,20 @@ interface OutgoingArgs {
   reply_to_message_id?: number | string;
   /** 图片base64(不含data:前缀);有则编译成image段(OneBot base64://) */
   image_base64?: string;
+  /** 语音base64(不含data:前缀);有则整条消息只有这一个record段 */
+  record_base64?: string;
 }
 
 /**
  * 出站 → segment数组:reply段(如有)在前,然后image段(如有),最后text段
  * (text非空才加——支持只发图不带字)。
+ * 语音条独占一条消息:QQ 的 record 段不与别的段同发,给了它就只发它。
  * 不做 @ 编译：agent 写出的“@某人”作为纯文本原样发出。
  */
 export function buildOutgoing(args: OutgoingArgs): Segment[] {
+  if (args.record_base64) {
+    return [{ type: 'record', data: { file: `base64://${args.record_base64}` } }];
+  }
   const segments: Segment[] = [];
   if (args.reply_to_message_id !== undefined) {
     segments.push({ type: 'reply', data: { id: String(args.reply_to_message_id) } });

package/src/worlds/qq/world.ts

@@ -109,6 +109,8 @@ interface PendingDraft {
   replyMessageId?: number | string;
   /** 要发送的图片的句柄(`log:` 她看见过的 / `mem:` 她收藏的);无=纯文本 */
   imageRef?: string;
+  /** 要发送的语音的句柄;语音条独占一条消息,与 text、imageRef 互斥 */
+  voiceRef?: string;
 }
 
 interface ForwardNode {
@@ -130,7 +132,9 @@ export class QQWorld implements World {
   private host?: WorldHost;
   private driver?: OneBotDriver;
   private log: Logger = nullLogger();
-  private imagePolicy: ImageRenderPolicy = () => '[图片]';
+  /** 主模型支持 image/png 或 World 配置了视觉模型时启用取图；每次渲染按当前端点判断。 */
+  private readonly imagePolicy: ImageRenderPolicy = (data) =>
+    makeImagePolicy(!!this.vision || (this.host?.modelFacts.accepts('image/png') ?? false))(data);
 
   /** 外挂视觉(注入=auxVLM生效);null=无,一切保持[图片]占位现状 */
   private readonly vision?: VisionService;
@@ -546,8 +550,6 @@ export class QQWorld implements World {
   async start(host: WorldHost): Promise<void> {
     this.host = host;
     this.log = host.log;
-    // 主模型支持 image/png 或 World 配置了视觉模型时启用取图。
-    this.imagePolicy = makeImagePolicy(!!this.vision || host.modelFacts.accepts('image/png'));
     // 外挂视觉的用量自愿上报进 core 的成本账(不报就在成本页看不到)
     this.vision?.setUsageSink((usage, model) =>
       host.reportUsage(usage, { model, label: 'QQWorld·辅助视觉' }),
@@ -1235,7 +1237,14 @@ export class QQWorld implements World {
   /** 实际发送到目标会话,回录 qq.self,返回回执文本 */
   private async sendToTarget(
     target: Conv,
-    opts: { text: string; replyMessageId?: number | string; imageRef?: string; imageBytes?: Uint8Array },
+    opts: {
+      text: string;
+      replyMessageId?: number | string;
+      imageRef?: string;
+      imageBytes?: Uint8Array;
+      voiceRef?: string;
+      voiceBytes?: Uint8Array;
+    },
   ): Promise<string> {
     const host = this.host!;
     const driver = this.driver!;
@@ -1247,6 +1256,7 @@ export class QQWorld implements World {
       text: opts.text,
       reply_to_message_id: opts.replyMessageId,
       image_base64: imageBase64,
+      ...(opts.voiceBytes ? { record_base64: Buffer.from(opts.voiceBytes).toString('base64') } : {}),
     });
     const action = target.kind === 'group' ? 'send_group_msg' : 'send_private_msg';
     const params =
@@ -1259,7 +1269,13 @@ export class QQWorld implements World {
     // 回录正文:文字 + (如有)图片标记,保证自己发的图在历史里也可见。
     // 行首保留平台消息号,使历史查询结果可引用自身消息。
     const imgMark = opts.imageRef ? `[图片: ${opts.imageRef}]` : '';
-    const selfBody = [opts.text, imgMark].filter(Boolean).join(' ');
+    const voiceMark = opts.voiceRef ? `[语音: ${opts.voiceRef}]` : '';
+    const selfBody = [opts.text, imgMark, voiceMark].filter(Boolean).join(' ');
+    const selfBlob = opts.imageRef
+      ? { handle: opts.imageRef, fallbackText: '你发出的图片' }
+      : opts.voiceRef
+        ? { handle: opts.voiceRef, fallbackText: '你发出的语音' }
+        : null;
     const idTag = messageId !== undefined ? `#${messageId} ` : '';
     const env = await host.pushEvent(
       {
@@ -1267,8 +1283,8 @@ export class QQWorld implements World {
         ts: nowIso(this.timezone),
         source: this.id,
         text: `${idTag}[${this.convLabel(target)} ${shortTime(this.timezone)}] 你: ${selfBody}`,
-        // 发出去的图按句柄附在自己这条记录上:时间线与吃图的模型都看得到发了什么
-        ...(opts.imageRef ? { blobs: [{ handle: opts.imageRef, fallbackText: '你发出的图片' }] } : {}),
+        // 发出去的图和语音按句柄附在自己这条记录上:时间线与吃这些类型的模型都看得到发了什么
+        ...(selfBlob ? { blobs: [selfBlob] } : {}),
         senderKey: String(driver.identity?.selfId ?? 'self'),
         meta: {
           message_id: messageId,
@@ -1320,6 +1336,13 @@ export class QQWorld implements World {
               'Optional. An image to send, given by handle: a log: handle from a [blob ...] line you saw, '
               + 'or a mem: handle of one kept in your workspace.',
           },
+          voice: {
+            type: 'string',
+            description:
+              'Optional. Audio to send as a QQ voice bar, given by handle the same way as image. '
+              + 'A voice bar is a message of its own: leave text, image and reply_to out. '
+              + 'The protocol end converts the audio it accepts (wav, mp3) to what QQ plays.',
+          },
           reply_to: {
             type: 'string',
             description:
@@ -1335,7 +1358,12 @@ export class QQWorld implements World {
         const rawText = typeof args.text === 'string' ? args.text : '';
         const imageArg =
           typeof args.image === 'string' && args.image.trim() ? args.image.trim() : undefined;
-        if (!rawText.trim() && !imageArg) return '[bad input] provide at least one of text or image';
+        const voiceArg =
+          typeof args.voice === 'string' && args.voice.trim() ? args.voice.trim() : undefined;
+        if (!rawText.trim() && !imageArg && !voiceArg) return '[bad input] provide at least one of text, image or voice';
+        if (voiceArg && (rawText.trim() || imageArg || (args.reply_to !== undefined && args.reply_to !== null && String(args.reply_to) !== ''))) {
+          return '[bad input] a voice bar is a message of its own; it carries no text, image or quote-reply';
+        }
         // 纯空白正文视为不带字(避免只发图时混进一个空白 text 段)
         const text = rawText.trim() ? rawText : '';
 
@@ -1373,7 +1401,17 @@ export class QQWorld implements World {
             : `[will send image: ${imageArg}]`;
         }
 
-        this.pendingDraft = { target, text, replyMessageId: rep.mid, imageRef };
+        // 语音:同样按句柄确认取得到,MIME 必须是音频
+        let voiceRef: string | undefined;
+        if (voiceArg) {
+          const got = host.blob(voiceArg);
+          if (!got) return `[send failed] no blob for ${voiceArg}; use a log: handle from a [blob ...] line or a mem: handle from your workspace`;
+          if (!got.mime.startsWith('audio/')) return `[send failed] ${voiceArg} is ${got.mime}, not audio`;
+          voiceRef = voiceArg;
+          previewLine = `[will send voice: ${voiceArg}]`;
+        }
+
+        this.pendingDraft = { target, text, replyMessageId: rep.mid, imageRef, voiceRef };
 
         // 排出当下已积、尚未投递的QQ会话事件(consume-once)。正文不能伪装成
         // draft 工具结果:交回 loop 按常规投递,本轮下一次推理前它们就在眼前,
@@ -1382,7 +1420,7 @@ export class QQWorld implements World {
         ctx.queueExternalEvents?.(drained);
 
         const lines = [`[draft staged → ${this.targetDesc(target)}]`];
-        lines.push(text.trim() ? `Text: ${text}` : '(image only, no text)');
+        lines.push(text.trim() ? `Text: ${text}` : voiceRef ? '(voice bar, no text)' : '(image only, no text)');
         if (previewLine) lines.push(previewLine);
         lines.push(
           '',
@@ -1433,11 +1471,19 @@ export class QQWorld implements World {
               if (!got) return `[send failed] blob ${draft.imageRef} is gone (draft kept)`;
               imageBytes = got.bytes;
             }
+            let voiceBytes: Uint8Array | undefined;
+            if (draft.voiceRef) {
+              const got = host.blob(draft.voiceRef);
+              if (!got) return `[send failed] blob ${draft.voiceRef} is gone (draft kept)`;
+              voiceBytes = got.bytes;
+            }
             const receipt = await this.sendToTarget(draft.target, {
               text: draft.text,
               replyMessageId: draft.replyMessageId,
               imageRef: draft.imageRef,
               imageBytes,
+              voiceRef: draft.voiceRef,
+              voiceBytes,
             });
             this.pendingDraft = null; // 成功才清;失败保留草稿,可再 confirm 重试
             return receipt;

package/src/worlds/terminal/world.ts

@@ -74,8 +74,7 @@ const MODEL_TEXT = {
   selfLine: (time: string, text: string) => `[${time}] you: ${text}`,
   inviteLine: (time: string, name: string, label: string, spokenBefore: boolean) =>
     `[${time}] ${name} pressed the "${label}" button on the terminal.`
-    + (spokenBefore ? '' : ' Nothing has been said here before.')
-    + ' You may say hello and introduce yourself.',
+    + (spokenBefore ? '' : ' No speech is recorded in the retained terminal history.'),
   imageFallback: (from: string, i: number, total: number) => `image ${i}/${total} from ${from}`,
   deliveredTo: (delivered: number, names: string[]) =>
     `Sent to the chat channel on the console's "Terminal" page; ${delivered} connection${delivered === 1 ? '' : 's'} online right now`
@@ -631,11 +630,11 @@ export class TerminalWorld implements World {
     this.sendJson(client.peer, { type: 'sys', text: t.unknownType(String(msg.type)) });
   }
 
-  /** 这个终端上有没有人说过话。末尾几十条够判断:这颗按钮只在事件库还空着时露面。 */
+  /** 已保存的终端事件里有没有人说过话。 */
   private spokenBefore(): boolean {
     if (!this.host) return false;
     return this.host.store
-      .range({ source: this.id, limit: 50 })
+      .range({ source: this.id })
       .some((e) => e.type === 'terminal.message' || e.type === 'terminal.self');
   }