#	功能	说明
1	科学埋点设计	四类事件（生命周期 / 交互 / 滚动曝光 / 热力图坐标）+ 稳定元素身份 + schema 版本化，参考主流产品分析（Amplitude / Mixpanel / Heap / Clarity）的埋点原则
2	热力图模式	点击 + 鼠标悬停密度热力图，色带「蓝→青→绿→黄→红」；面板标注「本地 / 本人数据」并展示聚合统计
3	CLI / 外部访问接口	host 侧 `analytics_export` 工具（Agent 可调用）+ `webServer` 上的 `/dsh-heatmap/*` HTTP 路由，预留统一分析平台对接
4	上传授权弹窗	数据上传到外部/其他软件前弹出授权弹窗，用户「同意并上传」后才发送
5	隐私最小化（补充）	只采集控件身份、坐标、时间、视口；绝不采集对话正文与输入内容（输入仅记录长度）
6	数据本地化（补充）	采集数据默认只存本地 localStorage；host 收集器用 NDJSON 落盘，可随时导出/清空
7	可配置（补充）	采样率、事件开关、热力图开关、鼠标热力图、上传地址、授权要求、存储上限均可配置

埋点设计（事件分类学）

事件类型

类型	触发时机	采集字段	产品用途
`session_start` / `session_end`	页面加载 / 卸载或隐藏	会话 id、时间	会话数、会话时长
`page_view`	初始加载 + hash 路由变化	path、hash	页面/视图访问量
`click`	任何可点击元素被点击	元素身份 + 视口坐标	按钮点击率、点击热力图
`focus` / `blur`	元素获得/失去焦点	元素身份	是否 focus、交互路径
`hover`	鼠标悬停（250ms 节流，可选）	视口坐标 + 元素身份	悬停/注意力热力图
`scroll_depth`	滚动停止后（500ms 防抖）	滚动深度 0..1	内容消费深度
`visibility`	页签可见性变化	visible	停留时长（活跃时段累计）
`input`	输入框输入（1s 节流）	元素身份 + 输入长度	输入活跃度（不含内容）
`impression`	元素首次进入视口 ≥50%（IntersectionObserver）	元素身份	曝光分析（哪些面板/控件被看到）

元素身份（稳定指纹）

采集端按优先级生成稳定的 elementId，保证跨会话可聚合到同一控件：

data-testid > id > aria-label > role#tag > tag:文本摘要(≤40字)

同时记录 tag / role / ariaLabel / title / text 供分析侧做控件维度下钻。

数据模型（schema v1）

interface AnalyticsEvent {
  v: number            // schema 版本
  id: string           // 事件 uuid
  ts: number           // epoch ms
  sessionId: string    // 会话 uuid
  type: EventType
  page: { path: string; hash: string }
  target?: ElementRef  // 元素身份
  position?: { x: number; y: number } // 热力图坐标
  depth?: number       // 滚动深度
  visible?: boolean    // 可见性
  inputLength?: number // 输入长度（无内容）
}

架构

┌────────────────────────── browser 半部 ──────────────────────────┐
│ tracker.ts     全局埋点采集（document 级监听）                      │
│ storage.ts     本地环形缓冲 + 设置 + 授权（localStorage）          │
│ HeatmapOverlay 热力图 + 统计面板 + 设置 + 上传入口（shell.overlay）│
│ ConsentModal   上传授权弹窗                                        │
└──────────────────────────────┬───────────────────────────────────┘
                                │ 授权后 fetch(POST)
┌──────────────────────────────▼────── host 半部 ──────────────────┐
│ /dsh-heatmap/ingest   批量上报（本地收集器）                        │
│ /dsh-heatmap/export   导出（JSON/NDJSON）                          │
│ /dsh-heatmap/stats    聚合统计                                     │
│ /dsh-heatmap/sessions 会话时间线（回放/复现）                        │
│ /dsh-heatmap/funnel   漏斗分析（有序步骤转化率）                     │
│ /dsh-heatmap/clear    清空                                         │
│ analytics_export 工具 stats/export/sessions/funnel/clear/upload    │
│ AnalyticsStore     NDJSON 落盘 + 内存环形缓冲 + 漏斗/会话聚合        │
└──────────────────────────────────────────────────────────────────┘

数据默认只在本机流动：采集→本地；上传→（授权后）host 收集器或配置的外部地址。

安装

dsh plugin --profile web add ./dsh-heatmap
# 或使用 dsh-master：dsh_master_install 工具

然后重启 dsh（dsh web 或 dsh --profile web）。重启后页面右下角会出现 🔥 按钮，打开面板即可查看统计、开启热力图。

开发

# 在插件目录内
pnpm install
pnpm run build   # 构建 lib/client.js（browser 半部）
pnpm run typecheck

配置

host 配置（cordis.yml，部署级默认值）

- id: dsh-heatmap
  config:
    enabled: true            # host 收集器与工具开关
    dataDir: ''              # 落盘目录；空则 $DSH_HOME/storages/dsh-heatmap
    maxEvents: 20000         # 环形缓冲上限
    uploadEndpoint: ''       # 统一分析平台上传地址（analytics_export upload 目标）
    consentRequired: true    # 上传是否要求授权（文档化；实际弹窗在 browser 半部）

客户端设置（localStorage，运行时在面板中调整）

设置	默认	说明
热力图模式	关	开启全屏热力图覆盖层
采集埋点	开	总开关
鼠标热力图	关	是否采集悬停坐标（开启会增大数据量）
上传需授权	开	上传前是否弹授权窗
上传地址	空	空 = 同源 host 收集器 `/dsh-heatmap/ingest`

CLI / 外部访问接口

1. Agent 工具（`analytics_export`）

在会话中让 Agent 调用：

动作：stats     聚合统计（事件总数/点击/聚焦/曝光/会话数/按类型分布）
动作：export    导出最近 5000 条事件
动作：sessions  会话时间线（最近 20 个会话的有序事件序列，用于回放/复现）
动作：funnel    漏斗分析（需 steps：有序事件类型数组，如 [session_start, click, input]）
动作：clear     清空收集器数据
动作：upload    上传到 config.uploadEndpoint（统一分析平台）

2. HTTP 路由

curl http://127.0.0.1:PORT/dsh-heatmap/health
curl http://127.0.0.1:PORT/dsh-heatmap/stats
curl http://127.0.0.1:PORT/dsh-heatmap/export?format=json&limit=100
curl http://127.0.0.1:PORT/dsh-heatmap/sessions?limit=20
curl -X POST http://127.0.0.1:PORT/dsh-heatmap/funnel -H 'content-type: application/json' -d '{"steps":["session_start","click","input"]}'
curl -X POST http://127.0.0.1:PORT/dsh-heatmap/ingest -H 'content-type: application/json' -d '{"v":1,"sessionId":"s","sentAt":0,"events":[...]}'
curl -X DELETE http://127.0.0.1:PORT/dsh-heatmap/clear

端口即 DSH 网页服务的端口（客户端与 host 同源）。

统一分析平台对接

预留了三条对接路径，按需选择：

Agent 工具 upload：配置 uploadEndpoint 后，让 Agent 调用 analytics_export（action=upload）把收集器数据批量 POST 到平台。
HTTP 路由：GET /dsh-heatmap/export 拉取原始事件，由你的平台 SDK/脚本转发。
示例适配脚本：examples/push-to-platform.mjs —— 从 /export 拉取、按 mapEvent 适配成平台形状、POST 到 PLATFORM_ENDPOINT（仅需改这一个适配函数）。

DSH_BASE=http://127.0.0.1:3080 \
PLATFORM_ENDPOINT=https://analytics.example.com/ingest \
PLATFORM_API_KEY=sk-xxx \
node examples/push-to-platform.mjs