夜雨聆风学习资料网

ARTICLE · 1334276

dsh-superagent 文档|001 领域模型

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(未完成)结束
每个线程至多一个活动工单
一个线程可以承载几份相互独立的工作;研判会借助工单列表来避免重复
一种"追加到工单"的决定
追加就是订阅扇出,无需评估
对订阅做准入检查
一个订阅覆盖整个线程;授权把"被授权"与"上下文"区分开
会路由的关联
订阅负责路由;关联只增加上下文
跟随 DSH Session 的工单状态
一个工单可以被移交、被恢复、或由多个执行器先后运行,所以它定义自己的状态
由执行器声称某个人要求它停止
只有评估才决定一次结束属于哪种强度
在策略变更时取消正在运行的工单
取消会留下做了一半的工作;相反,变更记录下来并送达
当执行器 Session 失败或受阻时锁定它的全部工具
这会挡住那个直接在 Session 里工作的人,也会挡住恢复之后的报告;只需暂停自动输入即可
从报告的自由文本中推断"在等待某个人"
这种分类需要结构化的事实;执行器通过一个结构化字段来询问

哪些是可复用的

上述概念及其规则是可复用的。来源的实现、策略的内容、执行器以及渠道的实现,属于某一次部署。每个来源在内部保留它自己的用词,例如 message(消息)、chat(会话)或 notification(通知),并把它们翻译成触发。

部分
在本仓库中
来源
飞书(Feishu):实时事件、历史恢复、对已订阅话题的轮询。GitHub:通知、已订阅的 Issue 和拉取请求、CI 的变更、被合并或关闭的拉取请求,以及在开启之处——仓库中每一个新建的 Issue、拉取请求和评论,以及默认分支的 CI
策略
研判规则,以及每个来源的允许列表、它的同步、它的机器人列表和它的准入表
执行器
每个工单对应一个 DSH 执行器 Session 和一个目录,位于一个执行环境之中,其变量由执行器和各来源注册
渠道
飞书话题回复、GitHub 评论以及评审讨论串(review thread)回复

术语表

本文档及其后续文档所用术语的一份参照清单,附其中文名;后续文档会解释上面未引入的术语。面板一次只显示一种语言;它的 (?) 按钮会以两种语言打开这份术语表。智能体在 GitHub 和飞书上发给人的消息使用平实语言,而不是这些术语。

术语
中文
含义
Agent
智能体
dsh-superagent 所运行的那位自动化团队成员,通过诸如 GitHub 账号和飞书机器人这样的身份在各个来源上行动
Main Session
主 Session
评估触发、接单并派发工单、以及回复的那个 DSH Session;在代码和提示词中为 orchestrator(编排器)
Executor Session
执行器 Session
执行器为某一个工单所运行的那个 DSH Session;在代码和提示词中为 worker(工作器)
Source
来源
一条事件的流:一个由插件提供的种类,加上一个实例配置
Trigger
触发
来自某个来源的一个不可变事件
Thread
线程
按时间顺序排列的触发;评估在其内一次只跑一个的单位
Correlation
关联
共享同一个触发的各个线程之间的关系;它只增加上下文
Channel
渠道
线程的写入侧
Policy
策略
用于接单的那套带版本的规则,以及每个来源各自的那一部分,例如谁可以在那里请求工作
Policy version
策略版本
某一组规则、各来源部分与接单模式这一组合的标识;每个授权都记录它
Eval
评估
把一批触发变成一个决定的过程
Gate
准入
评估的确定性第一层:谁可以发起工作,以及以何种强度
Assessment
研判
评估期间所做的模型判断
Decision
决定
评估的结果
Mandate
授权
一次接单所授予的东西:强度、范围以及它所依据的策略版本
Ticket
工单
一份被授权的工作的单位
Assignment
派工
把一个工单绑定到一个执行器实例
Subscription
订阅
一个工单与一个线程之间的关系
Fan-out
扇出
把一个已订阅线程的触发作为上下文送达某个工单
Executor
执行器
运行派工的那个端口:每个工单对应一个执行器 Session 和一个目录
Execution environment
执行环境
执行器 Session 和 prepare 命令运行的所在:由执行器和各来源注册的变量,每个都有键、值和描述
Report
报告
一次派工向其工单上报的状态
Attention
待人工决定
某个工单上等待人来回答的一个问题
Disposition
去向
一个触发被过滤、被评估或被扇出的记录
Input
输入
送达某个工单的上下文:扇出的触发、策略变更、恢复消息和文本
Scope
范围
一个授权所允许的工作
Strength
强度
一个授权或一次评估的根据有多强
组
取值
决定 Decision
accept 接单 · stop 停止 · ignore 忽略 · unavailable 未完成
强度 Strength
explicit 明确 · inferred 推断
派工 Assignment
pending 待启动 · running 执行中 · ended 已结束
报告 Report
progress 进展 · waiting 等待 · ready 就绪 · blocked 受阻 · failed 失败 · dropped 无需处理

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料