跳过主要内容
W

dsh_vim

wurdmemory/dsh_vim

为 DeepSeek Harness 的对话输入、侧栏和面板提供 Vim 模态编辑与键盘导航。

安装

dsh plugin --profile web add github:wurdmemory/dsh_vim

README

dsh-vim

在 DeepSeek Harness 里用 Vim 风格的按键编辑输入框,并用 Vim 风格的按键浏览对话、侧栏和右侧栏。

当前版本 0.2.1(2026-11-22,tag v0.2.1)。本次修复:区域 1 的选框落回整行、长列表跟随滚动并在真正到底后才回绕、选框不再停在底部的用户控件上。完整历史见 CHANGELOG.md。

你会得到什么

  • 输入框模态编辑:NORMAL、INSERT、VISUAL、VISUAL-LINE,支持移动、操作符、文本对象、寄存器、计数、撤销/重做、搜索和 . 重复。
  • 对话区导航:j/k 滚动,gg/G 到顶部/底部,Ctrl-d/Ctrl-u 半页滚动,h/l 切换对话标签。
  • 四个分区:使用 Ctrl-1 到 Ctrl-4 在左栏、对话区、输入框和右栏之间切换。
  • 可见状态:徽标显示当前模式和分区;侧栏、菜单、右栏条目会显示选框;探测失败会在提示条中说明原因。
  • 与 DSH 共存:检测到 DSH 已占用的裸字母时,插件会让路,不拦截该快捷键。

插件只接管输入框、对话区、左右侧栏,不会把整个网页变成 Vim,也不会修改 DSH 的服务端或会话行为。

安装

前置条件

  • DeepSeek Harness 0.2.0-rc.1 或更高的 0.2.x 版本
  • Node.js 20 或更高版本
  • 本地插件目录:D:\DSH\dsh-vim

安装本地插件

在 PowerShell 中运行:

dsh plugin --profile <profile> add D:\DSH\dsh-vim

把 <profile> 换成要使用的 DSH profile 名称。安装后重新打开 DSH,或刷新客户端页面。

本地目录是链接安装。修改插件的 client.js 后刷新页面即可验证改动,不需要重复安装。

卸载

dsh plugin --profile <profile> remove dsh-vim

确认插件是否生效

  1. 打开一个 DSH 对话页面。
  2. 点击输入框。
  3. 如果看到 NORMAL 徽标和块状光标,说明插件已经加载。
  4. 按 i,输入一段文字,再按 Esc;徽标应回到 NORMAL。
  5. 按 Ctrl-2,提示条应显示已经进入对话区。

如果没有徽标,先刷新页面;仍无效时确认安装命令使用的是当前正在运行的 profile。

5 分钟上手

编辑并发送一条消息

  1. 点击输入框。每次重新进入输入框都会先进入 NORMAL。
  2. 按 i 进入 INSERT。
  3. 正常输入文字;中文输入法、Enter 和 Shift+Enter 在 INSERT 中保持浏览器原行为。
  4. 按 Esc 回到 NORMAL。
  5. 需要继续编辑时使用 Vim 操作;需要发送时再次按 i,然后按 Enter。

最常用的一组键:

h j k l       左 / 下 / 上 / 右
w b e         按单词移动
0 ^ $         行首 / 首个非空白 / 行尾
i a           在当前位置前 / 后插入
A I           到行尾 / 行首插入
o O           在下方 / 上方新开一行
u             撤销
Ctrl-r        重做
Esc           INSERT -> NORMAL
.             重复上一次修改

浏览对话

Ctrl-2        进入对话区
j / k         向下 / 向上滚动 160px
Ctrl-d/u      向下 / 向上滚动半页
gg            连续按两次 g 到顶部
G             到底部
h / l         切换「对话 / 轨迹 / 上下文」
yy            连续按两次 y,复制视口中间的消息
/             增量搜索
Esc           回到输入框

对话区不是逐条选中模式,j/k 直接滚动。消息行是由页面结构探测得到的,因此切换标签或页面刚加载时可能短暂显示“正在定位”。标签组第一次识别会走几何探测,之后 h/l 复用已确认的标签组;宿主替换标签栏或滚动列时才回到一次冷探测,因此连续切换不会重复读取整组布局。切换标签后的视图渲染仍由 DSH 宿主完成,宿主异步挂载内容时可能短暂显示“正在定位”。

浏览四个分区

快捷键分区
Ctrl-1左侧栏:会话、项目或文件树
Ctrl-2对话区
Ctrl-3输入框
Ctrl-4右侧栏

桌面端可能在原生层拦截 Ctrl-数字,此时在 NORMAL 下使用备用写法:

Space 1      左侧栏
Space 2      对话区
Space 3      输入框
Space 4      右侧栏
Space ?      复制分区探测诊断快照

在侧栏或菜单中:

j / k        下一个 / 上一个条目
l / o        打开当前条目
Enter        打开当前条目;在左侧栏中会跳到输入框
g / G        第一个 / 最后一个条目
r            重新探测分区
Esc          回到输入框

侧栏以整行作为条目单位:会话行左侧的图标、右侧的 ⋯ 菜单等自带点击处理的部件不会单独成为条目。j/k 选中并框住整行,Enter 触发的也是这一行的打开动作,不会落到行内按钮上。

会话很多时,j/k 不只停在当前可见的几行:列表会跟随选中项滚动,选框按列表的滚动位置贴着整行移动;走到最后一行、且选框已经完整停在列表底部之后,下一次 j 才回到顶部,同时列表也回到开头。侧栏最下方的用户 / 设置控件属于工具栏而不是条目,j/k 不会停在它们上面。

浏览右侧栏

Ctrl-4 会在右栏折叠时先展开它;已经在右栏时再次按 Ctrl-4 会收起右栏并回到输入框。

右栏的行为取决于当前标签:

内容主要按键
标签栏h/l 切换标签,Enter 进入
文件树、开始页、任务管理j/k 选中,Enter 打开
文档、Markdown、文本j/k 滚动
diffj/k 滚动,h/l 切换文件
图片j/k 缩放
终端、浏览器Enter 进入输入,按键交给内容;裸 Esc 返回标签栏
侧边对话j/k 滚动,Enter 聚焦输入框

在右栏中按 q、:q 或 :q! 可以关闭当前标签。关闭依赖宿主提供的关闭按钮或中键行为;如果页面没有可用的关闭动作,提示条会明确说明。

输入框完整键位

模式

模式进入方式说明
NORMAL点击输入框、Esc、Ctrl-3默认模式;可移动和执行编辑命令,不直接输入文字
INSERTi/a/I/A/o/O/s/S/C浏览器正常输入文字
VISUALv选择字符范围后执行操作
VISUAL-LINEV从当前行开始选择整行
SEARCH/ 或 ?增量搜索输入框内容

NORMAL 和 VISUAL 会接管可打印键、Enter、Backspace、Delete,避免误输入或误发送。要输入文字或发送消息,先按 i 进入 INSERT。

移动与操作

键行为
h/j/k/l左 / 下 / 上 / 右移动
w/W, b/B, e/E按单词移动
0, ^, $行首、首个非空白、行尾
gg, G文档首行、末行
f/F/t/T, ;, ,行内查找和重复查找
{, }, %段落或括号移动
d, c, y + 移动删除、修改、复制范围
dd, cc, yy删除、修改、复制整行
x, X删除当前字符、前一个字符;X 不跨行
D, C, Y操作到行尾
p, P在光标后、前粘贴
r, J, ~替换字符、合并行、切换大小写
iw, aw, i(, a(, i", a", i{, a{文本对象
"a 到 "z使用具名寄存器
3j, 2dd, d2w使用计数
n, N下一个、上一个搜索结果

jk 可以在 INSERT 中作为 Escape 的替代方式。默认启用;需要关闭时,在 src/entry.js 中将 escapeMapping: 'jk' 改为 escapeMapping: null,然后重新构建客户端 bundle。

Escape 的特殊行为

  • INSERT 中按 Esc 或 Ctrl-[:回到 NORMAL。
  • NORMAL 中按 Esc:交给 DSH,不被插件拦截,因此 DSH 的双击 Esc 停止回合仍然可用。
  • 点击输入框会回到 NORMAL,这是为了避免上次编辑状态残留后误输入。

重要说明

为什么有时按键没有移动

分区和消息行没有公开 API,插件会根据 DOM 结构、类名、角色和几何位置进行探测。探测失败时不会静默滚动错误区域,而会在徽标或提示条中说明原因。

  • 页面刚加载或切换标签后:等待短暂的“正在定位”,或按 r 重探。
  • 看不到选框:按 Space ? 复制诊断快照。
  • 方向键有效但 j/k/h/l 无效:页面或桌面端可能在更早层级拦截了单字母键;诊断快照会记录最近一次 key、code 和目标元素。
  • Ctrl-1 到 Ctrl-4 无效:改用 Space 1 到 Space 4。

与 DSH 快捷键冲突

插件启动时读取 DSH 已注册的裸字母快捷键。冲突键会让路,并在徽标中提示,例如 j 被占用时不会被 Vim 导航消费。

桌面端原生快捷键可能在按键进入网页前就被拦截,这种情况插件无法观测;请在 DSH 设置中调整冲突快捷键,或使用 Space leader。

输入法与跨源 iframe

  • 中文输入法组合输入会放行,不会被当成 Vim 命令。
  • 右栏中的跨源 iframe 受浏览器同源策略限制,插件只能控制外层 iframe,不能读取其中的页面内容。

常见问题

安装后看不到 NORMAL 徽标怎么办? 先确认 profile 名称正确,然后刷新 DSH 页面。仍无效时卸载后重新执行安装命令。

为什么按 Enter 没有发送? 你当前在 NORMAL 或 VISUAL。先按 i 进入 INSERT,再按 Enter 发送。

为什么点输入框后不能直接打字? 这是设计行为:点击输入框会进入 NORMAL,按 i 后再输入。

为什么 h/l 在右栏内容里没有反应? h/l 只用于标签层切换,或在 diff 页面切换文件;普通文档、图片、终端和浏览器内容会把它们交给内容本身。

为什么右栏慢加载时按键没反应? 右栏会等待内容挂载完成并自动重探。按 Esc 取消等待,按 r 重新探测。

为什么 j/k 没有逐条跳消息? 对话区采用滚动语义,单次滚动 160px,不显示消息选框。只有 yy 会使用视口中间的消息。

开发与验证

这些命令面向插件开发者,不是普通用户的安装步骤。

node --test "test/*.test.mjs"
node test/core.test.mjs
node test/shortcuts.test.mjs
node test/adapter-input-direct.mjs
node tools/build.mjs

当前回归覆盖:引擎 35 条、快捷键共存 6 条,以及无浏览器依赖的输入适配器边界测试。构建脚本把 bundle 输出到 stdout;在本机请使用 PowerShell 落盘,避免终端防护把 Node 写出的文件转换成不可加载的文件:

$t = (node tools/build.mjs) -join "`n"
[System.IO.File]::WriteAllText("D:\DSH\dsh-vim\client.js", $t, (New-Object System.Text.UTF8Encoding($false)))

浏览器夹具验证:

node tools/dev-server.mjs D:\DSH\dsh-vim 5900
# 打开 http://127.0.0.1:5900/tools/dev-harness.html

完整的 CDP 场景和性能诊断见 tools/verify.mjs;源码结构和设计取舍见 docs/design.md 与 docs/requirements.md。

# 场景脚本默认连 CDP 64000;ego-lite 等浏览器自选端口时用 DSH_VIM_CDP_PORT 指定
$env:DSH_VIM_CDP_PORT = "50995"
node tools/verify.mjs "http://127.0.0.1:5900/tools/dev-harness.html?longlist=1" sidebar-longlist

已知边界

  • 输入框编辑依赖 execCommand,失败时降级为文本节点 Range 编辑;这不是对 Lexical 内部 API 的替换。
  • 分区、消息行和右栏内容依赖 DOM 启发式;DSH 主题或布局变化后可能需要更新探测规则。
  • 首次进入新分区或新文本时会有探测和索引的冷路径;连续按键使用缓存。
  • 不提供独立 Vim 编辑器页面,不接管其它网页输入框。
  • 不支持宏、:命令、mark、分屏、插件脚本或 .vimrc。
  • 版本以 git tag 标记(v0.2.0、v0.2.1),变更记在 CHANGELOG.md;本地链接安装可直接 git checkout v0.2.1 回滚到旧版本。

文件结构

src/core.js              Vim 状态机,无 DOM,可单独测试
src/adapter-input.js     contenteditable 映射、键盘仲裁、块光标
src/adapter-transcript.js 对话区探测、滚动、复制和搜索
src/zones.js             分区探测和侧栏导航
src/adapter-pane.js      右栏标签、文档、图片和输入层
src/shortcuts.js         DSH 快捷键冲突检测
src/entry.js             插件入口、徽标和样式
client.js                生成的客户端 bundle

相关插件