Skip to content

dsh-acp-door

Verified

dsh-acp-door · v0.7.2 · MIT · Web UI

连接本机 DSH 与 VS Code 等外部程序,共用模型、工具、记忆和会话。支持历史查看、权限切换及已注册插件的能力调用。

Install

dsh plugin add dsh-acp-door

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

dsh-acp-door

连接本机 DSH 与 VS Code 等外部程序,共用模型、工具、记忆和会话。支持历史查看、权限切换及已注册插件的能力调用。

存在 DSH workspaceRegistry 时,历史列表默认仅包含工作区已登记或已置顶的未归档会话,archived: true 只读取已归档会话,unlisted: true 读取尚未登记的未归档持久记录;过滤先于分页与标题读取。新建和接回的 ACP 会话会登记到相应工作区。归档、恢复调用同一注册表的 archiveSession、unarchiveSession,不直接修改归档文件,也不隐式停止运行中的任务。归档与成员范围变更以 dsh-door/history-changed 通知所有已连接面板,通知只含列表版本,不含会话正文。缺少该服务时明确报告归档状态未知,并禁用写入。

历史通过当前内核的公开 sessionQuery 服务读取,不直接解析持久文件。客户端通过 $/cancelRequest(id)或 ACP 的 $/cancel_request(requestId)取消查询,连接断开也会停止等待结果;内核拥有实际持久读取。每个连接最多同时等待 8 个历史请求。

需要已安装并运行的 DeepSeek Harness,以及支持 ACP 的外部客户端。接入点仅供本机使用;安装后需重启对应的 DSH 内核。

dsh-door/images/capabilities({sessionId})检查当前连接所属会话的模型是否声明图片输入、原生附件服务是否可用,以及初始化连接时是否启用了图片。当前验证范围为 ACP 0.2.2-rc.1,发送仍使用标准 ACP 图片内容块。模型切换后重新查询;原连接禁用图片时需要重连。相关工具清单来自当前 Agent 可见的注册名称,不能据此保证外部搜图或图片生成服务可用。

成功读取历史后,图片以不含原生附件标识的临时引用返回。客户端通过 dsh-door/images/read({token})读取该连接已取得的图片引用;未知或其他连接的引用被拒绝。历史图片按格式、内容摘要和大小校验,并受并发、超时和取消限制。

在同一内核启用 dsh-meme 和 Web 服务时,客户端可通过 dsh-door/media/catalog、dsh-door/media/read 读取表情图库及图片,两个方法均指定 provider: "dsh-meme",图片读取另传图库返回的 id。状态中的 capabilities.media 表示适配接口可用;插件是否已启用以图库请求结果为准。适配器只访问该内核回环地址上的固定插件路由,不读取图库数据库,不执行图库管理操作;每项内容限制为 8 MiB,并校验图片类型及文件签名。当前按 dsh-meme 0.1.52 的公开路由格式验证。

IDE Bridge 提供同一连接上的能力调用:插件主动注册能力、本机自动鉴权、可恢复运行与取消。 协议规范见仓库的 docs/bridge-v1.md。现有 ACP 会话、流式输出、历史和权限方法继续兼容。

English

dsh-acp-door opens an extra ACP (Agent Client Protocol) transport on a running DeepSeek Harness kernel — loopback only (127.0.0.1), for use on your own machine. ACP chat retains its local transport; IDE Bridge calls use a per-user endpoint credential and client lease. External clients such as the DSH Panel VS Code extension can then drive the very same kernel you already have open: same config, same memory, same tools, same session records.

ACP normally speaks over stdio, which can only be attached at process start; this plugin instead mounts one ACP bridge per TCP connection on top of the live kernel, and exposes a few bypass methods the core does not have over ACP (session listing, permission presets).

Install:

dsh plugin --profile <your-profile> add dsh-acp-door

Restart the kernel (or the desktop app) afterwards — plugins are loaded at startup.

For a compatible update of an installed copy, run:

dsh plugin --profile <your-profile> update dsh-acp-door

Restart the kernel afterwards.

Compatibility: DSH 0.2.2-rc.1 only. Current candidate acceptance is recorded in the compatibility matrix.

安装

dsh plugin --profile <档名> add dsh-acp-door

安装完成后需要重启内核(或重启桌面端)才会生效:ACP 接入点插件(dsh-acp-door)在内核启动时加载。

该插件装入哪个档,外部程序即可连接该档的 DSH —— 桌面端所用的档由桌面端自身管理 (运行时命令行无法修改),因此通常装入用户自己的档。

若 VS Code 面板需要在桌面端未运行时自行启动 DSH,应使用可由命令行启动的网页配置集, 而不是 desktop 配置集。例如:

dsh --profile vscode-panel --from-default-profile web --dump-config
dsh plugin --profile vscode-panel add dsh-acp-door

安装后重启该配置集的内核。新会话默认使用该配置集中 DSH 当前选择的默认模型;无需把 服务商或模型名再复制到本插件配置中。若该配置集还没有选择模型,先在 DSH 的模型设置中完成选择。 不同电脑分别安装各自的 DSH 与本插件;接入点固定在 127.0.0.1,不支持远程设备连接、端口转发或隧道。

安装 VS Code 配套扩展

在提供 Connection 与界面 Slots 接口的本机 DSH 桌面端或网页版中,首次加载接入点后会检查默认 VS Code 配置集。 尚未安装时显示“VS Code 配套扩展”提示。选择编辑器和已有配置集,点击“安装配套扩展”后, 插件通过 VS Code 官方命令下载 Elk-ydy.dsh-acp-panel,并重新查询所选配置集,确认存在后才显示成功。 已经安装时不重复安装或强制更新。安装失败可重试,也可使用提示中的扩展市场入口或手动命令。

点击“稍后安装”会保存偏好,不再自动弹出。之后可从 DSH 设置 → VS Code 配套扩展继续安装或重新检测。 该偏好保存在当前 DSH_HOME 的 plugins/dsh-acp-door/companion.json 中,与插件版本无关。 不会在包管理器的安装脚本中执行安装;安装动作仅由用户点击触发。

编辑器检测覆盖常见安装目录、Windows 安装记录及 PATH 中的 VS Code / Insiders;Windows 便携版读取自身数据目录。 未检测到的自定义安装可以直接在 VS Code 扩展视图搜索 DSH ACP Panel。 安装过程中不创建 VS Code 配置集。远程访问的 DSH 页面不提供此功能;无界面或缺少上述接口的旧 DSH 继续使用原有 ACP 接入点,可按以下命令单独安装扩展:

code --install-extension Elk-ydy.dsh-acp-panel

更新

常规兼容更新使用以下命令:

dsh plugin --profile <档名> update dsh-acp-door

该命令按当前配置集中声明的版本范围更新。更新完成后重启对应内核(桌面端使用的配置集则重启桌面端)。 若版本说明标为不兼容更新,按该版本的安装说明处理,避免在未阅读变更记录的情况下跨越大版本。

配置项(写入档的 cordis.patch.yml,见本包自带的同名文件):

键 默认 说明
host 127.0.0.1 固定监听地址。其它值会被忽略,接入点不会暴露到局域网。
port 47821 监听端口。也可用环境变量 DSH_ACP_DOOR_PORT 覆盖(0.0.11 起)。
provider / model 留空,跟随 DSH 可选的成对覆盖;必须同时填写才会固定新会话的初始模型。
preset standard 新会话挂载的 agent preset 套件。

解决的问题

ACP 默认使用标准输入输出:该通道只能在进程启动时接入。 而 DSH Desktop 已处于运行状态时,外部程序无法接入该通道。

DSH 自带的 ACP 插件支持注入传输层(其源码中有对应实现):

const stream = config.stream ?? ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));

因此该插件仅执行一项操作:在每个 TCP 连接上挂载一份 ACP 桥。

DSH Desktop(运行中)
├── 内核:agents / llm / sessions / 工具 / 记忆 / 技能      ← 只有一份
├── 网页界面                                     (原有)
└── 该插件:127.0.0.1:47821  ── 每个连接 = 一份 ACP 桥      (新增)

会话预设补挂的必要性

这是该插件除监听端口之外唯一执行的实际操作,也是最易出错的环节,因此单独说明。

桌面端与网页端架构停用了宿主层的全部工具 —— dsh-web-app 的补丁中:

- id: tool-bash
  disabled: true
- id: tool-pwsh
  disabled: true
- id: tool-jobs
  disabled: true
- id: tool-fs
  disabled: true
- id: tool-fs-search
  disabled: true

它的注释说明了理由:"the Web surface disables them here and lets each session mount a preset instead" —— 即工具改为 每个会话按 agent preset 挂载一套。

而 @deepseek-ai/dsh-acp 创建 agent 时只传入工作目录、从不指定预设 (dsh-acp/lib/index.js 的 AcpSession.create 中为 meta: { cwd })。 两者结合后,经 ACP 建立的会话缺少工具来源:宿主层未提供工具,预设层也未指定预设 —— 即一个无法调用工具的 agent(该 agent 会声明「我来读一下这个文件」,随后无法执行任何操作)。

内核自身的报错文案指明正确做法:

(join through AgentPresets.mount() or composeFrom() in the agent factory setup)

因此该插件监听 agent/created,使用公开的 agentPresets 补上这一步。新建会话与 恢复的会话使用两个不同的入口 —— 该结论来自实测,并非推测:

情况 所用入口 原因
新建的会话 select(agent, id) 该入口重新组装 agent 的作用域,并将本次选择追加进会话事件日志(agent-preset/selected)。
恢复的会话(断线重连 / 打开历史会话) mount(agent.ctx, id) 内核按「是否执行过回合」为 select 设置了锁(agent-preset/locked,属设计行为)。恢复时 agent 的作用域为重新组装的结果,缺少该调用时作用域为空。mount 是工厂期使用的入口,只负责组装,不检查该锁。

恢复会话与工具挂载

恢复的会话需要重新挂载工具预设。select() 适用于新建会话;恢复时遇到预设锁,改用 mount(agent.ctx, id),确保恢复后的 Agent 具有该预设提供的工具。

两项必须注意的约束(均已实测)

  1. agentPresets 必须写成声明式依赖。 cordis 的服务代理对未声明的属性 直接抛错(cannot get property "…" without inject)。该异常发生在内核 创建 agent 的同步流程中:或打断 session/new,或被 async 捕获, 使该插件静默失败。因此该服务写入 inject,缺少该服务的 profile 不会启动这个插件。 同一结论也适用于 mount():该入口需要 agent 的作用域上下文(agent.ctx), 传入错误对象会抛 refusing to compose an unscoped context。

  2. 存在一处竞态,必须由入站闸阻塞。 内核派发 agent/created 时不等待 监听器返回的 promise,因此「补挂预设」与「客户端发送第一个 prompt」并行执行。 客户端请求先到达时,模型尚无完整工具清单。因此传输层对该会话的 session/prompt 设置入站闸,等待预设挂载完成再发送。

预设恢复来源

接入点在内核进程内保存 sessionId → preset 映射,客户端也会在 session/resume 的 _meta 中指定所需预设。恢复时使用这些明确的预设信息补挂工具,不读取旧版会话文件。

配置

字段 默认 说明
host 127.0.0.1 固定监听地址。其它值会被忽略,接入点不会暴露到局域网。
port 47821 监听端口;传 0 由系统分配空闲端口。
provider — 可选。与 model 同时填写时,固定新会话的初始模型服务商。
model — 可选。与 provider 同时填写时,固定新会话的初始模型名。
preset standard 新会话挂载的 agent preset:standard(标准)/ ptc / cordis(创造)/ minimal(极简)。
diagLog 关 诊断日志文件路径;也可用环境变量 DSH_ACP_DOOR_DIAG。用于排查时序问题,未配置时不写任何文件。

初始模型的选择顺序

  1. 插件配置中同时填写了 provider 与 model:使用这组显式覆盖。
  2. 未完整填写:读取 DSH 的 agentDefaultModel.currentSelection(),即该配置集当前选择的默认模型。
  3. 默认模型服务尚未就绪且也没有完整显式配置:状态接口报告“模型未就绪”,新版 VS Code 面板会在 建会话前提示先选择模型。其它客户端也可调用 dsh-door/status 自检。

只填写 provider 或 model 其中一项不会与 DSH 的值拼接;这组不完整配置会被忽略并记录诊断。 DSH 冷启动时,插件会先等待用户设置加载完成再开放端口,避免短暂读取到基础默认模型。

DSH 内核兼容性

DSH 历史会话 权限预设
0.2.2-rc.1 公开 sessionQuery 服务 catalog/current/resolve/set

接入点只接受该精确 ACP 版本;历史持久格式和迁移均由内核负责。状态中的 protocolVersion 与 runtime.acpVersion 分别报告接入协议及实际 ACP 包版本;历史服务不可用时报告 history: false。

dsh-door/text/generate 使用所属会话的当前模型直接生成文本,发送空工具集合,不进入 Agent 工具调度;工具响应、错误或截断终态均拒绝,支持请求取消。

版本变更

见 CHANGELOG.md。

旁路方法:ACP 未提供的能力

该插件除转发 ACP 之外,还自行应答少量带 dsh-door/… 前缀的请求帧(不转发给内核, 就地回复),因为 ACP 协议中不包含对应能力:

方法 该插件所需的 params 该插件的回复 起始版本
dsh-door/status {} { version, model: {ready, source, provider?, model?}, capabilities } 0.0.14
dsh-door/sessions/list 可选 cwd、limit、offset、query;未发布版增加 archived、unlisted { skipped, sessions, total, offset, nextOffset?, archiveStateKnown?, workspaceStateKnown?, archiveSupported?, archiveRevision? } 0.0.8(分页与搜索从 0.3.0 起)
dsh-door/sessions/get { id } { card, entries, truncated } 0.0.8
dsh-door/sessions/state {} { archiveStateKnown, archiveSupported, archiveRevision? } 未发布
dsh-door/sessions/archive { id, archived: boolean } { id, archived, archiveStateKnown, archiveSupported, archiveRevision } 未发布
dsh-door/permission/get { id } { currentValue, options: [{value, name?, description?}], defaultPreset? } 0.0.12
dsh-door/permission/set { id, value } 同 permission/get(修改之后回读的真实状态) 0.0.12

权限相关的两个方法无法经由 ACP 提供:@deepseek-ai/dsh-acp 仅将模型与推理强度 暴露为 session/set_config_option,其 README 写明该实现「刻意不提供 DSH 专用呈现数据 与交互式 UI 功能」。权限选择器正属于该类别。

实现上需注意两点:

  1. permissionPresets 是可选依赖 —— 使用 ctx.inject(['permissionPresets'], …) 而不写入 export const inject。若写死,未挂载该服务的档(例如极简的自建档) 会导致整个插件无法加载,而非仅权限这一项不可用。
  2. 切换后回读再回复(settledPermission),不采用乐观更新:若某项设置被其它 机制阻塞,客户端显示的是真实状态。

历史方法统一通过当前内核的 sessionQuery 读取,不提供直接文件读取退路。

从源码目录或 tgz 安装

在目标 profile 中安装该包,两种来源均可,但需明确两者的区别:

# A) 指向源码目录:开发用,安装后即可使用(pnpm 会将其复制进 profile)
dsh plugin --profile <profile> add "file:<本目录>"

# B) 使用 npm pack 的 tgz:接近用户实际获取的产物
cd <本目录>; npm pack
dsh plugin --profile <profile> add "file:<本目录>\dsh-acp-door-<版本>.tgz"

不应使用 link:。 该方式会建立真实符号链接,Node 解析依赖时按真实路径向上查找, 因此 import '@deepseek-ai/dsh-acp' 无法解析(该包不在源码树中,而在 profile/DSH 安装目录中), 导致该插件无法启动。删除该链接时,包管理器也可能对源目录执行清理;使用独立的发行归档可以明确安装与源码的边界。

修改源码后必须重新执行一次 add。 file: 是拷贝而非链接,且 pnpm 存在缓存, 源码变更后有时直接报告 added 0(内容未替换)。packages/vscode-extension/test/helpers/door.js 的 syncDoor() 在每次运行测试前逐字节比对源码与已安装的那份,不一致时自动重装 —— 避免测试实际验证旧代码。

然后在该 profile 的用户自定义层 cordis.patch.yml 里插入一行:

- insert:
    - id: acp-door
      name: dsh-acp-door
      config:
        preset: standard

上例默认跟随该配置集中 DSH 当前选择的模型。只有确实需要让此接入点长期固定到另一个模型时, 才在 config 中同时增加 provider 与 model。

或者将该包名 dsh-acp-door 加入该 profile package.json 的 dsh.profile.bundles 数组(本包自带的 cordis.patch.yml 会自动生效)。

卸载

  1. 删除上述 insert 记录(或将 dsh-acp-door 从 bundles 中移除);
  2. dsh plugin --profile <profile> remove dsh-acp-door。

已知限制

  • 普通 ACP 传输没有鉴权:本机程序可连接该端口;IDE Bridge 的能力调用另有本机凭据、客户端租约和风险授权。接入点固定监听 127.0.0.1,不支持通过改地址、端口转发或隧道提供给其它设备。
  • 硬依赖 agentPresets:不提供预设机制的 profile(例如纯 base 的 acp profile) 不会加载该插件。该限制属刻意设计 —— 见上文第 1 项约束。
  • 需重启 DSH 后才会加载(profile 的 patchReload 为 live 时,配置改动可以热生效, 但新装一个包仍需重启)。
  • 依赖三个内部接缝:@deepseek-ai/dsh-acp 的 config.stream、 agentPresets.select() 的签名、以及 agent/created 事件。 它们在 DSH 升级中若变动,该插件需要同步调整。
  • 仅能挂载预设,不能中途切换:内核只允许「尚未产出任何内容」的会话切换预设。