yunmin311/dsh-universal-palette

dsh-universal-palette

npm version
GitHub release
license
DSH
node
CI

面向 DeepSeek Harness Web 的命令、会话、模型与历史统一面板：一次按键，当前工作区的一切触手可及。

活动会话中的完整全局悬浮面板

为什么需要 Universal Palette

DSH 的能力通过插件不断增长：官方与社区插件持续添加 Host 命令、客户端命令 UI、模型与引用源。这些能力的原生入口散落在不同位置——斜杠菜单、模型选择器、侧栏、输入框 @ 菜单——没有一个地方能回答键盘用户真正关心的问题：当前工作区里我现在能用什么，怎么到达？

Universal Palette 为同一个搜索控制器提供两种呈现：有上下文的 Composer Search，以及面向全局导航的悬浮面板。它不维护第二套目录：每一条命令、会话、模型和历史命中都在查询时来自 DSH 的公开 Client API，因此 DSH 与社区生态变化时，Palette 无需任何修改即自动保持正确。

它刻意保持克制：DSH 官方设计令牌、原生界面之上的玻璃质感、跟随界面语言的文案，以及对一切没有经过验证公开 contract 的东西零行为影响。

功能

- 命令 — 完整的实时 Host 命令目录，全部经官方 API 搜索与执行；DSH 或任何插件新增的 Host 命令零适配自动出现。
- 模型 — 会话的真实模型目录与当前选择，经公开选择契约提交。
- 会话 — Current 优先的会话导航，稳定 Session ID 去重，不做按标题合并。
- 历史命中 — 经 DSH 自带的会话全文搜索，展示片段与元数据。
- 确定性相关性 — 精确前缀优先打分加最低相关性门槛；最近使用与上下文只影响真实相关结果的排序。
- 原生外观与语言 — DSH 设计令牌、官方菜单排版与层级、玻璃表面、跟随 DSH 语言的中英文案。
- 公开契约互操作 — 与社区插件按能力检测协作；不读私有 registry、无硬依赖。

快速开始

dsh plugin --profile web add @yunmin311/dsh-universal-palette@0.2.1
dsh --profile web

Composer Search

- 从 DSH 原生 slash 菜单输入 /find，或点击 Search 按钮。裸 / 仍完全由 DSH 接管。
- Composer 始终是唯一查询输入框。/find query 保留在 Composer 中；Search 按钮则直接从当前 draft 打开同一个搜索，不插入 /find。
- 活动会话中，结果以紧凑的 DSH 原生样式呈现在 Composer 上方。
- 零轮次 Hero 会话中，结果以同样的 DSH 原生样式直接呈现在 Composer 下方：常规文档流，约 5 行可见加内部滚动，绝不遮挡 Composer。这要求宿主声明 conversation.hero.composer.dock 席位——在不提供该席位的宿主（包括官方 0.1.2-rc.1）上，Hero 页面的 Composer Search 直接 fail closed，绝不向上回退；见兼容性。
- Hero 与活动会话两种呈现共享同一个控制器、同一组 provider、同一套排序与结果执行。

全局搜索

- Windows/Linux 按 Alt+Q，macOS 按 Cmd+Shift+K。
- 打开悬浮面板：零轮次使用紧凑版，活动会话使用完整的 600px 版本。

已有用户的自定义快捷键不会被覆盖。Esc 关闭面板；点击悬浮面板外部会关闭并把点击穿透给 DSH。

使用

| 操作 | 效果 |
|---|---|
| / | 使用 DSH 原生 slash 菜单 |
| Search 按钮或 /find | 从 Composer 打开 Composer Search：零轮次 Hero 会话向下展开 Morph，活动会话向上展开 Morph |
| Alt+Q（Windows/Linux）或 Cmd+Shift+K（macOS） | 开关全局悬浮面板 |
| 输入 | 模糊搜索命令、模型、会话与历史 |
| ↑↓ | 移动选择 |
| Enter | 打开 / 执行选中行 |
| Tab | 操作面板（基础设施；当前内置 provider 仅提供主操作） |
| Esc | 关闭 |

两种搜索模式

Composer Search — 上下文 / 嵌入式

活动会话中，Composer 始终是唯一查询输入框，搜索结果以紧凑的 DSH 原生样式直接出现在其上方。零轮次 Hero 会话中，同一个 Search 按钮或 /find 入口以常规文档流在 Composer 下方打开同一个结果面。

零轮次 Hero 会话中向下展开的 Composer Search

活动会话中向上展开的 Composer Search

全局悬浮面板 — 全局 / 导航式

全局快捷键始终打开悬浮面板。零轮次使用紧凑的 540px 呈现；活动会话使用本页顶部所示的完整 600px 呈现。

搜索 goal 命令

带片段与元数据的历史命中

搜索面

| 搜索面 | 来源契约 | 动作 | 需要活动会话 |
|---|---|---|---|
| 命令 | ctx.remote.commands.list / execute（官方 Host 目录） | 执行 | 是 |
| 模型 | ctx.modelDirectories（官方模型目录） | 选择 | 是 |
| 会话 | ctx.sessions（官方会话控制器） | 打开 | 否 |
| 历史命中 | ctx.sessions.search（官方 FTS 边界） | 打开 | 否 |

社区互操作

互操作均对真实安装的插件验证——详见互操作矩阵。

- Host 命令联邦：自动。 社区插件的 Host 命令（如 dsh-tui-command-ext 的 /clear /rename /unarchive /compact-fast，或 /code-review 类插件）零适配出现并执行——Palette 读取实时官方目录。

精确查询发现第三方 Host 命令

- dsh-keys-palette：可选公开桥接。 在其公开的 keys.actions registry 注册一个 universal-palette.open action，可为"打开面板"绑定快捷键。插件不存在时零影响。
- 已验证共存： dsh-tui-command-ext、dsh-session-workbench、dsh-reference-anything、dsh-keys-palette、dsh-market——均已在真实 DSH 启动中同时安装验证。
- 无私有耦合。 Session Workbench 与 Reference Anything 目前没有公开 handoff API；Palette 不做超出共存范围的集成，并把 upstream gap 记录在案而不是绕过。

这不是"支持所有插件"——只消费上述契约，全部能力检测，插件不存在时零行为变化。

给插件作者

Universal Palette 联合的是 DSH 的公开契约——想出现在面板里，不需要和 Palette 集成。

- Host 命令：通过 DSH 官方 Host 命令契约（ctx.commands.register）注册即可，Palette 每次查询都会从实时目录自动发现你。无需依赖 Palette、无需 adapter、无需协调发版。
- 更深的互操作：只有当你的插件暴露稳定公开 Cordis service 时，才会考虑做可选的、按能力检测的 adapter；插件未安装时必须零影响、卸载时生命周期正确。现行正例是 dsh-keys-palette 的公开 keys.actions registry——Palette 借它贡献了一个可绑定快捷键的"打开面板"action。
- Client-only commandUi 命令、私有 registry、DOM 状态、内部路由均不接入——这些场景保持共存关系，等待公开 API（upstream gaps）。
- 会话 / 引用 / 工作区类插件同理：公开 handoff service 或官方契约是进入 Palette 二级集成的唯一路径；没有公开 seam 即 WAIT_PUBLIC_API。

Universal Palette 目前没有 Provider SDK，也没有相关计划。推荐的生态路径是：向 DSH 注册，Palette 联合公开契约。细节与已验证案例见互操作矩阵。

兼容性

已验证：
- @deepseek-ai/dsh@0.1.2-rc.1（baseline，deepseek-ai/deepseek-harness@76fda729799fe9b3848dbe2c211d4b231032b81e）
- @deepseek-ai/dsh@0.1.5-rc.1（API drift 已验证；仅兼容 seam）

其他 DSH 版本未验证。详见 COMPATIBILITY.md 与 COMMAND_COMPATIBILITY.md。

0.1.5-rc.1 API drift（不影响 Universal Palette）

Palette 仅消费以下公开 Client seam；这些在 0.1.2-rc.1 与 0.1.5-rc.1 之间兼容：

- ctx.remote.commands.list — 形状不变
- ctx.sessions.list / binding / search / open — 形状不变
- ctx.workspaces.list / create — 不变
- ctx.modelDirectories.directoryFor / load / select — 不变
- ctx.inputTriggers.registerSource / sessionOf / adjudicate — envelope 字段 images→attachments 重命名（Palette 不提交 images）
- ctx.slots.spec / subscribe / inject / register — shell.overlay、conversation.input.left、conversation.input.overlay、conversation.hero.composer.dock、conversation.composer.dock、sidebar.footer.action 名称不变
- locale、plugin lifecycle — 不变

0.1.5 的破坏性变更（如 commands.execute 第 3 参数 images→attachments、session 格式 V3、wire seedLength→isSeeded、history events 重组）均不与 Palette 调用面相交。

Hero 页面

- Stock 0.1.2-rc.1 / 0.1.5-rc.1：无 conversation.hero.composer.dock → Composer Search 直接 fail closed（Search 按钮禁用并给出原因；/find 被 claim 但返回 capability 错误；绝不向上回退）。
- 增强 Hero 体验（向下 Morph）要求宿主声明 conversation.hero.composer.dock。已完整验证的宿主是维护者自己的增强 fork（yunmin311/deepseek-harness，分支 feat/hero-composer-dock，SHA 321bf88d10e0176674226d02de59d3e0bd79579d）。这不是 upstream 支持；该 fork 将作为完整 Hero 体验的长期增强宿主维护。

Desktop

- 当前无官方 DeepSeek Desktop 安装包发布。上游仓库包含 Desktop 打包基础设施（apps/desktop Electron shell + apps/desktop-host），但 https://download.deepseek.com/_/harness/desktop/stable/... 无安装包（审查时 404）。
- 社区封装（Electron/Tauri/Wails shell 打包 stock dsh web）存在但不在 verified matrix。
- deepseekagent.io / 第三方站点非官方 DeepSeek 产品。

隐私与安全

- 无遥测、无统计埋点。
- 不发起任何自己的网络请求：一切经由 DSH 进程内的公开 Client API。
- 不读取、不存储任何凭据；验收 profile 本身即无凭据运行。
- 用户偏好（快捷键、使用频率）保存在浏览器 localStorage 中本插件自己的命名空间下。
- 历史搜索委托 DSH 的会话 FTS；其数据库属于 DSH profile，不属于本插件。

测试

- pnpm run check — 类型检查 + 单元测试（含 Keys Palette 桥接生命周期）。
- pnpm run build — Host ESM 面 + 带 purity gate 的浏览器 CJS bundle。
- Windows 真机验收：官方命令兼容性 gate（scripts/command-compat.mjs）、多插件共存探针（scripts/interop-probe.mjs），证据见 evidence/。

已知限制

- 锁定 DSH 0.1.2-rc.1；其他版本未验证。
- Client-only commandUi 命令（如弹出式选择器）不可发现——DSH 尚无公开枚举接口（upstream gaps）。

开发

pnpm install
pnpm run check
pnpm run build

文档

- 架构
- 兼容性
- 命令兼容性
- 设计合同
- 互操作矩阵
- Upstream 接口缺口
- 变更日志

许可证

MIT