# dsh-dafeiyu

> Provides a Windows desktop floating widget for DeepSeek Harness, switching state actions based on real-time agent events while displaying project phases and to-do progress.

## Metadata

- Author: [@QCYTSN](https://github.com/QCYTSN)
- Repo: <https://github.com/QCYTSN/dsh-dafeiyu.git>
- GitHub: [QCYTSN/dsh-dafeiyu](https://github.com/QCYTSN/dsh-dafeiyu)
- Stars: 201
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-companion`, `deepseek-harness`, `desktop-pet`, `dsh-plugin`, `windows`
- Forks: 23
- Open Issues: 9
- Last push: 2026-08-20T01:29:02.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:QCYTSN/dsh-dafeiyu
```

## Wiki

## One-Line Description
DSH Da Fei Yu is a small fish floating window that stays on top of the Windows desktop. It is enabled by the DeepSeek Harness plugin and starts/exits together with DSH. By subscribing to DSH's Session events, it can switch between thinking, working, waiting, completed, and error states in real-time, allowing you to see what the Agent is currently doing at a glance even when you switch to VS Code, browsers, or other software.

## Core Features
- Displays the character on the Windows desktop as a borderless, transparent, always-on-top window, bound to the DSH Host lifecycle
- Maps DSH Agent events (turn/start, assistant/message, tool/call, tool/result, todo/write, turn/end, etc.) into 7 states: Idle, Thinking, Working, Waiting, Completed, Error, Disconnected
- Based on the current phase and actual todos, displays the project name, phase name, current todo, and "Completed N/M steps" progress in the bubble
- When multiple DSH Sessions run in parallel, selects the most attention-requiring task based on priority (Waiting > Error > Working > Thinking > Idle), while listing other active tasks in the bubble
- Adjust size, bubble, activity level, whether to respond to sub-agents and other parameters in real-time through DSH WebUI's "Settings → Plugins → Plugin Config → Da Fei Yu Desktop Companion" without needing to restart the floating window
- Supports desktop interactions such as drag, single/double click, right-click menu, hide for this session, close for this session, etc.; window position and settings are automatically saved

## Technical Implementation
- **Languages**: JavaScript (Node.js, ESM) + Python 3 (Helper subprocess, PySide6/Qt desktop rendering)
- **Key Dependencies**: @deepseek-ai/schemastery (Schema definition for DSH settings panel); PySide6>=6.7,<7 (Helper desktop rendering); PyInstaller (packages Helper into .exe, regular users don't need to install themselves)
- **Architecture Pattern**: DSH plugin injects via Cordis patch, injecting sub-capabilities like settings, webServer, sessions into `apply()`; subscribes to global `session/event` and `session/disposed`, with `CompanionReducer` merging events into a message stream, then writes to Helper subprocess's stdin via JSONL protocol; Helper renders transparent borderless window with `Qt.WindowStaysOnTopHint | FramelessWindowHint`, and receives configuration via environment variables (DSH_DAFEIYU_SCALE, etc.)
- **Entry Files**: Node side `src/index.js` (exports `apply`, `Config` Schema, `HelperProcess`, `CompanionReducer`); DSH settings panel `lib/client.js` (injects `@deepseek-ai/dsh-client-ui-settings-plugins`); desktop rendering `runtime/helper.py`

## Use Cases
DSH Da Fei Yu is suitable for users who "open DSH and let the Agent work on its own, while they go write code in VS Code or attend meetings": you want to know at any time whether the Agent is still thinking, stuck on which tool call, waiting for your confirmation, or has finished this round, but don't want to constantly switch back to the DSH tab. It doesn't read screens or monitor other applications—the state comes entirely from DSH's real event stream, making it suitable for scenarios requiring privacy and "only seeing real progress"; it's not suitable for users who need screenshots, monitoring other applications, or displaying desktop companions on macOS or pure Linux.

## Prerequisites & Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH | Not declared | Plugin injects via `dsh.bundle.patch`, requires DSH WebUI (`dsh plugin --profile web`) |
| Node.js | >=22.19 | Only needed by plugin host process (package.json#engines.node) |
| Python + PySide6 | Python 3 + PySide6>=6.7,<7 | Only needed when developing from source or rebuilding Helper; regular users don't need to install themselves via prebuilt .exe |
| Operating System | Windows 10/11 x64 | Desktop floating window runtime target; CPU restricted to x64 |
| WSL2 | — | Can install via `dsh plugin --profile web add` in WSL terminal, Helper runs via `cmd.exe` calling Windows .exe |
| Native Modules | PySide6 (Helper only) | Helper is already packaged as standalone .exe via PyInstaller in the package |

## Installation
```bash
dsh plugin --profile web add github:QCYTSN/dsh-dafeiyu
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| 启用大肥鱼 | Toggle | Exits desktop companion immediately when disabled; no manual restart needed when re-enabled | Enabled |
| 角色大小 | 70%–140% (Slider) | Adjusts overall size of desktop floating window character | 100% |
| 气泡大小 | 80%–120% (Slider) | Adjusts status bubble size, balancing information readability | 100% |
| 活跃程度 | Quiet / Standard / Lively | Controls frequency of micro-movements like blinking and observing when idle | Standard |
| 减少动态效果 | Toggle | Reduces walking, loop frames and programmatic swaying; rendering frame rate also drops to 25 FPS | Disabled |
| 气泡显示 | Always Show / Fully Hide / Custom | In custom mode, can check which states show bubbles | Always Show |
| 自定义显示状态 | Multi-select (Idle/Thinking/Working/Waiting/Completed/Error) | Only effective when "Bubble Display=Custom", determines which states show bubbles | Completed, Error, Waiting |
| 响应子 Agent | Toggle | Allows sub-agents to seize pet status when enabled; defaults to following only top-level tasks to avoid excessive state jumping | Disabled |

## FAQ
**Q: Installation command succeeded, but I can't see Da Fei Yu on the desktop.**

A: First confirm the installation used `--profile web`; then you must completely exit DSH Host (not just close the browser tab) and restart; go to DSH's "Settings → Plugins → Plugin Config → Da Fei Yu Desktop Companion" and confirm "Enable Da Fei Yu" is checked; also confirm you're using the installation package with prebuilt Helper (runtime/bin/win32-x64/dsh-dafeiyu-helper.exe exists), not just source code clone.

**Q: I closed the DSH browser tab, but Da Fei Yu is still on the desktop.**

A: Da Fei Yu is bound to the DSH Host process lifecycle, not the browser tab. As long as DSH is still running in the background, it will continue to display; it will automatically close after completely exiting DSH Host.

**Q: Why does the status card only show the phase name without "Completed N/M steps" numbers?**

A: Numbered progress is only reliably calculated when the DSH Agent writes structured todos (todo/write events). When DSH doesn't provide real todos, the status card only displays the current working phase to avoid fabricating percentages.

**Q: After right-clicking "Close for This Session", Da Fei Yu didn't come back automatically.**

A: Expected behavior. "Close for This Session" suppresses auto-restart during the current DSH run; it will recover after completely exiting and restarting DSH. To permanently close, just uncheck "Enable Da Fei Yu" in DSH settings.

**Q: I'm a regular user, do I need to install Python or PySide6 myself?**

A: No. The npm alpha package and GitHub Release .tgz package already include the Windows x64 dsh-dafeiyu-helper.exe (PyInstaller packaged), and DSH will automatically pull it up. Only when developing from source or rebuilding Helper yourself do you need to install PySide6>=6.7,<7 locally.

**Q: Can I use it on macOS or pure Linux?**

A: No. The current Alpha desktop floating window only supports Windows x64; WSL2 can display the floating window by calling the Windows Helper via cmd.exe, but regular Linux, remote Linux, and containers are not targets for this version's desktop display.

**Q: Does this plugin read the screen, monitor other applications, or upload data?**

A: No. The plugin only subscribes to DSH's session/event and session/disposed, doesn't read or save model API Keys, doesn't take screenshots, doesn't monitor keyboard or other applications, and doesn't send telemetry; the settings card reuses DSH's own local Web service (/plugins/dsh-dafeiyu/config, and only accepts 127.0.0.1 requests), doesn't open new network ports.

**Q: How do I uninstall?**

A: Completely exit DSH Host, then run `dsh plugin --profile web remove dsh-dafeiyu`, then restart DSH. Plugin code and Helper will be removed from the web profile; DSH may retain a historical settings file that no longer takes effect, which won't start processes or occupy ports.

## Getting Started Difficulty
Beginner — No additional configuration needed: install the plugin, start DSH, start a task and you can see Da Fei Yu working; the only things to care about are "confirm the system is Windows x64", and the few toggles in the settings panel are all in the Chinese UI.

## Known Issues & Limitations
- **Alpha Status**: Version is `0.1.0-alpha.12`, settings panel and desktop status text use Simplified Chinese (README.md:81), interface and defaults may still be adjusted.
- **Windows x64 + WSL2 Only**: Helper actually runs on Windows x64; regular Linux, remote Linux, containers, macOS cannot display desktop floating windows (README.md:111-112, src/helper-process.js:16-31).
- **Bad Historical Version**: 0.1.0-alpha.7 released Windows Helper missing PySide6/Qt, causing desktop floating window not to appear; this version has been marked "Known broken release" and needs to upgrade to alpha.8 or later (CHANGELOG.md:134-138).
- **DSH Config Sync Issue**: Early alpha version's cordis.patch.yml didn't sync `bubbleScale/bubbleMode/bubbleStates`, DSH Harness updates may cause `failed to apply loader entry`; 0.1.0-alpha.12 has been fixed (CHANGELOG.md:23, cordis.patch.yml:5-15).
- **No Fake Progress**: When DSH doesn't write structured todos, status card only shows current working phase, won't fabricate completion percentage (src/companion-reducer.js:81-90).
- **Sub-Agent Not Responsive by Default**: Defaults to following the most recently active top-level DSH Session; enabling "Respond to Sub-Agent" changes the state priority strategy, which may cause the desktop floating window to change more frequently (README.md:269-276, src/companion-reducer.js:53-56,111-121).
- **Running from Source Requires Python + PySide6**: Only when developers run Helper from source do they need to install PySide6>=6.7,<7 locally (requirements.txt:1, README.md:39-41); regular installation via prebuilt package doesn't need this step.

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-dafeiyu](https://deepseek-plugin.org/plugins/QCYTSN/dsh-dafeiyu)
Wiki generated by AI (model: `MiniMax-M2.5`)