dsh-ambient-ui
Ambient UI components for DeepSeek Harness (DSH) Web — 为 DSH 界面添加毛玻璃余额悬浮窗与 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 配置行
- 重启
dsh web
- 检查终端输出中是否有
[dsh-ambient-ui] 相关日志
- 配置行依赖 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）。
