用 deepseek-harness-acp 把 DeepSeek Harness 接到 Zed 等 ACP 客戶端

DeepSeek Harness 插件 DeepSeek DSH ACP Zed 開發與運行時 2026-08-18 150 閱讀

前言

DeepSeek Harness（dsh）把智能體運行時拆成插件：模型、工具、技能、會話、沙箱、存儲和界面都可以換。日常入口多半是 Web UI，例如 npx @deepseek-ai/dsh web。寫代碼時人卻待在編輯器裏，於是會出現一個具體問題：會話、工具調用、權限詢問和 diff 審查都發生在瀏覽器，編輯器這邊還要另開一套流程。

Agent Client Protocol（ACP）就是爲這件事準備的協議。它由 Zed 發起，現在和 JetBrains 一起開放維護，定位接近「智能體版 LSP」：編輯器當客戶端，智能體當子進程，雙方用 JSON-RPC 走標準輸入輸出。Gemini CLI、Claude Agent、Codex CLI 已經能按這套協議接到編輯器裏。DeepSeek Harness 自己也有一份官方包 @deepseek-ai/dsh-acp，但源碼註釋寫得很清楚：那是給受信任程序客戶端用的自動化通道，展示層和人機交互仍留在 Harness 自己的 UI。

社區插件 deepseek-harness-acp 走的是另一條路：把完整的 Harness 組合進程內拉起來，再把會話事件映射成編輯器能渲染的 ACP 詞表。下面按插件目錄頁、GitHub README、package.json、LICENSE 和 npm 登記信息覈對後整理：它是什麼、和官方 ACP 包差在哪、怎麼裝、怎麼接到 Zed。

這是什麼

deepseek-harness-acp 是一款「開發與運行時」類 DeepSeek Harness 插件，維護者是 GitHub 組織 openma-ai。npm 包名是 @openma/deepseek-harness-acp，命令行入口是 dsh-acp。目錄頁一句話介紹是：「DeepSeek Harness 的 ACP（Agent Client Protocol）服務端實現。」倉庫 README 寫得更具體：從 Zed、Backchat 這類 ACP 客戶端裏使用 DeepSeek Harness。

它解決的不是「再做一個聊天窗口」，而是把已經在 dsh web 裏配好的同一套運行時接到編輯器：

  • 適配器在進程內組裝 Harness，而不是在外面再包一層 HTTP 代理。
  • 憑證不進編輯器配置。它複用 Web UI 寫進 $DSH_HOME 的密鑰，或用 dsh-acp login 寫到同一份存儲。
  • 會話、設置、預設和日誌跟 dsh web 共用 $DSH_HOME。Web 裏開過的對話，編輯器側可以列出並加載。

許可證以倉庫爲準：LICENSE、package.json 和 npm 登記都是 Apache-2.0。目錄頁把許可證標成 NOASSERTION，那是 GitHub 許可證探測沒有識別出來，不是另有一份未聲明協議。主要語言是 TypeScript，engines 要求 Node.js >=22.15。覈對當日 GitHub 倉庫顯示 9 星，目錄頁顯示 7 星；倉庫仍在快速迭代，星標只作參考。

需要先分清兩套名字相近的東西：

  1. 官方 @deepseek-ai/dsh-acp：DeepSeek Harness 源碼樹裏的自動化 ACP 服務，面向程序客戶端，能力刻意收窄。
  2. 社區 @openma/deepseek-harness-acp：面向編輯器的完整適配器，把流式文本、推理、工具 diff、權限請求、會話模式、斜槓命令、技能和 MCP 都投影到 ACP。

另外還有一個同名縮寫干擾：Agentic Control Plane 也叫 ACP，和 Agent Client Protocol 不是一回事。本文只討論後者。

社區插件目錄 deepseek-harness-plugin.com 是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，不要把它理解成官方應用商店。DeepSeek Harness 本身仍處於 developer preview，官方倉庫明確寫了會有破壞性變更。

核心功能

倉庫 README 把能力寫成「把 harness 的 session-event 日誌映射到完整 ACP 詞表」。下面只列已經在 README 和 cordis.patch.yml 裏寫明的部分。

流式輸出與工具調用

助手文本和推理增量會按 ACP 推給客戶端；客戶端若收不到增量，適配器會退回拼好的整段消息。工具調用帶 ACP kind、可讀標題、文件位置，以及從 fs-tool hunk 得到的真實 diff。客戶端支持 display terminal 時，命令輸出走終端面板；否則用圍欄代碼塊。

session/cancel 會穿過 Harness 的 agent 打斷當前回合，不是隻在協議層丟一個標誌。

權限預設當成會話模式

會話默認從 workspace-write 開始：bash 和文件改動限制在會話 cwd（外加共享臨時目錄）。三個命名預設與 Web UI 一致，每個都是 {sandbox, approval} 的固定搭配：

  • read-only
  • workspace-write
  • danger-full-access

模型若請求更寬的權限，會彈出 ACP 權限請求。「Always allow (this session)」會把該會話的審批策略改成 never。danger-full-access 會同時關掉沙箱和提示，README 寫明只適合一次性檢出或容器。

組合、模型目錄與斜槓命令

profile 掛了 agentPresets 時，會出現未分類配置項 id: "agent"，名單包括 standard / code / minimal / cordis 以及用戶自己的副本。切換會現場重建 agent，歷史保留。複製和刪除預設仍在 Web 設置頁完成，沒有 /preset 斜槓命令。

模型列表來自正在運行的組合：在 Web UI 里加的第三方供應商會立刻出現。推理力度跟隨產品默認值。適配器內置 /status、/model，同時執行 Harness 命令註冊表裏的 /compact、/goal、/permission、/plan 等，以及技能調用（/skill-name）。這些命令不走模型回合。登錄和登出是 ACP 方法，不是聊天命令。

會話、計劃、用量與 MCP

todo_write 快照會變成 ACP plan；token 記賬走 usage_update 和按回合用量。session/load 會重放完整歷史，session/list 可列出會話；agent 重啓後客戶端若仍對舊會話發 prompt，適配器會靜默恢復。標題通過 session_info_update 同步。

每個會話的 mcpServers 會掛上 @deepseek-ai/dsh-mcp-client 實例（stdio 和 streamable HTTP），工具名形如 mcp__<server>__<tool>。單個 MCP 服務器失敗不會把整個會話打掛。

圖片與憑證

組合掛了 ctx.attachments（dsh-base 會掛）時，適配器會聲明 promptCapabilities.image。ACP image 塊會校驗、用 saveImage 保存，並與周圍文本保持線上順序。resource_link 只當作文本文件指針。

憑證有兩層，編輯器配置裏都不放密鑰：

  1. Harness 憑證庫：$DSH_HOME/.credentials.yaml（權限 600），與 Web UI 寫入的是同一份，支持熱加載。
  2. 進程環境：DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL，以及對應路由上的 ANTHROPIC_API_KEY / OPENAI_API_KEY。

憑證門禁看的是當前供應商路由。只有 Anthropic 密鑰時，開不了 DeepSeek 會話，反過來也一樣。缺少憑證時，session/new 和 session/prompt 會以 auth_required（-32000）失敗。

ACP initialize 會聲明三種 Agent Auth：

  1. API key：方法名 api-key；多條路由並存時寫成 api-key: <route>。客戶端可傳 _meta["api-key"].apiKey。
  2. Browser：打開本機登錄頁，密鑰不走 ACP。設置了 NO_BROWSER 時隱藏。
  3. Custom gateway：僅當客戶端聲明 clientCapabilities.auth._meta.gateway === true 時出現，客戶端發送 { baseUrl, headers, providerName? }。

安裝與啓用

先確認本機已有 Node.js 22.15 或更高版本，並且能運行 DeepSeek Harness。官方快速入口是：

npx @deepseek-ai/dsh web

Web UI 默認在 http://127.0.0.1:3080。也可以先全局安裝：

npm install -g @deepseek-ai/dsh
dsh web

DeepSeek Harness 仍是 developer preview，核心插件和 API 還會變。

目錄頁給出的安裝命令

社區目錄頁上的原文命令如下，在 DeepSeek Harness 終端裏運行即可：

dsh plugin add github:openma-ai/deepseek-harness-acp

需要可復現安裝時，按目錄頁說明固定 commit 哈希：

dsh plugin add github:openma-ai/deepseek-harness-acp#<commit>

把 <commit> 換成倉庫裏的真實哈希。目錄頁同時提醒：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；裝之前應檢查源碼倉庫和許可證。

倉庫 README 的兩種用法

目錄頁那條命令解決的是「把插件加進當前配置」。真正接到編輯器時，README 給出兩條路徑。

A. 獨立服務端，適合先跑通：

npm install -g @openma/deepseek-harness-acp
dsh-acp login

dsh-acp login 是交互式的，輸入不會回顯；密鑰也可以只在 Web UI 的 Settings → Models 裏保存一次。覈對當日 GitHub package.json 版本是 0.4.10-beta.2，npm latest 是 0.4.9。用 npm 安裝時以登記處實際版本爲準，不要把未發佈的 beta 號寫進腳本。

獨立進程會按 --dsh-path / DSH_PATH、自身目錄、./node_modules、PATH 上的 dsh、npm root -g 尋找 Harness，最後才用 npm 安裝的 peer。已經存在 $DSH_HOME/profiles/acp 時，由該 profile 負責組合。

Zed 的 settings.json 示例：

{
  "agent_servers": {
    "DeepSeek Harness": { "command": "dsh-acp" }
  }
}

B. dsh profile 插件，適合長期放在自己的 dsh 配置裏：

npm install -g @deepseek-ai/dsh
dsh web
dsh plugin --profile acp add -w @openma/deepseek-harness-acp

這會創建 $DSH_HOME/profiles/acp，並註冊包裏的 dsh.bundle 補丁。橋接掛在 @deepseek-ai/dsh-base 上，產品基線與 dsh web 相同，模塊熱重載是關掉的。之後可以像普通 profile 一樣改 $DSH_HOME/profiles/acp/cordis.patch.yml。

對應的 Zed 配置：

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

兩種形態共用 $DSH_HOME：憑證、設置、預設和會話日誌都是同一套。

典型用法

下面的命令和配置都來自倉庫 README，可以按原文復現。

在 Zed 裏啓動一次會話

  1. 用上面 A 或 B 裝好適配器。
  2. 在 Web UI 或 dsh-acp login 裏寫入當前要用的供應商密鑰。
  3. 把對應的 agent_servers 寫進 Zed settings.json。
  4. 在 Zed 的 Agent 面板裏選「DeepSeek Harness」，新開會話。

獨立服務端啓動後，stdout 只承載 ACP JSON-RPC，不要在這個進程上再掛普通日誌到 stdout。cordis.patch.yml 因此關掉了 HMR 監視。

覆蓋模型、權限和推理力度

標誌優先於環境變量，環境變量優先於默認值。不傳任何標誌時，會話跟隨產品默認（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

永久覆蓋應寫進 profile 的 cordis.patch.yml（按 id 覆蓋，後寫生效），不要把密鑰寫進編輯器 JSON。

子命令還有 dsh-acp login [api-key] 和 dsh-acp update（經 npm 自更新）。

會話裏直接用的命令

登錄完成後，不必再在聊天裏貼密鑰。會話內可用：

  • /status、/model：適配器內置
  • /compact、/goal、/permission、/plan 等：Harness 命令註冊表
  • /skill-name：調用已安裝技能

需要換 agent 預設時，走客戶端的配置項 agent，不要找 /preset。

本地改插件時的雙 profile

README 建議：編輯器繼續用已發佈包，另開一個 profile 用 pnpm 的 link: 指到工作樹（file: 會被當成拷貝安裝，同版本 tarball 還會走緩存）：

dsh plugin --profile acp add -w @openma/deepseek-harness-acp
dsh plugin --profile acp-test add -w "link:$PWD"

開發循環是 npm run build 之後重啓進程。Zed 可以同時掛穩定版和開發版：

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

適用場景與注意事項

比較適合這幾類人：

  • 已經在用 dsh web，希望同一套憑證和會話出現在 Zed 等 ACP 客戶端裏。
  • 需要在編輯器裏看工具 diff、權限請求、計劃和終端輸出，而不是隻拿一段純文本回復。
  • 想把 DeepSeek Harness 的技能、斜槓命令和 MCP 帶到編輯器側，又不想給編輯器單獨配一套密鑰。

不太適合的情況也要說清楚：

  • 只要程序裏調一輪 prompt / 取消 / 一次性權限，官方 @deepseek-ai/dsh-acp 纔是那個自動化通道；不要把兩套包混裝混用。
  • 需要把智能體接到沒有 ACP 客戶端的編輯器時，這個插件幫不上忙。協議本身支持的編輯器可以看 Zed 的 ACP 頁 和 agentclientprotocol.com。
  • DeepSeek Harness 和本插件都還在快速變動。npm 的 0.4.9 與倉庫 0.4.10-beta.2 不一致，安裝後以實際解析到的版本和 commit 爲準。

安全方面按目錄頁和 README 的原文執行：

  • 插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。裝之前閱讀源碼和 Apache-2.0 許可證。
  • 不要把 API 密鑰寫進 settings.json。優先用 Web UI 或 dsh-acp login。
  • 默認 workspace-write 已經把改動限制在會話工作目錄；danger-full-access 會關掉沙箱和詢問，只用於一次性目錄或容器。
  • 憑證門禁按供應商路由生效，缺密鑰時會話會直接 auth_required，這是預期行爲，不是客戶端壞了。

小結

deepseek-harness-acp 做的事情很具體：讓 DeepSeek Harness 作爲 ACP 服務端跑在編輯器旁邊，會話事件、工具 diff、權限和憑證仍然以 Harness 爲準。它不是 DeepSeek 官方應用商店裏的一款「認證插件」，而是 openma-ai 維護的社區開源適配器；和倉庫裏那份自動化專用的 @deepseek-ai/dsh-acp 也不是同一個包。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-acp/

GitHub：https://github.com/openma-ai/deepseek-harness-acp

裝之前看源碼，固定 commit，密鑰留在 $DSH_HOME。這三件事比多裝一個編輯器插件更重要。

相關文章

快速從零部署一個DeepSeek-R1服務 2025-04-05 使用 dsh-anchored-standard 爲 DeepSeek Harness 配置兩階段 Agent 預設 2026-08-17 用 dsh-web-ui 把 DeepSeek Harness 網頁界面補成工作臺 2026-08-17 用 modlens 給 DeepSeek Harness 的純文本模型補上視覺 2026-08-17 用 dsh-TUI 給 DeepSeek Harness 補上全屏終端界面 2026-08-17
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜