dsh-superagent：DeepSeek 开源的"主动型"编码智能体原型

仓库地址：https://github.com/deepseek-ai/dsh-superagent-prototype ｜ 20376 ★ ｜ MIT ｜ TypeScript 重要提示：官方明确标注这是"研究原型（research prototype），仅供参考，并非 DeepSeek 官方产品"，且发布版本与内部实现及配套论文中的设计并不完全一致。

一、它解决的是什么问题？

想象一个典型的团队场景：仓库里躺着一个拼写错误、一处文档错位、一条 CI 报错。传统做法是——有人刷到、有人建 Issue、有人认领、有人改、有人 review、有人合并。六个人为一件小事来回传递注意力。

dsh-superagent 想把这整条链路压缩成一句话："在这个 Issue 里 @机器人 修一下这个错别字"，然后它自己去开一个工作项、自己开分支、自己改代码、自己提 PR，最后回到原来的 Issue 里回帖交付。

它的核心哲学写在 docs/000-philosophy.md 里，翻译成人话只有两句："尽可能少占用人的注意力，尽可能多地产生价值。" 每一条消息、每一个通知、每一个面板元素都要被审判——它消耗的注意力必须小于它产出的价值，否则就删掉。

二、背景：它出自一篇设计文章

DeepSeek Harness 团队在开源的同时发布了一篇设计文章《Exploring Super-agent Design: Towards a More Autonomous Agent System》。README 明确说明：文章里讨论的部分设计是"未来方向"，并未在这个原型中实现。 所以这是一份"论文 + 代码"的组合发布，而不是单纯的工具开源。

值得注意的是 README 里的另一句自白："much of the engineering done by coding agents"——这个项目很大一部分工程工作本身是由编码智能体完成的。某种意义上，它是 AI 写的 AI 智能体框架。

三、领域模型：五个核心概念撑起整套系统

要理解这个项目，抓住 docs/001-domain.md 里的五个词就够了：

工作流是：Source → Trigger → Thread → Eval → Ticket → Assignment → Executor，结果再通过 Channel 写回 Source。

其中最漂亮的设计是 Mandate（授权书）：每个 Ticket 出生时就带一份不可变的授权快照——依据哪个版本的 Policy、范围多大、匹配了哪条规则、请求者是谁。Policy 变更不会吊销已生效的 Mandate，但会作为通知推给正在跑的 Assignment。这解决了 Agent 系统中一个经典难题：授权的时点与执行的时点是分离的。

四、它凭什么"敢"自动动手？

三层防护：

1. 准入表（Admission）——先判断"这条消息到底是不是在要求实现"，并且目标是否明确、是否涉及待定设计决策。directionAllowed() 要求 implementation_requested=true 且 target_basis != 'undetermined' 且 requires_design_decision=false。
2. 策略与白名单——谁能派活按 Source 各自的身份体系配置，Policy 从不跨 Source 映射身份。列表为空则任何请求都变不成 Ticket。
3. 接受模式（accept mode）——默认 observe，只记录"如果开了它会做什么"而不真做。想开主动执行，评测模型推断出的候选也必须显式升级。

另有内置规则库，如 copy（文案修正）、visual（视觉修正），每条规则都必须被评测模型逐条给出 matched + reason，恰好一次，缺一条直接抛错——这是很强的审计约束。

五、架构与代码结构

src/ 约 15000 行 TypeScript，分层清晰：

• src/core/ —— 纯领域引擎：engine、tickets、model、policy 判定、evals、replies，零 IO
• src/app/ —— 应用层：assessment（2 万行字符的最大文件之一）、sessions、settings、http（面板服务端）、resources
• src/sources/ —— GitHub / 飞书适配：github-trigger、github-read、github-pull、feishu-*
• src/executor/ —— dsh.ts（4.7 万字符）负责在独立 DSH Session 中执行
• src/client/ —— React 面板前端（overview / trigger / eval / execution / settings 五个页签）
• src/infra/ —— 路径、命令、健康检查

测试极为密集：tests/ 下 60 余个 spec 文件，涵盖核心引擎、策略、迁移、面板交互，甚至有 class-docs.spec.ts 检查文档与代码类名一致性。技术栈上依赖极少（运行时只依赖 proper-lockfile 和 zod），其余全是 @deepseek-ai/* 的 peerDependency——它是 DSH 的插件包，不是独立程序。

内置两个技能包（skills/dsh-superagent-github、skills/dsh-superagent-feishu）教会 Worker 用 gh 读 Issue/PR/review/CI，用 GraphQL 的 resolveReviewThread 解决 review 线程。

六、部署难度：需要人陪跑一遍

这是本项目最大的落地门槛。 它没有 Dockerfile、没有 docker-compose，官方安装方式是：

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

除此之外还要求：Node.js 22.19+、pnpm、git 2.32+、tmux、Python 3.8+、GitHub CLI 2.48+（且必须是包装器 gh-agent 走独立 GH_CONFIG_DIR）、一个专用 GitHub 机器人账号（不能用 GitHub App，因为它要读账号通知）、飞书场景还需 lark-cli 与自建应用、模型 Provider 已配置。最后还要写 cordis.patch.yml 填 stateDir 绝对路径、端口、prompt 上限等机器级配置。

有意思的是它把安装流程本身做成了由智能体来执行：SETUP.md 是一份写给"编码智能体看的说明书"——"读这份文件并和我一起把 dsh-superagent 装起来"。它规定一次只问一个问题、每条消息不超过 300 字、先给完整计划再执行、绝不索要任何密钥（需要人手的地方给出精确命令让用户自己敲）。

安全上要注意：两个预设 dsh-superagent-worker / dsh-superagent-router 都以 danger-full-access 跑在操作者的 OS 用户下，能读 home 目录。官方明确建议：要隔离就单独建一个只含机器人凭据的 OS 账号。

七、争议与局限

• 官方自认是研究原型，明说"可能有 bug，编码风格与工程实践可能不一致，用之前请审阅并改造"。而且发布版 ≠ 内部版，论文里的部分设计没实现。
• 单机单仓库：一次只服务一个 GitHub 仓库，不支持 GitHub Enterprise Server，飞书只是可选项。
• 权限模型偏危险：默认全权限运行，隔离要靠人工建账号。
• 强依赖 DSH 生态：peerDependency 全是 ^0.2.1-alpha.2 的 alpha 版本，上游一改就可能不兼容。
• 社区版几乎无外部贡献者：GitHub API 返回的 contributors 列表为空，提交历史极少，基本是单团队自研自放。
• 易被误用为"批量 PR 机器"：官方在哲学文档里专门警告"不要用它来产出量"，说批量 PR 和广播消息对团队是净损耗。

八、行业意义

2026 年下半年，Agent 工程的重心明显从"单体聊天框"转向多智能体协作 + 长期运行 + 可审计。dsh-superagent 最有价值的不是代码量，而是它给出了一套把 Agent 关进笼子的完整设计：准入、授权、幂等、审计、隔离、静默原则。MarkTechPost 用"Router-Worker 编码智能体"来概括它的架构，而社区里已经出现第三方 fork（如 jwangkun/dsh-superagent）把多账号共享 profile 的场景补上。

对研发团队的现实建议：先读 docs/000-philosophy.md 和 002-authorization.md，再决定要不要部署。它真正的产品是那份"Agent 应当如何消耗人类注意力"的设计文档，而不是那 1.5 万行 TypeScript。