@miphamai/cli 0.52.0 → 0.54.0

package/package.json

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

package/skills/mipham/save-to-wiki.mipham-skill.md

@@ -0,0 +1,92 @@
+---
+name: save-to-wiki
+description: Save the current conversation, an insight, or a decision into the Obsidian wiki vault (~/MiphamAI) as a structured note. Analyzes the chat, picks a note type (synthesis/concept/source/decision/session), writes it via the Obsidian MCP, and leaves a memory pointer back. Use when the user types /save, says "save this to the wiki", "file this", "keep this insight", or wants a decision/concept archived.
+version: 1.0.0
+---
+
+# Save to Wiki
+
+Good answers and insights shouldn't disappear into chat history. This skill files the most valuable content from the current conversation into the user's Obsidian wiki as a permanent, searchable note.
+
+The wiki compounds. Save often.
+
+## Transport
+
+Writes go through the Obsidian MCP server (`obsidian` in `~/.mipham/mcp.json`), exposed as tools prefixed `mcp__obsidian__`:
+
+- `mcp__obsidian__create_note` — create a new note (target path + markdown body)
+- `mcp__obsidian__append_note` — append to an existing note
+- `mcp__obsidian__get_file` / `mcp__obsidian__list_files` — check whether a note already exists
+- `mcp__obsidian__set_property` — update frontmatter properties
+
+If a tool name is unfamiliar, run `/mcp` to list the connected Obsidian tools and use the exact names. Avoid `get_vault_info` — it has a known upstream bug (`Command "vault" not found`) and is not needed for writing.
+
+## Note Type Decision
+
+Pick the best type from the conversation content. If the user specifies a type, use it.
+
+| Type      | Folder (`wiki/`) | Use when                                                 |
+| --------- | ---------------- | -------------------------------------------------------- |
+| synthesis | `questions/`     | Multi-step analysis, comparison, or answer to a question |
+| concept   | `concepts/`      | Explaining or defining an idea, pattern, or framework    |
+| source    | `sources/`       | Summary of external material discussed in the session    |
+| decision  | `meta/`          | Architectural, project, or strategic decision made       |
+| session   | `sessions/`      | Full session summary — captures everything discussed     |
+
+When in doubt, use `synthesis`.
+
+## Frontmatter
+
+All note types share this base frontmatter (aligns with the vault's `_templates/`):
+
+```yaml
+---
+type: <synthesis|concept|source|decision|session>
+title: 'Note Title'
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags:
+  - <relevant-tag>
+status: developing
+related:
+  - '[[Any Wiki Page Mentioned]]'
+sources: []
+saved_from: Mipham Code
+mipham_memory: <memory-slug>
+---
+```
+
+- `synthesis` adds: `question: "<original query>"`, `answer_quality: solid`
+- `decision` adds: `decision_date: YYYY-MM-DD`
+- `saved_from` and `mipham_memory` implement the light two-way bridge (see below).
+
+## Workflow
+
+1. **Scan** the conversation and identify the single most valuable content to preserve — an insight, a decision with rationale, or a synthesis. If the conversation is trivial (mechanical Q&A, setup steps already documented, temp debugging), say so and skip.
+2. **Determine** the note type using the table. Respect an explicit type/title from the user.
+3. **Name** the note — short and descriptive; ask the user if not already named.
+4. **Check existence** — use `list_files`/`get_file` to see whether `wiki/<folder>/<title>.md` already exists. If it does, offer to update (`append_note` or rewrite) instead of duplicating.
+5. **Write** the note via `create_note` (path `wiki/<folder>/<title>.md`) with full frontmatter and a declarative, present-tense body.
+6. **Leave a memory pointer** — write a `reference` memory via the Memory tool (`action=write`, `name=wiki-<title-slug>`) whose body records the wiki note path and a one-line summary. This lets `/memory` and recall surface the wiki note.
+7. **Update** `wiki/index.md` (add the note to the relevant section) and `wiki/log.md` (prepend `## [YYYY-MM-DD] save | Note Title`). Refresh `wiki/hot.md` if it tracks recent additions.
+
+## Light Two-Way Bridge
+
+- **memory → wiki**: the pointer memory (step 6) stores the wiki path, so memory recall can link back to the note.
+- **wiki → memory**: the note's frontmatter carries `saved_from: Mipham Code` and `mipham_memory: <slug>` — plain strings, not wikilinks, so they don't create broken links in Obsidian.
+
+This is a one-way pointer plus a provenance back-reference, not a sync layer. Do not attempt bidirectional synchronization.
+
+## Writing Style
+
+- Declarative, present tense. Write the knowledge, not the conversation.
+- Not: "The user asked about X and Claude explained..."
+- Yes: "X works by doing Y. The key insight is Z."
+- Link mentioned concepts/entities/wiki pages with `[[wikilinks]]`.
+- Cite sources where applicable: `(Source: [[Page]])`.
+
+## What to Save vs. Skip
+
+**Save**: non-obvious insights, decisions with rationale, analyses that took real effort, comparisons likely to be referenced again, research findings.
+
+**Skip**: mechanical Q&A, setup steps already documented, temporary debugging with no lasting insight, anything already in the wiki (update instead of duplicating).

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/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/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

@@ -0,0 +1,59 @@
+import type { SessionManager } from './session-manager'
+import type { SessionWorker } from './session-worker'
+import type { RateLimiter } from './rate-limiter'
+
+export interface ChannelMessageOptions {
+  channel: string // 'feishu' | 'telegram' | 'wecom' | 'dingtalk'
+  externalId: string // openId / chatId / userId
+  text: string
+  allowed: Set<string>
+  rateLimiter: RateLimiter
+  sm: SessionManager
+  getOrCreateWorker: (sessionId: string) => SessionWorker | null
+  cwd: string
+  provider: string
+  model: string
+  sendText: (externalId: string, text: string) => Promise<void>
+  maxLen: number // 飞书 4000 / Telegram 4096 / 企微 2048 / 钉钉 2000
+  logPrefix: string // '[feishu]' / '[telegram]' / '[wecom]'
+}
+
+/** 四频道共享的消息处理骨架：白名单→限流→会话→processPrompt→回发。 */
+export async function handleChannelMessage(opts: ChannelMessageOptions): Promise<void> {
+  const {
+    channel,
+    externalId,
+    text,
+    allowed,
+    rateLimiter,
+    sm,
+    getOrCreateWorker,
+    cwd,
+    provider,
+    model,
+    sendText,
+    maxLen,
+    logPrefix,
+  } = opts
+  try {
+    if (!allowed.has(externalId)) return
+    if (!rateLimiter.check(`${channel}:${externalId}`).allowed) return
+
+    const session = sm.getOrCreateByExternalUser(channel, externalId, cwd, provider, model)
+    const worker = getOrCreateWorker(session.id)
+    if (!worker) {
+      await sendText(externalId, '（会话初始化失败，请稍后重试）')
+      return
+    }
+    await worker.processPrompt(text)
+    const result = worker.getLastAssistantContent()
+    await sendText(externalId, result ? result.slice(0, maxLen) : '（无回复）')
+  } catch (err) {
+    console.error(`${logPrefix} message handling failed:`, err)
+    try {
+      await sendText(externalId, '（处理失败，请稍后重试）')
+    } catch {
+      /* 忽略回送失败，不 rethrow */
+    }
+  }
+}

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 可能抛错，忽略 */
+      }
+    }
+  }
+}