Documentation
¶
Overview ¶
Package contract 编排运行契约:编排引擎与宿主状态之间的**唯一边界**。
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
## 为什么需要这个包
L2 抽取在 `flowEngine`(42 方法)处遇到硬墙,实测结论(详见 docs/SPLIT_PLAN.md §一.4): 被称作「通用环节执行机制」的 14 个方法里,11 个直接依赖 `model.Session` / `model.CaseStep` / `repo`——而 `Session` 有 37 个字段,其中 `Host` / `Cluster` / `TargetPending` / `PendingQuestion` / `PendingOptions` / `Entry`(incident|patrol|query) / `PolicyMode` 全是纯运维域语义。
**结论:只要编排的状态模型是带领域语义的宿主资产,编排机制就不可能下沉。** 本包就是那道出口——编排只认接口,宿主负责把领域结构适配进来。
## 设计取舍:核心字段定死 + 领域字段开放
纯粹的开放键(`Field(string)` 走天下)契约太松、两边必然漂移;纯粹定死则 每加一个运维概念都要改内核。故采用混合:
- **编排语义字段定死在接口上**:会话标识、环节标识、状态、当前环节—— 编排引擎的算法只依赖这些,任何宿主都必须提供;
- **领域字段走开放键**:宿主专属状态(目标、策略档、租户…)由宿主自取自存, 内核不解释、不校验、也不需要知道它们存在。
这样约 80% 的编排逻辑可下沉,剩下 20% 留在宿主适配层。
## 稳定承诺
本包是**契约面**:方法集只增不改(加新能力时新增方法并给零值默认实现), 以免宿主适配层跟着内核升级频繁返工。
status.go —— 状态词表:成员判定与三态分类的**单一事实源**。
为什么这张表在本包 ¶
「什么算词表外」这条**边界**此前没有单源:contract 只导出「终态成员判定」 (IsTerminalStatus),没有导出「已知状态」谓词,于是每个消费方各自推导出 这条边界——checkpoint 与 controlplane 各立了一份逐字同构的三态分类器 (issue #363)。两处注释都声明「不在本包另立一份」,但立的是两份。
三态的含义 ¶
- StatusOpen:已知**过程态**(含尚未声明状态的空串——崩溃快照的常态);
- StatusTerminal:已知终态;
- StatusUnknown:词表外,语义判不了。
StatusUnknown 的处置方向由消费方各自决定(checkpoint 阻塞续跑、controlplane 拒绝终止),但**分类结果本身只有一份**。
归一口径 ¶
判定一律先归一(ToLower + TrimSpace)再查表,与本包 IsTerminalStatus 的 旧实现、statemachine 的 normalized() 同口径。此前 checkpoint 的分类器 只对终态侧归一(走 IsTerminalStatus)、对过程态侧精确比对,于是同一个 "RUNNING" 在内核一处被认、在 checkpoint 一处被判「读不懂」——同一判据 两个口径。归一后两侧同源。
与 statemachine 的划界 ¶
本表的词表覆盖**会话轴与环节轴两根轴的并集**(13 值):会话独有 timed_out, 环节独有 approved / rejected / expired / interrupted / rolled_back / skipped, 两轴共有的 7 个取值单点定义在 contract(issue #354/#357)。statemachine 侧 只认**环节轴**的 12 个取值(timed_out 是会话独有取值,环节侧按词表外处理) ——那是**轴的边界**,不是判据分叉:同一取值在两根轴上的分类逐条一致,由 statemachine 的跨包用例钉住。
Index ¶
Constants ¶
const ( StatusCreated = "created" StatusRunning = "running" StatusWaitingApproval = "waiting_approval" StatusSucceeded = "succeeded" StatusFailed = "failed" StatusCancelled = "cancelled" StatusTimedOut = "timed_out" )
会话状态(编排运行生命周期;与宿主存储列名无关)。
取值由宿主定义,但编排引擎只按「可流转」使用,不解释具体语义。 与环节状态共有的 6 个取值(created / running / waiting_approval / succeeded / failed / cancelled)在此**单点定义**:statemachine 的 StepStatus 常量全部是这里的别名(issue #357),不再各写一份字面量。
const ( StatusApproved = "approved" StatusRejected = "rejected" StatusExpired = "expired" StatusInterrupted = "interrupted" StatusRolledBack = "rolled_back" StatusSkipped = "skipped" )
环节状态(与 statemachine.StepStatus 共用同一取值空间;issue #354/#357)。
环节状态与会话状态是**两根轴**(环节可以由 failed 补偿迁移到 rolled_back, 会话到 failed 就收尾),但取值空间重叠,且终态判定必须是**同一份判据**: 否则宿主按一份词表落库、内核按另一份判终态,同一状态在两处得到相反结论。 这里补齐环节独有的 6 个取值,终态判定因此只需一份词表就能覆盖两根轴; 转移表与环节语义仍在 statemachine(本包不解释迁移)。
const ( FieldQueuedInput = "queued_input" // 待处理输入队列(多轮续跑的载体) FieldPendingAsk = "pending_ask" // 待用户答复的挂起态(见 harness/pending) FieldTargetSummary = "target_summary" // 目标的人类可读摘要(仅用于日志/事件载荷) )
FieldKey 约定语义键。内核只**建议**这些键名(便于不同宿主对齐语义), 不强制——宿主可用自己的键。
注意:这些都是**编排通用语义**,不是运维域语义;运维域字段(主机/集群/目标) 由宿主自定键,本包不列。
Variables ¶
var ErrSessionDeadline = errors.New("会话超过会话级时限")
ErrSessionDeadline 会话级墙钟超时的 Cause(issue #170 / #333)。
**全仓唯一身份**:deadline 用它装饰轮 ctx(context.WithTimeoutCause), finalize 用同一个值做收尾路由。两侧各写一份 errors.New 时字面量相同但 error 值不同,errors.Is 互不认领——墙钟超时会被收尾侧判成进程停机、 不落终态,会话永久滞留 running(#333 的实测失效形态)。
判定一律走 errors.Is(可被包装链包裹);与 drain.ErrDeadline(停机排水 超时)是两根轴、两个 Cause。
var ErrUserCancelled = errors.New("会话被用户取消")
ErrUserCancelled 用户经取消 API 触发的协作中止 Cause(issue #355)。
**全仓唯一身份**:宿主用 context.WithCancelCause(ErrUserCancelled) 表达 用户取消,deadline/finalize 的收尾路由都用同一个值判定。两侧各写一份 errors.New 时字面量相同但 error 值不同,errors.Is 互不认领——同一 ctx 在 一侧判 cancelled(落终态)、另一侧判停机(不落终态,会话滞留 running)。
与 ErrSessionDeadline(墙钟到点)、裸 ctx 取消(进程停机)、 steer.ErrSteered(接管)是四个可区分的 Cause,判定一律走 errors.Is。
Functions ¶
func AllStatuses ¶ added in v0.43.0
func AllStatuses() []string
AllStatuses 返回状态词表的全集(排序后的**新切片**)。
宿主据此渲染状态选择器 / 校验落库值,不必手抄常量清单——手抄清单必然 漂移:内核新增一个取值,宿主那份不会跟着变,且没有任何判据会红 (issue #356)。返回的是副本:调用方改写它不影响判定面。
func IsKnownStatus ¶ added in v0.43.0
IsKnownStatus 报告 status 是否为内核状态词表成员(大小写/空白变体先归一)。
与 ClassifyStatus 的区别:**空串不是词表成员**(本函数为假),但它被 判成 StatusOpen(尚未声明状态)——「不是词表成员」与「读不懂」不是 一回事,前者是「还没说」,后者是「说了但不认识」。
func IsTerminalStatus ¶ added in v0.38.0
IsTerminalStatus 报告 status 是否为内核终态词表成员(会话/环节共用一份判据)。
终态 = 一轮编排不会再**自行**前进的收尾状态:
- 会话轴:succeeded / failed / cancelled / timed_out;
- 环节轴:succeeded / failed / cancelled / rejected / expired / interrupted / rolled_back / skipped。
**failed 在两根轴上都是终态。** 环节的 failed → rolled_back 是回滚补偿: 由裁决面/恢复面显式驱动,不是状态机自行前进,故不改变「failed 已收尾」 的判定(issue #354 把两侧口径收敛到这一条)。
created / running / waiting_approval / approved 是过程态;词表外取值 (含宿主自定义终态)一律 false——本函数只判**内核词表成员**,不臆断 自定义状态。#334 的三态口径不变:词表外按「判不了」处置,不得冒充终态。
这是**词表成员判定**,不是「这个终态是否与事实一致」的裁决——后者需要存储 面与恢复路径,归宿主。机制面只需要一个共同的词表真相,故在这里单点导出: 消费方(checkpoint / controlplane / watchdog / 参考实现)一律引用本函数 或 ClassifyStatus,不各抄一份终态清单(第二套词表必然漂移)。
statemachine 是**环节侧**的类型化入口:IsTerminal 从自己的转移表派生 (无自行推进出边=终态,#374),不直接调用本函数——两者对 12 个环节状态 的结论由 statemachine 的跨包表驱动用例逐条钉住;转移表若变,用例会同时 逼本函数与 IsTerminal 对齐(#354)。timed_out 是会话独有取值,环节侧 按「词表外」返回 false,这是轴的边界而不是判据分叉。
实现读 statusClass 表(与 ClassifyStatus 同一张):判定与枚举同源, 不另写一份终态清单——两份清单迟早漂移,且漂移是静默的。
Types ¶
type Clock ¶
type Clock interface {
Now() (unixNano int64)
}
Clock 时钟注入点(避免编排逻辑直接依赖 time.Now,测试可注入确定性时钟)。
type RunContext ¶
type RunContext interface {
// ID / CaseID 会话与案例标识(编排日志与事件载荷用,必须稳定)。
ID() string
CaseID() string
// Status 当前状态(取值见上常量集)。
Status() string
// SetStatus 状态迁移;宿主应在此实现其状态机约束(如 created→running 唯一)。
SetStatus(status string) error
// CurrentStep 当前环节标识(agent slug 或链节点路径;空=尚未起步)。
CurrentStep() string
// SetCurrentStep 推进当前环节。
SetCurrentStep(step string) error
// Field 取宿主领域状态(按**语义键**,不是存储列名)。
// 内核不解释键的含义,也不假设它存在——取不到返回 (false) 由调用方降级。
Field(key string) (string, bool)
// SetField 写宿主领域状态;宿主拒绝未知键时返回错误(fail-closed,不静默吞)。
SetField(key, value string) error
}
RunContext 编排运行上下文。
生命周期:一轮编排对应一个实例,由宿主在派发时构造、终态后释放。 实现须**并发安全**:编排引擎会在事件回调与主流程间共享同一实例。
type StatusClass ¶ added in v0.43.0
type StatusClass int
StatusClass 状态的三态分类。
const ( // StatusOpen 已知过程态:状态还会继续前进。 // // 含**尚未声明状态**的空串(含只含空白的变体)——空串不是词表成员 // (IsKnownStatus 为假),但它表示「还没开始」,不是「读不懂」。 StatusOpen StatusClass = iota // StatusTerminal 已知终态:状态不会再自行前进。 StatusTerminal // StatusUnknown 词表外:内核读不懂这个状态值。 // // 「不是词表成员」与「读不懂」不是一回事:前者是「还没说」, // 后者是「说了但不认识」。 StatusUnknown )
func ClassifyStatus ¶ added in v0.43.0
func ClassifyStatus(status string) StatusClass
ClassifyStatus 把状态值归成三类:过程态 / 终态 / 读不懂。
- 空串 ⇒ StatusOpen(尚未声明状态,按过程态处理);
- 词表内 ⇒ 该取值在 statusClass 里的分类;
- 词表外 ⇒ StatusUnknown。
三态与 checkpoint / controlplane 的运行状态分类同一口径(同一事实、同一 方向):宿主据此分「还在跑 / 结束了 / 读不懂」三路处置,而不是把「读不懂」 混进「还在跑」。
谁在用它(issue #363) ¶
checkpoint 与 controlplane 的「什么算词表外」此前各有一份逐字同构的 分类器(两份注释都写着「不在本包另立一份」,但立的是两份)。本函数是 那条边界的唯一出口:两处改为调用它,边界只剩一份。
type StepSink ¶
type StepSink interface {
// Open 新建环节:宿主应完成「建行 + 状态迁移到 running」两件事。
// name 为环节标识(agent slug 或链节点路径),label 为用户可见语义标签。
Open(name, label string) (StepRef, error)
// Finish 环节收口。status 是**宿主自定义词表**的终态取值(编排面惯用
// succeeded / failed / degraded / skipped,本包不判值——终态判定由宿主
// 注入,见包头承诺)。
//
// 终态判定的公开入口是 contract.IsTerminalStatus(issue #354);statemachine
// 的 12 个 StepStatus 常量已全部别名化到本包常量(issue #357),其
// IsTerminal 从转移表派生并与本函数对 12 个环节状态逐条一致(跨包用例
// 钉住)。宿主把任一判据注入 commitgate 当判定面,对环节词表内的取值
// 结论相同。degraded 等宿主自定义终态不在内核词表内,按 #334 的三态口径
// 由宿主自行登记,不要指望内核认得。
Finish(ref StepRef, status string) error
}
StepSink 环节推进出口:建行 / 收口。
编排引擎不直接碰存储——所有环节状态的读写都经此出口, 这样换一个宿主(文件系统、内存、别的库)不必改编排逻辑。
type ToolBinder ¶
type ToolBinder interface {
// Tools 按 server + allow 白名单取工具面。
// allow 为空 = 取该 server 全部工具。
// 该 server 级失败(未装配/未返回)必须显式报错,不得静默返回空面——
// 空面会让编排把「没工具」误判成「工具失败」,两者处置完全不同。
Tools(ctx context.Context, server string, allow []string) (Tools, error)
}
ToolBinder 工具面绑定出口。
编排侧只说「我要 server X 的这几个工具」,**不关心工具从哪来** (MCP 池、静态注册表、测试替身都实现同一接口)。这是宿主可替换的关键接缝。