cortico-world-wechat 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 本文件的 `## <版本号>` 段落会显示在扩展市场的发布时间线上（索引仓的 Action 按同样规则切段）。
 
+## 0.1.2
+
+- 文档重写：安装给出三条路径（npm / 离线包 / 源码，按推荐顺序）、配置项逐条说明、
+  "没反应时按顺序查"的排查表、以及"消息正文会进入模型上下文"的明确提示。
+- 无功能变化。
 ## 0.1.1
 
 - **打包内容调整**（无功能变化）：
@@ -21,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,52 +1,52 @@
-{
-  "name": "cortico-world-wechat",
-  "version": "0.1.1",
-  "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"
-  }
-}
+{
+  "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"
+  }
+}