@pi-flash-plugins/pf-wxbot 0.0.0-stage → 0.1.3

package/pi/register.mjs

@@ -0,0 +1,236 @@
+// register —— 扫码注册流程，自 PF 仓 wxprobe src/register.rs **逐条移植**（JS 版）。
+//
+// iLink 协议（对齐 ZCode weixinRegistration.ts）：
+// - `GET /ilink/bot/get_bot_qrcode?bot_type=3`（30s 超时，wire.get_qr）
+// - `GET /ilink/bot/get_qrcode_status?qrcode=<enc>`，3s 间隔轮询
+// - 状态归一：数字 0/1/2/3|4 与字符串词表两套
+//
+// 生命周期：ext 的 `session_start` 里起 runQrFlow（异步循环），`session_shutdown`
+// 里取消（返回值 false 语义）。二维码 URL 交 J2 壳渲染（qr.mjs → canvas）。
+
+/** 出码（P0 步骤 1）。 */
+export async function begin(wire) {
+  const payload = await wire.get_qr("qr-begin", "/get_bot_qrcode", [["bot_type", "3"]]);
+  const firstStr = (keys) => {
+    for (const k of keys) {
+      const v = payload[k];
+      if (typeof v === "string" && v !== "") return v;
+    }
+    return undefined;
+  };
+  const qrcode = firstStr(["qrcode", "qr_code"]);
+  if (qrcode === undefined) {
+    throw new Error(`扫码接口未返回 qrcode，真实字段：${JSON.stringify(payload)}`);
+  }
+  const qr_url = firstStr(["qrcode_img_content", "qrcode_url"]) ?? qrcode;
+  const interval = typeof payload.expires_in === "number" ? payload.expires_in : undefined;
+  const expires_at_ms = Date.now() + (interval ?? 120) * 1000;
+  return { qrcode, qr_url, interval_secs: 3, expires_at_ms };
+}
+
+/** 扫码状态（P0 步骤 2）。 */
+export async function poll(wire, qrcode) {
+  const payload = await wire.get_qr("qr-status", "/get_qrcode_status", [["qrcode", qrcode]]);
+  const raw = payload["status"] ?? payload["qrcode_status"] ?? payload["qr_status"];
+  const status = normalize(raw);
+  switch (status) {
+    case "success": {
+      let bot_token;
+      for (const k of ["bot_token", "token"]) {
+        const v = payload[k];
+        if (typeof v === "string" && v !== "") { bot_token = v; break; }
+      }
+      if (bot_token === undefined) {
+        throw new Error(`扫码成功但未返回 bot_token，真实字段：${JSON.stringify(payload)}`);
+      }
+      let bot_id;
+      for (const k of ["ilink_bot_id", "bot_id"]) {
+        const v = payload[k];
+        if (typeof v === "string" && v !== "") { bot_id = v; break; }
+      }
+      return { kind: "success", bot_token, bot_id };
+    }
+    case "expired":
+      return { kind: "expired" };
+    case "error":
+      return { kind: "error", message: typeof payload["errmsg"] === "string" ? payload["errmsg"] : "二维码状态接口报错" };
+    default: {
+      if (status === "scanned") return { kind: "scanned" };
+ // normalize 已认的等待词（实测 "wait"）不算未知状态：以前会拼成
+ // 「未识别的扫码状态」→ 壳白遮二维码
+      if (KNOWN_PENDING.has(String(raw).toLowerCase())) return { kind: "pending" };
+      const msg = unknownStatusMessage(raw);
+      if (msg) return { kind: "error", message: msg };
+      return { kind: "pending" };
+    }
+  }
+}
+
+/** 词表外的**字符串**状态 → 给 UI 的错误文案（含安装指引）。
+ * ZCode 静默按 pending 吞掉未知状态，会把「微信侧未装插件」吞成无限等待
+ * （2026-10-24 用户要求识别并告知）；数字码仍归 pending。 */
+const KNOWN_PENDING = new Set(["wait", "waiting", "pending", "created"]);
+
+export function unknownStatusMessage(raw) {
+  if (typeof raw !== "string") return undefined;
+  if (raw.toLowerCase().includes("install")) {
+    return `微信侧未安装「微信ClawBot」插件：请先在微信安装/启用插件，再重新扫码。（原始状态：${raw}）`;
+  }
+  return `未识别的扫码状态：${raw} —— 若微信提示未安装，请先安装「微信ClawBot」插件再扫。`;
+}
+
+/** ZCode `normalizeQrStatus`（weixinRegistration.ts:103-130）逐条对应。 */
+export function normalize(status) {
+  if (typeof status === "number") {
+    if (status === 0) return "pending";
+    if (status === 1) return "scanned";
+    if (status === 2) return "success";
+    if (status === 3 || status === 4) return "expired";
+    return "pending";
+  }
+  if (typeof status === "string") {
+    const s = status.toLowerCase();
+    if (["confirmed", "confirm", "authorized", "success", "ok"].includes(s)) return "success";
+    if (["scaned", "scanned", "scan", "confirmed_wait"].includes(s)) return "scanned";
+    if (["expired", "timeout", "cancel", "cancelled", "canceled"].includes(s)) return "expired";
+    if (["error", "failed", "fail"].includes(s)) return "error";
+    if (["wait", "waiting", "pending", "created"].includes(s)) return "pending";
+    return "pending";
+  }
+  return "pending";
+}
+
+// ---------------------------------------------------------------- 状态落地
+
+/** 扫码成功后清掉属于**上一个 bot 会话**的路由字段。
+ * 游标/对端/上下文都绑在旧 token 上：换绑后带着它们用新 token 去 getupdates，
+ * iLink 以 errcode:-14 拒之（2026-10-23 真机事故）。`session_key` 是 PF 侧
+ * 会话归属，与 bot 无关，保留。 */
+export function reset_session_fields(st) {
+  for (const k of ["buf", "chat_id", "user_id", "context_token"]) delete st[k];
+}
+
+/** 重绑落地：**清旧路由字段 + 写新 bot 三件**（2026-10-24 用户定夺）。
+ * 必须喂**当场 loadState()** 的内容——严禁攥着旧快照整文件回写（自动续码
+ * 时代每个到期 worker 都把 begin 时的快照原样 save，把换绑刚写好的
+ * bot_token 盖回旧值——「重绑就废」的根因）。 */
+export function apply_success(st, bot_token, bot_id) {
+  st["bot_token"] = bot_token;
+  if (bot_id) st["bot_id"] = bot_id;
+  else delete st["bot_id"];
+ // sendmessage 的 from_user_id 就是 bot 自己，必须随换绑同步
+  if (bot_id) st["bot_user_id"] = bot_id;
+  else delete st["bot_user_id"];
+  reset_session_fields(st);
+  delete st["qrcode"];
+ // 旧码也要清：留着的话任何丢 token 的瞬间弹窗会画出**上一轮**的死码
+  delete st["qrcode_grid"];
+}
+
+/** 只动 `qrcode` 一个字段的最小写入口：当场新读-改-写，不碰其它字段。 */
+export function set_qrcode_fresh(deps, v) {
+  const st = deps.loadState();
+  if (v === null || v === undefined) delete st["qrcode"];
+  else st["qrcode"] = v;
+  deps.saveState(st);
+}
+
+// ---------------------------------------------------------------- 扫码全流程
+
+/** 扫码事件。 */
+// Ready{url} / Scanned / Success{bot_id} / Expired / Error{message}
+
+/**
+ * 扫码全流程（异步循环）：begin → 每 3s poll → 状态落盘 → 回调事件。
+ *
+ * deps：{ wire, loadState, saveState, sleep?, deadlineSec? }
+ * onEvent(event) 返回 **false** = 接收端被丢（UI 取消扫码）→ 清 qrcode 退出
+ * （不检查的话 worker 会空转到死线，2026-10-24 取消语义）。
+ *
+ * 返回取消函数（幂等，等价于 onEvent 返回 false）。
+ */
+export function runQrFlow(deps, onEvent) {
+  const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+ // 服务端实测：出码后 120s 返回 status=expired（dump 325/329 时间差 120s）。
+ // 本地死线取同一值，只做兜底；主判据永远是服务端的 expired。
+  const deadlineSec = deps.deadlineSec ?? 120;
+  let cancelled = false;
+  const cancel = () => { cancelled = true; };
+
+  const done = (async () => {
+    let qr;
+    try {
+      qr = await begin(deps.wire);
+    } catch (e) {
+      onEvent({ kind: "error", message: String(e?.message ?? e) });
+      return;
+    }
+    if (cancelled || onEvent({ kind: "ready", url: qr.qr_url }) === false) return;
+    set_qrcode_fresh(deps, qr.qrcode);
+
+ // 002·绑定3：**只有真的扫码**才算绑定成功。已绑过的 bot 再要码时，微信侧
+ // 常直接回 status=success（token 还是老的那条）——不设门就会「没扫也绑上」
+ // 。
+ // 判据：本次流程出现过 scanned 事件，或 success 带回的 token 与起点不同。
+ // 微信真机状态序列：wait → confirmed（=扫码已确认）→ 服务端 120s 后 expired。
+ // `confirmed` 就是扫码成功的证据（同一个 bot 重绑时 token 不变，不能拿 token
+ // 变化当判据，也不能要求先出现 scanned —— 实测这轮根本没 scanned）。
+ // 2026-10-28 真机：卡 scanned 导致 confirmed 被吞、扫完仍不绑定、最后白遮。
+
+    const started = Date.now();
+    while (!cancelled) {
+      let st;
+      try {
+        st = await poll(deps.wire, qr.qrcode);
+      } catch (e) {
+ // 状态接口偶发报错/超时**不是**码坏了：退避后继续（§6 坑 4：不能让循环
+ // 退出）。事件用 retry（可重试），绝不能报 error —— error 会让壳把二维码
+ // 白遮（态3），用户就没法扫了。
+        if (onEvent({ kind: "retry", message: String(e?.message ?? e) }) === false) {
+          set_qrcode_fresh(deps, null);
+          return;
+        }
+        await sleep(3000);
+        continue;
+      }
+ // 轮询状态落日志
+      console.error(`[wxbridge] qr status=${st.kind}`);
+      if (cancelled) return; // 取消后回来的在途响应一律丢弃（换人出码时防旧协程抢绑）
+      if (st.kind === "success") {
+        const fresh = deps.loadState(); // 当场读：严禁旧快照回写
+        apply_success(fresh, st.bot_token, st.bot_id);
+        deps.saveState(fresh);
+        onEvent({ kind: "success", bot_id: st.bot_id });
+        return;
+      }
+      if (st.kind === "expired") {
+        set_qrcode_fresh(deps, null);
+        onEvent({ kind: "expired" });
+        return;
+      }
+      if (st.kind === "scanned") {
+        if (onEvent({ kind: "scanned" }) === false) {
+          set_qrcode_fresh(deps, null);
+          return;
+        }
+      }
+      if (st.kind === "error") {
+        if (onEvent(st) === false) {
+          set_qrcode_fresh(deps, null);
+          return;
+        }
+      }
+      if ((Date.now() - started) / 1000 >= deadlineSec) {
+        set_qrcode_fresh(deps, null);
+        onEvent({ kind: "expired" });
+        return;
+      }
+      await sleep(3000);
+    }
+  })();
+
+ // 结束信号：任何退出路径（begin 失败/取消/死线/成功）都让调用方放锁。
+ // 没有它，begin() 一次网络失败就泄漏运行标志 —— 「刷新后永远不出码」的根因。
+  cancel.done = done;
+  return cancel;
+}

package/pi/register.test.mjs

@@ -0,0 +1,232 @@
+// register 单测 —— 与 wxprobe src/register.rs 单测逐条对齐（JS 版）。
+// 跑法：node --test packages/wechat-bridge/pi/register.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  begin, poll, normalize, unknownStatusMessage,
+  apply_success, reset_session_fields, set_qrcode_fresh, runQrFlow,
+} from "./register.mjs";
+
+// ---------------------------------------------------------------- 状态归一（ZCode 词表两套）
+
+test("normalize_numeric_status", () => {
+  assert.equal(normalize(0), "pending");
+  assert.equal(normalize(1), "scanned");
+  assert.equal(normalize(2), "success");
+  assert.equal(normalize(3), "expired");
+  assert.equal(normalize(4), "expired");
+  assert.equal(normalize(5), "pending", "表外数字归 pending（ZCode 语义）");
+  assert.equal(normalize(undefined), "pending");
+});
+
+test("normalize_string_status_wordlist", () => {
+  for (const s of ["confirmed", "confirm", "authorized", "success", "ok"]) assert.equal(normalize(s), "success", s);
+  for (const s of ["scaned", "scanned", "scan", "confirmed_wait"]) assert.equal(normalize(s), "scanned", s);
+  for (const s of ["expired", "timeout", "cancel", "cancelled", "canceled"]) assert.equal(normalize(s), "expired", s);
+  for (const s of ["error", "failed", "fail"]) assert.equal(normalize(s), "error", s);
+ // 实测：等待态返回 "wait"，不在 ZCode 词表，显式归并
+  for (const s of ["wait", "waiting", "pending", "created"]) assert.equal(normalize(s), "pending", s);
+  assert.equal(normalize("weird_state"), "pending", "词表外字符串归 pending（由 unknownStatusMessage 补文案）");
+});
+
+test("unknown_status_messages_carry_install_guidance", () => {
+ // 含 install 关键词 → 直接判定未安装并给行动指引
+  const m = unknownStatusMessage("not_install");
+  assert.ok(m.includes("未安装") && m.includes("ClawBot"), m);
+ // 其它未知字符串 → 原文透传 + 同样的指引
+  const m2 = unknownStatusMessage("weird_state");
+  assert.ok(m2.includes("weird_state") && m2.includes("未安装"), m2);
+ // 数字码与缺失 → 不产生错误（ZCode 语义归 pending）
+  assert.equal(unknownStatusMessage(5), undefined);
+  assert.equal(unknownStatusMessage(undefined), undefined);
+});
+
+// ---------------------------------------------------------------- 重绑语义（Rust 单测同款）
+
+test("rebind_clears_old_routing_fields_and_swaps_bot", () => {
+ // 重绑 = 清旧信息 + 换新 bot；session_key 是
+ // PF 侧归属，不在清理范围
+  const st = {
+    bot_token: "OLD-TOKEN",
+    bot_id: "old@im.bot",
+    bot_user_id: "old@im.bot",
+    buf: "OLD-CURSOR",
+    chat_id: "old@im.wechat",
+    user_id: "old@im.wechat",
+    context_token: "OLD-CTX",
+    session_key: "C:\\s.jsonl",
+    qrcode: "deadbeef",
+  };
+  apply_success(st, "NEW-TOKEN", "new@im.bot");
+  assert.equal(st.bot_token, "NEW-TOKEN");
+  assert.equal(st.bot_id, "new@im.bot");
+  assert.equal(st.bot_user_id, "new@im.bot", "from_user_id 必须跟新 bot 走");
+  for (const k of ["buf", "chat_id", "user_id", "context_token", "qrcode", "qrcode_grid"]) {
+    assert.ok(st[k] === undefined || st[k] === null, `${k} 必须被清掉`);
+  }
+  assert.equal(st.session_key, "C:\\s.jsonl", "PF 侧会话归属保留");
+});
+
+test("reset_clears_old_bot_routing_fields", () => {
+  const st = {
+    bot_token: "new-token",
+    bot_id: "new@im.bot",
+    buf: "OLD-BOT-CURSOR",
+    chat_id: "room@im.wechat",
+    user_id: "u@im.wechat",
+    context_token: "CT",
+    session_key: "C:\\sess\\a.jsonl",
+  };
+  reset_session_fields(st);
+  for (const k of ["buf", "chat_id", "user_id", "context_token"]) {
+    assert.ok(st[k] === undefined || st[k] === null, `${k} 必须被清掉——留着就是旧 bot 会话的游标/对端`);
+  }
+  assert.equal(st.session_key, "C:\\sess\\a.jsonl", "PF 侧会话归属保留");
+  assert.equal(st.bot_token, "new-token", "新 bot 字段不受影响");
+});
+
+// ---------------------------------------------------------------- 流程（fake wire）
+
+/** 脚本化 wire：get_qr 按 (qr-begin→begin / qr-status→status, 调用序) 出剧本。 */
+function fakeWire(script) {
+  const counters = { begin: 0, status: 0 };
+  return {
+    async get_qr(tag, path, query) {
+      const key = tag === "qr-begin" ? "begin" : "status";
+      const steps = script[key] ?? [];
+      const i = counters[key]++;
+      if (i >= steps.length) {
+ // 剧本演完：状态接口挂起返回 wait（流程自然等待）
+        return { status: "wait" };
+      }
+      const step = steps[i];
+      if (step.error) throw step.error;
+      return step.payload ?? step;
+    },
+  };
+}
+
+function fakeState(initial = {}) {
+  let st = { ...initial };
+  return {
+    load: () => ({ ...st }),
+    save: (n) => { st = { ...n }; },
+    get current() { return { ...st }; },
+  };
+}
+
+// 真机状态序列：wait → confirmed（扫码已确认）→ 服务端 120s 后 expired。
+// confirmed 必须当场绑定（同一个 bot 重绑 token 不变，不能拿 token 变化当判据）。
+test("runQrFlow_confirmed_without_scanned_binds_immediately", async () => {
+  const events = [];
+  const fake = fakeState({ bot_token: "SAME" }); // 旧 token 与新 token 相同（同 bot 重绑）
+  const wire = fakeWire({
+    begin: [{ qrcode: "QR1", qrcode_img_content: "https://qr/1", expires_in: 120 }],
+    status: [
+      { status: "wait" },
+      { status: "confirmed", bot_token: "SAME", ilink_bot_id: "bot@im.bot" },
+      { status: "expired" },
+    ],
+  });
+  runQrFlow(
+    { wire, loadState: fake.load, saveState: fake.save, sleep: () => Promise.resolve() },
+    (e) => { events.push(e); },
+  );
+  await new Promise((r) => setTimeout(r, 30));
+  const kinds = events.map((k) => k.kind);
+  assert.equal(kinds.filter((k) => k === "success").length, 1, "confirmed = 扫码成功，当场绑定");
+  assert.ok(!kinds.includes("expired"), "成功之后不再等到 expired");
+  assert.equal(fake.current["bot_token"], "SAME");
+});
+
+test("runQrFlow_success_writes_token_and_fires_events", async () => {
+  const events = [];
+  const fake = fakeState();
+  const wire = fakeWire({
+    begin: [{ qrcode: "QR1", qrcode_img_content: "https://qr/1", expires_in: 120 }],
+    status: [
+      { status: 0 },
+      { status: 1 },
+      { status: 2, bot_token: "TK1", ilink_bot_id: "bot@im.bot" },
+    ],
+  });
+  const cancel = runQrFlow(
+    { wire, loadState: fake.load, saveState: fake.save, sleep: () => Promise.resolve() },
+    (e) => { events.push(e); },
+  );
+  await new Promise((r) => setTimeout(r, 20));
+  cancel();
+  assert.deepEqual(events.map((e) => e.kind), ["ready", "scanned", "success"]);
+  assert.equal(events.find((e) => e.kind === "ready").url, "https://qr/1");
+  assert.equal(fake.current.bot_token, "TK1", "token 已落盘");
+  assert.equal(fake.current.bot_id, "bot@im.bot");
+  assert.equal(fake.current.qrcode, undefined, "成功后清 qrcode");
+  assert.equal(fake.current.buf, undefined, "旧游标随换绑清理");
+});
+
+test("runQrFlow_cancel_during_scanned_clears_qrcode", async () => {
+  const fake = fakeState();
+  const wire = fakeWire({
+    begin: [{ qrcode: "QR2" }],
+    status: [{ status: 1 }],
+  });
+  const cancel = runQrFlow(
+    { wire, loadState: fake.load, saveState: fake.save, sleep: () => Promise.resolve() },
+    (e) => (e.kind === "scanned" ? false : undefined), // UI 取消
+  );
+  await new Promise((r) => setTimeout(r, 20));
+  assert.equal(fake.current.qrcode, undefined, "取消后清 qrcode（不空转到死线）");
+  cancel();
+});
+
+test("runQrFlow_poll_error_keeps_looping_until_deadline", async () => {
+  const events = [];
+  const fake = fakeState();
+  const wire = fakeWire({
+    begin: [{ qrcode: "QR3" }],
+    status: [{ error: new Error("HTTP 500") }, { error: new Error("HTTP 500") }],
+  });
+  const cancel = runQrFlow(
+    { wire, loadState: fake.load, saveState: fake.save, sleep: () => Promise.resolve(), deadlineSec: 0.005 },
+    (e) => { events.push(e); },
+  );
+  await new Promise((r) => setTimeout(r, 30));
+  assert.ok(events.some((e) => e.kind === "retry"), "状态超时归 retry（不白遮二维码）");
+  assert.equal(events[events.length - 1].kind, "expired", "到死线收尾 expired（不静默死）");
+  cancel();
+});
+
+test("set_qrcode_fresh_touches_only_qrcode_field", () => {
+  const fake = fakeState({ bot_token: "tk", buf: "B" });
+  const deps = { loadState: fake.load, saveState: fake.save };
+  set_qrcode_fresh(deps, "abc");
+  assert.equal(fake.current.qrcode, "abc");
+  assert.equal(fake.current.bot_token, "tk", "其它字段不动");
+  assert.equal(fake.current.buf, "B");
+  set_qrcode_fresh(deps, null);
+  assert.equal(fake.current.qrcode, undefined);
+});
+
+test("runQrFlow_begin_failure_always_settles_done", async () => {
+ // begin 一次网络失败必须走完收尾（调用方靠 cancel.done 放锁）：
+ // 泄漏运行标志 = 刷新/重绑后再也不出码
+  const events = [];
+  const fake = fakeState();
+  const wire = fakeWire({ begin: [{ error: new Error("GET /get_bot_qrcode: timeout") }] });
+  const cancel = runQrFlow(
+    { wire, loadState: fake.load, saveState: fake.save, sleep: () => Promise.resolve() },
+    (e) => { events.push(e); },
+  );
+  assert.ok(cancel.done && typeof cancel.done.then === "function", "必须给结束信号");
+  await cancel.done;
+  assert.deepEqual(events.map((e) => e.kind), ["error"], "只报错，不静默");
+});
+
+test("pending_word_wait_is_not_reported_as_unknown", async () => {
+ // 实测 2026-10-24：等待态返回字符串 "wait"（ZCode 词表外但 normalize 认）。
+ // 若当未知状态报 error，壳会把二维码白遮 —— 用户没码可扫。
+  const ev = await poll({ get_qr: async () => ({ status: "wait" }) }, "QR");
+  assert.equal(ev.kind, "pending");
+});

package/pi/reply.mjs

@@ -0,0 +1,49 @@
+// reply —— 回复分块排版，自 wxprobe src/format/reply.rs 移植（JS 版）。
+//
+// hook 出站唯一依赖的两个函数：`split_long_reply_text`（3500 分块）与
+// `extract_bot_assistant_response_messages`（CRLF 归一 + 终态冲刷）。
+// 对拍基准 = wxprobe parity/ 的 golden.jsonl（ZCode 真实源码跑出的 71 条），
+// 其中 flush.* 两条与 blocks.* 的 content 段在这里逐字复刻（见 hook.test.mjs）。
+//
+// **暂缺**（与 Rust 版同口径）：工具调用摘要 / 变更摘要排版不移植——
+// 002 产品语义里微信只收 agent 发言，工具调用被 hook 过滤（滤工具调用提取发言）。
+
+/** ZCode `replyFormatter.ts:48-52` 的四个上限，本文件只用最后一个；
+ * 其余随工具摘要排版一并留在 Rust 参考里。 */
+export const MAX_REPLY_MESSAGE_LENGTH = 3500;
+
+/** ZCode `splitLongReplyText`（`replyFormatter.ts:266`），reply.rs 逐字移植。
+ *
+ * 断点取 `max(最后一个换行, 最后一个空格)`，**两者都没有才硬切 3500**；
+ * 切出的块与剩余部分都会 `trim`。断点优先级是 `Math.max` —— 意味着
+ * 只要窗口内有空格就优先在空格处断，哪怕换行更靠前。
+ *
+ * 字符计数按码点（`Array.from`），与 Rust `char` 对齐；ZCode 的 UTF-16
+ * 切法会在代理对中间产生乱码，码点切法更安全（reply.rs 同款差异说明）。 */
+export function split_long_reply_text(text) {
+  const chunks = [];
+  let remaining = text.trim();
+  let chars = Array.from(remaining);
+  while (chars.length > MAX_REPLY_MESSAGE_LENGTH) {
+ // ZCode 的 fromIndex 是 3500（含），这里取 0..=3500 这段找断点。
+ // lastIndexOf 缺席 = -1，与 Rust rposition 的 None 分支同语义。
+    const window = chars.slice(0, MAX_REPLY_MESSAGE_LENGTH + 1).join("");
+    const newline = window.lastIndexOf("\n");
+    const space = window.lastIndexOf(" ");
+    const breakpoint = Math.max(newline, space);
+    const end = breakpoint > 0 ? breakpoint : MAX_REPLY_MESSAGE_LENGTH;
+    chunks.push(chars.slice(0, end).join("").trim());
+    remaining = chars.slice(end).join("").trim();
+    chars = Array.from(remaining);
+  }
+  if (remaining !== "") chunks.push(remaining);
+  return chunks;
+}
+
+/** ZCode `extractBotAssistantResponseMessages`：非终态不 flush。
+ * 返回 `{ messages, rest }`（Rust 元组对位）；`rest` 恒为 CRLF 归一后的原文。 */
+export function extract_bot_assistant_response_messages(buffer, force) {
+  const normalized = buffer.replace(/\r\n/g, "\n");
+  if (!force) return { messages: [], rest: normalized };
+  return { messages: split_long_reply_text(normalized), rest: "" };
+}