鲸跃桌面增强套件z-time-007/whale-desktop-kit

DeepSeek Harness 桌面增强套件

这是一套为 DeepSeek Harness（本地安装的 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 账号）

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 跳过）并验证。

常用参数：

.\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 为例：

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

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

3. 复核报告后安装
powershell -NoProfile -ExecutionPolicy Bypass -File D:\path\to\deepseek-harness\security\Install-PluginSafely.ps1 -Package  -ApprovedReport  -Approve

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

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

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

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

2. 逐插件安装（在仓库 plugins\ 目录内）
pnpm pack
dsh plugin add  --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  --profile web（等效于 install.ps1 的 6 个插件之和，含桌面体验 UI）。

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

构建桌面应用（desktop/）

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 —— DSH 生态精选列表（插件 / 技能 / MCP / UI / 工作流）
- awesome-dsh-plugin —— DSH 插件精选列表
- dsh-plugin-marketplace —— 社区插件市场
- WhaleHub 🐋 —— 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 官方无关，请勿以官方名义发布。

感谢使用与传播！