@dsh-external/dsh-nav-keys

Readme

# dsh-nav-keys

[![简体中文](https://img.shields.io/badge/语言-简体中文-0969da)](./README.md) [![English](https://img.shields.io/badge/Language-English-57606a)](./README.en.md)

DeepSeek Harness Web 输入框方向键插件：裸 ↑/↓ 像终端（bash/readline）一样召回与切换已发送消息历史——**按键意图驱动**：一旦用 ←/→/Home/End 或鼠标定位光标，↑/↓ 立刻变回普通行间移动，编辑永不被打断。零核心改动。本项目是非官方社区插件，与 DeepSeek 官方不存在隶属或背书关系。

## 与 DeepSeek 的关系

本插件运行在 DeepSeek Harness Web 客户端中，只读写官方输入门面（`conversation.input.for(actx).setDraft()`）与会话快照（`ConversationSnapshot.nodes`）；不修改模型、提示词或会话数据，不向外部服务发送数据，纯浏览器端行为。

## 功能与行为

**裸 ↑/↓ —— 终端式历史召回（按键意图驱动）**：
- **默认（history 模式）**：↑/↓ = 翻历史——↑ 召回最近一条已发送消息，连按向更早遍历；↓ 向新走，走到底恢复你召回前的草稿（空草稿、单行、多行一致）
- **定位后（caret 模式）**：一旦用了 ←/→/Home/End（含 Ctrl 词跳、Shift 选区扩展）或鼠标点击移动光标——↑/↓ 立刻变回**普通行间移动光标**：你在编辑，上下不该再翻历史
- **回到 history 模式**的自然边界：发送清空草稿、删到空、召回一条历史落地（继续翻）、切换会话

**Ctrl+↑ / Ctrl+↓（macOS 上 Cmd+↑/↓ 同效）—— 无条件召回**：
- 任何模式/草稿状态下直接进入历史遍历（caret 模式下的后门）
- macOS 绑定 Cmd 作为别名（Ctrl+方向键常被系统占用）；代价是覆盖 Cmd+↑/↓ 原生跳首尾

**历史来源**：当前会话快照的用户消息（自动去相邻重复、跳过空白），刷新页面后仍然可用。

**让位规则**（这些键永远不属于本插件）：
- `/`、`@` 触发菜单与命令弹窗打开时：所有方向键（含 Ctrl 组合）让位给菜单高亮移动
- IME 输入法组合中（`isComposing` / keyCode 229）：一律放行
- Alt+方向键、Ctrl+Cmd 叠加、其余所有键：原样放行
- 召回出的文本被手动编辑后，浏览状态自动复位

## 安装

在 Web profile 安装（Git 安装会跑 `prepare` 构建）：

```sh
dsh plugin --profile web add github:ClausYang/dsh-nav-keys
```

或安装本地 checkout：

```sh
dsh plugin --profile web add /path/to/dsh-nav-keys
```

重启 `dsh web` 后浏览器端随页面加载。

## 构建

```bash
pnpm install
pnpm run build      # lib/index.js + lib/invariant.js + lib/client.js
pnpm run test       # 纯逻辑单测（19 个）
pnpm run typecheck
```

## 设计说明

- 纯浏览器端实现：无服务端行为（`src/index.ts` 是空壳），不向模型或会话日志注入任何内容
- 两层纯逻辑，零 DOM/零 cordis 依赖，全部可单测：
  - `src/client/history.ts` —— 历史抽取（kind 过滤、text 块拼接、空白跳过、相邻去重）+ 召回状态机（进入/最旧/最新/回 live 恢复草稿）+ 外部变更 re-sync
  - `src/client/decision.ts` —— 模式状态机（意图驱动）：position（←/→/Home/End/选区/鼠标）→ caret；recall / 草稿清空 / 切会话 → history
- 键盘在 document capture 阶段拦截；只在判定为召回时 `preventDefault`，其余一律放行
- 召回草稿写入走官方输入门面 `conversation.input.for(actx).setDraft()`，与撤销/发送事务兼容

## 兼容性

基于 snapshot0812 / npm `@deepseek-ai/dsh@0.0.1-rc.5` 基线开发与实机验证（boot 图加载、召回与模式切换实测可用）。依赖的契约：
- `conversation` / `sessions` 服务与 `conversation.input.for(actx).setDraft()`、`ConversationSnapshot.nodes`（与 dsh-input-history 相同的官方门面，0808–0812 间未变）
- DOM 标记 `data-input-scroll`（composer 定位）、`data-composer-seat`（菜单让位检测）

## 已知限制

- 历史仅覆盖当前会话；跨会话/跨设备历史共享未实现
- 快照窗口外的旧消息不在召回范围内
- Cmd+↑/↓ 别名覆盖了 textarea 原生跳到首/尾（macOS）
- 切换会话后召回浏览状态复位，不跨会话续接
- caret 模式下裸 ↑/↓ 是原生光标移动（设计如此）；想翻历史用 Ctrl/Cmd+↑，或清空草稿回到默认模式

## 许可证

BSD 3-Clause，见 [LICENSE](./LICENSE)。

## 维护

由 [@ClausYang](https://github.com/ClausYang) 维护，欢迎 Issue / PR。