DSH-SUPERAGENT 架构深度解读白皮书
CHAPTER 01 · FIRST-PRINCIPLES DECONSTRUCTION & BENCHMARK

第一性原理拆解：本质定位、运转机制与同类生态对比

从最底层的“人类注意力约束”出发，剖析 dsh-superagent 的系统边界、输入输出契约、核心状态机流转，并将其置于当前最前沿的自主研发 Agent 坐标系（Grok Bot / Grok Build、Meta Muse Agent、Nous Hermes Agent）中进行正交对比。

1.1 FIRST PRINCIPLES & DESIGN PHILOSOPHY

第一性原理：为什么说“人类注意力”是 Agent 系统的终极瓶颈？

在传统的单会话 Coding Agent（如 Claude Code、Cursor Agent、早期 Devin）中，默认的交互假设是“人机 1:1 结对编程”：人类在终端或 IDE 里紧盯屏幕，随时审批命令、纠正方向、回答 Agent 抛出的澄清问题。然而，当我们将视角从“个人辅助工具”切换到“团队级全天候自治成员（Proactive Team Agent）”时，物理定律发生了根本性转移：

核心公理（源自 docs/000-philosophy.md 第 5 行）

“Take as little human attention as possible, and give as much value as possible.”
（消耗尽可能少的人类注意力，交付尽可能高的实际价值。）

第一性推演：一个能够替整个研发团队行动的 Agent，同样具备瞬间瘫痪整个团队注意力的破坏力。如果 Agent 在群聊或 GitHub 上频繁播报内部进度、抛出未经深思的方案探讨、制造大量半成品 PR，那么它节省的编码时间将远不足以抵消全员阅读噪音所损失的心流成本。因此，本项目的每一行代码、每一个配置项、每一句提示词，都以“单位注意力产出比（Value per Attention）”作为唯一裁决标准。

由公理推导出的“智能体行为五定律”与“极简架构四铁律”

对 Agent 行为的五项刚性约束 Agent Behavior
  1. 无授权不行动（Authorized Only）：仅响应白名单成员的显式指派，或符合团队书面规则（Policy Rules）的主动任务；主动规则默认处于只记录不执行的 observe（观察）模式。
  2. 非必要不发言（Silent Progress）：收到请求仅做一次具体确认（说明改什么、预期结果是什么）；执行期间保持绝对静默；仅在成果就绪、遇到必须人工拍板的阻塞、或彻底无法完成时才再次发声。
  3. 单次单问结构化（One Question at a Time）：严禁把问题藏在长篇报告里，必须通过结构化字段 human_action 每次只问一个具体问题。
  4. 按影响半径止损（Stop by Impact, Not Effort）：局部修改直接推进到可合入的 PR；一旦发现涉及公共接口变更或跨模块架构重设计，立即停止并提交带明确问题的草稿，绝不擅自替人类做产品/设计决定。
  5. 绝对诚实（Honest Reporting）：未完成的草稿严禁伪装成 Ready；UI 改动缺少真实的 Before/After 对比截图一律视为未就绪；严禁为了“不打扰人类”而绕过安全或权限限制。
对系统架构的四项极简铁律 System Design
  1. 概念最小化（Few Concepts）：内核仅保留 11 个不可化约的领域原语（如 Source, Trigger, Thread, Mandate, Ticket）。任何业务特殊需求要么成为现有实体的属性，要么写成 Prompt，绝不为特定业务新增领域概念。
  2. 配置最小化（Few Settings）：只要某个默认值适合 95% 的团队，就直接砍掉该配置项；能用自然语言描述的团队习惯（如谁是 Review Bot、多少行内允许自动合并）全部收归版本化的 Prompt 文本，而非做成复杂的表单开关。
  3. 异常置顶面板（Attention-First Panel）：Web 监管面板第一屏永远只展示“正在等待人工处理的工单”与“连续失败满 3 次的系统故障”。健康的组件不占任何视觉空间。
  4. 严格拓扑演进（Linear Documentation & Dependency）：从 000 到 008 的文档与代码模块严格保持单向依赖，上层绝不反向污染底层领域模型。
1.2 WHAT IT IS & HOW IT WORKS

本质定位与运转机制：它是做什么的？如何做到？

一句话定义：dsh-superagent 是构建在 DeepSeek Harness (DSH) 宿主之上的、面向单一 GitHub 代码仓库的主动式研发协同智能体系统（Proactive Coding Agent Bundle）。它持续监听 GitHub（Issues、PR、代码评审、CI 状态）以及可选的飞书群聊/私聊，在严格的策略网关（Policy Gate）与语义研判（Assessment）控制下，将合规的显式指令或潜在缺陷转化为受授权约束的工单（Ticket），并在各自独立的 Git Worktree 目录与专属 Agent Session 中异步完成调查、编码、测试、自审与 PR 交付。

核心运转机制一：Router-Worker（主从双层会话）物理解耦

为了解决单会话 Agent“一边跑耗时编译测试，一边漏掉人类新消息或阻塞新任务调度”的顽疾，dsh-superagent 在 cordis.patch.yml 与 src/app/sessions.ts 中定义了两个权限、工具集与上下文完全隔离的角色：

维度 主会话：Main Session (orchestrator) 执行器会话：Executor Session (worker-<ticketId>)
生命周期与数量 全局唯一、常驻在线（单例） 按 Ticket 动态创建（1 个 Ticket 对应 1 个持久 Session + 1 个独立工作目录）
DSH 预设 (Preset) dsh-superagent-router dsh-superagent-worker（其派生的子 Agent 使用 standard）
核心职责边界 只做评估与路由，绝不写代码或制定技术方案：
1. 评估主动候选事件（orchestrator_eval*）；
2. 批量路由显式请求（orchestrator_route：接单/挂载/停止/忽略）；
3. 将 Worker 的成果或问题转发回源渠道（orchestrator_reply）。 		全权负责技术实现与源线程追问裁决：
1. 阅读完整原始上下文与代码库 AGENTS.md；
2. 编码、运行测试、创建并维护 PR、处理 CI 失败与 Code Review；
3. 自主裁决本线程上的后续人类消息（处理并 ack，或超范围时 handback）。
工具集与权限裁剪 严格受限 禁用文件写入/编辑（write: false, edit: false）、禁用子 Agent、禁用 Web 搜索、禁用 Todo；路由备注严格限制 ≤ 30 词。 全功能研发 拥有完整文件系统读写、代码搜索、Web 搜索、Todo 及派生子 Agent（spawn）能力；但禁用交互式弹窗（如 ask_user_question）。
5 秒非阻塞铁律 两者均强制配置 timeoutMs: 5000 与 waitTimeoutMs: 5000：任何前台 Shell 命令或任务等待超过 5 秒自动转为后台 Job。主会话禁止 sleep，防止阻塞新事件分流；Worker 在后台编译期间可随时在下一步接收人类的最新补充指令，Job 完成后自动唤醒当前槽位。

核心运转机制二：全链路事件流与状态机（从 Trigger 到 Ticket 终结）

当外部世界发生一个事件（例如某人在 GitHub Issue 评论，或飞书群有人反馈按钮文案错误），系统严格按照以下双路径（Two Paths）流转：

双路径事件路由与主从协同流程 (Two-Path Event Routing & Handback Flow) Intake → Subscription Fan-out vs. Eval Gate
步骤 01：外部事件捕获与转换Source → Trigger
GitHub 或飞书轮询器捕获新消息/状态，丢弃 Agent 自身消息，生成带稳定哈希 ID 的不可变 Trigger。
步骤 02：幂等写入与订阅检查Engine.receive()
校验 SourceKind.scope 监听范围；检查该 Thread 是否已有活跃或可唤醒的订阅 Ticket，由此分流为两条正交路径：
路径 A：已有工单订阅线程 (Subscription Fan-out) 零延迟直达 Worker
A1
绕过 Eval 直接投递：消息作为 TicketInput 直接扇出给订阅该线程的 Worker Session；若工单已结束且非人工停止，人类消息经 Mandate.revalidate 重校验后自动唤醒工单。
↓
A2
锁定主会话路由权：向 Main Session 发送 followupRelay 知会，此时主会话仅允许响应人类的显式 stop 指令，严禁重复接单或改派。
↓
A3
Worker 自主裁决归属：
• 在授权范围内：调用 orchestrator_ack 确认并继续修改代码；
• 超出范围 / 属于其他工单：调用 orchestrator_trigger_handback 退回并附带一句话原因，退回后自动转入右侧 路径 B！
路径 B：新线程或被退回消息 (Gate & Eval Path) 门禁与主会话研判
B1
Gate 确定性门禁计算强度：根据发送者白名单与准入表计算 Strength：
• explicit（白名单 @提及）：进入快速路由卡片；
• inferred（观察域未提及/Bot）：进入主动评估队列。
↓
B2
Main Session 路由或语义评估：
• 显式请求：调用 orchestrator_route（accept / attach / stop / ignore）；
• 推断候选：调用 orchestrator_eval 核验三元语义事实与启用规则。
↓
B3
原子创建工单与拉起执行器：若决策为 accept，单事务创建 Ticket + Mandate + Assignment，入队首次确认回复，并通过 Effects: launch 创建独立 Git Worktree 启动 Worker。
图 1-1：dsh-superagent 双路径事件分流与主从协同机制（对比“订阅直达快车道”与“新任务门禁评估车道”）

为了保证在长周期异步运行中状态绝对一致，src/core/model.ts 与 src/core/stage.ts 为每个 Ticket（工单） 定义了严格互斥、自顶向下匹配的 7 个生命周期阶段（Stages），按优先级分为三大状态组：

Ticket 生命周期阶段与优先级匹配表 (Ticket Lifecycle Stages — src/core/stage.ts) 自顶向下首个命中条件生效
P1 需人工介入组 (Person Stages)

面板第一屏强制置顶；暂停自动机器输入，等待人类动作解封：

  • ① person / deliveryInput undelivered
    向 Worker Session 投递消息失败（2s → 60s 指数退避重试中）。
  • ② person / answerAwaiting answer
    Worker 提交了结构化提问 Attention，正等待人类在原对话回答。
  • ③ person / reviewAwaiting review
    最新报告为 ready 且关联了未关闭的 PR，等待人类 Code Review 合入。
  • ④ person / blocked, failedBlocked · Failed
    Worker 报告阻塞或启动/执行失败；一旦人类发来新消息或点击 Retry 即刻解除锁定转入 Working。
P2 自治运行与静默等待组 (Working & Idle)

无需打扰人类，系统在后台自主排队、编码或监听外部事件：

  • ⑤ working / queuedQueued
    已接单创建 pending Assignment，正在等待空闲的 WorkerSlots 并发槽位。
  • ⑥ idleWaiting for a Trigger
    当前回合已结束且无后台命令，或上报了 waiting；释放槽位，静默等待订阅线程上的新评论或 CI 状态。
  • ⑦ workingWorking
    正在准备 Git Worktree 目录、模型正在推理执行工具、或回合虽结束但仍有后台 Shell Job / 子 Agent 在跑（最长保留槽位 30 分钟）。
P3 终结态与无缝唤醒 (Ended & Resume)

工单闭环归档，但保留订阅关系以支持跨周期无缝续接：

  • completed / merged / closedDone
    无 PR 任务直接报告 ready，或绑定的所有自有 PR 均已 Merged / Closed。
  • droppedNothing to do
    Worker 调查后确认无法复现或无需改动，静默结束且不发骚扰消息。
  • stopped (人工终止)Mandate Withdrawn
    人类显式下达 stop 指令，永久撤销 Mandate，后续消息不再唤醒。
  • 🔄 跨周期无缝唤醒机制：
    除 stopped 外，已结束工单一旦收到人类在原线程的新评论，只要通过 Mandate.revalidate 校验，无需重新 Eval 即刻恢复为 Open → Working！
图 1-2：Ticket 7 大运行阶段优先级矩阵与终结态无缝唤醒机制
1.3 SYSTEM INPUTS & OUTPUTS

输入（Inputs）与输出（Outputs）全契约解析

1. 系统输入（Inputs）：从外部事件到两级准入过滤

系统并不直接把原始 Webhook JSON 塞给大模型，而是通过三层漏斗将外部信号转化为受控输入：

  • 第一层：Source 接入与范围过滤（SourceKind.scope）
    目前内置两大事件源插件：
    • GitHub Source (src/sources/github*.ts)：默认轮询 Agent 专属账号的 GitHub Notifications、已订阅的 Issues/PRs 评论与 Review 线程、关联 PR 的 CI Check 状态变更以及 PR 合入/关闭事件。可选开启“全量观察开关”（observeIssues, observePulls, observeComments, observeCi）以监听仓库所有新动态。
    • Feishu Source (src/sources/feishu*.ts)：通过 lark-cli 接收飞书群聊事件、历史消息恢复与话题轮询。支持按群配置“仅接收 @ 提及（mentions）”或“接收全部消息（all）”，以及是否接收私聊（directMessages）。
    过滤规则：Agent 自己发出的消息在进入领域前直接丢弃；不在监听范围内的消息记录为 filtered（供面板审计）但不创建 Thread。
  • 第二层：Gate 确定性准入矩阵（src/policy.ts）
    任何进入 Eval 的 Trigger 首先经过纯代码实现的 Gate，根据发送者身份（是否在白名单 allowed 或机器人白名单 bots）、是否直接寻址 Agent（mention / direct）以及接收域准入表（Admission Table）计算出授权强度（Strength）：
发送者类型与寻址状态 默认准入结果 (Strength) 可配置选项 (Admission Cell) 下游处理路径
白名单成员 (Listed) + 直接 @ 或私聊 Agent explicit (明确授权) 固定为 explicit（不可削弱） 免除规则匹配，直接交由主会话 orchestrator_route 快速派单。
白名单成员 (Listed) + 未 @ Agent（仅在开启“全部消息”域生效） inferred (推断候选) inferred (默认) / ignore 进入主动评估（MasterAssessor），需建立三元语义证据并匹配至少一条启用规则。
非白名单成员 (Unlisted) + 直接 @ Agent ignore (忽略) ignore (默认) / inferred / explicit 若设为 explicit（如公开支持群），则群内任何人 @ 均可直接派单。
非白名单成员 (Unlisted) + 未 @ Agent（或默认分支 CI 失败事件） ignore (忽略) ignore (默认) / inferred 可将默认分支 CI 设为 inferred，配合规则实现 CI 挂掉时自动排查修复。
白名单 Bot (Listed Bot，如 dependabot[bot]) inferred (最高仅限推断) 受全局 Accept Mode 控制 Bot 永远不可能获得 explicit 权限，也无权停止工单。
  • 第三层：主动研判的三元语义事实（AdmissionDirectionSchema）
    对于所有 inferred（推断候选）事件，主会话在调用 orchestrator_eval_decide 时，代码层（directionAllowed）强制要求模型必须从上下文中证实三个独立布尔/枚举事实并附上原文引证（intent_evidence），缺一不可：
    1. implementation_requested === true：讨论中确实表达了修改当前项目的明确意图（而非闲聊、抱怨或讨论竞品）；
    2. target_basis !== 'undetermined'：修改目标必须是 specified（明确指定了改成什么样，如“把按钮改成 Save”）或 existing-standard（恢复已确立的客观标准），绝不允许在目标未定时由 Agent 自由发挥设计；
    3. requires_design_decision === false：不存在尚未收敛的产品、交互或视觉层级分歧。

2. 系统输出（Outputs）：严守边界的四大交付物

系统的所有外部副作用均受 Outbox 与环境垫片（Shims）管控，分为四类：

① 代码与 GitHub 仓库交付物 Code & PRs

Worker 在独立目录（默认通过 git worktree add -b agent/<name> 创建）中完成开发后，通过专用账号 CLI（gh-agent）推送分支并创建 Pull Request。

  • 真实视觉证据：凡涉及 UI 变更，PR 描述必须包含真实渲染的 Before & After 截图对比，否则禁止标记为 ready。
  • Reviewer 自动署名致谢：当人类 Reviewer 提出评审意见并被采纳后，Worker 会通过 git filter-branch 与 git interpret-trailers 自动将该人类 Reviewer 的 Co-authored-by 写入分支所有 Commit。
  • 双账号安全自动合并：Agent 账号自身绝不执行合并；仅当配置了第二个合并专用 CLI、代码变更 < 200 行、且所有必需审批已覆盖最新 Commit 时，才可挂载 --auto --merge。
② 四类结构化渠道回复（ReplyRequest） Channel Replies

引擎的 Replies 模块规定，向 GitHub 或飞书发送的任何消息必须声明以下四种明确目的（Purpose）之一，否则直接被内核拒绝：

  • acknowledgement（接单确认）：每个新请求仅发送一次，点明修改对象与预期结果。
  • attention（人工决策提问）：当 Worker 上报 human_action 时，精准路由到引发该问题的人类消息所在对话。
  • answer（直接答复）：针对人类在线程中提出的明确问题给予简短回答（IM 强制 ≤ 100 词）。
  • result（最终成果交付）：仅当 Ticket 进入 ready、completed 或 merged 状态时才允许发送 PR 链接与用户可见结论。
1.4 ECOSYSTEM BENCHMARK

与现有主流同类 Agent 的深度对比（Grok Bot / Muse / Hermes）

当前 AI 研发 Agent 生态正在经历从“IDE 副驾驶”向“自主异步 Agent”的跃迁。我们将 dsh-superagent 与业界最具代表性的三款同类标杆系统——Grok Bot / Grok Build (xAI)、Muse Agent / Muse Code (Meta) 以及 Hermes Agent (Nous Research) 进行多维解构对比：

对比维度 dsh-superagent (DeepSeek) Grok Bot / Grok Build (xAI) Muse Agent / Muse Code (Meta) Hermes Agent (Nous Research)
第一性设计哲学 人类注意力最小化
以团队注意力成本为核心度量，强调静默执行、受控主动性与权限可审计。		 云端数字队友 (Cloud Teammate)
赋予每个 Bot 独立的云电脑与专属工程角色，强调全天候多角色并行值守。		 高吞吐并发重工程 (Parallel Workstreams)
围绕终端重度开发流，强调架构规划后向多后台 Worker 扇出大规模重构。		 自进化个人中枢 (Self-Improving Harness)
强调跨会话持久记忆、从历史经验中自主提炼与迭代可复用 Skill。
触发与交互范式 团队协作流事件驱动 + 两级准入：
监听 GitHub 全事件与飞书群聊，通过 Gate 准入表 + 语义三元证据区分显式指令与主动观察。		 角色例程 (Routines) + 任务指派：
用户在 Web/TUI 为不同领域 Bot 设定定时巡检例程（如盯 CI、审 PR）或直接派发工单。		 开发者终端 Prompt 驱动：
以工程师在 CLI 终端发起复杂工程指令为主，由主规划器拆解并调度后台子任务。		 全渠道个人入口 + Cron 调度：
常驻个人 VPS/本地服务器，通过 Telegram、Discord、CLI 或定时任务唤醒。
多智能体拓扑架构 1 Router + N Workers 强解耦：
Router 严禁写代码或做技术方案（备注 ≤ 30 词），仅做无偏路由；Worker 独占 Ticket 与后续追问所有权。		 多专家 Bot 协同 (Multi-Bot Domains)：
按前端、后端、Infra 划分多个独立 Bot 实例，各自维护领域上下文与云沙箱。		 Planner + Background Workers：
主 Agent 进行深入的架构设计与任务分解，再分发给多个隔离 Worktree 的后台 Worker。		 单体持久内核 + 子 Agent 委派：
以具备长期记忆的单体 Agent 为核心，按需派生子进程执行专项任务。
权限边界与安全治理 内核级 Mandate 与版本化 Policy：
不信任任何外部文本；基于 Mandate 追踪授权来源，支持策略变更热通知与恢复前重校验（Revalidation）。		 云端沙箱隔离 (Cloud VM)：
每个 Bot 运行在独立的云端虚拟机环境，通过平台级账号权限隔离。		 本地 Git Worktree + Append-only 日志：
侧重本地代码工作树隔离与不可变决策日志，面向单人开发者权限模型。		 宿主级操作权限 + 技能沙箱：
侧重个人助理的全能访问能力，团队级多人多源 RBAC 并非其设计重点。
沟通与防骚扰机制 代码级强制静默与字数封顶：
内置 4 种合法回复目的校验、IM ≤ 100 词硬上限、Bot Review 最多 3 轮熔断机制。		 依赖系统提示词与角色设定，状态流实时展示在工作台，消息密度较高。 面向终端开发者的交互式流式输出与后台进度汇总。 对话式交互风格，侧重像私人管家一样主动汇报与持续沟通。
适用场景定位 多人研发团队共享的代码仓库自治成员（无缝嵌入现有 GitHub + IM 流程）。 希望在云端直接雇佣多个全栈/专项“AI 虚拟工程师”的团队。 单兵作战的高级工程师在本地终端驾驭大型跨文件重构与调试。 追求长期记忆沉淀、跨平台个人自动化与自我进化技能库的极客用户。

架构能力重心对比可视化

为了更直观地展现四者在设计取向上的差异，下图从六个正交工程维度展示了各自的架构重心分布：

四大 Agent 系统核心设计重心对比 (0 - 100 相对工程权重) dsh-superagent (DeepSeek) Grok Bot / Build (xAI) Muse Agent (Meta) Hermes Agent (Nous) 1. 团队注意力保护与静默治理 96% 2. 多人多源权限与策略安全边界 94% 3. 复杂对话线程归属与防重路由 97% 4. 本地 Git Worktree 并发研发 Muse 95% 5. 跨任务自学习与技能沉淀闭环 Hermes 96% 6. 全托管云端多虚拟工位开箱即用 Grok 95%
图 1-3：dsh-superagent 与 Grok Bot、Muse Agent、Hermes Agent 的六维工程重心对比
核心差异总结：为什么 dsh-superagent 独树一帜？

Muse Agent 解决的是“单人开发者如何在终端里同时推进多个重度重构”；Hermes Agent 解决的是“如何让个人 Agent 拥有长期记忆并自我编写技能”；Grok Bot 解决的是“如何在云端虚拟电脑里雇佣按角色分工的 AI 员工”。
而 dsh-superagent 解决的是一个此前几乎被所有开源框架忽视的“社会化工程难题（Socio-Technical Problem）”：当一个 Agent 进入真实的 20 人研发群和共享 GitHub 仓库时，如何保证它既能主动眼里有活，又绝对不会越权、不会由于 Prompt Injection 泄露权限、不会在群里刷屏惹怒同事、也不会在多人插话时搞乱任务归属？