dsh-ds-vpet

Readme

# 🐋dsh-ds-vpet🐋

**DSH 虚拟桌宠（ds娘）** — DeepSeek Harness Web 桌宠插件，仿《虚拟桌宠模拟器》交互体验。

**DSH Virtual Pet (ds-chan)** — A DeepSeek Harness web plugin inspired by *Virtual Desktop Pet*-style interactions.

一只陪伴你写代码的 ds娘 桌宠：会按时提醒、会喵叫、会得意、能看余额，还能在你需要做决定时提醒你。

A little ds-chan who keeps you company while you code: she checks in on schedule, meows when poked, gets proud of herself, shows your balance, and nudges you when a decision needs your input.

##  特性 / Features

| 特性 | 说明 |
|---|---|
|  **多状态立绘** | 常态 / 等待允许选择（随机 2 选 1）/ 思考完成庆祝，随状态自动切换 |
|  **按时说话** | 8 个时间段各有专属台词（早晨问候、午休提醒、深夜关心…）|
|  **点击互动** | 点击人物连击喵叫 |
|  **拖拽 + 缩放** | 按住拖动移动（拖拽时变形），滚轮调节大小（30%–300%） |
|  **齿轮设置** | 深蓝主题弹窗：最上层显示、余额计数器、隐藏/唤出、说话频率、中英文 |
|  **余额计数器** | 实时显示 DeepSeek 账户余额，低于预警值变红（预警值可调） |
|  **思考检测** | 模型思考结束自动切换庆祝立绘并说"我厉害吧～" |
|  **双语** | 全部台词中 / 英可切换（English available） |
|  **立绘可替换** | 素材在 `assets/`，替换同名 PNG 即可换形象 |

| Feature | Description |
|---|---|
| Multi-state art | Idle / waiting for approval (random 1-of-2) / celebrating a finished turn — switches automatically |
| Time-aware lines | Each of 8 dayparts has its own lines (morning greetings, lunch nudges, late-night care…) |
| Tap to talk | Tap the pet for escalating meows |
| Drag & zoom | Drag to move (she dangles while dragged); scroll to resize (30%–300%) |
| Gear settings | Deep-blue modal: always-on-top, balance counter, hide/show, talk frequency, language |
| Balance counter | Live DeepSeek account balance; turns red below your configurable warning threshold |
| Thinking detection | When a thinking phase ends, she switches to a victory pose and says "I'm awesome, right?" |
| Bilingual | Every line is available in Chinese or natural English |
| Swap-in art | Drop your own transparent PNGs into `assets/` with matching names to reskin her |

##  安装 / Installation

### 环境要求 / Requirements

- DeepSeek Harness（`dsh`）已安装，`dsh web` 可正常启动
  DeepSeek Harness (`dsh`) installed, with `dsh web` able to start.
- 构建时需要 Node.js ≥ 22 + pnpm
  Node.js ≥ 22 and pnpm are required only for building from source.

### 方式一：本地路径安装（推荐）/ Option 1: Local path (recommended)

```bash
# 克隆或下载本仓库后，用绝对路径添加插件
# Clone or download this repo, then add the plugin by absolute path
dsh plugin --profile web add /绝对路径/dsh-ds-vpet
```

> Windows 下用绝对路径（正斜杠/反斜杠均可）；`dsh plugin add` 不接受裸目录名。
> On Windows use an absolute path (forward or back slashes both work); `dsh plugin add` does not accept bare directory names.

### 方式二：GitHub 子路径安装 / Option 2: GitHub subpath

```bash
dsh plugin --profile web add 'github:<你的用户名>/dsh-ds-vpet#path:/'
```

### 安装后 / After installing

1. **重启 dsh web**（新增插件必须重启）
   **Restart dsh web** — new plugins require a restart.
2. 刷新页面（Ctrl+F5），右下角出现 ds娘 桌宠
   Refresh the page (Ctrl+F5); the ds-chan pet appears in the bottom-right corner.
3. 打开 设置 → 桌宠 可调整全部选项
   Open Settings → Pet to tweak every option.

##  目录结构 / Project Layout

```
dsh-ds-vpet/
├── package.json          # 插件清单（dsh.bundle 协议）/ plugin manifest (dsh.bundle protocol)
├── cordis.patch.yml      # bundle patch（loader 注册行）/ bundle patch (loader entry)
├── tsdown.config.ts      # 构建配置（node 半边 + client bundle）/ build config (node half + client bundle)
├── tsconfig.json
├── src/
│   ├── index.ts          # node 半边：余额 API + 立绘静态路由 / host half: balance API + art routes
│   └── client/           # 浏览器半边 / browser half
│       ├── index.ts      # 入口：创建桌宠 + 注册设置栏位 / entry: create pet + register settings section
│       ├── pet.ts        # 桌宠核心：状态机/交互/气泡/检测 / pet core: state machine, interactions, bubbles, detectors
│       ├── settings.tsx  # DSH 设置页「桌宠」栏位 / DSH "Pet" section in Settings
│       └── images.ts     # 立绘 URL 映射 / art URL map
├── assets/               # 立绘 PNG（1=常态 2/3=等待 4=思考完成）/ art PNGs (1=idle, 2/3=waiting, 4=thinking done)
├── scripts/
│   ├── cutout.py         # 立绘抠图脚本（Pillow + numpy）/ art background-removal script (Pillow + numpy)
│   └── process-images.ps1
└── lib/                  # 构建产物（client.js + index.js）/ build output (client.js + index.js)
```

##  开发构建 / Building from Source

```bash
pnpm install
pnpm build        # 输出 lib/client.js（浏览器）+ lib/index.js（node）/ outputs lib/client.js (browser) + lib/index.js (node)
```

##  常见问题 / FAQ

### Q1：图片不显示 / 显示破图图标？/ Images won't load or show a broken icon?

1. 重启 dsh web 后**刷新页面（Ctrl+F5）**——服务重启后路由注册需要几秒，图片失败会自动重试（2/5/10 秒）
   After restarting dsh web, **refresh the page (Ctrl+F5)** — routes take a few seconds to register on a fresh server, and failed images auto-retry (2/5/10s).
2. 确认浏览器没在使用缓存页面（完全关闭浏览器重开，或 Ctrl+Shift+T 重新打开标签页）
   Make sure the browser isn't showing a cached page (fully close and reopen the browser, or reopen the tab with Ctrl+Shift+T).

### Q2：思考结束不切换立绘？/ Pet doesn't switch art after thinking?

思考检测依赖 DSH 的状态指示（"Deep diving" 文案 / 停止按钮 / 输入框禁用）。如果失效，打开 F12 → Console，查看 `[dsh-ds-vpet] 思考状态` 日志反馈给作者。

Thinking detection relies on DSH's status cues ("Deep diving" text / the stop button / a disabled composer). If it stops working, open F12 → Console and share the `[dsh-ds-vpet] thinking status` logs with the author.

### Q3：余额显示 "—" 或不变？/ Balance shows "—" or never updates?

- 插件通过 `DEEPSEEK_API_KEY` 凭据查询余额（`~/.dsh/.credentials.yaml`）
  The plugin reads the balance using the `DEEPSEEK_API_KEY` credential (`~/.dsh/.credentials.yaml`).
- 没有该凭据则无法显示；余额 30 秒缓存刷新一次
  Without that credential there's nothing to show; the balance refreshes on a 30-second cache.

### Q4：怎么换形象？/ How do I change the art?

把新的立绘（透明背景 PNG，建议 ≤ 512px）替换 `assets/1.png`（常态）、`2.png`/`3.png`（等待）、`4.png`（思考完成）。本地 link 安装时立绘经路由实时读取，替换后刷新即可；正式打包安装需重新构建。

Replace `assets/1.png` (idle), `2.png`/`3.png` (waiting) and `4.png` (thinking done) with your own transparent PNGs (≤ 512px recommended). With a local link install the art is served live, so a refresh is enough; packaged installs need a rebuild.

### Q5：说话内容不喜欢？/ Don't like the lines?

台词在 `src/client/pet.ts` 的 `LINES_BY_HOUR`（定时）和 `TAP_LINES`（点击喵叫）中，改后重新 `pnpm build`。

The lines live in `LINES_BY_HOUR` (scheduled) and `TAP_LINES` (tap meows) in `src/client/pet.ts`; edit them and re-run `pnpm build`.

### Q6：卸载 / Uninstall

```bash
dsh plugin --profile web remove dsh-ds-vpet
```

##  许可 / License

- 插件代码：**MIT License**
  Plugin code: **MIT License**.
- **立绘素材**：仓库内置的 `assets/*.png` 均来自网络
  **Art assets**: the bundled `assets/*.png` were sourced from the internet.

##  说明 / Notes

- 插件为纯展示层（client 插件），不修改 DSH 核心
  This is a presentation-only client plugin — it never touches DSH core.
- 遇到问题欢迎提 Issue
  Issues and PRs are welcome.