dsh-ambient-ui

Ambient UI components for DeepSeek Harness (DSH) Web — 为 DSH 界面添加毛玻璃余额悬浮窗与 Agent 轨迹像素动画。

| 毛玻璃余额悬浮窗 | Agent 轨迹像素动画 | | ------------------------------------------------ | ----------------------------------------------- | | |

功能一览

| 功能 | 位置 | 说明 | | ------------------ | -------------------------------- | ------------------------------------------------------------ | | API 余额悬浮窗 | 输入框右侧工具条（与输入框持平） | 毛玻璃卡片，实时显示账户余额 + 当前会话 token 用量 | | Agent 轨迹像素动画 | 输入框上方（30×8 点阵条） | 将 Agent 执行步骤映射为流动像素：think → #00ff88、tool → #ff8800、output → #4488ff |

两个功能均为纯 CSS 实现（CSS Modules），跟随 DSH 明暗主题（通过 --dsw-alias-* token），无额外运行时依赖（仅需官方 Harness 包 + React）。

插件 ID：dsh-ambient-ui · 当前版本：1.1.0（已适配 DSH 0.1.2-rc.1；npm 上 ≥1.1.0 才能用于 0.1.2-rc.1 运行时）

环境要求

• DSH 0.1.2-rc.1（0.1.2-rc.1 起 DSH 将 settings 注册从顶层 installSettingsSection / settingsNamespace 迁移为 ctx.settings 服务 API，旧版插件需按本次适配更新； @deepseek-ai/dsh-client-runtime 已在 rc.1 停产，client 类型统一走 @deepseek-ai/dsh-client-ui-* 与 @deepseek-ai/dsh-client-ui-slots）
• Node.js ≥ 22.19
• 余额提供方 API Key（默认读取 DEEPSEEK_API_KEY；可通过插件配置 baseUrl / apiKeyEnv 接入兼容端点）

安装

根据你的使用场景选择一种方式：

从 npm 安装（推荐）

# Web 端
dsh plugin --profile web add dsh-ambient-ui

# 桌面端
dsh plugin --profile desktop add dsh-ambient-ui

从 Git 安装（获取最新开发版）

dsh plugin --profile web add https://github.com/Q04291/dsh-ambient-ui

从本地目录安装（开发调试）

pnpm install
pnpm run build
dsh plugin --profile web add link:<绝对路径>/dsh-ambient-ui

安装完成后，重启 dsh web（或刷新页面），进入 设置 → 插件 确认 dsh-ambient-ui 已启用。

配置

进入 设置（⚙️）→ General → Ambient UI，所有改动即时生效：

| 字段 | 类型 | 范围 | 默认值 | 说明 | | ----------- | ---- | --------- | ------ | ---------------------------------------------------- | | opacity | 滑块 | 0.3 – 1.0 | 0.85 | 悬浮窗整体透明度 | | blur | 滑块 | 0 – 30 px | 12 | 毛玻璃模糊强度 | | speed | 滑块 | 1 – 10 | 5 | 像素轨迹滚动速度 | | showBalance | 开关 | — | on | 是否显示余额悬浮窗 | | showTrail | 开关 | — | on | 是否显示像素轨迹 | | glass | 开关 | — | on | 全局弹窗毛玻璃效果（设置面板 / Modal / 菜单 / 提示） |

常见问题

余额显示"不可用"

• 未配置 API Key：默认读取 DEEPSEEK_API_KEY，配置后悬浮窗会自动恢复显示。
• 使用了 OpenAI、Moonshot/Kimi 等提供方：其原生余额接口与 DeepSeek 格式不同，无法直接查询，属正常现象；token 用量与像素轨迹动画不受影响。
• 若你的网关/中转站提供 DeepSeek 兼容的 /user/balance 接口，可通过插件配置 baseUrl / apiKeyEnv 接入。

Token 显示"不可用"

当前 profile 中未包含 token-meter 服务。该功能不影响余额显示。

设置面板中看不到 Ambient UI 配置行

1. 重启 dsh web
2. 检查终端输出中是否有 [dsh-ambient-ui] 相关日志
3. 配置行依赖 Host 侧注册的 ambient 命名空间经 DSH 设置通道下发；若 profile 未挂载 @deepseek-ai/dsh-settings-file（通常由 dsh-base 自动挂载），命名空间不会被下发， 行会回退到默认值且编辑不生效。

配置存在哪里 / 改动如何生效

• 配置通过 DSH 原生设置通道读写（ctx.settings 注册 + 浏览器 settingsScope）， 持久化到 ~/.dsh/settings.yaml 的 ambient: 段，改动即时生效，无需轮询。
• 若以非 loopback 方式远程访问 GUI，settingsScope 可能处于 memory 模式（改动仅本次会话内生效），属 DSH 设置传输的既定行为。

设置 → 插件 页可能列出 ambient 命名空间

所有 Host 注册的命名空间都会被设置控制器描述给浏览器。dsh-ambient-ui 的配置入口在 General → Ambient UI；若在 Plugins 页看到空的 ambient 项，属于 DSH 插件页对 “仅注册命名空间、无卡片插件”的展示，不影响本插件功能。

悬浮窗 / 像素轨迹的位置不对

• 余额悬浮窗停靠在输入框右侧工具条（conversation.input.right 插槽）
• 像素轨迹位于输入框上方（conversation.input.dock 插槽）

开发

pnpm install
pnpm run typecheck   # tsc -b
pnpm test            # vitest（tests/ 目录）
pnpm run build       # tsc -b && tsdown → 输出 lib/ 与 lib/client.js

项目结构

src/
├── index.ts                  # Host 侧：注册 ambient 设置命名空间 + /api/ambient/* 路由
├── config.ts                 # 共享配置类型、默认值与命名空间常量
├── service.ts                # 余额查询（credentials + Get User Balance）+ token-meter 读取
├── routes.ts                 # API 路由：/balance, /balance/refresh, /tokens
├── AmbientRow.tsx            # 设置面板中的 Ambient UI 配置行
├── BalanceWidget.tsx         # 毛玻璃余额 / 用量悬浮窗组件
├── TrailAnimation.tsx        # 30×8 像素轨迹动画组件
├── trailFeed.ts              # 轨迹数据映射的纯函数（可单测）
├── styles.module.css         # 纯 CSS 样式（CSS Modules，跟随主题）
└── client/
    ├── index.ts              # Client 侧：绑定 settingsScope + 注册三个插槽
    ├── ambientConfigStore.ts # 配置共享 store（由原生 settings scope 驱动，无轮询）
    ├── feed.ts               # rc.1 会话标准 props 的轻量类型声明
    ├── glass.ts              # 全局弹窗毛玻璃（mask token 覆盖）
    └── useAmbientConfig.ts   # 配置消费 Hook
tests/                        # vitest 测试（config / store / trailFeed / service / routes）
shared/                       # 官方 DSH client bundle 构建预设（MIT）
cordis.patch.yml              # bundle patch（dsh plugin 安装用）

License

MIT. shared/ 目录下的构建预设派生自 DeepSeek Harness 官方仓库（MIT）。