statemachine

package
v0.44.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: 5 Imported by: 0

Documentation

Overview

enum.go —— 环节状态 / 环节类别的导出枚举面。

为什么必须可枚举

词表是**判定依据**:宿主接编排协议时要知道环节有哪些合法状态与类别。 此前这两张词表全是包私有且没有任何枚举出口,宿主只能手抄一份常量清单 ——内核新增一个取值,宿主那份不会跟着变,且没有任何判据会红 (「三份手抄表 = 三份会漂的真相」,issue #356)。

本文件的出口**直接读判定用的同一张私有 map**,不另写列表:枚举与判定 同源,新增取值只需改一处。返回的切片是**新分配的副本**(排序后),宿主 改写它不影响判定面。

与 Valid 的关系

枚举回答「全部合法值」,谓词回答「这个值是否合法」。两者必须逐字一致: 枚举里的每个值都过谓词;谓词为真的每个值都在枚举里。用例做双向断言 (单向断言会漏掉「词表里有但没导出」)。

为什么是**字符串集合**而不是 []StepStatus

本包的环节状态常量是 contract 的**无类型别名**(issue #354/#357:状态 词表的主人只有一个),既能作 StepStatus 用、也能作 string 直传那些按 字符串取参的位点。宿主手里的「环节有哪些状态」也多是字符串(落库列、 协议字段),故枚举出口按字符串集合给,与 protocol 的 All* 出口同形。

Package statemachine 环节状态机(PHASE1_PLAN §6.2):合法转移表硬编码 + 全覆盖单测。

生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。

所有状态迁移走条件 UPDATE(repo 层),影响行数=0 即竞态失败——standalone/cluster 同一写法。

Index

Constants

View Source
const (
	StatusCreated         = contract.StatusCreated
	StatusRunning         = contract.StatusRunning
	StatusWaitingApproval = contract.StatusWaitingApproval
	StatusApproved        = contract.StatusApproved
	StatusRejected        = contract.StatusRejected
	StatusExpired         = contract.StatusExpired
	StatusSucceeded       = contract.StatusSucceeded
	StatusFailed          = contract.StatusFailed
	// StatusInterrupted 中断占位态(spec 2026-09-21-conversation-uplift P1-3):环节因
	// 用户取消/会话超时/进程中断而中止——区别于失败(执行了但失败)。占位报告写明
	// 「被中断、无产出或不完整」,下一轮对话历史如实携带,LLM 自行决定重做或跳过。
	StatusInterrupted = contract.StatusInterrupted
	StatusRolledBack  = contract.StatusRolledBack
	StatusSkipped     = contract.StatusSkipped
	StatusCancelled   = contract.StatusCancelled
)

环节状态常量:**全部是 contract 同值常量的别名**(issue #354/#357)。

状态词表只有一个定义处(contract);本包不再写第二份字面量。无类型别名 保持批次二十八的性质:同一取值既可作 StepStatus 用(转移表/判定),也可作 string 直传 repo.TransitionStep 等以字符串参数调用的位点。

两包共有的 6 个取值(created/running/waiting_approval/succeeded/failed/ cancelled)与会话词表同源;环节独有的 6 个取值也由 contract 单点定义, 使终态判据只需一份词表就能覆盖两根轴。

Deprecated: 状态取值的词表主人是 contract(便于两包共用同一份终态判据)。 这些常量保留为别名仅为兼容既有调用方;新代码请直接使用 contract.StatusX。

Variables

View Source
var (
	// ErrIllegalTransition 两个状态都在词表内,但转移不在合法转移表里。
	ErrIllegalTransition = errors.New("statemachine: 非法状态转移")
	// ErrUnknownStatus 状态值不在本状态机词表内(读不懂,不是迁移写错)。
	//
	// 与 ErrIllegalTransition 分开:旧实现把两者压成同一条「非法状态转移」,
	// 宿主据此去查迁移代码,而真因往往是写库口径错/版本不一致/数据被截断。
	// 同仓 checkpoint.classifyStatus 对同一问题已做三态(open/terminal/unknown),
	// 本包口径向它对齐。
	ErrUnknownStatus = errors.New("statemachine: 状态不在词表内")
)

转移错误哨兵(宿主按 errors.Is 分流排障方向)。

Functions

func AllStepStatuses added in v0.43.0

func AllStepStatuses() []string

AllStepStatuses 返回环节状态的**字符串集合**(排序后的新切片)。

宿主据此渲染环节状态选择器 / 校验落库值,不必手抄常量清单。

func AllStepTypes added in v0.43.0

func AllStepTypes() []string

AllStepTypes 返回环节类别的**字符串集合**(排序后的新切片)。

func CanTransition

func CanTransition(from, to StepStatus) bool

CanTransition 判定 from→to 是否合法(两边先归一:写法变体与规范形态 走同一张转移表,issue #373)。

两段判定:① 自行推进走 transitions;② 补偿迁移只允许从**终态**出发, 且必须显式登记在 compensations(IsTerminal 的生产调用点——终态定义若漂了, 补偿迁移的准入会立刻跟着变)。

func IsTerminal

func IsTerminal(s StepStatus) bool

IsTerminal 是否终态(环节侧的类型化入口)。

判据:转移表派生(issue #374)

本函数是**本状态机**的终态判据,直接读 transitions:无**自行推进**出边 = 终态。failed 的出边(→ rolled_back)是补偿迁移,登记在 compensations, 不在 transitions 里,所以 failed 仍是终态——与 contract.IsTerminalStatus 的结论一致(issue #354;两包对 12 个环节状态逐条一致由用例钉住)。

写法变体先归一(与 Valid / CanTransition 同口径)。词表外的值不是终态: 「读不懂」不能被当成「不可再变」(timed_out 等会话独有状态在环节词表外, 本函数返回 false;会话侧判据 contract.IsTerminalStatus 仍认它)。

反向验证(#374 常驻用例):给某个终态临时加一条 transitions 出边,本函数 必须立即跟随;#354 的跨包用例则保证此时 contract 侧也会红——两处必须同改。

func MustTransition

func MustTransition(from, to StepStatus) error

MustTransition 非法转移返回错误(repo 条件 UPDATE 前的快速失败;DB 侧仍有条件守卫兜底)。

错误分三类(issue #325)

  • 正常迁移 → nil;
  • from / to 有任一词表外 → 包装 ErrUnknownStatus,文案说明「不认识这个 状态」,不含「非法状态转移」;
  • 两者都在词表内但不在转移表 → 包装 ErrIllegalTransition。

判定方向不变(词表外仍然拒绝),变的只是诊断分类:把「读不懂」说成 「写错了」会让宿主照着错方向查。

func RequiresApproval

func RequiresApproval(t StepType) bool

RequiresApproval 该环节类别是否必须经过审批态。

口径(issue #322)

  • 规范类别按治理语义判定:plan / execute 必经审批,readonly / approval / verify 免审;
  • 大小写与空白先归一("PLAN" / "Execute" / " plan " 与规范形态同结论)—— 旧实现用精确相等,模型或配置里的大小写变体会静默落进「免审」;
  • **词表外一律返回 true**:这是审批类判定面,沉默必须落在最严一侧。 旧实现在这里返回 false,一条 "remediate" / "" / 拼写错误就能把治理闸 静默拆掉,而宿主没有任何信号(同包 CanTransition 对词表外是 fail-closed, 两处口径本来就该一致)。

Types

type StepStatus

type StepStatus string

StepStatus 环节状态。

func (StepStatus) Valid added in v0.43.0

func (s StepStatus) Valid() bool

Valid 报告状态是否在本状态机词表内(归一化后判定;词表 = 全部状态常量)。

词表外的值代表「内核读不懂这个状态」,与「状态合法但迁移非法」是两种 不同的现场:前者排障应查数据来源/版本,后者查迁移代码。MustTransition 据此分成两条可判定的错误(issue #325)。

大小写/空白变体与规范形态同结论(issue #373):它们是同一个状态,不是 「读不懂」——误诊会把宿主导向错误的数据来源排查。

type StepType

type StepType string

StepType 环节类别;plan/execute 必经审批态,readonly 裁剪审批(AGENTS 治理闸门)。

const (
	TypeReadonly StepType = "readonly"
	TypePlan     StepType = "plan"
	TypeApproval StepType = "approval"
	TypeExecute  StepType = "execute"
	TypeVerify   StepType = "verify"
)

func (StepType) Valid added in v0.43.0

func (t StepType) Valid() bool

Valid 报告该类别是否在内核词表内(归一化后判定)。

为什么必须有:RequiresApproval 对词表外取值走保守侧(要求审批),宿主 还需要一个手段区分「这类别本就免审」与「内核不认识它」。此前 StepType 没有 Valid(),宿主只能看到 false,连「词表里没有它」都查不到。 口径向 backend.Isolation.Valid() 对齐:越界值不得被当成最弱档。

Jump to

Keyboard shortcuts

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