前言¶
用 DeepSeek Harness（DSH）跑 Agent 时，任务往往分布在编辑器、终端和浏览器里，会话里的「思考、查找、修改、执行」等阶段并不总是显眼。若你希望在写代码或看 WebUI 的同时，用一块始终置顶的小窗口感知当前会话进度，而不是反复切回 DSH 页面，社区插件 dsh-xmlans 提供的是一条可选路径：由 DSH 插件拉起原生桌宠「兰酱」，把会话事件映射成角色动作与状态气泡。下面介绍它是什么、能做什么，以及如何在 WebUI 与官方桌面端安装与配置。
这是什么¶
dsh-xmlans（包名 dsh-xmlans，当前版本 0.1.0）由维护者 xmlans 发布，归类为趣味换装类 DSH 插件。简介为：让兰酱住进你的电脑里和你一起 Coding 的 DeepSeek Harness 插件。
插件随 DSH Host 启动，随 DSH 一起退出。角色通过透明、无边框、始终置顶的原生窗口展示；动作帧为离线渲染（竖版 256×352，24 fps），角色设定为白发、带天使翅膀的女仆兰酱。状态数据来自 DSH 会话事件；兰酱不读取屏幕，推理强度与进度仅显示上游实际提供的信息。
核心功能¶
任务与进度展示¶
- 显示与会话一致的任务状态：思考、查找、修改、执行、验证、等待确认、完成和错误。
- 展示项目、步骤、多任务及 DSH 提供的待办进度；无真实进度时显示阶段。
- 可选让子 Agent 状态参与显示（设置项「子 Agent」）。
DeepSeek 余额¶
余额默认出现在兰酱状态气泡底部和设置页，查询逻辑由 WebUI 与官方桌面端共用：
- 自动（默认）：优先使用 DSH 模型设置中的 DeepSeek API Key；未配置时尝试已登录账户。
- 也可在设置中指定来源为 API Key 或已登录账户；API 与账户余额会标明来源，CNY / USD 分别显示。
- 每分钟自动刷新，同一 Host 内共享缓存；手动刷新最快每 5 秒一次。
- 未配置凭据时仍可正常显示任务状态；可关闭「显示 DeepSeek 余额」。插件不会发起模型调用。
凭据在 DSH 模型／账户设置 中配置，兰酱设置页无需再填 API Key。
交互与显示选项¶
- 支持拖动、摸头、戳一下、碰翅膀；完成／出错时可播放提示音。
- 可独立调整角色大小、气泡大小；安静／标准／活泼三档控制待机动作间隔（约 45～90 / 25～45 / 12～22 秒）。
- 「减少动态」可固定姿势并停止待机与点击动画，状态与提示仍实时更新。
- 气泡可设为常驻、隐藏或仅在指定状态显示。
- 可选在 DSH 页面右下角显示轻量角色（默认关闭）。
- 「打开目标」可自动、指向 WebUI 或通过
dsh://open唤起官方桌面端。
客户端与 profile¶
| 使用方式 | 安装位置 | 设置入口（DSH 0.2） | 角色右键菜单的打开目标 |
|---|---|---|---|
| 浏览器 WebUI | web profile |
左侧插件 → dsh-xmlans | WebUI，默认 http://127.0.0.1:3080/ |
| 官方桌面端 | desktop profile |
左侧插件 → dsh-xmlans | 通过 dsh://open 唤起桌面应用 |
WebUI 中安装的插件不会自动出现在桌面端；两边都启用会各自启动原生角色，可在其中一个 profile 关闭「启用兰酱」。官方 Electron 桌面端与 Web 客户端共用同一套 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，调整角色、气泡和余额设置，修改实时生效。
使用命令安装时，需先启动一次桌面应用以初始化 desktop profile 后完全退出，并使用桌面应用自带的 dsh 命令（独立安装的 npm / npx @deepseek-ai/dsh CLI 不能修改官方桌面端的 profile）：
dsh plugin --profile desktop add dsh-xmlans@0.1.0
离线安装¶
使用发布包 dsh-xmlans-0.1.0.tgz（Windows、Linux、macOS 共用），无需解压：
# 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 的完整路径。标准安装包已包含各平台 Helper，不需要自行安装 Python 或单独运行 Helper。
典型用法与设置¶
安装并启用后，兰酱会随当前 profile 的 DSH Host 出现在 Host 所在机器的图形桌面上。在 DSH 0.2 中，通过左侧 插件 → dsh-xmlans 打开设置页；修改角色大小、气泡、余额来源、页面内角色等项会实时生效。右键菜单可快速调整大小、减少动态、打开对应 DSH 客户端，或仅在本次运行隐藏／关闭角色。
若 WebUI 使用自定义地址，可在启动 Host 时设置环境变量 DSH_XMLANS_WEBUI_URL，其优先于自动推断的默认地址。
WebUI 用户更新插件（完全退出 DSH 后）：
npx -y @deepseek-ai/dsh plugin --profile web update dsh-xmlans
官方桌面端可使用应用自带 dsh：
dsh plugin --profile desktop update dsh-xmlans
（官方桌面端 0.2.0-rc.2 暂不支持应用内自动更新时，可按 README 卸载后重新添加 dsh-xmlans@0.1.0。）
适用场景与注意¶
适合谁： 已在使用 DSH WebUI 或官方桌面端、希望在本地桌面直观看到 Agent 会话状态（及可选 DeepSeek 余额）的开发者。分类上属于趣味换装，侧重陪伴与状态可视化，而非替代 DSH 本身的调试面板。
运行环境与权限：
- Windows 10 / 11 x64、Linux x64（需图形桌面，glibc 2.35+）、macOS 12+（实验性）均随包提供原生 Helper。
- 原生角色显示在 Host 所在的桌面；远程无图形环境、或浏览器与 Host 不在同一台机器时，需先确认 Host 运行位置；页面内角色可在浏览器中显示。
- 插件以当前 DSH 进程权限运行；安装前请阅读 https://github.com/xmlans/dsh-xmlans 源码与 LICENSE，自行评估是否纳入工作流。
排错提示（来自 README）： 角色不出现时检查 profile、插件是否启用及 Host 是否有可用图形桌面；余额查询失败时检查 DSH 凭据及网关是否支持 /user/balance；桌面端安装仅显示 [exit 1] 时需查看安装详细日志（如 hub.log）并附带 DSH 版本与系统信息。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。本插件在 GitHub 上当前约 2 stars，版本与安装包名以 README 为准（dsh-xmlans@0.1.0 / dsh-xmlans-0.1.0.tgz）。
结尾¶
dsh-xmlans 把 DSH 会话事件接到桌面原生窗格，用兰酱的动作与气泡反映真实任务阶段，并可选展示 DeepSeek 余额与页面内轻量角色。若你需要在 Coding 时保持对 Agent 进度的感知，可按上述 profile 安装 dsh-xmlans@0.1.0 并在插件设置中按需开关。
