2026 DeepSeek Harness 插件更新怎么做灰度发布？

先把发布风险拆成五个控制点

DeepSeek Harness 的特殊之处在于，模型适配器、工具注册、会话记录、Agent 循环等部分都以插件形式组成，Cordis 负责插件树、服务、事件和可逆效果的组合。官方架构文档还说明，运行中的配置由 profile、bundle 和 patch 逐层叠加，因此只看插件名称，无法判断实际启动了哪一套组合。(github.com)

这会带来至少四个容易被忽略的风险：

• 组合风险：单个插件看似只改了一个功能，但它可能同时依赖特定 Harness、Cordis 接口或其它 bundle。
• 配置风险：配置文件、profile 顺序、patch 覆盖关系发生变化时，插件可能“已加载但行为不同”。
• 权限风险：新版本可能新增工具、扩大文件访问范围、改变审批方式或修改沙箱默认值。
• 会话风险：服务重启成功，不等于原来的 Agent 任务能够继续运行；内存状态、会话持久化和任务游标可能分别失效。
• 执行面风险：如果正式环境只有一台 Mac，更新、重启和排错都会直接影响共享 Agent 或持续任务。

官方在开发指南中将 Host 与 Client 分成两个独立聚合，并要求插件注册到对应的构建面；这说明“能安装”与“能在完整运行链路中工作”不是同一件事。(github.com)

第一阶段：更新前锁定完整组合

更新前不要只记录类似“安装了插件 A、插件 B”。可回退的对象应当是完整组合，至少包括：

1. Harness 的 Git 标签、提交号或发行包版本。
2. 每个插件的来源、提交号、包版本和安装方式。
3. pnpm-lock.yaml 或实际使用的其它锁文件。
4. profile、bundle、cordis.patch.yml 以及启动参数。
5. Node.js、包管理器和系统架构等运行环境信息。
6. 一个当前确实可以完成的基准任务及其输出摘要。
7. 启动日志、插件发现日志、工具清单和权限状态。

官方仓库当前的开发指南显示，项目支持 Node.js 22.19+、24+ 和 26，并固定使用 pnpm@11.7.0；这类运行时约束应当作为回退证据的一部分保存，而不是只在维护者记忆中保留。(github.com)

可以先在当前环境执行以下记录动作：

node --version
pnpm --version
git rev-parse HEAD
git status --short
sha256sum pnpm-lock.yaml
dsh --profile web --dump-config > before-config.txt

输出示例应类似：

v24.x.x
11.7.0
<当前 Harness 提交号>
<空输出或已知工作区变更>
<锁文件校验值>
<当前实际启动的配置行>

其中版本号和校验值只是当前环境产生的结果，不应把示例中的占位内容直接写入发布记录。若团队使用 npm 安装方式，则应同时保存实际包清单和 package-lock.json；官方 README 明确支持从 npm 启动 Web UI，也支持从源码通过 pnpm install、构建后运行。(github.com)

团队是否应把插件版本固定在同一套已验证组合上？

需要统一锁定“经过验证的完整组合”，但不必强行让所有开发者永远使用同一版本。更稳妥的做法是：正式环境使用经过验收的锁文件；验证环境允许测试候选版本；只有候选组合通过后，才更新团队基线。这样既能控制生产风险，也不会阻塞插件作者验证新接口。

本阶段的进入条件是：当前任务已停止无回退路径的自动更新，并且旧组合可以重新安装或重新启动。成功证据是版本、锁文件、配置和基准任务输出都已归档；如果其中任何一项缺失，应回到当前组合补齐记录，而不是进入下一阶段。

第二阶段：创建不接触真实副作用的验证面

验证环境可以是独立工作区，也可以是独立的远程 Mac。关键不是“换了一台机器”本身，而是验证环境必须复用正式环境的安装路径逻辑、启动方式和配置层级，同时去掉真实客户凭据、生产密钥和不可逆任务。

建议复制：

• 与正式环境相同的 profile 和 bundle 结构；
• 与正式环境相同的启动命令；
• 脱敏后的配置和测试工作区；
• 可重复的最小任务输入；
• 用于比较的旧版工具与权限清单。

不要复制：

• 客户 API 密钥；
• 生产数据库连接；
• 付款、删除、发布或外发任务；
• 正在运行的真实会话数据库；
• 无法撤销的自动化凭据。

如果正式环境只有一台 Mac，不能把它一边当生产执行面、一边当验证环境。更安全的路径是先准备第二执行面；短期测试可以参考 云端 Mac 稳定与验证双轨环境，需要特定地区节点时，再按实际网络条件比较 不同远程 Mac 方案。

验证环境还应记录启动入口。例如源码构建链路可按照官方开发指南执行：

pnpm install
pnpm run typecheck
pnpm run build
pnpm dsh web

pnpm run typecheck 成功只能证明类型检查通过，不能证明插件在运行时可以加载；pnpm run build 成功也不能证明旧会话能够续跑。因此，构建结果只能作为进入运行时验证的条件之一。(github.com)

中段决策表：什么情况下可以推进

这张表的核心判断是：任何一轮失败，都不应只降级一个插件。如果 Harness、插件和依赖同时发生变化，只回退其中一个包，很容易留下未经测试的混合版本。

第三阶段：先验证加载，不要急着跑写入任务

第一轮只验证加载和配置契约，目标是回答三个问题：

• Harness 是否能发现候选插件；
• 配置是否能被正确读取；
• Host 与 Client 是否都能完成启动。

可以先导出实际配置树：

dsh --profile web --dump-config > candidate-config.txt
diff -u before-config.txt candidate-config.txt

官方架构文档说明，profile 会按顺序叠加 bundle、profile 级 patch、Home 级 patch 和命令行 overlay；配置行出现变化时，应先确认变化来自哪个层，而不能简单归因于某个插件。(github.com)

此阶段不要运行文件写入、外部发布、删除、发送消息或其它带副作用的工具。应记录真实错误，包括插件发现失败、模块解析失败、配置字段不识别、Host/Client 类型不一致和启动后立即退出。不要根据插件名字推断兼容性，也不要把社区插件的兼容声明当成官方承诺；应直接核对目标插件源码、Release 说明和锁文件。

截至当前官方资料，dsh-plugin 只是用于插件仓库发现的主题标识；它不能证明插件已经通过某个 Harness 版本的兼容测试。(github.com)

第四阶段：用最小任务验证工具与权限边界

加载通过后，再选两个任务：

• 一个只读任务，例如读取测试工作区中的固定文件并返回摘要；
• 一个可以完整撤销的写入任务，例如在临时目录创建测试文件，再由维护者删除。

这一步重点不是任务复杂度，而是比较更新前后的能力清单：

旧组合：
- 可发现工具：
- 需要审批的工具：
- 工作区范围：
- 外部网络能力：
- 默认沙箱策略：

候选组合：
- 可发现工具：
- 需要审批的工具：
- 工作区范围：
- 外部网络能力：
- 默认沙箱策略：

如果候选版本多出工具、扩大路径范围、取消审批或改变默认工具，即使最小任务成功，也不能直接进入分批发布。权限扩大必须单独审批，并在发布记录中写明原因、影响范围和回退方式。

对于 Cordis 相关变化，尤其要注意“插件可以被挂载”和“插件的服务契约保持不变”是两件事。官方架构说明插件卸载时会回收注册效果，但这不代表已经产生的文件、网络请求或外部任务可以自动撤销。(github.com)

第五阶段：验证会话、持久化和重启

会话回归应分成三层：

1. 新建会话后执行一个短任务，确认消息、工具调用和结果返回正常。
2. 关闭并重新启动 Harness，确认配置和会话索引仍可读取。
3. 恢复一个尚未结束的测试任务，确认它能从正确状态继续，而不是重新执行、丢失上下文或静默跳过步骤。

“服务重新启动成功”不能作为“原任务能够续跑”的证据。尤其是长期 Agent，必须分别记录会话 ID、最后一个已确认步骤、任务状态和重启后的恢复结果。

rc.7 的官方发布说明提到，插件可以注册自己的设置卡片，同时修复了部分会话保留、历史消息分页和持久 Bash 问题；这些变化说明 UI、会话和插件设置都可能影响回归范围，但不意味着所有第三方插件都已获得稳定兼容承诺。(github.com)

第六阶段：按风险逐批切换远程 Mac

远程 Mac 上应怎样安排 Harness 插件的分批发布？

建议按风险而不是按机器编号分批：

1. 先切换没有共享会话、没有外部写入的低风险任务。
2. 观察启动日志、工具调用、错误率和会话恢复结果。
3. 确认本批次没有权限扩大或结果格式变化后，再切换共享工作区。
4. 最后处理长期 Agent 和持续任务，并提前安排可控的暂停窗口。
5. 每批都保留旧组合，不要在确认前覆盖唯一回退目录。

远程 Mac 的切换操作应尽量做到“新旧目录并存、启动入口可切换、日志独立保存”。如果只能通过远程桌面操作，也应保留 SSH 或其它管理通道，避免 Web UI 启动失败后失去控制面。

一个简化的发布记录可以这样写：

批次：低风险测试工作区
旧组合：<完整版本记录>
候选组合：<完整版本记录>
切换时间：<具体时间>
加载：通过
只读任务：通过
可回退写入：通过
权限差异：无
重启恢复：通过
观察结论：允许进入下一批

如果某批出现插件加载失败、工具清单异常、权限扩大、会话无法恢复或持续任务中断，应立即停止扩大范围，并执行整组回退：

# 停止候选进程后，恢复已知可用的完整工作目录
mv "$DSH_HOME" "${DSH_HOME}.failed"
mv "${DSH_HOME}.known-good" "$DSH_HOME"

# 按已归档锁文件恢复依赖
pnpm install --frozen-lockfile

# 再次检查实际启动配置
dsh --profile web --dump-config > rollback-config.txt

上面的目录名是运维示例，实际路径必须以团队归档记录为准。回退完成后，不要只看进程是否重新出现，应重新执行一个基准任务，并确认共享 Agent、会话索引和配置持久化均恢复正常。

dsh-plugin 更新失败时，怎样把系统恢复到最后一套可用状态？

最快的回退路径不是临时寻找“上一个插件版本”，而是恢复最后一套完整已知组合：Harness 版本、插件版本、依赖锁文件、profile、patch、运行时和启动参数必须一起恢复。若旧版本只存在于某个被覆盖的目录、缓存或开发者电脑中，回退速度就会被重新安装和重新排错拖慢。

发布结束后，还应记录版本负责人、批准人、回退负责人，以及下一次复核条件。每当官方 Harness 候选版、插件 API、Cordis 接口或配置目录变化时，都应重新核对目标插件源码、Release 和锁文件，而不是继续沿用旧的兼容判断。

当前方案与 Mac 灰度环境的取舍

把所有插件直接更新在本地唯一 Mac 上，常见缺点是：没有并行旧环境、重启会打断共享任务、失败后只能临时拼装依赖，而且真实凭据和测试副作用很难彻底隔离。纯云主机方案又可能遇到 macOS 专属工具链、远程桌面体验和本地权限模型不一致的问题。

如果只是长期稳定重负载、必须连接固定物理设备，直接自购并维护独立 Mac 可能更合适；但如果需求是短期验证新插件、保留旧组合、按批次切换远程 Mac，NodeMini 提供的 Mac 环境更适合作为第二执行面。先准备可立即恢复的旧组合，再把验证和回归任务放到独立环境中，通常比拿生产唯一实例承担更新风险更稳妥。需要临时算力或测试环境时，可进一步查看 NodeMini 的 Mac 远程算力方案。

最后可按下面的清单验收：

• [ ] 已停止无回退路径的自动更新。
• [ ] 已保存 Harness、插件、依赖、配置和运行时证据。
• [ ] 已建立独立工作区或独立远程 Mac。
• [ ] 已确认验证环境不含真实客户凭据。
• [ ] 已完成插件加载和配置读取检查。
• [ ] 已完成只读任务与可回退写入任务。
• [ ] 已比较工具清单和权限边界。
• [ ] 已验证新会话、旧会话、持久化和重启恢复。
• [ ] 已保留整套旧组合，而不是只保留单个旧插件。
• [ ] 已明确每一批的观察窗口、负责人和回退动作。
• [ ] 已记录下一次因 Harness、Cordis 或插件 API 变化而触发的复核条件。