openma-ai/deepseek-harness-acp

deepseek-harness-acp

在 Agent Client Protocol 客户端（例如
Zed 和
Backchat）中使用
DeepSeek Harness。

= 22.15" />

该适配器以进程内方式组合 harness，并将其会话事件日志映射到完整的 ACP 词汇表：流式文本与推理、带 diff 和显示终端的工具调用、计划、权限请求、会话模式、配置选项、斜杠命令、技能以及 MCP 服务器。凭据绝不会触碰你的编辑器配置——它会复用你在 dsh Web UI 中保存的密钥，或者由 dsh-acp login 将密钥保存到同一存储中。

一个包，既可独立运行也可作为插件

| | A · dsh 配置文件插件（推荐） | B · 独立服务器 |
|---|---|---|
| 最适合 | 常规安装与升级 | 在不管理 dsh 配置文件的情况下连接 ACP 客户端 |
| 安装 | dsh plugin --profile acp add @openma/deepseek-harness-acp@latest | npm i -g @openma/deepseek-harness-acp |
| Zed 运行 | dsh --profile acp | dsh-acp |
| Harness | 拥有该配置文件的 dsh | 你安装的 dsh，然后是包中锁定的私有运行时 |
| 组合 | dsh-base + 此 bundle + 你配置文件自身的补丁 | dsh-base + 此 bundle（配置文件机制在进程内启动） |

两种形态共享 $DSH_HOME：与 dsh web 相同的凭据存储、设置、预设和会话日志——在 Web UI 中开始的对话可以从编辑器中列出并加载。

其他 dsh 界面可以将与传输无关的 @openma/deepseek-harness-acp/plugin 挂载到其 Base Host 树上，并自行拥有传输适配器。TUI 配置文件使用此路径：它启动一个单独的 TUI Client 进程，并通过该进程的标准 stdin/stdout 连接 ACP；它
不启动 dsh-acp，也不使用进程内 Client 流。

因此，该包不仅是 CLI 包装器。它还是其他 dsh 应用程序所使用的 ACP 表面插件：一个 Host 组合可以通过由该表面选择的传输方式，暴露相同的会话、工具、预设、技能和持久化。

DSH 兼容性

捆绑的运行时是 DSH 0.1.5-rc.1，包含上游的跨进程会话写锁。你已安装的 DSH 仍然优先；请使用更新后的 host 或捆绑的运行时来获得该修复。

竞争的 load/resume 会返回标准的 JSON-RPC 错误。关闭会话或退出拥有者进程后，另一个进程即可恢复它。每个写入共享会话的进程都必须使用固定的后端；较旧的 host 不参与此锁。

恢复历史会话使用 host 的 V3 迁移，该迁移会保留原始日志。升级后的会话无法被较旧的 host 读取。多根工作区仍不受支持。

A · dsh profile 插件（推荐）

npm install -g @deepseek-ai/dsh
dsh web                                                    # save your API key once
dsh plugin --profile acp add @openma/deepseek-harness-acp@latest

// Zed settings.json
{
"agent_servers": {
"DeepSeek Harness": { "command": "dsh", "args": ["--profile", "acp"] }
}
}

该插件命令会创建 $DSH_HOME/profiles/acp，安装或升级适配器，并注册其 dsh.bundle 补丁。该桥接挂载在 @deepseek-ai/dsh-base 之上——与 dsh web 相同的产品基线，但关闭了模块重载监视器。像任何其他 dsh profile 一样，在 $DSH_HOME/profiles/acp/cordis.patch.yml 中扩展该 profile。此路径不需要全局安装 dsh-acp。

B · 独立服务器

npm install -g @openma/deepseek-harness-acp
dsh-acp login        # interactive; or save the key in the dsh Web UI

// Zed settings.json
{
"agent_servers": {
"DeepSeek Harness": { "command": "dsh-acp" }
}
}

独立二进制文件通过 --dsh-path / DSH_PATH、./node_modules、PATH 上的 dsh 或 npm root -g 查找 DeepSeek Harness，然后回退到本包内归档的确切运行时。DSH 仅是用于 Host 集成的通配可选 peer，绝不是通过 npm 安装的依赖：插件模式使用 Host 的依赖树，而独立模式将相同的导入映射到私有运行时。当存在真实的 $DSH_HOME/profiles/acp 时，该 profile 拥有该组合。

插件与扩展模型

有两种相互独立的方式来扩展由 ACP 支持的表面。

要通过 ACP 客户端使用可移植的 Agent Plugins、Codex 插件、Claude Code 插件或 Pi 包，请将 Agent Plugins Bridge 添加到同一 profile：

dsh plugin --profile acp add @openma/dsh-agents-plugins-bridge@latest

该 Bridge 贡献普通的 Host 行。导入的命令、技能、工具、
hooks、MCP 连接、agents 和 Pi 扩展因此通过此适配器现有的投影到达 ACP；不存在 ACP 专用的插件导入运行时。Bridge 的 Web 管理面板和 MCP Apps HTML 渲染器仍然是 Web 界面，不会通过 ACP 发送。

对于需要会话拥有的后台生命周期且没有打开终端 UI 的扩展，请使用
Martty owner。
它是一个通用的 ACP rpc 客户端：此包仍然是服务器/传输层，而 Martty 拥有长期存活的 Session 以及显式的启动/关闭斜杠命令。

扩展 Host 组合

ACP 适配器搭载在 profile 已经拥有的 Cordis 树上。向该 profile 添加 dsh 插件以更改 agent 组合，而不是 fork ACP 服务器：providers 和 models 加入实时目录，commands 和 skills 加入通告的会话界面，tools 和 subagents 通过标准的 session/update 出现，并且相同的会话持久化对每个界面仍然可用。

对于嵌入 ACP 的应用程序，公开的包入口为：

| 导出 | 角色 |
|---|---|
| @openma/deepseek-harness-acp/plugin | 完整的 Host 侧界面插件。它填充 Base 留给某个界面的 ACP 所需的 Host 服务，并提供 ctx.acpServer。它不声明传输层。 |
| @openma/deepseek-harness-acp/server | 较低层的、与传输无关的 acpServer 提供者，用于已经提供注入的组合服务的 Host 树。 |
| @openma/deepseek-harness-acp/stdio | 标准 profile 适配器：将 ctx.acpServer 连接到进程 stdin/stdout。 |
| @openma/deepseek-harness-acp/bridge | Node 流适配器以及用于旧 profile 补丁的兼容入口。 |

ctx.acpServer.connect(stream) 在现有 Host 组合上创建一个连接拥有的 bridge fiber。传输所有者保留进程、流和 TTY 生命周期；ACP 插件保留会话和 agent 语义。这就是
@openma/deepseek-harness-tui 使用的形态：
ACP 留在 Base Host 树上，而单独的 TUI Client 进程拥有自己的 Cordis 树。

添加 Cordis 服务并不会自动发明一个 wire 方法。只要存在标准 ACP 能力或事件投影，就优先使用它；仅为必须跨越客户端边界的行为添加适配器。

在不破坏普通客户端的情况下扩展 ACP

可选的 wire 行为遵循 ACP 的扩展约定：

1. 在 initialize 元数据中通告支持，使用带命名空间和版本的能力，例如 _meta.dsh.cordis.protocol。
2. 当不需要新请求时，在标准消息上以带命名空间的 _meta 字段携带注解。
3. 用前导下划线命名自定义 JSON-RPC 请求和通知，并且仅在双方协商了匹配的能力后才发送它们。
4. 保持标准 ACP 路径完整。未声明扩展的客户端仍必须获得正常的会话、提示、更新、取消、认证和配置选项。

DSH 工具结果值

[ACP 元数据注册表][metadata-registry] 是本适配器读取或发出的每个 _meta 字段的权威列表。它记录了方向、载体、形状、协商要求以及重放行为，包括位于 _meta.dsh.toolResult.value 的原生 DSH 工具值。

[metadata-registry]: https://github.com/openma-ai/deepseek-harness-acp/blob/main/docs/metadata.md

当前包将此模式应用于 TUI 用于客户端能力发现、动态 Package 生命周期以及包私有 Host/Client RPC 的内置 _dsh/cordis/ 系列。它是一个显式的、带版本的扩展——而不是跨进程同步 Cordis 插件 id、纤程或 inject。该桥接的内部方法注册表目前不是公共的任意扩展 API；新的扩展系列应首先定义稳定的能力、所有权、生命周期和回退契约。

认证

编辑器配置中不放密钥，聊天中不粘贴机密。ACP 客户端遵循协议：initialize 声明三种 Agent Auth 方法。

1. API 密钥 — api-key，或当有多条路由处于活动状态时为 api-key:。客户端可以传入 _meta["api-key"].apiKey。
2. 浏览器 — browser。适配器打开一个 localhost 登录页面；机密绝不会通过 ACP 传输。当设置了 NO_BROWSER 时隐藏。
3. 自定义网关 — gateway，仅当客户端通过 clientCapabilities.auth._meta.gateway === true 选择加入时可用。客户端发送 _meta.gateway { baseUrl, headers, providerName? }。

适配器将凭据写入 harness 存储。缺少凭据会使 session/new 和 session/prompt 失败，并返回 auth_required（-32000）。登出即 ACP 的 logout 方法。

1. Harness 凭据存储 — $DSH_HOME/.credentials.yaml（权限模式 600），即 dsh Web UI 写入的文件；会热重载。使用 dsh-acp login [--provider ] 或 Web UI（Settings → Models）保存密钥。
2. 进程环境 — 在启动 agent 的环境中设置 DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL（以及对应路由的 ANTHROPIC_API_KEY / OPENAI_API_KEY）。

凭据门控针对的是当前 provider 路由。仅含 Anthropic 的存储足以用于 Anthropic 会话；DeepSeek 密钥无法解锁另一个 provider。

功能

- 流式传输 — 助手文本和推理增量；组装消息回退。
- 图像 — 当组合挂载 ctx.attachments（dsh-base 会这样做）时，声明 promptCapabilities.image。ACP image 块会被验证，通过 saveImage 存储，并与周围的文本保持线上顺序。resource_link 仍为文本文件指针。
- 工具调用 — ACP 类型、人类可读标题、文件位置、来自 fs-tool hunks 的真实 diff、原始输入/输出；当客户端支持时，命令输出显示在显示终端上，否则以围栏代码块形式输出。
- 作为会话模式的权限预设 — read-only / workspace-write / danger-full-access，每个都是一个命名的 {sandbox, approval} 对，记录为持久会话事实（对于仅渲染这些内容的客户端，也作为配置选项暴露）。
- Agent 组合 — 当 profile 挂载 agentPresets 时，一个未分类的配置选项 id: "agent" 会列出名册（standard / code / minimal / cordis，以及用户副本）。切换时会实时重建 agent 并保留历史记录。创作（复制/删除）仍在 Web 设置页面上进行；没有 /preset 斜杠命令。
- 实时模型目录 — 来自运行中组合的 providers × models（在 Web UI 中添加的第三方 provider 会立即出现），以及遵循你的产品默认值的推理强度选择。
- 斜杠命令 — 适配器内置命令（/status、/model）加上 harness 命令注册表（/compact、/goal、/permission、/plan 等），无需模型轮次即可执行，再加上 skills（/skill-name — harness 自身的调用手势）。登录和登出是 ACP 方法，不是聊天命令。
- 计划与用量 — todo_write 快照作为 ACP 计划；token 核算作为 usage_update 和每轮用量。
- 会话 — session/resume 恢复持久会话而不重放其对话记录；session/load 仍是完整历史路径。还支持 session/list、当客户端在 agent 重启后提示旧会话时的静默恢复，以及作为 session_info_update 的标题。不宣传多根会话：在 session/new、session/resume 或 session/load 上非空的 additionalDirectories 会返回 Invalid params，直到 dsh 支持多个工作区根目录。
- MCP 服务器 — 每会话的 mcpServers 挂载 @deepseek-ai/dsh-mcp-client 实例（stdio + 可流式 HTTP）；工具以 mcp____ 加入；服务器故障绝不会导致会话中断。
- 引导 — 初始化响应会声明 _meta.steering.supported: true。发送 _session/steering 并附带 { sessionId, prompt, _meta: { steering: { idleBehavior: "promptRequired" } } } 以注入到活动轮次中；{ outcome: "injected" } 会让其原始提示请求和输出流继续负责。如果该轮次在注入前结束，响应为 { outcome: "promptRequired", reason: "noRunningTurn" }，客户端发送普通的 session/prompt。省略 idleBehavior 会使用相同行为。并发 session/prompt 引导仍受支持。
- 真正的取消 — session/cancel 通过 harness agent 中断活动轮次。

配置

标志优先于环境变量，环境变量优先于默认值。全部可选 —
没有标志时，会话遵循你的产品默认值（settings.yaml）。

| 标志 | 环境变量 | 默认值 | 用途 |
|---|---|---|---|
| --dsh-path | DSH_PATH | 自动检测 | DeepSeek Harness 安装位置 |
| --provider | DSH_PROVIDER | 产品默认值 | 提供商路由覆盖 |
| --model | DSH_MODEL | 产品默认值 | 模型覆盖 |
| --max-tokens | DSH_MAX_TOKENS | 提供商默认值 | 每请求输出 token 上限 |
| --permission-mode | DSH_PERMISSION_MODE | workspace-write | 初始权限预设 |
| --reasoning-effort | DSH_REASONING_EFFORT | 产品默认值 | off / high / max |
| — | DEEPSEEK_API_KEY | — | API 凭据（回退到凭据存储） |
| — | DEEPSEEK_BASE_URL | DeepSeek 端点 | OpenAI 兼容端点覆盖 |
| — | DSH_ACP_DEBUG | 关闭 | 详细 stderr 诊断 |

子命令：dsh-acp login [api-key]（省略时进入交互模式；输入永不
回显），dsh-acp update（通过 npm 自更新）。

权限与沙箱

会话以 workspace-write 启动：bash 和文件变更被限制在
会话的 cwd（加上共享临时根目录）内，模型重试请求
更宽访问权限时会触发 ACP 权限请求。始终允许（本次
会话）* 会将该会话的批准策略切换为 never。
danger-full-access 同时禁用沙箱和提示——仅
在一次性检出或容器中使用。每个级别是一个持久预设
（沙箱 + 批准一起），与 Web UI 提供的三个级别相同。

架构

ACP 客户端（Zed、……）
│  ACP JSON-RPC over stdio
▼
dsh-acp
├─ src/bin.ts              在 Host 导入求值前选择一个 DSH 树
├─ src/profile-boot.ts     启动 harness 自身的 profile 机制
│                          （dsh-base + 此 bundle + $DSH_HOME 层）
├─ src/harness.ts          host 发现（DSH_PATH → cwd → PATH → npm -g → 捆绑运行时）
└─ src/bridge/             ACP 桥接（一个 cordis 插件）
├─ index.ts           会话、提示、取消、模式、选项、
│                     命令、凭据、MCP 挂载
├─ translate.ts       session-event → ACP update 投影（纯函数）
├─ history.ts         用于 session/load 的存储日志重放（纯函数）
└─ prompt.ts          ACP 提示块 → harness 内容块（纯函数）
▼
外部或包捆绑的 dsh     （agent spine、llm、持久化、沙箱、
工具、预设、技能、压缩、……）

当由另一个 surface 嵌入时，只有传输边缘发生变化：

dsh Base Host Cordis 树
├─ 产品插件（agents、tools、skills、persistence、……）
└─ @openma/deepseek-harness-acp/plugin
└─ acpServer.connect(Stream)
│ 标准 ACP + 协商扩展
▼
surface 拥有的 Client 进程

桥接消费 harness 的 session/event 数据流——与
仅追加日志持久化存储——因此实时流式传输、历史回放和
session/list 在构造上保持一致。所有 harness 模块，包括 cordis
本身，都从同一个宿主树加载：插件和服务身份绝不会被拆分
到多个副本中。

开发

npm install         # dev deps include the harness packages (types + tests)
npm run typecheck   # tsc --noEmit
npm test            # vitest: unit + e2e smoke (boots the real composition; no model calls)
npm run build       # esbuild → dist/

若要针对独立宿主安装运行 e2e 测试套件：

npm install --prefix /tmp/dsh-host @deepseek-ai/dsh
DSH_ACP_TEST_HOST=/tmp/dsh-host npm test

实时迭代：成对 profile

将你的编辑器使用的 profile 保持在已发布的包上，并通过 pnpm 符号链接
将第二个 profile 指向此工作树：

dsh plugin --profile acp add -w @openma/deepseek-harness-acp   # stable
dsh plugin --profile acp-test add -w "link:$PWD"               # dev (symlink)

开发循环是 npm run build + 重启——dist/ 和 cordis.patch.yml
通过该链接读取。（pnpm 将 file: 视为复制安装并缓存
同版本 tarball；link: 可避免这两者。）

{
"agent_servers": {
"DeepSeek Harness": { "command": "dsh", "args": ["--profile", "acp"] },
"DeepSeek Harness (dev)": { "command": "dsh", "args": ["--profile", "acp-test"] }
}
}

许可证

Apache-2.0。