dsh-heatmap 0.1.0

package/src/client/storage.ts

@@ -0,0 +1,144 @@
+/**
+ * browser 半部：本地事件环形缓冲 + 运行时设置 + 授权状态（全部 localStorage）。
+ *
+ * 设计要点：
+ * - 数据默认只在用户本地（localStorage），热力图读取本地数据，无需授权；
+ * - 上传动作才可能触发授权弹窗，授权结果也持久化在本地；
+ * - 运行时设置是「当前」可变对象，供埋点引擎与面板共享。
+ */
+import type { AnalyticsBatch, AnalyticsEvent } from '../shared/types.ts'
+
+const EVENTS_KEY = 'dsh-heatmap.events.v1'
+const SETTINGS_KEY = 'dsh-heatmap.settings.v1'
+const CONSENT_KEY = 'dsh-heatmap.consent.v1'
+
+export interface ClientSettings {
+  /** 是否启用热力图覆盖层。 */
+  heatmapMode: boolean
+  /** 是否启用埋点采集。 */
+  trackingEnabled: boolean
+  /** 是否采集鼠标悬停坐标（供热力图，默认关闭以控制数据量）。 */
+  trackMouse: boolean
+  /** 采样率 0..1。 */
+  sampleRate: number
+  /** 上传目标；空则上传到同源 host 收集器 `/dsh-heatmap/ingest`。 */
+  uploadEndpoint: string
+  /** 上传前是否要求授权弹窗。 */
+  consentRequired: boolean
+  /** 本地最多保留事件条数。 */
+  maxEvents: number
+}
+
+export const DEFAULT_SETTINGS: ClientSettings = {
+  heatmapMode: false,
+  trackingEnabled: true,
+  trackMouse: false,
+  sampleRate: 1,
+  uploadEndpoint: '',
+  consentRequired: true,
+  maxEvents: 5000,
+}
+
+function readSettings(): ClientSettings {
+  try {
+    const raw = localStorage.getItem(SETTINGS_KEY)
+    if (!raw) return { ...DEFAULT_SETTINGS }
+    return { ...DEFAULT_SETTINGS, ...JSON.parse(raw) as Partial<ClientSettings> }
+  } catch {
+    return { ...DEFAULT_SETTINGS }
+  }
+}
+
+/** 当前生效设置（可变引用，供埋点引擎实时读取）。 */
+let currentSettings: ClientSettings = readSettings()
+
+export function getSettings(): ClientSettings {
+  return currentSettings
+}
+
+export function saveSettings(next: ClientSettings): void {
+  currentSettings = { ...next }
+  try {
+    localStorage.setItem(SETTINGS_KEY, JSON.stringify(currentSettings))
+  } catch {
+    /* storage unavailable */
+  }
+}
+
+let currentSessionId = ''
+
+export function getSessionId(): string {
+  return currentSessionId
+}
+
+export function setSessionId(id: string): void {
+  currentSessionId = id
+}
+
+/** 本地事件环形缓冲（内存 + localStorage 持久化）。 */
+class ClientEventStore {
+  private events: AnalyticsEvent[] = []
+  private loaded = false
+
+  private ensureLoaded(): void {
+    if (this.loaded) return
+    this.loaded = true
+    try {
+      const raw = localStorage.getItem(EVENTS_KEY)
+      this.events = raw ? JSON.parse(raw) as AnalyticsEvent[] : []
+    } catch {
+      this.events = []
+    }
+  }
+
+  push(event: AnalyticsEvent, maxEvents: number): void {
+    this.ensureLoaded()
+    this.events.push(event)
+    if (this.events.length > maxEvents) this.events = this.events.slice(-maxEvents)
+  }
+
+  flush(): void {
+    try {
+      localStorage.setItem(EVENTS_KEY, JSON.stringify(this.events))
+    } catch {
+      /* quota exceeded / storage unavailable — keep in-memory only */
+    }
+  }
+
+  all(): AnalyticsEvent[] {
+    this.ensureLoaded()
+    return this.events
+  }
+
+  clear(): void {
+    this.events = []
+    try {
+      localStorage.removeItem(EVENTS_KEY)
+    } catch {
+      /* ignore */
+    }
+  }
+
+  buildBatch(sessionId: string): AnalyticsBatch {
+    this.ensureLoaded()
+    return { v: 1, sessionId, sentAt: Date.now(), events: this.events }
+  }
+}
+
+export const clientStore = new ClientEventStore()
+
+export function hasConsented(): boolean {
+  try {
+    return localStorage.getItem(CONSENT_KEY) === '1'
+  } catch {
+    return false
+  }
+}
+
+export function setConsented(value: boolean): void {
+  try {
+    localStorage.setItem(CONSENT_KEY, value ? '1' : '0')
+  } catch {
+    /* ignore */
+  }
+}

package/src/client/tracker.ts

@@ -0,0 +1,219 @@
+/**
+ * browser 半部：全局埋点采集引擎。
+ *
+ * 通过 document 级（capture）监听，捕获页面生命周期、交互、滚动曝光与热力图
+ * 坐标。核心原则：只记录「元素身份 + 位置 + 时间 + 视口」，绝不采集输入内容
+ * 或对话正文（input 仅记录长度）。
+ */
+import type { AnalyticsEvent, ElementRef } from '../shared/types.ts'
+import { clientStore, getSettings, setSessionId } from './storage.ts'
+
+export interface Tracker {
+  dispose(): void
+}
+
+function uuid(): string {
+  try {
+    return crypto.randomUUID()
+  } catch {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  }
+}
+
+/** 参与「元素身份」识别的语义标签；点击落在子节点时向上寻找最近的可交互元素。 */
+const INTERACTIVE_TAGS = new Set([
+  'BUTTON', 'A', 'INPUT', 'TEXTAREA', 'SELECT', 'OPTION', 'LABEL',
+  'SUMMARY', 'DETAILS', 'LI', 'DIV', 'SPAN', 'P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
+])
+
+function nearestInteractive(el: Element | null): Element | null {
+  let cur: Element | null = el
+  while (cur && cur !== document.body && cur !== document.documentElement) {
+    if (INTERACTIVE_TAGS.has(cur.tagName)) return cur
+    cur = cur.parentElement
+  }
+  return el
+}
+
+function textOf(el: Element): string | undefined {
+  const t = (el.textContent ?? '').replace(/\s+/g, ' ').trim()
+  if (t === '') return undefined
+  return t.length > 40 ? `${t.slice(0, 40)}…` : t
+}
+
+/**
+ * 生成稳定的元素身份（优先 data-testid > id > aria-label > role+tag > placeholder/name > tag+text）。
+ * 隐私保护：input/textarea/select 与 contenteditable 元素绝不采集其内容/文案。
+ */
+function identify(el: Element | null): ElementRef | undefined {
+  if (!el || el === document.body || el === document.documentElement) return undefined
+  const tag = el.tagName.toLowerCase()
+  const testId = el.getAttribute('data-testid') ?? el.getAttribute('data-test-id') ?? undefined
+  const id = el.id || undefined
+  const ariaLabel = el.getAttribute('aria-label') ?? undefined
+  const role = el.getAttribute('role') ?? undefined
+  const title = el.getAttribute('title') ?? undefined
+  const isInputLike = tag === 'input' || tag === 'textarea' || tag === 'select'
+    || (el as HTMLElement).isContentEditable === true
+  const name = isInputLike ? (el.getAttribute('name') ?? undefined) : undefined
+  const placeholder = isInputLike ? (el.getAttribute('placeholder') ?? undefined) : undefined
+  const text = isInputLike ? undefined : textOf(el)
+  const elementId = testId ?? id ?? ariaLabel
+    ?? (role ? `${role}#${tag}` : undefined)
+    ?? (placeholder ? `${tag}[${placeholder}]` : undefined)
+    ?? (name ? `${tag}#${name}` : undefined)
+    ?? `${tag}${text ? `:${text}` : ''}`
+  return {
+    tag,
+    ...(id !== undefined ? { id } : {}),
+    ...(role !== undefined ? { role } : {}),
+    ...(ariaLabel !== undefined ? { ariaLabel } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(testId !== undefined ? { testId } : {}),
+    ...(name !== undefined ? { name } : {}),
+    ...(placeholder !== undefined ? { placeholder } : {}),
+    ...(text !== undefined ? { text } : {}),
+    elementId,
+  }
+}
+
+export function createTracker(): Tracker {
+  const sessionId = uuid()
+  setSessionId(sessionId)
+
+  const page = () => ({ path: window.location.pathname, hash: window.location.hash })
+
+  const emit = (type: AnalyticsEvent['type'], partial: Partial<AnalyticsEvent>): void => {
+    const s = getSettings()
+    if (!s.trackingEnabled) return
+    if (s.sampleRate < 1 && Math.random() > s.sampleRate) return
+    const event: AnalyticsEvent = {
+      v: 1,
+      id: uuid(),
+      ts: Date.now(),
+      sessionId,
+      type,
+      page: page(),
+      ...partial,
+    }
+    clientStore.push(event, s.maxEvents)
+  }
+
+  emit('session_start', {})
+  emit('page_view', {})
+
+  const onClick = (e: MouseEvent): void => {
+    emit('click', {
+      target: identify(nearestInteractive(e.target as Element | null)),
+      position: { x: e.clientX, y: e.clientY },
+    })
+  }
+
+  const onFocusIn = (e: FocusEvent): void => {
+    emit('focus', { target: identify(e.target as Element | null) })
+  }
+  const onFocusOut = (e: FocusEvent): void => {
+    emit('blur', { target: identify(e.target as Element | null) })
+  }
+
+  let lastHover = 0
+  const onMouseMove = (e: MouseEvent): void => {
+    if (!getSettings().trackMouse) return
+    const now = Date.now()
+    if (now - lastHover < 250) return
+    lastHover = now
+    emit('hover', {
+      position: { x: e.clientX, y: e.clientY },
+      target: identify(nearestInteractive(e.target as Element | null)),
+    })
+  }
+
+  let scrollTimer: number | undefined
+  const onScroll = (): void => {
+    if (scrollTimer !== undefined) return
+    scrollTimer = window.setTimeout(() => {
+      scrollTimer = undefined
+      const doc = document.documentElement
+      const max = doc.scrollHeight - doc.clientHeight
+      const depth = max > 0 ? Math.min(1, Math.max(0, doc.scrollTop / max)) : 0
+      emit('scroll_depth', { depth: Math.round(depth * 100) / 100 })
+    }, 500)
+  }
+
+  const onVisibility = (): void => {
+    const visible = document.visibilityState === 'visible'
+    emit('visibility', { visible })
+    if (!visible) emit('session_end', {})
+  }
+
+  let lastInput = 0
+  const onInput = (e: Event): void => {
+    const now = Date.now()
+    if (now - lastInput < 1000) return
+    const el = e.target as HTMLInputElement | HTMLTextAreaElement | null
+    if (!el || !('value' in el)) return
+    lastInput = now
+    emit('input', { target: identify(el), inputLength: el.value.length })
+  }
+
+  const onHashChange = (): void => {
+    emit('page_view', {})
+  }
+
+  const onPageHide = (): void => {
+    emit('session_end', {})
+    clientStore.flush()
+  }
+
+  // 元素曝光：IntersectionObserver 上报「哪些面板/控件被用户看到」。
+  // 只观察有稳定身份的区域（testid、显式标记、ARIA landmark），控制开销。
+  const impressed = new WeakSet<Element>()
+  const IMPRESSION_SELECTOR = '[data-testid], [data-impression], [role="main"], [role="region"], [role="dialog"], [role="navigation"], [role="complementary"]'
+  const impressionObserver = new IntersectionObserver((entries) => {
+    for (const entry of entries) {
+      if (entry.isIntersecting && entry.intersectionRatio >= 0.5 && !impressed.has(entry.target)) {
+        impressed.add(entry.target)
+        impressionObserver.unobserve(entry.target)
+        emit('impression', { target: identify(entry.target) })
+      }
+    }
+  }, { threshold: [0.5] })
+  const scanImpressions = (): void => {
+    document.querySelectorAll(IMPRESSION_SELECTOR).forEach((el) => {
+      if (!impressed.has(el)) impressionObserver.observe(el)
+    })
+  }
+  scanImpressions()
+  const impressionTimer = window.setInterval(scanImpressions, 2500)
+
+  document.addEventListener('click', onClick, true)
+  document.addEventListener('focusin', onFocusIn, true)
+  document.addEventListener('focusout', onFocusOut, true)
+  document.addEventListener('mousemove', onMouseMove, true)
+  document.addEventListener('scroll', onScroll, true)
+  document.addEventListener('input', onInput, true)
+  document.addEventListener('visibilitychange', onVisibility)
+  window.addEventListener('hashchange', onHashChange)
+  window.addEventListener('pagehide', onPageHide)
+
+  const flushTimer = window.setInterval(() => clientStore.flush(), 3000)
+
+  return {
+    dispose(): void {
+      document.removeEventListener('click', onClick, true)
+      document.removeEventListener('focusin', onFocusIn, true)
+      document.removeEventListener('focusout', onFocusOut, true)
+      document.removeEventListener('mousemove', onMouseMove, true)
+      document.removeEventListener('scroll', onScroll, true)
+      document.removeEventListener('input', onInput, true)
+      document.removeEventListener('visibilitychange', onVisibility)
+      window.removeEventListener('hashchange', onHashChange)
+      window.removeEventListener('pagehide', onPageHide)
+      window.clearInterval(flushTimer)
+      window.clearInterval(impressionTimer)
+      impressionObserver.disconnect()
+      if (scrollTimer !== undefined) window.clearTimeout(scrollTimer)
+      clientStore.flush()
+    },
+  }
+}

package/src/http.ts

@@ -0,0 +1,172 @@
+/**
+ * host 侧「外部访问接口」：挂载在 DSH 自带 webServer 上的 HTTP 路由。
+ *
+ * 这些路由即预留的统一分析平台对接面：
+ * - GET  /dsh-heatmap/health   健康检查
+ * - POST /dsh-heatmap/ingest   客户端批量上报（本地收集器）
+ * - GET  /dsh-heatmap/stats    聚合统计
+ * - GET  /dsh-heatmap/export   导出事件（NDJSON/JSON）
+ * - DELETE /dsh-heatmap/clear  清空
+ *
+ * 客户端与 host 同源（页面由 host 的 webServer 提供），因此客户端用
+ * `window.location.origin + '/dsh-heatmap/ingest'` 即可直接上报，无需配置端口。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { AnalyticsStore } from './store.ts'
+import { SCHEMA_VERSION } from './shared/types.ts'
+
+/** 结构性最小依赖：避免把 host-webserver 变成硬依赖。 */
+export interface WebServerLike {
+  register(route: {
+    kind: 'exact' | 'prefix'
+    path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+  }): () => void
+}
+
+export interface HttpOptions {
+  consentRequired: boolean
+  uploadEndpoint: string
+}
+
+const MAX_BODY_BYTES = 32 * 1024 * 1024
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(payload),
+    'cache-control': 'no-store',
+  })
+  res.end(payload)
+}
+
+function sendText(res: ServerResponse, status: number, text: string): void {
+  res.writeHead(status, {
+    'content-type': 'text/plain; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(text)
+}
+
+/** 读取 JSON 请求体（带大小上限，避免被异常体拖垮）。 */
+function readJson(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    req.setEncoding('utf8')
+    let body = ''
+    let size = 0
+    req.on('data', (chunk: string) => {
+      size += Buffer.byteLength(chunk)
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      body += chunk
+    })
+    req.on('end', () => {
+      if (body.trim() === '') return resolve({})
+      try {
+        resolve(JSON.parse(body))
+      } catch {
+        reject(new Error('invalid JSON body'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/** 注册全部埋点 HTTP 路由，返回一次性解除全部路由的 disposer。 */
+export function registerRoutes(webServer: WebServerLike, store: AnalyticsStore, opts: HttpOptions): () => void {
+  const disposers: (() => void)[] = []
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/health',
+    handler: (_req, res) => {
+      sendJson(res, 200, { ok: true, service: 'dsh-heatmap', schemaVersion: SCHEMA_VERSION })
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/ingest',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return sendText(res, 405, 'method not allowed')
+      try {
+        const body = (await readJson(req)) as { v?: number; events?: unknown[] }
+        if (body?.v !== SCHEMA_VERSION || !Array.isArray(body.events)) {
+          return sendJson(res, 400, { ok: false, error: 'unsupported schema version or malformed batch' })
+        }
+        const accepted = await store.ingest(body as never)
+        sendJson(res, 200, { ok: true, accepted })
+      } catch (err) {
+        sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/stats',
+    handler: async (_req, res) => {
+      sendJson(res, 200, await store.stats())
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/export',
+    handler: async (req, res) => {
+      const url = new URL(req.url ?? '/', 'http://x')
+      const format = url.searchParams.get('format') === 'json' ? 'json' : 'ndjson'
+      const limit = Number.parseInt(url.searchParams.get('limit') ?? '0', 10) || 0
+      const events = await store.list(limit)
+      if (format === 'json') return sendJson(res, 200, { schemaVersion: SCHEMA_VERSION, count: events.length, events })
+      const payload = events.map(e => JSON.stringify(e)).join('\n') + (events.length ? '\n' : '')
+      sendText(res, 200, payload)
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/sessions',
+    handler: async (req, res) => {
+      const url = new URL(req.url ?? '/', 'http://x')
+      const limit = Number.parseInt(url.searchParams.get('limit') ?? '0', 10) || 0
+      const timelines = await store.sessions(limit)
+      sendJson(res, 200, { count: timelines.length, sessions: timelines })
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/funnel',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return sendText(res, 405, 'method not allowed')
+      try {
+        const body = (await readJson(req)) as { steps?: unknown }
+        if (!Array.isArray(body?.steps) || body.steps.length === 0) {
+          return sendJson(res, 400, { ok: false, error: 'steps 必须是至少一个事件类型的数组' })
+        }
+        sendJson(res, 200, await store.funnel(body.steps.map(String)))
+      } catch (err) {
+        sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }))
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: '/dsh-heatmap/clear',
+    handler: async (req, res) => {
+      if (req.method !== 'DELETE') return sendText(res, 405, 'method not allowed')
+      await store.clear()
+      sendJson(res, 200, { ok: true, cleared: true })
+    },
+  }))
+
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * dsh-heatmap — host 半部。
+ *
+ * 职责（与 browser 半部分工清晰）：
+ * - 收集器：webServer 上的 /dsh-heatmap/* HTTP 路由（客户端上报、导出、统计、清空）；
+ * - CLI/Agent 接口：注册 `analytics_export` 工具，供 Agent 或统一分析平台导出/统计/清空/上传；
+ * - 持久化：NDJSON 落盘（AnalyticsStore）。
+ *
+ * browser 半部负责真正的埋点采集、本地热力图、统计面板与上传授权弹窗——
+ * 数据默认只存在用户本地，热力图展示「本地 / 本人」数据，无需授权；
+ * 只有「上传」动作会触发授权弹窗。
+ */
+import { resolve } from 'node:path'
+import { homedir } from 'node:os'
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { AnalyticsStore } from './store.ts'
+import { registerRoutes, type WebServerLike } from './http.ts'
+
+export const name = 'dsh-heatmap'
+
+/** 部署级配置（cordis.yml 可覆盖；browser 侧另有 localStorage 的运行时开关）。 */
+export interface Config {
+  /** 是否启用 host 收集器与工具（false 则纯本地采集，仅浏览器热力图可用）。 */
+  enabled: boolean
+  /** 数据落盘目录；空则默认 `$DSH_HOME/storages/dsh-heatmap` 或 `~/.dsh/storages/dsh-heatmap`。 */
+  dataDir: string
+  /** 内存与文件最多保留的事件条数（环形缓冲）。 */
+  maxEvents: number
+  /** 统一分析平台上传地址（`analytics_export upload` 动作的目标）。 */
+  uploadEndpoint: string
+  /** 是否要求上传授权（文档化：实际授权弹窗由 browser 半部执行）。 */
+  consentRequired: boolean
+}
+
+export const Config: Schema<Config> = Schema.object({
+  enabled: Schema.boolean().default(true),
+  dataDir: Schema.string().default(''),
+  maxEvents: Schema.number().default(20000),
+  uploadEndpoint: Schema.string().default(''),
+  consentRequired: Schema.boolean().default(true),
+})
+
+/** tools 服务的结构性最小依赖。 */
+interface ToolsLike {
+  register(definition: unknown): () => void
+}
+
+function defaultDataDir(): string {
+  const base = process.env.DSH_HOME ?? resolve(homedir(), '.dsh')
+  return resolve(base, 'storages', 'dsh-heatmap')
+}
+
+export function apply(ctx: Context, config: Config): void {
+  if (!config.enabled) return
+
+  const dataDir = config.dataDir !== '' ? config.dataDir : defaultDataDir()
+  const store = new AnalyticsStore(dataDir, config.maxEvents)
+
+  ctx.effect(() => {
+    const disposers: (() => void)[] = []
+
+    // 1) 外部访问接口：HTTP 路由。
+    const webServer = ctx.get('webServer') as WebServerLike | undefined
+    if (webServer !== undefined) {
+      disposers.push(registerRoutes(webServer, store, {
+        consentRequired: config.consentRequired,
+        uploadEndpoint: config.uploadEndpoint,
+      }))
+      ctx.logger.info(`dsh-heatmap: http routes ready (data: ${store.filePath})`)
+    } else {
+      ctx.logger.warn('dsh-heatmap: webServer service unavailable — http routes skipped')
+    }
+
+    // 2) CLI / Agent 接口：注册工具。
+    const tools = ctx.get('tools') as ToolsLike | undefined
+    if (tools !== undefined) {
+      disposers.push(tools.register(defineTool({
+        name: 'analytics_export',
+        description: '导出/统计/清空 dsh-heatmap 采集的页面埋点数据，或上传到统一分析平台。动作：stats（聚合统计）、export（导出事件）、sessions（会话时间线/回放）、funnel（漏斗分析，需 steps）、clear（清空）、upload（上传到配置的上传地址）。',
+        parameters: {
+          action: {
+            type: 'string',
+            required: true,
+            enum: ['stats', 'export', 'sessions', 'funnel', 'clear', 'upload'],
+            description: '要执行的动作',
+          },
+          steps: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '漏斗步骤（仅 action=funnel 时使用）：有序事件类型数组，如 [session_start, click, input]',
+          },
+        },
+        output: {
+          schema: { type: 'json' },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args): Promise<JsonValue> {
+          const asJson = (value: unknown): JsonValue => value as JsonValue
+          if (args.action === 'stats') return asJson(await store.stats())
+          if (args.action === 'sessions') return asJson({ sessions: await store.sessions(20) })
+          if (args.action === 'funnel') {
+            const steps = Array.isArray(args.steps) ? args.steps.map(String) : []
+            if (steps.length === 0) return { ok: false, error: 'funnel 需要 steps（有序事件类型数组）' }
+            return asJson(await store.funnel(steps))
+          }
+          if (args.action === 'clear') {
+            await store.clear()
+            return { ok: true, cleared: true }
+          }
+          if (args.action === 'upload') {
+            if (config.uploadEndpoint === '') {
+              return { ok: false, error: 'uploadEndpoint 未配置，无法上传' }
+            }
+            const events = await store.list()
+            const res = await fetch(config.uploadEndpoint, {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ schemaVersion: 1, sentAt: Date.now(), count: events.length, events }),
+            })
+            return { ok: res.ok, status: res.status, sent: events.length }
+          }
+          // export
+          const events = await store.list(5000)
+          return asJson({ ok: true, count: events.length, events })
+        },
+      })))
+    }
+
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  }, 'dsh-heatmap: host surfaces')
+}