@hellokidder/dsh-hotkey 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.0.1
+
+- First release.
+- Hold Command (Control on Windows/Linux) to number the sidebar conversations.
+- `Command+N` / `Command+Shift+N` cycle through conversations.
+- `Command+1` through `Command+9` jump to a numbered conversation.
+- Capture-phase keyboard handling that keeps working while an editor or IME has focus.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kidder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# dsh-hotkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 快捷键的统一入口。当前版本提供侧边栏对话切换；后续快捷键能力都集成在这个插件里。
+
+npm：`@hellokidder/dsh-hotkey`
+
+## 已包含
+
+- **按住 Command**（Windows/Linux 为 Control）时，左侧每个对话行首显示 1…n 的序号；当前对话的序号使用品牌色高亮。
+- **Command + N** 切换到下一个对话，**Command + Shift + N** 切换到上一个，均循环。
+- **Command + 1…9** 直接跳转到对应序号的对话。
+- 序号顺序跟随侧边栏默认视图：按 Workspace 分组、置顶优先、组内按最近使用排序；归档会话、子代理会话和空的「新会话」行不参与编号。
+- 三个快捷键会出现在「设置 → 键盘快捷键」的只读分组中，便于查找。
+
+## 平台说明
+
+- 在桌面 App 中，Command 组合先经过原生层；插件把 `Command+N` 注册为固定快捷键，因此它会交给页面而不是「新建会话」。
+- 如果直接在 Chrome / Safari 里打开 Web GUI，`Command+N` 和 `Command+Shift+N` 会被浏览器占用（新建窗口 / 无痕窗口），页面收不到，请使用桌面 App。
+
+## 安装
+
+从 npm 安装：
+
+```sh
+dsh plugin --profile web add @hellokidder/dsh-hotkey
+```
+
+从本地目录安装（开发）：
+
+```sh
+dsh plugin --profile web add "link:/absolute/path/to/dsh-hotkey"
+```
+
+安装后在插件管理中启用，客户端会通过 HMR 加载；如果没有更新，刷新一次页面。
+
+## 显示细节
+
+- 编号占用每行标题左侧的 16px 座位；正在运行、等待审批或有未读完成状态的行会优先显示宿主的状态点，该行不显示编号。
+- 编号顺序与侧边栏默认视图一致：按 Workspace 分组、置顶优先、组内最新在前。折叠分组中的会话仍参与编号和切换。
+
+## 与「新建会话」的关系
+
+宿主给「新建会话」分配的默认快捷键也是 Command + N。本插件把 Command + N 注册为固定（不可编辑）快捷键，因此：
+
+- Command + N 现在用于切换对话；
+- 「新建会话」的 Command + N 会显示为冲突且不再触发，侧边栏的新建按钮和菜单仍然可用；
+- 如需保留「新建会话」的键盘入口，可在「设置 → 键盘快捷键」中给它换一个组合。
+
+卸载插件后，Command + N 自动回到「新建会话」。
+
+## 扩展新快捷键
+
+1. 在 `client.js` 的 `apply` 中用 `ctx.shortcuts.registerFixed({ id, label, keys, bindings, group })` 声明固定组合，用来占键并让快捷键面板可见；需要用户可改键时改用 `ctx.shortcuts.register`（与宿主已有默认组合冲突时 `register` 会抛错）。
+2. 在 `window` 的**捕获阶段**监听 `keydown` 并分发动作，不要依赖 `observeFixedInput` 的 bubble 监听：编辑器和输入法可能提前 `stopPropagation`，中文输入法还会把 Shift 标记为组合态。带 Command/Ctrl 的组合是命令，不应被 `isComposing` 拦截。
+3. 需要随快捷键状态显示 UI 时，沿用当前 `store` + `React.useSyncExternalStore` 的模式，通过槽位渲染。
+4. 同步更新 `locale/en.json`、`locale/zh.json` 的插件标题与描述，以及 `client.js` 中的 `en`/`zh` 命令标签。
+5. 保存后客户端 HMR 会自动重载；如未生效刷新页面即可。修改 `package.json` 或 patch 需要重新安装。
+
+## 开发
+
+```sh
+git clone https://github.com/hellokidder/dsh-hotkey.git
+cd dsh-hotkey
+node --check client.js
+```
+
+- `client.js` 是浏览器端模块（`window.__ModuleLoader__` 格式），不依赖构建工具。
+- 插件清单与入口见 `package.json`、`cordis.patch.yml`，宿主半边 `index.js` 目前为空。
+
+## 发布
+
+```sh
+npm publish --access public
+git tag v0.0.1 && git push origin v0.0.1
+```
+
+## License
+
+MIT

package/client.js

@@ -0,0 +1,310 @@
+window.__ModuleLoader__.load({
+  id: '@hellokidder/dsh-hotkey',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    const NS = 'dshHotkey'
+    const BADGE_CLASS = 'dsh-hotkey__number'
+    const BADGE_CURRENT_CLASS = 'dsh-hotkey__number--current'
+    const STYLE_ID = '@hellokidder/dsh-hotkey/badge.css'
+
+    const en = {
+      'command.next': 'Next conversation',
+      'command.previous': 'Previous conversation',
+      'command.jump': 'Go to conversation 1-9',
+    }
+    const zh = {
+      'command.next': '下一个对话',
+      'command.previous': '上一个对话',
+      'command.jump': '跳转到对话 1-9',
+    }
+
+    const CSS = `
+.${BADGE_CLASS} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  border: 0.5px solid var(--dsw-alias-border-l1);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  letter-spacing: -0.02em;
+  pointer-events: none;
+  user-select: none;
+}
+.${BADGE_CURRENT_CLASS} {
+  border-color: transparent;
+  background: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-bg-base);
+}
+`
+
+    function createStore(initial) {
+      let snapshot = initial
+      const listeners = new Set()
+      return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+          listeners.add(listener)
+          return () => {
+            listeners.delete(listener)
+          }
+        },
+        publish(patch) {
+          let changed = false
+          for (const key of Object.keys(patch)) {
+            if (!Object.is(snapshot[key], patch[key])) {
+              changed = true
+              break
+            }
+          }
+          if (!changed) return
+          snapshot = { ...snapshot, ...patch }
+          for (const listener of [...listeners]) listener()
+        },
+      }
+    }
+
+    /** Newest first, with the Session id as a deterministic tie-break. */
+    function orderByRecency(ids, byId) {
+      return ids
+        .map((id) => ({ id, rank: byId[id] === undefined ? 0 : byId[id].updatedAt }))
+        .sort((left, right) => (left.rank !== right.rank ? right.rank - left.rank : left.id < right.id ? -1 : 1))
+        .map((entry) => entry.id)
+    }
+
+    /**
+     * Reproduce the sidebar's default browsing order: Workspace groups in Host
+     * order, pinned rows before ordinary rows inside each group, then newest
+     * first. Only rows the sidebar can show are numbered: no archived Session,
+     * no subagent Session, and no blank New Session placeholder.
+     */
+    function deriveOrder(list, workspaceState) {
+      const byId = list.byId === undefined ? {} : list.byId
+      const state = workspaceState === undefined || workspaceState === null ? {} : workspaceState
+      const archived = new Set(state.archivedSessionIds === undefined ? [] : state.archivedSessionIds)
+      const pinned = new Set(state.pinnedSessionIds === undefined ? [] : state.pinnedSessionIds)
+      const workspaces = Array.isArray(state.items) ? state.items : []
+      const ids = Array.isArray(list.ids) ? list.ids : []
+      const ordered = []
+      const indexById = {}
+      const accounted = new Set()
+
+      const visible = (session) => session !== undefined
+        && session.origin !== 'subagent'
+        && session.blank !== true
+        && !archived.has(session.id)
+
+      const pushSection = (memberIds) => {
+        const recency = orderByRecency(memberIds, byId)
+        const section = [
+          ...recency.filter((id) => pinned.has(id)),
+          ...recency.filter((id) => !pinned.has(id)),
+        ]
+        for (const id of section) {
+          if (Object.hasOwn(indexById, id)) continue
+          indexById[id] = ordered.length + 1
+          ordered.push(id)
+        }
+      }
+
+      for (const workspace of workspaces) {
+        const memberIds = Array.isArray(workspace.sessionIds) ? workspace.sessionIds : []
+        const visibleIds = []
+        for (const id of memberIds) {
+          accounted.add(id)
+          if (visible(byId[id])) visibleIds.push(id)
+        }
+        pushSection(visibleIds)
+      }
+
+      pushSection(ids.filter((id) => !accounted.has(id) && visible(byId[id])))
+
+      let currentId
+      for (const id of ids) {
+        const session = byId[id]
+        if (session !== undefined && (session.retainedBy === undefined ? 0 : session.retainedBy.mainView ?? 0) > 0) {
+          currentId = id
+          break
+        }
+      }
+
+      return { ordered, indexById, currentId }
+    }
+
+    return {
+      inject: ['slots', 'locale', 'shortcuts', 'sessions', 'workspaces', 'uiWorkspace'],
+      apply(ctx) {
+        ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-hotkey: dictionaries')
+        const t = ctx.locale.bind(NS)
+
+        const initial = deriveOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot())
+        const store = createStore({ held: false, ...initial })
+
+        function SwitcherBadge({ sessionId }) {
+          const snapshot = React.useSyncExternalStore(store.subscribe, store.getSnapshot)
+          const number = snapshot.held ? snapshot.indexById[sessionId] : 0
+          if (!number) return null
+          return h('span', {
+            className: snapshot.currentId === sessionId
+              ? `${BADGE_CLASS} ${BADGE_CURRENT_CLASS}`
+              : BADGE_CLASS,
+            'aria-hidden': 'true',
+          }, String(number))
+        }
+
+        const platform = String(
+          (navigator.userAgentData === undefined ? undefined : navigator.userAgentData.platform)
+          ?? navigator.platform
+          ?? '',
+        ).toLowerCase()
+        const isMac = platform.includes('mac') || platform.includes('iphone') || platform.includes('ipad')
+
+        ctx.effect(() => {
+          const style = document.createElement('style')
+          style.setAttribute('data-plugin-css', STYLE_ID)
+          style.textContent = CSS
+          document.head.appendChild(style)
+          return () => {
+            style.remove()
+          }
+        }, 'dsh-hotkey: badge styles')
+
+        ctx.effect(() => {
+          const rebuild = () => {
+            store.publish(deriveOrder(ctx.sessions.list.getSnapshot(), ctx.workspaces.list.getSnapshot()))
+          }
+          const offSessions = ctx.sessions.list.subscribe(rebuild)
+          const offWorkspaces = ctx.workspaces.list.subscribe(rebuild)
+          rebuild()
+          return () => {
+            offSessions()
+            offWorkspaces()
+          }
+        }, 'dsh-hotkey: switch order')
+
+        // Numbers follow the physical primary modifier: Command on macOS, Control elsewhere.
+        ctx.effect(() => {
+          const sync = (event) => store.publish({ held: isMac ? event.metaKey : event.ctrlKey })
+          const clear = () => store.publish({ held: false })
+          const onVisibility = () => {
+            if (document.visibilityState === 'hidden') clear()
+          }
+          window.addEventListener('keydown', sync, true)
+          window.addEventListener('keyup', sync, true)
+          window.addEventListener('blur', clear)
+          document.addEventListener('visibilitychange', onVisibility)
+          return () => {
+            window.removeEventListener('keydown', sync, true)
+            window.removeEventListener('keyup', sync, true)
+            window.removeEventListener('blur', clear)
+            document.removeEventListener('visibilitychange', onVisibility)
+          }
+        }, 'dsh-hotkey: modifier state')
+
+        const activate = (sessionId) => {
+          if (sessionId !== undefined) ctx.uiWorkspace.openSession(sessionId)
+        }
+
+        const step = (delta) => {
+          const { ordered, currentId } = store.getSnapshot()
+          if (ordered.length === 0) return
+          const at = currentId === undefined ? -1 : ordered.indexOf(currentId)
+          const target = at === -1
+            ? (delta > 0 ? 0 : ordered.length - 1)
+            : (at + delta + ordered.length) % ordered.length
+          const nextId = ordered[target]
+          if (nextId !== currentId) activate(nextId)
+        }
+
+        const jump = (number) => {
+          const { ordered, currentId } = store.getSnapshot()
+          const target = ordered[number - 1]
+          if (target !== undefined && target !== currentId) activate(target)
+        }
+
+        ctx.effect(() => {
+          const nextBinding = { code: 'KeyN', modifiers: ['primary'] }
+          const previousBinding = { code: 'KeyN', modifiers: ['primary', 'shift'] }
+          const jumpBindings = []
+          for (let number = 1; number <= 9; number++) {
+            jumpBindings.push({ code: `Digit${number}`, modifiers: ['primary'] })
+          }
+          const jumpKeys = ctx.shortcuts.describeBinding({ code: 'Digit1', modifiers: ['primary'] }).keys
+          const disposers = [
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.next',
+              label: () => t('command.next'),
+              keys: ctx.shortcuts.describeBinding(nextBinding).keys,
+              bindings: [nextBinding],
+              group: 'application',
+            }),
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.previous',
+              label: () => t('command.previous'),
+              keys: ctx.shortcuts.describeBinding(previousBinding).keys,
+              bindings: [previousBinding],
+              group: 'application',
+            }),
+            ctx.shortcuts.registerFixed({
+              id: 'dsh-hotkey.jump',
+              label: () => t('command.jump'),
+              keys: [...jumpKeys.slice(0, -1), '1-9'],
+              bindings: jumpBindings,
+              group: 'application',
+            }),
+          ]
+          return () => {
+            for (const dispose of disposers) dispose()
+          }
+        }, 'dsh-hotkey: fixed shortcuts')
+
+        // Capture phase: own the combination before editors, terminals, and
+        // modal controls can stop its propagation. The fixed registrations above
+        // reserve the keys (so Command+N is not intercepted as New Session) and
+        // keep them visible in the Keyboard Shortcuts reference.
+        ctx.effect(() => {
+          const onKeyDown = (event) => {
+            if (event.defaultPrevented || event.repeat) return
+            // Do not consult isComposing/keyCode 229 here: Chinese IMEs report
+            // Shift as a composition key, which used to swallow Command+Shift+N.
+            // A primary-modifier chord is a command, not text input.
+            const primary = isMac
+              ? event.metaKey === true && event.ctrlKey !== true
+              : event.ctrlKey === true && event.metaKey !== true
+            if (!primary || event.altKey === true) return
+            if (event.code === 'KeyN') {
+              event.preventDefault()
+              event.stopPropagation()
+              step(event.shiftKey === true ? -1 : 1)
+              return
+            }
+            if (event.shiftKey !== true && /^Digit[1-9]$/u.test(event.code)) {
+              event.preventDefault()
+              event.stopPropagation()
+              jump(Number(event.code.slice('Digit'.length)))
+            }
+          }
+          window.addEventListener('keydown', onKeyDown, true)
+          return () => {
+            window.removeEventListener('keydown', onKeyDown, true)
+          }
+        }, 'dsh-hotkey: keyboard')
+
+        ctx.slots.inject('sidebar.session.row.leading', () => ctx.slots.register({
+          name: 'sidebar.session.row.leading',
+          id: 'dsh-hotkey.number',
+          order: 20,
+        }, SwitcherBadge))
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-hotkey
+      name: '@hellokidder/dsh-hotkey'

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#1b1e24"/>
+  <rect x="12" y="13" width="9" height="9" rx="2.5" fill="#5b8def"/>
+  <rect x="26" y="15.5" width="26" height="4" rx="2" fill="#8fb3ff"/>
+  <rect x="12" y="27.5" width="9" height="9" rx="2.5" fill="#8fb3ff"/>
+  <rect x="26" y="30" width="26" height="4" rx="2" fill="#c3d4ff"/>
+  <rect x="12" y="42" width="9" height="9" rx="2.5" fill="#c3d4ff"/>
+  <rect x="26" y="44.5" width="26" height="4" rx="2" fill="#e2eafc"/>
+</svg>

package/index.js

@@ -0,0 +1,2 @@
+/** Host half of the dsh-hotkey bundle; all behavior lives in the Client module. */
+export function apply() {}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH Hotkey",
+    "description": "One home for DSH keyboard shortcuts. Currently: hold Command to number the conversations in the sidebar, Command+N / Command+Shift+N to move between them, and Command+1-9 to jump straight to that number."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH 快捷键",
+    "description": "DSH 快捷键的统一入口。当前包含：按住 Command 显示侧边栏对话编号，Command+N / Command+Shift+N 循环切换，Command+1-9 直接跳转到对应序号。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@hellokidder/dsh-hotkey",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "One home for DSH keyboard shortcuts: hold Command to number sidebar conversations, Command+N / Shift+N to cycle, Command+1-9 to jump.",
+  "license": "MIT",
+  "author": "kidder",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "hotkeys",
+    "keyboard-shortcuts",
+    "session-switcher"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hellokidder/dsh-hotkey.git"
+  },
+  "homepage": "https://github.com/hellokidder/dsh-hotkey#readme",
+  "bugs": {
+    "url": "https://github.com/hellokidder/dsh-hotkey/issues"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-shortcuts",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  }
+}