deepseek-ai/dsh-superagent-prototype：7,182 stars 的主动型 GitHub 代理，把「注意力」当成唯一预算

发表于 2026-11-02 分类于开源项目

deepseek-ai/dsh-superagent-prototype 是 DeepSeek Harness 团队 2026 年 10 月 31 日开源的研究原型，两天半冲到 7,182 stars、730 forks，MIT 协议，主语言 TypeScript。它不是又一个「你说一句它答一句」的聊天式编程代理，而是一个面向单个 GitHub 仓库的主动型代理：监听 GitHub 与可选的飞书事件流，把获授权的请求在策略约束下转成 Ticket，再把每个 Ticket 交给独立的执行器 Session 去做。整个设计的核心约束写在文档第一行——尽可能少占用人类注意力，尽可能多创造价值。配套源码包含完整领域模型（Source、Trigger、Thread、Eval、Mandate、Ticket、Assignment、Subscription）、准入表与强度分级（explicit / inferred）、off / observe / auto 三档接收模式、每个工单独立的执行目录与工作分支、5 秒前台转后台的 shell 策略、30 分钟后台作业上限、PR 自动合并的默认红线（改动行数少于 200）、以及一个把「需要人处理的事」排在最前面的 Web 控制面板。

上周三下午，我在一个 PR 的 review 线程里回了条评论，顺手 @ 了一句「这个函数记得加个边界检查」。

然后我去开会了。四十分钟后回来，PR 里已经多了一个 commit，改动是我说的那个边界检查，还附了一句测试说明。

这不是什么魔法。这是任何一个「能在后台跑」的编程代理都能做到的事。

但真正让我停下来想了一下的，是另一件事：这个 PR 里的代理，没有顺手帮我做三件事 —— 没有把我的评论转发到公司飞书群、没有给我生成一份看起来很完整但其实没跑过的总结、没有在我没要求的时候去改另外两个文件。

它安静了。

这套「知道什么时候该闭嘴」的能力，正好是 DeepSeek 团队两天前开源的一个原型项目里反复强调的东西。

一、我想解决的其实是「注意力」问题

先说背景，因为这个项目的出发点跟大部分 AI Agent 项目不太一样。

过去两年，AI Agent 的叙事主线是「能力」：能调工具、能写代码、能跑测试、能自己循环迭代。同一个 demo 做十遍，每次都能再卷一点 —— 从「能改 bug」到「能改一整个模块」再到「能自己接需求」。

但真正把 agent 塞进团队工作流之后，会撞上一个完全不同的问题：

不是它做不了多少，而是它让你不得不看它的过程。

一个「有干劲但话多」的同事，比一个「能力弱但安静」的同事消耗的团队精力更多。这话很难听，但你在真实团队里一定见过 —— 周报写得极漂亮的人、把每个 PR 都写成长篇散文的人、在群里同步「我今天调研了 X」的人。

DeepSeek 把这条判断写进了 docs/000-philosophy.md 的第一句：

Take as little human attention as possible, and give as much value as possible.

翻译过来：每一条消息、每一次通知、每一个提问、每一个设置项、面板上的每一个元素、文档里的每一段文字，都要花掉某个人的注意力，所以每一个都得回报比它花掉的更多的价值，否则就删掉。

这不是一句漂亮话，它是可以拿来当验收标准的。整个项目的每一处设计 —— 包括看起来最奇怪的那些 —— 都能追到这句话上。

项目自己在 README 开头也把这个自我约束讲得很清楚：

An agent that can act for a whole team can also waste a whole team’s attention, so it acts only when asked or when a rule the team wrote allows it, and speaks only when someone must act or can use a result.

一个能替整个团队干活的代理，同样也能浪费整个团队的注意力。所以它只在被要求时、或团队写下的规则允许时才动手；只在有人必须行动、或有人能用上结果时才开口。

二、它是什么

一句话定义：

deepseek-ai/dsh-superagent-prototype 是一个面向单个 GitHub 仓库的主动型编码代理，打包成 DeepSeek Harness（DSH）的插件包；它监听 GitHub（可选加上飞书），在策略约束下评估请求，把获授权的请求变成工单，然后在各自独立的 DSH Session 里执行。

几个必须写清楚的事实：

项目	数据
仓库	`deepseek-ai/dsh-superagent-prototype`
Stars	7,182
Forks	730
协议	MIT
主语言	TypeScript
创建时间	2026-10-31
包版本	`0.1.0`（`private: true`，尚未发布到 npm）
依赖运行时	Node.js `^22.19.0 \|\| >=24.0.0`，DSH `^0.2.1-alpha.2`
依赖数量	生产依赖只有 2 个：`proper-lockfile`、`zod`

两天半从零到 7,182 stars —— 这个增速本身说明市场对「主动型 agent」这个形态有强需求。

不过要提醒一句，README 第一行就写着：

Research prototype for reference only, not an official DeepSeek product.

它明确说了三件事：一、这是研究原型，不是 DeepSeek 官方产品；二、代码是从团队日常开发里长出来的，很多工程工作本身是 coding agent 做的；三、它可能还有 bug，代码风格和工程实践可能不一致，用之前要自己审查和适配。

This code grew out of our team’s day-to-day development work, with much of the engineering done by coding agents.

「很多工程工作本身是 coding agent 做的」—— 这句话读起来有点讽刺，但如果你打开 src/ 目录看一眼，会发现代码质量确实不低。有意思的是，一个由 agent 写出来的项目，反过来教你怎么让 agent 更像个好同事。

README 还说了一句更诚实的话：

We have adapted it for publication, so it is not identical to our internal version or the implementation described in Exploring Super-agent Design: Towards a More Autonomous Agent System. Some designs discussed in the article are directions for future development and are not implemented in this prototype.

也就是说，配套文章里讨论的部分设计尚未实现。如果你按文章读，别把文章当成代码的说明书。

三、核心概念：把「聊天」重构成「工单流」

这个项目最有价值的部分，我觉得是它的领域模型。它没有用「会话」「消息」「agent」这套通用词，而是重新起了一套名字。完整定义在 docs/001-domain.md，我挑重点说。

先看整体流程（这是文档里的原始 mermaid 图）：

flowchart LR
  S[Source] -->|Trigger| T[Thread]
  T -->|batch| E[Eval]
  T -->|Subscription fan-out| K[Ticket]
  E -->|accept with Mandate / stop| K
  E -->|ignore / unavailable| X[recorded]
  P[Policy change] -->|notice| K
  K -->|Assignment| W[Executor]
  K -->|Channel| S

翻译成中文：

Source（来源）：事件流。有两种 GitHub Source 实现 —— 一个读通知，一个读 Issue / PR / 评论 / CI。飞书那边有实时事件、历史恢复、订阅话题轮询。
Trigger（触发）：一个不可变事件。审计和幂等的最小单位 —— 同一个 Trigger 被接收两次只会创建一个 Ticket。
Thread（线程）：按时间排序的一串 Trigger。同一时刻一个 Thread 上最多跑一个 Eval。
Eval（评估）：对一批 Trigger 的判断，分两层 ——Gate（准入） 是确定性的代码逻辑，Assessment（研判） 才是模型判断。产出是 Decision。
Mandate（授权）：一次「接单」授予的东西：策略版本、范围、强度、命中的规则、发送者在该 Source 上的身份。不可变。
Ticket（工单）：一份被授权的工作单元。只有 Eval 能创建。走 open → ended，人在它自己的 Thread 上发消息可以把它恢复回 open。
Assignment（派工）：Ticket 和某个执行器实例的绑定。一个 Ticket 生命周期内会有好几个 Assignment。
Subscription（订阅）：Ticket 和 Thread 的多对多关系。Ticket 开了 PR 之后，那个 PR 的后续讨论会自动流回 Ticket，不需要谁再 @ 一次代理。

几个设计上很讲究的点

一、人不是领域概念。

文档里明说：「A person is not a domain concept.」

一个人在不同 Source 上有不同身份，这些身份从不互相映射。授权名单是 Source 的 Policy 的一部分；「同一个人在这几个平台上都是他」这种信息，是写在 prompt 文本里让 agent 读的，不是写进数据模型的。

这听起来是小事，但它避免了一整类「权限系统越建越复杂最后没人敢动」的坑。

二、有一个章节专门叫「Rejected concepts（被拒绝的概念）」。

这是我觉得整个项目最值得学的地方。它把「我们考虑过但明确不要的东西」列成了表：

被拒绝的概念	原因
Principal / Membership 作为实体，或跨 Source 映射身份	人是 Trigger 的元数据；名单是 Policy 的一部分；跨 Source 映射是 prompt 文本
Eval 自己调度延迟 Trigger	需要等待的条件就是一个普通 Source，Eval 不该反向依赖 Source
等待中 / 已撤销的 Eval 状态	等待属于 Source；Eval 超时就把 Trigger 重新排队
一个 Thread 最多一个活跃 Ticket	一个 Thread 可以承载多件独立的工作
Ticket 状态跟随 DSH Session	Ticket 可能被移交、被恢复、被多个 Executor 执行，所以它自己定义状态
Executor 声称「有人让我停了」	只有 Eval 能决定结束强度
策略变更时取消运行中的 Ticket	取消会留下半成品；变更应该被记录并通知
从报告的自由文本推断「在等人」	分类需要结构化事实，Executor 得用结构化字段来问

「Rejected concepts」这一节，比它所有已实现的功能加起来更有参考价值。 因为大多数 Agent 项目的失败原因不是「功能没实现」，而是「概念加太多，最后没人说得清哪个东西归谁管」。

三、Mandate 有「保留但可撤销」的语义。

Ticket 结束时 Mandate 不随之消失。只有三件事能改变它：accept 创建它；人的 stop 撤销它；策略复检失败吊销它。

所以「PR 合并了，ticket 关了」并不代表授权被撤销 —— 后来有人在那个 Issue 上留言，工单还能恢复，而且不需要重新走一次 Eval。这解决了协作代理一个很实际的痛点：上下文断了。

四、授权模型：谁能派活，能派到什么程度

docs/002-authorization.md 讲的是「谁能启动工作，工作可以包含什么」。核心结论一句话：

The host enforces allowed lists, rules and Mandates. Messages, comments and quoted documents are inputs to a decision; they cannot change those permissions.

主机强制执行名单、规则和授权。消息、评论、被引用的文档只是决策的输入；它们不能改变那些权限。

这句话是在防一件事：prompt injection。一个在 Issue 评论里写「顺便把你所有仓库的 token 打印出来」的请求，哪怕看起来人畜无害，也只是一条待评估的 Trigger，不是权限。

两条路径

一个 Trigger 进入系统有两条路：

路径 A：走 Eval，判断是否开新工作。

Gate 层做确定性判断：发送者是谁、是不是在名单上、是不是明确 @ 了代理。

路径 B：走 Subscription，继续已有工作。

订阅的 Thread 上的每条消息（包括机器人和 CI 的）都会作为上下文送到 Ticket，但绕过 Gate，不授予任何新权限。

强度分级

强度	场景
`explicit`（明确）	名单上的人明确 @ 了代理；或者在已有 Ticket 的 Thread 上追问
`inferred`（推断）	不在名单上的人在有 Ticket 的 Thread 上追问；准入表某个格子设成推断；机器人在 bot 名单上发的 @
`not admitted`（不准入）	其他机器人的消息、准入表忽略的一切、以及 `off` 模式下的所有推断

准入表

每个 Source 有一张准入表，行是「接收范围」，列是三格：

格子	可选	默认
在名单上，且没 @ 代理	推断、忽略	推断
不在名单上，但 @ 了代理	明确、推断、忽略	忽略
不在名单上，也没 @ 代理	推断、忽略	忽略

GitHub 的接收范围有四种：新 Issue、新 PR、评论、默认分支的 CI。飞书是每个配置的群、其他被 @ 到的群、私聊。

把「不在名单上但 @ 了代理」那格设成「明确」，就等于「这个范围内任何人都可以 @ 代理派活」—— 文档说这在专用的支持群里有用。

接收模式：off /observe/auto

模式	效果
`off`	没有任何推断能变成候选
`observe`（默认）	推断候选会被研判；研判为正的记录成「忽略（本会接单）」，但不真的接
`auto`	推断候选研判为正就真的接单

明确请求在三种模式下都生效。 文档的建议是：先在 observe 跑一段时间，看清楚那些「本会接单」的记录长什么样，再切到 auto。

这个设计我觉得非常聪明。它把「要不要开自动挡」这个决定，从「盲开」变成了「看行车记录仪」。大多数 Agent 框架没有中间档 —— 要么全自动，要么全手动。

策略版本

规则、接收模式、每个 Source 的 Policy 三者构成一个「策略版本」，每个 Mandate 都记着自己是在哪个版本下被授予的。

版本一变：

正在跑的 Eval 被丢弃，Trigger 重新排队；
受影响的存活 Ticket 会收到一条 policy-changed 输入，告诉它「你被接单时用的那条规则改了 / 你这个请求者现在不能派活了 / 主动工作不再被接受」；
但不会立刻吊销已有 Ticket 的 Mandate。

这个「通知但不立刻撤销」的处理很务实。正在做的事先让它做完，下次恢复的时候再复检。

五、执行模型：每个工单一个 Session、一个目录、一条分支

docs/003-execution.md 是整个项目工程含量最高的部分。

工单阶段

每个打开的 Ticket 处于一个阶段，由「它在等什么」决定。表格从上往下读，第一条匹配的就赢：

阶段	条件	面板标签
person / delivery	投递 Input 给 Executor Session 失败	Input undelivered
person / answer	有待人工决定的问题	Awaiting answer
person / review	最新报告是 `ready`	Awaiting review
person / blocked, failed	最新报告是 `blocked` 或 `failed`，且此后没有人发消息	Blocked · Failed
working / queued	没有 Assignment，或者 Assignment 待启动	Queued
idle	最新报告是 `waiting`，或 Assignment 已结束	Waiting for a Trigger
working	其他	Working

person 阶段的意思是：没有人类输入，这个工单没法继续。

执行器

每个 Ticket 拿到：

一个叫 worker-<ticket id> 的 Executor Session；
一个以 Ticket 短名命名的目录；
目录在配置的 execution root 下，默认是 <stateDir>/work。

Executor Session 以操作者的操作系统用户身份无确认地执行命令。这里要特别注意 —— 默认情况下它不做任何审批。

dsh-superagent-worker 预设里有个关键设定：前台 shell 命令超过 5 秒就转成后台作业。文档的解释很实在：

This lets a worker receive new messages at the next step instead of waiting for a long command to finish.

这样 worker 就能在下一步接收新消息，而不是傻等一个长命令跑完。

后台作业和 30 分钟上限

一轮结束如果还有 shell 作业或 subagent 在跑，Ticket 会继续占用 worker 槽位并保持 working 状态。它不会被报成 waiting，主 Session 也不会收到等待报告。

后台工作最多有 30 分钟完成。到点后 shell 作业被杀掉，Ticket 报为 waiting，报告里包含：

Executor 最后说了什么；
哪些作业被杀掉了、哪些 subagent 还活着。

Subagent 允许继续跑。Executor 下一步会读到被杀作业的结果。

交接给人会立刻释放槽位。 这适用于 ready 报告或提问之后（除非又有新 Input 到达），也适用于任何 blocked / failed 报告。

并发

配置里的并发上限作用于槽位。但有一个细节我觉得设计得很体贴：

The configured concurrency limit applies to these slots, with one extra slot for a person’s message or a status request.

也就是说，人发消息和查状态永远有一个额外的槽位可用。新工作永远不会把你堵住，让你没法继续手上已经在跑的 Ticket。

这个细节单独拿出来就值回票价。

执行变量

prepare 命令和 Executor 指令共享同一批变量。命令读环境变量，Executor 在 prompt 里读到它们的值和说明。没有一个包含凭据。

变量	注册方	含义
`DSH_SUPERAGENT_DIR`、`DSH_SUPERAGENT_NAME`、`DSH_SUPERAGENT_TICKET`	Executor	Ticket 的目录、短名、id
`DSH_SUPERAGENT_BLOCKED_COMMANDS`	Executor	Executor 不允许执行的命令
`DSH_SUPERAGENT_GITHUB_REPOSITORY`	GitHub	监控的仓库，`owner/name`
`DSH_SUPERAGENT_GITHUB_ACCOUNT`、`DSH_SUPERAGENT_GITHUB_COMMIT_EMAIL`	GitHub	代理账号及其提交邮箱
`DSH_SUPERAGENT_GITHUB_NUMBER`、`DSH_SUPERAGENT_GITHUB_PR_HEAD`	GitHub	发起该 Ticket 的 Issue 或 PR，以及 PR 的 head ref
`DSH_SUPERAGENT_FEISHU_BOT`、`DSH_SUPERAGENT_FEISHU_CHAT`	Feishu	机器人、发起该 Ticket 的群

安全边界：说实话的那种

文档有一句很诚实的话，我原样贴出来：

These wrappers and directories establish defaults, not a security boundary. A worker can still execute a program by absolute path.

这些封装和目录是默认值，不是安全边界。worker 依然可以用绝对路径执行程序。

所以「把个人 CLI 列为 blocked command」这种措施，是防君子不防小人的。你要真隔离，得靠容器或虚拟机。

合并策略

默认情况下，Executor 绝不用代理账号启用 auto-merge。理由很实在：GitHub 会把合并归因于「谁启用的 auto-merge」，如果用代理账号，合并记录上就是代理的名字，没人能看出是谁真的点了合并。

默认指令允许 auto-merge 的条件是：

PR 是为这个 Ticket 开的；
状态是 ready；
要求的审批覆盖了 head commit；
新增加删除的行数总计少于 200 行。

在推新修订之前，Executor 会先撤掉 auto-merge。

第 4 条那个 200 行阈值是个很聪明的默认值 —— 大改动自动落到人手里。

要真正强制审批，得在 branch protection 里配，并 dismiss stale approvals。

Ticket 怎么结束

没有 PR 的 ready：工单完结。
dropped（无需处理）：Executor 觉得压根没活可干（比如请求复现不了、或者已经被别的解决了）。工单结束，不发消息 —— 除非命中的规则要求发。
有 PR 的：Ticket 跟踪它开的 PR，也跟踪从它分支开出去的 PR。当它开的 PR 全都不再是 open 状态时，工单才结束（如果它一个 PR 都没开，那就要它跟踪的 PR 全关闭）。

失败与恢复

模型供应商或网络出问题、HTTP 408/429/5xx、连接被拒或超时 —— 这些「偶发性失败」会先重试三次，带递增退避。但 prepare 命令失败不重试。

已经失败的 Ticket 上，CI 和机器人的消息会被记录，但不投递、不唤醒 Session。

它的工具仍然可用，所以人可以进 Session 里直接接着干。

重启恢复

这是我觉得很值得抄的一段设计：

Sessions, directories, Subscriptions, pending messages and the stored work below survive a restart, and so does the record of which messages each Executor Session took into its history, which a step does once it claimed them and before its model call.

「消息是否已被读」这个事实在重启后依然保留。 而且判定标准很细：被一个 step 领走、但在被取消或报错打断之前还没进历史的，算「未读」；领走之后有报告或回合结束跟着，就算「已读」。

这个追踪做得很细，但它解决的是真问题：重启后如果把已读的消息重投一遍，agent 会重复回答。

六、控制面板：只显示需要人处理的事

docs/005-panel.md 定义了面板。整个面板回答三个问题，按这个顺序：

现在有需要我处理的事吗？
系统健康吗，在做对的事吗？
一件工作的历史是什么样的，从 Trigger 到 Eval 到 Ticket？

面板设计原则第 6 条写着：

Quiet by default. Healthy states take no extra space. Problems must be actionable; a one-off network error is not enough. Rows needing a person offer their action directly.

默认安静。 健康状态不占额外空间。问题必须可行动 —— 一次性的网络错误不算问题。

同样的原则在哲学文档里重复了一遍：「A panel that shows only what needs a person. It lists first what waits for a person. A healthy state takes no space.」

六个标签页

标签页	内容
Overview	需要行动的 Ticket、系统问题、最近 24 小时活动计数、Executor 负载
Source	Source 状态、配置问题、非零计数。被过滤的 Trigger 和被丢弃的消息同样覆盖 24 小时窗口
Trigger	按 Subscribed / Evaluating / 24h 新 Trigger / 全部筛选的 Thread
Eval	Decision 及其理由和命中的规则
Execution	Executor 状态、暂停处理、Ticket 列表及其详情
Settings	Sources、Eval、Execution、Prompts、Deployment 五组，各自带保存历史

一处细节：区分「人话」和「内部状态码」

A label says whom a row waits for and what it needs, not an internal status code.

标签说的是「这一行在等谁、需要什么」，而不是内部状态码。所以你看到的是「Awaiting review（待评审）」而不是「state=3」。

同时，领域术语表是内置的（面板上的 ? 按钮），带中英双语。这个细节说明作者意识到：一线使用者不背 Assignment / Mandate / Subscription 这些词。

而且 GitHub 和飞书上发给人的消息用大白话，不用这些术语。

七、快速上手

前置条件

从 SETUP.md 的探针部分能看出完整依赖：

1
2
3

node -v; pnpm -v; git --version; tmux -V; python3 --version; gh --version | head -1; dsh --version
gh api user --jq .login
command -v lark-cli

需要：Node.js 22.19+ 或 24+、pnpm、git 2.32+、tmux、Python 3.8+、GitHub CLI 2.48+，以及版本在 package.json 的 engines.dsh 范围内的 DSH。

安装

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

四个命令各有分工：装 DSH、克隆并构建本项目、从 Web 模板创建 ~/.dsh/profiles/superagent 配置档、把本项目作为插件装进去。

Run the profile-creation command only for a new installation. If the profile already exists, that command replaces it and deletes its cordis.patch.yml, including machine configuration. Do not use it for upgrades.

这条警告值得注意：重复执行第 4 条命令会删掉你的机器配置。升级要读 docs/006-deployment.md 的 Upgrade 章节。

机器配置

把 examples/profile.cordis.patch.yml 拷到 ~/.dsh/profiles/superagent/cordis.patch.yml，替换掉所有 <placeholder>。

键	必填	含义
`stateDir`	是	绝对路径：数据库、锁、`worker-bin` 里的命令垫片、代理的 git 配置，默认还有 `work/` 里的工单目录。升级前要备份
`promptMaxChars`	否	保存的 prompt 配置上限
`admissionContextMaxPages`	否	一次研判能读多少页 Thread 上下文
`admissionContextTimeoutMs`	否	上述读取的超时

配置里的值非法或出现未知键会阻止启动，日志里会指出是哪个键。

启停

1 2	scripts/dsh-superagent start scripts/dsh-superagent status

start 会在 tmux 会话 dsh-superagent 里跑 dsh --profile superagent，最多等一分钟等运行时 ready 或报出配置需求。首次运行会打印缺什么配置。

status / start / restart 的退出码分四档，这个设计挺讲究：

退出码	含义
0	服务正常运行
1	没跑、跑了两份、不响应，或运行时报告错误；重启可能修好
2	在跑，但某个非运行时部件（比如某个 Source 或策略同步）报了错误；重启修不好
3	在跑，在等配置；重启修不好

2 和 3 需要人介入。 这个区分很重要 —— 它让「自动恢复」不会对着一个需要人改配置的问题反复重启。

还可以用 --profile / --url 换配置档和端口，或设 DSH_SUPERAGENT_PROFILE / DSH_SUPERAGENT_URL 环境变量。

给每个 Ticket 准备 checkout

设置里的 prepare 命令，官方给的例子：

1
2

git -C /home/me/src/widgets 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/me/src/widgets worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"

注意几个细节：

用 git worktree 而不是 clone，每个 Ticket 一个独立工作树；
分支前缀默认 agent/；
PR 归属于 Ticket 的判定规则：它分支的最后一段路径名要和 Ticket 的短名一致。

试一下

从允许名单上的账号，在仓库的某个 issue 里评论：

1	@<agent login> <你的请求>

大约一分钟内，Overview 上会出现一个 Ticket。

八、整个安装流程是「让 agent 帮你装」

这是我觉得最有意思的一点。README 说：

Setup has many steps, so an agent does it with you. Ask your coding agent:

Read SETUP.md in this repository and set up dsh-superagent with me.

别自己装，让你的编程代理读 SETUP.md 帮你装。

SETUP.md 本身是一份写给 agent 的指令文档，它规定了 agent 应该如何跟人交互：

开始提问前，只读这份文件和 docs/000-philosophy.md，并且只跑一次探针。在收集完所有答案之前，别的都不要读。
每条消息只问一个问题，问一件事。等回答了再问下一个。探针已经回答了的就跳过。
每条消息不超过 300 词（除非用户要求更多）。每个问题要给一个推荐答案，用户一个词就能接受，再加一句话说明为什么这事重要。
提问的时候不要执行。 先收集所有答案，然后发一条消息给出完整计划，用户确认后才执行。
绝不在聊天里要密钥。 需要用户动手的步骤（建账号、登录 CLI、填 app secret）统一放到一条消息里，给出确切的命令让用户自己在终端跑。

然后是 9 个问题，按工作流顺序：

来源：请求从哪来

只从 GitHub 收请求，还是也从飞书群收？[除非团队在飞书工作，否则只 GitHub]
代理要处理哪个 github.com 仓库，写成 owner/name？
代理用哪个 GitHub 账号行动？[专用账号，绝不用你自己的 —— 代理写的一切都以这个名字出现]
用飞书的话，是哪些群？

策略：谁能派活

GitHub 上哪些 login 可以给代理派活？[只有你自己的 login：名单短一点噪音低]
用飞书的话，飞书里谁能派活？[第一个群的所有成员，和群成员同步]

执行：代理拿到 Ticket 干什么

每个 Ticket 从哪个本地 clone 检出？[在 ~/src/<name> 下新建一个]
代理的 commit 作者署名是谁？[代理账号，这样它的工作一眼看得出是自己的]
代理在自己开的 PR 就绪并被批准后，要不要开 auto-merge？[不要：等代理的 PR 正确了一阵子之后再说]

第 9 条的默认值是「不要」，理由写在文档里：GitHub 把合并归因于启用 auto-merge 的人，所以「yes」的话需要另一个账号的 CLI 来启用合并 —— 那个账号必须由人登录。

最后一句话是对 philosophy 的呼应：

The goal is the right help at the right time, and nothing at any other time.

在正确的时间给出正确的帮助，在其他任何时候什么都不要给。

九、源码结构

TypeScript + React（客户端）+ 一个 Cordis 插件补丁。目录大致是这样：

src/
  core/          # 领域层：引擎与五个内部部件
    engine.ts      # 唯一写 Triggers/Threads/Decisions/Tickets/Assignments 的地方
    intake.ts      # Trigger 的摄入
    evals.ts       # Eval 的批处理、准入强度、决策
    tickets.ts     # Ticket 生命周期（最大的一个，27KB）
    assignments.ts # Executor 报告的处理
    replies.ts     # 通过 Outbox 的渠道写入
    model.ts       # 领域类型
    stage.ts       # 工单阶段表
    reasons.ts     # 理由码
    ports.ts       # 端口接口
  app/           # 应用层：Runtime、Engine 装配、HTTP 路由、设置、视图
  client/        # React 前端（面板）
  executor/      # DshExecutor 与后台作业管理
  policy.ts      # 策略模型
  sources/       # GitHub 和飞书 Source 实现
  tools/         # Session 工具
prompts/         # 所有 prompt 模板（含 team/ 子目录）
skills/          # dsh-superagent-github / dsh-superagent-feishu
docs/            # 000 到 008 编号文档
scripts/         # dsh-superagent 管理脚本（Python）

Engine 的设计

src/core/engine.ts 是唯一能写 Triggers、Threads、Decisions、Tickets 和 Assignments 的地方。它从 src/core/ports.ts 接收这些端口：

Repositories、当前 Policy 的 getter、SourceScope、Assessor、Executor、Outbox。

几条值得学的工程约定：

所有 Engine 方法都是同步的。 每条命令在一个事务里改完自己的聚合。evaluateDue 对它改的每个 Eval 或 Ticket 用独立事务。
端口在事务内入队外部工作，适配器在提交后才真正执行。
调用方只拿自己角色的 Pick：EngineForSources、EngineForMainSession、EngineForPeople、EngineForSettings、EngineForExecutor。这在类型层面就限制了谁能干什么。
命令用祈使词，事实用过去式。 stopTicket vs assignmentStarted。查询用名词：candidate。

这最后一条命名约定我很喜欢。它让代码读起来像一份事件日志。

依赖方向

五个内部部件之间的依赖是单向的：

部件	职责	依赖
`Intake`	Source 的 Trigger 进来	Tickets
`Evals`	Thread 上的 Eval	Tickets
`Tickets`	Ticket 生命周期	Replies
`Assignments`	Executor 报告	Tickets, Replies
`Replies`	通过 Outbox 的渠道写入	无

零环。 这在 Agent 项目里不常见 —— 大多数 Agent 框架的依赖图是一团毛线。

会话工具

Executor 和主 Session 用的工具集不一样。主 Session 用 dsh-superagent-router 预设，工具集更小，专门用来路由。Executor 用 dsh-superagent-worker，工具更多，能干活。两者都有 5 秒的 shell 和作业等待上限。

Worker 的 subagent 用 DSH 的 standard 预设，权限继承 worker，只保留 worker 允许的工作工具，Ticket 结束时这些工具就消失了。

提示词是文件，不是代码

prompts/ 目录下有十来个 markdown 模板：admission.md、dispatch.md、orchestrator.md、worker.md、handoff.md、replies.md、subscriptions.md、shared.md，外加 prompts/team/ 下的 communication.md、delivery.md、scope.md、work.md。

团队要改的东西（GitHub 披露行、review 机器人、commit 作者、auto-merge 条件）全在 team/ 目录里。

面板上改完还能看 Full prompt（组装后的完整文本）、和已保存文本或默认值做对比、以及 History（历史版本）。升级时如果内置默认值变了而你覆盖过，界面会标记 Default updated（默认内容已更新），让你选「保留我的文本」还是「用新默认值」。

十、Skills：让 worker 知道怎么读 GitHub

skills/dsh-superagent-github/SKILL.md 是给 worker 看的操作手册。摘几段：

worker 用 orchestrator_read 读仓库上下文：

github/issues/<number>、github/pulls/<number> — 描述
github/issues/<number>/comments/1 — 对话评论
github/pulls/<number>/comments/1 — review 评论
github/pulls/<number>/thread/<comment-id> — 任意评论所在的 review thread
github/pulls/<number>/reviews/1 — review
github/pulls/<number>/checks — CI

一页放 20 条，有下一页时会给出 next_resource。评论或 review 的结构是 { id, from, at, text, reply_to?, path?, line?, url }，其中 bot: true 标记机器人和 GitHub App。

这一句是关键：

Reading does not create tickets or send replies.

读不建单，不发消息。避免了「worker 读着读着把上下文当请求执行了」这类事故。

回复 review thread 必须用 GraphQL 的 resolveReviewThread，而且明确禁止用 gh pr comment 或 issue-comment 端点来解释 review thread：

1	gh api repos/<OWNER>/<REPO>/pulls/<PR>/comments/<ROOT>/replies --method POST -f body=<text>

还有一条我觉得值得抄的规矩：

Before substantial work on a new human request or review comment, call orchestrator_ack with its original trigger ID and a brief request-specific text, even within an existing ticket; the host replies once in that source thread.

在开始实质工作前先 ack 一次，哪怕是在一个已有的工单里。宿主只回一次。之后干活过程中就安静了。

而「什么时候该说话」也是有规范的：创建或接管 PR 之后立刻报 progress 并带上 PR 号，不要等 CI、不要等交接。

十一、和同类项目比

对比 Devin / Cursor Background Agent

这类产品的重心是「完成一个工单」，交互模式是人主动发起、agent 交付结果。

dsh-superagent 的重心是事件驱动的常驻代理：它一直在听 GitHub 通知，按你的策略决定接不接单，然后在独立 Session 里干活。人的角色从「下指令的人」变成「写规则的人 + 偶尔被问的人」。

差别在架构上体现得很清楚：它有完整的 Policy / Eval / Mandate / Subscription 这套授权与路由层，而大多数产品只有「谁能用这个功能」这一层。

对比 OpenHands / SWE-agent 这类研究型框架

SWE-agent 是单个任务、单个 episode：给定 issue，产生 patch，结束。评测友好。

dsh-superagent 是长期运行、多任务、有状态的系统：状态存在 Store 里（SQLite 之类），有跨重启的恢复，有策略版本，有订阅关系。它更像一个运维系统而不是一个 benchmark harness。

代价是：SWE-agent 那种「一条命令跑完 100 个 issue」的评测方式在这里很难写，因为它的行为依赖于团队写下的策略。

对比 GitHub 自己的 Copilot Workspace / Coding Agent

GitHub 官方的 coding agent 也在 PR 里干活、也发评论。但它是平台内置的，行为策略由平台定死。

dsh-superagent 的关键差异是策略可写：你能写规则说「什么情况下允许主动工作」，准入表能精细到「某类范围内、没 @ 代理但发言的人算不算候选」。

对比各类「自托管 Claude Code / Codex」封装

这类工具本质上是给 CLI 套个壳 + 加个网页面板。dsh-superagent 的独特之处是它不实现模型调用，只做编排 —— 模型能力来自 DeepSeek Harness。

这既是它的优点（不重复造轮子，模型随便换）也是它的硬伤（绑死 DSH）。

对比 n8n / Zapier 这类工作流自动化

n8n 的路子是「你画好流程，机器按图执行」。dsh-superagent 是「你写策略，模型判断意图，机器执行判断」。

前者确定性高、可预测；后者灵活、能处理开放式请求，但要求前面那套授权模型来兜住。

对比各类 multi-agent 编排框架（LangGraph、AutoGen、CrewAI）

那些框架提供的是编排原语（状态图、角色、任务路由），你得自己往上搭业务。

dsh-superagent 是一个具体的业务（GitHub 仓库工单流），但把领域模型、授权、执行、面板全都做完了。

我觉得这两条路都合理。dsh-superagent 的价值在于它是一个完整可抄的样板。

十二、真实局限

这是研究原型，下面这些是文档里明说或者代码里能看出来的：

1. 它不是官方产品，README 自己说的。

It may still contain bugs, and its coding style and engineering practices may be inconsistent.

2. 配套文章里的部分设计没实现。

「Some designs discussed in the article are directions for future development and are not implemented in this prototype.」—— 别拿文章当实现说明。

3. 依赖 DeepSeek Harness 生态，而且 DSH 本身是 alpha。

engines.dsh 是 ^0.2.1-alpha.2。所有 peerDependencies 都是 ^0.2.1-alpha.2。安装文档里钉的是 @deepseek-ai/dsh@0.2.1-rc.3。

alpha 阶段的接口不稳定性，你懂的。

4. 没有发布版本，没有 tag，没有 release。

package.json 里是 "private": true、"version": "0.1.0"。GitHub 上 releases 和 tags 都是空的。所以只能用 link:$PWD 本地装，不能 npm i。

5. 默认情况下执行器无确认地跑命令。

Executor Sessions run commands without approval as the operator’s OS user.

而且文档明确说这不是安全边界。需要真隔离得自己套容器。

6. 只支持单个仓库。

README 第一句就是「for one GitHub repository」。多仓库要么多部署实例，要么自己照着 docs/008-cookbook.md 写 Source。

7. 面板和概念表对非工程角色有门槛。

虽有中英术语表和 ? 按钮，但「Mandate」「Assignment」「Subscription」这套词汇量不小。飞书和 GitHub 上的消息已经特意不用术语了，面板这块还是工程师视角。

8. 那 200 行的 auto-merge 阈值是硬编码默认值，不是策略。

在 prompt 里，不是配置项。要改得改 prompt 文本。

9. observe 模式的意义被低估了。

默认模式只记录不执行，这意味着你装好它之后的第一周，它什么也不会干。这个设计是对的（先看清楚再开自动挡），但要有心理准备。

10. 文档语言是英文，界面是中文。

locale/zh.json 里目前只有 meta.title 和 meta.description 两条翻译。完整的界面文案在 src/client/locales.ts（73KB）里。

11. 需要 tmux。

scripts/dsh-superagent 靠 tmux 会话跑 DSH 服务。这在容器和 CI 环境里会绕路。

十三、适合谁，不适合谁

适合

维护单个活跃仓库的小团队。 尤其是一两个维护者、Issue 和 PR 来回讨论的那种。你的痛点是「回复之后忘了跟进」。

已经有 GitHub 工作流纪律的团队。 你有 review 流程、有分支保护、有 commit 规范 —— 这个项目会尊重它们。

愿意先花一周看「observe」记录的人。 它要求你先建立信任再放手。

想学「怎么设计 agent 权限模型」的人。 单看 docs/001-domain.md 的领域模型和「Rejected concepts」表，就值回票价。

想做平台而不是用平台的人。 docs/008-cookbook.md 讲怎么加一个 Source。把它当模板做自己的内部工单代理。

不适合

个人玩具项目。 你自己就有空处理 Issue，多一个代理只是多一份要 review 的 PR。

多仓库场景。 一个实例一个仓库，仓库一多就管理不过来了。

流程不成熟的团队。 如果你们连 PR 都不怎么 review，开一个会自己提交 PR 的代理只会制造混乱。

需要强隔离的场景。 默认没有沙箱、没有审批、执行器以你的身份跑命令。

完全不想配 DSH 的人。 装它要 Node 22+、pnpm、tmux、Python 3.8+、gh CLI 2.48+、还有一个 DSH 本体。对纯 Python 团队来说这个栈有点重。

指望它开箱即用的人。 配置步骤有 9 个问题 + 机器配置 + 策略 + prompt 定制。至少要花一个下午。

十四、我的实际判断

说点我的个人看法。

这个项目最被低估的东西不是那 7,182 stars，也不是主动型 agent 这个形态，而是它把「注意力」变成了一个可度量的工程约束。

文档里有一句：

Every part of the project is judged by the attention it costs.

这句话让「安静」从一个偏好变成了一个可以被 review 的标准。你 review 别人的 Agent 框架时，可以直接问：这条消息花掉了谁的注意力？它回报得更多吗？

同理，「Rejected concepts」这一节应该成为所有 Agent 框架文档的标配。写「我们不做什么」比写「我们做什么」更能约束复杂度。

至于技术本身，我最欣赏的是三处：

Gate（确定性准入）和 Assessment（模型研判）分层。 权限判断不交给模型。这是很多框架跳过的一步，但这恰恰是最不能交给模型的一步。
Subscription 让后续讨论自动回到 Ticket。 「PR 合并后上下文就断了」这个经典问题，被「工单结束后 Mandate 保留」这个设计干净地解决了。
多留一个给人用的槽位。 一个这么小的设计决策，暴露了作者是真的在脑子里跑过这个系统的。

需要清醒的地方也有：它现在的成熟度，配不上它传播的速度。 7,182 stars 的项目，0 个 release、0 个 tag、private: true、DSH 依赖还是 alpha。这个组合意味着 —— 现在动手的人会成为试错的人。

我的建议是：先读文档，再决定要不要装。 docs/000-philosophy.md 只有 3KB，docs/001-domain.md 12KB，两个加起来 15 分钟。读完你就知道这套设计值不值得你花一个下午去配。

如果它值得 —— 用 observe 模式起步，配一份短名单，先让它只做「明确的请求」，等你看清楚它的行为之后再放宽。

最后一句，也是它自己文档里的那句：