seewhydee/dsh-emacs-bridge

dsh-emacs-bridge

这是 GNU Emacs 与 Deepseek Harness 会话之间的双向桥接。该桥接通过回环 HTTP 在 Emacs 与 DeepSeek Harness（DSH）之间传递文本，反之亦然。这样你就可以在 Emacs 中输入并阅读 DSH 的回复，而无需复制粘贴，同时也避免了通过 Emacs 流式传输大量 LLM 输出。

它由两个组件组成：

- dsh-plugin/ —— 一个 DeepSeek Harness 插件（dsh-emacs-bridge）。
- emacs/dsh-bridge.el —— 一个用于与 harness 交互的 Emacs 包。配套库 dsh-bridge-install.el 按需加载，提供安装/卸载 DSH 插件的命令。

安装

要求

- dsh，即 DeepSeek Harness。
- Node.js 和 pnpm，用于构建插件。
- Emacs 29 或更高版本。
- （推荐）markdown-mode Emacs 包。

Emacs 包

要构建一个同时捆绑 DSH 插件的 Emacs 包，请在仓库根目录下运行：

make package

然后，在 Emacs 中：

1. M-x package-install-file RET /path/to/dsh-bridge-.tar RET
2. （可选）如果你从源码检出运行 DSH，请用 DSH 命令自定义变量 dsh-bridge-dsh-command（例如 M-x customize-variable RET dsh-bridge-dsh-command RET）（见下文）。如果 dsh 在可执行路径上或通过 npx 运行，则跳过此步骤。
3. M-x dsh-bridge-install-plugin —— 将捆绑的插件安装到 DSH 中。
4. 启动或重启 dsh web。

要稍后移除该插件，请运行 M-x dsh-bridge-uninstall-plugin。

以下是针对源码检出的 dsh-bridge-dsh-command 示例：

(setq dsh-bridge-dsh-command "pnpm -C /path/to/deepseek-harness dsh")

注意 ~ 不会被展开，因此请指定完整路径。不要在末尾添加额外的 web 参数。

手动编译和安装

除了使用一体化的 Emacs 包之外，你还可以手动构建并安装 DSH 插件和 Emacs 库。

构建并安装 DeepSeek Harness 插件

在此仓库的根目录下：

make build   # emits dsh-plugin/lib/index.js + lib/client.js

如果你已将 dsh 安装在可执行路径上，请运行以下命令：

global install, from this repo root:
dsh plugin --profile web add link:./dsh-plugin
dsh web

如果你有 DSH 的源码检出，并作为 pnpm 脚本运行它（pnpm dsh web），请改为在 deepseek-harness 目录下运行以下命令，并将 link: 路径替换为指向此仓库的相应路径：

source checkout, from deepseek-harness root:
pnpm dsh plugin --profile web add link:/absolute/path/to/dsh-emacs-bridge/dsh-plugin
pnpm dsh web

安装 Emacs 库

将以下内容放入你的 Emacs 初始化文件（~/.emacs.d/init.el 或 ~/.emacs），并将路径替换为 dsh-bridge.el 的实际路径：

(load "/path/to/dsh-emacs-bridge/emacs/dsh-bridge.el")

可选地，你也可以加载 dsh-bridge-install.el，其中包含前面提到的 M-x dsh-bridge-install-plugin 命令。但如果你按照上一节的步骤直接安装了 DSH 插件，那么你可能不需要这些。

用法

在 Emacs 中，主要入口是这两个命令：

- M-x dsh-bridge — 打开一个用于 DSH 命令的 transient 菜单。
- M-x dsh-bridge-list-sessions — 显示 DSH 会话列表。

可以考虑为其中任意一个设置全局键绑定，例如：

(keymap-global-set "C-c d" #'dsh-bridge)

Transient 菜单

M-x dsh-bridge 命令会打开一个 transient 菜单，提示你输入下一条命令。顶行显示你的下一条命令将作用于哪个会话。transient 菜单中提供以下命令：

* q — 退出 transient 菜单。
* r — 打开一个缓冲区以输入提示词。
* s — 将区域或缓冲区作为提示词发送（如果会话正忙，提示词会排队）。
* d — 将区域或缓冲区作为草稿发送（仍可在 DSH 中编辑后再提交）。
* f — 获取并显示会话的最新回复。
* D — 描述该会话。
* t — 设置默认目标会话。
* u — 清除默认目标会话。
* k — 停止正在运行的会话。
* l — 打开 DSH-Sessions 缓冲区。
* + — 创建新会话，并提示输入其工作区和标题；
新会话将成为默认目标。
* p — 为有效会话切换计划模式。
* G — 设置或编辑目标 objective（使用 C-u 时，还可设置轮次上限）。
* A — 暂停已武装的目标，或恢复并重新武装已停止的目标。
* X — 清除当前目标。

DSH-Sessions 缓冲区

M-x dsh-bridge-list-sessions 命令会打开一个 DSH 会话列表。默认目标会话（如果有）由最左侧列中的  标记，S（状态）列显示每个会话的实时状态。此处提供以下命令：

q — 退出窗口并 bury 缓冲区。
* RET — 对光标处的会话执行下一个合适的操作：
例如，如果它正在运行，则查看当前回复；如果正在等待提示词，则打开一个缓冲区以输入提示词。
* r — 为光标处的会话打开一个缓冲区以输入提示词。
* f — 获取并显示光标处会话的输出。
* a — 回答光标处会话待处理的用户查询。
* k — 如果光标处的会话正在运行，则停止它。
* t — 将光标处的会话设置为默认目标。
* u — 清除默认目标。
* v — 切换是否显示已归档会话（默认隐藏）。
* R — 重命名光标处的会话。
* d — 归档光标处的会话。
* U — 取消归档光标处的会话。
* + — 在现有或新工作区中创建新会话。
* W — 重命名光标处会话的工作区。
* D — 描述光标处的会话。
* g — 刷新 DSH-Sessions 缓冲区。
完整列表请参见菜单栏。其他 tabulated-list-mode 按键也可用。

DSH-View 缓冲区

此只读缓冲区包含 DSH 会话的模型输出。
每个缓冲区保存一个智能体回合（即从用户提示到空闲状态的所有回复）。
可通过瞬态菜单或 DSH-Sessions 缓冲区中的 f、提示缓冲区中的 C-c C-f，或从 Web UI 的“Send to Emacs”按钮推送（见下文）来获取。

DSH-View 缓冲区中可使用以下命令：

* g — 重新获取当前会话的最新回合。
* r — 为当前会话打开一个 DSH-Prompt 缓冲区。
* B — 将显示的回合分支为新会话。
* k — 停止所显示会话正在运行的回合。
* i — 接收最新的“Send to Emacs”消息（见下文）。
* D — 描述当前会话。
* M-p/M-n — 循环切换当前会话的回合（更旧 / 更新）。
* l — 打开 DSH-Sessions 缓冲区。
* q — 退出窗口并 bury 缓冲区。

创建时，DSH-View 缓冲区通常跟随最新回合，因此随着更多回复到达，缓冲区会自动更新。
使用 M-p 回溯较旧的回合会暂停跟随；
使用 M-n 循环回到最新回合会自动恢复跟随。
要自定义此行为，请更改 dsh-bridge-view-follow-at-newest。

如果安装了 Markdown 模式，且 dsh-bridge-view-gfm 非 nil，
回复将按 GitHub 风格 Markdown 进行字体锁定（分隔线使用
GFM 水平线语法，因此能干净地渲染）。

更改的文件

工具调用成功更改了文件的回合会以
Changed files: 页脚结尾，这是一个普通列表，每个文件一个可点击条目。
点击路径（或将光标放在其上按 RET）会访问该文件，
相对于会话目录解析。目前没有记录差异或审查视图：
之前的 hunk 查看器已被移除，等待重新设计（见 PLAN.md）。

将 dsh-bridge-view-changed-files 自定义为 nil 可省略页脚。
未产生助手文本的回合完全不会出现在回合列表中，
因此纯粹更改文件的回合没有页脚；回合完成后刷新（g）以获取其文件。

智能体查询和批准请求

如果模型通过 ask_user_question 工具请求额外的用户输入，
该查询会显示在 DSH-View 缓冲区中。在此处输入 a（或在 DSH-Sessions 缓冲区中将光标放在会话上输入 a）以打开用于处理该查询的缓冲区。

在此缓冲区中，用 RET 标记你选择的选项。你也可以导航到问题块并按所需选项的数字键，或输入 c 并通过 minibuffer 编写自由形式的回答。要提交答案，请输入 C-c C-c。或者，输入 C-c C-k 拒绝查询，取消工具调用。

某些智能体工具在行动前要求明确批准；例如，
danger-full-access 在允许沙箱升级前询问用户。
此类请求会显示在 DSH-View 缓冲区中；输入相同的 a 键
要查看请求的详细信息并做出决定。一个会话不能同时等待查询和审批，因此待处理的查询优先；否则 a 会显示审批。详细信息（工具、请求者的原因以及工具调用的参数）会显示在帮助窗口中，同时 minibuffer 会提示：输入 y 允许该操作一次，输入 n 拒绝它，或输入 c 取消请求（发起请求的工具调用随后会失败）。退出提示（例如使用 C-g）会使审批保持待处理状态；再次运行 a 可重新读取详细信息并做出决定。

两种等待会同时提供给 Emacs，并且当 Web UI 打开时，也会提供给其自己的面板：无论哪一方先应答，都会了结该请求并关闭另一方呈现。若要让 Emacs 仅显示审批而将决定留给 Web UI，请将 dsh-bridge-approval-answer 自定义为 notify-only：此时 a 会以只读方式显示详细信息，并且通知连接会告知宿主不要向 Emacs 提供审批以供决定。有关信任边界，请参见下文“权限、身份验证和失败边界”。

DSH-Prompt 缓冲区

此缓冲区用于为 DSH 会话撰写提示或回复。它可以通过瞬态菜单、DSH-View 缓冲区或 DSH-Sessions 缓冲区中的 r 打开。如果会话正在等待提示，你也可以从 DSH-Sessions 中使用 RET 打开它。

受影响的会话目标取决于缓冲区的调用方式；例如，从 DSH-View 缓冲区中按 r 会为同一会话打开一个提示。

以下命令可从 DSH-Prompt 缓冲区中使用：

* C-c C-c — 将缓冲区作为提示发送，并弹出到 DSH-View 缓冲区以查看回复。
* C-c C-d — 将缓冲区作为草稿推送到 DSH 撰写器。
* C-c C-a — 将文件附加到提示（见下文）。
* C-c C-m — 设置模型和推理强度。
* C-c C-s — 将缓冲区重新绑定到另一个会话。
* C-c C-k — 如果会话正在运行则停止它，否则清空提示。
* C-c C-f — 为此会话打开 DSH-View 缓冲区。
* C-c C-l — 打开 DSH-Sessions 缓冲区。
* M-p/M-n — 浏览会话的提示历史。

如果在会话运行时调用 C-c C-c，它会询问如何发送提示：排队以在当前回合之后运行、引导正在运行的回合，或取消。自定义 dsh-bridge-send-while-running 可更改此行为。要无条件引导，请输入 C-u C-c C-c。

在使用 M-p/M-n 浏览提示历史时，你可以编辑较早的提示。这会阻止进一步的历史导航；要恢复，你必须先发送提示，或使用 M-x revert-buffer 还原。

当安装了 Markdown 模式时，此缓冲区派生自它，因此大多数 markdown 编辑命令也可用。

附件

C-c C-a 命令会附加一个文件，以便随提示一起发送。与类似的 Message 模式命令一样，它会在 minibuffer 中提示输入文件，并向提示缓冲区插入一行标签：

如果你改变主意，不再想附加该文件，只需在发送提示前删除标签行即可。

在 Emacs 的其他位置，你也可以直接运行此命令（M-x
dsh-bridge-attach-file）来打开一个带有指定附件的 DSH-Prompt 缓冲区，或者运行 M-x dsh-bridge-attach-buffer-file 来打开一个以当前缓冲区的文件作为附件的提示。

计划模式和目标

计划模式和会话目标由以下命令提供：

* M-x dsh-bridge-toggle-plan-mode — 切换计划模式。带有数字前缀参数时，若为正数则启用，否则禁用。
* M-x dsh-bridge-set-goal — 设置或编辑目标。带有前缀参数时，还会读取目标轮次上限。
* M-x dsh-bridge-toggle-goal — 暂停或恢复目标。
* M-x dsh-bridge-pause-goal — 暂停活动目标。
* M-x dsh-bridge-resume-goal — 恢复已暂停或受阻的目标。
* M-x dsh-bridge-clear-goal — 清除当前目标。

这些命令也可在菜单栏中使用。

从 DSH 向 Emacs 发送文本

DSH 插件添加了一个“Send to Emacs”按钮，可让你将特定的助手消息推送到 Emacs。这会自动弹出 Emacs 中的 DSH-View 缓冲区。你可以在 DSH-View 缓冲区中使用 i（或运行 M-x dsh-bridge-receive）来拉取最后推送的消息。

开发测试

运行 make test 会启动标准单元测试套件（插件使用 Vitest，elisp 使用 ERT）。运行 make integration-test 会执行一套集成测试，使用模拟 LLM 在实时 DeepSeek Harness 主机上启动插件；参见 integration/README.md。它不属于 make test 的一部分（后者保持快速）；在提交主机插件更改前以及发布前运行它。

权限、身份验证和故障边界

该桥接监听 DSH Web 服务器的回环接口，并且从不联系第三方服务。每个路由都由一个共享的 bearer 令牌进行门控，该令牌在首次使用时生成，并以仅所有者权限存储在 ~/.dsh/dsh-bridge-token。Emacs 直接读取该文件，浏览器插件则从一条仅限于回环对等方和同源页面的路由获取它。请求正文上限为 1 MiB，等待 Emacs 的消息存放在一个有界发件箱中，该发件箱会驱逐最旧的条目（并发出警告）。

请注意，任何能够访问该令牌的第三方都可以执行此 Emacs 包所能做的一切：发送提示、读取会话日志（包括已持久化的日志）、回答模型的问题和审批请求、中断正在运行的轮次、指定主机要附加的文件等。但是，通过此路由提交的审批不会授予 Web UI 无法授予的任何权限。

许可证

本软件根据 GNU 通用公共许可证第 3 版或更高版本的条款发布。参见 COPYING。