dsh-hiyori-web-ui

Readme

<div align="center">

# 桃濑日和 · DSH 伴侣

**给 DeepSeek Harness Web 一套暖色、温柔的界面，也给每段任务一位会回应你的 桃濑日和。**

![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white)
![DSH Web Plugin](https://img.shields.io/badge/DSH-Web_Plugin-BB7A68?style=flat-square)
![Live2D Hiyori Pro](https://img.shields.io/badge/Live2D-Hiyori_Pro-E7A9A1?style=flat-square)

[产品体验](#产品体验) · [功能亮点](#功能亮点) · [快速开始](#快速开始) · [设置](#设置) · [常见问题](#常见问题)

![桃濑日和 DSH 伴侣主界面](docs/readme/hero.png)

</div>

## 不只是换一张背景

`dsh-hiyori-web-ui` 是一个 DSH Web 常驻插件。它把暖色半透明面板、细腻柔和的视觉细节与低干扰樱花带进工作区，并让 Live2D 原创角色桃濑日和常驻右下角：看向鼠标、回应任务状态，也在漫长等待中陪你说句话。

默认台词完全在本地运行，不配置 API Key 也能获得完整的角色互动；需要更丰富的表达时，再按需启用 DeepSeek 生成台词。

## 产品体验

### 她会看向你的鼠标

桃濑日和的眼睛和头部会平滑跟随鼠标移动，鼠标离开后再自然恢复正视，让她真正成为界面里有回应的伙伴。

![桃濑日和视线跟随鼠标](docs/readme/hiyori-mouse-follow.gif)

### 点击，她会回应

点击头部或身体会触发气泡、动作与表情；每 12～24 秒，她也会自然播放一次符合当前性格的待机动作。悬停即可隐藏，想见她时随时唤回。

![桃濑日和角色互动](docs/readme/interaction.png)

### 一处配置，控制全部体验

在完整设置页中，可以分别控制背景与角色，切换温柔、傲娇、乖巧、元气、慵懒五种性格，也可以按需配置 DeepSeek API Key 和台词模型。

五种性格拥有各自的台词、基础表情和动作池，切换后立即生效并自动保存。AI 台词始终是可选项：不填写 API Key 时，角色继续使用内置台词，本地互动能力不受影响。

![桃濑日和完整设置页面](docs/readme/settings.png)

## 功能亮点

- **沉浸外观**：暖色半透明面板、柔和字体、金色角饰与低干扰樱花覆盖亮色 / 暗色主题，背景和樱花均可独立关闭。
- **Live2D 互动**：角色跟随鼠标，点击头部或身体触发气泡、动作和表情，并自然播放性格专属待机动作。
- **状态感知**：根据本地时间、会话切换和任务加载 / 完成 / 错误（loading / complete / error）状态回应；长任务会在 20 秒、1 分钟、2 分钟、4 分钟及之后每 2 分钟反馈进度。
- **连击反馈**：连续完成 3 / 5 / 10 次以及 15 / 20 / 25 次时，会触发逐层升级的专属台词。
- **性格联动**：五种性格分别拥有台词、常驻表情和动作池；8 种事件表情会与任务结果同步，播放后回到当前性格的常态。
- **隐私克制**：不读取对话内容，不发送遥测；背景、角色、性格与 AI 台词分别控制。

## 快速开始

### 环境要求

- Node.js 20+
- npm
- pnpm（DSH 插件命令会调用它）
- 可正常运行的 DeepSeek Harness（DSH）

本插件是 DSH 常驻插件（Cordis bundle）。安装一次后会随 `dsh web` 自动加载，重启后依然保留。

如果还没有 pnpm，可用 npm 安装并确认命令可用：

```bash
npm install -g pnpm
pnpm --version
```

### 1. 获取项目并生成插件包

```bash
git clone https://github.com/Shmilyol/dsh-hiyori-web-ui.git
cd dsh-hiyori-web-ui
npm install
npm run setup:live2d
```

仓库已包含预构建的 Hiyori Pro / Cubism 运行资源。`setup:live2d` 只校验资源并生成插件包，不会下载 Live2D SDK：

```text
lib/index.js   插件主机端：托管角色资源并提供状态接口
lib/client.js  插件浏览器端：暖色皮肤、设置和角色界面
```

### 2. 安装到 DSH Web

```bash
npx @deepseek-ai/dsh plugin --profile web add /你的存放路径/dsh-hiyori-web-ui
```

把路径替换为仓库的实际**绝对路径**。如果终端当前就在仓库目录，也可以简写为 `add .`。

### 3. 启动 DSH

```bash
npx @deepseek-ai/dsh web
```

打开命令输出的地址，皮肤与桃濑日和会直接出现，无需让助手运行命令或批准操作。之后重启 DSH，插件仍会自动加载。

> [!NOTE]
> DSH 与本仓库必须位于同一台机器。插件按绝对路径读取 `assets/live2d` 中的资源；仓库可以放在任意目录，但移动后需要重新执行 `npm run setup:live2d` 和第 2 步。

## 设置

点击左下角 **设置** → **桃濑日和配置**：

| 配置项 | 作用 |
| --- | --- |
| **背景颜色** | 开启暖色背景；关闭后还原 DSH 默认背景色 |
| **虚拟角色** | 显示或隐藏右下角的桃濑日和 |
| **性格** | 在温柔 / 傲娇 / 乖巧 / 元气 / 慵懒之间切换 |
| **DeepSeek API Key** | 可选；启用模型生成台词，Key 只保存到服务端 `$DSH_HOME/.credentials.yaml` |
| **模型** | 选择台词生成模型，默认 `deepseek-v4-flash` |

会话标题栏旁的樱花开关可单独控制飘落花瓣。

> [!IMPORTANT]
> 插件不读取对话内容、提示词、回复文本、错误详情或文件内容，也不发送遥测。启用 AI 台词后，只会把事件类型、性格、连胜数或耗时档位等最小元数据发送给 DeepSeek；API Key 只保存在服务端 `$DSH_HOME/.credentials.yaml`。

### 升级

拉取新版本或修改插件代码后，重新生成 bundle，必要时重启 DSH：

```bash
npm install
npm run setup:live2d
```

### 卸载

如果配置过 DeepSeek API Key，请先在 **设置 → 桃濑日和配置** 中清空并保存。插件卸载不会自动删除 `$DSH_HOME/.credentials.yaml` 中独立保存的凭据。

```bash
npx @deepseek-ai/dsh plugin --profile web remove dsh-hiyori-web-ui
```

重启 `dsh web` 后，皮肤、角色及 web profile 中的插件配置会一起移除。

## 常见问题

<details>
<summary><strong><code>setup:live2d</code> 失败或命令不可用</strong></summary>

确认正在使用 Node.js 20+，并在仓库目录先运行 `npm install`，再执行 `npm run setup:live2d`。

</details>

<details>
<summary><strong><code>dsh plugin add</code> 失败</strong></summary>

确认 DSH 与 `pnpm` 可用。如果通过 `npx @deepseek-ai/dsh` 启动 DSH，安装插件时也使用同一条命令：

```bash
npx @deepseek-ai/dsh plugin --profile web add .
```

安装完成后重启 `dsh web`，新 bundle 才会加载。

</details>

<details>
<summary><strong>只有皮肤，没有看到角色</strong></summary>

按顺序检查：

1. **设置 → 桃濑日和配置** 中“虚拟角色”是否开启；
2. 插件是否已加入 web profile；
3. 仓库是否被移动过，若移动过请重新执行安装步骤；
4. 修改代码后是否重新运行了 `npm run setup:live2d`。

</details>

## 许可与来源

本作品的角色使用 Live2D 原创角色桃濑日和（Hiyori Pro）：插画 Kani Biimu，模型 Live2D。相关条款与来源：[Hiyori Pro 素材](https://www.live2d.com/zh-CHS/download/sample-data/)、[示例模型条款](https://www.live2d.com/eula/live2d-sample-model-terms_en.html)、[无偿提供素材协议](https://www.live2d.com/eula/live2d-free-material-license-agreement_en.html)、[Core proprietary license](https://www.live2d.com/eula/live2d-proprietary-software-license-agreement_en.html)。

本作品的角色在运用株式会社Live2D的著作物素材样本时依据了株式会社Live2D规定的协议。本作品完全根据制作者的自我裁量制作而成。

`assets/live2d` 中的 Cubism Core、Hiyori 模型和 Framework / Samples 构建资源适用各自的官方条款，不适用仓库其他代码的许可。不得脱离本插件单独再分发这些角色资源；再使用时必须保留角色设计细节与随附许可信息。详见 [Live2D 资源与发布边界](docs/live2d-licenses.md)。

---

<p align="center">
  <a href="https://github.com/Shmilyol/dsh-hiyori-web-ui">GitHub 仓库</a> · 桃濑日和（Hiyori Pro）由 <a href="https://www.live2d.com/zh-CHS/download/sample-data/">Live2D</a> 提供
</p>