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

package/pi/wire.mjs

@@ -0,0 +1,219 @@
+// wire —— iLink HTTP 传输层，自 PF 仓 wxprobe src/wire.rs **逐条移植**（JS 版）。
+// pi ext = Node 全权代码（契约 v2.4 pi_extensions），fetch/fs 直用，零 npm 依赖。
+//
+// 出站行为对齐 ZCode `packages/services/src/bots/providers/`：
+// - 扫码接口：GET + `iLink-App-ClientVersion: 1`（weixinRegistration.ts:86-101）
+// - 业务接口：POST + `AuthorizationType: ilink_bot_token` + `Bearer` +
+// `X-WECHAT-UIN` + `base_info.channel_version`（weixinProvider.ts:104-155）
+// - 三档超时 30s / 90s / 15s，分别对齐 ZCode 的三个常量
+//
+// **每个请求的 request 与 response 原样落盘**（dump_dir）—— 2026-10-23 真机
+// -14 静默重试数小时的教训：没有原始报文就只能靠猜。
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "./jsonx.mjs";
+
+export const ILINK_BASE = "https://ilinkai.weixin.qq.com";
+export const API_PREFIX = "/ilink/bot";
+export const CHANNEL_VERSION = "2.0.0";
+
+/** 扫码接口超时（ZCode WEIXIN_LOGIN_REQUEST_TIMEOUT_MS）。 */
+export const QR_TIMEOUT_MS = 30_000;
+/** getupdates 长轮询超时（ZCode WEIXIN_GET_UPDATES_TIMEOUT_MS）。 */
+export const POLL_TIMEOUT_MS = 90_000;
+/** 普通业务接口超时（ZCode BOT_PROVIDER_REQUEST_TIMEOUT_MS）。 */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** dump 目录只留最近这么多对文件，探针反复跑不会把磁盘写爆。 */
+const DUMP_KEEP = 120;
+
+export function sha256_hex(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+export class Wire {
+  /** @param {string|null} dumpDir 原始报文落盘目录；null = 不落盘（单测） */
+  constructor(dumpDir = null) {
+    this.dumpDir = dumpDir;
+    if (dumpDir) {
+      try { mkdirSync(dumpDir, { recursive: true }); } catch { /* 排障产物，尽力而为 */ }
+      this.#prune();
+    }
+    this.seq = this.#nextSeq();
+  }
+
+  /** 扫码：`GET /ilink/bot/<path>?<query>`，无鉴权（30s）。 */
+  async get_qr(tag, path, query = []) {
+    const url = new URL(API_PREFIX + path, ILINK_BASE);
+    for (const [k, v] of query) url.searchParams.set(k, v);
+    const seq = this.seq++;
+    try {
+      const res = await fetch(url, {
+        headers: { "iLink-App-ClientVersion": "1" },
+        signal: AbortSignal.timeout(QR_TIMEOUT_MS),
+      });
+      return await this.#consume(tag, seq, res, null);
+    } catch (e) {
+      throw new Error(`GET ${path}: ${e.message ?? e}`);
+    }
+  }
+
+  /** 业务：`POST /ilink/bot/<path>`，带 bot_token（15s）。 */
+  async post(tag, path, token, body) {
+    return this.#postInner(DEFAULT_TIMEOUT_MS, tag, path, token, body);
+  }
+
+  /** getupdates 长轮询（90s）—— JS await 原生生态位：await 期间 send 并发照跑。 */
+  async post_poll(tag, path, token, body) {
+    return this.#postInner(POLL_TIMEOUT_MS, tag, path, token, body);
+  }
+
+  async #postInner(timeoutMs, tag, path, token, body) {
+    const url = ILINK_BASE + API_PREFIX + path;
+    const headers = {};
+    if (token) {
+      headers["content-type"] = "application/json";
+      headers["AuthorizationType"] = "ilink_bot_token";
+      headers["Authorization"] = `Bearer ${token}`;
+      headers["X-WECHAT-UIN"] = wechat_uin();
+    }
+    const payload = with_base_info(body);
+    const seq = this.seq++;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      return await this.#consume(tag, seq, res, payload);
+    } catch (e) {
+      throw new Error(`POST ${path}: ${e.message ?? e}`);
+    }
+  }
+
+  async #consume(tag, seq, res, reqBody) {
+    const text = await res.text();
+    this.#dump(seq, tag, res.status, reqBody, text);
+    if (!(res.status >= 200 && res.status < 300)) {
+      throw new Error(`${tag}: HTTP ${res.status}: ${truncate(text, 400)}`);
+    }
+    let value;
+    try {
+      value = parse(text); // jsonx：message_id 等 19 位整数保精度
+    } catch (e) {
+      throw new Error(`${tag}: 非 JSON 响应 ${e.message}: ${truncate(text, 400)}`);
+    }
+    check_ret(value);
+    return unwrap_data(value);
+  }
+
+ #dump(seq, tag, status, req, resText) {
+    if (!this.dumpDir) return;
+    const base = join(this.dumpDir, `${String(seq).padStart(3, "0")}-${tag}`);
+    try {
+      if (req) writeFileSync(`${base}.req.json`, JSON.stringify(req, null, 2));
+      writeFileSync(`${base}.res.txt`, `HTTP ${status}\n${resText}`);
+    } catch { /* 排障产物，尽力而为 */ }
+  }
+
+ #nextSeq() {
+    if (!this.dumpDir) return 1;
+    try {
+      let max = 0;
+      for (const name of readdirSync(this.dumpDir)) {
+        const m = /^(\d+)-/.exec(name);
+        if (m) max = Math.max(max, Number(m[1]));
+      }
+      return max + 1;
+    } catch {
+      return 1;
+    }
+  }
+
+  /** 按 `.res.txt` 后缀识别响应文件（`Path::extension` 对它返回 "txt" 的坑，见 wire.rs）。 */
+ #prune() {
+    let resFiles;
+    try {
+ // 数值序：文件名以 seq 开头，字典序会把 "1000-…" 排在 "880-…" 前面，
+ // 剪掉的是**最新**的 dump
+      resFiles = readdirSync(this.dumpDir)
+        .filter((n) => n.endsWith(".res.txt"))
+        .sort((a, b) => (Number.parseInt(a, 10) || 0) - (Number.parseInt(b, 10) || 0));
+    } catch {
+      return;
+    }
+    if (resFiles.length <= DUMP_KEEP) return;
+    for (const name of resFiles.slice(0, resFiles.length - DUMP_KEEP)) {
+      const base = join(this.dumpDir, name.slice(0, -".res.txt".length));
+      try { rmSync(`${base}.res.txt`, { force: true }); } catch { /* 尽力而为 */ }
+      try { rmSync(`${base}.req.json`, { force: true }); } catch { /* 尽力而为 */ }
+    }
+  }
+}
+
+/** ZCode `appendBaseInfo`：`{ base_info, ...body }`。 */
+export function with_base_info(body) {
+  return { base_info: { channel_version: CHANNEL_VERSION }, ...body };
+}
+
+/** ZCode `unwrapData`：`payload.data ?? payload`（扫码接口把字段包在 `data` 里）。 */
+export function unwrap_data(value) {
+  const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+  if (isObj(value) && "data" in value && isObj(value.data)) {
+    const merged = { ...value };
+    delete merged.data;
+    for (const [k, v] of Object.entries(value.data)) {
+      if (!(k in merged)) merged[k] = v; // or_insert：顶层已有键优先
+    }
+    return merged;
+  }
+  return value;
+}
+
+/** ZCode `requestWeixinJson` 的 ret/errcode 校验（weixinProvider.ts:141-150）。 */
+export function check_ret(payload) {
+  const ret = num(payload, "ret");
+  const errcode = num(payload, "errcode");
+  if ((ret !== undefined && ret !== 0) || (errcode !== undefined && errcode !== 0)) {
+    const msg = str_of(payload, "errmsg") ?? str_of(payload, "message") ?? "";
+ // 错误串形态与 Rust 对齐：is_session_timeout 靠「errcode=-14」与
+ // 服务端原文 "session timeout" 判过期（transport.is_session_timeout）
+    throw new Error(`iLink 业务错误 ret=${fmt_opt(ret)} errcode=${fmt_opt(errcode)} ${msg}`);
+  }
+}
+
+export function num(v, key) {
+  const x = v?.[key];
+  return typeof x === "number" ? x : undefined;
+}
+
+export function str_of(v, key) {
+  const x = v?.[key];
+  if (typeof x === "string") return x;
+  if (typeof x === "number") return String(x);
+  return undefined;
+}
+
+function fmt_opt(v) {
+  return v === undefined ? "None" : `Some(${v})`;
+}
+
+/** `X-WECHAT-UIN` = base64(十进制 u32 的 UTF-8 字节)，ZCode `buildRandomWechatUin`。 */
+export function wechat_uin() {
+  const nanos = (Date.now() % 1_000_000) * 1000 || 0x5eed;
+  const mixed = (nanos ^ (process.pid * 2_654_435_761)) >>> 0;
+  return Buffer.from(String(mixed), "utf8").toString("base64");
+}
+
+export function truncate(s, n) {
+  return Array.from(s).length <= n ? s : Array.from(s).slice(0, n).join("") + "…";
+}
+
+/** 供排障：dump 目录里最近一次 getupdates 响应原文（存在时）。 */
+export function last_dump(dumpDir, tag) {
+  const p = join(dumpDir, `${tag}.res.txt`);
+  return existsSync(p) ? readFileSync(p, "utf8") : null;
+}

package/pi/wire.test.mjs

@@ -0,0 +1,29 @@
+// wire dump 剪枝单测 —— #prune 的排序口径。
+// 跑法：node --test packages/pf-wxbot/pi/wire.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Wire } from "./wire.mjs";
+
+test("prune_keeps_newest_by_numeric_seq_not_lexicographic", () => {
+  const dir = mkdtempSync(join(tmpdir(), "wxwire-"));
+ // 125 个 res：1..5（老）+ 1000..1119（新）。字典序会把 "1000-…" 排在
+ // "880-…"/"5-…" 前面 —— 旧实现剪的是**最新**的 dump（2026-10-29 排障时
+ // qr-status 证据文件就是这样被吃掉的）。数值序必须剪最老的 1..5。
+  for (let i = 1; i <= 5; i += 1) writeFileSync(join(dir, `${i}-getupdates.res.txt`), "x");
+  for (let i = 1000; i <= 1119; i += 1) writeFileSync(join(dir, `${i}-getupdates.res.txt`), "x");
+
+  new Wire(dir); // 构造即 prune（DUMP_KEEP = 120）
+
+  const left = new Set(readdirSync(dir));
+  for (let i = 1; i <= 5; i += 1) {
+    assert.ok(!left.has(`${i}-getupdates.res.txt`), `最老 dump ${i} 被剪`);
+  }
+  for (let i = 1000; i <= 1119; i += 1) {
+    assert.ok(left.has(`${i}-getupdates.res.txt`), `最新 dump ${i} 保留`);
+  }
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.