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 ¶
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 ¶
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 ¶
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):它们是同一个状态,不是 「读不懂」——误诊会把宿主导向错误的数据来源排查。