niulai-pet

Readme

# 牛来桌宠 (Niulai Pet)

一个无边框、透明、置顶的 **A股桌面宠物**。点击桌宠即可获取 A股实时涨跌幅：

- **上涨** → 播放 `niulai.mp3`（牛来了！🔴）
- **下跌** → 播放 `mama.mp3`（妈呀！🟢）

基于 Electron 构建，同时以 **DSH bundle** 形式打包，可作为插件安装进任意 DSH profile。

## 效果预览

| 正常状态 | 点击后(说话) |
|---|---|
| <img src="assets/niu.png" width="150" alt="正常状态"> | <img src="assets/niu_speek.png" width="150" alt="说话状态"> |

---

## 功能特性

- ✅ 正常状态显示 `./assets/niu.png`，点击切换为 `./assets/niu_speek.png`（带弹跳动画）
- ✅ 调用免费财经 API 获取 A股实时涨跌幅（上证指数，可配置）
- ✅ 点击后弹出气泡展示名称 / 涨跌幅 / 现价 / 涨跌额（A股红涨绿跌）
- ✅ 上涨 / 下跌播放不同音效，音频异步预加载
- ✅ 无边框 + 透明窗口，只显示宠物剪影
- ✅ 支持拖拽到桌面任意位置，位置自动记忆
- ✅ 窗口置顶，常驻其他窗口之上
- ✅ 最小化到系统托盘（单击托盘图标切换显示/隐藏）
- ✅ 可选开机自启（开发模式可用，打包后更稳定）

---

## 目录结构

```
niulai/
├── assets/                 # 素材(打包进 asar，路径自动解析)
│   ├── niu.png             # 正常表情(已转透明)
│   ├── niu_speek.png       # 说话表情(已转透明)
│   ├── niulai.mp3          # 上涨音效
│   ├── mama.mp3            # 下跌音效
│   └── original/           # 原始(白底)图片备份
├── build/
│   └── icon.png            # 应用图标(由透明图自动生成)
├── scripts/
│   ├── make-transparent.cjs # 白底抠图脚本(可重复执行)
│   └── build.mjs            # 打包脚本(自动配置国内镜像)
├── src/
│   ├── main.js             # Electron 主进程(窗口/托盘/拖拽/自启/IPC)
│   ├── preload.cjs         # contextBridge 安全桥接
│   ├── stock.js            # A股行情获取(东方财富 + 腾讯备用)
│   ├── renderer/           # 渲染进程(UI/动画/音效)
│   └── pet/index.js        # DSH/Cordis 插件入口(拉起桌宠)
├── cordis.patch.yml        # DSH bundle patch 清单
├── package.json
└── README.md
```

---

## 环境要求

- Node.js ≥ 20（推荐 20/22/24）
- npm 或 pnpm
- Windows 10/11、macOS、Linux（桌面环境）

---

## 一、依赖安装

```bash
# 在项目根目录
npm install
```

> 国内网络建议配置 Electron 镜像加速（项目已内置 `.npmrc`，也可用环境变量）：
>
> ```powershell
> # PowerShell（等价于 .npmrc 配置；npm 11 已不接受 `npm config set` 写自定义键）
> $env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
> $env:ELECTRON_BUILDER_BINARIES_MIRROR = "https://npmmirror.com/mirrors/electron-builder-binaries/"
> npm install
> ```
>
> 项目内 `.npmrc` 已配置 electron 安装镜像；electron-builder 的打包镜像由 `scripts/build.mjs` 自动设置。海外网络可删除 `.npmrc`。

## 二、运行

```bash
npm start
```

启动后宠物出现在屏幕右下角，可拖动；点击宠物查看行情并播放音效；右键托盘图标可隐藏/刷新/退出。

## 三、打包分发

```bash
npm run pack     # 免安装目录版 → release/win-unpacked/
npm run dist     # 安装包(NSIS) → release/*.exe
```

`开机自启` 在开发模式与打包后均可用；打包后是独立 exe，不依赖源码目录，更稳定。

---

## 四、作为 DSH 插件安装

本包声明了 `dsh.bundle.patch`，可作为插件安装进任意 DSH profile（推荐常驻型的 `web`）：

```bash
# 在项目根目录执行(相对路径会锚定到当前目录)
dsh plugin --profile web add .
```

安装成功后，桌宠会**随 profile 启动**，请按以下步骤操作：

1. **先完全退出正在运行的桌宠**（右键托盘图标 →「退出」）。桌宠是**单实例**应用：已有实例运行时，新启动的实例只会唤起旧窗口，不会重复出现新宠物。
2. **重启该 profile**：在运行 `dsh web` 的终端按 `Ctrl+C` 停止，再重新执行 `dsh web`。
3. 重启后桌宠窗口会自动出现在桌面；profile 退出时桌宠一并关闭。

**如何确认是否生效**：重启 `dsh web` 后，它的终端里会出现一行日志：

```
[niulai-pet] 已拉起桌宠进程 (pid=12345)
```

如果启动失败，会看到 `[niulai-pet] 启动失败: ...` 或 `[niulai-pet] 未找到 electron ...` 的警告。

**常见问题**：

- **重启 dsh 后没有反应**：先看 dsh 终端日志里有没有 `[niulai-pet]` 警告。最常见原因是 ① 安装后没有重启 profile（必须重启才会加载插件）；② 桌宠实例已在运行（单实例，先「退出」再重启 dsh）。
- **`electron` 解析失败**：插件从**项目目录**的 `node_modules` 解析 electron（`dsh plugin add .` 是软链方式）。确认 `npm install` 已执行、`node_modules\electron\dist\electron.exe` 存在。
- **一次性 profile（`headless`）**：任务结束会立即关闭桌宠，请装在常驻型 profile（如 `web`）。

> `cordis.patch.yml` 中的 `enabled` 可控制是否随 profile 启动；`electron` 字段留空时自动解析，也可填绝对路径。

---

## 五、配置

### 修改追踪的指数 / 股票

编辑 `src/stock.js` 顶部的 `INDEX`：

```js
const INDEX = {
  name: '上证指数',
  code: '000001',
  secid: '1.000001',   // 东方财富: 1=沪市 0=深市
  tencent: 'sh000001'  // 腾讯: sh/sz + 代码
}
```

例如追踪深证成指改为 `secid: '0.399001'`、`tencent: 'sz399001'`。

### 更换素材

直接用同名文件替换 `assets/` 下的图片/音效即可。若新图片是**白底 PNG**，重新执行抠图脚本：

```bash
npm run transparent   # 需要 sharp 依赖(项目已装或走 DSH 环境回退)
```

---

## 六、行情数据说明

| 源 | 接口 | 说明 |
|---|---|---|
| 东方财富(主) | `push2.eastmoney.com/api/qt/stock/get` | UTF-8 JSON，字段 `f43` 现价 / `f60` 昨收 |
| 腾讯财经(备) | `qt.gtimg.cn/q=sh000001` | GBK 文本，按 `~` 分隔 |

涨跌幅统一按 `(现价 - 昨收) / 昨收` 计算，不依赖各家涨跌幅字段的缩放差异，保证一致性。主源失败自动切换备用源。请求在主进程完成，规避浏览器 CORS 限制。

> 免费接口不保证 SLA，行情可能有延迟；仅用于桌面宠物展示，不构成投资建议。

---

## 七、常见问题

**Q: 宠物显示成白色方块？**
图片必须是带透明通道的 PNG。仓库已内置转透明后的素材；若自行替换请确保透明，或执行 `npm run transparent`。

**Q: 开机自启不生效？**
托盘菜单勾选「开机自启」即可（开发模式也已支持，会自动带上应用目录参数）。注意：若之后移动项目目录或重装 electron，开发模式的自启会失效；打包安装（`npm run dist`）后自启为独立 exe，与源码目录无关。

**Q: 窗口挡住了桌面的点击？**
透明窗口本身会拦截鼠标事件（用于拖拽）。窗口已压缩到「宠物 + 顶部气泡区」的最小矩形，宠物本体约占下半部分。

**Q: 音效没声音？**
音效在启动时已预加载；若仍无声音，检查系统音量及 Electron 是否被静音。涨跌各对应 `niulai.mp3` / `mama.mp3`。