dsh-acp-door
Verifieddsh-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 具有该预设提供的工具。
两项必须注意的约束(均已实测)
agentPresets必须写成声明式依赖。 cordis 的服务代理对未声明的属性 直接抛错(cannot get property "…" without inject)。该异常发生在内核 创建 agent 的同步流程中:或打断session/new,或被 async 捕获, 使该插件静默失败。因此该服务写入inject,缺少该服务的 profile 不会启动这个插件。 同一结论也适用于mount():该入口需要 agent 的作用域上下文(agent.ctx), 传入错误对象会抛refusing to compose an unscoped context。存在一处竞态,必须由入站闸阻塞。 内核派发
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。用于排查时序问题,未配置时不写任何文件。 |
初始模型的选择顺序
- 插件配置中同时填写了
provider与model:使用这组显式覆盖。 - 未完整填写:读取 DSH 的
agentDefaultModel.currentSelection(),即该配置集当前选择的默认模型。 - 默认模型服务尚未就绪且也没有完整显式配置:状态接口报告“模型未就绪”,新版 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 功能」。权限选择器正属于该类别。
实现上需注意两点:
permissionPresets是可选依赖 —— 使用ctx.inject(['permissionPresets'], …)而不写入export const inject。若写死,未挂载该服务的档(例如极简的自建档) 会导致整个插件无法加载,而非仅权限这一项不可用。- 切换后回读再回复(
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 会自动生效)。
卸载
- 删除上述
insert记录(或将dsh-acp-door从bundles中移除); dsh plugin --profile <profile> remove dsh-acp-door。
已知限制
- 普通 ACP 传输没有鉴权:本机程序可连接该端口;IDE Bridge 的能力调用另有本机凭据、客户端租约和风险授权。接入点固定监听
127.0.0.1,不支持通过改地址、端口转发或隧道提供给其它设备。 - 硬依赖
agentPresets:不提供预设机制的 profile(例如纯 base 的acpprofile) 不会加载该插件。该限制属刻意设计 —— 见上文第 1 项约束。 - 需重启 DSH 后才会加载(profile 的
patchReload为live时,配置改动可以热生效, 但新装一个包仍需重启)。 - 依赖三个内部接缝:
@deepseek-ai/dsh-acp的config.stream、agentPresets.select()的签名、以及agent/created事件。 它们在 DSH 升级中若变动,该插件需要同步调整。 - 仅能挂载预设,不能中途切换:内核只允许「尚未产出任何内容」的会话切换预设。