DeepSeek Super-agent：Router/Worker 架构与设置指南

从单仓库、单请求发起人开始试用

试用 DeepSeek Super-agent 时，先只接入一个仓库、只允许一名请求发起人，并使用专用操作系统账户。Router 将获授权的请求转为 Ticket，Worker 则使用各自独立的会话和目录。初期保持 observe 模式，但要清楚：显式请求仍然可以执行。

截至 2026 年 11 月 9 日，dsh-superagent-prototype 仍是研究代码，并非 DeepSeek 官方产品，也不是可用于生产环境的服务。其软件包清单声明版本为 0.1.0，采用 MIT 许可证。公开实现与团队内部系统及设计文章描述的方案也存在差异。

Router、Ticket 和 Worker 各自负责什么

核心变化是持续接收任务，而不是推出另一个模型或新的编码界面。这套组件包运行在 DeepSeek Harness 内，监听一个 GitHub 仓库，也可选择接收飞书消息。

领域模型将传入事件与获授权的工作区分开来。评估环节称为 Eval，负责判断候选事项是否值得新建 Ticket。每个被接受的 Ticket 都带有一份 Mandate，用于记录其授权依据和工作范围。

Router 是负责路由决策的主代理会话。Worker 负责执行已接受的任务，配置页面将这个 Worker 称为 Executor。

每个 Worker 都有自己的会话和工作目录。结果通过最初的对话返回，例如在 GitHub 评论中附上拉取请求（PR）。目录可以分开各个检出副本，却不能限制进程的读取范围。

例如，两份互不相关的缺陷报告可以变成独立的 Ticket，而不必共用同一个编码对话。当协调传入任务比启动单个编码任务更耗费精力时，这种方式就有价值。

如果只是交互式完成一项改动，继续使用现有的编码代理即可。对于范围明确的委派任务，可以先从只读且显式选择模型的 Claude Code 子代理开始。

为什么 observe 模式不是安全沙箱

observe 限制的是系统推断出的工作，而不是所有执行行为。授权规则允许在所有接收模式（accept mode）下接受显式请求。

在 observe 下，推断出的候选任务即便通过评估，也只会生成“would accept”记录，表示候选任务在 auto 模式下会被接受，但 observe 模式不会据此创建任务。在 auto 下，通过评估则可以接收这类推断任务。允许名单中的人员在提及代理时，可以在任何模式下请求执行任务。

允许名单不是唯一的准入控制。准入表中的单元格也可以向未列入名单的人员授予显式请求权限。应按下文配置仅允许一名请求发起人的策略，而不是只依赖 observe。

danger-full-access 意味着什么

使用一个只存放代理所需凭据的操作系统账户。部署指南中的隔离警告同时适用于 dsh-superagent-router 和 dsh-superagent-worker：它们均以运行者的操作系统用户身份运行，权限模式为 danger-full-access。

凭据包装层只负责选择账户，并不提供进程隔离。Worker 可以通过绝对路径运行程序，也能读取运行者的主目录。实现指南还表明，Router 同样拥有 shell 和文件读取工具。

首次试用应选择可随时弃用的机器或虚拟机，并为代理使用无管理员权限的账户。不要在该环境中放置个人凭据、生产环境密钥或无关仓库。这些是部署时需要自行采取的预防措施，并非原型提供的保护。

同时使用独立的 Harness 配置档案（profile）。插件会修改整个进程范围内的 PATH 和 Git 设置。让面板保持绑定到 127.0.0.1，不要把这次试用部署为公开 Web 服务。

设置仅接入 GitHub 的试用环境

在全新的账户和配置档案中按以下手动流程操作。仓库也提供了由代理引导的 SETUP.md。

检查前置条件

安装 Node.js 22.19+ 或 24+、pnpm、git 2.32+、Python 3.8+、tmux，以及 GitHub CLI 2.48+。这些是文档列出的前置条件。

你还需要 github.com 上的一个仓库，以及供 DeepSeek Harness 使用的模型提供商。不支持 GitHub Enterprise Server。目标仓库使用 Git LFS 时，还要安装 git-lfs。

使用一个非空且包含 README.md 的试用仓库。首次测试优先选择仅你和代理可访问的私有仓库。

飞书是可选项，不属于本次试用范围。其文档所述接入方式还需要一个已启用机器人功能的飞书或 Lark 应用，以及 lark-cli；项目测试使用的版本为 1.0.90。

只登录代理账户

创建专用的 GitHub 用户账户，并授予它试用仓库的写入权限。在专用操作系统账户下，使用 Bash 运行以下命令。

unset GH_TOKEN GITHUB_TOKEN
gh auth login --hostname github.com --git-protocol https
gh api user --jq .login
gh auth setup-git --hostname github.com

以代理账户完成 GitHub CLI 的交互式登录。gh api 命令必须显示代理账户的登录名。清除这两个变量可避免环境变量中的凭据覆盖已存储的登录信息。

单独执行的 gh auth setup-git 步骤会将 Git 配置为使用 GitHub CLI 作为凭据助手。这一步很重要，因为准备阶段和分支推送会直接调用 Git。

按照文档中的 GitHub CLI 克隆语法创建本地克隆：

read -r -p "Repository (owner/name): " TARGET_REPOSITORY
mkdir -p "$HOME/src"
gh repo clone "$TARGET_REPOSITORY" "$HOME/src/superagent-target"

然后独立检查 HTTPS 访问，不要只依赖 gh api 的结果：

GIT_TERMINAL_PROMPT=0 git ls-remote \
  "https://github.com/$TARGET_REPOSITORY.git" HEAD

GIT_TERMINAL_PROMPT=0 git -C "$HOME/src/superagent-target" push --dry-run \
  "https://github.com/$TARGET_REPOSITORY.git" \
  HEAD:refs/heads/agent-auth-check

git ls-remote 应返回远端的 HEAD 信息。对于公共仓库，这项读取操作即使匿名访问也可能成功。push --dry-run 检查会在不更新远端引用的情况下检查推送连接。两条命令都必须成功，但仍要把后续为创建 PR 而进行的真实推送作为最终交付验证。

这里直接使用 gh，是因为整个操作系统账户都专供代理使用。不要复用个人账户的多登录配置。

安装专用 Harness 配置档案

使用部署指南固定的 Harness 版本 0.2.1-rc.3。组件包的清单要求 engines.dsh 满足 ^0.2.1-alpha.2。

运行任何 dsh 命令前，先设置 DSH_HOME。固定版本的 CLI 参考文档将命名配置档案放在 $DSH_HOME/profiles/<name> 下。本次试用明确选用 $HOME/.dsh 作为 DSH_HOME 的位置。

以下 Bash 命令仅适用于全新安装：

export DSH_HOME="$HOME/.dsh"

npm install -g @deepseek-ai/dsh@0.2.1-rc.3
git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git
cd dsh-superagent-prototype
pnpm install
pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"

不要在已有安装上重新运行创建配置档案的命令。 该命令会替换配置档案，并删除其中的 cordis.patch.yml。已有安装应改用部署指南中的升级流程。

写入机器配置前，先确认配置档案的清单文件存在。在同一个 Bash shell 中继续执行：

test -f "$DSH_HOME/profiles/superagent/package.json" || exit 1

cat > "$DSH_HOME/profiles/superagent/cordis.patch.yml" <<EOF
- id: webserver
  config:
    host: 127.0.0.1
    port: 3082
- id: dsh-superagent
  config:
    stateDir: "$DSH_HOME/state/superagent"
EOF

if tmux list-sessions >/dev/null 2>&1; then
  tmux set-environment -g DSH_HOME "$DSH_HOME"
  if tmux has-session -t '=dsh-superagent' 2>/dev/null; then
    tmux set-environment -t '=dsh-superagent' DSH_HOME "$DSH_HOME"
  fi
fi

scripts/dsh-superagent start
scripts/dsh-superagent status

服务脚本通过 tmux 启动 dsh --profile superagent。新启动的 tmux 服务器会继承已导出的环境变量。上述代码块也会更新已有服务器或会话的 tmux 环境变量。

在服务器所在机器的浏览器中打开 http://127.0.0.1:3082。在 Harness Settings 中，Open configuration file 应打开上面的 superagent/cordis.patch.yml 路径。如果指向其他位置，停止操作。添加提供商设置后，不要再次覆盖这个补丁文件。

在侧栏中选择 Superagent。完成仓库和账户设置前，出现初始设置警告是正常现象。配置任务接入前，先完成下文的模型选择部分。

配置任务接入和每个 Ticket 的工作树

使用 Superagent → Settings 中文档列出的设置分组。

在 Sources → GitHub 中，将仓库设为你的 owner/name，代理 CLI 设为 gh。让 Issues、拉取请求、评论和默认分支 CI 对应的 receive-all（全部接收）开关保持关闭。保持飞书禁用。

在 Eval → On each Source → GitHub 中，让 GitHub accounts that may originate work 只包含你本人使用的 GitHub 登录名。移除其他条目，机器人列表保持为空。将所有可见的、针对未列入名单人员的准入单元格设为 ignore，包括这些人员点名或 @ 提及代理时对应的单元格，无论是否直接提出任务，都应设为 ignore。将接收模式设为 observe 并保存。

这些针对未列入名单人员的默认值定义在准入矩阵中。它们限制的是新任务请求，不会阻止已订阅讨论中的消息作为上下文传入现有 Ticket。试用期间应把对话参与者限制为你和代理。

在 Execution 中，先将并发数设为 1，作为试用设置。保留默认的目录根路径。将以下内容粘贴到准备命令字段中；该命令在 sh 下运行，其语法也适用于 Bash。

git -C "$HOME/src/superagent-target" fetch --no-tags \
  "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C "$HOME/src/superagent-target" worktree add \
  -b "agent/$DSH_SUPERAGENT_NAME" \
  "$DSH_SUPERAGENT_DIR" \
  "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"

这段命令根据上面创建的本地克隆，调整了部署指南中的工作树示例。它会获取对应的 head，并创建该 Ticket 的分支和检出副本。如果不配置准备命令，Worker 会在空目录中启动。

在 Prompts 中，设置代理提交代码时使用的身份信息和身份披露文本。要求由人工合并，不要提供单独的合并账户。提示词只起指导作用，并不是强制执行的仓库保护措施。

能否使用其他模型

可以，通过 DeepSeek Harness 中配置的提供商使用其他模型即可。标签 dsh-v0.2.1-rc.3 下的提供商指南为本次安装的版本说明了以下操作路径。

打开 Harness Settings → Models。在 DeepSeek 卡片中输入并保存 API 密钥，或选择 Add model provider 添加其他受支持的提供商。凭据应在本地 UI 中输入，不要发布到 GitHub 讨论中。

对于 Custom model API，需要提供小写的 Provider ID、基础 URL、匹配的 API 协议、凭据，以及至少一个模型。使用提供商文档中给出的值。保存提供商并不能证明其模型可以完成所需的工具调用。

接下来，按照固定版本的 Web UI 指南，通过 Choose workspace 添加并选择 $HOME/src/superagent-target。启动普通会话，在模型选择器中选择已配置的模型。这一选择会设置新会话的默认模型。

再新建第二个会话，发送请求前先确认它显示相同的提供商和模型。让模型读取 README.md，不修改文件，只返回首个标题。将回答与文件内容对照。此次测试不要使用两个受管理的 dsh-superagent-* 预设中的任何一个。

随后，在 Superagent → Settings → Eval 和 Execution 中，显式选择已经测试过的提供商和模型。Eval 指定 Router/评估所用的模型，Execution 指定 Worker 所用的模型。本次试用不依赖未经确认的回退行为。只有在验证了配置档案的默认模型后，才适合将任一模型覆盖设置留空。

Executor 的模型选择在创建会话时生效。已有 Worker 会话会保留原来的模型，Retry 也会复用同一个会话。后续更换模型时，要用新 Ticket 验证变更。

验证一次完整请求，并定位失败环节

请求代码改动前，先验证完整的 GitHub 请求与回复流程。面板正在运行，并不能证明授权、准备步骤和模型调用都能正常工作。

首先，重新运行 scripts/dsh-superagent status。必须返回退出码 0，且没有设置问题。使用允许名单中的人工账户，在 issue 中发布一条新评论，将 @AGENT_LOGIN 替换为代理的登录名：

@AGENT_LOGIN 读取 README.md，并在这里回复它的首个标题。
不要编辑文件、推送分支或创建拉取请求。

按照部署指南中的试用流程，生成的 Ticket 会出现在 Overview 中。验收时必须确认：代理在原始 GitHub 对话中回复了正确的标题。

这一步成功后，再请求一项小范围文档改动，并要求创建 PR 供人工审核。确认分支确实已推送、PR 由代理账户创建，且 diff 未超出任务范围。这些是验收检查，不是对模型结果的保证。

如果没有生成 Ticket，检查允许的登录名、准入单元格、仓库以及 GitHub Source 的健康状态。然后发布一条新的评论，并在其中提及代理。

服务失败时，服务脚本以退出码 1 表示进程或运行时问题，2 表示组件错误，3 表示设置未完成。重启可能有助于解决 1；对于 2 或 3，应修复所报告的原因。

对于暂时性的模型或网络故障，执行指南规定进行三次重试，退避等待时间逐次增加。适用情况包括 HTTP 408、429 和 5xx。准备命令失败不在自动重试范围内。

恢复失败的准备步骤

选择 Retry 前，先检查记录的准备错误和 Ticket 目录。启动实现只在该目录不存在时执行准备步骤。已有目录会被视为准备完成，即使其中的工作尚不完整。

目录不存在时，修正凭据或准备命令的问题，然后选择 Retry。这次启动会再次尝试准备。

目录已存在时，从 Ticket 详情中复制它的路径，并在 Bash 中检查：

read -r -p "Ticket directory (absolute path): " TICKET_DIR
git -C "$TICKET_DIR" rev-parse --show-toplevel
git -C "$TICKET_DIR" status --short --branch

报告的顶层目录必须是 Ticket 目录，而不是父级检出目录。检查分支与工作树状态、应当存在的文件，以及此前失败的每个准备步骤。

只有补齐并验证准备工作后，才应对已有目录重试。Retry 不会重新构建它。对于不完整且无法安全恢复的检出副本，应将其保留，停止该 Ticket，修复命令，再提交一个新的 issue 请求。继续之前，确认替代 Ticket 使用的是新目录。

Ticket 一旦失败，CI 和机器人消息就不会唤醒它的 Worker，必须由人员介入。试用结束后停止服务：

scripts/dsh-superagent stop

什么时候值得持续运行

只有当路由决策和交付改动的价值足以抵消运维投入时，才值得继续运行这个原型。先从小范围开始，在衡量有效产出和提供商用量后再提高并发数。

比较每项验收通过的改动的成本，而不是只看模型价格。将路由、评估、Worker 调用和恢复过程都纳入试用预算。编码代理单任务成本指南提供了将模型及其配套 harness 一并比较的框架。

不要将内部演示等同于当前检出的代码。仓库提醒，更完整的设计文章中描述的部分方案尚未实现。在你自己的验收检查足以支持扩大部署范围之前，部署应始终保持环境隔离，并由人工审核。