cortico-world-wechat 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 本文件的 `## <版本号>` 段落会显示在扩展市场的发布时间线上（索引仓的 Action 按同样规则切段）。
 
+## 0.1.1
+
+- **打包内容调整**（无功能变化）：
+  - 把打包脚本移出 npm 包（仓库里保留在 `scripts/`）——它是构建用的，最终用户用不到；
+  - npm 包内补上 `test/`，方便使用者自行验证（尤其是微信升级后跑 `test/decrypt-verify.mjs`，
+    它用 `PRAGMA integrity_check` 判断页布局是否仍被正确解密）。
+
 ## 0.1.0
 
 首个公开版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-wechat",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "把 Windows 微信新消息播报给桌宠：扩展自己解密并轮询微信本地库，把新消息推进桌宠的事件流，由桌宠决定怎么汇报。",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
   "files": [
     "src",
     "tools",
+    "test",
     "describe.json",
     "CHANGELOG.md",
     "README.md"

package/test/decrypt-verify.mjs

@@ -0,0 +1,56 @@
+/**
+ * 解密验证（集成测试，需要真机微信库与密钥）。
+ *
+ * 为什么保留：它验证的是"Node 能否读懂微信加密库"这条**地基**，
+ * 一旦微信升级导致页布局变化，这个测试会最先报红。
+ *
+ * 前置：先用 tools/fetch-keys.py 生成 keys.json（含各库密钥与 db_storage 路径）。
+ * 用法：node test/decrypt-verify.mjs [库相对名，默认 contact\\contact.db]
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { KeyOracle } from '../src/keys.js';
+import { WeChatReader } from '../src/wechat-db.js';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, '..');
+
+const rel = process.argv[2] ?? 'contact\\contact.db';
+const keysPath = process.argv[3] ?? join(process.env.LOCALAPPDATA ?? '.', 'WeChatNotifier', 'keys.json');
+
+const oracle = new KeyOracle({ keysPath, logger: { info: () => {}, warn: (m) => console.error(m) } });
+const payload = oracle.loadCache();
+if (!payload) {
+  console.error(`没有 ${keysPath}，先运行: python tools/fetch-keys.py`);
+  process.exit(2);
+}
+
+const reader = new WeChatReader({
+  dbStorage: payload.db_storage,
+  keys: oracle.keys(),
+  cacheDir: join(dirname(keysPath), 'cache'),
+  logger: { info: () => {}, warn: (m) => console.error(m), debug: () => {} },
+});
+
+console.log(`库: ${rel}`);
+const started = Date.now();
+const path = reader.ensureDecrypted(rel);
+console.log(`  解密到 ${path}（用时 ${((Date.now() - started) / 1000).toFixed(2)}s）`);
+
+const Sqlite = require('better-sqlite3-multiple-ciphers');
+const db = new Sqlite(path, { readonly: true });
+const integrity = db.pragma('integrity_check', { simple: true });
+const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length;
+db.close();
+
+console.log(`  integrity_check = ${integrity}`);
+console.log(`  表数量 = ${tables}`);
+if (integrity !== 'ok') {
+  console.error('❌ 解密结果不完整：页布局可能已随微信版本变化');
+  process.exit(1);
+}
+console.log('✅ 解密正确');

package/test/format.test.mjs

@@ -0,0 +1,55 @@
+/**
+ * format.js 单测：把"她会听到什么"钉死。
+ * 运行：node test/format.test.mjs（DSH 沙箱内不要用 node --test，见 README）
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { frameToText } from '../src/format.js';
+
+test('单聊消息：说清谁说了什么，并带动作要求', () => {
+  const text = frameToText({
+    t: 'notice', kind: 'message', chat: '张三', sender: '张三',
+    is_group: false, preview: '下午三点开会',
+  });
+  assert.equal(text, '【微信】张三发来消息：下午三点开会。跟胡闹说一声。');
+});
+
+test('群聊消息：带群名与发言人', () => {
+  const text = frameToText({
+    t: 'notice', kind: 'message', chat: '云南项目部', sender: '李四',
+    is_group: true, preview: '明天上线',
+  });
+  assert.equal(text, '【微信】群「云南项目部」里的 李四发来消息：明天上线。跟胡闹说一声。');
+});
+
+test('自己发的消息不催办', () => {
+  const text = frameToText({
+    t: 'notice', kind: 'message', chat: '文件传输助手', sender: '我',
+    is_group: false, preview: '测试',
+  });
+  assert.equal(text, '【微信】你在「文件传输助手」发了一条消息。');
+  assert.ok(!text.includes('胡闹说一声'), '自己发的消息不该催她汇报');
+});
+
+test('空正文给占位，不出现空串', () => {
+  const text = frameToText({
+    t: 'notice', kind: 'message', chat: '张三', sender: '张三', is_group: false, preview: '',
+  });
+  assert.ok(text.includes('没有正文'), `空正文应有占位说明，实际: ${text}`);
+});
+
+test('控制帧不产生正文', () => {
+  assert.equal(frameToText({ t: 'hello', role: 'wechat-listener' }), null);
+  assert.equal(frameToText(null), null);
+  assert.equal(frameToText({ t: 'notice', kind: 'other' }), null);
+});
+
+test('超长正文被截断', () => {
+  const text = frameToText({
+    t: 'notice', kind: 'message', chat: '张三', sender: '张三', is_group: false,
+    preview: '长'.repeat(500),
+  });
+  assert.ok(text.length < 220, `应被截断，实际长度 ${text.length}`);
+  assert.ok(text.includes('…'));
+});

package/test/listener.test.mjs

@@ -0,0 +1,60 @@
+/**
+ * 纯逻辑单测：正文规范化、限流、类型映射。
+ * 运行：node test/listener.test.mjs（DSH 沙箱内不要用 node --test）
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { Throttle, previewText, typeName } from '../src/wechat-listener.js';
+
+test('类型映射：码 → 展示名', () => {
+  assert.equal(typeName(1), '文本');
+  assert.equal(typeName(3), '[图片]');
+  assert.equal(typeName(34), '[语音]');
+  assert.equal(typeName(49), '[文件/链接/卡片]');
+  assert.equal(typeName(8594229559345), '[文件/链接/卡片]'); // 复合类型的低 32 位分解
+});
+
+test('正文：XML 类只给占位符，绝不把 XML 塞进上下文', () => {
+  const xml = '<msg><img aeskey="deadbeef" md5="abc" cdnbigimgurl="305f0201"/></msg>';
+  const result = previewText(3, xml, 60);
+  assert.equal(result, '[图片]');
+  assert.ok(!result.includes('aeskey'), '不能泄露 cdn 地址与密钥');
+});
+
+test('正文：普通文本单行化并截断', () => {
+  assert.equal(previewText(1, '第一行\n第二行', 60), '第一行 第二行');
+  assert.equal(previewText(1, '长'.repeat(100), 10), `${'长'.repeat(10)}…`);
+});
+
+test('正文：空内容给类型占位，不出现空串', () => {
+  assert.equal(previewText(1, '', 60), '文本');
+  assert.equal(previewText(3, '', 60), '[图片]');
+});
+
+test('正文：未识别的 XML 容器不原样透出', () => {
+  const result = previewText(99, '<sysmsg type="revokemsg"><revoke/></sysmsg>', 60);
+  assert.ok(!result.includes('<'), `不应透出 XML：${result}`);
+});
+
+test('限流：正常放行 / 全局间隔 / 同会话冷却', () => {
+  const throttle = new Throttle({ throttle: { global_min_gap_sec: 20, per_chat_cooldown_sec: 120 } });
+  assert.equal(throttle.allow('chat_a', 1_000_000).allowed, true);
+  assert.equal(throttle.allow('chat_b', 1_000_000 + 5_000).reason, 'global_gap');
+  const t2 = new Throttle({ throttle: { global_min_gap_sec: 0, per_chat_cooldown_sec: 120 } });
+  assert.equal(t2.allow('chat_a', 1_000_000).allowed, true);
+  assert.equal(t2.allow('chat_a', 1_000_000 + 60_000).reason, 'per_chat_cooldown');
+  assert.equal(t2.allow('chat_a', 1_000_000 + 121_000).allowed, true);
+});
+
+test('限流：静音时段（含跨零点）一条不放行', () => {
+  const throttle = new Throttle({ quiet_hours: { enabled: true, start: '23:30', end: '08:00' } });
+  const at = (h, m) => new Date(2026, 0, 1, h, m);
+  assert.equal(throttle.inQuietHours(at(23, 45)), true);
+  assert.equal(throttle.inQuietHours(at(7, 59)), true);
+  assert.equal(throttle.inQuietHours(at(12, 0)), false);
+  // 把"当前时间"注入进去，避免测试结果依赖跑测试的真实时刻
+  assert.equal(throttle.allow('chat_a', 1_000_000, at(23, 45)).reason, 'quiet_hours');
+  assert.equal(throttle.allow('chat_a', 1_000_000, at(7, 59)).reason, 'quiet_hours');
+  assert.equal(throttle.allow('chat_a', 1_000_000, at(12, 0)).allowed, true);
+});

package/test/world.test.mjs

@@ -0,0 +1,194 @@
+/**
+ * world.js 单测：真起 WS 服务 + 真 ws 客户端，验证契约行为。
+ * 运行：node test/world.test.mjs（DSH 沙箱内不要用 node --test）
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { WECHAT_ID, WECHAT_WORLD, WechatWorld, wechatDefaults } from '../src/index.js';
+import { WebSocket } from 'ws';
+
+const loadWs = () => import('ws');
+
+/** 起一个 World 实例并等它开始监听。
+ *
+ * 显式指定 mode='bridge'：本文件测的是"外部进程推事件"那条腿（WS 服务 + 状态端点）。
+ * in-process 读库模式需要真实微信库与密钥，属于集成测试，不放在这里（见 test-inprocess 系列）。
+ */
+async function startWorld(config = {}) {
+  const port = 19400 + Math.floor(Math.random() * 200);
+  const world = new WechatWorld(
+    WECHAT_ID,
+    { mode: 'bridge', url: `ws://127.0.0.1:${port}/wechat/pet`, ...config },
+    loadWs,
+  );
+  const pushes = [];
+  const logs = [];
+  const host = {
+    pushEvent: async (event, opts) => {
+      pushes.push({ event, opts });
+      return event;
+    },
+    log: { info: (text) => logs.push(text), warn: () => {}, error: () => {}, debug: () => {} },
+  };
+  await world.start(host);
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  return { world, pushes, logs, port };
+}
+
+/** 连上去并等 hello 帧。 */
+function connect(port, onFrame) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(`ws://127.0.0.1:${port}/wechat/pet`);
+    socket.on('message', (raw) => onFrame?.(JSON.parse(raw.toString())));
+    socket.on('open', () => resolve(socket));
+    socket.on('error', reject);
+  });
+}
+
+test('声明的事件类型必须与运行时推送的类型一致（否则框架会警告）', () => {
+  // 站过一次坑：describe.events 写了 'wechat-notice'，而 pushEvent 用的是
+  // 'wechat-notifier.notice' → Core 日志出现 "事件 type 不在 describe.events 里"。
+  assert.equal(WECHAT_WORLD.describe.events[0].type, `${WECHAT_ID}.notice`);
+});
+
+test('状态端点：GET /wechat/status 返回 JSON，未知路径 404', async () => {
+  const { world, port } = await startWorld();
+  const status = await fetch(`http://127.0.0.1:${port}/wechat/status`).then((r) => r.json());
+  assert.equal(status.ok, true);
+  assert.equal(status.world, WECHAT_ID);
+  assert.equal(status.listening, true);
+  assert.equal(status.clients, 0);
+  assert.match(status.statusUrl, /\/wechat\/status$/);
+
+  const missing = await fetch(`http://127.0.0.1:${port}/nope`);
+  assert.equal(missing.status, 404);
+  await world.stop();
+});
+
+test('状态端点可关闭，且关闭后 WS 仍可用', async () => {
+  const { world, pushes, port } = await startWorld({ statusEnabled: false });
+  const status = await fetch(`http://127.0.0.1:${port}/wechat/status`);
+  assert.equal(status.status, 404, '关闭后状态端点应 404');
+  const socket = await connect(port);
+  socket.send(JSON.stringify({ t: 'notice', kind: 'message', chat: '张三', sender: '张三', is_group: false, preview: '仍然可用' }));
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  assert.equal(pushes.length, 1, '关闭状态端点不应影响事件推送');
+  socket.close();
+  await world.stop();
+});
+
+test('升级请求路径不匹配时被拒绝（不静默吞掉）', async () => {
+  const { world, port } = await startWorld();
+  const socket = new WebSocket(`ws://127.0.0.1:${port}/wrong/path`);
+  const rejected = await new Promise((resolve) => {
+    socket.on('open', () => resolve(false));
+    socket.on('error', () => resolve(true));
+  });
+  assert.equal(rejected, true, '错误路径的升级请求应被拒绝');
+  await world.stop();
+});
+
+test('默认配置符合预期（仅回环、默认关闭）', () => {
+  const defaults = wechatDefaults();
+  assert.equal(defaults.enabled, false);
+  assert.match(defaults.url, /^ws:\/\/127\.0\.0\.1:\d+\/wechat\/pet$/);
+  assert.equal(defaults.notifySelf, false);
+  assert.equal(defaults.notifyGroup, true);
+});
+
+test('envPromptVars 必须含"要主动汇报"的职责说明', () => {
+  const world = new WechatWorld(WECHAT_ID, {}, loadWs);
+  const vars = world.envPromptVars();
+  assert.ok(vars.wechat_notifier_url, '应注入地址变量');
+  assert.ok(vars.wechat_notifier_duty.includes('pet_say'), '缺了这句她会读完不吭声');
+  assert.ok(vars.wechat_notifier_duty.includes('不要只是记下来'));
+});
+
+test('客户端连上后收到 hello', async () => {
+  const { world, port } = await startWorld();
+  const frames = [];
+  const socket = await connect(port, (frame) => frames.push(frame));
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  assert.equal(frames[0].t, 'hello');
+  assert.equal(frames[0].world, WECHAT_ID);
+  socket.close();
+  await world.stop();
+});
+
+test('收到微信消息 -> 翻译并 pushEvent（带 trigger:flush 与 worldId.notice 类型）', async () => {
+  const { world, pushes, port } = await startWorld();
+  const socket = await connect(port);
+  socket.send(JSON.stringify({
+    t: 'notice', kind: 'message', chat: '张三', sender: '张三',
+    is_group: false, preview: '下午三点开会', ts: 1792137092000,
+  }));
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  assert.equal(pushes.length, 1);
+  assert.equal(pushes[0].event.type, `${WECHAT_ID}.notice`);
+  assert.equal(pushes[0].event.source, WECHAT_ID);
+  assert.match(pushes[0].event.text, /张三发来消息：下午三点开会/);
+  assert.equal(pushes[0].opts.trigger, 'flush');
+  socket.close();
+  await world.stop();
+});
+
+test('自己发的消息按配置不推送', async () => {
+  const { world, pushes, port } = await startWorld({ notifySelf: false });
+  const socket = await connect(port);
+  socket.send(JSON.stringify({
+    t: 'notice', kind: 'message', chat: '文件传输助手', sender: '我', is_group: false, preview: '测试',
+  }));
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  assert.equal(pushes.length, 0, '自己发的消息不该推给她');
+  socket.close();
+  await world.stop();
+});
+
+test('关闭群消息后群聊不推送、单聊仍推送', async () => {
+  const { world, pushes, port } = await startWorld({ notifyGroup: false });
+  const socket = await connect(port);
+  socket.send(JSON.stringify({ t: 'notice', kind: 'message', chat: '某群', sender: '李四', is_group: true, preview: '群里的话' }));
+  socket.send(JSON.stringify({ t: 'notice', kind: 'message', chat: '张三', sender: '张三', is_group: false, preview: '单聊的话' }));
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  assert.equal(pushes.length, 1);
+  assert.match(pushes[0].event.text, /单聊的话/);
+  socket.close();
+  await world.stop();
+});
+
+test('坏帧不崩、控制帧不误推', async () => {
+  const { world, pushes, port } = await startWorld();
+  const socket = await connect(port);
+  socket.send('这不是 JSON');
+  socket.send(JSON.stringify({ t: 'hello', role: 'wechat-listener' }));
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  assert.equal(pushes.length, 0);
+  socket.close();
+  await world.stop();
+});
+
+test('status() 反映连接数与收帧数', async () => {
+  const { world, port } = await startWorld();
+  const socket = await connect(port);
+  socket.send(JSON.stringify({ t: 'notice', kind: 'message', chat: '张三', sender: '张三', is_group: false, preview: 'x' }));
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  const status = world.status();
+  assert.equal(status.clients, 1);
+  assert.equal(status.received, 1);
+  assert.equal(status.listening, true);
+  socket.close();
+  await world.stop();
+  assert.equal(world.status().listening, false, 'stop 后不该还报在监听');
+});
+
+test('stop 之后端口释放（可以立刻重新起在同一端口）', async () => {
+  const { world, port } = await startWorld();
+  await world.stop();
+  const again = new WechatWorld(WECHAT_ID, { url: `ws://127.0.0.1:${port}/wechat/pet` }, loadWs);
+  const host = { pushEvent: async (e) => e, log: { info: () => {} } };
+  await again.start(host);
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.equal(again.status().listening, true);
+  await again.stop();
+});

package/tools/pack-native.mjs

@@ -1,79 +0,0 @@
-/**
- * 依赖自描述生成器：从扩展包里查找依赖的原生模块目录，打包进 native/。
- *
- * 为什么需要：扩展依赖 better-sqlite3-multiple-ciphers（原生 .node）。
- * 普通用户不会自己 npm install，缺了它扩展根本起不来。
- * 只保留 win32-x64 的 prebuild，并剔除 C 源码，避免包从 1.3MB 涨到 30MB+。
- *
- * 用法：node tools/pack-native.mjs <目标 native 目录> [查找根...]
- */
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-
-const MODULES = ['better-sqlite3-multiple-ciphers', 'node-addon-api'];
-/** 这些内容用户用不到、体积又大：C 源码、其它平台的加载器 */
-const DROP_DIRS = new Set(['deps', 'src']);
-const KEEP_PREBUILD = /^win32-x64\./;
-const DROP_PLATFORM_FILE = /^(darwin|linux|linuxmusl|win32-arm64)/;
-
-const target = process.argv[2];
-const searchRoots = process.argv.slice(3);
-if (!target || searchRoots.length === 0) {
-  console.error('用法: node tools/pack-native.mjs <目标 native 目录> <查找根...>');
-  process.exit(2);
-}
-
-function locate(moduleName) {
-  for (const root of searchRoots) {
-    const candidate = join(root, 'node_modules', moduleName);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-/** 先整拷，再删用不到的东西——比在拷贝时做过滤判断更不容易出错 */
-function slimModule(dir) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (DROP_DIRS.has(entry.name)) {
-        rmSync(full, { recursive: true, force: true });
-      } else if (entry.name === 'prebuilds') {
-        for (const file of readdirSync(full)) {
-          if (!KEEP_PREBUILD.test(file)) rmSync(join(full, file), { force: true });
-        }
-      } else {
-        slimModule(full);
-      }
-    } else if (entry.name === 'binding.gyp' || DROP_PLATFORM_FILE.test(entry.name)) {
-      rmSync(full, { force: true });
-    }
-  }
-}
-
-mkdirSync(target, { recursive: true });
-let packed = 0;
-for (const moduleName of MODULES) {
-  const source = locate(moduleName);
-  if (!source) {
-    console.warn(`  [!] 找不到 ${moduleName}`);
-    continue;
-  }
-  const dest = join(target, moduleName);
-  rmSync(dest, { recursive: true, force: true });
-  cpSync(source, dest, { recursive: true });
-  slimModule(dest);
-  const bytes = (function total(dir) {
-    let sum = 0;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) sum += total(full);
-      else if (entry.isFile()) sum += statSync(full).size;
-    }
-    return sum;
-  })(dest);
-  console.log(`  [OK] ${moduleName}  ${(bytes / 1024 / 1024).toFixed(2)} MB`);
-  packed += 1;
-}
-console.log(`已打包 ${packed}/${MODULES.length} -> ${target}`);
-process.exit(packed === MODULES.length ? 0 : 1);