dsh-plugin-petdex-market

DSH Petdex Market · 宠物市集插件

在 DSH Settings 里逛 petdex.dev 实时市集，装一只桌面宠物陪 agent 干活。
A petdex.dev companion-pet market in DSH Settings, with a native macOS desktop pet.

接入面 —— Settings 页签（settings.section slot）· petdex-market settings 命名空间 · /petdex-market/* HTTP API

一个 DSH（DeepSeek Harness） 插件：在 Settings 的 Petdex 页签浏览 petdex.dev 实时市集，

安装 / 启用 / 改名 / 删除宠物（单活跃伙伴模型），并把活跃宠物渲染为原生桌面宠物（Swift/AppKit 透明置顶窗口；

agent 工作时奔跑，回复落地时挥手 + 气泡）。

数据流向：目录直连 petdex.dev（/api/manifest + /api/pets/search，约 4,500 只），贴图经服务端

同源代理转发给 WebView 与渲染器（内存缓存可一键清空）。接入：一条命令

dsh plugin --profile web add github:NattoCB/dsh-plugin-petdex-market，重启后 Settings 出现 Petdex 页签；渲染器每 2 秒轮询 GET /petdex-market/desktop。

✨ 功能一览 / Features

• 🛒 实时市集 Market：live catalog 直连 petdex.dev（/api/manifest + /api/pets/search，约 4,500 只）；按名称 / 种类 / 作者搜索、分页、5 种排序（curated / newest / most-liked / most-installed / alphabetical）。stats 排序首次请求在后台构建全量索引（60 只/页、并发 8、约 76 个请求），期间回退 manifest 顺序并标记 sortReady: false。
• 🐾 宠物管理 Pets：「安装」= 在 petdex-market.pets 持久化一条记录并托管其预览，不下载宠物文件；单活跃伙伴模型——启用一只自动禁用其余，安装即设为活跃，删除活跃宠物后自动切换下一只已启用宠物。
• 🖼️ 同源贴图代理 Sprite proxy：市集与已装宠物的 spritesheet 全部经 /petdex-market/sprite/<slug>、/petdex-market/installed/<id>/sprite 服务端转发，WebView 预览无 CORS 问题；10 分钟 TTL 缓存，Settings 内一键清空。
• 🦎 原生桌面宠物 Desktop pet：petdex-renderer（Swift/AppKit）透明、无边框、置顶窗口，沿主屏幕底部自主行走、边缘折返、可拖拽（拖后冻结 3 秒）、右键菜单（禁用 / 重载 / 退出）；尺寸 0.4–2.5 倍等比缩放，liveliness 控制行走 / 休息占空比。
• 🏃 感知 agent 工作状态 Activity：订阅 DSH session/event——turn/start → 奔跑，assistant/message → 暂存气泡文本，turn/end → 挥手 + 弹一次气泡（多段回复只挥手一次，气泡截断至 120 字符）；渲染器每 2 秒轮询 GET /petdex-market/desktop。
• ⚙️ 配置热加载 Hot reload：全部设置存于 petdex-market settings 命名空间（写入 settings.yaml），改动即时生效，无需重启；渲染器进程由服务端管理（spawn / kill，崩溃 2 秒后自动重启一次）。

📸 效果预览 / Preview

🚀 Quick Start

前置 / Prerequisites

• 可用的 DSH 及 web profile（a working DSH with a web profile）
• macOS（桌面渲染器为 Swift/AppKit 原生二进制）

安装 / Install

一行安装（one-line install）：

dsh plugin --profile web add github:NattoCB/dsh-plugin-petdex-market

本地路径安装（开发 / 离线）：

git clone <this-repo> dsh-plugin-petdex-market

在 ~/.dsh/profiles/web/package.json 注册依赖与 bundle：

{
  "dependencies": {
    "@jasper/dsh-plugin-petdex-market": "file:/path/to/dsh-plugin-petdex-market"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@jasper/dsh-plugin-petdex-market"
      ]
    }
  }
}

然后链进 profile：

dsh plugin --profile web add /path/to/dsh-plugin-petdex-market
# 手动等价方式：在 ~/.dsh/profiles/web/node_modules/@jasper/ 下 symlink

运行 / Run

在 ~/.dsh/settings.yaml 启用：

petdex-market:
  enabled: true
  desktopEnabled: true   # 渲染桌面宠物
  petScale: 1            # 0.4 – 2.5
  petLiveliness: 0.6     # 0 (calm) – 1 (lively)
  bubbleEnabled: true

重启 dsh web，Settings 出现 Petdex 页签——挑一只，开始干活。

⚙️ Configuration

pets 与 activePetId 由插件自动管理（auto-managed）。全部配置热加载，修改无需重启。

🌐 HTTP API

🔨 Build

仅在改动前端 UI 或原生渲染器时需要。

# 1. client bundle（esbuild，临时 dev dependency）
npm i -D esbuild
node build-client.mjs          # 写入 client/client.js（window.__ModuleLoader__ 加载）

# 2. 原生 macOS 渲染器（需要 Xcode Command Line Tools）
swiftc -O renderer/main.swift -o petdex-renderer

🧱 Architecture

dsh-plugin-petdex-market/
├── src/
│   ├── index.js        # server：settings 命名空间、/petdex-market API、
│   │                   #   单活跃约束、session/event → 宠物状态、
│   │                   #   渲染器进程生命周期（spawn/kill/watchdog）
│   └── petdex.js       # petdex.dev client（manifest、pet.json 归一化、目录索引、贴图缓存）
├── renderer/main.swift # 原生 macOS 宠物窗口（透明置顶、行走器、拖拽、气泡、右键菜单）
├── client_src.tsx      # Settings 页签组件
├── client/client.js    # esbuild 产物，window.__ModuleLoader__.load() 挂载 settings.section slot
├── cordis.patch.yml    # bundle 注册（settings + sessions 注入）
└── build-client.mjs    # client 打包脚本

服务端订阅 DSH session/event（用户消息 → 宠物 run；助手回复 → wave + 气泡）， 通过 GET /petdex-market/desktop 暴露最新活动状态；渲染器每 2 秒轮询一次。

Credits · 致谢

宠物素材与目录来自 petdex.dev 及其社区。 Pet artwork and catalog by petdex.dev and their community.

GitHub · Issues · LICENSE · MIT