dsh-dafeiyu README

The project's README from github.com/QCYTSN/dsh-dafeiyu. As one markdown file: README.md.

DSH 大肥鱼 🐋

住在桌面上、由 DeepSeek Harness 真实工作状态驱动的 Agent 伴侣。

入口属于 DSH，生命周期属于 DSH，显示层属于桌面。

English · npm · 下载最新版本 · 更新日志 · 更新与回退 · 验收记录

npm · GitHub Release

DSH 大肥鱼在真实任务中显示项目状态

DSH 大肥鱼不是一个需要单独启动的桌宠应用。它由 DSH 插件启用，跟随 DSH 一起启动和退出，并以透明、无边框、始终置顶的原生窗口显示在桌面上。即使切换到 VS Code、浏览器或文件管理器，也能知道 DSH 当前在思考、修改、测试、等待还是已经完成。

当前版本：0.1.9 · Windows / WSL2 / Linux x64 · macOS 实验性支持

关注最新进展

它有什么用？

如果 DSH 没有提供待办清单，大肥鱼只显示“分析阶段”“实现阶段”“验证阶段”等可靠信息， 不会编造完成百分比。

状态展示

思考 工作
大肥鱼思考状态 大肥鱼工作状态
等待确认 完成
大肥鱼等待用户确认 大肥鱼任务完成
遇到问题
大肥鱼错误状态

状态大致按照下面的流程变化：

stateDiagram-v2
    [*] --> 空闲
    空闲 --> 思考: DSH 开始一轮任务
    思考 --> 工作: 搜索、读取、修改、执行或测试
    工作 --> 思考: 整理工具结果
    思考 --> 等待: 需要用户确认
    工作 --> 等待: 需要用户确认
    思考 --> 完成: 本轮任务完成
    工作 --> 完成: 本轮任务完成
    思考 --> 错误: 任务异常结束
    工作 --> 错误: 工具或任务失败
    等待 --> 思考: 用户继续任务
    错误 --> 思考: 用户重试
    完成 --> 空闲

多个 DSH Session 同时运行时，默认优先展示最需要注意的顶层任务：

等待确认 > 错误 > 工作 > 思考 > 空闲

当有多个活动任务时，状态气泡会同时列出这些任务的状态。

系统要求

普通用户不需要安装 Python、PySide6 或单独运行 Helper。Windows、Linux x64 和 macOS 的 Helper 都已经包含在发布包里。

当前 Alpha 版的设置与桌面状态文案使用简体中文。

安装插件

1. 完全退出 DSH

先关闭 DSH Host，而不只是关闭浏览器标签页。安装或更新时不要让旧版插件继续运行。

2. 命令安装

Windows 用户

在 PowerShell 中进入你的 DSH 安装目录，例如：

cd D:\DSH

然后从 npm 安装稳定版：

pnpm dsh plugin --profile web add dsh-dafeiyu

如果你的系统已经能直接使用全局 dsh 命令，只需要：

dsh plugin --profile web add dsh-dafeiyu

想抢先试用新功能（@alpha 测试版）的用户，把命令里的包名换成 dsh-dafeiyu@alpha 即可。

如果 DSH 运行在 WSL2，请在 WSL 终端执行同一条安装命令。可视模式下插件会 自动通过 cmd.exe 启动包内的 Windows Helper，不需要手动 chmod， 也不需要在 WSL 安装 Python 或 PySide6。原生 Linux 桌面请看下一节，使用 随包的 Linux Helper，而不是 Windows 的 .exe。

Linux 用户（x64 桌面，glibc ≥ 2.35）

Linux 桌面的安装方式与 Windows 相同，只是换成终端和 Linux 路径。发布包 内置预构建 Helper，不需要安装 Python 或 PySide6。

系统要求：

在终端中进入你的 DSH 安装目录（例如 ~/deepseek-harness）：

cd ~/deepseek-harness

然后从 npm 安装稳定版：

pnpm dsh plugin --profile web add dsh-dafeiyu

也可以从 GitHub Releases 下载 dsh-dafeiyu-<version>.tgz（不要解压），然后安装：

pnpm dsh plugin --profile web add ~/Downloads/dsh-dafeiyu-<version>.tgz

装完照常启动 DSH WebUI，大肥鱼会由 DSH 自动拉起；不需要手动打开 Helper。

macOS 用户（Apple Silicon / Intel，macOS 12.0+）

0.1.4 首次提供实验性的原生 macOS Helper。CI 已验证 Universal 架构、 AppKit 渲染和进程生命周期；Apple Silicon 实机体验将继续通过用户反馈验证。 当前应用只有 ad-hoc 签名，尚未 Developer ID 签名或公证。Gatekeeper 只在 个别场景触发，放行方式见下方「关于 macOS Gatekeeper」。

macOS 的安装方式与 Windows 相同，只是换成「终端」和 macOS 路径。发布包 内置原生 Helper，不需要安装 Python、PySide6 或 Xcode。

在「终端」中进入你的 DSH 安装目录（例如 ~/deepseek-harness）：

cd ~/deepseek-harness

然后从 npm 安装稳定版：

pnpm dsh plugin --profile web add dsh-dafeiyu

如果系统已经能直接使用全局 dsh 命令：

dsh plugin --profile web add dsh-dafeiyu

也可以从 GitHub Releases 下载 dsh-dafeiyu-<version>.tgz（不要解压），然后安装：

pnpm dsh plugin --profile web add ~/Downloads/dsh-dafeiyu-<version>.tgz

装完照常启动 DSH WebUI，大肥鱼会由 DSH 自动拉起；不要手动打开 Helper。

关于 macOS Gatekeeper

实测结论（见 issue #24）： 从 npm 安装、用终端下载、以及浏览器下载 .tgz 后直接安装，都不会触发 Gatekeeper 拦截。只有用 Finder 解压出来的 .app 才会携带隔离标记，双击时 被拦截。

3. GitHub Release 备用安装方式

进入 GitHub Releases，下载最新的：

dsh-dafeiyu-<version>.tgz

不要解压这个文件。

不解压，在 DSH 目录中直接安装下载的插件包：

pnpm dsh plugin --profile web add "C:\Users\you\Downloads\dsh-dafeiyu-<version>.tgz"

4. 启动 DSH

照常启动 DSH WebUI。插件默认启用，大肥鱼会由 DSH 自动拉起；不要手动打开 Helper。

5. 找到设置入口

在 DSH WebUI 中进入：

设置 → 插件 → 插件配置 → 大肥鱼桌面伴侣

DSH 大肥鱼插件设置入口

怎么使用？

安装后不需要额外操作：

  1. 启动 DSH。
  2. 在 DSH 中开始一个项目任务。
  3. 大肥鱼根据 DSH 的真实事件切换动作和状态卡。
  4. 切换到其他窗口继续工作；大肥鱼仍然保持在桌面最上层。
  5. DSH Host 真正退出后，大肥鱼自动退出。

状态卡可能显示：

大肥鱼不会监听 VS Code、浏览器或其他应用，也不会截图。只有 DSH Agent 的事件能够 改变它的工作状态。

可配置项目

设置 作用
启用大肥鱼 立即显示或关闭桌面伴侣
角色大小 在 55%～140% 之间调整；右键菜单提供 60% 迷你档
气泡大小 在 80%～120% 之间调整状态气泡，兼顾信息可读性
气泡显示 常驻显示、完全隐藏，或自定义哪些状态显示气泡
活跃程度 控制空闲时眨眼、观察等微动作频率
减少动态效果 减少走动、循环帧和程序化晃动
提示音 控制任务完成或出错时的大肥鱼提示音
响应子 Agent 允许子 Agent 状态参与优先级选择；默认关闭

设置由 DSH 保存，更新插件后通常不需要重新配置。

桌面互动

更新插件

GitHub 仓库出现新提交后，已经安装的插件不会自动变化。新版本发布后，完全退出 DSH，然后更新 npm 稳定版包：

cd D:\DSH
pnpm dsh plugin --profile web update dsh-dafeiyu

也可以再次执行安装命令，它会解析 npm latest 标签指向的新版本：

pnpm dsh plugin --profile web add dsh-dafeiyu

使用 @alpha 测试版的用户，把更新命令里的包名换成 dsh-dafeiyu@alpha 即可。

使用 GitHub Release 安装的用户，可以下载新 .tgz 后覆盖安装：

pnpm dsh plugin --profile web add "C:\Users\you\Downloads\dsh-dafeiyu-<new-version>.tgz"

以上方式都会替换插件及随包携带的 Helper，并保留 DSH 已保存的设置。详细 说明见 插件更新与回退。

回退到旧版本

完全退出 DSH，重新安装之前保留的旧版 .tgz：

cd D:\DSH
pnpm dsh plugin --profile web add "C:\Users\you\Downloads\dsh-dafeiyu-<old-version>.tgz"

卸载插件

完全退出 DSH 后运行：

cd D:\DSH
pnpm dsh plugin --profile web remove dsh-dafeiyu

然后重新启动 DSH。插件代码和 Helper 会从 web profile 中移除。DSH 可能保留一份 不会再生效的历史设置，这不会启动进程或占用额外端口。

常见问题

安装后没有看到大肥鱼
  1. 确认安装使用的是 --profile web。
  2. 完全退出并重新启动 DSH Host。
  3. 进入“设置 → 插件 → 插件配置”确认“启用大肥鱼”已经勾选。
  4. 确认使用包含对应平台预构建 Helper 的发布包，而不是只克隆了缺少预构建 Helper 的源码。 Windows / WSL2 需要 runtime/bin/win32-x64；原生 Linux 桌面需要 runtime/bin/linux-x64；macOS 需要 runtime/bin/darwin。
关闭了 DSH 网页，为什么大肥鱼还在？

大肥鱼绑定的是 DSH Host 生命周期，而不是浏览器标签页。只要 DSH 后台仍在运行， 大肥鱼就会继续显示；真正退出 DSH Host 后它会自动关闭。

为什么没有显示数字进度？

只有 DSH 写入了结构化待办时，插件才能可靠计算“已完成 3/5 步”。没有真实待办数据时， 状态卡只显示当前工作阶段，避免制造虚假的百分比。

右键选择“本次关闭”后为什么没有自动回来？

这是预期行为。“本次关闭”会抑制当前 DSH 运行期间的自动重启；完全退出并重新启动 DSH 后会恢复。若想永久关闭，请在 DSH 设置中取消“启用大肥鱼”。

隐私与边界

macOS 原生适配（AI 辅助生成）

说明：本仓库的 macOS 原生 Helper（runtime/bin/darwin/dsh-dafeiyu-helper.app） 及 native/macos/ 下的 Swift 源码由 AI 辅助生成，经人工 review 与调试后合入， 用于替代原 Qt/PySide6 与 PyObjC 原型在 macOS 上不稳定、易崩溃的问题。

重做了哪些地方

兼容性

开发与测试

pnpm install
npm test
py -3 -m unittest discover -s runtime/tests -t .

开发时可以从源码运行 Helper，但正式用户不应手动启动它：

py -3 -m pip install -r requirements.txt
py -3 runtime\helper.py

构建 Windows Helper：

python -m pip install -r requirements.txt pyinstaller
$env:DSH_DAFEIYU_BUILD_PYTHON = (Get-Command python).Source
npm run build:helper:windows

构建 Linux Helper（需在 Linux x86_64 上；官方发布在 Ubuntu 22.04 上构建， 以保证 glibc 2.35 基线）：

python3 -m pip install -r requirements.txt pyinstaller
export DSH_DAFEIYU_BUILD_PYTHON="$(command -v python3)"
npm run build:helper:linux

macOS 原生 Helper 的构建说明见 native/macos/README.md。

更多文档

相关项目：QCYTSN/ds-local-pet 是独立桌宠版本； 本仓库是只服务于 DSH 状态的插件版本。

License

代码采用 MIT License。角色视觉资产不适用 MIT 代码许可证，来源和使用边界 见 ASSET_LICENSE.md。

dsh-dafeiyu (QCYTSN/dsh-dafeiyu)

Searching Database…

451 ·GitHub
Dsh-dafeiyu
What is this?DSH BigFish (大肥鱼) is a desktop companion character that lives on your screen and visually reflects the real-time working status of DeepSeek Harness (DSH) agent sessions - thinking, working, waiting, error or done - shown as an always-on-top transparent window.
Is this a standalone desktop-pet app or does it need DSH installed?It is not a standalone desktop-pet app - it is a plugin enabled by DSH itself. It starts and exits together with the DSH Host process and only renders as a native overlay window; closing the browser tab does not close it.
What do I need before installing it?You need a working DeepSeek Harness WebUI already installed, with a CLI that supports the plugin --profile web command. Regular users don't need Python, PySide6, or Xcode - the Windows, Linux and macOS Helper binaries are already bundled inside the release package.
Does it work the same way on every platform?No - Windows 10/11 and WSL2 are the primary targets, Linux desktop support requires glibc 2.35+ and has only been verified on Ubuntu 24.04, and macOS support (Apple Silicon or Intel, 12.0+) is explicitly experimental, shipped as an ad-hoc-signed build that isn't notarized.
How does BigFish know what DSH is doing?It only reacts to DSH's own agent events - project name, current phase, active to-do, and real completion counts - it never watches VS Code, the browser, other windows, or takes screenshots.
What can I customize?Character size (55%-140%), status bubble size and visibility, idle-animation activity level, a 'reduce motion' mode, completion/error sound alerts, and whether sub-agent status affects priority; all settings are saved by DSH itself.
Why might macOS Gatekeeper block it?Only if you unzip the downloaded .app with Finder, which adds a quarantine flag. Installing via npm, downloading through the terminal, or running the .tgz installer directly never triggers Gatekeeper.
What happens if I close the DSH browser tab?Nothing - BigFish is tied to the DSH Host process lifecycle, not the browser tab, so it keeps running on the desktop until DSH Host itself fully quits.
What are similar projects?dsh_desktop, dsh-pet, deepseek-harness-desktop, Bigfish, dsh-tavern, pilot-harness, dsh-damage-pulse, dsh-plugin-agent-workflow
Which topics is it in?desktop-pet, dsh, dsh-plugin, deepseek-harness, apple-silicon, swift, deepseek, customization, monitoring, plugin, desktop, ai-agent
Creator
QCYTSN
Size
95.9 MB
Stars
451
Updated
CommitOct 10Releasev0.1.18Oct 10
Age
2mo
Commits · 90 Days