cortico-world-wechat 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件的 `## <版本号>` 段落会显示在扩展市场的发布时间线上（索引仓的 Action 按同样规则切段）。
 
+## 0.1.2
+
+- 文档重写：安装给出三条路径（npm / 离线包 / 源码，按推荐顺序）、配置项逐条说明、
+  "没反应时按顺序查"的排查表、以及"消息正文会进入模型上下文"的明确提示。
+- 无功能变化。
+## 0.1.1
+
+- **打包内容调整**（无功能变化）：
+  - 把打包脚本移出 npm 包（仓库里保留在 `scripts/`）——它是构建用的，最终用户用不到；
+  - npm 包内补上 `test/`，方便使用者自行验证（尤其是微信升级后跑 `test/decrypt-verify.mjs`，
+    它用 `PRAGMA integrity_check` 判断页布局是否仍被正确解密）。
+
 ## 0.1.0
 
 首个公开版本。
@@ -14,3 +26,4 @@
 - **取密钥**：微信的库密钥只存在于其进程内存中，由 `tools/fetch-keys.py` 按需取出
   （短命进程，取完即退；失效时自动重取）。这是本项目唯一用到 Python 的地方。
 - 实测：真机库解密 `PRAGMA integrity_check = ok`；测试 26 例（7 监听逻辑 + 6 文本格式化 + 13 World 行为）。
+

package/README.md

@@ -0,0 +1,244 @@
+# wechat-notifier · 微信消息桌宠提示器
+
+把 Windows 微信新消息播报给桌宠（Coopanion / 大肥鱼）：她看到后用一句话汇报，并能用 TTS 念出来。
+
+> **它是一个 Coopanion World 扩展。** 监听、解密、轮询、限流、推送**全部在扩展里**（Node），
+> 随 Coopanion 一起启动 —— 没有独立常驻进程、没有 exe、没有开机自启任务。
+>
+> 唯一的例外是**取密钥**：微信的库密钥只存在于微信进程内存中，需要一个短命脚本把它取出来
+> （几秒完成、取完即退，失效时由扩展自动重拉）。这是本项目唯一用到 Python 的地方，
+> 取舍理由见下文「为什么取密钥保留 Python」。
+
+| | |
+|---|---|
+| **npm 包** | [`cortico-world-wechat`](https://www.npmjs.com/package/cortico-world-wechat) |
+| **源码仓** | https://gitee.com/ydcy_studio/wechat-notifier |
+| **平台** | Windows x64 ｜ 微信 4.x（需已登录） ｜ Coopanion 0.2.0+ |
+
+---
+
+## 快速开始（三步）
+
+```powershell
+# ① 装扩展：在 Coopanion 的扩展页搜 cortico-world-wechat 点安装
+#    （或命令行：进 Coopanion 的 data\extensions 目录执行下面这行）
+pnpm add cortico-world-wechat
+
+# ② 准备密钥（取密钥需要 Python；扩展启动时会自动拉起它，也可手动跑）
+#    见下方「准备密钥」
+
+# ③ 重启 Coopanion（扩展在启动时装载，不热更）
+```
+
+装好并重启后，随便发一条微信消息，桌宠应当冒泡汇报。
+
+---
+
+## 架构
+
+```text
+微信 4.x ──加密库──▶ Coopanion World 扩展（主体）
+（已登录）             ├─ 解密：纯 node:crypto（AES-256-CBC raw CBC）+ WAL 增量合并
+                       ├─ 轮询：sort_seq 水位（落盘，重启不重复）
+                       ├─ 规范化 + 限流（全局间隔 / 会话冷却 / 静音时段）
+                       └─ host.pushEvent ──▶ 桌宠（气泡 / TTS）
+                    ▲
+                    └── keys.json ◀── tools/fetch-keys.py（短命，仅取密钥）
+```
+
+| 部件 | 位置 | 说明 |
+|---|---|---|
+| **World 扩展（主体）** | `cortico-world-wechat/src/` | 监听、解密、轮询、推送全在这里 |
+| 取密钥工具（例外） | `cortico-world-wechat/tools/fetch-keys.py` | 密钥缺失/失效时被自动拉起，几秒后退出 |
+| 密钥与状态 | `%LOCALAPPDATA%\WeChatNotifier\`（`keys.json`、`watermarks.json`、`cache\`） | 含密钥，**切勿入库** |
+
+### 为什么取密钥保留 Python
+
+密钥只在微信进程内存里，"把它找出来"需要**版本相关的结构锚点**
+（`com.Tencent.WCDB.Config.Cipher` 标记 + 多层指针 + XOR 解码）。上游 `wechatauto-replica`
+已把这套做得很稳，而我们在 Node 里试过的替代方案（宽扫内存候选 + 页 HMAC 验真）
+**性能不可接受**（约 4000 万次 HMAC，实测 10 分钟跑不完）。
+
+所以取舍是：**取密钥复用已验证实现（短命、按需），其余全部在扩展里**。
+如果将来要彻底去掉 Python，正确路径是复刻上游那套"标记 + 指针链"（只扫 Weixin.dll，秒级），
+而不是宽扫 —— 这条路记录在 `设计文档.md` 里备用。
+
+---
+
+## 安装（三种方式，按推荐顺序）
+
+### 方式一：从 npm 安装（推荐）
+
+Coopanion 的扩展页会用 `keywords:cortico-world` 搜 npm。搜 **cortico-world-wechat** 点安装即可；
+它内部执行 pnpm，依赖（含原生 sqlite 绑定）会自动装好。
+
+命令行等价做法：
+
+```powershell
+cd 'D:\MyApp\Coopanion\data\extensions'
+pnpm add cortico-world-wechat
+```
+
+### 方式二：离线发布包（不想装 npm / 内网）
+
+下载 `wechat-notifier-v<版本>-win-x64.zip`，解压后：
+
+```powershell
+pwsh -File install.ps1                       # 默认装到 D:\MyApp\Coopanion
+pwsh -File install.ps1 -CoopanionRoot 'C:\Apps\Coopanion'   # 自定义安装目录
+pwsh -File install.ps1 -KeysOnly             # 只看"怎么准备密钥"
+```
+
+它会：复制扩展到 `extensions/node_modules/`、复制**原生 sqlite 绑定**（离线包已内置，
+只保留 win32-x64）、把 `worlds.wechat-notifier` 写进配置（改前自动备份）。
+
+### 方式三：从源码（开发者）
+
+```powershell
+$src = '<本仓库>\cortico-world-wechat'
+$dst = 'D:\MyApp\Coopanion\data\extensions\node_modules\cortico-world-wechat'
+robocopy $src $dst /E /XD node_modules
+# 依赖装到 Coopanion 的 extensions 下（不要装进扩展目录，避免嵌套）
+cd 'D:\MyApp\Coopanion\data\extensions'
+pnpm add better-sqlite3-multiple-ciphers
+```
+
+---
+
+## 配置
+
+`D:\MyApp\Coopanion\data\home\companion\config.json` 的 `worlds.wechat-notifier`：
+
+```json
+"wechat-notifier": {
+  "mode": "in-process",
+  "enabled": true,
+  "notifySelf": false,
+  "notifyGroup": true,
+  "autoFetchKeys": true,
+  "pollIntervalSec": 1,
+  "previewMaxChars": 60,
+  "throttle": { "global_min_gap_sec": 20, "per_chat_cooldown_sec": 120 },
+  "quietHours": { "enabled": true, "start": "23:30", "end": "08:00" }
+}
+```
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `mode` | `in-process` | `in-process`＝扩展自己读库（推荐）；`bridge`＝收外部进程推来的事件（兼容旧架构） |
+| `notifySelf` | `false` | 是否提醒"自己发的消息" |
+| `notifyGroup` | `true` | 是否提醒群消息 |
+| `autoFetchKeys` | `true` | 密钥缺失/失效时自动拉起取密钥工具 |
+| `pollIntervalSec` | `1` | 轮询间隔（秒） |
+| `previewMaxChars` | `60` | 正文截断长度（隐私 + 上下文成本） |
+| `throttle.*` | 20 / 120 | 全局最短间隔、同会话冷却（秒） |
+| `quietHours.*` | `23:30–08:00` | 静音时段；**被吞掉即丢弃、不补发** |
+
+---
+
+## 准备密钥
+
+密钥只在微信进程内存里，需要一个 64 位 Python 环境来取（**建议装在 `%LOCALAPPDATA%` 下**）。
+
+```powershell
+# 建环境（一次性）
+python -m venv "$env:LOCALAPPDATA\wechat-notifier-venv"
+$py = "$env:LOCALAPPDATA\wechat-notifier-venv\Scripts\python.exe"
+& $py -m pip install -U pip
+& $py -m pip install "wechatauto-replica>=1.2.6.1" `
+    -i https://mirrors.cloud.tencent.com/pypi/simple --no-build-isolation
+
+# 取密钥（微信需已登录）
+& $py "<扩展目录>\tools\fetch-keys.py"
+# 产出 %LOCALAPPDATA%\WeChatNotifier\keys.json（24 个库密钥）
+```
+
+**一般不用手动跑**：扩展启动时发现没有 `keys.json`，会自己拉起这个脚本（实测冷启动 4 秒完成）。
+微信重新登录 / 升级导致密钥变化时会自动重取。
+
+---
+
+## 确认在工作
+
+日志在 `D:\MyApp\Coopanion\data\logs\core.log`，搜 `wechat-notifier`：
+
+```
+[wechat-notifier] 读库模式：db_storage=...\xwechat_files\<账号>\db_storage
+[wechat-notifier] 消息分片 4 个
+[wechat-notifier] [listener] 联系人 8269 条
+[wechat-notifier] [listener] 放行 chat=文件传输助手 sender=胡闹 preview=测试3
+[wechat-notifier] 收到 文件传输助手 的消息 → 推给她：【微信】…
+```
+
+> 状态端点（`http://127.0.0.1:19391/wechat/status`）**只在 `mode: "bridge"` 下存在**
+> （那种模式才起 WS/HTTP 服务）。`in-process` 模式靠上面的日志判断。
+
+### 没反应时按顺序查
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 日志里 `keysError` 非空 | 取不到密钥 | 确认微信**已登录**；把 Python 换成 64 位；杀软放行读内存 |
+| 日志停在"密钥缓存不存在" | 取密钥工具起不来 | 检查 Python 环境是否存在、`wechatauto-replica` 是否装好 |
+| 有"放行"但桌宠不吭声 | 问题在桌宠侧 | 看 core.log 有无 `收到 … 推给她`；有则说明已推，检查她的 persona / TTS 开关 |
+| 完全没日志 | 扩展没装载 | 扩展在**启动时**装载：改完配置或代码必须**重启 Coopanion** |
+| 几分钟没有任何"放行" | 可能确实没人发消息 | 用手机发一条；记得看是否被限流吞掉（日志会写 `限流吞掉 … global_gap`） |
+
+---
+
+## 测试
+
+```bash
+cd cortico-world-wechat
+
+# 纯逻辑（26 例：正文规范化、限流、类型映射、WS 服务、状态端点、事件推送）
+node test/listener.test.mjs
+node test/format.test.mjs
+node test/world.test.mjs
+
+# 集成（需要真机微信库 + keys.json）：验证解密正确性
+# 微信升级后先跑这个 —— integrity_check = ok 才说明页布局仍被正确解密
+node test/decrypt-verify.mjs 'contact\contact.db'
+```
+
+> 在受限沙箱里不要用 `node --test` / `npm test`（可能 `spawn EPERM`），**逐个文件直跑**。
+
+---
+
+## 发布与分发
+
+- npm：`npm publish`（版本号改 `package.json` 并在 `CHANGELOG.md` 加 `## <版本>` 段）
+- 离线包：`pwsh -File release/build-package.ps1 -Version <版本>`
+- 官方扩展市场：机制与清单见 [docs/发布到官方市场.md](docs/发布到官方市场.md)
+
+---
+
+## 已知限制
+
+1. 仅 Windows x64；微信必须**已登录**（密钥在其进程内存里）。
+2. 取密钥需要读微信进程内存，**可能被杀软拦截**（当前未遇）。
+3. 依赖上游 [`wechatauto-replica`](https://pypi.org/project/wechatauto-replica/) 取密钥；
+   微信大版本升级后若取不到密钥，先跑它的体检命令排查。
+4. 只读微信库：不回消息、不写库、不驱动微信窗口。
+5. 消息频率高，**限流是必需的**（每次推送都会真实唤醒桌宠、走一次 LLM 调用）。
+6. **消息正文会进入桌宠的模型上下文**（随 `pushEvent` 交给她处理）——扩展在市场里已声明
+   `sensitive-data` 警示标签，装之前请知悉。
+7. 主要在**一台机器、一个微信版本（4.1.15.13）、单账号**上验证过；市场标签为 `experimental`。
+
+---
+
+## 实现要点（踩过的坑，改代码前先读）
+
+| 坑 | 现象 | 正解 |
+|---|---|---|
+| **水位必须用 `sort_seq`** | 用 `local_id` 会漏消息：`local_id` 在每个会话表内各自计数，跨 `Msg_*` 表不单调（实测一条新消息 `local_id=2392` 小于"分片最大 2564"被永久跳过） | 水位存最大 `sort_seq`（毫秒） |
+| **IV 在页内 `[4016:4032]`** | 当成文件头盐或页尾 IV 会解出乱码 | 保留区前 16 字节 |
+| **第 2 页起密文从 offset 0 开始** | 第 1 页才是 `[16:4016)`；一律从 16 开始会在第 2 页起解错 | 按页号分支 |
+| **必须 `setAutoPadding(false)`** | Node 默认校验 PKCS#7，SQLCipher 页是 raw CBC → `bad decrypt` | 关闭自动填充 |
+| **WAL 帧只合并同 salt 的** | checkpoint 会重置 WAL，旧世代帧合并会用过期页覆盖新数据 | 比对 WAL 头 salt |
+| **`real_sender_id` 要按所在分片解析** | 用别的表解析会把发送者显示成无关的人（上游 issue #34） | 查该分片自己的 `Name2Id` |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,51 +1,52 @@
-{
-  "name": "cortico-world-wechat",
-  "version": "0.1.0",
-  "description": "把 Windows 微信新消息播报给桌宠：扩展自己解密并轮询微信本地库，把新消息推进桌宠的事件流，由桌宠决定怎么汇报。",
-  "license": "MIT",
-  "type": "module",
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src",
-    "tools",
-    "describe.json",
-    "CHANGELOG.md",
-    "README.md"
-  ],
-  "os": [
-    "win32"
-  ],
-  "engines": {
-    "node": "^22.19.0 || >=24.0.0"
-  },
-  "dependencies": {
-    "better-sqlite3-multiple-ciphers": "^13.0.3",
-    "ws": "^8.21.3"
-  },
-  "keywords": [
-    "cortico-world",
-    "cortico",
-    "wechat",
-    "weixin",
-    "notifier"
-  ],
-  "cortico": {
-    "displayName": "微信消息提示",
-    "kind": "world",
-    "api": 6,
-    "describe": "describe.json",
-    "tags": [
-      "im",
-      "external-setup",
-      "experimental",
-      "sensitive-data"
-    ]
-  },
-  "scripts": {
-    "test": "node --test test/format.test.mjs test/world.test.mjs"
-  }
-}
+{
+  "name": "cortico-world-wechat",
+  "version": "0.1.2",
+  "description": "把 Windows 微信新消息播报给桌宠：扩展自己解密并轮询微信本地库，把新消息推进桌宠的事件流，由桌宠决定怎么汇报。",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "tools",
+    "test",
+    "describe.json",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3-multiple-ciphers": "^13.0.3",
+    "ws": "^8.21.3"
+  },
+  "keywords": [
+    "cortico-world",
+    "cortico",
+    "wechat",
+    "weixin",
+    "notifier"
+  ],
+  "cortico": {
+    "displayName": "微信消息提示",
+    "kind": "world",
+    "api": 6,
+    "describe": "describe.json",
+    "tags": [
+      "im",
+      "external-setup",
+      "experimental",
+      "sensitive-data"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/format.test.mjs test/world.test.mjs"
+  }
+}

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);