dsh-xmlans
xmlans/dsh-xmlans
Desktop pet for DSH: 兰酱, an angel-winged maid in a transparent always-on-top window who reacts to session states (thinking, working, waiting, done, error), shows task progress and DeepSeek balance, and responds to drags, head pats, pokes and wing touches.
설치
dsh plugin --profile web add github:xmlans/dsh-xmlansREADME
兰酱由 DSH 插件启动，随 DSH 一起退出。透明、无边框、始终置顶的原生窗口，让你在编辑器、浏览器或其他应用中也能看到 Agent 的工作状态。
当前版本：0.1.0。 安装时填写
dsh-xmlans@0.1.0；离线安装使用dsh-xmlans-0.1.0.tgz，Windows、Linux 与 macOS 共用这一个包。角色是白发、天使翅膀的女仆兰酱，动作帧离线渲染（竖版 256 × 352，24 fps）。
能做什么
- 显示真实任务状态：思考、查找、修改、执行、验证、等待确认、完成和错误。
- 展示项目、步骤、多任务和 DSH 提供的待办进度；没有真实进度时显示阶段。
- 在状态气泡和设置页显示 DeepSeek 余额，区分 API Key 与已登录账户。
- 兼容 WebUI 与官方桌面端的共享客户端；两个客户端使用各自的插件配置。
- 支持拖动、摸头、戳一下、碰翅膀，以及大小、气泡、声音和减少动态设置。
- 可选在 DSH 页面右下角显示轻量角色，默认关闭。
状态来自 DSH 会话事件。兰酱不会读取屏幕；推理强度与进度只显示上游实际提供的信息。
先选你的 DSH 客户端
| 使用方式 | 安装位置 | 设置入口（DSH 0.2） | 角色右键菜单的打开目标 |
|---|---|---|---|
| 浏览器 WebUI | web profile | 左侧插件 → dsh-xmlans | WebUI，默认 http://127.0.0.1:3080/ |
| 官方桌面端 | desktop profile | 左侧插件 → dsh-xmlans | 通过 dsh://open 唤起桌面应用 |
WebUI 中安装的插件不会自动出现在桌面端。 两边都启用会各自启动原生角色，可以在其中一个 profile 关闭“兰酱”。第三方桌面包装器可能仍使用 web profile，请以它的实际启动方式为准。
客户端包中的 platform: web 也适用于官方桌面端：官方 Electron 应用使用同一套 Web 客户端。原生角色由对应 Host 启动。
安装
使用命令行安装、升级或移除前，先完全退出对应 DSH Host；操作后重新启动。通过桌面应用内的插件管理操作时，按应用提示重启。
浏览器 WebUI
已全局安装 DSH：
dsh plugin --profile web add dsh-xmlans@0.1.0
dsh web
使用 npx，无需全局安装 DSH：
npx -y @deepseek-ai/dsh plugin --profile web add dsh-xmlans@0.1.0
npx -y @deepseek-ai/dsh web
从 DeepSeek Harness 源码运行的用户，在 Harness 仓库中执行：
pnpm dsh plugin --profile web add dsh-xmlans@0.1.0
pnpm dsh web
官方桌面端
推荐直接在应用内安装：
- 打开官方 DeepSeek Harness 桌面应用，点击左侧 插件。
- 点击 添加插件，输入
dsh-xmlans@0.1.0，点击 安装。 - 安装成功后点击 立即启用，兰酱会出现在桌面上。
- 在插件列表打开 dsh-xmlans，调整角色、气泡和余额设置，修改实时生效。
这套流程使用桌面应用自带的安装环境，用户无需安装 Node.js 或执行 npm 命令。若应用提示刷新或重启，按提示操作；失败时展开 查看安装详情 并保留日志。
使用命令安装时：
-
先启动一次官方桌面应用，让它初始化
desktopprofile，然后完全退出。 -
使用桌面应用自带的
dsh命令。支持命令注册的版本可从应用菜单的 Manage dsh command… / 管理 dsh 命令入口配置；也可直接调用安装目录的resources/runtime/cli/bin/dsh（Windows 为dsh.cmd）。 -
执行：
dsh plugin --profile desktop add dsh-xmlans@0.1.0 -
重新打开桌面应用，在左侧插件 → dsh-xmlans 调整角色。
这里的 dsh 必须来自桌面应用。 独立安装的 npm / npx @deepseek-ai/dsh CLI 不能修改官方桌面端的 profile。请参考 DSH 官方桌面端说明。
离线安装包
拿到 dsh-xmlans-0.1.0.tgz 后，用对应客户端的命令安装；无需解压：
# WebUI；文件路径替换为实际路径
npx -y @deepseek-ai/dsh plugin --profile web add "C:\Downloads\dsh-xmlans-0.1.0.tgz"
# 官方桌面端；必须使用应用自带的 dsh
dsh plugin --profile desktop add "C:\Downloads\dsh-xmlans-0.1.0.tgz"
桌面端也可在 添加插件 的输入框填写 .tgz 的完整路径。DSH 的插件管理器需要 pnpm 在 PATH 中。自行打包时必须用平铺依赖（npm install --ignore-scripts --no-package-lock --omit=dev && npm pack），不要在 pnpm 安装的目录里直接 npm pack，详见 发布说明。
余额显示
余额默认出现在兰酱状态气泡底部和设置页，查询逻辑由两个客户端共用。设置页可查看总余额、赠送和充值，并手动刷新。
| 来源 | 凭据来自哪里 | 查询内容 |
|---|---|---|
| 自动（默认） | 优先使用 DSH 模型设置中的 DeepSeek API Key；未配置时尝试已登录账户 | 对应来源的余额 |
| API Key | DSH 的凭据服务；旧 Host 无该服务时读取启动环境 | DeepSeek /user/balance |
| 已登录账户 | DSH 的 DeepSeek 账户服务 | 账户充值与赠送钱包 |
- 在 DSH 模型／账户设置中配置凭据；兰酱设置页不需要再填写 API Key。
- API 余额与账户余额分别标明来源；CNY / USD 分别显示。
- 每分钟自动刷新，同一 Host 内共享缓存；手动刷新最快每 5 秒一次。
- 服务失败时保留上次成功结果，并标明“上次查询”；未配置、授权失败和网络失败分别提示。
- 自定义网关需要实现相同的
/user/balance接口；不支持时显示查询失败。 - API Key、登录凭据和上游原始错误不会进入余额页面、角色消息或事件流。
- 没有余额凭据也能正常显示任务状态；可关闭“显示 DeepSeek 余额”。
账户余额和 API 余额的查询方式参考了 keshing/balance-display 与 DSH 的公开账户服务。插件不会发起模型调用。
常用设置
| 设置 | 作用 |
|---|---|
| 启用兰酱 | 开关当前 profile 的原生角色 |
| 角色大小 / 气泡大小 | 独立调整；小气泡保留基本字号 |
| 安静 / 标准 / 活泼 | 每次待机动作结束后，分别休息 45～90 / 25～45 / 12～22 秒 |
| 减少动态 | 固定角色姿势，停止待机与点击动画；状态和提示仍实时更新 |
| 提示音 | 完成／出错时播放声音 |
| 气泡显示 | 常驻、隐藏，或仅在指定状态显示 |
| 子 Agent | 允许子 Agent 状态参与显示 |
| 页面内角色 | 在 DSH 页面右下角显示轻量角色 |
| 打开目标 | 自动、WebUI 或官方桌面端 |
| 显示余额 / 余额来源 | 开关与选择余额查询来源 |
设置页修改实时生效。右键菜单可调整大小、减少动态、打开对应 DSH 客户端，或仅在本次运行隐藏／关闭角色。
点击动作会完整播完，再回到当前任务状态；新任务可立即打断装饰动作。拖拽期间只播放悬空姿势，松手后完整落地。具体触发、频率和衔接规则见 动作说明。
若 WebUI 使用自定义地址，可在启动 Host 时设置 DSH_XMLANS_WEBUI_URL；它优先于自动推断的默认地址。
平台与运行环境
| 平台 | 原生角色 |
|---|---|
| Windows 10 / 11 x64 | 随包提供 Helper；WSL2 可通过 Windows 互操作启动 |
| Linux x64 | 随包提供 Qt Helper，需要图形桌面；glibc 2.35+，Ubuntu 24.04 有验收记录 |
| macOS 12+ | 原生 Swift / AppKit Helper，Universal 构建；实验性支持 |
标准安装包已包含 Helper，不需要自己安装 Python 或运行 Helper。从源码使用时需自行构建。macOS 小字号与拖动边缘已修复并通过 CI，仍需真实机器验证视觉效果与多屏操作。
原生角色显示在 Host 所在的桌面：远程服务器、无图形环境和浏览器客户端不在同一台机器时，请先确认 Host 的运行位置。页面内角色可在浏览器中显示。
更新与排错
WebUI 用户完全退出 DSH 后执行：
npx -y @deepseek-ai/dsh plugin --profile web update dsh-xmlans
官方桌面端 0.2.0-rc.2 暂不支持应用内自动更新。在插件页面卸载兰酱，再添加 dsh-xmlans@0.1.0 并立即启用；也可以完全退出应用后使用自带的命令：
dsh plugin --profile desktop update dsh-xmlans
然后重新启动对应客户端。回退、移除、DSH 迁移后恢复大小，以及 Windows EPERM 的处理见 更新与回退。
- DSH 0.2 设置页变化：安装当前版本，通过左侧插件 → dsh-xmlans 打开设置；较旧 Host 保留原设置入口。
- 桌面端安装只显示
[exit 1]：该信息不足以确定原因，请附上插件安装详细日志（如hub.log）、DSH 版本、系统和安装方式。 - 余额查询失败：检查 DSH 中的凭据及所用网关是否支持余额接口。
- 角色不出现：检查 profile、插件是否启用，以及 Host 是否有可用图形桌面。
源码开发
pnpm install --frozen-lockfile
npm test
npm run test:python
npm run build:helper
npm run test:helper:packaged
开发 Python Helper 需要 requirements.txt 中的依赖；macOS Helper 需要 Xcode Command Line Tools。纯 Swift 核心测试运行 swift test。修改原生代码后应重新构建 Helper，再安装本地打包产物。
CI 还会隔离安装 DSH 0.2.0-rc.2 并运行 scripts/test-dsh-settings.mjs，验证新设置接口。该检查不读取用户 profile 或凭据，文件写入使用测试适配器。
维护者打包与发布步骤见 发布说明。
重新生成角色帧
角色帧由 tools/render 离线渲染，不随 npm 包发布：
cd tools/render
npm install
npx playwright install chromium
node render.mjs # 全部片段，并重写 assets/pet-manifest.json
node render.mjs idle poke # 只重渲染指定片段，不改清单
动作时间轴在 tools/render/clips.mjs。循环片段长 8 秒，周期运动量化到整周期，首尾无缝。