deepseek-haeness-pet

A floating whale mascot for the DeepSeek Harness Web GUI — inspired by the DeepSeek whale logo and the Codex "pet" — that shows what the agent is doing right now.

一个 DeepSeek Harness Web GUI 的浮动鲸鱼小宠物（参考 DeepSeek 鲸鱼 logo 与 Codex 的宠物功能），实时展示当前 agent / tool 的执行状态。

(add a screenshot at docs/demo.png to show it in action / 把运行截图放到 docs/demo.png 展示效果)

---

⚠️ Read this first / 先看这里

This is not a standalone npm package. It is a plugin written for the DeepSeek Harness monorepo: it depends on the harness's internal @deepseek-ai/* workspace packages and its build pipeline (tsc + tsdown + the Typert Remote codegen). To use it you copy the two packages into a harness checkout, wire them into the composition, and rebuild — see Integration.

它不是一个可以 npm install 直接用的独立包。 这是为 DeepSeek Harness monorepo 写的插件：依赖 harness 内部的 @deepseek-ai/* workspace 包与构建管线（tsc + tsdown + Typert Remote 代码生成）。使用方式是把它拷进 harness 仓库、接入 composition 并重新构建，见下文「集成步骤」。

---

What it does / 功能

A small blue whale floats in the corner of the GUI and reflects the agent loop:

State	Behaviour	状态说明
idle	slow breathing, bubble says 空闲中 · 待命中	空闲：缓慢浮动
thinking	faster bob + blue pulse, 思考中…	思考中：加速浮动 + 蓝色脉冲点
running a tool	water spout + green pulse, 正在执行 <tool> · <arg>	执行工具：喷水动画 + 绿色脉冲点

Click the whale to expand a recent-activity log; drag it to reposition. It follows the GUI's light/dark theme via the --dsw-alias-* design tokens.

点击鲸鱼可展开「最近活动」日志，可拖拽移动位置；配色随 GUI 明暗主题自适应。

Architecture / 架构

Two packages, split along the Harness's host/client boundary:

Package	Plane	Role
@deepseek-ai/dsh-pet	Host	Listens to agent/status, tools/pre-execute, tools/result, keeps the live status + activity ring, and exposes a read-only @Remote('state') snapshot.
@deepseek-ai/dsh-client-ui-pet	Client	A dsh.client plugin that renders the whale in the shell.overlay layer and polls ctx.remote.pet.state() every ~700 ms.

包	平面	职责
@deepseek-ai/dsh-pet	Host	监听 agent/status、tools/pre-execute、tools/result，维护当前状态与活动环形缓冲，通过 @Remote('state') 暴露只读快照。
@deepseek-ai/dsh-client-ui-pet	Client	dsh.client 插件，在 shell.overlay 浮动层画鲸鱼，约每 700ms 轮询 ctx.remote.pet.state()。

Repository layout / 目录结构

packages/
├── pet/pet/                 → host service, copies to <harness>/packages/pet/pet/
└── client/ui-pet/           → client UI,   copies to <harness>/packages/client/ui-pet/

Integration / 集成步骤

Copy the two packages into a DeepSeek Harness checkout, then wire the composition, project references, path mapping, and the Remote assembly. The full, ordered checklist lives in docs/INTEGRATION.md — it was derived by actually getting a build to pass, so follow it exactly.

把两个包拷进 DeepSeek Harness 仓库，然后依次接入 composition、project references、路径映射、Remote 装配。完整步骤见 docs/INTEGRATION.md——它是实测构建通过后整理出来的，请按步骤来。

Quick sketch（速览）:

1. Copy packages/pet/pet and packages/client/ui-pet into the harness repo.
2. Add the pet + ui-pet rows to packages/bundle/web-app/cordis.patch.yml, and mirror them in that bundle's package.json dependencies (missing this is the classic ERR_MODULE_NOT_FOUND).
3. Register the project references, the dsh-pet path mappings, and the remote.pet assembly (see INTEGRATION.md).
4. pnpm install → pnpm run build → restart dsh web → refresh.

Compatibility / 兼容性

Built and verified against the DeepSeek Harness revision it was developed on. Because the integration touches the harness's explicit reference/manifest lists, the exact line positions may drift across harness versions — treat the steps as a guide and reconcile against the files in your checkout.

在与开发时同版本的 DeepSeek Harness 上构建并验证通过。因为集成要改 harness 的显式引用清单，不同版本的行位置可能变化——请以你本地 harness 的文件为准做对齐。

License / 授权

MIT — same as the DeepSeek Harness itself.