wx2tg-puppet 6.0.16 → 6.0.18-dev.1

package/README.md

@@ -2,15 +2,15 @@
 
 微信机器人核心库，供 `wechat2tg` 调用 `wx2tg-server`。
 
-## v6 配套版本
+## v6 当前稳定配套版本
 
-| 仓库 | 维护分支 | 本次 Git 标签 | npm / Docker 版本 |
+| 仓库 | 维护分支 | 当前稳定 Git 标签 | npm / Docker 版本 |
 | --- | --- | --- | --- |
-| wechat2tg | `v6` | `v6.0.16` | 包版本 `6.0.16`；镜像 `finalpi/wechat2tg:v6.0.16` |
-| wx2tg-puppet | `v6` | `v6.0.16` | npm 格式包 `wx2tg-puppet@6.0.16` |
+| wechat2tg | `v6` | `v6.0.39` | 包版本 `6.0.39`；镜像 `finalpi/wechat2tg:v6.0.39` |
+| wx2tg-puppet | `v6` | `v6.0.17` | npm 格式包 `wx2tg-puppet@6.0.17` |
 | wx2tg-server（fk-zhang） | `v6`，继承 `875` | `v6.0.16` | 镜像 `finalpi/wx2tg-server:v6.0.16` |
 
-**只维护 `v6` 分支，开发版和稳定版用 tag 区分，不建立 `v6-dev` 分支。** `v6.X.Y-dev.N` 为开发版，`v6.X.Y` 为稳定版；npm 不带前面的 `v`。三个仓库使用相同配套版本。Docker 的 `v6-dev` 指向开发版、`v6` 指向稳定版，开发构建不得覆盖稳定别名。历史 `3.x`、`875`、`v51.*`、裸 `v6` 标签保留，不移动。
+**只维护 `v6` 分支，开发版和稳定版用 tag 区分，不建立 `v6-dev` 分支。** `v6.X.Y-dev.N` 为开发版，`v6.X.Y` 为稳定版；npm 不带前面的 `v`。三个组件在 v6 大版本内独立发布，不要求补丁版本号相同；本次 server 保持 v6.0.16。Docker 的 `v6-dev` 指向开发版、`v6` 指向稳定版，开发构建不得覆盖稳定别名。历史 `3.x`、`875`、`v51.*`、裸 `v6` 标签保留，不移动。
 
 根目录 `VERSION`、`package.json`、`package-lock.json` 必须一致；发布标签必须为 `v${VERSION}`。创建本地标签不代表已推送或已发布 npm。发布前执行：
 
@@ -25,6 +25,23 @@ npm pack
 
 `wechat2tg` 可继续锁定同版本本地制品以保证构建可重现；若切换 registry 来源，必须重新生成 lockfile 并校验制品，不要手工伪造 integrity。
 
+## v6.0.18-dev.1：登录不再等待全量联系人（开发预览）
+
+- 修复 `loginSuccess()` 等待所有联系人详情后才启动消息接收、发出登录事件的时序问题。恢复登录和扫码登录先启动接收与心跳，目录任务在后台处理；启动 Sync 取得的消息继续分发，不丢弃。
+- `start()` / `loginTwice()` 完成不再代表全量目录同步结束。依赖初次完整目录的调用方可显式 `await bot.waitForContactSync()`；这是等待当前轮次，不保证失败项已成功，也不启动额外同步。
+- `contacts-updated` 事件通知当前目录轮次结束（也包括后续分页失败后的部分更新），供调用方重新读取目录；不重新触发登录事件。
+- 保留每页最多 4 个详情请求、逐项失败隔离及分页等待。跨登录任务串行衔接，旧任务不再启动剩余详情 / 下一页或发出完成通知。
+- 联系人接口失败不主动退出账号；会话恢复仍由消息 Sync 的原有单次恢复逻辑负责。清缓存和切换扫码账号前等待旧在途写入结束，避免清空后被旧任务重新写入。
+- 208 项离线测试通过，包括安全菜单元数据、联系人保持挂起时接收已就绪、积压消息不丢、退出 / 重新登录、失败处理和缓存清理顺序。未访问真实账号，不代表线上延迟已验收。
+- 此开发包供 Bot `v6.0.40-dev.4` 使用；dev tag 只发布 npm `v6-dev` 通道，以发布工作流成功为准。不替换已发布的 `6.0.17` 制品，也不代表线上完整验收。
+
+## v6.0.17：联系人初始化修复
+
+- 修复初始化时异步详情查询未等待、未捕获，导致 `Contact detail response did not contain the requested contact` 等异常刷屏。
+- 每页最多 4 个并发详情请求，等待本页完成后再翻页；单项失败不会中断其他联系人或群聊。
+- 逐批记录成功 / 失败数量，不记录联系人 ID、接口原始数据或凭据。缺失详情仍明确计入失败，不伪造成功或删除缓存。
+- 183 项测试通过；对应 Bot 修复已通过用户的临时部署验收。
+
 ## 消息接收
 
 ### polling（保持默认）
@@ -57,6 +74,18 @@ HTTP 200 仅表示 puppet 处理并同步发出了事件，不代表异步业务
 
 此 SDK 管理 `puppet.db` 的联系人 schema。其他读取连接不要再次用不完整的镜像实体执行 schema synchronize，否则会删除新增字段。服务端目录接口的 `profile.verify_flag` 可用于批量补齐，但必须验证账号范围，不覆盖更新的已知值。
 
+## 公众号类型与只读菜单元数据（6.0.18-dev.1 开发预览）
+
+- `Contact.serviceType: number | null` 保留 `ContactList[0].CustomizedInfo.ExternalInfo` JSON 字符串中**顶层** `ServiceType` 的 uint32 原值（也接受规范十进制字符串）。仅详情本次明确带品牌位 8 的 `VerifyFlag` 时解析；不根据名称、ID、`BrandFlag` 或任意嵌套 `Type` 猜测。缺失/非法表示未知或保留旧值，绝不推断为订阅号/type 0。
+- `Contact.officialMenu: OfficialMenu | null` 返回经过重新校验的菜单。根入口导出 `OfficialMenu`、`OfficialMenuButton` 类型及纯函数 `parseStoredOfficialMenu(value: unknown): OfficialMenu | null`，供其他只读 DB 连接解析 TEXT 缓存；每次返回新的安全对象。无法解析是 `null`；明确空菜单为 `{buttons: []}`，两者不可混同。
+- `OfficialMenu` 为 `{buttons: OfficialMenuButton[]}`，按钮仅含 `name`、`kind: group | url | unsupported`，以及相应的 `children`、`url` 或 `reason: event | miniapp | wechat | unknown`。菜单组来自 type 0；普通网址只读取 type 2 的 **value**，不把 opaque key 当网址。type 1 事件和 type 5 小程序显示为不可执行项，不提供点击、授权或小程序执行 API。
+- 仅允许无凭据/控制字符的 HTTP(S) 地址；微信协议、脚本、data 及 OAuth/授权地址均变成 `unsupported/wechat`，缓存中的 URL 同样重新验证。不保存原始 key、uin、appid、native_url、版本或其他任意字段。
+- JSON/规范化结果最多 64 KiB、菜单最多 3 层/100 个节点、名称最多 256 字符、URL 最多 4096 字符。原始按钮 ID 可能全部相同，因此不作为身份或执行依据且不保存；超限、相同同级按钮、歧义子树、非法结构均拒绝整个菜单，不截断后冒充完整数据。缺失或非法菜单不覆盖已知缓存；显式空 `button_list` 才清除旧菜单。
+
+Schema 仍由 SDK 管理：`contact.serviceType INTEGER NULL` 与 `contact.officialMenu TEXT NULL` 都无默认值。迁移顺序为已有 `contact-verify-flag.sql` schema → `OfficialAccountMetadata1760000000000`（`src/database/migrations/1760000000000-OfficialAccountMetadata.ts`）→ 原有 TypeORM synchronize。新迁移检查现有列并直接执行 additive `ALTER TABLE ADD COLUMN`，避免 SQLite 的 addColumn helper 重建旧联系人表；fresh DB 无 contact 表时跳过 ALTER，由后续 synchronize 创建完整 schema。已执行迁移记入 TypeORM migrations 表，重启不重复；不提供会丢失元数据的自动 down。`migrations/contact-official-metadata.sql` 仅为对应增量的版本控制参考，不需手工修改远程 DB。Bot 镜像连接必须保持 `synchronize=false`。
+
+离线测试 `test/official-account-metadata.test.cjs` 使用合成数据覆盖真实详情入库路径、未知字段保留、菜单/URL 安全、隐私字段剔除、边界，以及旧/新 SQLite 初始化和旧行无重建保留。
+
 ## 接龙消息
 
 `Message.Type.Solitaire` 对应外层 `49`、应用子类型 `53`。`Message.text()` 返回接龙完整可见标题、名单和尾注；原始 `Content`、`_text`、`_xml` 保持不变，不把内部 `solitaire_info` 当正文输出。CDATA、实体转义、前导零、Unicode 和换行保留；无法安全解析时返回明确的接龙占位提示。此功能只负责识别/读取，不自动参与、发送或重放历史接龙。

package/VERSION

@@ -1 +1 @@
-6.0.16
+6.0.18-dev.1

package/dist/core/Contact.d.ts

@@ -1,5 +1,6 @@
 import { ContactEntity } from "../entities/ContactEntity";
 import { ResponseMsg } from "./Message";
+import { OfficialMenu } from '../utils/OfficialAccountMetadata';
 export type Message = any;
 export type FileBox = any;
 export type ContactType = any;
@@ -12,6 +13,8 @@ export declare class Contact {
     get nickName(): string;
     get verifyFlag(): number | null;
     isOfficialAccount(): boolean | undefined;
+    get serviceType(): number | null;
+    get officialMenu(): OfficialMenu | null;
     /**
      * Contact id (readonly)
      */

package/dist/core/Contact.js

@@ -15,6 +15,7 @@ const FriendApi_1 = require("../api/FriendApi");
 const config_service_1 = require("../services/config.service");
 const common_1 = require("../action/common");
 const ContactClassification_1 = require("../utils/ContactClassification");
+const OfficialAccountMetadata_1 = require("../utils/OfficialAccountMetadata");
 const detailFetches = new Map();
 const unknownRefreshAttempts = new Map();
 const UNKNOWN_REFRESH_INTERVAL_MS = 30000;
@@ -36,6 +37,14 @@ class Contact {
     isOfficialAccount() {
         return (0, ContactClassification_1.isOfficialAccountVerifyFlag)(this.verifyFlag);
     }
+    get serviceType() {
+        var _a;
+        return this.isOfficialAccount() === true ? (0, ContactClassification_1.normalizeContactVerifyFlag)((_a = this.contact) === null || _a === void 0 ? void 0 : _a.serviceType) : null;
+    }
+    get officialMenu() {
+        var _a;
+        return this.isOfficialAccount() === true ? (0, OfficialAccountMetadata_1.parseStoredOfficialMenu)((_a = this.contact) === null || _a === void 0 ? void 0 : _a.officialMenu) : null;
+    }
     constructor(contact) {
         this.contact = null;
         this.contact = contact;
@@ -228,7 +237,7 @@ class Contact {
     }
     static loadContactDetail(Wxid, Towxid) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2;
             const detail = yield FriendApi_1.friendApi.GetContractDetail({
                 "ChatRoom": "",
                 "Towxids": Towxid,
@@ -243,7 +252,8 @@ class Contact {
                 throw new Error('Contact detail response did not contain the requested contact');
             }
             const verifyFlag = (0, ContactClassification_1.normalizeContactVerifyFlag)(detailDataSave.VerifyFlag);
-            const contact = Object.assign(Object.assign({ userName }, (verifyFlag === null ? {} : { verifyFlag })), { nickName: (_f = (_e = detailDataSave.NickName) === null || _e === void 0 ? void 0 : _e.string) !== null && _f !== void 0 ? _f : 'no name', pyInitial: (_h = (_g = detailDataSave.Pyinitial) === null || _g === void 0 ? void 0 : _g.string) !== null && _h !== void 0 ? _h : '', quanPin: (_k = (_j = detailDataSave.QuanPin) === null || _j === void 0 ? void 0 : _j.string) !== null && _k !== void 0 ? _k : '', sex: (_l = detailDataSave.Sex) !== null && _l !== void 0 ? _l : null, remark: (_o = (_m = detailDataSave.Remark) === null || _m === void 0 ? void 0 : _m.string) !== null && _o !== void 0 ? _o : '', remarkPyInitial: (_q = (_p = detailDataSave.RemarkPyinitial) === null || _p === void 0 ? void 0 : _p.string) !== null && _q !== void 0 ? _q : '', remarkQuanPin: (_s = (_r = detailDataSave.RemarkQuanPin) === null || _r === void 0 ? void 0 : _r.string) !== null && _s !== void 0 ? _s : '', signature: (_t = detailDataSave.Signature) !== null && _t !== void 0 ? _t : '', alias: (_u = detailDataSave.Alias) !== null && _u !== void 0 ? _u : '', snsBgImg: (_w = (_v = detailDataSave.SnsUserInfo) === null || _v === void 0 ? void 0 : _v.SnsBgimgId) !== null && _w !== void 0 ? _w : '', country: (_x = detailDataSave.Country) !== null && _x !== void 0 ? _x : '', bigHeadImgUrl: (_y = detailDataSave.BigHeadImgUrl) !== null && _y !== void 0 ? _y : '', smallHeadImgUrl: (_z = detailDataSave.SmallHeadImgUrl) !== null && _z !== void 0 ? _z : '', province: (_0 = detailDataSave.Province) !== null && _0 !== void 0 ? _0 : '', city: (_1 = detailDataSave.City) !== null && _1 !== void 0 ? _1 : '' });
+            const metadata = (0, OfficialAccountMetadata_1.decodeOfficialAccountMetadata)((_e = detailDataSave.CustomizedInfo) === null || _e === void 0 ? void 0 : _e.ExternalInfo, verifyFlag);
+            const contact = Object.assign(Object.assign(Object.assign(Object.assign({ userName }, (verifyFlag === null ? {} : { verifyFlag })), (metadata.serviceType === undefined ? {} : { serviceType: metadata.serviceType })), (metadata.officialMenu === undefined ? {} : { officialMenu: JSON.stringify(metadata.officialMenu) })), { nickName: (_g = (_f = detailDataSave.NickName) === null || _f === void 0 ? void 0 : _f.string) !== null && _g !== void 0 ? _g : 'no name', pyInitial: (_j = (_h = detailDataSave.Pyinitial) === null || _h === void 0 ? void 0 : _h.string) !== null && _j !== void 0 ? _j : '', quanPin: (_l = (_k = detailDataSave.QuanPin) === null || _k === void 0 ? void 0 : _k.string) !== null && _l !== void 0 ? _l : '', sex: (_m = detailDataSave.Sex) !== null && _m !== void 0 ? _m : null, remark: (_p = (_o = detailDataSave.Remark) === null || _o === void 0 ? void 0 : _o.string) !== null && _p !== void 0 ? _p : '', remarkPyInitial: (_r = (_q = detailDataSave.RemarkPyinitial) === null || _q === void 0 ? void 0 : _q.string) !== null && _r !== void 0 ? _r : '', remarkQuanPin: (_t = (_s = detailDataSave.RemarkQuanPin) === null || _s === void 0 ? void 0 : _s.string) !== null && _t !== void 0 ? _t : '', signature: (_u = detailDataSave.Signature) !== null && _u !== void 0 ? _u : '', alias: (_v = detailDataSave.Alias) !== null && _v !== void 0 ? _v : '', snsBgImg: (_x = (_w = detailDataSave.SnsUserInfo) === null || _w === void 0 ? void 0 : _w.SnsBgimgId) !== null && _x !== void 0 ? _x : '', country: (_y = detailDataSave.Country) !== null && _y !== void 0 ? _y : '', bigHeadImgUrl: (_z = detailDataSave.BigHeadImgUrl) !== null && _z !== void 0 ? _z : '', smallHeadImgUrl: (_0 = detailDataSave.SmallHeadImgUrl) !== null && _0 !== void 0 ? _0 : '', province: (_1 = detailDataSave.Province) !== null && _1 !== void 0 ? _1 : '', city: (_2 = detailDataSave.City) !== null && _2 !== void 0 ? _2 : '' });
             return contact_service_1.contactService.upsertByUsername(userName, contact);
         });
     }

package/dist/database/data-source.js

@@ -8,11 +8,15 @@ const config_entity_1 = require("../entities/config.entity");
 const ContactEntity_1 = require("../entities/ContactEntity");
 const RoomEntity_1 = require("../entities/RoomEntity");
 const MessageEntity_1 = require("../entities/MessageEntity");
+const _1760000000000_OfficialAccountMetadata_1 = require("./migrations/1760000000000-OfficialAccountMetadata");
 function createAppDataSource(databasePath) {
     exports.AppDataSource = new typeorm_1.DataSource({
         type: 'sqlite',
         database: databasePath,
         synchronize: true,
+        // TypeORM runs migrations before synchronize: upgrade old caches in place.
+        migrationsRun: true,
+        migrations: [_1760000000000_OfficialAccountMetadata_1.OfficialAccountMetadata1760000000000],
         logging: false,
         entities: [config_entity_1.Config, ContactEntity_1.ContactEntity, RoomEntity_1.RoomEntity, MessageEntity_1.MessageEntity],
     });

package/dist/database/migrations/1760000000000-OfficialAccountMetadata.d.ts

@@ -0,0 +1,6 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+/** Add columns in place: TypeORM's SQLite addColumn helper rebuilds tables. */
+export declare class OfficialAccountMetadata1760000000000 implements MigrationInterface {
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(): Promise<void>;
+}

package/dist/database/migrations/1760000000000-OfficialAccountMetadata.js

@@ -0,0 +1,34 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfficialAccountMetadata1760000000000 = void 0;
+/** Add columns in place: TypeORM's SQLite addColumn helper rebuilds tables. */
+class OfficialAccountMetadata1760000000000 {
+    up(queryRunner) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!(yield queryRunner.hasTable('contact')))
+                return; // Fresh SDK schema is created by synchronize afterwards.
+            const columns = yield queryRunner.query('PRAGMA table_info("contact")');
+            if (!columns.some(column => column.name === 'serviceType')) {
+                yield queryRunner.query('ALTER TABLE "contact" ADD COLUMN "serviceType" integer');
+            }
+            if (!columns.some(column => column.name === 'officialMenu')) {
+                yield queryRunner.query('ALTER TABLE "contact" ADD COLUMN "officialMenu" text');
+            }
+        });
+    }
+    down() {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new Error('Additive contact metadata migration cannot be reverted without losing cached metadata');
+        });
+    }
+}
+exports.OfficialAccountMetadata1760000000000 = OfficialAccountMetadata1760000000000;

package/dist/entities/ContactEntity.d.ts

@@ -5,6 +5,8 @@ export declare class ContactEntity {
     quanPin: string;
     sex: number;
     verifyFlag?: number | null;
+    serviceType?: number | null;
+    officialMenu?: string | null;
     remark: string;
     remarkPyInitial: string;
     remarkQuanPin: string;

package/dist/entities/ContactEntity.js

@@ -39,6 +39,14 @@ __decorate([
     (0, typeorm_1.Column)('integer', { nullable: true }),
     __metadata("design:type", Object)
 ], ContactEntity.prototype, "verifyFlag", void 0);
+__decorate([
+    (0, typeorm_1.Column)('integer', { nullable: true }),
+    __metadata("design:type", Object)
+], ContactEntity.prototype, "serviceType", void 0);
+__decorate([
+    (0, typeorm_1.Column)('text', { nullable: true }),
+    __metadata("design:type", Object)
+], ContactEntity.prototype, "officialMenu", void 0);
 __decorate([
     (0, typeorm_1.Column)('text', { nullable: true }),
     __metadata("design:type", String)

package/dist/index.d.ts

@@ -38,6 +38,8 @@ export declare class WxBot extends EventEmitter {
     private syncTask;
     private syncRequested;
     private loginRecoveryInProgress;
+    private contactSyncTask;
+    private contactSyncGeneration;
     private syncFailureCount;
     private httpServer;
     private loggingOut;
@@ -58,6 +60,9 @@ export declare class WxBot extends EventEmitter {
      * @param currentChatroomSeq 当前群聊联系人序列号
      */
     private fetchAllContacts;
+    private startContactSync;
+    /** Explicit directory barrier for callers that need the current background pass. */
+    waitForContactSync(): Promise<void>;
     private loginSuccess;
     private startCallbackServer;
     private handleCallbackMessage;
@@ -86,4 +91,6 @@ export declare class WxBot extends EventEmitter {
 }
 export { Contact, Room, Message };
 export { normalizeContactVerifyFlag, isOfficialAccountVerifyFlag } from './utils/ContactClassification';
+export { parseStoredOfficialMenu } from './utils/OfficialAccountMetadata';
+export type { OfficialMenu, OfficialMenuButton } from './utils/OfficialAccountMetadata';
 export { Emoji, Voice, WeVideo, UrlLink };

package/dist/index.js

@@ -42,7 +42,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UrlLink = exports.WeVideo = exports.Voice = exports.Emoji = exports.isOfficialAccountVerifyFlag = exports.normalizeContactVerifyFlag = exports.Message = exports.Room = exports.Contact = exports.WxBot = exports.AppDataSource = void 0;
+exports.UrlLink = exports.WeVideo = exports.Voice = exports.Emoji = exports.parseStoredOfficialMenu = exports.isOfficialAccountVerifyFlag = exports.normalizeContactVerifyFlag = exports.Message = exports.Room = exports.Contact = exports.WxBot = exports.AppDataSource = void 0;
 require("reflect-metadata");
 const axiosInstance_1 = require("./utils/axiosInstance");
 const data_source_1 = require("./database/data-source");
@@ -87,6 +87,8 @@ class WxBot extends events_1.EventEmitter {
         this.syncTask = null;
         this.syncRequested = false;
         this.loginRecoveryInProgress = false;
+        this.contactSyncTask = null;
+        this.contactSyncGeneration = 0;
         this.syncFailureCount = 0; // Sync failure counter
         this.httpServer = null; // HTTP回调服务器
         this.loggingOut = false; // Flag to prevent concurrent logOut calls
@@ -256,13 +258,18 @@ class WxBot extends events_1.EventEmitter {
                 const statusData = statusResp.data;
                 if (statusData.Success) {
                     if (statusData.Message === '登录成功') {
+                        // Drain only old in-flight detail requests before changing accounts.
+                        this.contactSyncGeneration++;
+                        yield this.waitForContactSync();
                         yield config_service_1.configService.save({
                             uuid: this.uuid,
                             wxid: statusData.Data.acctSectResp.userName,
                         });
-                        this.loginSuccess(statusData.Data.acctSectResp.userName);
-                        if (this.interval)
+                        if (this.interval) {
                             clearInterval(this.interval);
+                            this.interval = null;
+                        }
+                        yield this.loginSuccess(statusData.Data.acctSectResp.userName);
                     }
                 }
                 else if (statusData.Message.includes('数据不存在') || statusData.Message.includes('未知的错误')) {
@@ -294,6 +301,8 @@ class WxBot extends events_1.EventEmitter {
         });
     }
     clearAllIntervals() {
+        // In-flight requests may settle, but old sessions cannot schedule more work.
+        this.contactSyncGeneration++;
         if (this.interval) {
             clearInterval(this.interval);
             this.interval = null;
@@ -322,34 +331,58 @@ class WxBot extends events_1.EventEmitter {
      * @param currentChatroomSeq 当前群聊联系人序列号
      */
     fetchAllContacts(userName_1) {
-        return __awaiter(this, arguments, void 0, function* (userName, currentWxSeq = 0, currentChatroomSeq = 0) {
+        return __awaiter(this, arguments, void 0, function* (userName, currentWxSeq = 0, currentChatroomSeq = 0, generation = this.contactSyncGeneration) {
+            if (generation !== this.contactSyncGeneration)
+                return false;
             try {
                 const res = yield FriendApi_1.friendApi.GetContractList({
                     "Wxid": userName,
                     "CurrentChatRoomContactSeq": currentChatroomSeq,
                     "CurrentWxcontactSeq": currentWxSeq,
                 });
+                if (generation !== this.contactSyncGeneration)
+                    return false;
                 if (res.data.Message === '用户可能退出') {
-                    yield this.logOut();
-                    yield this.login();
-                    return;
+                    // Optional directory work is not the session authority. Message Sync
+                    // owns recovery; starting it here could wait on this very task on reset.
+                    console.error('联系人接口提示会话可能失效，交由消息同步检查');
+                    return false;
                 }
                 const data = res.data;
                 if (!data.Success) {
-                    console.error('获取联系人列表失败:', data.Message);
-                    return;
+                    console.error('获取联系人列表失败，保留已有目录');
+                    return false;
                 }
                 // 处理当前批次的联系人
                 if (data.Data && data.Data.ContactUsernameList) {
                     console.log(`获取到 ${data.Data.ContactUsernameList.length} 个联系人`);
-                    data.Data.ContactUsernameList.forEach((contact) => {
-                        if (!contact.endsWith('@chatroom')) {
-                            Contact_1.Contact.fetchAndUpsertContactDetail(userName, contact);
-                        }
-                        else {
-                            Room_1.Room.find({ id: contact });
+                    const contacts = data.Data.ContactUsernameList;
+                    let nextIndex = 0;
+                    let succeeded = 0;
+                    let failed = 0;
+                    // Bound detail requests and finish this page before requesting the next.
+                    const worker = () => __awaiter(this, void 0, void 0, function* () {
+                        while (generation === this.contactSyncGeneration && nextIndex < contacts.length) {
+                            const contact = contacts[nextIndex++];
+                            try {
+                                if (!contact.endsWith('@chatroom')) {
+                                    yield Contact_1.Contact.fetchAndUpsertContactDetail(userName, contact);
+                                }
+                                else {
+                                    yield Room_1.Room.find({ id: contact });
+                                }
+                                succeeded++;
+                            }
+                            catch (_a) {
+                                // A missing/failed item must not abort the page or leak private data.
+                                failed++;
+                            }
                         }
                     });
+                    yield Promise.all(Array.from({ length: Math.min(4, contacts.length) }, () => worker()));
+                    if (generation !== this.contactSyncGeneration)
+                        return false;
+                    console.log(`联系人批次处理完成: 成功 ${succeeded}，失败 ${failed}`);
                 }
                 // 检查是否还有更多联系人需要获取
                 // CountinueFlag 为 1 表示还有更多数据
@@ -358,27 +391,60 @@ class WxBot extends events_1.EventEmitter {
                     const nextChatroomSeq = data.Data.CurrentChatRoomContactSeq || 0;
                     console.log(`还有更多联系人，继续获取... (WxSeq: ${nextWxSeq}, ChatroomSeq: ${nextChatroomSeq})`);
                     // 递归获取下一批联系人
-                    yield this.fetchAllContacts(userName, nextWxSeq, nextChatroomSeq);
+                    return yield this.fetchAllContacts(userName, nextWxSeq, nextChatroomSeq, generation);
                 }
                 else {
                     console.log('联系人列表获取完成');
+                    return true;
                 }
             }
-            catch (error) {
-                console.error('获取联系人列表时发生错误:', error);
+            catch (_a) {
+                if (generation === this.contactSyncGeneration)
+                    console.error('获取联系人列表时发生错误，保留已有目录');
+                return false;
             }
         });
     }
+    startContactSync(userName) {
+        const generation = this.contactSyncGeneration;
+        const previous = this.contactSyncTask;
+        const task = Promise.resolve(previous).then(() => __awaiter(this, void 0, void 0, function* () {
+            if (generation !== this.contactSyncGeneration)
+                return;
+            console.log('开始后台同步联系人，不阻塞消息接收');
+            const complete = yield this.fetchAllContacts(userName, 0, 0, generation);
+            if (generation !== this.contactSyncGeneration)
+                return;
+            console.log(complete ? '联系人后台同步批次处理完成' : '联系人后台同步未完成，已有目录仍可使用');
+            // Also invalidate a partially updated directory after a later page fails.
+            this.emit('contacts-updated');
+        })).catch(() => {
+            if (generation === this.contactSyncGeneration)
+                console.error('联系人后台同步失败');
+        }).finally(() => {
+            if (this.contactSyncTask === task)
+                this.contactSyncTask = null;
+        });
+        this.contactSyncTask = task;
+    }
+    /** Explicit directory barrier for callers that need the current background pass. */
+    waitForContactSync() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.contactSyncTask;
+        });
+    }
     loginSuccess(userName) {
         return __awaiter(this, void 0, void 0, function* () {
-            contact_service_1.contactService.clearRoom();
-            this.clearAllIntervals(); // 确保清理所有定时器
+            this.clearAllIntervals(); // 确保清理所有定时器，取消旧目录任务
+            const generation = this.contactSyncGeneration;
+            yield contact_service_1.contactService.clearRoom();
+            if (generation !== this.contactSyncGeneration)
+                return false;
             this.syncFailureCount = 0; // 重置失败计数器
-            // 分页获取所有联系人
-            yield this.fetchAllContacts(userName, 0, 0);
-            console.log('所有联系人获取完成');
             // 设置设备信息
             const cacheInfo = yield LoginApi_1.loginApi.GetCacheInfo(userName);
+            if (generation !== this.contactSyncGeneration)
+                return false;
             if (cacheInfo.data.Message === '成功') {
                 yield config_service_1.configService.save({
                     deviceId: cacheInfo.data.Data.Deviceid_str,
@@ -386,10 +452,16 @@ class WxBot extends events_1.EventEmitter {
                     DeviceType: this.deviceType,
                 });
             }
+            if (generation !== this.contactSyncGeneration)
+                return false;
             // 先监听再启动心跳；不再通过 Sync 清空并丢弃登录期间的消息。
             if (this.mode === 'callback') {
                 yield this.startCallbackServer(userName);
+                if (generation !== this.contactSyncGeneration)
+                    return false;
                 this.emit('login', userName);
+                if (generation !== this.contactSyncGeneration)
+                    return false;
                 this.callbackInterval = setInterval(() => {
                     void this.handleMsg(userName).catch(() => console.error('回调兜底同步失败'));
                 }, 1000 * 60 * 5);
@@ -397,7 +469,13 @@ class WxBot extends events_1.EventEmitter {
             else {
                 this.startPollingMode(userName);
             }
+            if (generation !== this.contactSyncGeneration)
+                return false;
             yield this.setupHeartbeat(userName);
+            if (generation !== this.contactSyncGeneration)
+                return false;
+            this.startContactSync(userName);
+            return true;
         });
     }
     startCallbackServer(userName) {
@@ -711,15 +789,17 @@ class WxBot extends events_1.EventEmitter {
      */
     clearCache() {
         return __awaiter(this, void 0, void 0, function* () {
-            this.logOut();
+            yield this.logOut();
+            // Never let an old request repopulate the cache after an account reset.
+            yield this.waitForContactSync();
             const config = yield config_service_1.configService.get();
             if (config) {
                 const res = yield LoginApi_1.loginApi.LogOut(config.wxid);
             }
-            config_service_1.configService.clear();
-            room_service_1.roomService.clear();
-            contact_service_1.contactService.clear();
-            message_service_1.messageService.clear();
+            yield config_service_1.configService.clear();
+            yield room_service_1.roomService.clear();
+            yield contact_service_1.contactService.clear();
+            yield message_service_1.messageService.clear();
         });
     }
     login() {
@@ -757,8 +837,8 @@ class WxBot extends events_1.EventEmitter {
                         "Synckey": ""
                     });
                     if (resp.data.Code === 0) {
-                        yield this.loginSuccess(config.wxid);
-                        yield this.enqueueMessages(config.wxid, resp.data);
+                        if (yield this.loginSuccess(config.wxid))
+                            yield this.enqueueMessages(config.wxid, resp.data);
                     }
                     else {
                         yield this.login();
@@ -787,7 +867,8 @@ class WxBot extends events_1.EventEmitter {
             });
             yield LoginApi_1.loginApi.LoginTwiceAutoAuth(config === null || config === void 0 ? void 0 : config.wxid);
             if (yield this.checkSyncLoginStatus(resp.data, config === null || config === void 0 ? void 0 : config.wxid)) {
-                yield this.loginSuccess(config.wxid);
+                if (!(yield this.loginSuccess(config.wxid)))
+                    return false;
                 yield this.enqueueMessages(config.wxid, resp.data);
                 return true;
             }
@@ -819,3 +900,5 @@ exports.WxBot = WxBot;
 var ContactClassification_1 = require("./utils/ContactClassification");
 Object.defineProperty(exports, "normalizeContactVerifyFlag", { enumerable: true, get: function () { return ContactClassification_1.normalizeContactVerifyFlag; } });
 Object.defineProperty(exports, "isOfficialAccountVerifyFlag", { enumerable: true, get: function () { return ContactClassification_1.isOfficialAccountVerifyFlag; } });
+var OfficialAccountMetadata_1 = require("./utils/OfficialAccountMetadata");
+Object.defineProperty(exports, "parseStoredOfficialMenu", { enumerable: true, get: function () { return OfficialAccountMetadata_1.parseStoredOfficialMenu; } });

package/dist/utils/OfficialAccountMetadata.d.ts

@@ -0,0 +1,17 @@
+export interface OfficialMenu {
+    buttons: OfficialMenuButton[];
+}
+export interface OfficialMenuButton {
+    name: string;
+    kind: 'group' | 'url' | 'unsupported';
+    url?: string;
+    reason?: 'event' | 'miniapp' | 'wechat' | 'unknown';
+    children?: OfficialMenuButton[];
+}
+/** Revalidate untrusted DB JSON (or an object) and return a fresh, allowlisted tree. */
+export declare function parseStoredOfficialMenu(value: unknown): OfficialMenu | null;
+/** Missing/invalid fields are omitted so an atomic partial upsert preserves known metadata. */
+export declare function decodeOfficialAccountMetadata(externalInfo: unknown, verifyFlag: unknown): {
+    serviceType?: number;
+    officialMenu?: OfficialMenu;
+};

package/dist/utils/OfficialAccountMetadata.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStoredOfficialMenu = parseStoredOfficialMenu;
+exports.decodeOfficialAccountMetadata = decodeOfficialAccountMetadata;
+const ContactClassification_1 = require("./ContactClassification");
+// Reject the entire tree at a limit, rather than displaying a truncated menu as complete.
+const MAX_JSON_BYTES = 64 * 1024;
+const MAX_DEPTH = 3;
+const MAX_NODES = 100;
+const MAX_NAME_LENGTH = 256;
+const MAX_URL_LENGTH = 4096;
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+function record(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+// Never use inherited values or invoke getters on caller-supplied cached objects.
+function own(value, key) {
+    var _a;
+    return (_a = Object.getOwnPropertyDescriptor(value, key)) === null || _a === void 0 ? void 0 : _a.value;
+}
+function json(value) {
+    if (typeof value !== 'string' || value.length > MAX_JSON_BYTES
+        || Buffer.byteLength(value, 'utf8') > MAX_JSON_BYTES)
+        return null;
+    return JSON.parse(value);
+}
+function safeUrl(value) {
+    if (typeof value !== 'string' || !value || value.length > MAX_URL_LENGTH
+        || /[\s\\]/u.test(value) || CONTROL.test(value) || !/^https?:\/\//i.test(value))
+        return null;
+    const url = new URL(value);
+    if (!url.hostname || url.username || url.password)
+        return null;
+    // Encoded authorization links and control characters must not bypass the check.
+    let decoded = value;
+    for (let i = 0; i < 4; i++) {
+        if (CONTROL.test(decoded) || /oauth|authori[sz]|snsapi_|connect\/qrconnect|(?:[?&#])(?:response_type|redirect_uri)=/i.test(decoded)) {
+            return null;
+        }
+        const next = decodeURIComponent(decoded);
+        if (next === decoded)
+            return value;
+        decoded = next;
+    }
+    return null;
+}
+function normalizeMenu(value, raw) {
+    if (!record(value))
+        return null;
+    let nodes = 0;
+    let textSize = 0;
+    const seen = new WeakSet();
+    function buttons(value, depth) {
+        if (!Array.isArray(value) || depth > MAX_DEPTH || value.length > MAX_NODES)
+            return null;
+        if (seen.has(value))
+            return null;
+        seen.add(value);
+        const result = [];
+        const siblings = new Set();
+        for (let i = 0; i < value.length; i++) {
+            const item = own(value, String(i));
+            if (!record(item) || seen.has(item) || ++nodes > MAX_NODES)
+                return null;
+            seen.add(item);
+            const name = own(item, 'name');
+            if (typeof name !== 'string' || !name.trim() || name.length > MAX_NAME_LENGTH || CONTROL.test(name))
+                return null;
+            textSize += Buffer.byteLength(name, 'utf8');
+            // Live menus may reuse the same placeholder id for every button. IDs and
+            // event keys are neither exposed nor used to execute actions here.
+            const type = own(item, raw ? 'type' : 'kind');
+            if (raw && (typeof type !== 'number' || !Number.isInteger(type) || type < 0 || type > 0xffffffff))
+                return null;
+            const children = own(item, raw ? 'sub_button_list' : 'children');
+            let button;
+            if (type === (raw ? 0 : 'group')) {
+                const nested = buttons(children, depth + 1);
+                if (!nested || !nested.length)
+                    return null;
+                button = { name, kind: 'group', children: nested };
+            }
+            else {
+                // A leaf with children is ambiguous; do not silently discard a subtree.
+                if (children !== undefined && !(raw && children === null)
+                    && (!Array.isArray(children) || children.length !== 0))
+                    return null;
+                if (type === (raw ? 2 : 'url')) {
+                    const candidate = own(item, raw ? 'value' : 'url');
+                    if (typeof candidate !== 'string')
+                        return null;
+                    let url;
+                    try {
+                        url = safeUrl(candidate);
+                    }
+                    catch (_a) {
+                        url = null;
+                    }
+                    if (url) {
+                        textSize += Buffer.byteLength(url, 'utf8');
+                        button = { name, kind: 'url', url };
+                    }
+                    else {
+                        button = { name, kind: 'unsupported', reason: 'wechat' };
+                    }
+                }
+                else if (raw) {
+                    button = { name, kind: 'unsupported', reason: type === 1 ? 'event' : type === 5 ? 'miniapp' : 'unknown' };
+                }
+                else if (type === 'unsupported') {
+                    const reason = own(item, 'reason');
+                    if (reason !== 'event' && reason !== 'miniapp' && reason !== 'wechat' && reason !== 'unknown')
+                        return null;
+                    button = { name, kind: 'unsupported', reason };
+                }
+                else {
+                    return null;
+                }
+            }
+            if (textSize > MAX_JSON_BYTES)
+                return null;
+            const identity = JSON.stringify(button);
+            if (siblings.has(identity))
+                return null;
+            siblings.add(identity);
+            result.push(button);
+        }
+        return result;
+    }
+    const normalized = buttons(own(value, raw ? 'button_list' : 'buttons'), 1);
+    if (!normalized)
+        return null;
+    const menu = { buttons: normalized };
+    return Buffer.byteLength(JSON.stringify(menu), 'utf8') <= MAX_JSON_BYTES ? menu : null;
+}
+/** Revalidate untrusted DB JSON (or an object) and return a fresh, allowlisted tree. */
+function parseStoredOfficialMenu(value) {
+    try {
+        return normalizeMenu(typeof value === 'string' ? json(value) : value, false);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** Missing/invalid fields are omitted so an atomic partial upsert preserves known metadata. */
+function decodeOfficialAccountMetadata(externalInfo, verifyFlag) {
+    const result = {};
+    if ((0, ContactClassification_1.isOfficialAccountVerifyFlag)(verifyFlag) !== true)
+        return result;
+    try {
+        const external = json(externalInfo);
+        if (!record(external))
+            return result;
+        const serviceType = (0, ContactClassification_1.normalizeContactVerifyFlag)(own(external, 'ServiceType'));
+        if (serviceType !== null)
+            result.serviceType = serviceType;
+        const officialMenu = normalizeMenu(own(external, 'MMBizMenu'), true);
+        if (officialMenu)
+            result.officialMenu = officialMenu;
+    }
+    catch (_a) {
+        // Malformed ExternalInfo is not evidence that the account has no menu.
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wx2tg-puppet",
-  "version": "6.0.16",
+  "version": "6.0.18-dev.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [