@dsh-external/dsh-client-ui-furina-desk-pet

Readme

# 芙宁娜卡通大头桌宠 · Furina Desk Pet

为 **DeepSeek Harness Web GUI** 制作的可移植客户端插件：一只漂浮在页面上的
卡通大头芙宁娜桌宠，带点击特效与好感度系统。

> 纯展示层客户端插件：不注入任何服务、不发 Cordis 事件、不触碰模型请求；
> 卸载即还原（所有 DOM / CSS 写入都由 Cordis effect 销毁器收回）。

> ⚠️ **版权与免责声明**：本插件的芙宁娜图片素材系发布者**从网络公开资源
> 收集**，**无法核实其原始版权归属**；本项目**不涉及任何商业行为**，
> 仅作学习与同好分享。**如相关素材存在侵权，请联系发布者
> （提交 GitHub Issue 或联系仓库维护者），将立即删除相关内容。**
> 素材来源明细见 `NOTICE.md`。

## ✨ 特性

- **点击特效**：点击芙宁娜会弹跳 + 迸发爱心粒子 + “+1” 飘字 + 随机台词气泡；
  约 8% 概率触发**金色暴击**（好感度 +3）。
- **好感度系统**：宠物下方常驻好感度条（❤ 数值 + 等级名 + 进度），
  点击即可涨好感度，随等级成长并触发升级庆祝：
  `初识 → 相识 → 熟悉 → 亲密 → 挚友 → 水神的宠儿`。
- **可拖拽**：按住芙宁娜拖动到任意位置（拖拽时切换惊讶表情），位置按
  视口百分比持久化，窗口缩放自动钳制在可视区内。
- **右键菜单**：重置好感度（二次确认）/ 收起·展开好感条 / 暂时隐藏
  （右下角“芙”按钮唤回）。
- **本地持久化**：好感度、位置、紧凑模式写入 localStorage
  （键 `dsh-furina-desk-pet.v1`），刷新页面 / 跨标签页自动同步。
- **零运行时依赖**：两张透明 chibi 表情以 data URI 内联进 bundle，
  不依赖任何外部图片 URL 或资源服务器。
- 支持键盘（Tab 聚焦后 Enter/空格 摸摸头）、prefers-reduced-motion 降级。

## 🖼 插图预览

插件内置的两张透明 chibi 表情（构建时以 data URI 内联进 bundle，
运行时不依赖任何外部图片；下方引用的是仓库内 `assets/source/` 原始文件，
GitHub 会直接渲染仓库内相对路径的图片）：

<table>
  <tr>
    <td align="center" bgcolor="#eef4fb">
      <img src="assets/source/furina-happy.webp" width="170" alt="芙宁娜 · 开心" />
      <br /><sub>开心 · 常驻表情 / 点击时</sub>
    </td>
    <td align="center" bgcolor="#eef4fb">
      <img src="assets/source/furina-shocked.webp" width="170" alt="芙宁娜 · 惊讶" />
      <br /><sub>惊讶 · 拖拽时 / 升级庆祝时</sub>
    </td>
  </tr>
</table>

## 🚀 安装（移植到任意 DeepSeek Harness）

插件遵循 dsh 官方插件形态（dsh.bundle + dsh.client 双面声明），
可安装到任意一个 profile（下例为 web）。

### 方式一：自己一条命令搞定（推荐）

```sh
dsh plugin --profile web add "github:fykuang02/furina-desk-pet"
```

然后重启 web 界面（`dsh web`）并刷新浏览器页面即可。

### 方式二：让你的 DeepSeek Harness 帮你安装

如果你是 DeepSeek Harness 用户但不想自己敲命令，直接把下面这段话发给
**你自己的 harness**（Chat 或 Web 界面里的 AI 助手），它会自己完成
克隆、安装与验证：

> 请帮我安装 GitHub 上的芙宁娜桌宠插件（仓库 fykuang02/furina-desk-pet）
> 到我的 dsh web 界面：克隆该仓库，然后用
> `dsh plugin --profile web add` 或等效方式装进 web profile 并让它生效。
> 如果本机无法直连 GitHub，请按你环境里的网络方案（镜像/代理）克隆。

### 方式三：克隆后本地链接

```sh
git clone https://github.com/fykuang02/furina-desk-pet.git
dsh plugin --profile web add link:"<克隆目录>/furina-desk-pet"
```

### 只想下载源码（不安装插件）

```sh
git clone https://github.com/fykuang02/furina-desk-pet.git
# 或直接下载 ZIP：
# https://github.com/fykuang02/furina-desk-pet/archive/refs/heads/main.zip
```

> 说明：`dsh plugin add` 本质是向 profile 的 pnpm 依赖里加入本包；
> 本包通过 dsh.bundle.patch（cordis.patch.yml）自动把客户端条目
> `furina-desk-pet` 插入插件花名册，因此**安装即生效，卸载即还原**。

### 热更新（不重启 dsh，适用于已经跑着的实例）

如果 dsh web 已经在本机运行、不想重启进程：把本包用 junction/符号链接
挂进 profile 的 node_modules（例如
`<dsh-home>/profiles/web/node_modules/@dsh-external/dsh-client-ui-furina-desk-pet`），
然后在 `<dsh-home>/profiles/web/cordis.patch.yml` 末尾追加：

```yaml
- insert:
    - id: furina-desk-pet
      name: '@dsh-external/dsh-client-ui-furina-desk-pet'
```

profile 的补丁层由 Cordis HMR 监听，保存后数秒内生效，刷新浏览器即可。
（注意：这种方式与“方式 A/B”二选一，不要叠加使用，避免条目重复。）

### 卸载

```sh
dsh plugin --profile web remove "@dsh-external/dsh-client-ui-furina-desk-pet"
```

## 🖱 使用说明

| 操作 | 效果 |
| --- | --- |
| 单击芙宁娜 | 好感度 +1（暴击 +3）、爱心粒子、弹跳、台词气泡 |
| 按住拖动 | 移动位置（惊讶表情），松手记住位置 |
| 右键 | 打开菜单：重置好感度 / 收起好感条 / 暂时隐藏 |
| 连续点击 | 每次点击都涨好感度（粒子特效有 250ms 节流防刷屏） |

## 🖼 独立预览（无需 dsh）

直接用浏览器打开 `preview/demo.html` 即可体验（`preview/pet-standalone.js`
由构建脚本生成，内置模块加载协议的模拟层）。

## 🛠 开发与构建

零依赖构建链，不需要 npm install：

```sh
node build/build.mjs   # 生成 lib/client.js、lib/index.js、preview/pet-standalone.js
node tests/smoke.mjs   # Node 冒烟测试（自带极简 DOM shim，37 项断言）
```

- 桌宠全部逻辑在 `src/client/index.js`（原生 JS，无框架、无导入）。
- 换表情图：替换 `assets/source/furina-happy.webp` / `furina-shocked.webp`
  后重新构建即可（建议 300×300 以上、透明背景的方形 webp/png）。
- 改台词、等级阈值、暴击率：编辑 `src/client/index.js` 顶部的常量表。

## 📁 目录结构

```
furina-desk-pet/
├── package.json          # dsh.bundle.patch + dsh.client 声明
├── cordis.patch.yml      # 把客户端条目插入插件花名册
├── src/
│   ├── index.js          # 主机侧入口（无行为）
│   └── client/index.js   # 桌宠全部客户端逻辑
├── build/build.mjs       # 零依赖构建脚本（内联素材 + 包装 bundle）
├── lib/                  # 构建产物（client.js / index.js，随仓库分发）
├── assets/source/        # 原始素材（透明 chibi 表情）
├── preview/              # 独立演示页（demo.html）
└── tests/                # 冒烟测试 + 极简 DOM shim
```

## ⚖ 许可与版权

- 插件**代码**：MIT License（见 `LICENSE`）。
- **素材**（`assets/source/` 两张 chibi 表情）：系从**网络公开资源收集**
  （原神维基 Genshin Impact Wiki），发布者**不确定其原始版权归属**；
  来源与链接详见 `NOTICE.md`。角色“芙宁娜”及其形象版权归
  **© miHoYo / HoYoverse** 所有。
- 本项目是**非商业同人分享**，不进行任何商业行为；请勿将本仓库用于商业用途。
- **如相关素材存在侵权，请联系发布者（提交 GitHub Issue 或联系仓库维护者），
  发布者收到通知后将立即删除相关内容。**