dsh-heatmap 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# dsh-heatmap
+
+DeepSeek Harness 页面埋点与热力图分析插件。为后续产品设计优化提供量化数据：科学采集页面交互行为，本地展示热力图与统计，预留 CLI 与外部上传接口，上传前强制用户授权。
+
+## 功能一览（在原始需求上补充后的完整设计）
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 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）
+
+```ts
+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 收集器或配置的外部地址。
+
+## 安装
+
+```sh
+dsh plugin --profile web add ./dsh-heatmap
+# 或使用 dsh-master：dsh_master_install 工具
+```
+
+然后重启 dsh（`dsh web` 或 `dsh --profile web`）。重启后页面右下角会出现 🔥 按钮，打开面板即可查看统计、开启热力图。
+
+## 开发
+
+```sh
+# 在插件目录内
+pnpm install
+pnpm run build   # 构建 lib/client.js（browser 半部）
+pnpm run typecheck
+```
+
+## 配置
+
+### host 配置（cordis.yml，部署级默认值）
+
+```yaml
+- 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 路由
+
+```sh
+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 同源）。
+
+## 统一分析平台对接
+
+预留了三条对接路径，按需选择：
+
+1. **Agent 工具 `upload`**：配置 `uploadEndpoint` 后，让 Agent 调用 `analytics_export`（action=upload）把收集器数据批量 POST 到平台。
+2. **HTTP 路由**：`GET /dsh-heatmap/export` 拉取原始事件，由你的平台 SDK/脚本转发。
+3. **示例适配脚本**：[`examples/push-to-platform.mjs`](examples/push-to-platform.mjs) —— 从 `/export` 拉取、按 `mapEvent` 适配成平台形状、POST 到 `PLATFORM_ENDPOINT`（仅需改这一个适配函数）。
+
+```sh
+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
+```
+
+## 隐私与合规
+
+- 采集默认**最小化**：不采集对话正文、不采集输入内容（仅长度）、不采集 PII。
+- 数据默认只在用户本机（localStorage / 本地 NDJSON）。
+- 上传动作前弹出授权弹窗，明示「上传什么、上传到哪里、不含对话内容」，用户确认后才发送。
+- 可随时「清除本地」或在 host 侧 `clear` 删除收集器数据。
+
+## 后续演进（预留）
+
+- 可视化会话回放：在面板内把 `sessions` 时间线渲染成逐步重放。
+- 曝光时长：为 `impression` 记录进入/离开视口时长（当前只记首次曝光）。
+- 性能埋点：`navigation`/`resource` 时序。
+
+> 生成自 DSH-Master（dsh-master）脚手架并扩展。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-heatmap bundle layer.
+#
+# Inserted by the dsh loader when this bundle is part of a profile's
+# dsh.profile.bundles list (see `dsh plugin --profile <name> add <this-dir>`).
+# This row activates the host plugin (src/index.ts) and, through the package's
+# `dsh.client` manifest, registers the client-side heatmap bundle (lib/client.js)
+# into the client boot graph.
+- insert:
+    - id: dsh-heatmap
+      name: dsh-heatmap

package/examples/push-to-platform.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * 统一分析平台对接示例（dsh-heatmap）。
+ *
+ * 用法：
+ *   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
+ *
+ * 作用：从 DSH host 收集器（/dsh-heatmap/export）拉取埋点事件，映射成目标
+ * 平台的通用事件形状，再 POST 到平台。`mapEvent` 是唯一的「适配点」——对接
+ * 不同平台时只需改它，其余逻辑不变。
+ *
+ * 说明：这只是示例脚本。生产环境可复用 host 侧 `analytics_export upload`
+ * 动作（走 config.uploadEndpoint），或把本脚本改造成定时任务 / SDK。
+ */
+
+const DSH_BASE = (process.env.DSH_BASE ?? 'http://127.0.0.1:3080').replace(/\/$/, '')
+const PLATFORM_ENDPOINT = process.env.PLATFORM_ENDPOINT ?? ''
+const PLATFORM_API_KEY = process.env.PLATFORM_API_KEY ?? ''
+
+if (PLATFORM_ENDPOINT === '') {
+  console.error('缺少 PLATFORM_ENDPOINT（目标平台接收地址）')
+  process.exit(1)
+}
+
+/**
+ * 适配点：把 dsh-heatmap 事件映射成目标平台的事件形状。
+ * 这里给的是通用形状（type / distinctId / properties / timestamp），
+ * 对接真实平台时按平台文档改这里的字段即可。
+ */
+function mapEvent(e) {
+  return {
+    event: e.type,
+    distinctId: e.sessionId,
+    timestamp: e.ts,
+    properties: {
+      page: e.page?.path ?? '',
+      hash: e.page?.hash ?? '',
+      elementId: e.target?.elementId,
+      tag: e.target?.tag,
+      role: e.target?.role,
+      text: e.target?.text,
+      x: e.position?.x,
+      y: e.position?.y,
+      depth: e.depth,
+      visible: e.visible,
+      inputLength: e.inputLength,
+      source: 'dsh-heatmap',
+    },
+  }
+}
+
+async function main() {
+  const exportUrl = `${DSH_BASE}/dsh-heatmap/export?format=json`
+  console.log(`拉取事件：${exportUrl}`)
+  const res = await fetch(exportUrl)
+  if (!res.ok) {
+    console.error(`导出失败：HTTP ${res.status}`)
+    process.exit(1)
+  }
+  const { events } = await res.json()
+  if (!events?.length) {
+    console.log('没有待上传的事件。')
+    return
+  }
+
+  const payload = {
+    source: 'dsh-heatmap',
+    sentAt: Date.now(),
+    events: events.map(mapEvent),
+  }
+
+  console.log(`上传 ${payload.events.length} 条 → ${PLATFORM_ENDPOINT}`)
+  const up = await fetch(PLATFORM_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(PLATFORM_API_KEY !== '' ? { authorization: `Bearer ${PLATFORM_API_KEY}` } : {}),
+    },
+    body: JSON.stringify(payload),
+  })
+  if (!up.ok) {
+    console.error(`平台返回 HTTP ${up.status}：${await up.text()}`)
+    process.exit(1)
+  }
+  console.log('上传完成。')
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})