DeepSeek Harness 团队提出的 Super-agent 把 Agent 从"你问一句、它答一句"的单会话工具，改成常驻在线、由事件驱动、可以并行推进多项工作的协作者。本教程先讲清它的双层结构（Router 与 Worker）定义及具体分工，再用官方开源原型插件 dsh-superagent 在本机跑通该架构的完整链路：从 GitHub 上的一条评论开始，到工单建立、执行器开工、分支推送、PR 产出，做到每一步都在面板上留下可核对的记录。

前置教程

1. Super-agent 要解决什么问题

主流 Agent 以单个 Session （会话）为基本单位。你同时推进三件事，就需要开三个会话，手动切换、手动维护各自的上下文。一般而言一个人同时只能跟住 3 到 5 个活跃会话。

DeepSeek 团队的判断是：模型执行单个任务越来越少需要人盯着，限制生产力的环节已经从"模型能力"挪到了"人的注意力"。单任务的上限取决于模型，多任务的上限取决于你的注意力能不能分得过来各个任务，也就是说，人脑的“上下文空间”是否够用。

Super-agent 的解法是不让你必再管 Session。Session 变成实现细节，你只面对一个常驻的入口。它有一下四项特征：

特征 含义 对应机制
连续 在 IM、GitHub 评论等不同信道与同一个 Agent 交互 多个 Source （信息源）汇入同一个 Router（路由）
高效 并行完成多个复杂任务 上下文隔离的 Worker 会话池
主动 持续观察环境事件并自行推进 Trigger （触发器）+ 投机执行
持久 始终在线、异常自动恢复 云端无状态计算 + 本地 daemon （守护进程）+ Watchdog（看门狗）

官方给出的初步实验数据（合成负载，约 300 条消息、其中 20 条为工作请求，每种方案重复 5 次）：

指标 Super-agent 单会话 + 子助手（中性提示）
完成时间 p50 12.4 分钟 —
完成时间 p95 15.7 分钟 29.5 分钟

官方同时限定：这组数字衡量的是系统调度与协作能力，不是单个任务的实际执行能力。

2. 双层架构：Router 只调度，Worker 只执行

整套设计由一个常驻的路由层和一组隔离开的执行会话组成。路由层不干活，执行层不对人说话。

graph LR E1[GitHub 评论] --> F[程序层过滤
白名单 / 来源 / 范围] E2[CI 结果] --> F E3[IM 群消息] --> F F -->|通过| S[语义评估
这批触发该不该接] F -->|拦下| X[丢弃并记数] S -->|接单| R[Router 层
常驻 · 只调度] S -->|忽略| X R --> W1[Worker A
独立会话 + 独立目录] R --> W2[Worker B] R --> W3[Worker C] W1 --> D[PR / 原会话回复] W2 --> D W3 --> D style E1 fill:#ffecd6,stroke:#b7950b style E2 fill:#ffecd6,stroke:#b7950b style E3 fill:#ffecd6,stroke:#b7950b style F fill:#e8f4f8,stroke:#1a6b8a style S fill:#d6eaf8,stroke:#2980b9 style R fill:#ebdef0,stroke:#8e44ad style W1 fill:#d5f5e3,stroke:#27ae60 style W2 fill:#d5f5e3,stroke:#27ae60 style W3 fill:#d5f5e3,stroke:#27ae60 style D fill:#fadbd8,stroke:#c0392b style X fill:#fadbd8,stroke:#c0392b

Router 层的三件事：接（待）人、判活、分派。它充当全局序点、协调点和记忆，承接所有入口的人类交互，自己不下场改代码。官方在实践中给它配较轻量的模型，因为它一次只做判断，不做实现。

Worker 层是一条工单对应一个会话、一个目录。它挂满执行工具，在独立上下文里专心做一件事，做完把状态和结果报回 Router，由 Router 统一对外沟通。因为直接决定代码质量，Worker 配能力最强的模型。

两层之间还有三个配套机制：

  • 两级过滤：程序层按来源、群组、用户白名单做确定性筛选，先把噪音挡掉；过了这一关的才交给模型做语义判断。
  • 订阅与直通：同一个 PR、同一个 IM 话题下的连续事件构成一条 Thread（线程）。Worker 订阅 Thread 之后，后续事件由程序直接发往该 Worker，不必每次绕回 Router。
  • 投机执行：根据环境信号在后台提前准备，确认有用才交付，没用就保持安静。

3. 用例目标

dsh-superagent 原型的完整形态是一个"面向单个 GitHub 仓库的主动式编码代理"。本教程把它跑成下面这条链路，每一步都能在面板或 GitHub 上核对：

环节 预期结果 核对位置
触发 仓库里一条 @ 智能体的评论 GitHub Issue 时间线
过滤 + 评估 生成一条决策，结果为"接单" 评估页
建单 生成工单，记下授权依据与策略版本 执行页 → 工单详情
派工 执行器在独立目录开工，首次可能失败并重试 工单详情 → 派工记录
交付 推送分支、创建 PR、回到原 Issue 回复 GitHub Pull requests

本机跑完这条链路后的实测产出：PR #2 携带两个新文件，greet.py（+18 行）与 tests/test_greet.py（+31 行）。

4. 环境准备

4.1 为什么必须在 WSL2 里跑

原型的执行器一侧依赖一套 POSIX 约定：worker 的命令 shim 用 #!/bin/sh 写成、靠 IFS=: 从 PATH 里剔除自身、proper-lockfile 对 Windows 的 \\?\ 前缀会报 EISDIR。这些不是配置问题，是代码假设。

Windows 原生安装会在两处直接失败，实测记录如下：

尝试方案 报错 原因
stateDir 填 C:/Users/... $.stateDir expect string to match regexp /^\// 配置校验只接受以 / 开头的绝对路径
stateDir 填 //?/C:/Users/... Error: EISDIR: illegal operation on a directory, lstat 'C:' 锁文件库对长路径前缀的 realpath 解析失败

因此本教程在 WSL2 的 Ubuntu 里安装整套环境。

4.2 依赖清单

依赖 版本要求 本机实测版本
Node.js 22.19+ 或 24+ 22.22.2
pnpm 11.x（packageManager 字段指定 11.7.0） 11.7.0
git 2.32+ 2.43.0
tmux 任意 3.4
Python 3.8+ 3.12
GitHub CLI 2.48+ 2.103.3
DeepSeek Harness ^0.2.1-alpha.2 0.2.1-rc.3

4.3 在 WSL2 里装 Node 22 与 dsh

Ubuntu 自带源里的 Node 是 18，不满足要求。用官方二进制包，避免动系统包管理器。

cd ~
curl -sL -o node22.tar.xz https://npmmirror.com/mirrors/node/v22.22.2/node-v22.22.2-linux-x64.tar.xz
mkdir -p ~/.local/node22
tar -xJf node22.tar.xz -C ~/.local/node22 --strip-components=1
export PATH="$HOME/.local/node22/bin:$PATH"
node -v

接着安装 dsh，版本按原型 engines.dsh 的要求选 0.2.1 系列：

npm config set registry https://registry.npmmirror.com
npm install -g @deepseek-ai/dsh@0.2.1-rc.3
dsh --version

输出 0.2.1-rc.3 即完成。模型凭据从你日常使用的那份配置里复制过来，省去重新登录：

mkdir -p ~/.dsh
cp /mnt/c/Users/<你的用户名>/.dsh/.credentials.yaml ~/.dsh/.credentials.yaml
chmod 600 ~/.dsh/.credentials.yaml

如果你的 Windows 侧 dsh 还停在 0.1.x，升级后先跑一次 dsh --profile web --dump-config。第三方插件若报 is incompatible with dsh 0.2.1-rc.3，用 dsh plugin --profile web add <插件>@<新版本> 升到兼容版本再继续。

5. 安装 dsh-superagent 插件

dsh-superagent原型是一个 DSH bundle，安装分四步：克隆、构建、建 profile、挂载。

mkdir -p ~/src && cd ~/src
git clone --depth 1 https://github.com/deepseek-ai/dsh-superagent-prototype.git
cd dsh-superagent-prototype
pnpm install
pnpm build

pnpm build 结束会打印 Build complete。接着创建一个独立的 profile：原型会改动进程级 PATH 和 git 配置，不能和你日常使用的 profile 混在一起。

dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"

第一条命令从 web 模板生成 ~/.dsh/profiles/superagent。第二条把当前目录以软链方式挂进去，改动源码重新 pnpm build 即生效。

--from-default-profile 只用于全新安装。profile 已存在时它会替换整个目录、删掉你写好的 cordis.patch.yml。升级时不要用它。

5.1 写机器配置

新建 ~/.dsh/profiles/superagent/cordis.patch.yml，只需要两个键：

- id: webserver
  config:
    host: 127.0.0.1
    port: 3082
- id: dsh-superagent
  config:
    stateDir: /home/eogee/.dsh/state/superagent

stateDir 用绝对路径，数据库、锁、命令 shim、agent 的 git 配置都放在这里，默认还会在这里建工单目录。升级前记得备份这个目录下的 orchestrator.sqlite。

5.2 启动与自检

原型自带一个 Python 管理脚本，把服务放进名为 dsh-superagent 的 tmux ，tmux 一个终端复用器（terminal multiplexer）的缩写，全称是 "terminal multiplexer"。它允许用户在一个终端窗口中创建、访问和控制多个会话（session），每个会话可以包含多个窗口（window）和窗格（pane），并且可以在断开连接后保持会话运行，重新连接时恢复：

export PATH="$HOME/.local/node22/bin:$HOME/.local/bin:$PATH"
cd ~/src/dsh-superagent-prototype
python3 scripts/dsh-superagent start
python3 scripts/dsh-superagent status

status 的退出码是判断依据：0 正常、1 没跑或有运行时错误、2 有部件报错、3 等待配置。首次启动会打印一段 JSON，其中 setup 会点名还缺什么，例如：

"setup": { "place": "github", "code": "repositoryUnset", "detail": "The GitHub Source names no repository." }

日志里还会打印带 token 的面板地址，形如 http://127.0.0.1:3082/?token=...，直接用 Windows 侧浏览器打开即可。WSL2 的 localhost 转发默认可用，curl 从 Windows 侧返回 401 就说明端口通了。

tmux 会话依赖 WSL 发行版处于运行状态。如果你在脚本外关闭了所有 WSL 会话，发行版会被回收，服务随之退出。保持一个常驻进程（例如 wsl -d Ubuntu -- sleep infinity）可以避免这种情况。

6. 配置模型服务商

原型的研判和实现都走 DSH 的模型层。如果你的默认服务商没有余额，先在 dsh 里加一个 OpenAI 兼容的自定义提供商，本教程以小红书的 dots 模型为例。

打开面板右上角账号菜单 → 设置 → 模型 → 添加模型提供商 → 自定义模型 API，填四项：

字段 示例值
Provider ID dev-cloud
API 地址 https://note3-prev-api.askdiandian.com/v1
API 协议 OpenAI Chat Completions
API 密钥 你的网关密钥

点「获取可用模型」会请求 GET {baseURL}/models 列出目录：

拉取网关的模型目录

私有模型不一定出现在目录里，实测该网关返回的是公共模型清单，没有我们要用的那个。这种情况直接点「添加模型」，手工填模型 ID 即可。

添加自定义模型提供商

保存后回到 Superagent 设置，把两处模型都指向它：评估页的「研判模型」负责 Router 的研判，执行页的「执行器模型」负责 Worker 的实现。两处都填 dev-cloud / dots3-note-prev。

执行器模型与准备命令

红框里是执行环境的两项关键配置：执行器模型决定 Worker 用哪个模型干活；准备命令决定每条工单的工作目录怎么来。

每条工单都有自己的一个文件夹，名字取自工单短名，比如 add-greet-py-4a9658800e0e。这个文件夹一定会被创建出来，不受你配置什么控制。真正需要配置的是，当 worker 打开这个文件夹时，里面应该有什么。

7. 配置来源、名单与执行环境

面板打开后先看概览。配置齐全之前，它会用红字列出暂时列出无法开工的问题：

首次打开概览：两项系统问题

这两条分别对应"来源没配仓库"和"白名单为空"。按下面的顺序配置：

7.1 来源：监听哪个仓库

设置 → 来源 → GitHub 卡片，填两项并打开评论开关：

字段 本教程取值 说明
监听的仓库 eogee/superagent-demo 写作 owner/name，保存时会校验 agent 账号能否推送
智能体的 GitHub CLI /home/eogee/.local/bin/gh-demo 指向一个用 agent 账号登录的 gh
接收仓库里的评论 打开 不打开就收不到评论触发

来源配置

CLI 这一栏的取值要点：原型会以这个账号的身份评论、推分支、开 PR，所以它必须是一个只登录了 agent 账号的 gh。如果你直接用日常的 gh，agent 的所有动作都会记在你个人账号名下。

7.2 名单：谁能发起工作

设置 → 评估 → 「能发起工作的 GitHub 账号」点添加，填入允许提需求的账号。名单为空时任何请求都不会变成工单。

同一页把「接单模式」从默认的「仅观察」改成「自动接单」。仅观察模式下系统照样评估、照样记录研判，但不建单。

策略与接单模式

7.3 执行环境：工单目录从哪来

设置 → 执行，填准备命令。每条工单执行前会先跑这条命令，用以检索仓库：

git clone --depth 1 "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" "$DSH_SUPERAGENT_DIR"

可用变量包括 $DSH_SUPERAGENT_GITHUB_REPOSITORY（仓库名）、$DSH_SUPERAGENT_DIR（本工单目录）、$DSH_SUPERAGENT_NAME（工单短名）、$DSH_SUPERAGENT_TICKET（工单 ID）。并行工单数默认 3，对应面板上的 执行中 0 / 3。

7.4 校验配置生效

三项都保存后回到概览，系统问题应清零，执行器从"等待部署检查"变成具体数值：

配置完成后的概览

红框里四个数字是链路的健康度：到达是进来的事件数，被过滤是被程序层挡掉的，已评估是过完语义判断的，接单或续做是正在受理的工单。

8. 触发一次真实任务

原型的触发方式是：在白名单账号下，于仓库 Issue 里发一条 @ 智能体的评论。

gh issue comment 1 --repo eogee/superagent-demo \
  --body "@eogee 请按 issue 描述把这个功能实现掉，完成后提 PR。"

默认 60 秒轮询一次。约一分钟后，触发页会出现这条记录：

触发列表

同一条事件在评估页会变成一条决策，写明为什么接：

评估决策

点进执行页的工单，能看到这条工单的全部内容：

工单的授权依据

触发保留原始请求文本和发起人；决定写清裁定结果和理由（"名单里的人明确请求，由主 Session 接单"）；范围是从请求里抽出的可执行边界；最后一行记下当时的策略版本——策略更改，之前接下的工单仍按旧版本授权。

8.1 执行器开工

工单建立后，Router 会给 Worker 开一个独立会话、准备一个独立目录。点工单页右上角的「打开 Session」可以看到它：

Worker 会话

上框是 Worker 报回 Router 的状态摘要，下框是它的模型 dots3-note-prev。注意这个会话的标题带着工单名，预设是「dsh-superagent 执行器」，你的日常会话列表里不会混进这些 Worker。

8.2 派工记录：失败、重试、推进

工单详情底部的派工记录是排查问题的第一现场：

派工记录

实测第一次派工是失败：The prepare command failed: ... fatal: could not read Username for 'https://github.com': terminal prompts disabled。原因是首次 git clone 时凭据还没准备好，git 被禁止弹交互提示。系统自动重试，第二次派工成功进入执行。

之后 Worker 报过一次 waiting，等人工确认。这时再发一条跟进评论即可：

gh issue comment 1 --repo eogee/superagent-demo --body "@eogee 不用再等确认，直接实现并按计划提 PR。"

这条评论不会再走一遍 Router 决策，而是作为 Thread 上的后续事件直接投递给已订阅该线程的 Worker——这就是第 2 章说的"订阅与直通"。

8.3 交付结果

Worker 完成后推送分支并创建 PR。核对命令与实测输出：

gh pr list --repo eogee/superagent-demo --state all

2  新增 greet.py：按时间段返回问候语  add-greet-py  OPEN  2026-11-01T09:26:15Z

gh pr view 2 --repo eogee/superagent-demo --json files

[{"path":"greet.py","additions":18,"changeType":"ADDED"},
 {"path":"tests/test_greet.py","additions":31,"changeType":"ADDED"}]

到这里整条链路闭合：一条评论 → 一次评估 → 一张工单 → 一个隔离会话 → 一个 PR。

9. 面板五个页面分别回答什么

页面 回答的问题 关键字段
概览 现在有没有事要我管 待处理工单、系统问题、24 小时四段计数、执行器负载
来源 事件从哪来、被挡掉了多少 每个来源的状态、近一日计数、被过滤与被丢弃的条目
触发 收到了什么、怎么处置的 每条 Trigger 的处置结果与错误
评估 为什么接、为什么拒 决策列表、决策依据
执行 谁在干活、干到哪一步 工单阶段、派工记录、执行器槽位
设置 系统按什么规则运行 来源、评估、执行、提示词、部署五组

一条实用的排查路径：概览看有没有红字 → 来源看事件有没有进来 → 触发看处置结果 → 评估看裁定理由 → 执行看派工报告。大多数"没反应"都能在这五步内定位。

10. 实测踩坑

现象 原因 处理
stateDir 校验失败 / EISDIR ... lstat 'C:' 原型只接受 POSIX 绝对路径，锁库不认 \\?\ 前缀 整套环境放 WSL2
插件启动但 dsh-superagent 未激活 profile 的 cordis.patch.yml 缺 stateDir 补齐配置后重启
服务起来一分钟后自动消失 WSL 发行版没有常驻进程，tmux 会话被回收 保持一个 sleep infinity 进程
评论发了但触发页一直空 轮询游标停在首次值，If-None-Match 持续命中 304 停服务、删掉 kv 表里的 github-stream:comments 记录、重启
自己 @ 自己毫无反应 源码里有 if (sameName(item.user.login, login)) continue，agent 自己账号的评论会被跳过 另备一个账号当"提需求的人"
触发页显示 gh-demo timed out after 90 s GitHub 接口在国内网络下握手慢 换网络或代理；单次超时不影响下一轮轮询

11. 架构边界

官方在文章里主动写了两条风险，本教程实测后认同它们不是纸上议题：

  • 云端被攻破的范围问题：Agent Loop 在云端跑，它连接的全部端侧设备都在可及范围内。一台机器中招，等于所有挂上去的机器一起暴露。
  • 凭据进入上下文：即使云端没事，只要端侧环境里的 token 能进模型上下文，正常执行过程中也存在泄露路径。需要让 Agent 在不接触凭据本身的前提下使用凭据。

原型 README 写明这是研究代码、不是正式产品，代码来自团队日常开发、大部分工程由编码代理完成，与内部版本不完全一致，文中部分设计属于未来方向、原型里没有实现。

对个人用户的实际含义：这套东西适合"我有一个长期维护的仓库，希望有条评论就能推进一个小改动"这种场景。它不适合当成通用助手直接开放给不确定的人——白名单、范围、策略版本这三个限定少一个都可能让一次误判变成一次错误提交。

12. 小结

Super-agent 的关键是把人的注意力从系统里摘出去：Session 变成实现细节，事件变成输入，Router 负责判断，Worker 负责执行，两条线可以各配各的模型。