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

package/pi/state.mjs

@@ -0,0 +1,248 @@
+// state —— 状态盘最小面（transport 运行所需），自 wxprobe src/state.rs 移植。
+// 运行态机（Service/Health/WxLine/Snapshot）在文件后半段：自 PF 仓
+// remote_control/state.rs 移植（七字段快照 + mtime 友好，PF壳只读镜像）。
+//
+// **落盘位置 = 包内 data/**（约定①）：ext 从包内路径被 -e 挂载，自定位
+// `__dirname/../data/` = 状态目录（与宿主 ChatHost dir 同源，卸载随删——
+// 重装即重绑，语义干净）。锁是唯一例外：必须在全局（lock.mjs 自述）。
+//
+// 游标持久化遵循 ZCode bugfix：**等本批消息全部处理完再写**（transport.ack_cursor），
+// 先写游标会让进程中途失败时跳过未处理消息（weixinChannelRuntime.ts:155-163）。
+
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "./jsonx.mjs";
+
+const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const dataDir = join(pkgDir, "data");
+
+/** 包内状态目录（约定①）。 */
+export function base_dir() {
+  return dataDir;
+}
+
+export function state_path() {
+  return join(dataDir, "wx-state.json");
+}
+
+export function dump_dir() {
+  return join(dataDir, "dump");
+}
+
+/** 坏 JSON / 缺文件 → {}（宿主把坏盘落成空串，兜底是插件的责任）。 */
+export function load() {
+  try {
+    const raw = readFileSync(state_path(), "utf8");
+    const v = parse(raw);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+  } catch {
+    return {};
+  }
+}
+
+/** 原子写（tmp + rename），避免半截 JSON。 */
+export function save(state) {
+  try {
+    mkdirSync(dataDir, { recursive: true });
+    const tmp = `${state_path()}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2));
+    renameSync(tmp, state_path());
+  } catch (e) {
+    console.error(`[wxbridge] 写状态失败: ${e?.message ?? e}`);
+  }
+}
+
+/** trim + 空串视同缺失（wxprobe get_str 同语义）。 */
+export function get_str(state, key) {
+  const v = state?.[key];
+  if (typeof v !== "string") return undefined;
+  const s = v.trim();
+  return s === "" ? undefined : s;
+}
+
+/** set(state, key, null) = 删除键。 */
+export function set(state, key, value) {
+  if (value === null || value === undefined) delete state[key];
+  else state[key] = value;
+}
+
+/** 新生成的 client_id（对齐 ZCode `zcode-weixin-<uuid>` 形态）。 */
+export function ensure_client_id(state) {
+  const existing = get_str(state, "client_id");
+  if (existing) return existing;
+  const id = `wxbridge-${process.pid.toString(16).padStart(8, "0")}-${(Date.now() & 0xffffffff).toString(16).padStart(8, "0")}`;
+  set(state, "client_id", id);
+  return id;
+}
+
+/** 供排障/测试：整目录拆除（卸载由宿主做，这里只服务自检）。 */
+export function reset_for_test() {
+  try { rmSync(join(dataDir, "wx-state.json"), { force: true }); } catch { /* 尽力而为 */ }
+}
+
+// ══════════════════════════════════════════════════════════════════
+// 运行态机（remote_control/state.rs 移植）：每个状态只有一个真身，
+// 别的模块只读、只走这里的方法改。
+
+/** 状态盘 mtime（ms）；文件不存在 = null（每拍重试探）。 */
+function default_stat() {
+  try {
+    return statSync(state_path()).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/** 启动失败的重试间隔：开机那次若撞上「轮询锁被另一个实例占着 / token 还没
+ * 写进盘」，不该整个进程生命周期都不再试。 */
+export const SERVICE_RETRY_MS = 30_000;
+
+/** 渠道生命周期。**句柄就在 On 里**——「在跑」= 句柄在，没有第二个 bool
+ * 可以撒谎。变体：pending / on / stopped / failed。 */
+export class Service {
+  constructor() {
+    this.variant = "pending";
+    this.transport = null; // On：渠道句柄
+    this.token = null; // On：句柄实际持有的 token（换绑检测唯一比对源）
+    this.failed_at = 0; // Failed：失败时刻（ms）
+    this.err_msg = null; // Failed：失败文案（状态卡④；成功即清）
+  }
+
+  is_running() {
+    return this.variant === "on";
+  }
+
+  transport_handle() {
+    return this.variant === "on" ? this.transport : null;
+  }
+
+  /** 运行中渠道手里那份 token（换绑检测的唯一比对源）。 */
+  started_token() {
+    return this.variant === "on" ? this.token : null;
+  }
+
+  /** 本拍该不该起渠道（唯一的「起不起」判据）。 */
+  wants_start(now = Date.now()) {
+    switch (this.variant) {
+      case "pending":
+        return true;
+      case "failed":
+        return now - this.failed_at >= SERVICE_RETRY_MS;
+      default: // on / stopped
+        return false;
+    }
+  }
+
+  /** 失败文案（状态卡④；成功即清）。 */
+  error() {
+    return this.variant === "failed" ? this.err_msg : null;
+  }
+
+  to_pending() {
+    this.variant = "pending";
+    this.transport = null;
+    this.token = null;
+  }
+
+  to_on(transport, token) {
+    this.variant = "on";
+    this.transport = transport;
+    this.token = token;
+    this.err_msg = null;
+  }
+
+  to_stopped() {
+    this.variant = "stopped";
+    this.transport = null;
+    this.token = null;
+  }
+
+  to_failed(at_ms, err) {
+    this.variant = "failed";
+    this.transport = null;
+    this.token = null;
+    this.failed_at = at_ms;
+    this.err_msg = err;
+  }
+}
+
+/** 链路健康度：只有「正常 / 服务端已作废本 bot 会话」两态。
+ * （长轮询的偶发报错只进 stderr，不是产品状态——2026-10-25 定。）
+ * Expired 粘性：置位后只能重新扫码解除（入口串接在重绑成功时清）。 */
+export class Health {
+  constructor() {
+    this.expired_flag = false;
+  }
+
+  expired() {
+    return this.expired_flag;
+  }
+
+  set_expired() {
+    this.expired_flag = true;
+  }
+
+  clear() {
+    this.expired_flag = false;
+  }
+}
+
+/** 微信线指针：`key` = 本进程会话身份（pi getSessionId，门控比对源）；
+ * `name` = 会话名。绑定指针的真身在镜像 `session_id` 键（壳侧单写入口），
+ * 这里只是进程内缓存。 */
+export class WxLine {
+  constructor() {
+    this.key = null;
+    this.name = null;
+  }
+
+  is(key) {
+    return this.key === key;
+  }
+}
+
+/** `wx-state.json` 的进程内镜像（门控字段 + mtime）。泵一拍 refresh 一次，
+ * 壳/门控只读镜像——门控路径不再额外碰盘。 */
+export class Snapshot {
+ #stat;
+ #load;
+ #mtime = null;
+
+  constructor(deps = {}) {
+    this.token = undefined;
+    this.session_id = undefined; // 壳侧键：被绑定的会话 key
+    this.bound_current = undefined; // ext 门控结果："1" = 本会话是被绑定会话
+    this.enabled = undefined; // 壳侧键："0" = 服务关
+    this.chat_id = undefined;
+    this.user_id = undefined;
+    this.#stat = deps.stat ?? default_stat;
+    this.#load = deps.load ?? load;
+  }
+
+  /** 盘 → 镜像。`force` = 不看 mtime（刚写完盘时用）。
+   * 返回 true = 内容可能变了。 */
+  refresh(force = false) {
+    const mtime = this.#stat();
+    if (!force && mtime !== null && mtime === this.#mtime) return false;
+    this.#mtime = mtime;
+    const st = this.#load();
+ // 与 transport require_token 同口径（空串 = 没 token）
+    this.token = get_str(st, "bot_token");
+    this.session_id = get_str(st, "session_id");
+    this.bound_current = get_str(st, "bound_current");
+    this.enabled = get_str(st, "enabled");
+    this.chat_id = get_str(st, "chat_id");
+    this.user_id = get_str(st, "user_id");
+    return true;
+  }
+
+  has_token() {
+    return this.token !== undefined;
+  }
+
+  /** 对端投递路由就绪（`chat_id` / `user_id` 随首条入站消息回写）。 */
+  routed() {
+    return this.chat_id !== undefined || this.user_id !== undefined;
+  }
+}

package/pi/state.test.mjs

@@ -0,0 +1,138 @@
+// state 运行态机单测 —— remote_control/state.rs + mod.rs 服务状态机测试镜像。
+// 跑法：node --test packages/wechat-bridge/pi/state.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { Service, Health, WxLine, Snapshot, SERVICE_RETRY_MS } from "./state.mjs";
+
+// ---------------------------------------------------------------- Service 四变体
+
+test("service_pending_wants_start", () => {
+  const s = new Service();
+  assert.equal(s.variant, "pending", "新实例待启动（泵一拍按开关决定起不起）");
+  assert.equal(s.is_running(), false);
+  assert.equal(s.wants_start(), true);
+  assert.equal(s.transport_handle(), null);
+  assert.equal(s.started_token(), null);
+  assert.equal(s.error(), null);
+});
+
+test("service_on_holds_handle_and_token", () => {
+  const s = new Service();
+  const tr = { send() {} };
+  s.to_on(tr, "TOKEN");
+  assert.equal(s.is_running(), true);
+  assert.equal(s.transport_handle(), tr, "句柄就在 On 里，没有第二个 bool");
+  assert.equal(s.started_token(), "TOKEN");
+  assert.equal(s.wants_start(), false, "在跑不该再起");
+  assert.equal(s.error(), null, "成功即清");
+});
+
+test("service_failed_retries_after_cooldown", () => {
+ // mod.rs failed_service_retries_after_cooldown 镜像：开机那次撞上
+ // 「锁被占 / token 没写」不该整个进程都不再试。
+  const s = new Service();
+  const now = 1_000_000;
+  s.to_failed(now, "x");
+  assert.equal(s.is_running(), false);
+  assert.equal(s.wants_start(now), false, "刚失败不立刻重试");
+  assert.equal(s.wants_start(now + SERVICE_RETRY_MS), true, "冷却到点允许重试");
+  assert.equal(s.wants_start(now + 31_000), true);
+  assert.equal(s.error(), "x", "失败文案供状态卡④");
+});
+
+test("service_stopped_waits_for_explicit_start", () => {
+  const s = new Service();
+  s.to_stopped();
+  assert.equal(s.is_running(), false);
+  assert.equal(s.wants_start(), false, "用户显式关停后本进程不再自动拉起");
+});
+
+// ---------------------------------------------------------------- Health 粘性
+
+test("health_expired_is_sticky_until_cleared", () => {
+  const h = new Health();
+  assert.equal(h.expired(), false);
+  h.set_expired();
+  assert.equal(h.expired(), true, "-14 洗完旧游标仍是它 = 服务端作废，粘住");
+  h.clear(); // 只在重绑成功时清（入口串接职责）
+  assert.equal(h.expired(), false);
+});
+
+// ---------------------------------------------------------------- WxLine
+
+test("wx_line_pointer", () => {
+  const line = new WxLine();
+  assert.equal(line.key, null);
+  assert.equal(line.is("draft-1"), false);
+  line.key = "draft-1";
+  line.name = "pf-wxbot-1760000000000000";
+  assert.equal(line.is("draft-1"), true);
+  assert.equal(line.is("draft-2"), false);
+});
+
+// ---------------------------------------------------------------- Snapshot 七字段 + mtime
+
+function mk_snapshot(initial, { mtime = 100, changed = null } = {}) {
+  let current = initial;
+  let currentMtime = mtime;
+  return {
+    snap: new Snapshot({
+      stat: () => currentMtime,
+      load: () => current,
+    }),
+    /** 模拟外部（transport ack/壳）写盘。 */
+    write(next, nextMtime) {
+      current = next;
+      currentMtime = nextMtime ?? mtime + 1;
+    },
+  };
+}
+
+test("snapshot_reads_fields_with_empty_folding", () => {
+  const { snap } = mk_snapshot({
+    bot_token: "T",
+    session_id: "sA",
+    enabled: "0",
+    chat_id: "room@chat",
+    user_id: "",
+  });
+  assert.equal(snap.refresh(true), true, "force 首刷");
+  assert.equal(snap.has_token(), true);
+  assert.equal(snap.session_id, "sA", "绑定指针（壳侧键）");
+  assert.equal(snap.enabled, "0", "开关（壳侧键）");
+  assert.equal(snap.chat_id, "room@chat");
+  assert.equal(snap.user_id, undefined, "空串视同缺失（get_str 口径）");
+  assert.equal(snap.routed(), true);
+});
+
+test("snapshot_empty_state", () => {
+  const { snap } = mk_snapshot({});
+  snap.refresh(true);
+  assert.equal(snap.has_token(), false);
+  assert.equal(snap.token, undefined);
+  assert.equal(snap.session_id, undefined, "未绑定");
+  assert.equal(snap.enabled, undefined, "开关缺省 = on");
+  assert.equal(snap.routed(), false, "chat_id/user_id 都缺 = 路由未就绪");
+});
+
+test("snapshot_mtime_gates_reread", () => {
+  const w = mk_snapshot({ bot_token: "T" }, { mtime: 100 });
+  assert.equal(w.snap.refresh(true), true);
+ // mtime 没变：不重读，返回 false（渲染不再碰盘的关键）
+  w.write({ bot_token: "CHANGED" }, 100); // 内容变了但 mtime 没动（异常路径）
+  assert.equal(w.snap.refresh(false), false);
+  assert.equal(w.snap.token, "T", "mtime 未变不重读");
+ // mtime 变了：重读并返回 true
+  w.write({ bot_token: "NEW" }, 200);
+  assert.equal(w.snap.refresh(false), true);
+  assert.equal(w.snap.token, "NEW");
+});
+
+test("snapshot_missing_file_retries_every_beat", () => {
+ // mtime = null（文件不存在）→ 永远重试（等首个入站回写路由字段）
+  const snap = new Snapshot({ stat: () => null, load: () => ({}) });
+  assert.equal(snap.refresh(false), true, "null 不命中缓存短路");
+  assert.equal(snap.refresh(false), true);
+});