ARTICLE · 1334276
dsh-superagent 文档|001 领域模型
发布时间:2026-11-09 14:29:49 最近访问:2026-11-09 14:29:50
dsh-superagent 文档|001 领域模型
本文档为 dsh-superagent 的各个概念命名,并说明每个概念所遵守的规则。代码、智能体所调用的工具、面板以及其他文档都使用这些术语,而不使用其他任何术语。遵循 000 理念,模型只保留工作所需的概念,而一个业务需求会成为其中某个概念的一项属性。
流程
工作从触发(Trigger)流向评估(Eval),再流向执行。来源(Source)产生触发。触发作为上下文扇出(fan out)到订阅了其所在线程(Thread)的那些工单(Ticket)。以此方式到达某工单的人的消息会留在该工单;其余每一个触发都进入评估,由评估判断它是否在请求新的工作。当评估接单时,它带着一个授权(Mandate)创建一个工单。派工(Assignment)把工单交给一个执行器(Executor),结果通过渠道(Channel)回到来源。
flowchart LR S[来源] -->|触发| T[线程] T -->|批量| E[评估] T -->|订阅扇出| K[工单] E -->|带授权接单 / 停止| K E -->|忽略 / 未完成| X[已记录] P[策略变更] -->|通知| K K -->|派工| W[执行器] K -->|渠道| S
概念
来源、线程、评估、授权和订阅(Subscription)构成核心领域;其余概念用于支撑它们。
| | | |
|---|
| 一条事件的流。一个来源种类是可复用的实现;一个来源实例是该种类的一种配置:它是否运行、以及它监听什么 | 持有自己的读取位置和它自身的机器人身份。定义什么算作一个事件,包括只在一段时间内成立的条件。在它们进入领域之前,丢弃机器人自己的消息以及落在它所监听范围之外的触发。把每个触发翻译成它所归属的线程,以及用于回复的渠道地址 | |
| 一个不可变的事件,带有来源自身的元数据,例如其发起者 | 归属于一个或多个线程。对同一个触发接单两次也只会创建一个工单 | |
| 按时间顺序排列的触发;由来源定义哪些触发构成一个线程 | 同一时刻至多有一个评估在它上面运行。它可以有多个工单。它持有自己的订阅、正在运行的评估以及它的决定(Decision)历史 | |
| | | |
| | | |
| 带版本(versioned)的研判规则,以及每个来源各自的那一部分:谁可以通过该来源发起工作、以该来源自身的身份、列表如何同步、以及哪些机器人可以产出候选 | 策略版本涵盖规则、接单模式以及各来源的部分。一项涉及某个活动工单的变更——例如变更它当初据以接单的那条规则——会送达它的派工;但不会撤销授权。不同来源上的身份绝不相互映射 | |
| 对一批触发的判断,分两层:准入(gate)与研判(assessment) | 输入:触发批次、一个线程快照、该线程上的每个工单(包括已结束的),以及当前策略。输出:一个决定。自身不持有状态 | |
| 一次接单所授予的东西:策略版本、范围、强度、命中的规则、发送者在该来源上的身份,以及来源接收该触发的方式 | 不可变;范围更广意味着新建工单。工单的结束并不会使它结束:只有人的停止会撤回它,而一个不再支持它的策略会撤销它。在已结束的工单恢复之前,会针对当前策略重新校验它 | |
| | 只有评估才创建它。引用它的授权;持有它的渠道和输入(Input)。状态从进行中(open)→ 已结束(ended),当某个线程上的人的消息使它恢复时又回到进行中,除非它曾被人停止。它定义自己的状态,而非跟随执行器的状态 | |
| | 一个工单随时间会有多个派工。它的状态独立于工单,从待启动(pending)→ 执行中(running)→ 已结束(ended)。在执行器这一侧,只有它的最终报告才能结束该工单 | 执行器处于领域之外,但"由谁执行"必须处于领域之内 |
| | 一个命中的触发会扇出到每一个活动的、已订阅的工单,而不检查是谁发送的;以此方式到达某工单的人的消息不需要评估。一个执行器为获取上下文而关注的线程,会以同样方式到达它对应的工单,但不会赋予该工单任何授权,也不会使它恢复。一个已结束的工单会保留它的订阅,包括那条来自某个已关闭或已合并的拉取请求的订阅:一条人的消息会在同一授权下使它恢复,而无需评估或决定;来自机器人和 CI 的消息不会到达它,因为当它恢复时其执行器会重新读取它的那些线程。一个被人停止的工单什么都收不到。主 Session(Main Session)只有在某条消息明确指向某个已存在的工单时,才把线程附加到该工单上。一个人可以丢弃某线程上的每一个订阅;一个执行器只能丢弃它自己那个工单对某个它认为无关的线程的订阅,除了它那个工单最初所起始的线程,以及某个来源让它去关注的线程(例如其拉取请求所在的线程) | 后续的讨论能够抵达执行器,而不必有人再次提及该智能体 |
人不是一个领域概念。一个触发携带其发起者的标识,正如来源所提供的那样。一个允许列表是策略中某个来源的那一部分,用的是该来源自己的身份。"同一个人同时在几个来源上有账号"这是一段提示词文本,智能体在需要时会去读它。
执行器连同它的各个 Session 和目录,处于领域之外,通过派工与之连接。
聚合(Aggregates):来源持有它的读取位置。线程持有它的订阅、它正在运行的评估(评估串行运行,并把其间到达的触发合并进下一个批次),以及它的决定历史。工单持有它的派工、渠道和输入,并以 id 引用决定。
被拒绝的概念
| |
|---|
| 把主体(Principal)或成员资格(Membership)当作一个实体,或跨来源映射身份 | 人只是触发上的元数据;允许列表是策略中某个来源的那一部分;跨来源映射是一段提示词文本 |
| 一个需要等待的条件就是一个普通的来源,因此评估绝不反过来依赖来源 |
| 等待属于来源;一个超时的评估会把它的那些触发重新入队,或以 unavailable(未完成)结束 |
| 一个线程可以承载几份相互独立的工作;研判会借助工单列表来避免重复 |
| |
| 一个订阅覆盖整个线程;授权把"被授权"与"上下文"区分开 |
| |
| 一个工单可以被移交、被恢复、或由多个执行器先后运行,所以它定义自己的状态 |
| |
| 取消会留下做了一半的工作;相反,变更记录下来并送达 |
| 当执行器 Session 失败或受阻时锁定它的全部工具 | 这会挡住那个直接在 Session 里工作的人,也会挡住恢复之后的报告;只需暂停自动输入即可 |
| 这种分类需要结构化的事实;执行器通过一个结构化字段来询问 |
哪些是可复用的
上述概念及其规则是可复用的。来源的实现、策略的内容、执行器以及渠道的实现,属于某一次部署。每个来源在内部保留它自己的用词,例如 message(消息)、chat(会话)或 notification(通知),并把它们翻译成触发。
| |
|---|
| 飞书(Feishu):实时事件、历史恢复、对已订阅话题的轮询。GitHub:通知、已订阅的 Issue 和拉取请求、CI 的变更、被合并或关闭的拉取请求,以及在开启之处——仓库中每一个新建的 Issue、拉取请求和评论,以及默认分支的 CI |
| 研判规则,以及每个来源的允许列表、它的同步、它的机器人列表和它的准入表 |
| 每个工单对应一个 DSH 执行器 Session 和一个目录,位于一个执行环境之中,其变量由执行器和各来源注册 |
| 飞书话题回复、GitHub 评论以及评审讨论串(review thread)回复 |
术语表
本文档及其后续文档所用术语的一份参照清单,附其中文名;后续文档会解释上面未引入的术语。面板一次只显示一种语言;它的 (?) 按钮会以两种语言打开这份术语表。智能体在 GitHub 和飞书上发给人的消息使用平实语言,而不是这些术语。
| | |
|---|
| | dsh-superagent 所运行的那位自动化团队成员,通过诸如 GitHub 账号和飞书机器人这样的身份在各个来源上行动 |
| | 评估触发、接单并派发工单、以及回复的那个 DSH Session;在代码和提示词中为 orchestrator(编排器) |
| | 执行器为某一个工单所运行的那个 DSH Session;在代码和提示词中为 worker(工作器) |
| | 一条事件的流:一个由插件提供的种类,加上一个实例配置 |
| | |
| | 按时间顺序排列的触发;评估在其内一次只跑一个的单位 |
| | 共享同一个触发的各个线程之间的关系;它只增加上下文 |
| | |
| | 用于接单的那套带版本的规则,以及每个来源各自的那一部分,例如谁可以在那里请求工作 |
| | 某一组规则、各来源部分与接单模式这一组合的标识;每个授权都记录它 |
| | |
| | 评估的确定性第一层:谁可以发起工作,以及以何种强度 |
| | |
| | |
| | 一次接单所授予的东西:强度、范围以及它所依据的策略版本 |
| | |
| | |
| | |
| | |
| | 运行派工的那个端口:每个工单对应一个执行器 Session 和一个目录 |
| | 执行器 Session 和 prepare 命令运行的所在:由执行器和各来源注册的变量,每个都有键、值和描述 |
| | |
| | |
| | |
| | 送达某个工单的上下文:扇出的触发、策略变更、恢复消息和文本 |
| | |
| | |
| |
|---|
| accept 接单 · stop 停止 · ignore 忽略 · unavailable 未完成 |
| explicit 明确 · inferred 推断 |
| pending 待启动 · running 执行中 · ended 已结束 |
| progress 进展 · waiting 等待 · ready 就绪 · blocked 受阻 · failed 失败 · dropped 无需处理 |