dsh-superagent-prototype

00 / EXECUTIVE SUMMARY执行摘要

这个仓库最值得研究的不是「Router 分活、Worker 干活」这句口号，而是它为了让智能体尽量少打扰人而建立的一整套可审计、可拒绝、可恢复的授权状态机。文章里最吸睛的几个机制，在开源代码里其实并不存在。

01 / VERIFIED FACTS事实核验：不转述，先对齐

以下数据来自 GitHub REST API、本地浅克隆与 git log，均为可复跑的一手证据（见 §11）。凡与二手解读冲突处，以仓库文件为准。

“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.” README.md（研究原型声明）—— 这是本次「文章 vs 代码」核验的合法性依据

02 / METHOD研究方法与证据分级

为避免「把宣传稿当实现」，本次采用三级证据，并遵守一条原则：每个结论都要有一条命令能复跑。

核验手法：① 用 GitHub API 拿元信息与提交列表；② 浅克隆后逐文件读文档与 Prompt；③ 对文章中的明星机制做全仓关键词零命中检验；④ 用正则从 src/app/tools/*.ts 反查工具数量，与 docs/007 的表格对账；⑤ 审计 pnpm-lock.yaml（488 个包条目、289 条 integrity、无 git/file 外部引用）后安装依赖并运行 pnpm check。

图表均为手写 SVG，不依赖 Mermaid / Chart.js / 外部字体或 CDN，断网可完整阅读与打印。交付前另用本地 Chrome 无头渲染截图核对了首屏，并对 3 张 SVG 做了几何与深浅色对比度静态校验（文字溢出宿主色块 / 浅色字落白底 / 超出画布），结果 0 处问题。

03 / THE GAP文章构想 vs 原型实现：逐条核验

这是本报告的核心。左列是官方技术报告（B 级）提出的机制，右列是我在 216 个文件里实际找到的东西。

04 / ARCHITECTURE架构解剖：一条 Trigger 的完整旅程

下图按 docs/001 的领域流 + docs/007 的实现映射绘制。实线为主流程，虚线为订阅扇出（旁路、无授权），底部为支撑层。

目录职责与依赖规则

单写者原则（docs/007:258-274）是这份代码最值得抄的一条：每类状态只有一个写入者，其它模块只读或请求它写。Engine 写领域对象、Source 只写自己的读位置与 Thread meta、Settings 写设置与历史、Prompts 写版本、Effects 写队列行、Outbox 写回执、HealthBoard 每个条目由认领它的部件独占。ctx.effect() 的 disposer 保证注销后迟到的上报无效。

05 / AUTHORIZATION授权模型：这套系统真正的护城河

「主动」是最容易做成灾难的特性。原型的做法是把「谁可以开工」做成代码强制的状态机，而不是交给模型自觉。

两条互不混用的路径

强度、准入表与 accept mode

恢复与顺序：为「长期运行」做的脏活

• 幂等：Trigger id 由来源 id 派生（key()），重复读取返回 duplicate；发消息用 message.id 作幂等键（GitHub 隐藏标记 / 飞书 idempotency key）。
• 存后做：relay / candidate / launch / delivery / reply 都先在事务里落库，提交后再执行；失败按 2s 起指数退避（reply 为 5s→300s）。
• 顺序：同一 Ticket 发往同一会话的消息按排队顺序发出，前一条失败 3 次才放行后一条；relay 与 notice 各自保序，失败会阻塞同类后续。
• 重启恢复：Session / 目录 / Subscription / 待处理消息 / 「哪些 Input 已被 Session 读进历史」都持久化；被中断的 Assignment 带 recovery note 重启，按 Ticket 从旧到新。
• 后台工作：轮次结束时仍有 job / 子智能体运行则保留 worker slot 且不报 waiting；30 分钟上限杀 shell job（子智能体可继续）；交接给人时立即释放 slot。

06 / ENGINEERING工程实现亮点

07 / DSH INTEGRATIONDeepSeek Harness / Cordis 集成解剖

对做 DSH 插件的开发者，这一节是全仓库最可直接复用的部分。它不是普通 npm 包，而是一个 bundle：用 cordis.patch.yml 往宿主插件树里插入条目，用 preset 定义 Session 的能力边界。

三层挂载

Cordis 插件契约（可直接照抄）

// src/index.ts —— 主插件
export const name = 'dsh-superagent'
export const inject = ['agents','sessionController','sessionPersistence','workspaceRegistry',
  'permissionPresets','tools','systemPrompt','skills','webServer','llm','subprocess']
export async function apply(ctx: Context, config: DeploymentConfig) {
  ctx.inject(['settings'], child => child.effect(() => child.settings.configure({ auto: false }, ctx.fiber)))
  const restart = () => ctx.fiber.restart().then(() => ctx.get('settings')?.describe())
  const runtime = new Runtime(ctx, machine, restart)
  ctx.effect(() => async () => { await runtime.stop() })   // disposer
  await runtime.ready
}

// src/sources/github.ts —— Source 子插件（注入宿主暴露的 orchestrator 服务）
export const name = 'dsh-superagent-github'
export const inject = ['orchestrator']
export function apply(ctx: Context) {
  ctx.effect(() => ctx.orchestrator.sources.register(githubKind), 'github: source kind')
  ctx.effect(() => { /* 轮询循环 + AbortController，返回 disposer */ })
}

值得注意的两个细节：① ctx.effect() 的返回值就是清理函数，注销/重启时自动执行，迟到的 report 在注销后无效；② 因宿主 settings 服务在插件重启期间不再提供该条目，代码在 fiber.restart() 后主动调 describe() 让已打开的配置表单重新可编辑 —— 并留了一条 TODO 说明这是临时绕过。

构建：一份源码，两个目标

SourceKind：加一个来源要实现的 8 个面

docs/008-cookbook.md（425 行）给了一个虚构 hookq 队列的完整 11 步配方，是仓库里最实用的扩展文档。协议定义在 src/sources/kind.ts：

最后还要在 tsdown.config.ts 加入口、package.json 加 exports、cordis.patch.yml 加 disabled 的 insert，并把新模块与测试登记进 docs/007 的两张索引表 —— 因为 tests/docs.spec.ts 会检查索引完整性。

08 / BENCHMARK实验数据辨析：别把论文数字当仓库能力

官方技术报告给了一组合成负载结果（B 级，多家媒体交叉一致）。实验设定：每次约 300 条消息、其中约 20 条真实工作请求、每种配置跑 5 次；编码任务被换成「只消耗时间的假工具」，所以测的是调度与协作，不是代码质量。

Router 侧压测：事件速率从约 1 条/分钟升到 40 条/分钟时，单次决策分摊推理时间从 6.4s 降到 1.6s（平均批量 2.8 条）；去掉订阅直通会让 Router 决策数 +30%。

09 / RISKS风险与边界：官方自己写清楚了什么

“Open questions: Trust: which Trigger fields are trusted, such as the Source's actor and Thread membership, and which are not, such as the body and quotes. Deployment isolation: the agent's profile on its own pinned DeepSeek Harness installation…” docs/007-architecture.md:614-618 —— 官方自己承认的两个未解决问题

10 / RECOMMENDATIONS落地建议

以下为 C 级判断，结合「DSH 插件开发者 / 多智能体系统研究者」这一使用场景给出。

与常见多智能体模式的对比（C 级判断）

一句话概括差别：多数多智能体系统在优化「怎么把活干完」，这套系统在优化「什么时候不该动、什么时候才该开口」。这也是为什么它把大量代码花在 Mandate 复验、消息顺序、回执、unread 判定与阶段定义上。

11 / REPRODUCE可复跑命令

本报告所有 A 级结论都能用下列命令复核。工作目录为浅克隆根目录。

# 1. 元信息与提交历史
curl -s https://api.github.com/repos/deepseek-ai/dsh-superagent-prototype | python3 -m json.tool
curl -s 'https://api.github.com/repos/deepseek-ai/dsh-superagent-prototype/commits?per_page=30'

# 2. 克隆与规模
git clone --depth=50 https://github.com/deepseek-ai/dsh-superagent-prototype.git
find . -path './.git' -prune -o -type f -print | wc -l          # 216
find src -name '*.ts' -o -name '*.tsx' -o -name '*.css' | xargs cat | wc -l   # 15587
find tests -type f | xargs cat | wc -l                           # 14960

# 3. 明星机制零命中检验（关键结论）
for w in watchdog speculative spill daemon; do
  printf '%s: ' "$w"; grep -ril --exclude-dir=.git --exclude-dir=node_modules "$w" . | wc -l
done                                                             # 全部为 0

# 4. 工具数量与 docs/007 表格对账
grep -o "name: 'orchestrator_[a-z_]*'" src/app/tools/main.ts     | sort -u | wc -l   # 13
grep -o "name: 'orchestrator_[a-z_]*'" src/app/tools/executor.ts | sort -u | wc -l   # 5
grep -n "orchestrator_read" src/app/tools/tool.ts                  # +1 共享工具 → 14 / 6

# 5. 易误读点：memory.ts 到底是干什么的
sed -n '1,10p' src/core/memory.ts                                 # JSDoc: for testing

# 6. 存储实现与默认配置
grep -n 'node:sqlite\|DatabaseSync' src/app/store.ts
grep -n "mode: z.enum\|maxWorkers" src/policy.ts                  # observe / 3

# 7. 依赖审计 + 全量校验（需 Node 22.19+ / pnpm）
python3 -c "import json;d=json.load(open('package.json'));print(len(d['dependencies']),len(d['peerDependencies']))"
grep -c 'integrity:' pnpm-lock.yaml                              # 289
pnpm install --frozen-lockfile && pnpm check                    # typecheck + 全量测试 + build
# 默认并发若遇 vitest forks worker 启动超时（本机资源问题），改为保守并发复跑：
pnpm exec vitest run --maxWorkers=2 tests/panel-deployment.spec.tsx \
  tests/panel-panel.spec.tsx tests/controls.spec.tsx tests/navigation.spec.ts
pnpm build                                                     # 单独验证双目标构建

来源清单

12 / VERDICT结论

dsh-superagent-prototype 的价值不在「更自主」，恰恰相反 —— 它是一份关于如何给自主性装上刹车的工程样本。

它把「人的注意力」提升为第一等设计约束，然后围绕这个约束建立了一整套可验证的机制：确定性 Gate 挡在模型之前、版本化 Policy 与不可变 Mandate 说明「凭什么可以做」、Subscription 让上下文流动却不传递权限、Engine 单写者 + 事务 + 持久化 Effects 保证重启可恢复、Outbox 回执保证消息顺序与不重复、Ticket 阶段机保证面板只呈现真正需要人的事。Router 被拿掉干活工具这一点，把文章里最漂亮的观察变成了代码事实。

同时必须看清它的边界：Watchdog、投机执行、Inline/Spill、云端存算分离、长期记忆、多 Router 都不在这个仓库里；它是单机单仓库、绑定 DSH alpha 版本、以 danger-full-access 运行、数据只增不删、且没有公开 issue 通道的单 commit 发布快照。官方把信任边界与部署隔离原样写进了 Open questions，这份诚实比任何「已解决」的宣称都更值得信任。