@miphamai/cli 0.53.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/agent-registry.ts

@@ -10,9 +10,12 @@ interface FrontmatterResult {
 }
 
 function parseFrontmatter(raw: string): FrontmatterResult {
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+  // Strip a leading UTF-8 BOM — otherwise `^---` never matches and a
+  // BOM-prefixed file is silently treated as body text (effectively ignored).
+  const src = raw.replace(/^\uFEFF/, '')
+  const match = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
   if (!match) {
-    return { data: {}, content: raw }
+    return { data: {}, content: src }
   }
   return {
     data: parseYaml(match[1] || '') as Record<string, unknown>,

package/src/agent/cross-session/discovery.ts

@@ -9,7 +9,7 @@ import {
 } from 'node:fs'
 import { join, basename } from 'node:path'
 import { homedir, hostname } from 'node:os'
-import type { SessionInfo } from '../../shared/types'
+import type { SessionInfo, CrossSessionInbound } from '../../shared/types'
 
 const MIPHAM_HOME = join(homedir(), '.mipham')
 const ACTIVE_SESSIONS_DIR = join(MIPHAM_HOME, '.active-sessions')
@@ -97,6 +97,7 @@ export function createSessionInfo(
   cwd?: string,
   provider?: string,
   model?: string,
+  crossSessionInbound?: CrossSessionInbound,
 ): SessionInfo {
   return {
     id: sessionId,
@@ -107,6 +108,7 @@ export function createSessionInfo(
     cwd,
     provider,
     model,
+    crossSessionInbound,
   }
 }
 

package/src/agent/message-router.ts

@@ -90,6 +90,16 @@ export class MessageRouter {
     }
     const targetSession = resolution.session!
 
+    // Recipient refuses inbound messages — report "refused" instead of a silent
+    // success so the sender knows the message was not delivered.
+    if (targetSession.crossSessionInbound === 'deny') {
+      return {
+        success: false,
+        routedTo: 'inbox',
+        error: `Session "${targetSession.name}" refuses inbound messages.`,
+      }
+    }
+
     // Get sender info — resolve the human-readable name when the sender is a
     // registered session, else fall back to the raw id (e.g. non-session senders).
     const senderName = discoverSessions().find((s) => s.id === from)?.name ?? from

package/src/agent-view/agent-view-manager.ts

@@ -250,17 +250,26 @@ export class AgentViewManager {
     return true
   }
 
+  /**
+   * Permanently remove a single session (any status). Returns true if found.
+   */
+  remove(id: string): boolean {
+    if (!this.sessions.has(id)) return false
+    this.sessions.delete(id)
+    this.sessionOrder = this.sessionOrder.filter((oid) => oid !== id)
+    return true
+  }
+
   /**
    * Remove all completed and failed sessions (cleanup).
    */
   prune(): number {
+    const terminalIds = Array.from(this.sessions.entries())
+      .filter(([, session]) => session.status === 'completed' || session.status === 'failed')
+      .map(([id]) => id)
     let removed = 0
-    for (const [id, session] of this.sessions) {
-      if (session.status === 'completed' || session.status === 'failed') {
-        this.sessions.delete(id)
-        this.sessionOrder = this.sessionOrder.filter((oid) => oid !== id)
-        removed++
-      }
+    for (const id of terminalIds) {
+      if (this.remove(id)) removed++
     }
     return removed
   }

package/src/agent-view/dashboard.tsx

@@ -32,6 +32,8 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
   const [peekingSessionId, setPeekingSessionId] = useState<string | null>(null)
   const [groupBy, setGroupBy] = useState<'status' | 'directory'>('status')
   const [feedback, setFeedback] = useState<string | null>(null)
+  // Bump to force flatList recompute after a session is removed (list membership change).
+  const [version, setVersion] = useState(0)
 
   // Flash a brief feedback message that auto-clears
   const showFeedback = useCallback((msg: string) => {
@@ -87,7 +89,7 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
     }
 
     return result
-  }, [manager, groupBy])
+  }, [manager, groupBy, version])
 
   // Flatten sessions only for navigation (skip headers)
   const sessionsOnly = useMemo(
@@ -140,6 +142,22 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
       return
     }
 
+    // Ctrl+X — permanently remove the selected session
+    if (key.ctrl && input === 'x') {
+      if (sessionsOnly.length === 0) {
+        showFeedback('No sessions to remove')
+        return
+      }
+      const current = sessionsOnly[selectedIndex]
+      if (!current) return
+      manager.remove(current.session.id)
+      setPeekingSessionId(null)
+      setSelectedIndex((prev) => Math.max(0, Math.min(prev, sessionsOnly.length - 2)))
+      setVersion((v) => v + 1)
+      showFeedback(`Removed ${current.session.title || current.session.id}`)
+      return
+    }
+
     if (input === 'j') {
       if (sessionsOnly.length === 0) {
         showFeedback('No sessions to navigate — spawn a background agent first')
@@ -223,7 +241,8 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
         </Box>
         <Box>
           <Text dimColor>
-            j/k navigate · Space peek · Enter attach · Ctrl+T group · Ctrl+R rename · Esc back
+            j/k navigate · Space peek · Enter attach · Ctrl+T group · Ctrl+R rename · Ctrl+X remove
+            · Esc back
           </Text>
         </Box>
       </Box>

package/src/commands/cd-suggest.ts

@@ -0,0 +1,35 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { dirname, basename, join } from 'node:path'
+
+/**
+ * Suggest existing directories that match a partial `/cd` target.
+ *
+ * `path` must already be tilde-expanded and resolved by the caller (`/cd`
+ * passes the `resolve()`d target). Given a path that does not (fully) exist,
+ * walk up to its nearest existing ancestor and return the subdirectories whose
+ * names prefix-match the trailing segment. Files and non-matching entries are
+ * excluded. Returns `[]` when the path already exists or nothing matches.
+ */
+export function suggestDirectories(path: string): string[] {
+  if (existsSync(path)) return []
+
+  let ancestor = dirname(path)
+  while (!existsSync(ancestor)) {
+    const parent = dirname(ancestor)
+    if (parent === ancestor) return [] // hit filesystem root
+    ancestor = parent
+  }
+
+  const prefix = basename(path)
+  let entries
+  try {
+    entries = readdirSync(ancestor, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  return entries
+    .filter((e) => e.isDirectory() && e.name.startsWith(prefix))
+    .map((e) => join(ancestor, e.name))
+    .sort()
+}

package/src/commands/project.ts

@@ -7,6 +7,7 @@
  */
 import type { CommandHandler, CommandContext, CommandResult } from '../ui/commands.js'
 import { getWorkspaceTrust } from '../core/workspace-trust'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 
 export {
   initCmd,
@@ -20,7 +21,7 @@ export {
 }
 
 const initCmd: CommandHandler = async (ctx) => {
-  const { existsSync, mkdirSync, writeFileSync } = await import('node:fs')
+  const { existsSync, mkdirSync } = await import('node:fs')
   const { join } = await import('node:path')
   const { homedir } = await import('node:os')
 
@@ -78,7 +79,7 @@ providers:
 ${providerYaml}
 `
 
-    writeFileSync(userConfigPath, configContent, 'utf-8')
+    atomicWriteFileSync(userConfigPath, configContent)
     return {
       content: `✅ Mipham Code initialized!
 
@@ -434,7 +435,7 @@ permission: ask
 providers:
 ${providerYaml}
 `
-    writeFileSync(configPath, defaultConfig, 'utf-8')
+    atomicWriteFileSync(configPath, defaultConfig)
     created.push('.mipham/config.yml')
   } else {
     skipped.push('.mipham/config.yml (already exists)')

package/src/config/loader.ts

@@ -6,11 +6,11 @@ import {
   readdirSync,
   unlinkSync,
   chmodSync,
-  writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import type {
   MiphamConfig,
   ProviderConfig,
@@ -533,7 +533,7 @@ export function saveProviderApiKey(providerId: string, apiKey: string): boolean
     doc.providers = providers
 
     // Write back
-    writeFileSync(configPath, stringifyYaml(doc), { encoding: 'utf-8', mode: 0o600 })
+    atomicWriteFileSync(configPath, stringifyYaml(doc), { mode: 0o600 })
     return true
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err)

package/src/core/claude-md-audit.ts

@@ -0,0 +1,64 @@
+/**
+ * CLAUDE.md audit — find sections whose content the model can infer from the
+ * codebase itself (directory structure, tech stack, dependencies, commit
+ * history, project/submodule catalogs, test counts). Such sections burn
+ * context tokens every session and go stale as the code changes; they are
+ * candidates for the `prompt-exclude` frontmatter.
+ */
+
+export type DerivableReason =
+  'structure' | 'tech-stack' | 'dependencies' | 'commits' | 'catalog' | 'tests'
+
+export interface DerivableSection {
+  heading: string
+  reason: DerivableReason
+}
+
+/** Human-readable hint for each derivable category (diagnostic output). */
+export const DERIVABLE_HINTS: Record<DerivableReason, string> = {
+  structure: 'directory/file structure — inferable from the repo itself',
+  'tech-stack': 'tech stack — inferable from package.json / config',
+  dependencies: 'dependencies — inferable from package.json',
+  commits: 'commit/revision history — inferable from git log',
+  catalog: 'project/submodule catalog — inferable from .gitmodules / directories',
+  tests: 'test counts — inferable from running the suite',
+}
+
+const PATTERNS: Array<{ pattern: RegExp; reason: DerivableReason }> = [
+  {
+    pattern:
+      /目录结构|项目结构|文件结构|directory structure|project structure|file structure|repo structure|monorepo/i,
+    reason: 'structure',
+  },
+  { pattern: /技术栈|tech\s*stack|technology\s*stack/i, reason: 'tech-stack' },
+  { pattern: /依赖关系|依赖清单|dependencies/i, reason: 'dependencies' },
+  {
+    pattern: /最近提交|recent\s*commit|修订历史|revision\s*history|changelog|变更记录|变更历史/i,
+    reason: 'commits',
+  },
+  {
+    pattern: /项目一览|项目清单|项目列表|子模块清单|submodule\s*(list|catalog)|catalog/i,
+    reason: 'catalog',
+  },
+  { pattern: /测试矩阵|test\s*matrix|测试覆盖|coverage/i, reason: 'tests' },
+]
+
+/**
+ * Return `##`/`###` headings whose title matches a derivable-content pattern,
+ * in document order. Headings without a match are ignored.
+ */
+export function findDerivableSections(content: string): DerivableSection[] {
+  const found: DerivableSection[] = []
+  for (const line of content.split('\n')) {
+    const m = line.match(/^(#{2,3})\s+(.+?)\s*$/)
+    if (!m) continue
+    const heading = m[2]!.trim()
+    for (const { pattern, reason } of PATTERNS) {
+      if (pattern.test(heading)) {
+        found.push({ heading, reason })
+        break
+      }
+    }
+  }
+  return found
+}

package/src/core/instructions.ts

@@ -10,9 +10,12 @@ interface FrontmatterResult {
 }
 
 function parseFrontmatter(raw: string): FrontmatterResult {
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
+  // Strip a leading UTF-8 BOM — otherwise `^---` never matches and a
+  // BOM-prefixed file is silently treated as body text (effectively ignored).
+  const src = raw.replace(/^\uFEFF/, '')
+  const match = src.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
   if (!match) {
-    return { data: {}, content: raw }
+    return { data: {}, content: src }
   }
   return {
     data: parseYaml(match[1] || '') as Record<string, unknown>,
@@ -101,6 +104,16 @@ export class InstructionsLoader {
       parts.push(this.buildPermissionContext(permissionMode))
     }
 
+    // 开场克制：寒暄只回一句短问候，不上能力清单（避免把「你好」当「你是谁」处理）
+    parts.push(`## Greeting Restraint
+
+When the user's message is only a greeting or small talk ("hello", "hi",
+"你好", "您好", "在吗", "早上好"), reply with ONE brief, warm line —
+e.g. "你好，我是 Mipham，有什么可以帮你的？" Do NOT introduce yourself,
+list your capabilities/tools/MCP servers, or enumerate what you can do.
+Only describe your capabilities when the user explicitly asks ("你是谁",
+"你能做什么", "what can you do", "introduce yourself").`)
+
     // Inject critical thinking self-check layer (for analysis/comparison tasks)
     parts.push(`## Critical Thinking Self-Check
 

package/src/daemon/backoff.ts

@@ -0,0 +1,4 @@
+/** 指数退避，封顶 30s。三频道（telegram/wecom/dingtalk）重连共享。 */
+export function nextBackoff(currentMs: number): number {
+  return Math.min(currentMs * 2, 30_000)
+}

package/src/daemon/channel-message.ts

@@ -3,7 +3,7 @@ import type { SessionWorker } from './session-worker'
 import type { RateLimiter } from './rate-limiter'
 
 export interface ChannelMessageOptions {
-  channel: string // 'feishu' | 'telegram' | 'wecom'
+  channel: string // 'feishu' | 'telegram' | 'wecom' | 'dingtalk'
   externalId: string // openId / chatId / userId
   text: string
   allowed: Set<string>
@@ -14,11 +14,11 @@ export interface ChannelMessageOptions {
   provider: string
   model: string
   sendText: (externalId: string, text: string) => Promise<void>
-  maxLen: number // 飞书 4000 / Telegram 4096 / 企微 2048
+  maxLen: number // 飞书 4000 / Telegram 4096 / 企微 2048 / 钉钉 2000
   logPrefix: string // '[feishu]' / '[telegram]' / '[wecom]'
 }
 
-/** 三频道共享的消息处理骨架：白名单→限流→会话→processPrompt→回发。 */
+/** 四频道共享的消息处理骨架：白名单→限流→会话→processPrompt→回发。 */
 export async function handleChannelMessage(opts: ChannelMessageOptions): Promise<void> {
   const {
     channel,

package/src/daemon/dingtalk/adapter.ts

@@ -0,0 +1,62 @@
+import type { DingtalkApi } from './api.js'
+import type { DingtalkConfig, DingtalkMessage } from './types.js'
+import type { SessionManager } from '../session-manager'
+import type { SessionWorker } from '../session-worker'
+import type { RateLimiter } from '../rate-limiter'
+import { startDingtalkWs } from './ws-client.js'
+import { handleChannelMessage } from '../channel-message.js'
+
+export interface DingtalkAdapterDeps {
+  sm: SessionManager
+  getOrCreateWorker: (sessionId: string) => SessionWorker | null
+  rateLimiter: RateLimiter
+  cwd: string
+  provider: string
+  model: string
+}
+
+export interface DingtalkAdapter {
+  start(): () => void
+  handleMessage(msg: DingtalkMessage): Promise<void>
+  isAllowed(staffId: string): boolean
+}
+
+export function createDingtalkAdapter(
+  config: DingtalkConfig,
+  api: DingtalkApi,
+  deps: DingtalkAdapterDeps,
+): DingtalkAdapter {
+  const allowed = new Set(config.allowedStaffIds)
+  let stopWs: (() => void) | null = null
+
+  async function handleMessage(msg: DingtalkMessage): Promise<void> {
+    await handleChannelMessage({
+      channel: 'dingtalk',
+      externalId: msg.staffId,
+      text: msg.text,
+      allowed,
+      rateLimiter: deps.rateLimiter,
+      sm: deps.sm,
+      getOrCreateWorker: deps.getOrCreateWorker,
+      cwd: deps.cwd,
+      provider: deps.provider,
+      model: deps.model,
+      // 钉钉回发走每条消息自带的 sessionWebhook（非持久 userId 路由）
+      sendText: async (_staffId, text) => {
+        await api.reply(msg.sessionWebhook, text)
+      },
+      maxLen: 2000,
+      logPrefix: '[dingtalk]',
+    })
+  }
+
+  return {
+    handleMessage,
+    isAllowed: (staffId) => allowed.has(staffId),
+    start() {
+      if (stopWs) return stopWs
+      stopWs = startDingtalkWs(api, handleMessage)
+      return stopWs
+    },
+  }
+}

package/src/daemon/dingtalk/api.ts

@@ -0,0 +1,120 @@
+import type { DingtalkConfig, DingtalkMessage } from './types.js'
+
+const GATEWAY_URL = 'https://api.dingtalk.com/v1.0/gateway/connections/open'
+
+export interface DingtalkApi {
+  register(): Promise<{ endpoint: string; ticket: string }>
+  open(endpoint: string, ticket: string): WebSocket
+  reply(sessionWebhook: string, text: string): Promise<void>
+  parseMessage(frame: unknown): DingtalkMessage | null
+  isPing(frame: unknown): boolean
+  ack(ws: WebSocket, frame: unknown): void
+  pong(ws: WebSocket, frame: unknown): void
+}
+
+/** 回帧信封：code 200 + 回显 headers.messageId。ack 与 pong 共用。 */
+function sendResponse(ws: WebSocket, frame: unknown, data: unknown): void {
+  const f = frame as { headers?: { messageId?: string } }
+  ws.send(
+    JSON.stringify({
+      code: 200,
+      headers: { contentType: 'application/json', messageId: f?.headers?.messageId ?? '' },
+      message: 'OK',
+      data,
+    }),
+  )
+}
+
+/**
+ * 钉钉 Stream Mode 协议 codec。零依赖：HTTP 用裸 fetch（register + 回发），
+ * WebSocket 用 globalThis.WebSocket（Node 22+ / Bun 原生）。ticket 一次性且
+ * 90s 过期，由 ws-client 每次重连前重新 register。
+ */
+export function createDingtalkApi(
+  config: DingtalkConfig,
+  fetchImpl: typeof fetch = fetch,
+): DingtalkApi {
+  return {
+    async register() {
+      const res = await fetchImpl(GATEWAY_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          clientId: config.clientId,
+          clientSecret: config.clientSecret,
+          subscriptions: [{ type: 'CALLBACK', topic: '/v1.0/im/bot/messages/get' }],
+          ua: 'mipham-code',
+        }),
+      })
+      if (!res.ok) throw new Error(`dingtalk gateway register ${res.status}`)
+      const data = (await res.json()) as { endpoint?: string; ticket?: string }
+      if (!data.endpoint || !data.ticket) {
+        throw new Error('dingtalk gateway: missing endpoint/ticket')
+      }
+      return { endpoint: data.endpoint, ticket: data.ticket }
+    },
+
+    open(endpoint, ticket) {
+      return new WebSocket(`${endpoint}?ticket=${encodeURIComponent(ticket)}`)
+    },
+
+    async reply(sessionWebhook, text) {
+      if (!sessionWebhook) return
+      const res = await fetchImpl(sessionWebhook, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ msgtype: 'text', text: { content: text } }),
+      })
+      if (!res.ok) throw new Error(`dingtalk reply ${res.status}`)
+      const data = (await res.json()) as { errcode?: number; errmsg?: string }
+      if (data.errcode != null && data.errcode !== 0) {
+        throw new Error(`dingtalk reply errcode=${data.errcode}: ${data.errmsg ?? 'unknown'}`)
+      }
+    },
+
+    parseMessage(frame) {
+      if (!frame || typeof frame !== 'object') return null
+      const f = frame as { type?: string; data?: unknown }
+      if (f.type !== 'CALLBACK' || typeof f.data !== 'string') return null
+      let payload: {
+        msgtype?: string
+        text?: { content?: string }
+        senderStaffId?: string
+        senderId?: string
+        conversationId?: string
+        msgId?: string
+        sessionWebhook?: string
+      }
+      try {
+        payload = JSON.parse(f.data)
+      } catch {
+        return null
+      }
+      if (payload?.msgtype !== 'text') return null
+      const text = payload?.text?.content?.trim()
+      if (!text) return null
+      const staffId = payload?.senderStaffId ?? payload?.senderId
+      if (!staffId) return null
+      return {
+        staffId,
+        conversationId: payload?.conversationId ?? '',
+        msgId: payload?.msgId ?? '',
+        text,
+        sessionWebhook: payload?.sessionWebhook ?? '',
+      }
+    },
+
+    isPing(frame) {
+      const f = frame as { type?: string; headers?: { topic?: string } }
+      return f?.type === 'SYSTEM' && f?.headers?.topic === 'ping'
+    },
+
+    ack(ws, frame) {
+      sendResponse(ws, frame, '{"response": null}')
+    },
+
+    pong(ws, frame) {
+      sendResponse(ws, frame, (frame as { data?: unknown }).data)
+    },
+  }
+}

package/src/daemon/dingtalk/env.ts

@@ -0,0 +1,16 @@
+import type { DingtalkConfig } from './types.js'
+
+/** fail-closed：缺 clientId 或 clientSecret → null（daemon 不启用钉钉）。 */
+export function parseDingtalkEnv(): DingtalkConfig | null {
+  const clientId = process.env.DINGTALK_CLIENT_ID
+  const clientSecret = process.env.DINGTALK_CLIENT_SECRET
+  if (!clientId || !clientSecret) return null
+  return {
+    clientId,
+    clientSecret,
+    allowedStaffIds: (process.env.DINGTALK_ALLOWED_STAFF_IDS || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  }
+}

package/src/daemon/dingtalk/types.ts

@@ -0,0 +1,13 @@
+export interface DingtalkConfig {
+  clientId: string
+  clientSecret: string
+  allowedStaffIds: string[] // 白名单（钉钉 senderStaffId / senderId）
+}
+
+export interface DingtalkMessage {
+  staffId: string // 发消息用户（senderStaffId，回退 senderId）
+  conversationId: string // 会话 id
+  msgId: string // 消息 id（业务侧）
+  text: string // 文本内容
+  sessionWebhook: string // 回发路由（机器人 sessionWebhook URL）
+}

package/src/daemon/dingtalk/ws-client.ts

@@ -0,0 +1,81 @@
+import type { DingtalkApi } from './api.js'
+import type { DingtalkMessage } from './types.js'
+import { nextBackoff } from '../backoff.js'
+
+/**
+ * 钉钉 Stream 长连接生命周期：register（HTTP 拿 endpoint+ticket）→ 建连 →
+ * 服务端 ping/pong → 消息回调（parse→ack→onMessage）→ 断开重连。ticket 一次性
+ * 且 90s 过期，故每次重连前必须重新 register。返回 stop。
+ */
+export function startDingtalkWs(
+  api: DingtalkApi,
+  onMessage: (msg: DingtalkMessage) => Promise<void>,
+): () => void {
+  let stopped = false
+  let ws: WebSocket | null = null
+  let backoffMs = 1000
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+
+  function clearReconnect() {
+    if (reconnectTimer) clearTimeout(reconnectTimer)
+    reconnectTimer = null
+  }
+
+  function scheduleReconnect() {
+    if (stopped) return
+    reconnectTimer = setTimeout(() => void connect(), backoffMs)
+    backoffMs = nextBackoff(backoffMs)
+    ;(reconnectTimer as unknown as { unref?: () => void }).unref?.()
+  }
+
+  async function connect() {
+    if (stopped) return
+    let endpoint: string
+    let ticket: string
+    try {
+      ;({ endpoint, ticket } = await api.register())
+    } catch {
+      scheduleReconnect()
+      return
+    }
+    if (stopped) return
+    ws = api.open(endpoint, ticket)
+    ws.onopen = () => {
+      backoffMs = 1000
+    }
+    ws.onmessage = (ev) => {
+      let frame: unknown
+      try {
+        frame = JSON.parse(ev.data as string)
+      } catch {
+        return
+      }
+      if (api.isPing(frame)) {
+        if (ws) api.pong(ws, frame)
+        return
+      }
+      const msg = api.parseMessage(frame)
+      if (msg) {
+        if (ws) api.ack(ws, frame)
+        void onMessage(msg).catch(() => {})
+      }
+    }
+    ws.onclose = () => {
+      ws = null
+      scheduleReconnect()
+    }
+  }
+
+  void connect()
+  return () => {
+    stopped = true
+    clearReconnect()
+    if (ws) {
+      try {
+        ws.close()
+      } catch {
+        /* 连接尚未建立时 close 可能抛错，忽略 */
+      }
+    }
+  }
+}