# dsh-cursor-theme 需求文档

> 项目：dsh-cursor-theme —— 在 DeepSeek Harness 中自定义鼠标各状态图案
> 版本：v0.1（草案）
> 日期：2026-08-20
> 关联文档：[可行性分析](feasibility.md)

---

## 1. 背景与目标

### 1.1 背景

DeepSeek Harness（DSH）是长时运行、界面元素密集的 AI 工作台：会话列表、输入框、工具调用、拖拽、加载中、可点击按钮……用户每天长时间盯着它操作。默认的系统光标无法表达个性，也难以在密集 UI 中快速区分"可点击 / 可输入 / 等待中"。

### 1.2 目标

- **V1（MVP）**：用户可在 DSH 设置页为鼠标的每种 UI 状态（默认、点击、文本、等待、帮助、禁止等）自定义图案，实时生效、跨会话保存，并支持一键恢复系统默认。
- **V2（远期）**：主题包一键套用、素材市场、系统级光标（Windows）。

### 1.3 非目标（明确不做）

- 不修改 Windows/macOS 系统级指针（V2 仅 Windows 可评估）
- 不做光标动画（ANI/GIF 动画帧，Chromium 不支持）
- 不面向移动端触摸设备

---

## 2. 用户画像与场景

### 2.1 用户画像

| 画像 | 描述 | 核心诉求 |
|---|---|---|
| 个性化玩家 | 喜欢给一切界面换肤 | 好看、酷、能分享主题 |
| 效率工作者 | 长时间用 DSH 编码/写作 | 清晰区分各状态，减少误操作 |
| 无障碍用户 | 低视力/色弱 | 高对比、跟随系统主题 |

### 2.2 典型场景

1. 用户打开 设置 → 插件 → 光标主题，为"链接悬停"换成醒目的手型图案，保存后立即生效。
2. 用户上传一张自制的 PNG 箭头，调整热区到箭头尖端，之后所有"默认"状态都显示它。
3. 用户启用"跟随系统主题"，暗色模式下光标自动换成浅色描边版本。
4. 用户在 DSH Desktop 里装插件后无需重启即可看到新光标（HMR）。

---

## 3. 用户故事

| ID | 故事 | 优先级 |
|---|---|---|
| US-1 | 作为用户，我希望为每个鼠标状态单独选择图案，以便按需定制 | P0 |
| US-2 | 作为用户，我希望上传 PNG/CUR 图片作为光标图案，以便使用自己的素材 | P0 |
| US-3 | 作为用户，我希望调整光标热区（点击点），以便点击精确 | P0 |
| US-4 | 作为用户，我希望调整光标显示大小，以便在 4K 屏上看得清 | P0 |
| US-5 | 作为用户，我希望改动后立即生效、重启后依然保留，以便零成本使用 | P0 |
| US-6 | 作为用户，我希望一键恢复系统默认光标，以便随时还原 | P0 |
| US-7 | 作为用户，我希望把整套配置保存为"主题"并一键套用，以便快速换风格 | P1 |
| US-8 | 作为用户，我希望导出/导入我的光标主题 JSON，以便分享或备份 | P1 |
| US-9 | 作为用户，我希望光标跟随 DSH 亮/暗主题自动切换，以便视觉统一 | P1 |
| US-10 | 作为用户，我希望内置素材库提供多种风格（极简/复古/霓虹/高对比），以便开箱即用 | P1 |
| US-11 | 作为用户，我希望在 Windows 上把自定义光标应用到整个系统，以便系统级统一 | P2（远期） |

---

## 4. 功能需求

### 4.1 光标状态模型（P0）

插件识别并覆盖以下 UI 状态（CSS cursor 关键字映射）：

| 状态 | 触发场景 | 默认关键字 | 优先级 |
|---|---|---|---|
| default | 普通区域 | `default` | P0 |
| pointer | 链接 / 按钮 / 可点击 | `pointer` | P0 |
| text | 输入框 / 可编辑文本 | `text` | P0 |
| wait | 全局等待（如生成中） | `wait` | P0 |
| help | 帮助提示 | `help` | P1 |
| not-allowed | 禁止操作 | `not-allowed` | P0 |
| grab / grabbing | 拖拽会话/卡片 | `grab` / `grabbing` | P1 |
| progress | 后台忙碌可继续操作 | `progress` | P1 |
| cell | 表格单元格 | `cell` | P2 |
| copy | 可复制 | `copy` | P2 |
| move / resize* | 拖拽 / 调整大小 | `move`, `n-resize`, `ew-resize` 等 | P2 |

**规则**：
- 每个状态可独立设置：图案、热区、尺寸（继承全局默认或单独覆盖）。
- 未单独配置的状态使用全局默认光标（`auto`/`default`），不强制覆盖。
- 覆盖通过注入的全局样式实现：`:root { cursor: ... }` + 按状态元素选择器（如 `a, button { cursor: url(...) }`）。

### 4.2 图案来源（P0-P1）

| 来源 | 支持 | 优先级 | 说明 |
|---|---|---|---|
| 内置素材库 | ✅ | P1 | 打包进插件，多风格、多尺寸档（16/24/32/48） |
| 本地上传 | ✅ | P0 | PNG（推荐）/ CUR；前端校验格式与尺寸 ≤128px |
| 粘贴/URL 引用 | ⚠️ | P2 | 受 CSP 限制，需走资源代理 |

### 4.3 热区编辑器（P0）

- 可视化：在图案上显示十字准线，拖动设置点击点；或输入 X/Y 数值。
- 默认热区：PNG 无内嵌热区时默认 (0,0)，并给出提示；CUR 读取内嵌热区。
- 与尺寸联动：热区随图案缩放比例换算。

### 4.4 尺寸与缩放（P0）

- 内置档位：16 / 24 / 32 / 48（>128 禁止，防止被浏览器忽略）。
- 支持全局默认尺寸 + 单状态覆盖。
- 高 DPI 提示：缩放后热区同步换算。

### 4.5 主题系统（P1）

- 主题 = 一组"状态 → 图案/热区/尺寸"配置 + 元数据（名称、作者、跟随亮暗）。
- 内置示例主题：极简（黑白）、复古像素、霓虹、高对比无障碍。
- 一键套用：切换主题立即生效。
- 跟随系统：每个主题可含 light/dark 两套变体，随 DSH 主题自动切换。

### 4.6 持久化（P0）

- 配置保存到 profile（经 `dsh-settings` / 客户端 store），重启保留。
- 配置变更写盘采用原子写入（复用 dsh-atomic-write 语义），损坏时回退上次有效配置。

### 4.7 恢复与开关（P0）

- 全局开关：启用/停用全部自定义光标（停用 = 注入系统默认规则）。
- 一键还原：清空全部状态配置，恢复系统默认；若之前已应用到系统，同时同步还原系统级光标（Windows 还原注册表方案 / macOS 停止覆盖层）。
- 单状态重置：仅清空该状态。

### 4.8 导出/导入（P1）

- 导出为 JSON（含素材 base64 内嵌，保证跨机器可用）。
- 导入校验：结构校验 + 素材格式/尺寸校验，失败给出可读错误，不影响现有配置。

### 4.9 系统级光标（P2，远期，仅 Windows）

- 通过 DSH Desktop 宿主桥接写 `HKCU\Control Panel\Cursors` + 广播 `WM_SETTINGCHANGE`。
- 需要用户显式授权；UI 明示"影响整个 Windows 系统"。

---

## 5. 非功能需求

| 类别 | 需求 | 优先级 |
|---|---|---|
| 性能 | 样式注入仅一次；光标图片 ≤48px 时对渲染无感知影响 | P0 |
| 兼容性 | 适配 DSH Web + DSH Desktop（Electron）；Chromium 全系 | P0 |
| 无障碍 | 提供高对比主题；不删除 fallback 关键字（`cursor: url(...) , auto` 必须带回退） | P0 |
| 安全 | 上传文件仅读取为图片数据，不执行；素材不请求外网（除 P2 URL 引用） | P0 |
| 国际化 | 文案走 dsh 客户端 locale 机制，中英双语 | P1 |
| 可维护性 | 状态清单、素材清单、主题清单均用声明式配置（JSON）驱动 | P1 |

---

## 6. 界面流程（草案）

```
设置 → 插件 → 光标主题
├── [全局开关] 启用自定义光标
├── [跟随系统主题] (P1)
├── 主题区 (P1)：当前主题 / [套用主题...] / [导出] / [导入]
├── 状态列表（default / pointer / text / wait / ...）
│    └─ 点击某状态 →
│        ├─ 图案选择：内置素材库 | 上传图片
│        ├─ 热区编辑器（十字准线 + X/Y 数值）
│        ├─ 尺寸选择（16/24/32/48）
│        └─ 实时预览（光标直接变成该图案悬停预览）
├── 预览面板：把所有状态的成品光标排成一行，鼠标悬停逐个查看
└── [恢复系统默认] / [重置当前状态]
```

---

## 7. 数据结构（草案）

```jsonc
// profile 中保存的配置（dsh-settings 域）
{
  "schema": 1,
  "enabled": true,
  "followSystemTheme": false,
  "defaultSize": 32,
  "fallback": "auto",
  "activeTheme": "minimal",
  "states": {
    "default":     { "image": "data:image/png;base64,...", "hotspot": [0, 0] },
    "pointer":     { "image": "data:image/png;base64,...", "hotspot": [4, 4] },
    "text":        { "image": "data:image/png;base64,...", "hotspot": [4, 4] },
    "wait":        { "image": "data:image/png;base64,...", "hotspot": [8, 8] },
    "not-allowed": { "image": "data:image/png;base64,...", "hotspot": [8, 8] }
    // 其余状态省略 = 使用系统默认
  }
}

// 主题包（导出/导入 JSON）
{
  "schema": 1,
  "name": "霓虹",
  "author": "user",
  "variant": { "light": { ...同上结构... }, "dark": { ... } },
  "createdAt": "2026-08-20T00:00:00Z"
}
```

---

## 8. 验收标准（MVP）

1. **安装**：`dsh plugin --profile web add dsh-cursor-theme` 后，刷新/重启 DSH，设置页出现"光标主题"入口。
2. **覆盖**：为 default、pointer、text、wait、not-allowed 五个状态各设置 PNG 图案后，界面上对应交互（普通区/按钮/输入框/加载中/禁用）光标均变为自定义图案。
3. **热区**：热区设为图案尖端后，点击按钮命中精确（可在测试页验证）。
4. **持久化**：修改配置 → 刷新页面/重启 DSH → 配置仍在且生效。
5. **还原**：一键还原后所有光标恢复系统默认，且注入的全局样式被移除。
6. **兜底**：图案加载失败或格式非法时，光标回退为 `auto`，界面不报错、不白屏。
7. **性能**：页面无卡顿；样式只注入一次（`data-plugin-css` 去重）。
8. **安全**：上传非图片/超大文件被拒绝并给出提示；无外网请求。

---

## 9. 里程碑

| 阶段 | 内容 | 状态 |
|---|---|---|
| M0 骨架 | 工程脚手架、bundle 接入 profile、空客户端注入 | ✅ 完成 |
| M1 注入核心 | 全局样式注入 + 状态映射 + 配置持久化 | ✅ 完成 |
| M2 设置界面 | 状态列表、图案上传、热区、尺寸、预览、还原 | ✅ 完成（内联样式版） |
| M3 打磨 | 素材库、主题系统、导出导入、国际化增强、无障碍 | ✅ 完成 |
| M4 创意与 AI | 像素角色/梗图形状库（25 形状）、13 套创意主题、AI 主题提示词生成 + 会话一键发送 + JSON 导入渲染 | ✅ 完成 |
| V1 发布 | npm 发布 + 文档 + 上架（awesome-dsh-plugin） | ⏳ 待做 |
| V2（远期） | 系统级光标（Windows 桌面桥接） | 待评估 |

> 实现记录：客户端经 esbuild 打包为单文件 bundle（external 仅 react / @deepseek-ai/*，宿主 __ModuleLoader__ 注入，`jsx: automatic` 防 `React is not defined`）；设置界面注册于 `settings.plugins.tab`（对齐 deepseek-harness-desktop 官方形态）；配置写入走 `scope.set('states', {...})` 整对象（SettingsScopeController.set 为单字段路径）；AI 生成主题 = 形状库（共享像素矩阵，Node 生成器与浏览器 canvas 渲染同一数据源）+ 配色 → PNG data URL。

---

## 10. 竞品分析（市场调研 2026-08-20）

**调研范围**：dshmarket 精选列表（awesome-dsh-plugin，839 个插件，快照 2026-08-16），关键词覆盖 `cursor / mouse / pointer / crosshair / 光标 / 鼠标 / 指针`，并全量核对 theme / ui / fun 三个类目（100+ 个插件）。

### 10.1 结论：无直接竞品 ✅

市场上**不存在**提供"按 UI 状态自定义鼠标图案 + 上传 + 热区编辑"能力的插件。本插件是该细分领域的空白点。

### 10.2 最接近的两个插件

| 插件 | 类目 | 与光标定制的关系 | 差异点 |
|---|---|---|---|
| `dsh-skin-digital-arcade` | theme | 数码电玩 HUD 皮肤附带**一个固定**的十字准星光标（custom crosshair cursor） | 光标是皮肤附赠品，用户不能按状态配置、不能上传图案；本插件是独立、可配置的光标系统 |
| `pet-whale` | fun | 桌宠"光标避让"（cursor avoidance）动画 | 是宠物躲避鼠标的动画行为，与光标图案完全无关 |

### 10.3 间接信号与启示

1. **需求真实存在**：`dsh-skin-digital-arcade` 主动给皮肤加十字准星光标，说明"光标是个性化的一部分"是被社区验证过的需求——但没人做成独立的可配置插件。
2. **生态成熟可借鉴**：主题/皮肤类插件（30+ 个，如 `dsh-theme-plugin`、`dsh-dream-skin`、`dsh-client-ui-skins`）已沉淀成熟的注入机制（`data-plugin-css` 样式注入、设置页插槽、主题包导入导出、localStorage/dsh-settings 持久化）——本插件的技术方案与它们同构，可行性已被生态验证。
3. **差异化定位**：现有插件是"皮肤附带光标"，本插件是"光标独立定制 + 按状态 + 用户上传素材"，功能互补、不冲突，可作为独立插件或未来与皮肤类插件联动（例如皮肤包可引用光标主题）。

### 10.4 对产品的影响

- 无需避开任何现有产品；MVP 可自信立项。
- 需求文档 §4.5 的"主题系统"可参考皮肤类插件的主题包格式（导入/导出 JSON、亮暗双变体）保持生态惯例一致。
- 上架时在 awesome-dsh-plugin 的分类建议为 `theme`（或新增 `cursor` 子类），与皮肤类插件相邻曝光。

---

## 11. 开放问题（需确认）

| # | 问题 | 影响 |
|---|---|---|
| 1 | 是否需要"光标跟随鼠标移动的实时预览"（页面级浮层）还是仅列表预览即可？ | M2 界面复杂度 |
| 2 | 内置素材库版权：用 CC0 素材还是自制？ | 发布合规 |
| 3 | 是否优先支持 DSH Desktop（Electron）还是纯 `dsh web`？两者机制一致，但测试环境不同 | 测试计划 |
| 4 | V2 系统级光标是否真的需要？（工作量集中在 Windows 注册表桥接） | 路线图 |
| 5 | 插件名称是否确定（`dsh-cursor-theme`）？ | 发布名 |

---

*本文档为需求草案，欢迎在评审后修订。*