ACP 增强桥接grunmin/dsh-acp-enhanced

| English

dsh-acp-enhanced

一个为 DeepSeek Harness (dsh) 打造的增强版 Agent Client Protocol (ACP) 服务器，专为 Zed 等 ACP 编辑器构建。它是官方 @deepseek-ai/dsh-acp 桥接器的直接替代品：官方桥接器仅流式传输纯文本，而本桥接器通过 ACP 协议暴露 Web GUI 的能力——流式传输、遥测、模型/权限控制、会话管理、MCP。

功能特性

输出与遥测

- 块 + 推理流式传输：文本块和模型的思考过程实时到达
（agent_message_chunk / agent_thought_chunk）；被取消/重试的尝试绝不会泄漏
残缺输出。在 acp-enhanced 行上设置 streamDeltas: true 可启用 token 级
流式传输——模型书写时回复即渲染，以 75 毫秒定时器合并；代价是
块中途重试时无法再隐藏其被放弃的部分文本，因此会有一个可见的
_[stream interrupted — retrying]_ 标记分隔接缝（默认关闭）
- 完整遥测：上下文用量环，以及缓存命中率 / TPS / 输入-输出-推理
token 数 / 工具耗时 / 轮次计数（usage_update._meta 携带完整明细）
- 图像支持（多模态）：当 dsh 组合挂载了附件存储
（dsh 0.1.1-rc.2+ 搭配 dsh-attachment-local，即 dsh-base 中的默认配置）时，
会声明 promptCapabilities.image，粘贴/上传的图像会被摄取到 harness 的持久化附件
存储中——具备视觉能力的模型（例如 deepseek-v4-flash-vision-exp）可原生读取它们，
按传输顺序与周围文本一同处理。较旧的栈（无附件存储）会自动
降级：不声明图像能力，图像提示会以明确的错误被拒绝。

模型与权限

- 模型切换：实时 provider/model 目录下拉菜单（ACP 分组选择传输格式）
- 推理强度：reasoning_effort 下拉菜单——仅当所路由的模型暴露
可选强度时显示；每个模型会记住其上次使用的强度（按配置文件持久化），
因此切换回来时会恢复该强度，而首次使用的模型会回退到其自身默认值——或
其首个提供的强度——而不是空的“未知”选项
- 权限预设：只读 / 工作区写入 / 完全访问会话模式
- 审批：每次工具调用时提供原生的允许一次 / 拒绝一次提示
- Agent 预设：来自 dsh agent-presets 名册的按会话面向模型的组合（工具 + 提示词部分）。
standard 是完整的编码 agent（默认），
minimal（极简模式）是仅含 shell + 文件编辑器的裸配置，没有子 agent/web/todo/plan
工具——宿主层的任何内容都不会泄漏到极简 agent 中；code 和
cordis 也一同提供，你在 ~/.dsh/.agent-presets 下的自定义预设也会出现。
可通过 agent_preset 配置选项、/preset 命令，或
DSH_ACP_PRESET 环境变量（按会话的默认值）；仅当会话仍为空（尚未运行任何轮次）时才允许切换，因此历史记录绝不会跨越两套工具集。

Zed 深度集成

- 工具卡片：折叠标题中显示一行摘要——Read 、模型为 shell 命令自行给出的意图行（description，Codex 风格——确切命令只需点击一下即可查看）、Search: 、Fetch:  等。
卡片正文遵循 ACP 最佳实践：文件编辑渲染为真正的差异，bash/pwsh 命令渲染为真正的终端卡片（codex-acp 线格式：命令行 + 输出 + 终端面板内的退出状态胶囊——不再是原始 JSON 卡片），其他执行器渲染为语法高亮的代码块，被触及的文件渲染为可点击的位置，点击即可打开文件——同时 rawInput / rawOutput 只需点击一下即可查看以保持透明，另有按类型区分的图标以及恰当的进行中 → 已完成/失败状态生命周期
- Zed 文件与终端：zed_read_text_file / zed_write_text_file / zed_terminal
将文件编辑放入 Zed 的“已编辑文件”区域（差异 + 接受/拒绝），并将命令放入真正的 Zed 终端
- 原生表单问题：ask_user_question → elicitation/create 表单，点击一个选项——或在所有选项都不合适时输入自定义答案：选项连同其描述一起渲染，每个由选项支持的问题都有一个自由文本“自定义答案”字段，自定义答案会替换单选选择 / 伴随多选（与 dsh 原生问题卡片语义相同）
- 计划面板：计划模式切换 → Zed 中的“规划”状态栏

会话

- 恢复与归档：session/load 恢复过去的线程（完整重放）；
session/list / session/delete 管理线程归档（带标题，按最后活动时间排序）；实时标题更新
- 多根工作区：声明了 sessionCapabilities.additionalDirectories，因此 Zed 不再显示“此 agent 当前不支持多根工作区”，而是在 session/new / session/load 时传入每个工作区根目录。所有根目录都会在系统提示中向模型描述，并在 session/list 中报告；沙箱将主 cwd 保留为其唯一可写根目录（参见已知限制）

命令

- 斜杠命令：输入 / 会显示命令列表（available_commands_update）：
/status 显示路由和遥测，/model 列出或切换模型，/preset
列出或切换 agent 预设（列表渲染为等宽代码块——一目了然），其他所有命令（/compact /goal /permission /plan……）直接通过 harness 命令注册表运行——全部无需模型轮次即可执行。每个用户可调用的技能也会作为命令声明，因此 /ask-matt、/code-review、
/tdd…… 会到达桥接层，而不是被编辑器拒绝，并且该技能的指令会被注入到消息中（dsh-tool-skill 风格的用户调用）。
斜杠行旁边粘贴的图片会作为命令附件随行（例如 /goal 目标的参考截图），
与 Web 编辑器提交它们的方式相同

MCP

- MCP 服务器：session/new 的 mcpServers 可挂载任意 MCP 服务器（stdio + 可流式
HTTP）；工具以 mcp____ 形式加入；服务器故障绝不会导致会话中断

预览

在 Zed 的 AI Agent 面板中选择 dsh-acp-enhanced 后：

快速开始

此包遵循官方 dsh 插件约定（它声明了 dsh.bundle），因此安装方式与任何官方 bundle 相同：
一条命令——自动初始化 profile、安装包、追加 bundle 层；无需编写 profile YAML。

安装（2 步）

第 1 步——安装（从 npm registry 安装；无需检出源码）：

dsh plugin --profile acp-enhanced add dsh-acp-enhanced

在修改代码时，请改用 link: 指向本地检出（实时编辑）：
dsh plugin --profile acp-enhanced add "link:/absolute/path/to/dsh-acp-enhanced"

第 2 步——在 Zed 中注册（位于 ~/.config/zed/settings.json 的 agent_servers 下；
Zed 启动 agent 时使用最小化的 PATH，因此请使用随附的启动器
scripts/dsh-acp-zed.sh，它会自行定位 node/dsh）

启动器随包提供。 其绝对路径取决于你在第 1 步中的安装方式：
- npm 安装（默认）：$HOME/.dsh/profiles/acp-enhanced/node_modules/dsh-acp-enhanced/scripts/dsh-acp-zed.sh——将 $HOME 替换为你的主目录（例如 /Users/you）；Zed 不会展开 ~ 或环境变量，因此请写出完整的字面路径。
- link: 开发安装：/scripts/dsh-acp-zed.sh。

最常见：DeepSeek 官方 API（默认路由）

{
// ...your existing settings...
"agent_servers": {
"dsh-acp-enhanced": {
"type": "custom",
"command": "/bin/bash",
"args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
"env": {
"DSH_ACP_PROVIDER": "deepseek-official",  // the official provider id
"DSH_ACP_MODEL": "deepseek-v4-flash",     // the official model id
"DSH_ACP_PRESET": "standard"              // optional: agent preset id (minimal / standard / code / cordis / yours)
}
}
}
}

这两个环境变量都与随附补丁的默认值匹配，因此它们完全可以省略——
写出来只是让路由更明确。DSH_ACP_PRESET 在 roster 侧默认为 standard；
当你希望每个新会话都以特定模式启动时再设置它。
API 密钥不必存放在 Zed 中：
将其存储在 ~/.dsh/.credentials.yaml（DEEPSEEK_API_KEY）中，dsh 凭据
服务会解析它；启动器也会回退到正在运行的 dsh web 进程的密钥。

调试卡住的回合（是模型请求还是工具的问题？）：

"env": {jsonc
// ...现有变量...
"ACP_LOG": "/Users/you/.dsh/dsh-acp-enhanced.trace.jsonl"  // 仅追加的 JSONL 事件追踪
}

每一行是一个会话事件，带有挂钟时间 time（毫秒纪元）；一个看似
卡住的回合事后可以归因：模型请求停滞表现为
step/start 与第一个 assistant/chunk 之间的长时间间隔，而工具执行停滞表现为
tool/call 与 tool/result 之间的长时间间隔（结果行带有 elapsedMs）。
prompt/settled 行覆盖完整的用户消息往返（stopReason + elapsed）。

可选：固定面板的默认配置选项（全部仍可在面板中更改）：
jsonc
"dsh-acp-enhanced": {
// ...上面的 type/command/args/env...
"default_config_options": {
"model": "deepseek-official/deepseek-v4-flash",
"agent_preset": "standard",
"plan_mode": false,
"reasoning_effort": "high"
},
"favorite_config_option_values": {
"model": ["deepseek-official/deepseek-v4-flash", "deepseek-official/deepseek-v4-pro"]
}
}

扩展：通过 OpenAI-Responses 网关路由（例如公司模型网关）

安装路径相同；只需将环境变量值改为网关所暴露的 provider/model
以及它所需的密钥环境变量：
jsonc
"dsh-acp-enhanced": {
"type": "custom",
"command": "/bin/bash",
"args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
"env": {
"DSH_ACP_PROVIDER": "",  // 网关暴露的 provider id
"DSH_ACP_MODEL": "",         // 网关暴露的 model id
"": ""                      // 网关读取的密钥环境变量
}
}

也可以省略，而将密钥存储在
~/.dsh/.credentials.yaml 中。

Zed 会热重载设置。打开 AI Agent 面板（Cmd+Shift+A）→ 在 agent 选择器中
选择 dsh-acp-enhanced → 发送你的第一条消息：回复会实时流式传输，
状态栏显示上下文使用情况，面板暴露 Model / Permission preset
/ Plan mode 选项以及三种模式，线程归档会列出并恢复过去的
会话。

本地验证（无需 Zed）：
sh
node scripts/acp-client.mjs                    # 官方默认路由，无环境变量；预期 ALL CHECKS PASSED
DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # 仅用于自定义路由

Web 搜索

该桥接不附带任何搜索提供程序，也不对你使用哪一个表明立场：面向
模型的 web_search 工具依托于 web 接缝的 searchProvider，因此将任意
ctx.web 提供程序挂载到 profile 中即可——通过
dsh plugin --profile acp-enhanced add  添加带有 dsh.bundle 的包，或通过你的用户层
insert 行添加普通包（见下文）。你的 dsh 部署中存在哪个提供程序是 profile
层面的事，而非桥接层面的事。

管理 profile 的插件

dsh-acp-enhanced 在其自己的 profile 中运行——acp-enhanced，创建于
~/.dsh/profiles/acp-enhanced/ 由上述安装命令创建——与 dsh web 背后的 web profile 完全分离，因此此处的插件变更绝不会影响你的 web 设置。

该 profile 从三个来源组合其插件树，每一层都会修补之前的层：

1. Bundle 层——profile 的 package.json 中的 dsh.profile.bundles：先是模板的 @deepseek-ai/dsh-base，然后是按数组顺序排列的每个声明了 dsh.bundle 的已安装包（如 dsh-acp-enhanced）。
2. 你的用户层——~/.dsh/profiles/acp-enhanced/cordis.patch.yml：按 id 定位的行配置覆盖、disabled: true 行禁用，以及 insert 列表（没有 dsh.bundle 的包——例如手动挂载的自定义 provider——就是这样被挂载的）。
3. 每次运行的覆盖层——dsh --profile acp-enhanced --patch extra.yml。

用以下命令调整集合：
sh
dsh plugin --profile acp-enhanced add      # 安装；带有 dsh.bundle 的包会自动加入层栈
dsh plugin --profile acp-enhanced remove   # 卸载；自动离开层栈
dsh plugin --profile acp-enhanced update [package]  # 更新一个/全部，然后协调
dsh --profile acp-enhanced --dump-config             # 检查组合后的树（含每层来源信息）

dsh plugin 是一个轻量的 pnpm 转发器（在 profile 目录内运行），它在每次运行后根据已安装状态协调 dsh.profile.bundles。有两个值得了解的后果：

- 通过从 bundles 中删除来禁用一个 bundle 不会生效——该包仍然是已安装的依赖，下一次 dsh plugin 运行会把它重新追加回来。要在不卸载的情况下禁用单个行，请在用户层中按其 行 id（而非包名——在 --dump-config 输出中查找 id）定位它：

yaml
- id: mnemon
disabled: true

- 没有 dsh.bundle 的包自身不会加载任何内容——它会作为普通依赖安装（并附带一次性警告），需要你在用户层中自行添加 insert 条目。要更改现有行的配置，请用 - id:  + config: 覆盖它——patch 条目会替换整个行配置，而不会合并。

更改会在下一个进程中生效：Zed 会为每个 agent 线程启动一个新的 dsh --profile acp-enhanced，因此在编辑 profile 后请打开一个新的 agent 线程（或重启 Zed）。

兼容性

一个桥接二进制文件可针对从 0.1.0-rc.6 到 0.1.2-rc.1 的每一代 harness 运行。0.1.2 系列重写了此桥接所消费的三个 API，而桥接在运行时吸收每一代——无需 fork，无需版本标志：

| API | ≤ 0.1.1-rc.2（旧版） | ≥ 0.1.2-alpha.2（投影） | 桥接行为 |
|---|---|---|---|
| 会话的运行中预设 | resolveSessionPreset({header, events}) 导出 | 导出已移除；agentPreset 会话投影 | 自行折叠日志（最后一个 agent-preset/selected 胜出，header 作为回退）——两种情况下语义相同 |
| 预设解析失败 | UnknownPresetError / PresetMountError | RemoteError，代码 agent-preset/ | isPresetClientError：通过 isDSHRemoteError + code 进行 RemoteError 鸭子类型判断，旧式类通过 presetId 进行结构化识别（绝不跨副本使用 instanceof） |
| permissionPresets.current(x) | current(events) | current(session)（经由 permissionState） | currentPermissionMode 每次调用时探测服务实例 |
| 会话事件日志读取 | 同步的 session.events 数组 | session.events 已移除（0.1.2-rc.1）；snapshotEvents() / ownEvents() / eventAt() | sessionEventsOf 在存在时读取 snapshotEvents()，否则读取实时数组 |
| 注册表 execute 签名 | execute(agent, line, signal) | execute(agent, line, images, signal)（images 位于 line 与 signal 之间，0.1.1-rc.1+） | executeRegistryCommand 探测声明的参数个数（Remote 装饰器从不包装该方法） |
| userQuestions 注册 | registerProvider({ask}) | user-questions/request Cordis waterfall（0.1.2-alpha.2+） | 探测服务实例；waterfall 监听器应答桥接方拥有的请求，并通过 next() 委托 |

两条不变式保证了这一点是安全的（与 openma deepseek-harness-acp 适配器独立得出的结论相同）：仅值导入纯辅助函数（createUserMessage、ReasoningEffortId、SessionId、defineTool 等——外部副本在功能上等价），以及服务代际问题通过探测服务实例来回答，因为决定服务代际的是启动中的 CLI——而不是本包的依赖范围。dsh-agent-presets 以命名空间*方式导入：0.1.2-alpha.1 移除了其具名导出，而具名导入会在 ESM 链接时失败。

从干净的工作树中检查两代：
sh
node scripts/compat-check.mjs   # installs 0.1.0-rc.6 + 0.1.2-alpha.2+ sets, imports the bridge from each

开发检出：仓库固定的 CLI，隔离的 home

当启动器从检出目录运行（link: 安装）时，它按以下顺序解析 dsh CLI：

1. $DSH_PATH —— 显式的 dsh 二进制文件，或一个目录，其 node_modules/.bin/dsh 中包含该二进制文件
2. 仓库固定的 CLI —— /node_modules/.bin/dsh（本包的 @deepseek-ai/dsh devDependency，当前为 0.1.2-rc.1）
3. 全局回退 —— PATH 上的 dsh / npx 缓存 / npm 前缀（旧有行为；未执行 pnpm install 的全新克隆会降级到此）

只要 (1) 或 (2) 胜出，配置文件就会在隔离的 home（DSH_ACP_HOME，默认为 ~/.dsh-acp）下启动：dsh 在每次启动时将其整个依赖闭包修复到 $DSH_HOME/profiles/node_modules —— 该目录由该 home 下的每个配置文件共享，其内容会翻转为最后启动的那个 CLI —— 因此第二代 CLI 不得与例如正在运行的 dsh web 共享同一个 home。此路径绝不会触碰默认 home。子环境中由 harness 注入的 DSH_HOME=$HOME/.dsh（dsh 会将其导出到每个
agent/tool 进程）被检测到并被覆盖，不会被遵循——只有指向默认 home 之外的 DSH_HOME 才会被尊重；要强制将固定版本的 CLI 指向默认 home，请有意设置 DSH_ACP_HOME=$HOME/.dsh。

一次性引导隔离 home（使用不带 dsh-mnemon 的 profile——它不支持 0.1.2-alpha harness——加上逐字移植的旧 profile 用户行以及凭据/设置迁移、0.1.2-alpha standard 预设所需的 subagent-model-selection-settings 主机服务，以及被禁用的 DeepSeek 插件包清单报告器）：
sh
scripts/init-acp-home.sh            # 幂等；重复运行绝不会覆盖你的文件

两代 harness 都会将会话持久化到 $DSH_HOME/sessions///session.jsonl.zstd 下，而新一代会读取旧一代的日志（已验证：历史回放和预设折叠可跨代工作）。因此旧线程只需将其会话历史复制到新 home——scripts/init-acp-home.sh 会打印这一行命令（或传入 --copy-sessions）；默认情况下它不复制任何内容，因为默认 home 的目录树也保存着每个 web-profile 会话。

故障排除

| 症状 | 修复 |
|---|---|
| exec: dsh: not found（状态 127） | 使用随附的 dsh-acp-zed.sh 启动器（它会自行定位 node/dsh） |
| no API key for provider route "xxx" | 写入 ~/.dsh/.credentials.yaml，或在 agent_servers 条目上设置 env.DEEPSEEK_API_KEY |
| SyntaxError: ... 'PresetMountError' | 你正在用 0.7.0 之前的 bridge 副本对 0.1.2-alpha 主机运行——请更新此包 |
| modelSelectionSettings requires ... in the Host scope | 一个缺少 subagent-model-selection-settings 行的 0.1.2-alpha 主机——运行 scripts/init-acp-home.sh（或将 insert 行添加到你的用户层，参见脚本） |
| 主机升级后旧线程启动为空 | 会话位于 $DSH_HOME/sessions// 下；将旧 home 的历史复制到隔离 home（scripts/init-acp-home.sh --copy-sessions），新主机便会恢复它们 |
| 无法切换模型 | 保存的 reasoning_effort 默认值（或会话当前 effort）会被带到新模型上。自 0.3.6 起，bridge 会按模型记住最后一次 effort（按 profile 的 JSON）：不支持的被携带 effort 会被该模型记住的 effort 替换，否则使用其自身默认值，再否则使用其首个提供的 effort——绝不会出现“未知”下拉项，也绝不会切换失败。另请检查：是否选中了“幻影 provider”路由——此 bridge 默认会过滤它们（只公布 config.provider 的模型），因此请将 profile 的 provider 指向真实路由 |
| 缺少上下文用量 | 选中了“幻影 provider”路由；此 bridge 默认会过滤它们（只公布 config.provider 的模型）——请将 profile 的 provider 指向真实路由 |
| 需要详细诊断 | ACP_DEBUG=1 dsh --profile acp-enhanced（stderr 生命周期跟踪） |

开发
sh
node scripts/compat-check.mjs         # 跨代链接检查（0.1.0-rc.6 + 0.1.2-alpha.2+ 临时安装）
node scripts/acp-client.mjs           # 端到端冒烟测试（需要 API 密钥）
node scripts/acp-client-tools.mjs     # 客户端工具测试（模拟 Zed 的 fs/terminal/elicitation/plan）
node scripts/acp-mcp-test.mjs         # MCP 挂载测试（无模型调用）
node scripts/acp-smoke-keyless.mjs    # 无密钥启动冒烟测试（CI）
node scripts/acp-resume-test.mjs      # 会话恢复测试
node scripts/codec-image-test.mjs     # 图像编解码器单元测试（无网络，使用假存储）
node scripts/terminal-codec-test.mjs   # 终端卡片编解码器单元测试（无网络）
node scripts/acp-image-e2e.mjs        # 图像能力端到端测试（视觉模型部分需要 API 密钥）
scripts/init-acp-home.sh              # 引导/刷新隔离主目录（~/.dsh-acp）

测试工具包的 DevDependency 版本锁定使用与锁定的
@deepseek-ai/dsh CLI 所声明的相同范围（例如 ^0.1.2-rc.1），这样仓库的依赖树和全新的
CLI 安装会解析出一个一致的家族——此处精确的补丁版本锁定与 CLI 的
范围解析闭包混在一起会产生分裂的闭包（同一个名字出现两个版本），从而以导出未找到的错误破坏 profile 启动。
更改这些锁定后，请重新生成整个 lockfile（rm -rf node_modules pnpm-lock.yaml && pnpm install）：增量
安装既会留下过期的 store 条目毒害 profile 修复，又会保留过期的
lockfile peer 解析——将 0.1.2-alpha.2 → 0.1.2-rc.1 原地升级会留下
dsh-session-persistence@0.1.2-alpha.3（旧代 peer）被接入 rc.1
包的快照中，这能通过启动和 session/new，只在第一轮时以
TypeError: Cannot read properties of undefined (reading 'length') 从 PersistenceCoordinator 抛出而失败。
pnpm-workspace.yaml 批准了 CLI 闭包的构建脚本（node-pty 预构建、koffi）
——当仓库 CLI 启动 profile 时，它们是运行时需求。

已知限制

不支持音频附件（未声明音频能力），默认情况下文本以
块粒度流式传输（streamDeltas: true 可选择启用 token 级流式传输，参见功能），每个会话一次进行中的提示。MCP 支持 stdio 和可流式 HTTP
（不声明旧版 SSE / acp 传输）。
session/close / session/fork / session/resume 未实现（能力未声明，合规客户端不会调用它们）；session/delete 直接删除
持久化目录，因为 dsh 持久化没有官方的删除 API。

多根工作区已声明，所有根对模型可见，但 dsh 的
沙箱策略解析为每个会话一个可写根（主 cwd，即
session.header.cwd），本地沙箱恰好绑定该根用于写入。读取
在每个根中都有效；在 workspace-write 下，对额外根的写入会先被拒绝，需要升级/批准，而 danger-full-access 可以在任何地方写入。
真正的多根写入强制执行属于 dsh 核心（dsh-sandbox-policy /
dsh-sandbox-local 需要的是一个根列表，而不是单个根）。

Agent 预设接管面向模型的行：随附的 cordis.patch.yml 会禁用某个预设所拥有的
dsh-base 行（tool-bash/fs/subagent/todo/web/…… —— 正好是官方
dsh-web-app/tui 列表减去 hmr），并挂载 agent-presets 名册（默认
standard；code/minimal/cordis 随 dsh CLI 一起提供，你自己放在
~/.dsh/.agent-presets 下的预设目录会被自动拾取）。该 bundle 自带的补丁会自动应用
（package.json dsh.bundle.patch）—— 不要把它复制到该 profile 的
用户层 cordis.patch.yml 中，否则加载器会在启动时因重复的条目 id 而拒绝。
当升级一个已经带有自定义用户层补丁的 profile 时，只在那里保留你的自定义行配置
（例如 acp-enhanced 行上的 includeAllProviders: true，并重新声明
provider/model/preset，因为补丁条目会替换整行，而不是合并）。在升级之前创建的会话
会以该名册的默认预设恢复。