chatboty 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "chatboty",
+  "version": "0.1.0",
+  "description": "chatboty — 企业微信(WeCom)IM 自动化 SDK。自研全生态框架, 收发消息/群管理/群事件/联系人, 经云网关连接你的探针实例。",
+  "type": "module",
+  "main": "dist/cjs/src/mod.js",
+  "types": "dist/esm/src/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/src/mod.d.ts",
+      "require": "./dist/cjs/src/mod.js",
+      "import": "./dist/esm/src/mod.js"
+    },
+    "./client": {
+      "types": "./dist/esm/src/client.d.ts",
+      "require": "./dist/cjs/src/client.js",
+      "import": "./dist/esm/src/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/fixup-cjs.mjs",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "chatboty",
+    "wecom",
+    "wxwork",
+    "企业微信",
+    "im",
+    "chatbot",
+    "automation"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0"
+  },
+  "license": "Apache-2.0"
+}

package/src/chatboty.ts

@@ -0,0 +1,228 @@
+/**
+ * Chatboty — 自研机器人主类(零外部框架依赖)。
+ * 封装 ChatbotyClient(发证+连网关传输), 把 wire 事件/结果映射成实体类(Message/Contact/Room/Friendship),
+ * 对外暴露 typed 事件与便捷 API。这是 chatboty 全生态框架的核心。
+ */
+import { ChatbotyClient, type ChatbotyClientOptions } from './client.js'
+import {
+  type BotApi, type Sayable, type MessagePayload, type ContactPayload, type ContactQueryFilter,
+  toMessageType, isRoomId,
+} from './types.js'
+import { Message } from './entity/message.js'
+import { Contact } from './entity/contact.js'
+import { Room } from './entity/room.js'
+import { Friendship } from './entity/friendship.js'
+
+export type ChatbotyOptions = ChatbotyClientOptions
+
+type Listener = (...args: any[]) => void
+
+export class Chatboty implements BotApi {
+  private readonly client: ChatbotyClient
+  private readonly listeners = new Map<string, Set<Listener>>()
+  private _self?: Contact
+
+  constructor (options: ChatbotyOptions) {
+    this.client = new ChatbotyClient(options)
+  }
+
+  /** 该接入授权的探针实例 id。 */
+  get accountId (): string | undefined { return this.client.account }
+
+  /** 当前登录者(self)。start 后异步热身; 未就绪时 undefined(用 {@link currentUser} 主动拉取)。 */
+  get self (): Contact | undefined { return this._self }
+
+  async start (): Promise<void> {
+    this.wire()
+    await this.client.start()
+    this.emit('ready')
+    // 热身 self(供 message.mentionSelf/self 判定); 失败不致命(未登录时拉不到)。
+    void this.currentUser().catch(() => undefined)
+  }
+
+  async stop (): Promise<void> { this.client.stop(); this.emit('stop') }
+
+  /* ---------------- 事件 ---------------- */
+  on (event: 'message', l: (m: Message) => void): this
+  on (event: 'friendship', l: (f: Friendship) => void): this
+  on (event: 'room-join' | 'room-leave', l: (p: { room: Room, contactList: Contact[], idList: string[], timestamp?: number }) => void): this
+  on (event: 'room-topic', l: (p: { room: Room, topic?: string, oldTopic?: string, timestamp?: number }) => void): this
+  on (event: 'login', l: (self?: any) => void): this
+  on (event: 'scan', l: (p: { qrcode?: string, status?: any }) => void): this
+  // 登录阶段(扫码/验证码全流程): phase = scan|scanned|need-verify|verifying|verify-ok|verify-fail|online...
+  on (event: 'login-phase', l: (p: { phase: string, label?: string }) => void): this
+  // 探针/代理侧错误信号(不中断运行, 仅上报): { error }。
+  on (event: 'error', l: (p: { error: string }) => void): this
+  // 探针心跳(~30s 一次), 供上层做存活/掉线判定: { state }。
+  on (event: 'heartbeat', l: (p: { state?: string }) => void): this
+  on (event: 'logout' | 'ready' | 'stop' | 'disconnected', l: () => void): this
+  on (event: string, l: Listener): this {
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set())
+    this.listeners.get(event)!.add(l)
+    return this
+  }
+
+  private emit (event: string, ...args: any[]): void {
+    this.listeners.get(event)?.forEach((l) => { try { l(...args) } catch { /* 隔离回调异常 */ } })
+  }
+
+  private wire (): void {
+    this.client.on('message', (w) => this.emit('message', this.toMessage(w)))
+    this.client.on('room-join', (w) => this.emit('room-join', this.toMemberEvent(w, w.inviteeIdList, w.inviteeList)))
+    this.client.on('room-leave', (w) => this.emit('room-leave', this.toMemberEvent(w, w.removeeIdList, w.removeeList)))
+    this.client.on('room-topic', (w) => this.emit('room-topic', {
+      room: new Room(this, { id: w.roomId, topic: w.topic }), topic: w.topic, oldTopic: w.oldTopic, timestamp: w.timestamp,
+    }))
+    this.client.on('friendship', (w) => this.emit('friendship', this.toFriendship(w)))
+    this.client.on('login', (w) => this.emit('login', w.self))
+    this.client.on('logout', () => { this._self = undefined; this.emit('logout') })
+    this.client.on('scan', (w) => this.emit('scan', { qrcode: w.qrcode, status: w.status }))
+    this.client.on('login-phase', (w) => this.emit('login-phase', { phase: w.phase, label: w.label }))
+    this.client.on('disconnected', () => this.emit('disconnected'))
+    this.client.on('error', (w) => this.emit('error', { error: w.error }))
+    this.client.on('heartbeat', (w) => this.emit('heartbeat', { state: w.state }))
+  }
+
+  /* ---------------- wire → 实体 ---------------- */
+  private toContactPayload (u: any): ContactPayload {
+    return {
+      id: u.userId ?? u.id, name: u.name, alias: u.alias, avatar: u.avatar,
+      phone: u.phone, title: u.title, corpId: u.corpId, unionId: u.unionId, conversationId: u.conversationId,
+    }
+  }
+
+  private toMessage (w: any): Message {
+    const conv = w.conversationId
+    const room = isRoomId(conv)
+    const talker: ContactPayload | undefined = w.talkerUser
+      ? this.toContactPayload(w.talkerUser)
+      : (w.talkerId ? { id: w.talkerId, name: w.talker } : undefined)
+    const payload: MessagePayload = {
+      id: w.msgId,
+      type: toMessageType(w.type, w.typeRaw),
+      text: w.text,
+      talkerId: talker?.id ?? w.talkerId,
+      roomId: room ? conv : undefined,
+      conversationId: conv,
+      timestamp: w.timestamp,
+      self: !!w.self,
+      talker,
+      file: w.file ?? null,
+      miniProgram: w.miniProgram ?? null,
+      urlLink: w.urlLink ?? null,
+    }
+    return new Message(this, payload)
+  }
+
+  private toMemberEvent (w: any, idList: string[], userList: any[]) {
+    return {
+      room: new Room(this, { id: w.roomId }),
+      idList: idList || [],
+      contactList: (userList || []).filter(Boolean).map((u: any) => new Contact(this, this.toContactPayload(u))),
+      timestamp: w.timestamp,
+    }
+  }
+
+  private toFriendship (w: any): Friendship {
+    const kind = w.kind === 'add' ? 'add' : w.kind === 'delete' ? 'delete' : w.kind === 'receive' ? 'receive' : 'confirm'
+    return new Friendship(this, {
+      contactId: w.vid || w.contactId,
+      contact: w.user ? this.toContactPayload(w.user) : undefined,
+      kind,
+      hello: w.hello,
+    })
+  }
+
+  /* ---------------- BotApi(实体动作底座) ---------------- */
+  async command (cmd: string, args: Record<string, any> = {}): Promise<any> {
+    return this.client.command(cmd, args)
+  }
+
+  /** 登录扫码后若企微要求验证码, 用此提交(配合 on('login-phase') 的 need-verify 阶段)。 */
+  async enterVerifyCode (code: string): Promise<any> {
+    return this.client.command('enterVerifyCode', { code })
+  }
+
+  /** BotApi: 当前登录者 payload(供实体做本机 self 判定, 如 Message.mentionSelf)。 */
+  selfContact (): ContactPayload | undefined { return this._self?.payload }
+
+  /**
+   * 干净登出(回到扫码页, 不重启探针进程)。冷调 LoginServiceImpl 登出链,
+   * 完成后探针会推 'logout' 事件并转为出新二维码的扫码态。
+   */
+  async logout (): Promise<void> {
+    await this.command('logout')
+    this._self = undefined
+  }
+
+  /**
+   * 拉取当前登录者(self)为完整 Contact, 并缓存到 {@link self}。
+   * @returns 当前登录者 Contact; 未登录/会话未加载时 undefined。
+   */
+  async currentUser (): Promise<Contact | undefined> {
+    let r: any
+    try { r = await this.command('self') } catch { return this._self }
+    if (!r || !(r.userId || r.id)) return this._self
+    this._self = new Contact(this, this.toContactPayload(r))
+    return this._self
+  }
+
+  async sayTo (conversationId: string, sayable: Sayable): Promise<any> {
+    if (typeof sayable === 'string') return this.client.command('sendText', { conversationId, text: sayable })
+    if ('image' in sayable) return this.client.command('sendImage', { conversationId, url: sayable.image })
+    if ('file' in sayable) return this.client.command('sendFile', { conversationId, url: sayable.file })
+    if ('url' in sayable) return this.client.command('sendUrlLink', { conversationId, url: sayable.url, title: sayable.title, desc: sayable.description, thumb: sayable.thumbUrl })
+    if ('miniProgram' in sayable) return this.client.command('sendWeAppCard', { conversationId, ...sayable.miniProgram })
+    throw new Error('不支持的发送内容')
+  }
+
+  /* ---------------- 查询/工厂 ---------------- */
+  async roomList (): Promise<Room[]> {
+    const r = await this.command('roomList')
+    const arr = (r && (r.rooms || r.list || (Array.isArray(r) ? r : []))) || []
+    return arr.map((x: any) => new Room(this, { id: x.conversationId || x.id, topic: x.name || x.topic }))
+  }
+
+  async contactList (): Promise<Contact[]> {
+    const r = await this.command('contactList')
+    const arr = (r && (r.contacts || r.list || (Array.isArray(r) ? r : []))) || []
+    return arr.map((u: any) => new Contact(this, this.toContactPayload(u)))
+  }
+
+  /**
+   * 在【已加载的全量通讯录】按条件查找联系人(本地过滤, 非服务端搜陌生人)。
+   * @param query 关键词字符串(匹配 name/alias/phone/title/vid 子串), 或 { name?, alias?, id? } 精确匹配。
+   * @returns 命中的 Contact 列表(可能为空)。
+   */
+  async contactFindAll (query?: ContactQueryFilter): Promise<Contact[]> {
+    const keyword = typeof query === 'string'
+      ? query
+      : (query?.name ?? query?.alias ?? query?.id ?? '')
+    const r = await this.command('contactSearch', { keyword })
+    const arr = (r && (r.contacts || r.list || (Array.isArray(r) ? r : []))) || []
+    let list = arr.map((u: any) => new Contact(this, this.toContactPayload(u)))
+    if (query && typeof query !== 'string') {   // 对象条件: 在子串命中基础上再做精确收窄
+      if (query.id) list = list.filter((c: Contact) => c.id() === query.id)
+      if (query.alias) list = list.filter((c: Contact) => c.alias() === query.alias)
+      if (query.name) list = list.filter((c: Contact) => c.name() === query.name)
+    }
+    return list
+  }
+
+  /**
+   * 查找单个联系人(取 {@link contactFindAll} 第一个命中)。
+   * @param query 关键词字符串或 { name?, alias?, id? }。
+   * @returns 命中的第一个 Contact; 无则 undefined。
+   */
+  async contactFind (query: ContactQueryFilter): Promise<Contact | undefined> {
+    const all = await this.contactFindAll(query)
+    return all[0]
+  }
+
+  /** 建群(成员 vid 列表)。 */
+  async roomCreate (memberIdList: string[], topic?: string): Promise<Room | undefined> {
+    const r = await this.command('roomCreate', { userList: memberIdList, topic })
+    const id = r && (r.conversationId || r.roomId || r.id)
+    return id ? new Room(this, { id, topic }) : undefined
+  }
+}

package/src/client.ts

@@ -0,0 +1,310 @@
+/**
+ * ChatbotyClient — P1 身份主线的"薄壳"接入客户端。
+ *
+ * 自研、零外部框架依赖(仅 ws)。职责:
+ *   1) 服务发现+发证: 用长期订阅 token 调售卖端 /api/access/grant 换取
+ *      {endpoint(网关地址), accessToken(短TTL接入JWT), accountId}。
+ *   2) 连网关: endpoint + `/client?token=<accessToken>`; 网关公钥验签后按 accountId 路由+隔离。
+ *   3) 收发: 命令请求/回包关联(带超时) + 事件订阅(message/room-join/room-leave/room-topic/friendship/...)。
+ *
+ * 这是 P2 自研全生态框架(Contact/Room/Message/插件)的传输地基。
+ */
+import WebSocket from 'ws'
+
+export interface ChatbotyClientOptions {
+  /**
+   * 长期订阅 token(cbt_...), 由售卖端签发给用户。
+   * 直连/发证模式(fallback)必填; 使用服务发现(serviceToken+serviceAuthority)时可省略。
+   */
+  token?: string
+  /** 售卖端基址(发证/服务发现)。默认 http://127.0.0.1:8080 */
+  atlasUrl?: string
+  /** 命令回包超时(ms)。默认 25000 */
+  timeoutMs?: number
+  /** 调试直连: 跳过发证, 直接给网关地址 */
+  endpoint?: string
+  /** 调试直连: 直接给接入 JWT(配合 endpoint) */
+  accessToken?: string
+  /**
+   * 【推荐】服务发现: 长期服务令牌。配合 serviceAuthority 使用。
+   * SDK 会带 `Authorization: Bearer <serviceToken>` POST 到 serviceAuthority,
+   * 换取 { endpoint, accessToken(短TTL RS256), expiresIn }, 用 accessToken 连网关(?access=)。
+   */
+  serviceToken?: string
+  /**
+   * 【推荐】服务发现端点(权威 URL)。给定时优先走服务发现流程(而非 token 直连/发证)。
+   */
+  serviceAuthority?: string
+  /** accessToken 过期前提前刷新的秒数。默认 30 */
+  refreshSkewSec?: number
+}
+
+export type EventHandler = (payload: Record<string, any>) => void
+
+interface Pending {
+  resolve: (v: any) => void
+  reject: (e: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export class ChatbotyClient {
+  private readonly opts: Required<Pick<ChatbotyClientOptions, 'token' | 'atlasUrl' | 'timeoutMs' | 'refreshSkewSec'>> &
+    ChatbotyClientOptions
+  private ws?: WebSocket
+  private accountId?: string
+  private reqId = 1
+  private readonly pending = new Map<number, Pending>()
+  private readonly handlers = new Map<string, Set<EventHandler>>()
+  private readyResolve?: () => void
+  // —— 服务发现(discovery)模式状态 ——
+  private readonly discoveryMode: boolean
+  private stopped = false
+  private autoReconnect = false
+  private currentAccessToken?: string
+  private currentEndpoint?: string
+  private refreshTimer?: ReturnType<typeof setTimeout>
+  private reconnectTimer?: ReturnType<typeof setTimeout>
+  private reconnectAttempt = 0
+
+  constructor (options: ChatbotyClientOptions) {
+    const hasDiscovery = !!(options && options.serviceToken && options.serviceAuthority)
+    const hasDirect = !!(options && (options.token || (options.endpoint && options.accessToken)))
+    if (!hasDiscovery && !hasDirect) {
+      throw new Error('ChatbotyClient: 需提供 { serviceToken, serviceAuthority } 或 { token, endpoint }')
+    }
+    this.discoveryMode = hasDiscovery
+    this.opts = {
+      atlasUrl: 'http://127.0.0.1:8080',
+      timeoutMs: 25000,
+      refreshSkewSec: 30,
+      token: '',
+      ...options,
+    }
+  }
+
+  /** 该接入授权的探针实例 id(发证后可知)。 */
+  get account (): string | undefined { return this.accountId }
+
+  /** 服务发现 + 连接网关。resolve 于网关 gateway-ready。 */
+  async start (): Promise<void> {
+    this.stopped = false
+    // 【推荐】服务发现流程: serviceToken/serviceAuthority → 短TTL accessToken → 连网关(?access=) + 到期前刷新。
+    if (this.discoveryMode) {
+      const d = await this.discover()
+      this.applyDiscovery(d)
+      await this.connect(d.endpoint, d.accessToken, 'access')
+      return
+    }
+    // 直连/发证 fallback: 保持既有 `?token=<accessToken>` 行为不变。
+    let endpoint = this.opts.endpoint
+    let accessToken = this.opts.accessToken
+    if (!endpoint || !accessToken) {
+      const g = await this.grant()
+      endpoint = g.endpoint
+      accessToken = g.accessToken
+      this.accountId = g.accountId
+    }
+    await this.connect(endpoint!, accessToken!)
+  }
+
+  /**
+   * 服务发现: POST serviceAuthority(带 Bearer serviceToken)换取接入凭据。
+   * 期望响应 { endpoint, accessToken, expiresIn }(可选 accountId/seatId)。
+   */
+  private async discover (): Promise<{ endpoint: string, accessToken: string, expiresIn: number, accountId?: string }> {
+    const url = this.opts.serviceAuthority!
+    const httpFetch: (u: string, init?: any) => Promise<any> = (globalThis as any).fetch
+    if (!httpFetch) throw new Error('运行环境无 fetch(需 Node>=18)')
+    const resp = await httpFetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${this.opts.serviceToken ?? ''}`,
+      },
+      body: JSON.stringify({ token: this.opts.serviceToken }),
+    })
+    if (!resp.ok) {
+      const txt = await resp.text().catch(() => '')
+      throw new Error(`服务发现失败 ${resp.status}: ${txt.slice(0, 200)}`)
+    }
+    const j: any = await resp.json()
+    if (!j.endpoint || !j.accessToken) throw new Error('服务发现响应缺少 endpoint/accessToken')
+    const expiresIn = Number(j.expiresIn) > 0 ? Number(j.expiresIn) : 300
+    return { endpoint: j.endpoint, accessToken: j.accessToken, expiresIn, accountId: j.accountId ?? j.seatId }
+  }
+
+  /** 应用一次发现结果: 缓存 endpoint/accessToken, 并安排到期前刷新。 */
+  private applyDiscovery (d: { endpoint: string, accessToken: string, expiresIn: number, accountId?: string }): void {
+    this.currentEndpoint = d.endpoint
+    this.currentAccessToken = d.accessToken
+    if (d.accountId) this.accountId = d.accountId
+    this.scheduleRefresh(d.expiresIn)
+  }
+
+  /** 在 accessToken 过期前(提前 refreshSkewSec)重新发现, 刷新缓存的 accessToken。 */
+  private scheduleRefresh (expiresIn: number): void {
+    if (this.refreshTimer) clearTimeout(this.refreshTimer)
+    if (this.stopped) return
+    const delayMs = Math.max(1000, (expiresIn - this.opts.refreshSkewSec) * 1000)
+    this.refreshTimer = setTimeout(() => { void this.refresh(0) }, delayMs)
+  }
+
+  /** 刷新 accessToken; 失败按指数退避重试(封顶 30s)。刷新后的 token 供下次(重)连使用。 */
+  private async refresh (attempt: number): Promise<void> {
+    if (this.stopped) return
+    try {
+      const d = await this.discover()
+      this.applyDiscovery(d) // 内部会重新 scheduleRefresh
+    } catch {
+      if (this.stopped) return
+      const backoff = Math.min(30000, 1000 * 2 ** attempt)
+      if (this.refreshTimer) clearTimeout(this.refreshTimer)
+      this.refreshTimer = setTimeout(() => { void this.refresh(attempt + 1) }, backoff)
+    }
+  }
+
+  /** discovery 模式下断线自愈: 重新发现取新 accessToken 后重连; 失败指数退避。 */
+  private scheduleReconnect (): void {
+    if (this.stopped || this.reconnectTimer) return
+    const backoff = Math.min(30000, 1000 * 2 ** this.reconnectAttempt)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined
+      void this.reconnect()
+    }, backoff)
+  }
+
+  private async reconnect (): Promise<void> {
+    if (this.stopped) return
+    try {
+      // 优先用刷新循环维护的最新 accessToken(“on reconnect use the fresh one”);
+      // 无缓存(如刚被失败清空)则强制重新发现。
+      let endpoint = this.currentEndpoint
+      let accessToken = this.currentAccessToken
+      if (!endpoint || !accessToken) {
+        const d = await this.discover()
+        this.applyDiscovery(d)
+        endpoint = d.endpoint
+        accessToken = d.accessToken
+      }
+      await this.connect(endpoint, accessToken, 'access')
+      this.reconnectAttempt = 0
+    } catch {
+      if (this.stopped) return
+      this.reconnectAttempt++
+      // 缓存 token 可能已失效, 清掉 → 下次重连强制重新发现。
+      this.currentAccessToken = undefined
+      this.currentEndpoint = undefined
+      this.scheduleReconnect()
+    }
+  }
+
+  /** 用订阅 token 向售卖端换接入 JWT(发证/服务发现)。 */
+  private async grant (): Promise<{ endpoint: string, accessToken: string, accountId: string }> {
+    const url = this.opts.atlasUrl.replace(/\/$/, '') + '/api/access/grant'
+    const httpFetch: (u: string, init?: any) => Promise<any> = (globalThis as any).fetch
+    if (!httpFetch) throw new Error('运行环境无 fetch(需 Node>=18)')
+    const resp = await httpFetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: this.opts.token }),
+    })
+    if (!resp.ok) {
+      const txt = await resp.text().catch(() => '')
+      throw new Error(`发证失败 ${resp.status}: ${txt.slice(0, 200)}`)
+    }
+    const j: any = await resp.json()
+    if (!j.endpoint || !j.accessToken) throw new Error('发证响应缺少 endpoint/accessToken')
+    return { endpoint: j.endpoint, accessToken: j.accessToken, accountId: j.accountId }
+  }
+
+  /**
+   * 连接网关。queryKey='token' 为直连/发证 fallback(既有行为不变);
+   * queryKey='access' 为服务发现流程(网关验 RS256 accessToken → seatId)。
+   */
+  private connect (endpoint: string, accessToken: string, queryKey: 'token' | 'access' = 'token'): Promise<void> {
+    const sep = endpoint.includes('/client') ? '' : '/client'
+    const wsUrl = `${endpoint}${sep}?${queryKey}=${encodeURIComponent(accessToken)}`
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(wsUrl)
+      this.ws = ws
+      this.readyResolve = resolve
+      const onErr = (e: Error) => reject(new Error('连接网关失败: ' + e.message))
+      ws.once('error', onErr)
+      ws.on('open', () => {
+        ws.removeListener('error', onErr)
+        // 首次成功连上后才开启断线自愈, 避免首连失败时把错误吞进后台重连。
+        if (queryKey === 'access') this.autoReconnect = true
+      })
+      ws.on('message', (raw: WebSocket.RawData) => this.onFrame(raw))
+      ws.on('close', () => {
+        if (this.ws === ws) this.ws = undefined
+        this.emit('disconnected', {})
+        if (this.autoReconnect && !this.stopped) this.scheduleReconnect()
+      })
+    })
+  }
+
+  private onFrame (raw: WebSocket.RawData): void {
+    let m: any
+    try { m = JSON.parse(raw.toString()) } catch { return }
+    if (typeof m.id === 'number' && this.pending.has(m.id)) {  // 命令回包
+      const p = this.pending.get(m.id)!
+      this.pending.delete(m.id)
+      clearTimeout(p.timer)
+      if (m.ok) p.resolve(m.result)
+      else p.reject(new Error(m.error || 'command failed'))
+      return
+    }
+    if (m.ev) {                                                // 事件
+      if (m.ev === 'gateway-ready') {
+        if (!this.accountId && Array.isArray(m.accounts) && m.accounts.length) this.accountId = m.accounts[0]
+        if (this.readyResolve) { this.readyResolve(); this.readyResolve = undefined }
+      }
+      this.emit(m.ev, m)
+    }
+  }
+
+  /** 订阅事件: message / room-join / room-leave / room-topic / friendship / login / logout / disconnected ... */
+  on (event: string, handler: EventHandler): this {
+    if (!this.handlers.has(event)) this.handlers.set(event, new Set())
+    this.handlers.get(event)!.add(handler)
+    return this
+  }
+
+  off (event: string, handler: EventHandler): this {
+    this.handlers.get(event)?.delete(handler)
+    return this
+  }
+
+  private emit (event: string, payload: Record<string, any>): void {
+    this.handlers.get(event)?.forEach((h) => { try { h(payload) } catch { /* 隔离回调异常 */ } })
+  }
+
+  /** 通用命令: 发到网关 → 路由到本接入授权的探针。 */
+  command (cmd: string, args: Record<string, any> = {}): Promise<any> {
+    const ws = this.ws
+    if (!ws || ws.readyState !== WebSocket.OPEN) return Promise.reject(new Error('未连接'))
+    const id = this.reqId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pending.has(id)) { this.pending.delete(id); reject(new Error('命令超时: ' + cmd)) }
+      }, this.opts.timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      ws.send(JSON.stringify({ id, accountId: this.accountId, cmd, ...args }))
+    })
+  }
+
+  // —— 便捷方法(P2 框架前的最小集; 完整 Contact/Room/Message 对象模型见 P2) ——
+  roomList (): Promise<any> { return this.command('roomList') }
+  contactList (limit = 0): Promise<any> { return this.command('contactList', { limit }) }
+  say (conversationId: string, text: string): Promise<any> { return this.command('sendText', { conversationId, text }) }
+
+  /** 断开。停止刷新/重连定时器。 */
+  stop (): void {
+    this.stopped = true
+    this.autoReconnect = false
+    if (this.refreshTimer) { clearTimeout(this.refreshTimer); this.refreshTimer = undefined }
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = undefined }
+    try { this.ws?.close() } catch { /* noop */ }
+  }
+}

package/src/entity/contact.ts

@@ -0,0 +1,32 @@
+import type { BotApi, ContactPayload, Sayable } from '../types.js'
+import { ContactType } from '../types.js'
+
+/** 联系人实体(含外部客户)。 */
+export class Contact {
+  constructor (private readonly bot: BotApi, readonly payload: ContactPayload) {}
+
+  id (): string { return this.payload.id }
+  name (): string { return this.payload.name ?? '' }
+  alias (): string | undefined { return this.payload.alias }
+  avatar (): string | undefined { return this.payload.avatar }
+  phone (): string | undefined { return this.payload.phone }
+  title (): string | undefined { return this.payload.title }
+
+  /**
+   * 联系人类别。企微通讯录成员/外部客户都是真人 → 默认 {@link ContactType.Individual}。
+   * (企微不存在微信式"公众号/服务号", 且探针未采集"应用号/机器人"标志, 故不臆造 Official。)
+   */
+  type (): ContactType { return this.payload.type ?? ContactType.Individual }
+
+  /** 单聊会话 id(发消息目标)。 */
+  conversationId (): string | undefined { return this.payload.conversationId }
+
+  /** 给该联系人发消息(单聊)。 */
+  async say (sayable: Sayable): Promise<any> {
+    const conv = this.payload.conversationId
+    if (!conv) throw new Error(`Contact ${this.id()} 无单聊会话 id, 无法发送`)
+    return this.bot.sayTo(conv, sayable)
+  }
+
+  toString (): string { return `Contact<${this.name() || this.id()}>` }
+}

package/src/entity/friendship.ts

@@ -0,0 +1,16 @@
+import type { BotApi, FriendshipPayload, FriendshipKind } from '../types.js'
+import { Contact } from './contact.js'
+
+/** 好友关系事件实体。 */
+export class Friendship {
+  constructor (private readonly bot: BotApi, readonly payload: FriendshipPayload) {}
+
+  kind (): FriendshipKind { return this.payload.kind }
+  hello (): string | undefined { return this.payload.hello }
+
+  contact (): Contact {
+    return new Contact(this.bot, this.payload.contact ?? { id: this.payload.contactId })
+  }
+
+  toString (): string { return `Friendship<${this.kind()}:${this.payload.contactId}>` }
+}