前言¶
在 DSH 的 web GUI 裏，部分常用操作原本需要反覆用鼠標點擊：聚焦輸入框、新建會話、切換側欄、切換詳情面板、滾動對話、切換主題等。@blue-a11y/dsh-client-shortcuts 把這些瀏覽器內的 UI 動作註冊成全局鍵盤快捷鍵，並提供一個設置頁用於查看、錄製、重置和校驗組合鍵。
下面介紹它的定位、核心功能、安裝方式、典型用法、開發構建和注意事項。
這是什麼¶
@blue-a11y/dsh-client-shortcuts 是 blue-a11y 維護的 DeepSeek Harness web GUI 插件，許可證爲 MIT。它是一個瀏覽器端 UI 插件，node half 刻意爲空，整個功能都運行在瀏覽器側。
它提供 ShortcutRegistry 服務，也就是 ctx.shortcuts。這個服務會在 window 上掛一個捕獲階段的 keydown 監聽，並分發已註冊的組合鍵。
它同時提供設置頁：
- 註冊於
settings.section； - 基於
@deepseek-ai/dsh-client-ui-primitives構建； - 列出全部可綁定動作；
- 支持錄製組合鍵、重置改鍵、衝突檢測和保留組合鍵攔截。
該包聲明瞭 dsh.bundle，屬於組合包。package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml，安裝後會激活其配置層。
這個插件只把瀏覽器鍵盤手勢轉發爲 UI 動作，不觸及任何模型請求。
核心功能¶
全局快捷鍵註冊¶
核心服務是 ShortcutRegistry，即 ctx.shortcuts。它負責：
- 在
window上監聽捕獲階段keydown； - 解析和匹配已註冊組合鍵；
- 分發到對應 UI 動作；
- 提供綁定註銷能力。
mod 在 macOS 上匹配 Cmd，在其他平臺匹配 Ctrl。文檔和 UI 以 cmd 友好形式書寫組合鍵，例如 cmd 與 mod 在組合鍵表達中按約定對應處理。
文本輸入框保護¶
默認情況下，焦點在文本輸入框內時會放行鍵盤事件，避免影響正常輸入。
如果某個綁定顯式聲明輸入框內可用，它纔會在輸入框內響應。
可綁定動作¶
插件列出全部可綁定動作，包括：
- 聚焦輸入框；
- 新建會話；
- 切換側欄；
- 切換詳情面板；
- 上一個會話；
- 下一個會話；
- 切換淺色/深色主題；
- 滾動到對話頂部；
- 滾動到對話底部；
- 分叉當前會話。
其中，沒有安全默認值的動作默認不綁定。用戶可以在設置頁錄製組合鍵啓用，也可以重置回未綁定狀態。
會話切換順序¶
會話切換鏡像側欄的完整顯示順序，會跳過「新建任務」空白條目和歸檔會話，並在兩端循環。也就是說，最後一個會話繼續切換時會回到第一個可用會話，第一個會話反向切換時會回到最後一個可用會話。
改鍵與衝突檢測¶
設置頁支持：
- 錄製新的組合鍵；
- 重置爲未綁定；
- 校驗與現有綁定是否衝突；
- 拒絕瀏覽器保留組合鍵；
- 拒絕 macOS 的
Option/Alt改寫組合。
瀏覽器保留組合鍵會在頁面監聽器執行 preventDefault 之前被瀏覽器消費，web 插件無法綁定。macOS 的 Option/Alt 改寫組合可能導致 event.key 與註冊鍵不再匹配，因此設置頁會拒絕這類組合。
改鍵生命週期¶
改鍵僅在插件 fiber 生命週期內有效。刷新頁面後會恢復默認狀態，當前不會持久化保存用戶改鍵結果。
安裝與啓用¶
前置條件¶
先安裝 dsh CLI：
npm i -g @deepseek-ai/dsh
然後確保運行環境滿足：
- Node 22.19 或更高版本；
pnpm可用。
從 npm 安裝¶
推薦從 npm 安裝：
dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts
該包是組合包，安裝後會激活其配置層。
本地 checkout 安裝¶
開發期可以安裝本地目錄：
dsh plugin --profile web add ./dsh-client-shortcuts
打包產物安裝¶
如果有打包產物，也可以使用 tarball：
dsh plugin --profile web add ./dsh-client-shortcuts-0.1.0.tgz
重啓與驗證¶
新增插件行後，需要重啓一次 dsh web，因爲插件行發現在每次啓動時緩存。
先查看配置：
dsh --profile web --dump-config
配置中應能看到 id: shortcuts 行。
然後啓動 web GUI：
dsh web
瀏覽器打開後，進入「設置 → 快捷鍵」，應能看到快捷鍵設置頁。
更新與卸載¶
更新時重新執行安裝命令：
dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts
如果需要鎖定版本，需指定版本號。
卸載命令：
dsh plugin --profile web remove @blue-a11y/dsh-client-shortcuts
卸載會同時移除相關依賴與配置層。
pnpm 構建授權¶
如果使用 pnpm 10 或更高版本，可能需要在 pnpm-workspace.yaml 的 allowBuilds 中一次性授權 profile。
典型用法¶
打開設置頁¶
啓動 dsh web 後，在瀏覽器中進入：
設置 → 快捷鍵
設置頁會列出全部可綁定動作，並展示當前組合鍵與觸發計數。
錄製組合鍵¶
對於默認未綁定的動作，可以在設置頁使用錄製控件按下想要綁定的組合鍵。
錄製控件會暫停註冊中心分發，按下的組合鍵會被捕獲而不是直接觸發。設置頁會校驗該組合鍵是否與現有綁定衝突，並拒絕非法或保留組合鍵。
重置組合鍵¶
如果某個動作不再需要自定義鍵位，可以重置，使其清回未綁定狀態。
會話切換¶
綁定會話切換動作後，快捷鍵會按側欄的完整顯示順序移動，跳過「新建任務」空白條目和歸檔會話，並在首尾之間循環。
不觸及模型請求¶
這些快捷鍵只用於瀏覽器內的 UI 操作。插件不會發起模型請求，也不會改變模型調用路徑。
開發與構建¶
克隆倉庫¶
git clone https://github.com/blue-a11y/dsh-client-shortcuts.git
cd dsh-client-shortcuts
pnpm install
常用命令¶
pnpm install
pnpm run build
pnpm test
pnpm run build 會生成構建產物，pnpm test 會運行測試。
本地熱更新¶
本地開發時，可以先安裝本地目錄：
dsh plugin --profile web add ./dsh-client-shortcuts
修改源碼並重新構建後，client HMR 鏈路可以自動換新模塊。只有新增或刪除插件行時，才需要重啓 dsh web。
依賴關係¶
該包的 peer dependencies 包含：
@deepseek-ai/cordis ^4.0.1
@deepseek-ai/dsh-invariants ^0.1.0-rc.6
適用場景與注意¶
適合誰使用¶
適合使用 dsh web 並希望減少鼠標操作的開發者，尤其是：
- 需要頻繁聚焦輸入框；
- 需要快速新建會話；
- 需要頻繁切換側欄或詳情面板；
- 需要在多個會話之間快速移動；
- 需要快速滾動到對話頂部或底部；
- 需要對瀏覽器 UI 動作做輕量自定義。
它適合放在 DSH 的插件化工作流中，作爲 web GUI 的鍵盤增強插件使用。這裏介紹的插件來自獨立社區目錄，不是 DeepSeek 或幻方官方應用商店。
安全注意¶
該插件會加入當前 dsh 的 web profile 配置層，並隨當前 dsh 進程加載運行。安裝前應檢查源碼、許可證和依賴關係。
該插件許可證爲 MIT。它只處理瀏覽器鍵盤事件和 UI 動作，不觸及模型請求，但任何第三方插件都應在使用前確認其來源和構建產物。
行爲邊界¶
需要注意以下邊界：
- 改鍵不會持久化，刷新頁面後恢復默認；
- 焦點在輸入框內時默認放行，除非綁定聲明輸入框內可用；
- 瀏覽器保留組合鍵無法被 web 插件綁定；
- macOS 的
Option/Alt改寫組合會被設置頁拒絕； - 聚焦輸入框依賴
[data-phase]DOM 查詢，因爲當前沒有 composer 暴露聚焦服務； - 新增插件行後需要重啓一次
dsh web。
結尾¶
@blue-a11y/dsh-client-shortcuts 的價值比較集中：它爲 dsh web 提供一組可綁定的 UI 快捷鍵，並提供可錄製、可重置、可校驗的設置頁。它不改變模型請求鏈路，只優化瀏覽器內的操作路徑。
倉庫地址：
https://github.com/blue-a11y/dsh-client-shortcuts
