dsh-whale-desktop-kit

Readme

# DeepSeek Harness Desktop 增强套件

<p align="center">
  <img src="coverbg.png" alt="DeepSeek Harness 桌面增强套件封面" width="100%" />
</p>

这是一套为 [DeepSeek Harness](https://www.deepseek.com)（本地安装的 DSH）构建的自用增强插件 + 原生桌面应用，把 DSH 变成一个更像「桌面软件」的工作环境。

仓库只保留**最终版本**的源码，已清除所有个人路径、密钥、对话记录与账户余额信息。

> 本项目为个人学习 / 自用项目，与 DeepSeek 官方无关。
>
> **兼容性**：适配 DeepSeek Harness 0.1.0-rc.6；壁纸功能需要 `sharp` 图像库（未安装时其余功能不受影响）。

---

## 目录结构

```
├── plugins/                 # 6 个 Cordis 插件
│   ├── desktop-experience/  # 壁纸、黑鲸鱼桌宠、贴边 dock、设置页与透明度滑块
│   ├── dsh-token-pet/       # DeepSeek 余额 + 会话 token 用量数据源
│   ├── dsh-office-docs/     # Office 文档安全读取（docx / pptx / xlsx）
│   ├── personal-assistant/  # 本地秘书 + 文档生成工具
│   ├── safe-auto-approval/  # 工具调用的安全自动批准策略
│   └── dsh-desktop-app/     # 桌面应用入口 / PWA / 应用图标
├── desktop/                 # Electron 原生桌面应用（frameless、贴边隐藏、独立桌宠窗口、托盘）
├── tools/                   # Restart-DshService.ps1（脱机重启后端）
├── LICENSE                  # MIT
└── .gitignore
```

---

## 功能介绍

### 1. 桌面体验（desktop-experience，v0.1.26）

- **本地壁纸**：支持 PNG / JPEG / WebP / GIF。图片经过安全扫描与转码（动态图转成 animated WebP，静态图同时生成封面），拒绝 SVG、网页、远程 URL 和视频。
- **壁纸美化**：可调「模糊」「玻璃质感」「壁纸透明度」。
- **对话框 / 工作区不透明度**：分别控制底部输入框（对话框）与左侧栏（工作区）的透明度。底色跟随系统主题（浅色主题为白色，深色主题为深灰），**0 = 完全透明、100 = 完全不透明**，中间值实时过渡。
- **顶栏快捷栏（dock）**：鼠标移到屏幕顶部自动显示、移开自动隐藏；提供侧边栏开关、详情开关、桌宠开关、壁纸开关。
- **黑鲸鱼桌宠**：独立透明置顶窗口，可离开 DSH 在 Windows 桌面自由拖动；点击查看 DeepSeek 余额、token 用量与缓存命中率；右键菜单可刷新 / 复位 / 关闭。
- **设置页**：在 DSH 设置里注入「桌面体验」「桌宠」「壁纸」三个标签页。

### 2. 余额与用量数据源（dsh-token-pet，v0.1.1）

- 读取 DeepSeek 官方 `user/balance` 接口，展示账户余额。
- 统计当前会话的 token 用量（输入 / 输出 / 缓存读 / 缓存写 / 命中率），按「最近活跃会话」选择当前会话。
- 提供 `GET /dsh-token-pet/data.json` 给桌宠或其他面板使用。

### 3. Office 文档读取（dsh-office-docs，v0.1.0）

- 安全读取 Word / PowerPoint / Excel：路径越界防护、文件类型与内容格式校验、只读解析。

### 4. 个人助理（personal-assistant，v0.1.2）

- **本地秘书**：任务清单、便签、每日摘要、会议纪要（只写入本地工作区）。
- **文档生成**：`assistant_document_create_text/docx/pptx/xlsx` 一键生成文档。
- 图片收件箱、本机状态读取等辅助能力。


> **固定工作区**：助理的所有文件操作被限制在一个固定工作目录内。完整版 harness 由启动脚本通过 DSH_ASSISTANT_WORKSPACE 环境变量提供；官方 npm 版由 install.ps1 自动写入 ~\.dsh\profiles\web\cordis.patch.yml（默认工作区 ~\.dsh\workspace）。
### 5. 安全自动批准（safe-auto-approval，v0.1.1）

- 对只读类工具调用自动放行，涉及写操作的工具调用仍要求用户确认，减少打断。

### 6. 桌面应用入口（dsh-desktop-app，v0.1.0）

- 原生应用定位、PWA 支持、应用图标生成脚本。

### 7. 原生桌面应用（desktop/）

- 无边框现代窗口（自带标题栏与最小化 / 最大化 / 关闭）。
- 主窗口贴边自动隐藏（失去焦点后缩到屏幕边缘，鼠标靠近边缘唤回）。
- 独立黑鲸鱼桌宠窗口（透明、置顶、点击穿透、全桌面拖动）。
- 系统托盘（显示 / 隐藏、开机自启、自动隐藏开关、重新加载、退出）、单实例锁、窗口状态记忆。

---

## 安装说明

### 前置要求（一次性）

- Windows 10 / 11
- Node.js LTS（≥ 22，含 npm）、pnpm（`npm install -g pnpm`）、git
- DeepSeek Harness（二选一）：
  - **完整版 harness**：自带 `security\` 插件安全门禁与 `scripts\Start-DeepSeek-Harness.ps1` 启动脚本
  - **官方 npm 版**：`npm install -g @deepseek-ai/dsh`（无门禁，用 `dsh plugin add` 安装）

### 方式一：一键安装（推荐，全程无需 npm 账号）

```powershell
# 1. 下载本仓库
git clone https://github.com/z-time-007/whale-desktop-kit.git
cd whale-desktop-kit

# 2. 一键安装（自动完成后续全部步骤）
powershell -ExecutionPolicy Bypass -File install.ps1
```

**install.ps1 自动完成流程**：

1. 检查环境（Node / pnpm / git，缺失时尝试自动安装）；
2. 定位 DeepSeek Harness（支持 `-HarnessRoot` 手动指定），并判断安装模式：
   - 检测到**完整版 harness**（有 `security\` 门禁）→ 逐插件「打包 → 安全扫描（Defender + 静态分析 + 依赖审计）→ 门禁安装」；
   - 检测到**官方 npm 版**（无门禁）→ 逐插件「打包 → `dsh plugin add --profile web`（匿名下载依赖，无需 npm 账号）」；
3. 官方 npm 版额外自动配置**个人助手工作区**（写入 `~\.dsh\profiles\web\cordis.patch.yml`，默认工作目录 `~\.dsh\workspace`）；
4. 构建原生桌面应用（`desktop\dist\DeepSeekHarness\DeepSeekHarness.exe`，可用 `-SkipDesktopApp` 跳过）；
5. 重启后端（`tools\Restart-DshService.ps1`，可用 `-SkipRestart` 跳过）并验证。

**常用参数**：

```powershell
.\install.ps1 -HarnessRoot "D:\path\to\deepseek-harness"   # 手动指定 DSH 根目录
.\install.ps1 -Port 3090                                    # 换端口（默认 3080，端口被占用时用）
.\install.ps1 -SkipDesktopApp                               # 跳过桌面应用构建
.\install.ps1 -SkipRestart                                  # 安装后不自动重启后端
```

> 说明：`dsh plugin add` 安装依赖时从 npm 仓库**匿名下载**（无需账号）；只有「发布到 npm」才需要 npm 账号。网络不佳导致超时可重试，或临时配置 npm 镜像源。

### 方式二：手动安装（完整版 harness，走安全门禁）

以 `desktop-experience` 为例：

```powershell
# 1. 打包（拒绝任何生命周期脚本）
pnpm pack

# 2. 安全扫描（Defender + 静态模式分析 + 依赖审计，产出不可变报告）
powershell -NoProfile -ExecutionPolicy Bypass -File D:\path\to\deepseek-harness\security\Inspect-PluginPackage.ps1 -Package <生成的.tgz>

# 3. 复核报告后安装
powershell -NoProfile -ExecutionPolicy Bypass -File D:\path\to\deepseek-harness\security\Install-PluginSafely.ps1 -Package <同一个.tgz> -ApprovedReport <报告.json> -Approve

# 4. 脱机重启后端
powershell -NoProfile -ExecutionPolicy Bypass -File D:\path\to\whale-desktop-kit\tools\Restart-DshService.ps1
```

各插件目录下的 `build\` 内也提供了打包脚本（如 `Build-DshTokenPetPlugin.ps1`），直接运行即可完成「打包 + 扫描」两步。

### 方式三：手动安装（官方 npm 版）

```powershell
# 1. 先安装 DSH 官方 CLI
npm install -g @deepseek-ai/dsh

# 2. 逐插件安装（在仓库 plugins\<插件名> 目录内）
pnpm pack
dsh plugin add <生成的.tgz> --profile web

# 3. 配置个人助手工作区（否则 personal-assistant 拒绝启动，报 ROOT_REQUIRED）
#    编辑 ~\.dsh\profiles\web\cordis.patch.yml，加入：
#    - id: local-personal-assistant
#      config:
#        workspaceRoot: 'C:\Users\你的用户名\.dsh\workspace'
#    （或启动 dsh 前设置环境变量 $env:DSH_ASSISTANT_WORKSPACE）

# 4. 启动
dsh web
```

> **根目录即规范插件**：仓库根目录声明了 dsh.bundle + dsh.client，可直接打包为单个插件一键安装全部 6 个增强：cd 仓库根目录; pnpm pack; dsh plugin add <dsh-whale-desktop-kit-1.0.0.tgz> --profile web（等效于 install.ps1 的 6 个插件之和，含桌面体验 UI）。

> 完整版 harness 无需手动配置工作区：启动脚本 `scripts\Start-DeepSeek-Harness.ps1` 已通过 `DSH_ASSISTANT_WORKSPACE` / `DSH_ASSISTANT_ENABLED` 环境变量自动提供（插件 v0.1.2 起内置环境变量回退）。

### 构建桌面应用（desktop/）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File D:\path\to\whale-desktop-kit\desktop\build\Build-DshDesktopApp.ps1
```

构建产物为 `desktop\dist\DeepSeekHarness\DeepSeekHarness.exe`，并会在桌面创建快捷方式。

### 验证是否装好

1. 打开 `http://127.0.0.1:3080`（或 `-Port` 指定的端口）。
2. 打开设置，能看到「桌面体验 / 桌宠 / 壁纸」三个标签 → 即安装成功。
3. 可选接口自检：
   - `GET /dsh-token-pet/data.json` → 桌宠数据接口；
   - `GET /dsh-desktop/state.json`、`GET /dsh-desktop-experience/api/state` → 桌面体验状态接口。

### 常见问题

- **端口被占用**：`.\install.ps1 -Port 3090` 换端口，或启动时 `dsh web --port 3090`。
- **壁纸功能不可用**：需要 `sharp` 图像库（`install.ps1` 会随插件自动安装）；未安装时其余功能不受影响。
- **个人助理不启动 / 报 `ROOT_REQUIRED`**：`personal-assistant` 强制要求固定工作区（`workspaceRoot`）。完整版 harness 由启动脚本环境变量提供；npm 版按「方式三」配置 `cordis.patch.yml` 或设置 `DSH_ASSISTANT_WORKSPACE`。
- **npm 网络超时**：`dsh plugin add` 从 npm 匿名下载依赖，网络不佳时重试或配置镜像源。
## 操作步骤

1. **启动**：双击桌面快捷方式（或运行 `DeepSeekHarness.exe`），应用会自动检查并启动本地 DSH 后端，就绪后进入主界面。
2. **打开设置**：点击 DSH 界面里的设置入口，打开设置面板。
3. **更换壁纸**：设置 → **壁纸** → 点击「从本地导入壁纸」选择图片，或把图片放入收件箱后点「安全扫描并更换」；用滑块调整「模糊 / 玻璃质感 / 透明度」。
4. **调整对话框 / 工作区不透明度**：设置 → **壁纸** → 拖动「对话框不透明度」「工作区不透明度」滑块（0 = 完全透明，100 = 完全不透明，底色跟随系统主题）。
5. **桌宠**：
   - 打开：顶部 dock 点 🐋（按一下打开、再按一下关闭），或 设置 → **桌宠** → 「立即打开」。
   - 拖动：按住鲸鱼拖动到桌面任意位置。
   - 查看数据：点击鲸鱼，气泡显示余额、token 用量与缓存命中率。
   - 关闭：右键鲸鱼 → 「关闭桌宠」。
6. **顶部快捷栏**：鼠标移到屏幕顶部唤起 dock；「☰」切换侧边栏、「◫」切换详情栏、「▧」开关壁纸。
7. **托盘**：右键托盘鲸鱼图标可显示 / 隐藏主窗口、开机自启、自动隐藏窗口、重新加载、退出。

---

## 社区与生态

本项目属于 DeepSeek Harness（DSH）社区生态的一部分，可关注以下资源发现更多插件、也让本项目被更多人看到：

- [awesome-deepseek-harness](https://github.com/Dominic789654/awesome-deepseek-harness) —— DSH 生态精选列表（插件 / 技能 / MCP / UI / 工作流）
- [awesome-dsh-plugin](https://github.com/beancookie/awesome-dsh-plugin) —— DSH 插件精选列表
- [dsh-plugin-marketplace](https://github.com/YELEBAI/dsh-plugin-marketplace) —— 社区插件市场
- [WhaleHub 🐋](https://github.com/vvlife/whalehub-dsh) —— DSH 插件市场（发现、搜索、一键安装）
- 搜索话题：`dsh` · `dsh-plugin` · `deepseek-harness`

---

## 隐私说明

- 本仓库**不含**任何对话记录、账户余额、真实 API 密钥或机器特定的绝对路径。
- 源码中的绝对路径一律用 `D:\path\to\deepseek-harness` 与 `D:\path\to\whale-desktop-kit` 占位。
- 测试文件中的 `sk-test`、`sk-abc123`、`sk-quoted` 等均为**假数据**。

---

## 版权与商标

- 代码与文档：**MIT**（见 `LICENSE`）。
- `dsh-black-whale.ico`、`dsh-app-icon-*.png` 等鲸鱼 logo 为 **DeepSeek 的商标 / 品牌资产**，**不在** MIT 授权范围内，仅用于项目内展示；请勿擅自用于商业用途或衍生品牌。

---

## 授权与使用声明

- 你可以**自由地**基于本项目：
  - 制作视频教程、图文教程、演示与评测；
  - 进行二次开发、修改、学习、fork 与再分发（遵守 MIT）。
- 但请遵守以下约定：
  1. **注明来处**：在使用或衍生作品中保留本项目名称与出处（如本仓库链接 / 作者信息）。
  2. **鲸鱼 logo 除外**：DeepSeek 鲸鱼品牌资产不受本项目 MIT 授权，请勿用于商业用途或衍生品牌。
  3. 本项目与 DeepSeek 官方无关，请勿以官方名义发布。

感谢使用与传播！