DEEPSEEK HARNESS RESEARCH PROTOTYPE · ARCHITECTURE ANALYSIS

dsh-superagent：面向“人类注意力最小化”的主动式研发智能体系统

本报告基于当前仓库源码（src/core, src/app, src/executor, src/sources）与全套领域设计文档（docs/000~008），从第一性原理拆解、主流生态竞品横评、学术/工程范式辨析以及生产落地实操四个维度，全景式剖析 DeepSeek 团队在《Exploring Super-agent Design: Towards a More Autonomous Agent System》背后的核心工程结晶。

项目版本: v0.1.0 (MIT) 宿主底座: DeepSeek Harness (^0.2.1-alpha.2) 核心技术栈: TypeScript 6 / Cordis IoC / SQLite / React 18 代码规模: 70+ 核心模块 / 52 个自动化测试套件

1 : N

Router-Worker 双层解耦

1 个常驻轻量级主 Session 负责研判与路由，N 个隔离 Git Worktree 的执行器并发推进任务。

5,000 ms

前台 Shell 自动转后台阈值

任何阻塞超 5 秒的命令自动降级为后台 Job，确保 Worker 随时响应人类在原线程中的最新追问。

≤ 100 词

IM 消息硬性注意力预算

执行过程保持绝对静默；仅在需要人类决策或成果可评审时发言，且 IM 回复强制限制在一句话内。

100%

事务化持久化与幂等投递

基于 SQLite Effects 队列与 Outbox 收据机制，进程崩溃或重启绝不重放事件或丢失上下文。

EXECUTIVE SUMMARY

核心命题速览（点击卡片进入对应分册章节）

第一章：第一性原理与竞品横评 CH 01

解决什么痛点？如何运转？与同类有何本质差异？

第一性公理：将“人类注意力（Human Attention）”而非算力视为多 Agent 扩展的终极瓶颈。
全链路状态机：完整拆解 Source → Trigger → Thread → Gate/Assessment → Mandate → Ticket → Assignment → Outbox。
四大流派横评：深度对比 dsh-superagent 与 Grok Bot / Grok Build、Muse Agent (Meta)、Hermes Agent (Nous)。

阅读第一章详情 →

第二章：范式审视与方法论辨析 CH 02

到底是全新流派的方法论，还是“旧瓶装新酒”？

客观定性：执行底座是成熟的工程原语（“好瓶”），但在组织协同治理、权限传播边界与注意力经济学代码化上开创了全新的 Attention-Centric Proactive Agent 流派。
六大硬核创新：两阶段准入（确定性 Gate + 语义三元证据）、订阅扇出与追问所有权（Follow-up Ownership & Handback）、动态策略重校验（Mandate Revalidation）等。
12 项反模式剔除：剖析作者团队在实战中踩坑后刻意拒绝的 12 个过度设计概念。

阅读第二章详情 →

第三章：工程可用性与实操指南 CH 03

现在直接能用吗？存在哪些前置约束？如何部署与扩展？

可用性评估：源码完成度极高且内聚，但强依赖 DeepSeek Harness (@deepseek-ai/dsh) 宿主环境与专用账号隔离配置。
Agent-Assisted Setup：独创由你的 Coding Agent 阅读 SETUP.md 进行单步交互式探测与自动配置。
渐进式演进路线：从 off（仅显式指令）到 observe（影子记录 would_accept）再到 auto（全自主接单）。

阅读第三章详情 →

SYSTEM ARCHITECTURE PANORAMA

全景架构图：从外部事件流到隔离工作区的闭环

不同于传统的“聊天框问答式 Agent”，dsh-superagent 是一个挂载在团队协作流（GitHub Issues/PRs/CI 与飞书群聊）上的事件驱动型自治守护系统。下图展示了其核心组件在运行时的完整拓扑关系：

dsh-superagent 四层端到端架构蓝图 (Four-Tier End-to-End Architecture)

外部事件与输出层纯同步事务内核主会话路由层隔离执行池

TIER 01 外部协作源与回写通道 (External Sources & Outbox Channels) src/sources/* · src/app/outbox.ts

GitHub 协作源github-watch

通过专属 gh-agent 轮询 Notifications、Issue/PR 评论、Review 线程与 CI Check 状态变更。

飞书群聊与私聊源feishu-watch

通过纯 Bot 模式的 lark-bot 消费群聊 @ 提及、全量群消息、私聊及历史话题恢复。

Web 监管面板 & APIsrc/client/*

嵌入 DSH 侧边栏的 React 18 控制台；仅置顶等待人工决策的工单与连续 3 次失败的系统告警。

↓ 1. 转换为幂等 Trigger 写入 (engine.receive) ↑ 6. 事务 Outbox 收据幂等发回原对话 (SourceRegistry.send)

TIER 02 纯领域事务引擎 (Core Domain Engine — 零 I/O、单写者同步事务) src/core/engine.ts · src/policy.ts

① Intake

事件幂等去重、越界过滤（scope），记录 Trigger 去向（Disposition）。

② Thread & Fan-out

按线程聚合上下文；若线程已有订阅 Ticket，消息直接扇出给对应 Worker。

③ Gate & Evals

确定性门禁计算授权强度（explicit / inferred），合并批次送交评估。

④ Tickets & Mandate

接单时签发不可变授权凭证 Mandate，管理工单生命周期与恢复重校验。

⑤ Assignments & Replies

绑定底层执行器实例，追踪消息已读状态，按 4 种合法目的校验对外回复。

↓ 2. SQLite Effects 异步持久化队列 (assessment / launch / delivery / relay / reply)

TIER 03 双层解耦智能体会话层 (Router-Worker Agent Sessions on DeepSeek Harness) src/app/sessions.ts · src/executor/dsh.ts

主会话：Main Session (单例常驻路由器) orchestrator

• 预设：dsh-superagent-router（无写文件/无子 Agent 权限，5s 命令自动转后台）
• 职责 1（显式路由）：调用 orchestrator_route 批量接单、挂载已有工单、响应停止或忽略（路由备注强制 ≤ 30 词，严禁编写技术方案）
• 职责 2（主动研判）：通过 MasterAssessor 验证三元语义事实与启用规则，支持 observe 影子记录模式

执行池：Executor Sessions (1 工单 : 1 目录 : 1 会话) worker-<ticketId>

• 预设：dsh-superagent-worker（完整研发工具链 + worker-bin 凭证隔离垫片）
• 工作区隔离：启动前执行 prepare 命令（git worktree add -b agent/<name>）
• 并发与追问自治：受 WorkerSlots 控制（为人类跟进消息预留 +1 特权槽位）；自主裁决本线程后续追问（处理并 ack，或超范围时 handback 退回重路由）

图 0-1：dsh-superagent 四层端到端架构蓝图（从外部事件源、纯事务内核到 Router-Worker 双层会话的完整闭环）

CODEBASE ANATOMY

仓库源码结构与分层边界映射

仓库在架构上严格执行单向依赖法则（Strict Dependency Rule）与单一状态写入者（One Writer Per State）原则。下表梳理了核心目录的工程职责：

目录 / 模块层级	核心文件代表	架构角色与依赖约束	核心职责说明
领域内核层 `src/core/`	`engine.ts`, `model.ts`, `intake.ts`, `evals.ts`, `tickets.ts`, `assignments.ts`, `stage.ts`, `ports.ts`	零外部依赖 / 零 I/O 仅依赖 Node 内置哈希，所有方法均为同步事务调用。	定义 11 个核心领域概念与不变量。`Engine` 是 Triggers、Threads、Decisions、Tickets、Assignments 的唯一写入者，并按调用方角色暴露窄接口（`Pick`）。
应用编排与存储层 `src/app/`	`runtime.ts`, `store.ts`, `effects.ts`, `outbox.ts`, `assessment.ts`, `sessions.ts`, `prompts.ts`, `settings.ts`	Composition Root & Glue 连接 SQLite、DSH Session 与领域端口。	管理 SQLite 持久化、`Effects` 异步副作用队列、`Outbox` 消息收据、主从 Session 生命周期、版本化 Prompts 组装以及 HTTP 管理 API。
执行器适配层 `src/executor/`	`dsh.ts`, `background.ts`	Worker 调度与槽位控制对接 DSH Agent 与 Subprocess 服务。	为每个 Ticket 创建独立目录（执行 `prepare` 如 `git worktree add`）与专属 Session；管理 `WorkerSlots` 并发限制（含人类消息 `+1` 优先槽位）与后台任务 30 分钟超时回收。
事件源插件层 `src/sources/`	`kind.ts`, `registry.ts`, `github.ts`, `feishu.ts`	可插拔 SourceKind 协议禁止导入 `src/app`，仅通过 `SourceContext` 交互。	将 GitHub 通知/Issue/PR/CI 状态以及飞书群消息转化为标准 `Trigger`，提供上下文分页读取器（`threadContext`）与幂等回复通道（`Channel`）。
基础设施与隔离层 `src/infra/` & 根模块	`environment.ts`, `commands.ts`, `health.ts`, `policy.ts`, `setup.ts`, `deployment.ts`	安全垫片与健康看板管理子进程环境变量与 CLI 传输。	生成 `worker-bin` 命令垫片（拦截危险命令、绑定专属 `gh`/`lark-cli`）与 `worker-gitconfig`，清除宿主敏感 Token 环境变量，维护单写者 `HealthBoard`。
监管面板前端层 `src/client/`	`app.tsx`, `overview.tsx`, `ticket.tsx`, `eval.tsx`, `prompts.tsx`, `settings.tsx`	React 18 Web UI 仅从宿主侧导入纯类型与常量。	嵌入 DSH Web 侧边栏的 Superagent 面板。遵循“默认静默、异常置顶”原则，依次回答：现在有什么需要我处理？系统健康吗？某项工作的来龙去脉是什么？