@aster110/cc2wechat 3.1.0 → 3.2.0

package/CODE_REVIEW.md

@@ -0,0 +1,182 @@
+# Code Review: v3 重构后代码审查
+
+> 审查日期: 2026-03-22 | 审查范围: daemon.ts, handlers/, utils.ts, auth.ts, wechat-api.ts
+
+---
+
+## 总评
+
+重构后模块边界清晰，代码量控制得很好。daemon.ts 精简为纯路由层（~180行），两个 handler 各司其职。主要问题集中在：少量代码重复、几处类型安全可改进、pipe.ts 的错误处理略粗糙。
+
+**评级: B+** — 可生产使用，有几个值得迭代的改进点。
+
+---
+
+## 一、模块职责（单一职责原则）
+
+| 模块 | 职责 | 评价 |
+|------|------|------|
+| daemon.ts | 长轮询 + 消息路由（macOS→terminal, 其他→pipe） | 清晰。路由逻辑只有一个 if/else |
+| handlers/terminal.ts | iTerm 窗口管理 + CC interactive 注入 | 清晰。iTerm AppleScript 全封装在此 |
+| handlers/pipe.ts | claude -p 管道模式 + 自动回复 | 清晰。但包含了 markdown 清理和分片逻辑，可考虑抽到 utils |
+| utils.ts | extractText + userIdToSessionUUID + sleep | 清晰。公共工具函数 |
+| auth.ts | QR 登录（终端 + 网页两种模式） | 清晰。两种登录方式都在一个文件 |
+| wechat-api.ts | 微信 API 封装 | 清晰。纯 HTTP 调用层，无业务逻辑 |
+| store.ts | 凭证 + sync buf 持久化 | 清晰 |
+| types.ts | 类型定义 | 清晰 |
+
+**结论**: 模块职责单一，边界合理。
+
+---
+
+## 二、依赖方向
+
+```
+daemon.ts
+  ├── auth.ts         (登录)
+  ├── store.ts        (凭证/游标)
+  ├── wechat-api.ts   (API 调用)
+  ├── utils.ts        (公共工具)
+  ├── types.ts        (类型)
+  ├── handlers/terminal.ts  (macOS)
+  └── handlers/pipe.ts      (Windows/Linux)
+
+handlers/terminal.ts
+  ├── types.ts
+  ├── store.ts (type only)
+  ├── wechat-api.ts    ← 未使用但 import 了
+  └── utils.ts
+
+handlers/pipe.ts
+  ├── types.ts
+  ├── store.ts (type only)
+  ├── utils.ts
+  └── wechat-api.ts    (动态 import sendMessage)
+```
+
+**无循环依赖。** 依赖方向合理：上层依赖下层，handler 之间无互相依赖。
+
+### 问题
+
+1. **terminal.ts 第 6 行**: import 了 `getConfig` 和 `sendTyping`，但函数体内未使用。这两个调用在 daemon.ts 的 `handleMessage` 里已经做了。**建议删除未使用的 import。**
+
+2. **pipe.ts 第 48 行**: `await import('../wechat-api.js')` 用了动态 import，而同文件顶部没有静态 import wechat-api。这样做可能是为了避免循环依赖，但实际不存在循环问题。**建议改为顶部静态 import。**
+
+---
+
+## 三、错误处理
+
+### daemon.ts — 良好
+
+- pollLoop 有完善的 try/catch，连续失败计数 + 退避策略
+- session 过期（errcode=-14）有专门处理
+- typing 发送失败被正确吞掉（non-critical）
+
+### handlers/terminal.ts — 一般
+
+- `tabExists` 的 catch 返回 false，合理
+- tab registry 加载的 catch 是空的（第 28 行），可以加个 console.warn
+- **缺失**: `createTabAndStartCC` 中 `execSync` 的 AppleScript 可能失败（iTerm 未运行），没有 try/catch。**建议包一层 try/catch，失败时 fallback 到 pipe 模式或给出明确错误。**
+- **缺失**: `injectMessage` 中 `execSync` 同样没有错误处理
+
+### handlers/pipe.ts — 粗糙
+
+- 第 31-45 行: 错误处理用 `err as { stdout?: string }` 类型断言，不够安全
+- 嵌套的 try/catch（先试 `--resume`，失败再试 `--session-id`）逻辑可以简化
+- 如果两次都失败，返回的错误信息可能丢失原始错误
+
+### auth.ts — 良好
+
+- QR 过期有自动刷新逻辑
+- HTTP server 在 finally 块中关闭
+- 超时有明确的错误提示
+
+### wechat-api.ts — 良好
+
+- apiFetch 统一了超时 + abort 处理
+- clearTimeout 在 catch 和 正常路径都有
+- AbortError 被正确识别并降级处理
+
+---
+
+## 四、类型安全
+
+### any 使用情况
+
+**无显式 `any`**。整体类型安全。
+
+### 可改进的类型断言
+
+| 位置 | 代码 | 问题 |
+|------|------|------|
+| pipe.ts:32 | `err as { stdout?: string; stderr?: string; message?: string }` | 应使用 node 的 `ExecException` 或自定义 guard |
+| pipe.ts:40 | `err2 as { stdout?: string; message?: string }` | 同上 |
+| terminal.ts:24 | `v as string` | entries 返回 unknown，可以加 typeof 检查 |
+
+### types.ts 的 optional 泛滥
+
+所有字段都是 `?` 可选的。这是对接外部 API 的常见做法，可以接受，但在关键路径上（如 `from_user_id`、`context_token`）可以考虑加 runtime validation。
+
+---
+
+## 五、代码重复
+
+### 1. sleep 函数重复定义
+
+- `daemon.ts:26-28`: 定义了 `sleep()`
+- `utils.ts:28-30`: 也定义了 `sleep()`
+
+daemon.ts 应该直接 import utils 的 sleep。
+
+### 2. extractText + 路由上下文重复
+
+daemon.ts 的 `handleMessage` 调用了 `extractText(msg)` 并提取 `userId`、`contextToken`。handlers/terminal.ts 和 handlers/pipe.ts 内部又各自调用了 `extractText(msg)` 和提取 `userId`。
+
+**建议**: handleMessage 把解析好的数据通过参数传给 handler，避免重复解析。定义一个 `ParsedMessage` 接口：
+
+```typescript
+interface ParsedMessage {
+  text: string;
+  userId: string;
+  contextToken: string;
+  sessionId: string;
+}
+```
+
+### 3. context 写文件
+
+daemon.ts:42 写 `/tmp/cc2wechat-context.json`，这是给 reply-cli 用的。但 terminal 模式下 reply-cli 可能不需要。可以只在 pipe 模式下写。
+
+---
+
+## 六、其他发现
+
+### 安全
+
+- `/tmp/cc2wechat-context.json` 包含 token，写在 /tmp 下任何用户可读。**建议**: 用 `fs.writeFileSync` 后 `chmodSync(0o600)`，或写到 `~/.claude/` 下。
+- `/tmp/cc2wechat-tabs.json` 同理，虽然不含敏感信息。
+
+### 性能
+
+- terminal.ts 中 `tabExists` 每次调用都 `execSync` 一个 AppleScript，同步阻塞。对于消息处理来说可接受（消息频率不高），但如果频率上来会成瓶颈。
+
+### 代码风格
+
+- 注释清晰，分区用 `// ---` 分隔线，风格统一
+- 常量命名一致（全大写 + 下划线）
+- 文件长度合理：daemon 180行、terminal 104行、pipe 56行、utils 30行
+
+---
+
+## 七、改进建议（优先级排序）
+
+| 优先级 | 建议 | 影响 |
+|--------|------|------|
+| P0 | daemon.ts 的 sleep 改为 import utils.sleep | 消除重复 |
+| P0 | terminal.ts 删除未使用的 getConfig/sendTyping import | 代码整洁 |
+| P1 | terminal.ts 的 execSync 加 try/catch | 防止 iTerm 未运行时崩溃 |
+| P1 | /tmp/cc2wechat-context.json 加 chmod 600 | 安全 |
+| P1 | pipe.ts 动态 import 改静态 import | 代码一致性 |
+| P2 | 定义 ParsedMessage 接口，避免 handler 重复解析 | 减少重复 |
+| P2 | pipe.ts 错误处理简化，使用 node ExecException 类型 | 类型安全 |
+| P3 | types.ts 关键字段加 runtime validation | 健壮性 |

package/EXPERIENCE.md

@@ -139,10 +139,51 @@ sendMessage 的 `image_item.url` 字段虽然存在，但直接传远程 URL 微
   - image_item.media.aes_key: base64(hex string)
 - CDN Base URL: `https://novac2c.cdn.weixin.qq.com/c2c`
 
-## 六、待解决
+## 六、v3 Interactive Terminal 模式踩坑
+
+> 2026-03-22 v3 重构
+
+### 坑 9：iTerm tab name 被 CC 覆盖
+
+最初用 tab name（`wechat-xxx`）标识用户窗口。问题：CC 启动后会把 tab title 改成自己的（显示 session info），导致 `tabExists()` 按 name 找不到已有窗口，重复创建。
+
+**解决方案**: 改用 iTerm window id。创建窗口时 `return id of w` 拿到数字 id，后续用 `first window whose id is <id>` 定位。window id 是 iTerm 内部分配的，CC 改不了。
+
+### 坑 10：多实例竞争 — tab registry 持久化
+
+daemon 重启后内存中的 `userTabs` Map 清空，无法找到之前创建的 iTerm 窗口。导致每次重启都创建新窗口，老窗口变成孤儿。
+
+**解决方案**: 把 `tabName → windowId` 的映射持久化到 `/tmp/cc2wechat-tabs.json`。启动时加载，每次创建/更新窗口时写入。`tabExists()` 先查 registry 拿到 window id，再用 AppleScript 验证窗口是否还在。
+
+### 坑 11：AppleScript 中 iTerm vs iTerm2 名称差异
+
+AppleScript 里 iTerm 的 application name 是 `"iTerm2"` 而不是 `"iTerm"`。写成 `tell application "iTerm"` 会弹出 "找不到应用" 的对话框，阻塞 execSync。
+
+**解决方案**: 统一用 `tell application "iTerm2"`。注意 Finder 里显示的名字是 "iTerm"，但 AppleScript identifier 是 "iTerm2"。
+
+### 坑 12：claude -p 不支持 Agent Teams
+
+v2 pipe 模式用 `claude -p <prompt>` 调用 CC。这种模式下 CC 以单次问答模式运行，**不支持 Agent Teams**（spawn worker、TeamCreate 等）。这是 v3 改用 interactive terminal 模式的核心原因。
+
+interactive 模式（`claude --resume`）下 CC 拥有完整能力：Agent Teams、MCP tools、multi-turn 等。
+
+### 坑 13：system prompt 的 reply-cli 路径问题
+
+pipe 模式的 system prompt 里写了 `node ${replyCli} --text "reply"`，其中 `replyCli` 用 `import.meta.url` 算出来的绝对路径。问题：
+
+1. 路径指向 `dist/` 编译产物目录，但 `reply-cli.js` 可能不在预期位置
+2. 如果用 npx 安装，路径是临时目录，下次运行就变了
+
+**解决方案**: `path.join(__dirname, '..', 'reply-cli.js')` 基于当前文件相对定位。terminal 模式下由 CC 的 system prompt（在 skill 文件里）指定 reply-cli 路径，不硬编码在代码里。
+
+---
+
+## 七、待解决
 
 1. **CDN 媒体上传/下载**：图片/文件需要 AES-128-ECB 加密，openclaw 插件有完整实现可参考
 2. **Channel notification 实测**：需要用 `--dangerously-load-development-channels` 启动 CC 测试
 3. **多账号支持**：当前只支持一个账号
 4. **重连机制**：token 失效后是否需要重新扫码？
 5. **npm 包发布**：package name、README、license
+6. **terminal.ts execSync 无 try/catch**：iTerm 未运行时 AppleScript 会抛错，应 fallback 到 pipe 模式
+7. **/tmp 安全**：context.json 含 token，应 chmod 600 或移到 ~/.claude/ 下

package/TEST_REVIEW.md

@@ -0,0 +1,55 @@
+## 测试审查报告
+
+### utils.test.ts
+- 覆盖率：2/3 个 export 函数被测（`extractText`, `userIdToSessionUUID`）
+- 问题：
+  1. **`sleep` 未测试** — 虽然实现简单（Promise + setTimeout），但作为 export 函数应有基本测试
+  2. **extractText 边界遗漏** — VOICE 没有 `voice_item.text`、FILE 没有 `file_item.file_name` 时，item 被静默跳过（不产出任何文本），这个行为未被测试覆盖。如果只有一个这样的 item，结果会是 `[Empty message]`，可能不符合预期
+  3. **extractText 未知类型遗漏** — `item.type` 不在已知枚举中时（如 type=99），item 被静默跳过，未测试
+  4. **userIdToSessionUUID UUID variant 位未校验** — 测试 regex 允许 variant nibble 为任意 hex，实际 UUID v4 要求 `[89ab]`。源码也没做 variant 处理，所以测试和源码一致，但生成的不是严格合规的 UUID v4
+- 建议：
+  - 补 `sleep` 基本测试（resolve 且耗时 >= N ms）
+  - 补 VOICE 无 text、FILE 无 file_name 的边界测试
+  - 补未知 type 的测试
+
+### store.test.ts
+- 覆盖率：5/6 个 export 函数被测（`saveAccount`, `getActiveAccount`, `loadAccounts`, `loadSyncBuf`, `saveSyncBuf`）
+- 问题：
+  1. **`removeAccount` 未测试** — 删除账户功能完全没覆盖
+  2. **accounts.json 文件权限未验证** — `saveAccount` 会 `chmod 0o600`，测试未验证文件权限
+  3. **并发写入未测试** — 两个 `saveAccount` 同时调用可能导致数据丢失（read-modify-write 竞态），虽然 Node 单线程不太会触发，但多进程场景下有风险
+  4. **corrupted JSON 测试缺失** — `loadAccounts` 对 JSON.parse 失败会 catch 返回 `[]`，但没测试 accounts.json 内容损坏的场景
+- 建议：
+  - 补 `removeAccount` 测试（删除存在的、删除不存在的）
+  - 补 corrupted JSON 文件测试（验证 graceful fallback）
+
+### wechat-api.test.ts
+- 覆盖率：2/9 个 export 函数被测（`encryptAesEcb`, `aesEcbPaddedSize`）
+- 问题：
+  1. **7 个 async API 函数完全未测** — `getQRCode`, `pollQRStatus`, `getUpdates`, `sendMessage`, `sendTyping`, `getConfig`, `uploadAndSendMedia` 均无测试
+  2. 这些函数包含重要逻辑（超时处理、AbortError fallback、header 构建、错误处理），不能因为"需要 mock fetch"就跳过
+  3. **encryptAesEcb 空输入未测** — 空 Buffer 加密是合法操作，未覆盖
+- 建议：
+  - 用 `vi.stubGlobal('fetch', ...)` 或 `msw` mock fetch，补充以下测试：
+    - `getUpdates`：正常返回、AbortError 返回默认值、HTTP 错误抛异常
+    - `sendMessage`：正常发送、失败抛异常
+    - `getQRCode`：正常返回、HTTP 错误
+    - `pollQRStatus`：各 status 返回值、超时返回 `{ status: 'wait' }`
+    - `sendTyping` / `getConfig`：基本成功/失败
+    - `uploadAndSendMedia`：至少测 getUploadUrl 无 upload_param 时抛错
+  - 补 `encryptAesEcb(Buffer.alloc(0), key)` 边界测试
+
+### 总体评价
+**需修改**
+
+纯工具函数（crypto、文件存储）测试质量不错，断言精确、覆盖了关键 case。但项目的核心价值在 WeChat API 交互层，7 个 async 函数零测试是最大短板。store 缺 `removeAccount`、utils 缺 `sleep` 属于小问题。
+
+### 需要 test-fixer 修复的问题
+1. **[P0]** wechat-api.test.ts：mock fetch 后补 `getUpdates`、`sendMessage`、`getQRCode`、`pollQRStatus` 测试（至少覆盖正常路径 + 错误路径 + 超时路径）
+2. **[P0]** wechat-api.test.ts：补 `sendTyping`、`getConfig` 基本测试
+3. **[P1]** store.test.ts：补 `removeAccount` 测试
+4. **[P1]** utils.test.ts：补 `sleep` 测试
+5. **[P2]** utils.test.ts：补 extractText 的 VOICE 无 text、FILE 无 file_name、未知 type 边界测试
+6. **[P2]** store.test.ts：补 corrupted JSON fallback 测试
+7. **[P2]** wechat-api.test.ts：补 `encryptAesEcb` 空 Buffer 边界测试
+8. **[P3]** wechat-api.test.ts：补 `uploadAndSendMedia` 测试（复杂度高，可后续补）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aster110/cc2wechat",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "WeChat channel for Claude Code — chat with Claude Code from WeChat via iLink Bot API",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/server.ts",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -23,7 +24,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
   "license": "MIT"
 }

package/tests/store.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// We need to mock the CHANNEL_DIR to use a temp directory
+// Since CHANNEL_DIR is a module-level const, we mock os.homedir before importing
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc2wechat-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// Since store.ts computes CHANNEL_DIR at module load time using os.homedir(),
+// we need to re-import with a mocked homedir each time.
+async function importStore(homeDir: string) {
+  vi.doMock('node:os', async () => {
+    const actual = await vi.importActual<typeof import('node:os')>('node:os');
+    return { ...actual, default: { ...actual, homedir: () => homeDir }, homedir: () => homeDir };
+  });
+  // Force fresh import
+  const mod = await import('../src/store.js');
+  return mod;
+}
+
+describe('store', () => {
+  let store: Awaited<ReturnType<typeof importStore>>;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    store = await importStore(tmpDir);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('saveAccount / getActiveAccount / loadAccounts', () => {
+    it('returns null when no accounts saved', () => {
+      expect(store.getActiveAccount()).toBeNull();
+    });
+
+    it('saves and retrieves an account', () => {
+      const account = {
+        accountId: 'acc1',
+        token: 'tok_abc',
+        baseUrl: 'https://example.com',
+        savedAt: '2026-01-01T00:00:00Z',
+      };
+      store.saveAccount(account);
+      const active = store.getActiveAccount();
+      expect(active).not.toBeNull();
+      expect(active!.accountId).toBe('acc1');
+      expect(active!.token).toBe('tok_abc');
+      expect(active!.baseUrl).toBe('https://example.com');
+    });
+
+    it('returns the last saved account as active', () => {
+      store.saveAccount({ accountId: 'a1', token: 't1', savedAt: '2026-01-01' });
+      store.saveAccount({ accountId: 'a2', token: 't2', savedAt: '2026-01-02' });
+      const active = store.getActiveAccount();
+      expect(active!.accountId).toBe('a2');
+    });
+
+    it('deduplicates by accountId on save', () => {
+      store.saveAccount({ accountId: 'a1', token: 'old', savedAt: '2026-01-01' });
+      store.saveAccount({ accountId: 'a1', token: 'new', savedAt: '2026-01-02' });
+      const accounts = store.loadAccounts();
+      expect(accounts).toHaveLength(1);
+      expect(accounts[0]!.token).toBe('new');
+    });
+  });
+
+  describe('removeAccount', () => {
+    it('removes an existing account', () => {
+      store.saveAccount({ accountId: 'a1', token: 't1', savedAt: '2026-01-01' });
+      store.saveAccount({ accountId: 'a2', token: 't2', savedAt: '2026-01-02' });
+      store.removeAccount('a1');
+      const accounts = store.loadAccounts();
+      expect(accounts).toHaveLength(1);
+      expect(accounts[0]!.accountId).toBe('a2');
+    });
+
+    it('does nothing when removing a non-existent account', () => {
+      store.saveAccount({ accountId: 'a1', token: 't1', savedAt: '2026-01-01' });
+      store.removeAccount('nonexistent');
+      const accounts = store.loadAccounts();
+      expect(accounts).toHaveLength(1);
+    });
+  });
+
+  describe('loadSyncBuf / saveSyncBuf', () => {
+    it('returns empty string when no buf saved', () => {
+      expect(store.loadSyncBuf('nonexistent')).toBe('');
+    });
+
+    it('saves and loads sync buf consistently', () => {
+      store.saveSyncBuf('acc1', 'some_cursor_data_12345');
+      expect(store.loadSyncBuf('acc1')).toBe('some_cursor_data_12345');
+    });
+
+    it('overwrites previous buf', () => {
+      store.saveSyncBuf('acc1', 'first');
+      store.saveSyncBuf('acc1', 'second');
+      expect(store.loadSyncBuf('acc1')).toBe('second');
+    });
+  });
+});

package/tests/utils.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { extractText, userIdToSessionUUID, sleep } from '../src/utils.js';
+import { MessageItemType } from '../src/types.js';
+import type { WeixinMessage } from '../src/types.js';
+
+describe('extractText', () => {
+  it('extracts text from a text message', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.TEXT, text_item: { text: 'hello world' } }],
+    };
+    expect(extractText(msg)).toBe('hello world');
+  });
+
+  it('returns [Image] for image messages', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.IMAGE }],
+    };
+    expect(extractText(msg)).toBe('[Image]');
+  });
+
+  it('extracts voice text', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.VOICE, voice_item: { text: 'voice content' } }],
+    };
+    expect(extractText(msg)).toBe('[Voice] voice content');
+  });
+
+  it('returns [Video] for video messages', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.VIDEO }],
+    };
+    expect(extractText(msg)).toBe('[Video]');
+  });
+
+  it('extracts file name', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.FILE, file_item: { file_name: 'doc.pdf' } }],
+    };
+    expect(extractText(msg)).toBe('[File: doc.pdf]');
+  });
+
+  it('returns [Empty message] for empty item_list', () => {
+    const msg: WeixinMessage = { item_list: [] };
+    expect(extractText(msg)).toBe('[Empty message]');
+  });
+
+  it('returns [Empty message] when item_list is undefined', () => {
+    const msg: WeixinMessage = {};
+    expect(extractText(msg)).toBe('[Empty message]');
+  });
+
+  it('joins multiple items with newline', () => {
+    const msg: WeixinMessage = {
+      item_list: [
+        { type: MessageItemType.TEXT, text_item: { text: 'line1' } },
+        { type: MessageItemType.IMAGE },
+      ],
+    };
+    expect(extractText(msg)).toBe('line1\n[Image]');
+  });
+
+  it('returns [Empty message] for VOICE without text', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.VOICE, voice_item: {} }],
+    };
+    expect(extractText(msg)).toBe('[Empty message]');
+  });
+
+  it('returns [Empty message] for FILE without file_name', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: MessageItemType.FILE, file_item: {} }],
+    };
+    expect(extractText(msg)).toBe('[Empty message]');
+  });
+
+  it('skips items with unknown type', () => {
+    const msg: WeixinMessage = {
+      item_list: [{ type: 99 }],
+    };
+    expect(extractText(msg)).toBe('[Empty message]');
+  });
+});
+
+describe('userIdToSessionUUID', () => {
+  it('is deterministic (same input same output)', () => {
+    const a = userIdToSessionUUID('user123');
+    const b = userIdToSessionUUID('user123');
+    expect(a).toBe(b);
+  });
+
+  it('returns valid UUID v4 format', () => {
+    const uuid = userIdToSessionUUID('testuser');
+    // UUID format: 8-4-4-4-12
+    expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it('produces different outputs for different inputs', () => {
+    const a = userIdToSessionUUID('user_a');
+    const b = userIdToSessionUUID('user_b');
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('sleep', () => {
+  it('resolves after the specified duration', async () => {
+    const start = Date.now();
+    await sleep(50);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeGreaterThanOrEqual(40); // allow small timing variance
+  });
+
+  it('resolves to undefined', async () => {
+    const result = await sleep(1);
+    expect(result).toBeUndefined();
+  });
+});

package/tests/wechat-api.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import crypto from 'node:crypto';
+import {
+  encryptAesEcb,
+  aesEcbPaddedSize,
+  getUpdates,
+  sendMessage,
+  getQRCode,
+  pollQRStatus,
+  sendTyping,
+  getConfig,
+} from '../src/wechat-api.js';
+
+// ---------------------------------------------------------------------------
+// Mock fetch helpers
+// ---------------------------------------------------------------------------
+
+function mockFetchJson(data: unknown, status = 200) {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    text: () => Promise.resolve(JSON.stringify(data)),
+    json: () => Promise.resolve(data),
+    headers: new Headers(),
+  });
+}
+
+function mockFetchText(text: string, status = 200) {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    text: () => Promise.resolve(text),
+    json: () => Promise.resolve(JSON.parse(text)),
+    headers: new Headers(),
+  });
+}
+
+function mockFetchAbort() {
+  return vi.fn().mockRejectedValue(Object.assign(new Error('The operation was aborted'), { name: 'AbortError' }));
+}
+
+// ---------------------------------------------------------------------------
+// API function tests
+// ---------------------------------------------------------------------------
+
+describe('getUpdates', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('returns parsed messages on success', async () => {
+    const resp = { ret: 0, msgs: [{ message_id: 1 }], get_updates_buf: 'buf2' };
+    vi.stubGlobal('fetch', mockFetchText(JSON.stringify(resp)));
+
+    const result = await getUpdates('tok', 'buf1');
+    expect(result.ret).toBe(0);
+    expect(result.msgs).toHaveLength(1);
+    expect(result.get_updates_buf).toBe('buf2');
+  });
+
+  it('returns default value on AbortError (timeout)', async () => {
+    vi.stubGlobal('fetch', mockFetchAbort());
+
+    const result = await getUpdates('tok', 'buf1');
+    expect(result.ret).toBe(0);
+    expect(result.msgs).toEqual([]);
+    expect(result.get_updates_buf).toBe('buf1');
+  });
+});
+
+describe('sendMessage', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('sends message successfully (no throw)', async () => {
+    vi.stubGlobal('fetch', mockFetchText('{"ret":0}'));
+    await expect(sendMessage('tok', 'user1', 'hello', 'ctx1')).resolves.toBeUndefined();
+  });
+});
+
+describe('getQRCode', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('returns qrcode and qrcode_img_content', async () => {
+    const data = { qrcode: 'qr123', qrcode_img_content: 'base64img' };
+    vi.stubGlobal('fetch', mockFetchJson(data));
+
+    const result = await getQRCode();
+    expect(result.qrcode).toBe('qr123');
+    expect(result.qrcode_img_content).toBe('base64img');
+  });
+});
+
+describe('pollQRStatus', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('returns wait status', async () => {
+    vi.stubGlobal('fetch', mockFetchJson({ status: 'wait' }));
+    const result = await pollQRStatus('qr123');
+    expect(result.status).toBe('wait');
+  });
+
+  it('returns confirmed status with token', async () => {
+    const data = { status: 'confirmed', bot_token: 'tok_abc', ilink_bot_id: 'bot1' };
+    vi.stubGlobal('fetch', mockFetchJson(data));
+    const result = await pollQRStatus('qr123');
+    expect(result.status).toBe('confirmed');
+    expect(result.bot_token).toBe('tok_abc');
+  });
+
+  it('returns { status: "wait" } on AbortError (timeout)', async () => {
+    vi.stubGlobal('fetch', mockFetchAbort());
+    const result = await pollQRStatus('qr123');
+    expect(result.status).toBe('wait');
+  });
+});
+
+describe('sendTyping', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('sends typing successfully (no throw)', async () => {
+    vi.stubGlobal('fetch', mockFetchText('{"ret":0}'));
+    await expect(sendTyping('tok', 'user1', 'ticket1')).resolves.toBeUndefined();
+  });
+});
+
+describe('getConfig', () => {
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('returns typing_ticket', async () => {
+    const data = { ret: 0, typing_ticket: 'ticket_xyz' };
+    vi.stubGlobal('fetch', mockFetchText(JSON.stringify(data)));
+
+    const result = await getConfig('tok', 'user1');
+    expect(result.typing_ticket).toBe('ticket_xyz');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Crypto tests
+// ---------------------------------------------------------------------------
+
+describe('encryptAesEcb', () => {
+  it('encrypt then decrypt produces original plaintext', () => {
+    const key = crypto.randomBytes(16);
+    const plaintext = Buffer.from('Hello, WeChat!');
+
+    const ciphertext = encryptAesEcb(plaintext, key);
+
+    // Decrypt with node:crypto to verify
+    const decipher = crypto.createDecipheriv('aes-128-ecb', key, null);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+    expect(decrypted.toString()).toBe('Hello, WeChat!');
+  });
+
+  it('produces ciphertext different from plaintext', () => {
+    const key = crypto.randomBytes(16);
+    const plaintext = Buffer.from('test data here');
+    const ciphertext = encryptAesEcb(plaintext, key);
+    expect(ciphertext.equals(plaintext)).toBe(false);
+  });
+
+  it('different keys produce different ciphertext', () => {
+    const key1 = crypto.randomBytes(16);
+    const key2 = crypto.randomBytes(16);
+    const plaintext = Buffer.from('same input');
+
+    const c1 = encryptAesEcb(plaintext, key1);
+    const c2 = encryptAesEcb(plaintext, key2);
+    expect(c1.equals(c2)).toBe(false);
+  });
+
+  it('ciphertext length matches aesEcbPaddedSize', () => {
+    const key = crypto.randomBytes(16);
+    const plaintext = Buffer.from('variable length content');
+    const ciphertext = encryptAesEcb(plaintext, key);
+    expect(ciphertext.length).toBe(aesEcbPaddedSize(plaintext.length));
+  });
+
+  it('encrypts empty buffer without error', () => {
+    const key = crypto.randomBytes(16);
+    const ciphertext = encryptAesEcb(Buffer.alloc(0), key);
+    expect(ciphertext.length).toBe(16); // one full padding block
+
+    // Decrypt to verify
+    const decipher = crypto.createDecipheriv('aes-128-ecb', key, null);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    expect(decrypted.length).toBe(0);
+  });
+});
+
+describe('aesEcbPaddedSize', () => {
+  it('returns 16 for empty input (0 bytes)', () => {
+    // 0 bytes plaintext → 16 bytes padding (full block of padding)
+    expect(aesEcbPaddedSize(0)).toBe(16);
+  });
+
+  it('returns 16 for 1 byte', () => {
+    expect(aesEcbPaddedSize(1)).toBe(16);
+  });
+
+  it('returns 16 for 15 bytes', () => {
+    // 15 bytes + 1 padding = 16
+    expect(aesEcbPaddedSize(15)).toBe(16);
+  });
+
+  it('returns 32 for 16 bytes (needs full padding block)', () => {
+    // 16 bytes plaintext → needs extra block for PKCS7 padding
+    expect(aesEcbPaddedSize(16)).toBe(32);
+  });
+
+  it('returns 32 for 17 bytes', () => {
+    expect(aesEcbPaddedSize(17)).toBe(32);
+  });
+
+  it('returns 32 for 31 bytes', () => {
+    expect(aesEcbPaddedSize(31)).toBe(32);
+  });
+
+  it('returns 48 for 32 bytes', () => {
+    expect(aesEcbPaddedSize(32)).toBe(48);
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+});