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

package/pi/poller.mjs

@@ -0,0 +1,364 @@
+// getupdates 响应解析 —— 自 PF 仓 wxprobe src/poller.rs **逐条移植**（JS 版，照答案抄）。
+// 对拍基准：poller.rs 全部单测 + tests/fixtures/getupdates-real.json 真机夹具（随行李）。
+//
+// 对齐 ZCode `providers/weixinProvider.ts`，**所有候选字段名逐条照搬**：
+// - 消息数组 5 候选：`msgs | messages | updates | items | list`
+// - 游标 6 候选：`get_updates_buf | buf | next_buf | nextBuf | getUpdatesBuf | syncKey`
+// - 文本/用户/会话/昵称/消息 id 各自的多级候选（见下）
+// 字段命名保留 Rust 蛇形（与协议 wire 字段同名），便于与参考实现逐条对拍。
+
+import { unbig } from "./jsonx.mjs";
+
+const MSG_LIST_KEYS = ["msgs", "messages", "updates", "items", "list"];
+const BUF_KEYS = [
+  "get_updates_buf",
+  "buf",
+  "next_buf",
+  "nextBuf",
+  "getUpdatesBuf",
+  "syncKey",
+];
+// 严格照搬 ZCode `readWeixinUserId` 的顶层候选——**不能加裸 `id`**，
+// 否则会把消息 id 当成发送者 id（ZCode 没有这条候选）。
+const USER_KEYS = [
+  "from_user_id",
+  "from",
+  "from_user",
+  "fromUser",
+  "user",
+  "user_id",
+  "userId",
+];
+// ZCode 不读回发方向，但 sendmessage 需要 `from_user_id`=机器人自身，这里补一组候选。
+const BOT_KEYS = ["to_user_id", "to", "to_user", "toUser", "receiver", "target_id"];
+const CHAT_KEYS = ["room", "room_id", "roomId", "chat", "chat_id", "chatId"];
+const NAME_KEYS = [
+  "name",
+  "displayName",
+  "nickname",
+  "nick_name",
+  "remark",
+  "sender_name",
+  "from_name",
+  "title",
+  "account",
+  "alias",
+];
+const MSG_ID_KEYS = [
+  "id",
+  "msgid",
+  "msgId",
+  "msg_id",
+  "message_id",
+  "new_msg_id",
+  "svrMsgId",
+  "localId",
+];
+const CONTEXT_KEYS = ["context_token", "contextToken", "context"];
+const ATTACH_ITEM_KEYS = ["image_item", "file_item", "video_item", "audio_item", "media_item"];
+const NESTED_KEYS = ["msg", "message"];
+const TOP_TEXT_KEYS = ["text", "content", "message"];
+const NESTED_ID_KEYS = ["id", "wxid", "user_id", "userId"];
+
+// ---------------------------------------------------------------- 基础读侧
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Rust wire.rs::str_of：字符串（哨兵还原）→ 原样；数字 → String；其余 → undefined。 */
+function str_of(v, key) {
+  const x = v[key];
+  if (typeof x === "string") return unbig(x);
+  if (typeof x === "number") return String(x);
+  return undefined;
+}
+
+/** 依次取第一个非空候选键（Rust wire.rs::first_str 的防御式嗅探）；v 缺省（None）→ undefined。 */
+function first_str(v, keys) {
+  if (v === undefined || v === null) return undefined;
+  for (const k of keys) {
+    const s = str_of(v, k);
+    if (s !== undefined && s !== "") return s;
+  }
+  return undefined;
+}
+
+const hasOwn = (v, k) => Object.hasOwn(v, k);
+
+// ---------------------------------------------------------------- 嗅探（照 poller.rs）
+
+/** ZCode `readInboundMessage` 的内层：第一个**存在的** msg/message 键，是对象才取。 */
+function nested(m) {
+  for (const k of NESTED_KEYS) {
+    if (!hasOwn(m, k)) continue;
+    return isObj(m[k]) ? m[k] : undefined;
+  }
+  return undefined;
+}
+
+function item_list(m, inner) {
+  for (const src of [m, inner]) {
+    if (src === undefined) continue;
+    const list = src["item_list"];
+    if (Array.isArray(list) && list.length > 0) return list;
+  }
+  return [];
+}
+
+/** ZCode `readWeixinText`：顶层 text/content/message → item_list 拼接 → inner.text/content。 */
+function read_text(m, inner) {
+  const top = first_str(m, TOP_TEXT_KEYS);
+  if (top !== undefined) return top;
+  const parts = item_list(m, inner)
+    .map(read_text_item)
+    .filter((s) => s !== undefined && s !== "");
+  if (parts.length > 0) return parts.join("\n");
+  return (inner !== undefined && first_str(inner, TOP_TEXT_KEYS)) || "";
+}
+
+function read_text_item(item) {
+  const ti = item["text_item"];
+  const t =
+    (isObj(ti) ? str_of(ti, "text") : undefined) ??
+    str_of(item, "text") ??
+    str_of(item, "content");
+  return t !== undefined && t !== "" ? t : undefined;
+}
+
+function count_attachments(m, inner) {
+  let direct = 0;
+  for (const src of [m, inner]) {
+    if (src !== undefined && Array.isArray(src["attachments"])) {
+      direct += src["attachments"].length;
+    }
+  }
+  const fromItems = item_list(m, inner).filter(
+    (it) =>
+      read_text_item(it) === undefined &&
+      (ATTACH_ITEM_KEYS.some((k) => hasOwn(it, k)) || str_of(it, "kind") !== undefined),
+  ).length;
+  return direct + fromItems;
+}
+
+/** 嵌套 from/sender 对象里的 id 嗅探（readWeixinUserId / bot 反推共用）。 */
+function nested_id(src, keys) {
+  if (src === undefined) return undefined;
+  for (const k of keys) {
+    if (!hasOwn(src, k)) continue;
+    const o = src[k];
+    if (!isObj(o)) continue;
+    const s = first_str(o, NESTED_ID_KEYS);
+    if (s !== undefined) return s;
+  }
+  return undefined;
+}
+
+/** ZCode `readWeixinUserId`：顶层候选 → from/sender.id → 内层两级。缺失 = 空串（丢弃信号）。 */
+function read_user_id(m, inner) {
+  return (
+    first_str(m, USER_KEYS) ??
+    nested_id(m, ["from", "sender"]) ??
+    first_str(inner, USER_KEYS) ??
+    nested_id(inner, ["from", "sender"]) ??
+    ""
+  );
+}
+
+/** 机器人自身 id（`sendmessage.from_user_id`）：从消息的回发方向反推。 */
+function read_bot_user_id(m, inner) {
+  return (
+    first_str(m, BOT_KEYS) ??
+    nested_id(m, BOT_KEYS) ??
+    first_str(inner, BOT_KEYS) ??
+    nested_id(inner, BOT_KEYS)
+  );
+}
+
+/** ZCode `readWeixinMessageId`：先按字符串取（两级候选），再退回数字。 */
+function read_msg_id(m, inner) {
+  const s =
+    first_str(m, MSG_ID_KEYS) ??
+    (inner !== undefined ? first_str(inner, MSG_ID_KEYS) : undefined);
+  if (s !== undefined) return s;
+  for (const src of [m, inner]) {
+    if (src === undefined) continue;
+    for (const k of MSG_ID_KEYS) {
+      const v = src[k];
+      if (typeof v === "number") return String(v);
+    }
+  }
+  return undefined;
+}
+
+/** ZCode `readNextBuf`：6 个候选字段名。 */
+function read_next_buf(container) {
+  return first_str(container, BUF_KEYS);
+}
+
+function read_inbound(m) {
+  const inner = nested(m);
+  const text = read_text(m, inner);
+  const attachments = count_attachments(m, inner);
+  if (text.trim() === "" && attachments === 0) return null; // 空消息丢弃
+  const user_id = read_user_id(m, inner);
+  if (user_id === "") return null; // ZCode 同语义：缺发送者丢弃，否则回发 to 为空
+  return {
+    msg_id: read_msg_id(m, inner),
+    text,
+    user_id,
+    bot_user_id: read_bot_user_id(m, inner),
+    chat_id: first_str(m, CHAT_KEYS) ?? (inner !== undefined ? first_str(inner, CHAT_KEYS) : undefined),
+    name: first_str(m, NAME_KEYS) ?? (inner !== undefined ? first_str(inner, NAME_KEYS) : undefined),
+    context_token: first_str(m, CONTEXT_KEYS) ?? (inner !== undefined ? first_str(inner, CONTEXT_KEYS) : undefined),
+    attachments,
+  };
+}
+
+// ---------------------------------------------------------------- 诊断（P0 产出：字段形状对拍）
+
+function keys_of(v) {
+  if (isObj(v)) {
+    const ks = Object.keys(v);
+    return ks.length === 0 ? "（空）" : ks.join(", ");
+  }
+  return `非对象: ${JSON.stringify(v)}`;
+}
+
+function probe_text(m) {
+  const inner = nested(m);
+  const hits = [];
+  for (const k of TOP_TEXT_KEYS) {
+    if (str_of(m, k) !== undefined) hits.push(`顶层.${k}`);
+  }
+  for (const [label, src] of [["顶层", m], ["内层", inner]]) {
+    if (src === undefined) continue;
+    const list = src["item_list"];
+    if (!Array.isArray(list)) continue;
+    list.forEach((it, ix) => {
+      if (read_text_item(it) !== undefined) hits.push(`${label}.item_list[${ix}]`);
+    });
+  }
+  return hits.length > 0 ? hits.join(", ") : "（无）";
+}
+
+function diagnose(container, raw_msgs) {
+  const out = [];
+  out.push(`顶层键: ${keys_of(container)}`);
+  const picked = MSG_LIST_KEYS.find((k) => hasOwn(container, k));
+  out.push(`消息数组键: ${picked ?? "未命中任何候选"}`);
+  const hits = BUF_KEYS.filter((k) => hasOwn(container, k));
+  out.push(`游标命中: ${hits.length > 0 ? hits.join(", ") : "（无）"}`);
+  const m = raw_msgs[0];
+  if (m !== undefined) {
+    out.push(`首条消息键: ${keys_of(m)}`);
+    const inner = nested(m);
+    if (inner !== undefined) out.push(`  内层(msg/message)键: ${keys_of(inner)}`);
+    const items = item_list(m, inner);
+    if (items.length > 0) {
+      out.push(`  item_list[${items.length}]: ${items.map((it) => keys_of(it)).join(" | ")}`);
+    }
+    out.push(`  文本候选命中: ${probe_text(m)}`);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- 入口
+
+/** getupdates 长轮询一拍（Rust poller.rs::get_updates 同名移植）。 */
+export async function get_updates(wire, token, buf) {
+  const payload = await wire.post_poll(
+    "getupdates",
+    "/getupdates",
+    token,
+    { get_updates_buf: buf ?? "" },
+  );
+  return parse_updates(payload, buf ?? null);
+}
+
+/**
+ * 纯解析：把 getupdates 响应映射成 Updates（Rust poller.rs::parse_updates 同名移植）。
+ * 与传输解耦，真机响应才能落成黄金夹具做单测。
+ *
+ * @param {object} payload getupdates 响应（建议经 jsonx.parse，message_id 需保精度）
+ * @param {string|null} previous_buf 入参旧游标；服务端没给新游标时回落（ZCode `readNextBuf(...) ?? buf`）
+ */
+export function parse_updates(payload, previous_buf = null) {
+  const container = payload ?? {};
+  const raw_msgs = MSG_LIST_KEYS.map((k) => container[k]).find(Array.isArray) ?? [];
+  const messages = raw_msgs.map(read_inbound).filter((x) => x !== null);
+  return {
+    raw_count: raw_msgs.length,
+    messages,
+ // 服务端没给新游标就沿用旧值——保证「启停不丢不重」。
+    next_buf: read_next_buf(container) ?? previous_buf,
+    diagnostics: diagnose(container, raw_msgs),
+  };
+}
+
+/**
+ * 剥掉 ANSI 转义序列（CSI 色码、nF 两字节转义）—— Rust poller.rs::strip_ansi 同名移植。
+ * 微信是纯文本通道，控制符会原样显示成乱码（真机：`\x1b[38;5;5m🔌 MCP: …` 直达用户）。
+ */
+export function strip_ansi(text) {
+  let out = "";
+  const ch = Array.from(text); // 按 code point 迭代，emoji 不拆
+  let i = 0;
+  while (i < ch.length) {
+    const c = ch[i];
+    if (c !== "\x1b") {
+      out += c;
+      i += 1;
+      continue;
+    }
+    const nx = ch[i + 1];
+    if (nx === "[") {
+ // CSI：参数/中间字节一路吃，终止字节（@–~，含）为止
+      i += 2;
+      while (i < ch.length) {
+        const t = ch[i];
+        i += 1;
+        if (t >= "@" && t <= "~") break;
+      }
+    } else if (nx !== undefined) {
+ // 吃一个字符；若是 nF 中间字节（0x20–0x2F）再吃终止字节（0x30–0x7E）
+      i += nx >= " " && nx <= "/" ? 3 : 2;
+    } else {
+      i += 1; // 悬尾 ESC 直接丢弃
+    }
+  }
+  return out;
+}
+
+/** ZCode `buildWeixinText`：微信各客户端对 LF 处理不一致，发送前统一 CRLF。 */
+export function normalize_crlf(text) {
+  return text.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n");
+}
+
+// ---------------------------------------------------------------- sendmessage（出站）
+
+let SEND_SEQ = 0;
+
+/**
+ * sendmessage 回发一条文本（Rust poller.rs::send_text 同名移植）。
+ *
+ * iLink 协议参考（epiral/weixin-bot PROTOCOL.md）：`client_id` = "unique_id"
+ * ——**每条消息唯一**。state 里存的是稳定实例 id，这里拼上毫秒 + 序列号
+ * 成每条唯一（2026-10-23 真机排障：受理返回 message_id 但手机不投递，
+ * 按 ZCode 语义逐项对拍时唯一的协议违规点）。
+ */
+export async function send_text(wire, token, from_user, to_user, text, context_token, client_id) {
+  const seq = SEND_SEQ++;
+  const millis = Date.now();
+  const unique_client_id = `${client_id}-${millis}-${seq}`;
+ // ZCode `buildWeixinText`：微信各客户端对 LF 处理不一致，统一 CRLF
+  const normalized = normalize_crlf(strip_ansi(text));
+  const msg = {
+    from_user_id: from_user,
+    to_user_id: to_user,
+    client_id: unique_client_id,
+    message_type: 2,
+    message_state: 2,
+    item_list: [{ type: 1, text_item: { text: normalized } }],
+  };
+  if (context_token && context_token !== "") msg.context_token = context_token;
+  await wire.post("sendmessage", "/sendmessage", token, { msg });
+}

package/pi/poller.test.mjs

@@ -0,0 +1,191 @@
+// poller 对拍单测 —— 与 PF 仓 wxprobe src/poller.rs 单测**逐条对齐**（JS 版）。
+// 跑法：node --test packages/wechat-bridge/pi/
+// 真机夹具随行李：pi/fixtures/getupdates-real.json。
+// iLink 协议一变，这里最先红。
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { parse_updates, strip_ansi, normalize_crlf } from "./poller.mjs";
+import { parse, guardBigInt, unbig } from "./jsonx.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fixtureText = readFileSync(join(here, "fixtures", "getupdates-real.json"), "utf8");
+const realPayload = () => parse(fixtureText);
+
+// ---------------------------------------------------------------- 真机夹具对拍
+
+test("parses_real_getupdates_fixture", () => {
+  const up = parse_updates(realPayload(), null);
+  assert.equal(up.raw_count, 1, "原始消息数");
+  assert.equal(up.messages.length, 1, "解析成功数");
+  const m = up.messages[0];
+  assert.equal(m.text, "测试文本");
+  assert.equal(m.user_id, "user_sandbox@im.wechat");
+  assert.equal(m.bot_user_id, "bot_sandbox@im.bot");
+ // 19 位大整数：JSON.parse 会丢精度，jsonx 哨兵方案必须精确到个位
+  assert.equal(m.msg_id, "7513480159106982024");
+  assert.equal(m.context_token, "SANITIZED_CONTEXT_TOKEN");
+  assert.equal(m.chat_id, undefined, "私聊没有 room/chat 字段");
+  assert.equal(m.attachments, 0);
+});
+
+test("cursor_taken_from_server_on_first_poll", () => {
+  const expected = realPayload()["get_updates_buf"];
+  const up = parse_updates(realPayload(), null);
+  assert.equal(up.next_buf, expected);
+});
+
+test("cursor_falls_back_to_previous_when_server_omits_it", () => {
+ // 服务端没给新游标（或给空串）时必须沿用旧值，否则「启停」会把游标冲掉。
+  const payload = realPayload();
+  payload["get_updates_buf"] = "";
+  const up = parse_updates(payload, "PREVIOUS_CURSOR");
+  assert.equal(up.next_buf, "PREVIOUS_CURSOR");
+});
+
+test("cursor_keeps_previous_when_field_absent_entirely", () => {
+  const up = parse_updates({ msgs: [] }, "PREVIOUS_CURSOR");
+  assert.equal(up.next_buf, "PREVIOUS_CURSOR");
+  assert.equal(up.raw_count, 0);
+});
+
+test("message_without_sender_is_dropped", () => {
+  const payload = {
+    msgs: [{ message_id: 1, item_list: [{ type: 1, text_item: { text: "hi" } }] }],
+    get_updates_buf: "X",
+  };
+  const up = parse_updates(payload, null);
+  assert.equal(up.raw_count, 1, "原始数组仍计数");
+  assert.equal(up.messages.length, 0, "缺发送者的消息必须被丢弃");
+});
+
+test("attachment_item_is_counted_and_text_item_is_not", () => {
+ // 纯图片消息没有 text，靠附件计数才不会被当成空消息丢掉。
+  const payload = {
+    msgs: [
+      {
+        from_user_id: "user_sandbox@im.wechat",
+        item_list: [
+          { type: 1, image_item: { media: { url: "https://x/img.png", aes_key: "K" } } },
+        ],
+      },
+    ],
+    get_updates_buf: "X",
+  };
+  const up = parse_updates(payload, null);
+  assert.equal(up.messages.length, 1);
+  assert.equal(up.messages[0].attachments, 1);
+  assert.equal(up.messages[0].text, "");
+});
+
+test("diagnostics_report_the_real_field_names", () => {
+ // 直接对拍候选嗅探：命中哪个候选必须打印出来。
+  const up = parse_updates(realPayload(), null);
+  const joined = up.diagnostics.join("\n");
+  assert.ok(joined.includes("消息数组键: msgs"), `候选 1 应命中：${joined}`);
+  assert.ok(joined.includes("游标命中: get_updates_buf"), `候选 1 应命中：${joined}`);
+  assert.ok(joined.includes("文本候选命中: 顶层.item_list[0]"), joined);
+  assert.ok(!joined.includes("未命中任何候选"), joined);
+});
+
+test("text_item_wins_over_nested_content", () => {
+ // 顶层 text 与 item_list 同时存在时，顶层优先（ZCode readWeixinText 同序）。
+  const payload = {
+    msgs: [
+      {
+        from_user_id: "u@x",
+        text: "顶层文本",
+        item_list: [{ type: 1, text_item: { text: "item 文本" } }],
+      },
+    ],
+  };
+  const up = parse_updates(payload, null);
+  assert.equal(up.messages[0].text, "顶层文本");
+});
+
+// ---------------------------------------------------------------- 游标语义（at-least-once）
+
+test("twenty_start_stop_cycles_never_lose_or_duplicate_the_cursor", () => {
+ // 对应验收「重复启停 20 次游标不丢不重」的确定性版本：
+ // 每个周期 = load → getupdates → **处理完** → 写回，跑 20 轮。
+  const serverCursor = realPayload()["get_updates_buf"];
+  let stored = null;
+  for (let cycle = 0; cycle < 20; cycle += 1) {
+ // 只有第 1 轮服务端发了新游标，其余 19 轮都是空闲（不带该字段）。
+    const payload = cycle === 0 ? realPayload() : { msgs: [] };
+    const up = parse_updates(payload, stored);
+ // 写回发生在本批消息全部处理完之后（ZCode weixinChannelRuntime.ts:155-163）
+    if (up.next_buf !== null && up.next_buf !== undefined) stored = up.next_buf;
+  }
+  assert.equal(
+    stored,
+    serverCursor,
+    "20 次启停后游标必须恰好等于服务端最后一次下发的值——既不能丢，也不能被重复推进",
+  );
+});
+
+test("idle_polls_do_not_advance_the_cursor", () => {
+  const up = parse_updates({ msgs: [], get_updates_buf: "" }, "CURSOR_V1");
+  assert.equal(up.next_buf, "CURSOR_V1", "空闲轮询不得改写游标");
+});
+
+// ---------------------------------------------------------------- strip_ansi
+
+test("strip_ansi_removes_sgr_color_codes", () => {
+ // 2026-10-23 真机 sendmessage 实发内容：色码直达微信用户
+  assert.equal(strip_ansi("\x1b[38;5;5m🔌 MCP: 1 server enabled\x1b[39m"), "🔌 MCP: 1 server enabled");
+});
+
+test("strip_ansi_keeps_plain_text_and_newlines", () => {
+  const s = "第一行\n第二行 with emoji ✅ no escapes";
+  assert.equal(strip_ansi(s), s);
+});
+
+test("strip_ansi_handles_trailing_escape_and_two_byte_forms", () => {
+  assert.equal(strip_ansi("ab\x1b"), "ab", "悬尾 ESC 直接丢弃");
+  assert.equal(strip_ansi("a\x1b(Bb"), "ab", "两字节转义整对丢弃");
+});
+
+test("normalize_crlf_unifies_line_endings", () => {
+ // ZCode buildWeixinText：微信各客户端对 LF 处理不一致，统一 CRLF
+  assert.equal(normalize_crlf("a\r\nb\nc"), "a\r\nb\r\nc");
+});
+
+// ---------------------------------------------------------------- jsonx（大整数保精度）
+
+test("jsonx_preserves_19_digit_message_id", () => {
+  const raw = '{"message_id":7513480159106982024,"n":13,"f":1.5}';
+  const v = parse(raw);
+  assert.equal(typeof v.message_id, "string", "超安全区间整数 → 哨兵字符串");
+  assert.equal(unbig(v.message_id), "7513480159106982024");
+  assert.equal(v.n, 13, "安全区间整数保持 number");
+  assert.equal(v.f, 1.5, "浮点不动");
+});
+
+test("jsonx_leaves_digits_inside_strings_alone", () => {
+  const v = parse('{"s":"12345678901234567890","esc":"a\\"12345678901234567890"}');
+  assert.equal(v.s, "12345678901234567890", "字符串值里的长数字不是 JSON 数字，不哨兵化");
+  assert.equal(v.esc, 'a"12345678901234567890');
+});
+
+test("jsonx_handles_arrays_and_boundaries", () => {
+  const v = parse('{"a":[7513480159106982024,9007199254740991,9007199254740993]}');
+  assert.equal(unbig(v.a[0]), "7513480159106982024");
+  assert.equal(v.a[1], 9007199254740991, "2^53-1 恰好安全，保持 number");
+  assert.equal(unbig(v.a[2]), "9007199254740993", "2^53+1 已不安全");
+});
+
+test("jsonx_guard_output_is_valid_json_and_unbig_round_trips", () => {
+  const raw = '{"message_id":7513480159106982024,"user":"u1"}';
+  const guarded = guardBigInt(raw);
+  assert.doesNotThrow(() => JSON.parse(guarded), "哨兵化后仍是合法 JSON");
+  assert.ok(
+    guarded.includes(JSON.stringify("\u0000BI:7513480159106982024")),
+    "裸整数应被包成哨兵字符串",
+  );
+  assert.ok(!guarded.includes("user\":\"\u0000"), "普通字符串值不动");
+});