@wangjunjian/dsh-spritely

Readme

# Spritely

中文 | [英文](README.en.md)

> *Your spritely work companion* —— dsh Web 界面的工作精灵，随智能体的工作状态实时做出表情与动作。

Spritely（原名 `ui-sprite` 插件）是一个 dsh 客户端插件，在界面角落放一个会动的小精灵：它观察智能体的活动（待命、思考、撰写、调用工具、等你确认、出错、完成），播放对应姿态，眼珠跟随鼠标，还能被拖到任意位置。

![](images/dsh-plugin-spritely.webp)

## 功能特性

- **四款可切换角色** —— 蓝球（Blob）、薄荷机器人（Bot）、猫咪（Cat）、幽灵（Ghost），各有独特造型与眼睛风格。
- **实时工作状态姿态** —— 待命 / 思考 / 撰写 / 工作 / 等待 / 出错，以及运行收尾时的短暂庆祝。
- **眼珠跟随鼠标**（rAF 节流）。
- **可拖拽** —— 拖到任意位置，一键归位。
- **自定义背景** —— 纯色、渐变、图片 URL、本地图片上传，支持等比居中 / 全屏拉伸缩放 + 淡化遮罩（保证文字可读）。
- **科幻 HUD 风格** —— 菜单与面板采用固定深色全息配色 + 青色霓虹描边。
- **划词悬浮工具条** —— 在会话消息里选中文字，弹出操作条：复制、朗读（浏览器语音合成）、提问（选中内容以引用块格式进入输入框，光标落到下一行等你补充）。
- **持久化** —— 角色、背景、位置保存在 DSH Host 的用户设置文档（`~/.dsh/settings.yaml`），本机的所有浏览器共享；非本机回环的浏览器（局域网访问）回退到 localStorage。

![](images/demo1.webp)

![](images/demo2.webp)

## 安装

Spritely 同时声明了 `dsh.bundle`（附带 `cordis.patch.yml` 补丁层）与 `dsh.client`（`platform: web`），一条命令即可完成安装与登记：

```bash
# 从 npm 安装
dsh plugin --profile <name> add @wangjunjian/dsh-spritely

# 或从 git 安装
dsh plugin --profile <name> add github:wang-junjian/spritely

# 或从本地源码
dsh plugin --profile <name> add ./spritely
```

`add` 会应用包自带的补丁层，往配置树插入 `id: ui-sprite` / `name: '@wangjunjian/dsh-spritely'` 一行；宿主 Loader 随即读到它的 `dsh.client` 元数据，serve `/plugins/@wangjunjian/dsh-spritely/client.js` 并注入 `window.__DSH_BOOT__`。

构建产物（`lib/`）不入库：git / 本地源码安装由 `prepare` 脚本自动构建，npm 包自带产物。

> 它的 peer 依赖（`@deepseek-ai/dsh-client-runtime`、`dsh-client-ui-layout`、`dsh-client-locale` 等）都是 dsh 自带的 in-box 包，从 dsh 安装本身解析，无需单独安装。

> 如果你按旧版说明手动往 `~/.dsh/profiles/<name>/cordis.patch.yml` 加过 `ui-sprite` 的 row，升级后请删掉那行，避免重复登记。

## 使用

点击精灵打开菜单：

- **新会话** —— 开启新会话（默认工作区流程）。
- **归位** —— 回到默认右下角。
- **设置背景** —— 打开背景控制台（纯色、渐变、图片 URL、本地上传、缩放、淡化）。
- **选择精灵** —— 在四款角色中切换。

## 角色

| 角色 | 造型 | 配色 |
|---|---|---|
| 蓝球 Blob | 圆球 + 天线星 | 蓝 |
| 机器人 Bot | 圆角方头 + LED 眼 | 薄荷绿 |
| 猫咪 Cat | 三角耳 + 竖瞳 + 胡须 | 橙 |
| 幽灵 Ghost | 波浪底边 + 大圆眼 | 紫 |

## 开发

```bash
npm install          # 安装 dsh peer 依赖 + 开发工具链
npm run build        # tsc（类型）+ tsdown（node 半 lib + 浏览器 client bundle）
npm test             # vitest
npm run watch        # tsdown --watch
```

构建产出 node 半库（`lib/index.js`、`lib/invariant.js`）和浏览器客户端 bundle（`lib/client.js`，dsh 的 `__ModuleLoader__` 闭包工厂格式），CSS Modules 由 lightningcss 内联。

## License

[MIT](./LICENSE)