Emacs 聊天客户端 vritser/dsh-emacs

dsh-emacs — DeepSeek Harness 的 Emacs 客户端

在 Emacs 里使用 DeepSeek Harness（dsh）：流式回复、工具调用、工作区会话、子代理对话、文件附件、模型选择。需要 Emacs 28.1+，不强制依赖任何第三方 Emacs 包。

https://github.com/user-attachments/assets/9ee9fc66-1997-49b7-a921-5753690edafa

dsh-emacs 0.7.0 兼容 dsh 0.2.1-rc.2，这是截至 2026-10-18 的最新上游版本（npm next；npm latest 仍指向 0.2.0-rc.2）。客户端包含针对 dsh 0.2.1 协议的兼容修复：服务端分配会话 ID、需要迁移的投影读取、外部子代理导航防护。协议参考已对照 dsh 0.2.1-rc.2 审计源码。2026-10-23 的实机验证针对该版本通过了 31 项 E2E 检查（可选的模型驱动子代理与运行状态场景未启用）；外部子代理防护有单元测试覆盖。保留原有的浏览器 cookie 认证。

快速开始

1. 克隆仓库：

git clone https://github.com/vritser/dsh-emacs.git ~/dsh-emacs

2. 把下面这段加进 Emacs 配置并求值，或者重启 Emacs：

(add-to-list 'load-path (expand-file-name "~/dsh-emacs"))
(require 'dsh-emacs)

3. 运行 M-x dsh-emacs。它会打开会话列表，需要时启动本地服务端，dsh 命令行缺失时还会提示安装。
4. 用 M-x dsh-emacs-add-provider 配置服务商，或者用 M-x dsh-emacs-open-web 登录账号、接入其他服务商系列。凭据和模型设置都留在 dsh 服务端。
5. 按 c 创建会话，用 C-c C-m 选择模型，然后在 ❯ 后面输入，按 C-c C-c 发送。

如果已有服务端，先配置它的地址和认证再连接。use-package 示例见自定义。

使用

M-x dsh-emacs 打开会话列表，最近排在最前：最近更新的 15 个可见会话，后面是它们各自的工作区分组。改 dsh-emacs-session-recents-limit 可以调整数量（设为零则隐藏「最近」）。按 RET 打开会话，按 c 新建会话，按 TAB 折叠分组或展开可用的子代理。
在本地项目里，命令会找到它已有的工作区；在对话里，命令会找到那个会话。新建会话在连接期间打开可编辑草稿。在全新对话缓冲区里打开已有会话时，只补全最新的用户轮次（一轮由用户撰写的消息），为长轮次加载更多页，同时不移动草稿光标。C-c C-o 取消正在进行的加载历史；加载完成后，默认加载 3 个更早的用户+助手轮次（dsh-emacs-history-rounds）。切回实时聊天时，会保留该聊天。

PTC 模式预设 ID 现在是 ptc。如果你的配置把 dsh-emacs-default-preset 设为 "code"，请改成 "ptc"。

空闲会话圆点、New Session 占位符和弱化文本（时间戳、回复页脚、交付物描述、子代理错误提示）使用主题的 shadow face（默认灰色）；运行中的会话圆点是橙色。

常用按键

| 按键 | 聊天缓冲区中的操作 |
| C-c C-c | 发送；忙碌时，排队输入，或在输入和附件都为空时中断 |
| C-u C-c C-c | 引导正在运行的轮次（默认配置） |
| C-c C-b | 中断正在运行的轮次 |
| C-c C-q / C-c C-j | 管理待发消息 / 后台任务 |
| C-c C-m / C-c C-e | 选择模型 / 调整推理强度 |
| C-c C-a | 暂存文件；重复操作可添加更多 |
| C-c C-v / C-c C-d | 粘贴剪贴板图片 / 丢弃暂存的附件 |
| C-c C-o | 加载 3 个更早的用户+助手轮次；前缀参数决定数量；再按一次取消 |
| C-c > | 回到草稿并跟随新输出 |
| C-c C-w / C-c C-y | 复制内容 / 从光标处的助手回复分叉 |
| C-c C-l | 在列表中定位当前会话（跳转偏好） |
| C-c C-s / C-c M-s | 在当前工作区 / 所有工作区之间切换会话 |
| C-c C-r | 刷新聊天 |
| M-p / M-n | 调出上一条 / 下一条输入 |
| TAB | 补全命令、技能、引用、本地路径或单词 |

用户消息保持左对齐，带青色左侧竖线和较浅的内边距，每个问题前后各留一个空行。回答保持无边框；完成摘要会在回答上方留出小间隙，但不改变回答的字体。
普通 Emacs 撤销只作用于输入，不改动对话记录。
复制用户消息的一行会得到其撰写的文本；粘贴时不会把对话竖线或间距带入目标位置。
M-x imenu 可在对话的问题之间跳转。点击折叠的工具或思考标题，或在标题上按 RET，即可展开。轮次结束后，回复之间的连续思考和工具卡片会折叠成活动摘要，例如 Read files and ran commands。回复仍留在这些分组之外。
没有中途输入的轮次成功结束后，还会把整个过程折叠到 Completed… 下，最终回答保持可见。Failed 和 Stopped 是不可折叠的状态行，有中途输入的轮次的完成行也是如此；它们内部的活动仍会各自独立折叠。运行中的轮次保持展开。
更早的历史会扩展展开项，但不会重置手动展开状态。
把 dsh-emacs-fold-work-details 设为 nil，再重新打开聊天，就能得到平铺的对话记录。
参见 Web 折叠规则与剩余差异。
可见的聊天窗口各自跟随新输出，光标和视图留在草稿附近，保留各自的编辑位置。正在阅读旧消息的窗口保持不动；C-c > 让该窗口回到草稿并恢复跟随。

0.7.0 版本移除了 dsh-emacs-group-consecutive-tools 和 dsh-emacs-assistant-divider；两者都已删除，请从个人配置里清掉残留条目。工具卡片仍独立折叠，助手消息间距不变。参见 自定义。

0.7.0 还移除了未使用的 Lisp 辅助函数 dsh-emacs-modeline-set-cwd、dsh-emacs-modeline-set-branch、dsh-emacs-modeline-teardown 和 dsh-emacs-usage-p，且不提供别名。请从个人 Lisp 代码里删掉对这些函数的调用；cwd 和分支改为跟随聊天的 default-directory 与缓存的 Git 检测结果。参见 模式行。

引用、命令与附件

- @ 引用用于选择服务端文件、目录或会话。发现过程在后台运行；Corfu 会在结果到达时刷新，其他前端可能需要再按一次 TAB。参见 @ 引用。
- / 命令与技能用 TAB 补全，消息内空格之后同样有效。用 /plan 进入计划模式，用 /plan off 退出。提交的计划会在审阅缓冲区中打开。参见 斜杠命令 和 技能。
- 附件通过 C-c C-a、剪贴板粘贴或拖放暂存。C-c C-c 会连同你的输入一起发送；输入为空时用附件的文件名。参见 附件暂存。
- !git status 在会话的工作区内本地运行。输出既不发给模型，也不存入服务端历史。普通路径补全同样使用运行 Emacs 的机器；要访问远程服务端文件请用 @。参见 Shell 命令。

未完成的输出会留在紧凑的对话记录卡片里，依据服务端的后续事件明确标注为 Retry（已排期或已开始）、Failed reply、Cancelled reply 或 Retry cancelled。没有显式重试事件、但已恢复的情况，会在同一轮同一 step 内收到另一个响应后显示 Retried。部分输出仍可展开；把鼠标悬停在标题上可查看失败详情。模式行会持续显示运行中的活动和已用时间，不另设重试标签。如果拿不到结果事件，卡片显示 Incomplete reply。重试、取消、模型错误和压缩失败共用一个状态点图标：橙色表示重试，红色表示失败，灰色表示已取消或未知。模型错误原因仍显示在标题下方。

目标、子代理与提问

输入区先显示下一条待发消息，再显示当前目标。C-c C-g 打开 目标操作；C-c C-q 管理队列。
默认的忙碌发送行为可通过 dsh-emacs-busy-enter-behavior 配置。

M-x dsh-emacs-list-subagents 打开子会话；M-, 返回起始位置。可继续的子会话接受后续输入，一次性子会话只读。见子代理。

智能体提问使用你惯用的 minibuffer 补全。选一个选项或直接输入答案；多选题答案接受逗号分隔的选项，例如 2,3。输入为空则跳过该问题。C-c C-p 回答已超时的定时问题。见问题提示。

外观

模式行显示模型、用量和活动状态。单独安装 Motion Line 可获得动画鲸鱼和计时时钟；不安装时，活动说明保持静态。
原生模式行始终保留朴素的 DSH 主模式标签；单独的鲸尾动画、说明和时钟只在活动期间出现。
Doom 保留其静态鲸鱼标志和现有布局。
完成的回复在左侧按顺序并排显示 Copy、Fork 和 token。
耗时显示在答案上方紧凑的 Completed 折叠区；把 duration 加入 dsh-emacs-reply-footer-items，页脚也会显示它。

转录事件行遵循 dsh-emacs-render-style：full（默认）在 Emacs 能渲染的地方绘制 dsh-web 的 SVG 图标，而 simple 让每个事件行以一个紧凑圆点开头（该行带状态时圆点按状态着色），并弱化该行其余部分。

配置见模式行、回复页脚和 UI 样式。

服务器设置

默认情况下，dsh-emacs 管理本地服务器。若要使用你自己运行的服务器：

(setq dsh-emacs-base-url "http://127.0.0.1:3080"
dsh-emacs-server-auto-start nil)

远程地址（包括 HTTPS）永远不会触发本地服务器启动。
由 dsh-emacs 启动的服务器自动完成认证。对于外部服务器，把其打印的启动 URL（http://host:port/?token=…）粘贴到 dsh-emacs-base-url，设置 dsh-emacs-server-auth-token，或在提示时提供 token。提示输入的 token 成功后会被保存；服务器重启后可能需要新 token。反向代理的 Basic 认证与 dsh 启动 token 相互独立。

配置见服务器选项，模型设置见添加服务商，本地或 TRAMP 配置文件见编辑 dsh 配置。

文档

- 自定义 — 选项、历史、工作区、审批
- @ 引用 · 斜杠命令 · 技能
- Shell 命令 · 模型选择器 · 子代理
- 模式行 · UI 样式
- 更新日志 — 发布说明与破坏性变更
- 架构 · RPC 协议

参与贡献

遵循 AGENTS.md，保持改动聚焦，推送前运行 scripts/verify.sh。它会检查语法、字节编译、单元测试、干净加载和仓库卫生。CI 在 Emacs 28.1 和当前稳定版上跑同一道关卡。可选的 GUI 测试和真实服务器测试覆盖显示与传输行为。

改完源码后，M-x dsh-emacs-reload 会重新加载，同时保留聊天和草稿。删掉的定义和改过的结构体布局需要重启；见源码重载。

致谢

UI 参照 dsh web。
Markdown 渲染与折叠基于 agent-shell；模式行统计和紧凑 token 格式化沿用 pi-mono。

许可证

GPL-3.0-or-later — GNU General Public License v3 或更高版本。