petdex/packages/petdex-desktop-native/integrations/dsh

3.9kStar185Fork18Issue10Watching

把 DeepSeek Harness Web 的会话生命周期事件镜像到 Petdex 桌面浮窗，让桌面宠物根据 DSH 任务状态切换动画，仅 macOS。

分类🔌 集成与服务🐾 趣味与陪伴
crafter-stationcrafter-station
·crafter-station/petdex.git·petdex.dev
语言
TypeScript
License
MIT
分支
main
claude-codeclerkclicodexdeveloper-toolsdrizzle-ormdsh-pluginmascot

安装

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

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

这个插件是 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
pnpm11.19.0仅在桌面安装命令里临时 npx 拉取，不需要全局安装
Node未声明插件本体未在 package.json 声明；桌面侧用 Bun 打包 tarball
平台macOSagent_hooks.zig 注释明确"DSH Web is macOS-only in the first integration slice"
原生模块无仅使用 Node 内置模块，无 native 依赖

安装方式

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 必须显式注入到桌面进程可见的环境
返回插件目录