# petdex

> Mirrors DeepSeek Harness Web session lifecycle events to the Petdex desktop floating window, allowing the desktop pet to switch animations based on DSH task status. macOS only.

## Metadata

- Author: [@crafter-station](https://github.com/crafter-station)
- Repo: <https://github.com/crafter-station/petdex.git>
- GitHub: [crafter-station/petdex](https://github.com/crafter-station/petdex)
- Stars: 3,935
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://petdex.dev>
- Topics: `claude-code`, `clerk`, `cli`, `codex`, `developer-tools`, `drizzle-orm`, `dsh-plugin`, `mascot`, `neon`, `nextjs`, `pixel-art`, `postgres`, `react`, `sprites`, `tailwindcss`, `vercel`
- Forks: 185
- Open Issues: 18
- Last push: 2026-08-20T15:10:09.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:crafter-station/petdex/packages/petdex-desktop-native/integrations/dsh
```

## Wiki

## 一句话定位
这个插件是 Petdex 桌面浮窗的 DeepSeek Harness 适配器：它把 DSH Web 的会话生命周期事件归一化成 5 个状态，POST 到 Petdex 桌面自带的本机 hook server（127.0.0.1:7777），让那只像素宠物根据你正在 DSH 里跑的任务切换动画——开始跳、跑任务变忙、等你审批就举手、做完就挥手。

## 核心能力
- 监听 DSH Web 的 session/created、session/disposed、session/event 三类会话生命周期事件
- 把 turn、step、tool、workflow、goal、compaction 等事件归一化成 jumping / running / waiting / waving / failed 五个 Petdex 状态
- 子代理（subagent）的事件折叠到顶层会话的同一张卡片，不会为子代理开新卡片
- 审批请求（approval/asked、approval/decided）只反映成"举手要你注意"的状态，不替你批准或拒绝任何操作
- 通过 token 鉴权把归一化结果 POST 到本机 127.0.0.1:7777 的 /state 和 /bubble，全程不携带提示词、工具参数、模型输出
- Petdex 桌面没启动时，整个投递链路 fail-open，绝不影响 DSH 正常运行

## 技术实现
- **语言**: JavaScript（ESM，源码为 .js；Cordis bundle 不是 TS）
- **关键依赖**: 无第三方依赖；只使用 Node 内置 `node:fs/promises`、`node:os`、`node:path`，不引入 npm 包
- **架构模式**: Cordis 插件（`cordis.patch.yml` 注册 `id: petdex-dsh-bridge`，`inject: ["sessions"]`）；监听官方 lifecycle 事件后做归一化、合并去重、限速（队列上限 64，单次请求 300ms 超时），通过 loopback HTTP 把"事件投影"投递给 Petdex 桌面的内置 hook server
- **入口文件**: `src/index.js`（导出 `apply`、`createBridge`、`projectionToRequests`、`name`、`inject`），归一化逻辑在 `src/normalize.js`

## 适用场景
你已经在 macOS 上用 DSH Web 跑任务，同时开着 Petdex 桌面浮窗：装上这个插件后，宠物会根据你当前在 DSH 里的工作状态动起来——开始任务时跳起来、跑工具时变忙、需要你审批时举手、做完就挥手。它适合"一边跟 DSH 对话，一边用浮窗上的小动物确认任务在不在跑"的人。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (DSH) | 0.1.0-rc.6 | 由 Petdex 桌面安装器硬编码固定，命令里 `--package=@deepseek-ai/dsh@0.1.0-rc.6` |
| pnpm | 11.19.0 | 仅在桌面安装命令里临时 npx 拉取，不需要全局安装 |
| Node | 未声明 | 插件本体未在 package.json 声明；桌面侧用 Bun 打包 tarball |
| 平台 | macOS | agent_hooks.zig 注释明确"DSH Web is macOS-only in the first integration slice" |
| 原生模块 | 无 | 仅使用 Node 内置模块，无 native 依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:crafter-station/petdex/packages/petdex-desktop-native/integrations/dsh
```

> 实际安装流程由 Petdex 桌面 App 的 Settings → Agents → DeepSeek Harness → Install 触发：桌面试图把内嵌的 `petdex-dsh-plugin-0.1.0.tgz`（SHA256 已固化）落盘到 `~/.petdex/integrations/dsh/0.1.0/`，再通过 macOS 登录 shell 跑 `npx ... dsh plugin --profile web add --ignore-scripts <tarball>`。安装完成后必须手动重启 DSH Web。

## 配置项
本插件无需额外配置。`apply(ctx, config = {})` 接收的 config 默认是空对象，且插件内只读取 `options.deliver`（用于测试注入的 mock 投递函数），运行时不会读取任何用户配置。

唯一的隐式约束来自 Petdex 桌面的安装命令：`DSH` 版本被硬编码为 `0.1.0-rc.6`，`pnpm` 被硬编码为 `11.19.0`，无法通过插件配置改动。

## 常见问题

**Q: 安装完之后为什么 Petdex 还显示"Restart DSH Web"？**

A: 这个插件是 Cordis bundle，不会被 DSH 热加载。安装成功后必须手动重启一次 `npx @deepseek-ai/dsh web`，然后启动或继续一个真实任务，Petdex 才会从 `~/.petdex/runtime/dsh-handshake.json` 读到握手信息并显示 Connected。单纯打开 DSH 不触发任何事件，握手不会完成。

**Q: 插件会把我的提示词、工具参数、模型输出发给 Petdex 吗？**

A: 不会。插件只监听官方 session lifecycle 事件，归一化后只投影状态（jumping/running/waiting/waving/failed）、显示文案、会话 ID、序号和事件类型；提示词、工具参数、模型输出和审批内容都被丢弃。POST 只发到本机 127.0.0.1:7777，并需要 `~/.petdex/runtime/update-token` 里的 token 鉴权。

**Q: 我点宠物应该会跳转到 DSH 当前会话，为什么只打开了默认浏览器？**

A: V1 没有精确的浏览器 tab 定位能力。点宠物只会激活当前 macOS 默认浏览器，不会跳到任何 URL、不会打开新标签，也不会区分 DSH 占用了哪个 tab。这是当前刻意保留的兜底行为，不是 bug。

**Q: 我把 DSH 装在自定义目录（DSH_HOME 指向非 ~/.dsh）怎么配置？**

A: 在 Petdex 进程的运行环境里设置同名 DSH_HOME。从 Finder 启动的 Petdex 不会继承只在交互式 shell 里 export 的变量；如果 DSH 用了自定义 home，安装前需要把 DSH_HOME 也注入到 Petdex 进程可见的环境里，否则 Petdex 会找不到 profile。

**Q: 卸载后 DSH Web 里还能看到这个插件怎么办？**

A: 卸载命令只调用 `dsh plugin --profile web remove @petdex/dsh-plugin`，不会清掉 DSH profiles、sessions、models 或其它插件。卸载完成后同样需要手动重启一次 DSH Web，让运行中的进程卸载插件 bundle。

**Q: 安装命令报 "Plugin command failed - check npx and network" 怎么排查？**

A: 桌面端跑的是 `npx --package=@deepseek-ai/dsh@0.1.0-rc.6 --package=pnpm@11.19.0 dsh plugin --profile web add`，需要 npx 和能访问 npm registry。装全局 pnpm 不是必须的（命令里带了内嵌版本）。错误通常意味着 Finder 启动的 shell 没继承 PATH、registry 不通，或者桌面包里的 tarball 哈希校验失败（桌面会清掉握手并报错）。

**Q: 这个插件能在 Linux 或 Windows 上用吗？**

A: 不能。Petdex 桌面本身跨平台，但 DSH 集成是 macOS 优先的首发切片（agent_hooks.zig 注释明确写了"DSH Web is macOS-only in the first integration slice"）。Linux/Windows 上 Petdex Settings 里 DeepSeek Harness 这一行只会显示 Not detected。

## 上手难度
入门 — 桌面 App 一键安装，重启 DSH Web 即用，不需要改任何代码或配置；但要理解"为什么装完还要重启"需要看一眼 Petdex 的 handshake 文件。

## 已知问题与限制
- **仅支持 macOS**：插件运行时不限制平台（任何能跑 DSH Web 的系统都能加载），但 Petdex 桌面的安装与状态检测路径在非 macOS 上被显式短路，Linux/Windows 用户看不到安装入口
- **不支持精确浏览器 tab 定位**：点击宠物只能激活默认浏览器，不会跳到 DSH 当前会话
- **安装/卸载都需手动重启 DSH Web**：Cordis bundle 不热加载，状态机从 `restart_required` 走到 `connected` 必须等用户重启 + 真实事件
- **DSH 版本被桌面侧硬编码到 0.1.0-rc.6**：插件本体的 `package.json` 没有声明 DSH 兼容性；如果 DSH 升级到不兼容的版本，桌面需要同步更新 `dsh_integration.zig` 里的版本字符串
- **投递队列上限 64、单次请求 300ms 超时**：极端高频事件下非关键进度事件会被合并丢弃，但所有干预类（approval）和终结类（turn.completed/failed/blocked）事件保留优先级
- **从 Finder 启动的 Petdex 不会继承交互式 shell 的环境变量**：自定义 `DSH_HOME` 必须显式注入到桌面进程可见的环境

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [petdex](https://deepseek-plugin.org/plugins/crafter-station/petdex/packages/petdex-desktop-native/integrations/dsh)
Wiki generated by AI (model: `MiniMax-M3`)