前言¶
用 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
