dsh-nvim-tui

给 DeepSeek Harness (dsh) 用的
Neovim 风格 TUI：以 Neovim 作为终端渲染壳（内置 TUI 提供分屏、模态编辑、
extmark 等全部能力），一个 Node runner 作为 DSH 桥，把 agent 的事件流渲染进
nvim 缓冲区、把 nvim 的输入回传给 agent。

dsh --profile nvim-tui
└─ DSH host 组合 (dsh-base + nvim-tui-runner)
    └─ nvim-tui-runner (Node, Cordis 插件行)
        ├─ inject: agents / agentDefaultModel，订阅 session/event
        └─ spawn: nvim --listen <unix-socket>
             ├─ nvim 内置 TUI 渲染你的终端
             ├─ Lua UI (nvim/lua/dsh_tui)：chat buffer + prompt 输入窗 + 键位
             └─ msgpack-RPC 双向通信
                  Node → nvim: buf_set_lines 流式渲染 DSH 事件
                  nvim → Node: rpcnotify（输入、退出）→ agent.followup

特性速览

• Neovim 原生体验：聊天区就是普通 nvim buffer——搜索、复制、可视模式选择、
  你自己的 colorscheme / statusline / LSP 全部生效
• 流式渲染：·· thinking · 12.3s 浮动活动指示 + <C-o> 右侧面板收思考与
  工具记录；工具卡片、subagent/workflow 卡片、GFM 表格框线渲染；子代理思考链
  回放边思考边实时输出
• 状态栏：权限模式 · 模型 · effort · 缓存命中% · 上下文占用 · Σ token ·
  TTFT/吞吐 · 时长 · 预估成本 · provider 路由 · ⏳ 排队 / ⚙ jobs / 📋 待办 ·
  ⇢ 子代理寻址
• 转录增强（对齐官方客户端）：📋 待办条、⋯ 压缩检查点、↻ 重试状态行、
  workflow 转录内嵌套回放、结构化工具结果逐条渲染
• 会话管理：/sessions 工作区分组浏览器（📁 分组 + 未分组 + 归档隐藏）、
  /fork 分叉、启动自动续上次活跃会话（claude --continue 式）、/rewind 回退、
  /search 跨会话搜索、/archive 归档、/queue 消息队列
• 引用与补全：@ 文件引用 + @session 会话引用（官方规范 mention）；
  / 补全菜单含全部命令 + 技能条目
• 多模态识图：原生 image 直发，或经 dsh-vision-bridge 本地 OCR 转文字；
  <C-v> 剪贴板读图、/image <路径>、粘贴 data URL
• i18n：runner 侧界面字典化，/locale zh|en 即时切换
• 斜杠命令：50+ 命令，/ 自动弹出补全菜单（命令名 + 说明实时过滤）

安装 / 运行

一键安装（npm 发布后，或私有 registry）：

dsh plugin --profile nvim-tui add dsh-nvim-tui   # 安装 + 自动加入 bundles
dsh --profile nvim-tui                            # 启动（真实终端里）

dsh plugin add 会自动把声明了 dsh.bundle 的依赖调和进 profile 的
bundles 层栈（无需手改 package.json）。首个 profile 首次使用时自动初始化
（bundle 层为 @deepseek-ai/dsh-base，从 dsh 安装锚点解析）。

开发安装（本地仓库直链）：

mkdir -p ~/.dsh/profiles/nvim-tui
#   package.json 依赖 "dsh-nvim-tui": "link:<本仓库绝对路径>"，
#   dsh.profile.bundles = ["@deepseek-ai/dsh-base", "dsh-nvim-tui"]
#   cordis.yml = []，cordis.patch.yml = []，pnpm-workspace.yaml（见仓库内模板）
dsh plugin --profile nvim-tui install
dsh --profile nvim-tui

本仓库根目录就是 bundle 本身：cordis.patch.yml 挂载 nvim-tui-runner 行，
package.json 的 dsh.bundle.patch 声明了它。

启动后聊天区会显示版本横幅：dsh-nvim-tui 0.1.0 (build YYYY-MM-DD HH:mm) · channel N。
输入 /help 随时查看全部命令。

配置

runner 行的 config（profile 的 cordis.patch.yml，环境变量兜底）：

主题：config.theme 是一个 高亮组 → 属性 映射，每组可给
{ fg, bg, bold, italic, underline }（颜色 #rrggbb）或 { link: '内置组' }。
不覆盖的组保持默认（自动适配你的 colorscheme）。正文类内容默认跟随主题的
Comment 组（暗色观感），角色内容跟随对应组；亮色主题下自动回退为
Normal 混合的暗灰，不刺眼。

# ~/.dsh/profiles/nvim-tui/cordis.patch.yml
- insert:
    - id: nvim-tui-runner
      name: 'dsh-nvim-tui'
      config:
        theme:
          DshTuiUser: { fg: '#7aa2f7', bold: true }
          DshTuiTool: { fg: '#e0af68' }
          DshTuiReasoning: { fg: '#565f89', italic: true }
          DshTuiError: { link: 'ErrorMsg' }

可用组：DshTuiUser（用户消息）· DshTuiAssistant（模型输出）·
DshTuiNotice（提示）· DshTuiDivider（分隔/表框）· DshTuiDim（列表等
未高亮文本）· DshTuiError · DshTuiTool · DshTuiSubagent ·
DshTuiWorkflow · DshTuiCode（行内代码/代码块）· DshTuiBold ·
DshTuiReasoning（思考）· DshTuiPrompt（输入行 ❯）·
DshTuiStatus（状态栏）· DshTuiActiveSession。
也可用内置预设 /theme default|dim|vivid|contrast|mono 即时切换。

布局与键位

双窗布局：对话区 / 输入窗（会话列表是 /sessions 浮窗）。输入窗每行行首有
REPL 风格的 ❯ 提示符——它渲染在窗口的 status column 里，不属于输入内容：
不会被提交、也删不掉。运行中发送的消息会排队在当前回合结束后处理（对话区有
"已排队"提示 + 状态栏 ⏳ 计数，/queue 可查看/编辑/删除排队消息；想不排队
可用 /btw 侧问）。

斜杠命令

输入 / 即弹出补全菜单（命令名 + 说明，随输入过滤）；命令目录由 runner 启动时
推送给 nvim，与 /help、命令分发表共用同一份注册表，不会漂移。

依赖的宿主服务未装配时，对应命令会给出明确提示。

多模态识图

图片经 harness 的 durable attachment 管线发送——TUI 读字节 →
attachments.saveImage() 校验并落库 → 用户消息携带稳定 image 块 →
LLM 适配器在请求时解析为 data URL。两条能力路径：

1. 原生识图：模型目录声明 inputModalities: [text, image]，且网关对模型
   透传 image_url（自建 text-only 网关会以
   unknown variant image_url, expected text 拒绝）；
2. 识图桥（text-only 模型/网关推荐）：装配 dsh-vision-bridge（提供
   visionBridge 服务），图片在进入模型前经本地 macOS Vision OCR
   （~/.dsh/scripts/feishu-ocr，零成本离线；可选远程视觉模型兜底）转成
   文字描述注入，模型读文字"看图"。此时模型目录应保持 [text]，否则桥会
   按"原生识图"跳过转换。

发送前 TUI 会预检：模型原生识图 → 直发；有识图桥 → 提示"经识图桥转成文字
描述后发送"；两者皆无 → 明确报错而不是让回合死在适配器里。

旧会话遗留：装桥之前失败发送留下的带图消息会永久留在会话历史里，导致该会话
后续每轮都被适配器拒绝——用 /rewind 回退到带图消息之前即可修复（新会话
不会再产生这类残留）。

会话管理

• 每个会话独立的 chat buffer 与事件流；/sessions 是工作区分组浏览器
  （对齐官方侧栏）：📁 工作区 头 + 缩进会话 + 未分组区 + 持久化历史
  （标记 历史），标题 + 完整会话 id 展示
• 工作区（需 dsh-workspace/适配器服务）：/workspace add|delete 管理，
  工作区行内可新建会话于此 / 重命名；/archive [id] 归档会话（非破坏性，
  从所有分组隐藏）
• 子代理/派发会话（裸 UUID id，无 session- 前缀）不出现在列表，经
  /subagents 目录进入
• 退出时 flush 全部活跃会话（jsonl.zstd 持久化）；下次启动历史会话出现在列表，
  Enter 选中即通过 agents.resume 恢复并重放转录
• 自动续会话（claude --continue 式）：启动时默认恢复本项目的"上次活跃会话"
  （状态记录在 $DSH_HOME/dsh-nvim-tui-state.json，无记录则回退到最新的
  持久化会话）；/new 随时开新。关闭：环境变量 DSH_NVIM_TUI_RESUME_LATEST=0
  或 config.resumeLatest: false；显式 DSH_NVIM_TUI_RESUME=<id> 优先
• 回合失败（缺凭据、网关错误等）以 ⚠ 行显式渲染在对话区，不再静默消失

状态栏与活动面板

• 状态行左侧：动态权限模式（sandbox/mode → read-only / normal /
  full-access + approval/policy → ask / never）+ 快捷键提示
  （/ 命令 · ctrl+o 面板 · ctrl+p 历史）
• 状态行右侧：模型 · effort（◎max）· 缓存命中%（会话累计）·
  上下文占用% + ◧ 已用/窗口（最近一步的 billed 输入）· Σ 会话累计 token ·
  TTFT / tok/s（读官方 sessionStats 投影）· 会话时长 · 预估成本
  （内置公开定价表，未知模型诚实降级不显示）· provider 路由 · ⏳ 排队计数 ·
  ⚙ 运行中 jobs · 📋 待办计数 · ⇢ 子代理寻址；running 时带旋转动画 +
  运行时长，180ms 刷新；idle 30s 低频刷新
• 活动面板（<C-o>）：思考过程 + 工具使用记录收进右侧面板，聊天区只显示
  浮动活动指示（·· thinking · 12.3s / 🔧 bash · 2.1s），活动结束即消失、
  不写入聊天记录。面板按回合组织：思考块（全文 + ── thinking end · Ns ──
  页脚）与工具卡片（🔧 调用 / ✓✗ 结果 · 耗时）按时间线累积，新回合自动清空，
  历史重放保留全量；turn 开始 800ms 仍无内容时显示跳动的 ·· thinking… Ns
• 渲染层：extmark 角色着色（用户/提示/工具/错误/子代理/工作流各自颜色，
  default link 自动适配你的 colorscheme）；**粗体**、`行内代码`、
  围栏代码块 剥离标记后以高亮 span 渲染；流式更新对上次视图做 diff
  后增量 set_lines
• Markdown 表格（Claude-TUI 风格）：GFM 表格渲染为对齐的框线表格
  （┌┬┐ ├┼┤ └┴┘）——整表统一加粗（单元格/│/─/转角同 weight，
  消除字体渲染造成的粗细不一）、数字列右对齐、显式 :--: 居中；列宽按
  显示宽度计算（中文/emoji 占 2 列）；流式输出期间无底边框，流结束自动补上
• 官方客户端对齐的转录元素：todo/write → 📋 待办条（✓/…/· 标记）；
  compaction/summary → ⋯ 压缩检查点（条数 + ≈tokens + 摘要块）；
  llm/retry → ↻ 重试状态行（次数/上限/倒计时/失败原因）；
  tool-workflow/* → ◈ workflow 嵌套成员行；JSON 结构化工具结果逐条 itemize

聊天记录缓冲区禁用了 undo（undolevels=-1），在对话区按 u 不会撤销内容。

用户配置与插件

默认加载你自己的 nvim 配置和插件（colorscheme / statusline / LSP 等全部生效）：
dsh_tui 在 VimEnter（用户配置加载完成后）接管窗口布局，并会在 300ms/1.2s 时
检查布局是否被插件（如 dashboard）顶掉并自动重建。
如需纯净启动（不加载用户配置），给 runner 行加 config: { loadUserConfig: false }；
沙箱/CI 的 headless 测试模式会自动隔离 XDG 目录。

开发

npm install                      # neovim 客户端（+ dsh peer 依赖用于本地解析）
npm run build                    # TypeScript (src/) → lib/（strict，tsc，含 .d.ts）
npm run dev                      # tsc --watch（改动即重编，dsh hmr 随即热载）
npm run check                    # src + scripts 双 tsconfig 全量类型检查
npm run smoke                    # 无头冒烟：RPC 往返 + Lua 插件 + 事件渲染
                                 # （scripts/*.ts 经 Node ≥23.6 原生 type-stripping 直跑）

端到端无头验证（不需要真实终端，走完整 host→agent→渲染链路）：

DSH_HOME=$PWD/.dsh-test \
DSH_NVIM_TUI_HEADLESS=1 \
DSH_NVIM_TUI_PROMPT='请只回复两个字：好的' \
DSH_NVIM_TUI_DUMP=/tmp/e2e-dump.txt \
dsh --profile nvim-tui
# 首个 turn 结束后 chat buffer 全量落盘到 /tmp/e2e-dump.txt 并退出

真模型回归（需要 dsh 凭据）：

npm run e2e -- "你好，请只回复：收到"   # headless 跑一轮真回合并校验 dump

.dsh-test/ 是工作区内的 DSH_HOME 测试副本（profiles 的共享 node_modules
以符号链接复用 ~/.dsh/profiles/node_modules），用于在沙箱/CI 里 boot。

发布

npm publish        # prepublishOnly 门禁：check（双 tsconfig）→ build → smoke

files 白名单已裁剪（lib / nvim / cordis.patch.yml / README）；peer 依赖
（@deepseek-ai/dsh-agent、dsh-llm）由 profile 内的 dsh-base 提供。

目录结构

src/                          TypeScript 源码（strict，唯一手写源）
  index.ts    Cordis 插件入口：spawn nvim → RPC → agent 生命周期 → 事件桥
  feed.ts     转录渲染器：DSH 事件 → chat buffer 行模型（节流刷新）
  types.ts    共享类型层：SessionEvent 判别联合 + 宿主服务结构接口
  i18n.ts     界面字典（zh 字面量 → en 查表，未知键回退中文）
  bridge.ts   nvim spawn / socket 连接（自建 socket + error 处理）
  table.ts    GFM 表格 → 框线表格转换（显示宽度对齐）
  stats.ts    状态栏统计：token/缓存/成本/时长 折叠与格式化
  images.ts   图片读取：文件 / macOS 剪贴板 / data URL 解析
lib/                          tsc 编译产物（.js + .d.ts；dsh 加载入口 main → lib/index.js）
nvim/lua/dsh_tui/init.lua     nvim 侧 UI：窗口布局、prompt 输入、键位、RPC
scripts/smoke.ts              无头冒烟测试（Node ≥23.6 直跑）
scripts/e2e.ts                真模型端到端回归
tsconfig.json / tsconfig.scripts.json   主构建 / scripts 检查配置
cordis.patch.yml              bundle patch：insert nvim-tui-runner 行

关键设计决策

• 不用 nvim --embed：它会隐式 headless，网格渲染就得自己做。
  这里正常启动 nvim，用 --listen socket 驱动，内置 TUI 渲染终端。
• 默认加载用户配置（-u NONE 仅是开关）：dsh_tui 在 VimEnter 后接管
  布局；headless/沙箱模式通过 XDG 隔离实现干净环境。
• runner 行的 effect disposer 只拆 UI 不退出进程：hmr 重载该行时
  dsh 继续运行，下一次 apply 会 spawn 新的 nvim。只有用户主动退出、
  nvim 退出、致命错误、信号才会走 appExit。
• 消息只从 session/event 渲染（不本地回显），避免与转录重复。
• TypeScript 源码 → 编译产物：src/*.ts 经 tsc（strict）输出 lib/，
  dsh 按 npm 包入口加载编译产物；.ts 不能直接作入口（Node 对 node_modules
  内 .ts 拒绝 type-stripping，发布形态必挂）。scripts 用 Node ≥23.6 原生
  type-stripping 直跑，不进发布包。

License

MIT

需求基线见 REQUIREMENTS.md（由本仓库早期 README 转化，
按里程碑 M0–M7 记录需求与验收状态）。