前言¶
用 DeepSeek Harness（DSH）做開發時，很多人手上不止一個編碼智能體：本地有 ZCode、MiniMax Code，訂閱的還有 Codex、Claude、Grok、Cursor、Qoder。它們散落在各自的 CLI 或桌面應用裏，各自的額度、密鑰、配置互不相通；想在 DSH 的一次會話里路由到不同智能體，要麼靠手工複製粘貼，要麼乾脆放棄統一入口。
下面介紹的插件 goodjin/dsh-acp-agent（npm 包 @goodjin2/dsh-acp-agent）解決的就是這件事：在 DSH 原生會話界面上註冊外部編碼智能體，並把各家的額度顯示和模型切換統一收斂回宿主進程。它由 goodjin 維護，在社區插件目錄中歸類爲「客戶端」。
這是什麼¶
一句話定位：DSH 插件，把外部編碼智能體（GLM/ZCode、MiniMax、Codex、Claude、Grok、Cursor、Qoder 共七家）接進 DSH 的原生會話界面，同時內置各家額度膠囊與賬戶餘額顯示。
插件分爲宿主側和瀏覽器側兩層：
- 宿主側隨 DSH 進程加載，負責外部智能體的進程管理、模型客戶端和配額接口；
- 瀏覽器側（
./client入口，經 DSH Web 自動加載）負責會話界面上的額度膠囊、模型芯片、切換反饋和進程步驟渲染。
目錄頁顯示星標爲 0，以頁面當時數據爲準。
核心功能¶
ACP 智能體框架¶
宿主側實現 ACP（Agent Client Protocol）運行框架，覆蓋傳輸層（stdio、WebSocket）、各智能體的方言適配、幀投影、終端與文件子協議。七家外部智能體經由這一層被註冊爲 DSH 的 preset，接管會話、路由對話輪次、處理模型切換。
GLM（ZCode）模型客戶端¶
直接讀取本地 ZCode 桌面應用保存的 coding-plan 密鑰，調用 GLM Coding Plan 並流式返回結果。密鑰讀取路徑按優先級有兩條：
~/.zcode/v2/config.json— 在options.apiKey字段中明文保存，與該 provider 條目服務的options.baseURL放在一起。條目按它服務的網關擇優，而不是按名稱。~/.zcode/v2/credentials.json— 舊版應用（當前 3.17.2，README 註明檢查日期 2026-11-06）已不再寫入該條目，僅作舊路徑保留。
按請求實時讀取，不做緩存——因爲用戶重新登錄或切換套餐時應用會重寫這些文件。兩個環境變量可以改位置：ZCODE_DATA_BASE_DIR 整體遷移數據目錄，ZCODE_ACP_CONFIG_FILE 和 ZCODE_ACP_CREDENTIALS_FILE 分別覆蓋單個文件路徑。
MiniMax 模型客戶端¶
借用本地 MiniMax Code 登錄態（~/.minimax/auth/<buildEnv>/<region>/mcode-public/auth.json），走同一官方 OAuth 核心刷新；刷新成功不會影響桌面應用或 CLI，因爲它們共用同一憑據存儲與跨進程鎖，插件刷新後寫入的是同一位置，桌面端照常工作。
刷新失敗時插件不再靜默降級，而是說明去哪授權：resolveCredential 拋出 MiniMaxLoginRequiredError（reason: 'missing' | 'expired'）；配額接口返回 { ok: false, needsLogin: true, login: { url, userCode?, expiresInSec? } }；模型請求無法鑑權時，授權鏈接會放進流式錯誤裏，用戶在會話裏直接點擊即可。該鏈接來自桌面應用所用的設備授權流程（POST /oauth2/device/code → verification_uri_complete）。插件在後臺啓動該流程，最多等 3 秒拿到提示，因爲 MiniMax Code 在運行時持有憑據鎖，插件的登錄請求需要排隊——第一次響應可能只帶賬戶來源，30 秒後的下一次輪詢纔會返回帶用戶碼的完整鏈接。令牌不會進入接口響應、日誌或錯誤消息。
配額接口與瀏覽器端膠囊¶
宿主側暴露 GLM、MiniMax、Codex、Claude、Grok 的配額路由，憑據永遠不離開宿主進程。瀏覽器側在輸入框下方顯示各家的配額膠囊，輪詢上述路由；另有模型可見性面板，可以在設置裏隱藏任意 provider 或模型；輸入框旁的模型芯片顯示當前 provider；會話切換到新 preset 時給出接管提示和進度條。
掉字輪次恢復與 ACP 進程視圖¶
輸入框支持被打斷的無文本輪次恢復（展開按鈕重新發送），也支持未進入對話記錄的請求重發。外部智能體的輪次會渲染出 ACP 進程步驟（終端、文件操作），獨立運行時可用，裝了 @goodjin2/dsh-chat-area 時會通過 conversation.chat.node.acp-segment-renderer 這個 seat 掛進該包的 assistant-step 渲染鏈路。
健康自檢¶
插件自帶一個葉子模塊 ./health，不導入包內任何其他模塊：即使其他行全部掛載失敗，它仍能加載並報告。啓動後打印一行日誌，例如：
acp-agent health: 12/13 行已掛載；未掛載 1 行 — acp-agent-minimaxi-quota（MiniMax 套餐額度接口）：SyntaxError: TypeScript parameter property is not supported in strip-only mode
同一賬本以 JSON 提供在 GET /acp-agent/health，status 取值 mounted、failed、pending、absent、disabled。日誌同時追加一行帶時間戳到 $DSH_HOME/logs/acp-agent-health.log，每次啓動一行。這個模塊的來歷是一次真實事故：2026-11-03，src/minimaxi/credential.ts 裏一個構造函數參數屬性在 DSH 的 strip-only TypeScript loader 下報錯，導致引用它的所有行連同宿主和瀏覽器兩側一起消失，日誌裏無任何痕跡，只能通過探測配額路由是否存在才定位到原因。現在另有一個 tests/entry-loadability.spec.ts 在發佈前用真實 node（不做轉換）導入每個宿主入口來把關。
安裝與啓用¶
從 GitHub Packages 安裝（README 原文命令）：
# 一次性配置 npm 鑑權
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc
echo "@goodjin:registry=https://npm.pkg.github.com" >> ~/.npmrc
dsh plugin --profile web add @goodjin2/dsh-acp-agent
或者把包加進 profile 的 package.json：
{
"dependencies": { "@goodjin2/dsh-acp-agent": "^0.1.0" }
}
裝完要在 profile 的 cordis.patch.yml 裏添加要用的智能體 preset。倉庫自帶一份示例 cordis.patch.yml，內含七行 agent preset 和一行瀏覽器半區 roster（acp-agent-client，按裸包名聲明——DSH 只把恰好叫這個名字的行當作客戶端入口）。
0.3.0 之前，泛用的對話區 UI（回答卡片、會話文件卡片、Mermaid 渲染器及其宿主路由、短會話 ID 條）已遷至 @goodjin2/dsh-chat-area。如果 profile 裏還寫着 @goodjin2/dsh-acp-agent/mermaid-asset，需要替換爲 @goodjin2/dsh-chat-area/mermaid-asset（或刪除，chat-area 自帶的 bundle patch 會聲明它）。兩個包同時安裝時的瀏覽器分層：assistant-step 渲染優先級最低的條目，chat-area 在 -50、本插件在 -40 包裹；只有 chat-area 聲明 seat，重複聲明會被吞掉並報錯。
運行環境（package.json）：node ^22.19.0 || >=24.0.0，dsh >=0.2.1-rc.2 <0.3，pnpm@11.7.0；當前版本 0.3.0。
適用場景與注意¶
適合已經在 DSH 裏工作、同時訂閱多個外部編碼智能體、希望在統一會話裏切換模型和看餘額的用戶；也適合想以 DSH 爲入口統一七家配額與路由的團隊。
兩點提醒：
- 插件以當前 DSH 進程的權限運行，宿主側會讀取本機憑據文件（如
~/.zcode/v2/config.json、~/.minimax/auth/…/auth.json），安裝前應檢查源碼與LICENSE（倉庫files中列出LICENSE，具體許可證類型 README 未標註）。 - 配額與憑據接口只在宿主進程內流轉，插件不把令牌放進頁面載荷或日誌，但如果對第三方插件做安全審計，仍按第三方代碼對待。
結語¶
這個插件的價值在於把「外部編碼智能體 + 各家額度」這兩件事收斂進 DSH 的原生會話界面：模型切換、額度查看、失敗重試不再需要逐個打開各家客戶端，健康自檢機制也補上了插件開發裏常見的靜默失效問題。
- 目錄頁：https://www.skillhub.cn/plugins/goodjin/dsh-acp-agent
- GitHub：https://github.com/goodjin/dsh-acp-agent
