contract

package
v0.48.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 4 Imported by: 0

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

View Source
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),不再各写一份字面量。

View Source
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(本包不解释迁移)。

View Source
const (
	FieldQueuedInput   = "queued_input"   // 待处理输入队列(多轮续跑的载体)
	FieldPendingAsk    = "pending_ask"    // 待用户答复的挂起态(见 harness/pending)
	FieldTargetSummary = "target_summary" // 目标的人类可读摘要(仅用于日志/事件载荷)
)

FieldKey 约定语义键。内核只**建议**这些键名(便于不同宿主对齐语义), 不强制——宿主可用自己的键。

注意:这些都是**编排通用语义**,不是运维域语义;运维域字段(主机/集群/目标) 由宿主自定键,本包不列。

Variables

View Source
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。

View Source
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

func IsKnownStatus(status string) bool

IsKnownStatus 报告 status 是否为内核状态词表成员(大小写/空白变体先归一)。

与 ClassifyStatus 的区别:**空串不是词表成员**(本函数为假),但它被 判成 StatusOpen(尚未声明状态)——「不是词表成员」与「读不懂」不是 一回事,前者是「还没说」,后者是「说了但不认识」。

func IsTerminalStatus added in v0.38.0

func IsTerminalStatus(status string) bool

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 StepRef

type StepRef struct {
	ID   uint64
	Name string
}

StepRef 环节引用:宿主分配的稳定标识,回传给 StepSink.Finish。

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 池、静态注册表、测试替身都实现同一接口)。这是宿主可替换的关键接缝。

type Tools

type Tools interface {
	// Names 返回工具名列表(诊断与留痕用)。
	Names() []string
	// Invoke 按名调用;未知名返回错误。
	Invoke(ctx context.Context, name string, args map[string]any) (result map[string]any, err error)
}

Tools 一次绑定得到的工具面。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL