DeepSeek AI 于 2026 年 11 月 11 日在 GitHub 发布了开源智能体框架 DeepSeek Harness（简称 dsh） 的预发布版本 v0.2.2-rc.2。作为 0.2.2 系列的第二个候选版本，本次更新共包含 76 项改动（3 项新功能、27 项体验优化、26 项问题修复及 20 项其他变更），核心围绕开发流程闭环展开：将 Git 工作树推进至支持 GitHub PR 评审收口，把多智能体协作重构为具名多层 SubAgent 与会话级 AgentTeam，并将网页搜索与抓取拆分为独立计费的 DeepSeek Search/Fetch API。
需要注意的是，截至 2026 年 11 月 13 日，npm 仓库的 latest 标签仍停留在 0.2.2-rc.1，v0.2.2-rc.2 位于 next 预发布渠道。本文整理了该版本的核心机制变化、升级风控清单，以及官方账号与第三方中转站（如 4SAPI）的大模型 API 接入配置方法，供开发者评估与迁移参考。
一、版本渠道与安装方式：为什么直接升级拿不到 rc.2？
DeepSeek Harness 基于 Cordis 元框架构建，采用“一切皆插件（Everything is a plugin）”的微内核架构。由于 v0.2.2-rc.2 仍带有预发布（Pre-release）标记，包管理器默认不会将其推送给常规安装用户。
| npm 分发渠道（dist-tag） | 当前对应版本 | 适用场景说明 |
|---|---|---|
latest |
0.2.2-rc.1 |
执行默认安装或常规全局升级时获取的基准版本 |
next |
0.2.2-rc.2 |
本次更新所在的候选版本渠道，适合测试环境尝鲜 |
alpha |
0.2.2-alpha.3 |
更早期的实验性开发分支 |
运行 DeepSeek Harness 需要 Node.js 24.9.0 及以上版本。在升级或试用前，建议先核对本地运行环境与渠道标签，再通过指定精确版本号的方式启动：
node -v
npm view @deepseek-ai/dsh dist-tags --json
npx @deepseek-ai/dsh@0.2.2-rc.2 web
如果使用桌面端应用，v0.2.2-rc.2 已在设置面板中新增“正式版 / 开发版”更新渠道切换开关，客户端是否推送 rc.2 以所选渠道为准。
二、三大核心能力升级：从“单点可用”走向“流程收口”
1. Git 工作树评审：在同一会话内完成 PR 收口
在 rc.1 引入实验性“变更请求与工作树（Worktrees）”的基础上，v0.2.2-rc.2 补齐了代码评审与迭代收口的完整链路：
- 多维度筛选 Diff：支持按分支、具体提交（Commit）以及文件类型三个入口过滤变更范围，在面对大型 Pull Request 时可快速聚焦核心代码文件。
- 会话内处理 GitHub 评审：可直接在 DSH 界面内查看并回复评审评论、同步文件已审阅进度以及拉取分支更新，无需在浏览器与本地终端之间频繁切换。
- 大仓库交互优化：改进了评论线程渲染、文件树导航及窄屏布局，减少了浏览大型改动时的界面卡顿，并放宽了大型代码仓库创建工作树的超时阈值。
使用边界与注意事项： 工作树组合包随安装包内置，但默认处于关闭状态，需前往「插件管理」中手动启用（其他 Profile 亦可单独挂载工作树工具包）。在日常使用时需留意四条底层机制：
- 工作树仅基于本地已有的提交、分支或标签创建，不会自动执行
git fetch拉取远端缺失对象。 - 源工作区中的暂存（Staged）、未暂存、未跟踪（Untracked）及
.gitignore忽略文件均不会被复制到新工作树中。 - 默认检出路径为
<当前仓库>/.agents/worktrees/<name>，退出当前工作树视图时，本地目录与对应分支会继续保留。 - 归档会话时系统默认自动清理符合条件的 Git 工作树目录（分支与提交记录会保留）；若需保留本地目录，需在设置中关闭归档清理。
2. 具名 SubAgent 与 AgentTeam：多智能体协作结构化
针对多 Agent 并发任务中“派发容易、追踪难”的痛点，rc.2 对子代理与团队协作模型进行了统一重构：
| 协作模式 | 核心定位 | v0.2.2-rc.2 关键改进 |
|---|---|---|
| SubAgent（子代理） | 将独立、边界清晰的子任务委派给下级执行 | 支持具名标识与多层嵌套协作；层级浏览器优先展示任务描述，支持逐层展开及读取失败后重试 |
| AgentTeam（智能体团队） | 单一会话内的多成员协同作战（临时项目组） | 支持按会话独立开启，提供共享成员列表与任务看板；SDK 支持配置新建会话默认启用 |
迁移与并发提示：
- AgentTeam 底层已切换为统一的具名子代理实现，且默认关闭中断工具；依赖旧版子代理行为的自定义插件或 SDK 集成需按新版接口调整。
- 若多个进程共享同一份会话存储，升级时必须保证所有进程同步更新，防止新旧版本对会话状态结构解析不一致。
- 官方文档特别指出，AgentTeam 中的
writeScopes属于提示性路径前缀，用于辅助识别写入范围重叠，并非操作系统级文件锁。并发修改代码时仍需人为划分清晰的文件职责边界。
3. 搜索链路独立：DeepSeek Search 与 Fetch 分离计费
v0.2.2-rc.2 将默认网页搜索切换至 DeepSeek Search API，并允许搜索（Search）与网页抓取（Fetch）分别绑定独立的凭据与计费方式。
早期版本的网页搜索往往依赖完整的辅助模型轮次进行检索总结，容易带来额外的响应延迟与 Token 消耗；新版将其拆分为直接检索与正文提取两个独立端点：
| 工具能力 | 返回数据结构 | 支持的凭据与计费模式 |
|---|---|---|
| Search（网页搜索） | 标题、URL、Snippet 摘要、Summary 总结、发布时间 | 自动（跟随会话路由）/ 已登录账号 / 独立 API Key |
| Fetch（网页获取） | 目标网页转换后的纯 Markdown 正文 | 自动（跟随会话路由）/ 已登录账号 / 独立 API Key |
配置入口位于 「插件 > 内置插件配置 > 网页搜索与获取」。升级前建议核查三项状态：
- 旧配置兼容性：自定义或旧版搜索 Provider 需按升级指南重新映射，避免配置失效。
- 凭据回退机制：选择
auto时会跟随当前会话的模型路由凭据；若显式指定了固定账号或固定 API Key，当该凭据余额不足或失效时，不会自动回退到另一种凭据。 - 工具可见性：若未配置有效凭据，
web_search或web_fetch工具可能会直接从发送给模型的工具列表中移除。若调用时出现401或403报错，应优先检查计费模式与凭据状态，再排查网络连通性。
三、DeepSeek Harness 接入大模型 API 配置指南
DeepSeek Harness 将模型适配模块设计为可插拔的 Provider 插件，无需修改源码即可在设置面板中切换底层模型。在实际部署中，主要有官方渠道与国内托管中转站两种接入路径。
方式一：官方账号登录或官方 API Key 接入
如果工作流以 DeepSeek 原生模型为主，且具备直接访问官方服务的条件，可采用以下两种标准方式：
- 官方账号授权登录
- 适用场景：已有 DeepSeek 官方网页端或客户端账号，希望直接复用账号额度。
- 配置路径：在 DSH 界面右上角或「设置 > 账号与模型」中登录官方账号。绑定后，常规会话以及网页搜索的
auto模式将默认消耗该账号下的可用额度。
- 官方 API Key 接入
- 适用场景：需要将开发环境与个人账号额度隔离，或通过 CLI 与自动化脚本按量调用。
- 配置路径：前往 DeepSeek 开放平台创建 API Key，进入 DSH 的 「设置 > 模型（Models）」，选择内置的 DeepSeek Provider 并填入密钥即可（rc.2 已新增密钥掩码预览与一键替换功能）。
方式二：通过国内托管中转站接入（如 4SAPI）
如果在 AgentTeam 或多层 SubAgent 场景下需要混合调用不同厂商的模型（例如主节点使用强推理模型规划任务，子节点调用轻量模型处理检索），或者受限于海外账号注册与跨境网络环境，也可以通过国内托管的 API 聚合中转站（例如 4SAPI）进行统一接入。
这类方案在工程实践中的主要作用是接口归一化与网络直连：DSH 原生支持自定义 OpenAI 兼容端点，中转站将 DeepSeek、Claude、GPT 等不同厂商的模型统一封装为标准的 OpenAI 协议格式，并聚合为单一令牌与按量账单，省去了在多个海外平台分别维护密钥和网络代理的麻烦。
配置步骤：
- 获取接口信息：在中转站控制台创建 API 令牌（Key），并确认对应的 OpenAI 兼容接口地址（通常以
/v1结尾）。 - 添加自定义 Provider：打开 DSH 的 「设置 > 模型」，新增自定义 OpenAI 兼容端点，填入
Base URL与API Key。 - 拉取可用模型：借助 rc.2 新增的模型发现（Model Discovery）功能自动获取模型列表（也可手动填写模型 ID 及推理等级
reasoning level），保存后即可在对话窗口顶部按需切换。
四、升级前必读：六项兼容性变更与四步验收清单
除上述核心特性外，v0.2.2-rc.2 还调整了六项底层运行行为，升级前建议逐一对照检查：
| 变更模块 | 具体影响 | 升级前应对动作 |
|---|---|---|
| MCP 动态注册与移除 | 插件可在运行时动态管理 MCP 服务、探测状态与重启 | 检查是否存在同名服务冲突，核对重连策略与插件权限 |
| Office 原生解析工具 | 文档解析直接在 DSH 主进程运行，不受命令行沙箱限制 | 迁移旧版文档处理插件；涉及敏感数据的文档需单独隔离 |
| PTC 工具预算限制 | 代码执行超出预算会直接终止并清空内存状态，已执行的外部副作用不会回滚 | 将长耗时任务拆分为小批次，增加检查点并确保操作幂等 |
| Agent 终端接管 | 用户在侧边栏接管终端输入的内容可进入模型上下文与会话记录 | 切勿在被接管的终端内明文打印密钥或环境变量 |
| 归档工作树清理 | 会话归档默认删除符合条件的本地工作树目录（保留分支） | 若依赖工作树目录留存编译产物，提前在设置中关闭自动清理 |
| 原生与自定义模型接口 | 支持模型自动发现与推理强度（reasoning level）参数透传 | 核对自定义模型 ID 命名规范及推理参数兼容层差异 |
此外，新版已在模型设置中开放请求失败后的重试条件、重试次数与退避等待时间配置；Computer Use 默认不再接管移动系统物理鼠标，依赖该特性的自定义脚本需同步更新。
四步安全升级验收流程
- 锁定精确版本：确认本地 Node.js $\ge$ 24.9.0，使用
npx @deepseek-ai/dsh@0.2.2-rc.2 web启动，避免依赖latest标签自动覆盖。 - 备份配置与环境隔离：提前备份本地 DSH 配置目录；建议先在独立的测试目录或副本 Git 仓库中验证新版本，避免直接在主力开发工作区中升级。
- 逐项恢复插件与模型路由：按需开启工作树、AgentTeam 与网页搜索插件，核对官方账号或自定义 API 节点的连通性与计费归属，避免一次性全量开启所有实验性插件。
- 最小闭环功能验收：在测试仓库中完整走通一次“创建工作树 $\rightarrow$ 查看 Diff $\rightarrow$ 归档清理”，并分别发起一次 Search 与 Fetch 请求确认返回正常，再逐步迁移日常工作流。
常见问题（FAQ）
Q1：DeepSeek Harness v0.2.2-rc.2 是正式稳定版吗？
不是。GitHub 已将其标记为预发布（Pre-release），npm 的 latest 分发标签目前仍指向 0.2.2-rc.1。rc.2 位于 next 渠道，适合愿意在隔离环境中提前体验工作树评审与新版多代理协作的开发者。
Q2：为什么执行 npm install -g @deepseek-ai/dsh 安装的不是 rc.2？
因为 npm 默认拉取 latest 标签对应的版本（即 0.2.2-rc.1）。如需安装或运行 rc.2，必须在命令中显式指定完整版本号：npx @deepseek-ai/dsh@0.2.2-rc.2 web。
Q3：归档会话时自动清理工作树，会导致写好的代码丢失吗？
不会丢失已提交的代码。归档清理仅移除 .agents/worktrees/ 下的本地工作目录，Git 分支与所有 Commit 记录都会完整保留。但需注意，工作树创建时本就不会复制未提交或未跟踪的文件，日常开发中应及时 Commit。
Q4：实际开发中该如何选择 SubAgent 和 AgentTeam？ 如果只需将单一、独立的任务（如“检索某个模块的定义”或“生成单元测试”）外包出去，使用 SubAgent 更为轻量；如果需要在同一个会话内让多个角色围绕共享任务板协同推进复杂需求，则建议按会话开启 AgentTeam，并提前规划好各成员的文件写入范围。
Q5：升级后网页搜索报错 401/403 或工具消失怎么办？ 请前往「插件 > 内置插件配置 > 网页搜索与获取」，分别检查 Search 与 Fetch 选用的 Provider 及计费模式。若选择固定账号或固定 API Key，系统不会在凭据失效时自动回退；当缺少有效凭据时，搜索工具会直接从模型可用工具列表中撤下，补全对应凭据即可恢复。
DeepSeek Harness v0.2.2-rc.2 的重点不在于单纯增加功能数量，而是将工作树评审、多智能体分工和网页搜索这三条高频链路补全为可追踪、可收口的开发流程。在模型接入层，无论是绑定官方账号还是通过 OpenAI 兼容中转站统一调度多模型，框架本身都已提供标准化的配置入口。鉴于该版本仍处于预发布阶段，建议先在隔离环境验证插件与凭据兼容性，再决定是否替换日常使用的 rc.1。