Documentation
¶
Overview ¶
Package dispatch 派发域的**失败面**:改派错误分类(transient/fatal/other 三档) 与同域/跨域兜底改派环(issue #169,下沉自宿主 internal/engine/scheduler/experts/dispatch.go)。
生命周期: Experimental(v0.38.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
它回答的是第四问 ¶
多执行者编排有四问,前三问各有归属,第四问此前无人回答:
① 这次派发**能不能**发生? → 上游 oagentkit/agent/dispatch(allow 矩阵 + 深度上限 + 自派发拒绝;原 dispatch 门面 v0.35.0 已整包删除,消费方直连上游) ② 排队**怎么排**? → scheduling(优先级/公平/配额/背压) ③ 同一次调用要不要**原样重发**? → guardx/toolfail(处置层语义,单源) ④ 失败后**还能不能再派、派给谁**? → 本包
本包是**新立的机制包**,不是可达性门面:不碰 allow 矩阵、深度上限、 自派发拒绝三条判定,也不做队列、不排序、不执行(执行步与候选枚举都经 回调注入,见 StickyFailover)。
两条硬纪律(包头写死,测试各钉一条) ¶
- **判定面只读首次失败的原始错误。** 改派环会用 `%w(已同域改派 X 仍失败)` 把改派说明拼进累计错误——那类文本**只进事件 与最终消息**(给人看),不进 Classify 的判定面。理由:文本兜底按关键词判定, 说明里若混进「权限」「连接」这类词,一次瞬态会被误判成 fatal(跨域兜底被 错误抑制),或 fatal 被误判成 transient(多烧一次跨域改派)。判定面只应看 **失败本身**,不该看编排过程。
- **状态码判定必须 `\b` 词边界。** 裸 `strings.Contains(msg, "403")` 会被 「省略中段 4032 字节」这类字节数/行号命中:瞬态被误判成 fatal,或 「共 429 行」把 fatal 误升级成 transient。词边界把「数字是更长数字的 一部分」整类排除。
三档词表 ¶
transient 瞬态:可跨域兜底改派(超时/连接类)。 fatal 终态类:换执行者也是白跑(权限/凭证/审批/治理类)——直接终态。 other 不确定:仅同域重试,不跨域。
词表**中英双语**(issue #207):ClassUnknown 落到文本兜底的错误文案两种语言 都会出现——transient 档若只有英文,中文瞬态(「连接被拒绝」「连接超时」) 整类不可达:跨域兜底对中文错误静默失效,最典型的瞬态还会被 fatal 档的 中文词升级成终态。语言不得成为档位偏置;fatal 档的「拒绝」因此收窄为 「权限拒绝」「拒绝访问」(裸「拒绝」会命中「连接被拒绝」这类瞬态文案)。
两级判定:上游单源优先,文本只兜底 ¶
第一级消费 `toolgate/policy.Disposition`——它是「toolfail 链 → MCP 协议层」 两级合成的**唯一**实现,本包零文本匹配。链与协议层都判不出类型 (ClassUnknown)才落第二级文本兜底(词表内置在本包)。类型已判出时**不看文本**: 「类型说了 A、文案说 B 时听文案」与判定纪律相反。
与上游的两轴映射(不是照搬) ¶
上游回答「同一次调用要不要原样重发」,本包回答「换一个执行者有没有意义」—— 故逐档映射而非照搬:
上游处置类 本包档 换执行者有没有意义 transient transient 有:基础设施抖动,换执行者/换后端可能通 rate_limited transient 有:限流在服务端侧,换执行者可能绕开 self_reported transient 有:生产者自报可重试 permanent other 有:「能力不支持这类请求」⇒ 换**能力**可能支持 authentication fatal 无:同一套凭证,换执行者不刷新凭证 permission_denied fatal 无:同一套权限面,需人工放开 not_found other 有:换执行者可能指向别的目标/用别的工具 invalid_argument other 有:换执行者的参数构造不同,可能就对了 unknown →文本兜底 不可分类 = 保守(不乐观)
关键分歧:上游把 not_found / invalid_argument 判「不可重试」,本包的「重试」 却是**换执行者**——换执行者正是「换构造参数的人 / 换目标对象」⇒ 不终态, 只是不跨域。
Index ¶
Constants ¶
const ( // EventSameDomain 同域改派(逐候选,含尝试的候选名)。 EventSameDomain = "same_domain_failover" // EventCrossDomain 瞬态跨域兜底(一次)。 EventCrossDomain = "cross_domain_failover" )
改派事件类别(进宿主事件面与最终消息,不进判定面)。
const ( // DefaultSameDomain 代码缺省:同域改派一次(存量行为)。 DefaultSameDomain = 1 // DefaultCrossDomain 代码缺省:不跨域。 DefaultCrossDomain = false )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AttemptFunc ¶ added in v0.38.0
AttemptFunc 执行步接缝:把候选 slug 当作执行者跑一次。
返回 nil = 改派成功(宿主在此拿到产出);返回非 nil = 该候选也失败。 本包不解释错误内容,也不在环内重新判档(纪律①)。
type CandidatesFunc ¶ added in v0.38.0
CandidatesFunc 改派候选接缝(issue #169 原文签名): FailoverCandidates(slug, tried, sameDomain)。
sameDomain=true 限同域(同 route_group 一类的分组),false=跨域全集; 两次调用都必须排除 tried 与 slug 本身。**候选怎么来是宿主的事**—— 注册表、能力画像、启用开关全在宿主侧,本包只消费有序列表, 与宿主的注册表/能力画像无关。
type Class ¶ added in v0.38.0
type Class string
Class 改派错误档(三档词表,机读值;取值见下常量集)。
用字符串而非整数枚举:档名要随事件载荷落日志、随调用链跨进程传递, 数字序一旦被无意依赖就会变成隐藏契约。
type Event ¶ added in v0.38.0
type Event struct {
Kind string
// From 首次失败的执行者。
From string
// To 本次改派尝试的候选。
To string
// Err 累计错误(含改派说明)。
Err error
}
Event 一次改派尝试的留痕。
Err 是**到目前为止的累计错误**(含 `%w(已同域改派 X 仍失败)` 说明)—— 它是给人看的,不得回喂 Classify(见包头纪律①)。
type Policy ¶ added in v0.38.0
type Policy struct {
// SameDomain 同域改派次数上限;0=禁用改派;nil=回落下一级。
SameDomain *int
// CrossDomain 瞬态错误在同域改派耗尽后允许跨域兜底一次;权限/凭证类
// 永不跨域(fatal 在环里直接终态,本开关管不到它)。nil=回落下一级。
CrossDomain *bool
}
Policy 改派策略的**一层**声明(条目层 / 表级层 / conf 层各一份)。
字段为 nil 表示该层**未声明**,回落到下一级;非 nil 即使是 0/false 也是 显式声明(同域 0 = 禁用改派;跨域 false = 显式不跨域)。
type Request ¶ added in v0.38.0
type Request struct {
// Slug 首次失败的执行者(也是候选枚举的起点)。
Slug string
// FirstErr **首次失败的原始错误**——判定面只读它(纪律①)。
// 累计错误、改派说明一律不得放进这个字段。
FirstErr error
// SameDomain 同域改派次数上限(来自 Resolve;0=禁用同域改派)。
SameDomain int
// CrossDomain 是否允许瞬态跨域兜底一次(来自 Resolve)。
CrossDomain bool
// FailoverCandidates 候选枚举接缝(nil = 视为无候选)。
FailoverCandidates CandidatesFunc
// Attempt 执行步接缝(nil = 不执行任何改派,只给出档位与原错误)。
Attempt AttemptFunc
// OnEvent 每次改派尝试前的通知(nil = 不通知)。只在此处产出改派说明。
OnEvent func(Event)
}
Request 一次改派环的输入。
type Result ¶ added in v0.38.0
type Result struct {
// Slug 改派**成功**的候选;空 = 未改派或全部仍失败。
Slug string
// Err 累计错误:无改派时原样返回 FirstErr,有改派时按
// `%w(已同域改派 X 仍失败)` / `%w(已跨域兜底 X 仍失败)` 累加(给人看)。
// 改派成功时为 nil。
Err error
// Class 首次失败的档位(进事件载荷:宿主据此解释「为什么没继续改派」)。
Class Class
// Attempts 实际执行的改派次数(同域 + 跨域)。
Attempts int
}
Result 改派环的结论。
func StickyFailover ¶ added in v0.38.0
StickyFailover 改派环骨架(issue #169):同域 N 次 → 瞬态跨域一次 → fatal 直接终态。
次序与档位的关系 ¶
- **进环前判一次档**(Classify(FirstErr)),环内不再判——环会改写 Err, 二次判定读到的文本含改派说明(纪律①)。
- fatal:**不进任何改派**,原样返回(换执行者也是白跑,直接终态)。
- 同域:按候选序最多 SameDomain 次,任一次成功即返回。
- 跨域:仅当 CrossDomain 且档位是 transient,且只兜底**一次**。
与宿主的分工 ¶
本包不发事件、不落库、不排序候选(能力画像排序是宿主的领域资产): 事件走 OnEvent,候选走 FailoverCandidates,执行走 Attempt。 首次失败的环节状态落库(running→failed 之类)也在宿主侧——那是展示面, 不是「能不能再派」的判据。