# PRD：电子木鱼桌宠插件（Wooden Fish Pet）

- 版本：v0.1（需求确认稿）
- 日期：2026-08-18
- 平台：DeepSeek Harness Web GUI（动态 Cordis 插件）

---

## 1. 背景与目标

用户希望在 DeepSeek Harness 的 Web 界面里拥有一只「桌宠」。它不是卡通人物，而是一个**电子木鱼**：

- 每天可以点击敲击，获得仪式感反馈；
- 系统自动按天记录点击次数；
- 设置界面可以看到每日点击次数的趋势。

目标：一个「能敲、能记、能看趋势」的禅意小工具，数据完全本地化。

## 2. 核心用户故事

| 角色 | 故事 |
|---|---|
| 用户 | 页面上有一只悬浮的木鱼，随时点一下就有敲击反馈 |
| 用户 | 系统自动按天记录我的敲击次数，跨天、跨重启不丢 |
| 用户 | 在设置页看到今日次数、累计次数、连续天数、每日趋势图 |

## 3. 功能需求

### FR1 悬浮木鱼（桌宠形态）✅ 已确认：可拖动
- 挂在页面**全局悬浮层**（shell.overlay），浮在所有内容之上。
- **可自由拖动**到任意位置；拖动与点击自动区分（移动距离 < 5px 视为点击敲击）。
- 敲击视觉反馈：
  1. 木鱼本体短促晃动；
  2. 木槌向下敲击动作；
  3. 飘出「+1」动效。
- 悬停显示今日次数：鼠标悬停木鱼时，上方浮现「今天已敲 N 次」气泡（0.15s 淡入、带小箭头）；不悬停不显示，拖动时不显示。
- 默认位置：页面右下角（拖动后记住本次会话位置；刷新后回默认位）。

### FR2 点击计数与按天累计
- 每次敲击令「当天」计数 +1，按本地日期 `YYYY-MM-DD` 分桶。
- **持久化**：写入本地 JSON 文件 `~/.dsh/wooden-fish-data.json`，跨天、跨进程重启保留。
- 跨零点自动进入新的一天，计数自然重计；历史天数全部保留。

### FR3 设置页统计看板（设置 → 电子木鱼）
- 新增独立设置页「电子木鱼」（settings.section）。
- 页面顶部放一个**可点击的小木鱼**：在设置页里也能敲击计数。
- 统计卡片：**今日敲击 / 累计敲击 / 连续天数**。
- **每日趋势图**：柱状图，支持 7 / 14 / 30 天切换；无敲击的日期显示为灰柱；悬停显示具体次数与日期。
- **悬浮木鱼显示/隐藏开关**（不想看到桌宠时可关掉，随时在设置页重新打开）。

## 4. 非功能需求

- **技术形态**：动态 Cordis 插件（Host 计数存储 + Client UI 双端）。
- **性能**：敲击即时响应（内存缓存），文件写入 600ms 防抖批量落盘。
- **数据安全**：纯本地、纯数字，无任何网络请求。
- **生命周期**：动态插件随 DSH 进程重启而失效，需重新激活；**数据文件保留**，重新激活后历史趋势完整。
- **沙箱限制**（当前动态插件 Client 沙箱不暴露 `window` / `document` / `AudioContext` / `localStorage`）：
  - ❌ v1 无敲击音效，纯视觉反馈（后续做成正式安装插件可补音效）；
  - ❌ 拖动位置不持久化（刷新后回到默认右下角）；
  - ❌ 无 localStorage（开关状态默认显示，会话内记忆）。

## 5. 技术方案概要

```
┌───────────────────────── Client（浏览器）─────────────────────────┐
│  shell.overlay ──→ 悬浮木鱼组件（拖动 + 点击敲击 + 动画）          │
│  settings.section ──→ 「电子木鱼」设置页（统计卡片 + 趋势图 + 开关） │
└──────────────────────────────┬──────────────────────────────────┘
                          host.call (wf.knock / wf.summary)
┌──────────────────────────────┴──────────────────────────────────┐
│  Host（Node 进程）                                                │
│  harness.handle('wf.knock')   今日+1 → 返回统计                    │
│  harness.handle('wf.summary') 读取统计（今日/累计/连续/近30天序列）  │
│  fs 服务 ──→ ~/.dsh/wooden-fish-data.json                        │
└──────────────────────────────────────────────────────────────────┘
```

- 数据模型：`{ version: 1, days: { "2026-08-18": 5, ... } }`
- RPC 返回：`{ today, total, streak, series: [{date, count} × 30] }`
- 连续天数：从今天（今天为 0 则从昨天）往前数连续有敲击的天数。

## 6. UI 设计方向（待 UI 设计阶段细化）

候选视觉风格（**需确认一项**）：

- **A. 禅意木质风**（推荐）：暖棕木色、圆润轮廓、柔和阴影、深棕描边，贴合「木鱼」材质感；趋势图用暖橙/木色系。
- **B. 极简线条风**：单色线条图标风，弱化材质，融入现有深色/浅色主题。
- **C. 像素复古风**：8-bit 像素木鱼，点击冒像素粒子。

## 7. 范围外（后续迭代）

- 敲击音效（需脱离动态插件沙箱，做成正式安装插件）
- 拖动位置持久化
- 成就 / 里程碑（108 连击、每日目标等）
- 数据导出 / 重置

## 8. 验收标准

- [ ] 页面上出现可拖动的木鱼；点击有晃动 + 木槌 +「+1」反馈
- [ ] 悬停木鱼时显示「今天已敲 N 次」气泡；刷新页面后次数保持
- [ ] 设置页出现「电子木鱼」入口；展示 3 项统计 + 趋势图（7/14/30 切换）
- [ ] 跨零点分桶正确；DSH 重启后重新激活插件，历史数据仍在
- [ ] 可随时在设置页隐藏/恢复悬浮木鱼
- [ ] 运行无报错，可正常停用/卸载